How karansampath/ai-sdr works
Project Type and Purpose
• This is a full-stack, AI-driven Sales Development Representative (SDR) application.
• The backend is a FastAPI service (async Python) providing REST endpoints for lead management, AI qualification, message personalization, pipeline operations, search, evaluation, and utilities.
• The frontend is a Streamlit web app serving as a simple UI for users.
• A DuckDB instance holds lead, interaction, and pipeline data.
• The system integrates with an external AI service (xAI Grok) for lead scoring and message generation.
• There is also a local evaluation framework (in evaluation_tests/) to benchmark consistency, performance, and edge cases.
File-Structure Analysis
• Top level: Dockerfile, docker-compose.yml, env.example, run.py (starter script for both services), pyproject.toml (dependencies).
• frontend/streamlit_app.py: Streamlit UI.
• src/: core Python modules—database.py (DuckDB wrapper), models.py (pydantic schemas), main.py (FastAPI app entrypoint), services.py (business logic), evaluation.py, grok.py, prompts/ (Jinja2 templates + manager).
• evaluation_tests/: standalone test scripts that call API endpoints or internal functions for consistency, performance, failure modes.
• scripts/: utility scripts (grok_demo.py, test.py).
• docker-compose.yml: orchestrates FastAPI and Streamlit, sets ports, environment variables.
Key Architectural Insights from README
• API endpoints grouped by feature (lead management, AI services, pipeline, evaluation, utilities).
• Async I/O throughout backend.
• Uses Jinja2 for dynamic prompt construction.
• Containerized deployment (Docker multi-service).
• Local dev vs production considerations.
Main Components
a. Frontend Layer
• Streamlit App (frontend/streamlit_app.py)
• Communicates via HTTP (port 8501 → 8000)
b. Backend Layer (Monolith)
• FastAPI Server (src/main.py)
• Modules:
• API Routers (lead, messages, pipeline, search, evaluate, health)
• Business Logic (src/services.py, src/evaluation.py, src/grok.py)
• Prompt Manager (src/prompts) plus Jinja2 templates
• Data Models (src/models.py)
• Database Access (src/database.py → DuckDB)
c. Data Storage
• DuckDB file-based database (data/ directory)
d. External Service
• xAI Grok API (external HTTP calls for qualification & messaging)
e. Evaluation Framework
• evaluation_tests/ scripts invoke API endpoints or internal functions
f. Utilities & Scripts
• scripts/grok_demo.py for manual testing
• run.py to start both services
g. Deployment
• Docker & docker-compose orchestration
• Environment variables (XAI_API_KEY, database path)
Relationships and Data Flow
1. User interacts with Streamlit UI → sends user actions (CRUD, qualify, search, etc.) to FastAPI.
2. FastAPI handler calls Business Logic → may read/write DuckDB or call external AI service.
3. For AI calls: Business Logic builds prompt via Prompt Manager (Jinja2), issues HTTP to xAI Grok, receives response, processes it.
4. Results returned to frontend or stored in DB (e.g., lead scores, pipeline changes).
5. Evaluation Tests and scripts can directly hit FastAPI endpoints or invoke internal libraries.
6. Docker Compose brings up two containers (backend, frontend) connected via network.
Architectural Patterns & Principles
• Modular Monolith: clear separation between API layer, business logic, data access, and prompt templating.
• Async I/O and event loop for high concurrency in AI calls and DB queries.
• Template-based prompt generation (Jinja2) for extensibility.
• Single-node DuckDB for analytics; no separate service.
• Containerized micro-services style (each service in its own container, but tightly coupled).
Technologies & Framework Highlights
• FastAPI (async endpoints, pydantic models)
• Streamlit (rapid UI prototyping)
• DuckDB (embedded OLAP database)
• xAI Grok (external AI inference)
• Jinja2 (prompt templating)
• Docker & docker-compose
• uv (package manager), ruff (linter)