---
title: Fello IQ
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
app_file: app.py
pinned: false
---

# fello-IQ

Fello IQ is an automated account intelligence platform that utilizes AI agents to identify, enrich, and analyze corporate leads based on IP addresses or domain names. It synthesizes data from multiple sources to provide intent scores, technographics, and actionable sales strategies.

# System Architecture
The project is divided into three primary modules:

Backend (FastAPI): Handles API requests, serves the React frontend, generates PDF reports, and manages Google Sheets synchronization.

Fello Crew (CrewAI): An autonomous agentic layer that performs account identification, deep enrichment (via Apollo and News APIs), and strategic analysis.

Frontend (React): A Vite-powered dashboard for real-time interaction and visualization of intelligence streams.

# Core Technologies
- LLM: Mistral (mistral-large-latest).

- Frameworks: FastAPI (Python), React (JavaScript), CrewAI.

- Data Sources: Apollo.io, ip-api.com, custom scraping tools.

# Prerequisites
- Python 3.10 or higher.

- Node.js 18 or higher.

- Google Cloud Service Account (for Sheets sync).

- Apollo.io API Key.

# Environment Variables
Create a .env file in the root directory and the backend/ directory with the following keys:

```.env
# AI and Search
OPENAI_API_KEY=your_openai_key
SERPER_API_KEY=your_serper_key
APOLLO_TOKEN=your_apollo_token

# Google Integration
SPREADSHEET_ID=your_google_sheet_id
GOOGLE_CREDENTIALS_JSON=your_minified_service_account_json
```
# Local Setup
1. Backend and Crew Setup
From the root directory, install the shared Python dependencies:

```Bash
pip install -r requirements.txt
```
# 2. Frontend Setup
Navigate to the frontend directory and install dependencies:

```Bash
cd frontend
npm install
Running the Application Locally
```
You will need two terminal instances to run the full stack during development.

Terminal 1: Backend API
From the root directory:

```Bash
python -m backend.main
```
The API will start at http://localhost:8000.

Terminal 2: Frontend Development Server
From the frontend directory:

```Bash
npm run dev
```
The UI will start at http://localhost:5173.

# Data Models and Tools
Intelligence Model
The system enforces a strict Pydantic schema for all analysis, including:

- Intent Score (0.0 - 10.0).

- Likely Persona.

- Leadership Team.

- Technographics (Tech Stack).

- Recommended Sales Actions.

# Integrated Tools
- GetDomain: Resolves raw IP addresses to corporate entities.

- ApolloEnrichmentTool: Fetches firmographics and technographics.

- JobOpeningsTool: Monitors hiring signals as growth indicators using apollo API.

- NewsTool: Tracks recent corporate events and press releases.

# PDF Generation and Syncing
- PDF Reports: Generated server-side using fpdf, sanitizing data for Latin-1 compatibility.

- Google Sheets: Data is appended to "Sheet1" of the specified SPREADSHEET_ID using the Google Sheets API v4.