How rikhil-nell/voiceiq works
Project type and purpose
• VoiceIQ is a backend‐focused AI-powered call log processing service.
• It exposes a RESTful API (FastAPI) for ingesting audio, transcribing, sanitizing, analyzing, and persisting call logs, plus a chat interface for conversational insights.
• It integrates with external transcription APIs (e.g., Groq’s Whisper), AI models for analysis, and a Supabase database.
File structure
• Top‐level files:
• app.py: Defines FastAPI endpoints.
• main.py: Orchestrates end-to-end workflow (transcribe → analyze → store).
• transcription.py: Audio ingestion, transcription calls, sanitization.
• agents.py: Implements AI agents (call log, report, database, chat).
• database.py: Wraps Supabase CRUD operations.
• memory.py: Manages state/memory for chat sessions.
• settings.py: Loads environment configuration (.env).
• prompts/: Stores prompt templates for each agent.
• Dockerfile, requirements.txt, pyproject.toml: Build and dependency definitions.
README
• The README confirms:
• Four AI agents each handling a specific task.
• Endpoints: /create_log, /logs/all, /logs/columns, /logs/report, /chat.
• Uses Supabase for persistence.
• External APIs for transcription and AI analysis.
Components
a. Client / Consumer
• Could be a web UI, CLI, or any HTTP client sending requests to the FastAPI server.
b. API Layer (FastAPI)
• app.py exposes endpoints; uvicorn serves.
c. Orchestration Layer
• main.py coordinates the workflow for /create_log:
1. transcription.py → external transcription API → raw transcript
2. Sanitization module within transcription.py → cleaned text
3. agents.py invokes:
• Call Log Agent (formatting)
• Report Agent (structured summary)
• Database Agent (extract actionable insights)
4. database.py persists final records in Supabase
• For /chat:
• memory.py retrieves session context
• chat agent in agents.py processes user prompt + context
d. Data Layer
• Supabase Database: tables for call logs, metadata, reports, perhaps memory…
e. External Services
• Transcription API (Groq’s Whisper or similar)
• AI Model API(s) for agent processing (OpenAI, etc.)
• Supabase REST/SDK endpoints
Relationships and interactions
• Client → HTTP → FastAPI (app.py)
• FastAPI endpoint (/create_log) → main.py workflow
• main.py → transcription.py → External Transcription API
• transcription.py → returns sanitized transcript → main.py
• main.py → agents.py for each agent → AI Model APIs
• agents.py → returns enriched data → main.py
• main.py → database.py → Supabase → confirmation → FastAPI → client
• For /chat: Client → app.py → agents.py + memory.py → AI Models → client
Architectural patterns and design principles
• Modular separation:
• API layer (app.py)
• Orchestration layer (main.py)
• Transcription & Sanitization (transcription.py)
• AI business logic (agents.py)
• Persistence (database.py)
• Session state (memory.py)
• Dependency injection via settings.py for environment/config
• Use of prompt templates in a separate folder for easy maintenance
• Single Responsibility Principle: each module has a clear, distinct role
• Externalize secrets and configs to .env (settings.py)