| --- |
| 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. |
