How vibing-ai/verifact works
Project Type and Purpose
• VeriFact is a full-stack, open-source AI fact-checking platform.
• It combines an interactive web UI (via Chainlit), a REST API (via FastAPI), a multi-agent pipeline for claim detection, evidence gathering, verdict writing, and persistence layers (Supabase PGVector and Redis).
File Structure Analysis
• Top-level:
• app.py & chainlit.md – entry point for Chainlit UI
• src/main.py – FastAPI app entrypoint
• src/verifact_manager.py – CLI orchestrator of the agent pipeline
• src/verifact_agents/ – implementations of ClaimDetector, EvidenceHunter, VerdictWriter
• src/api/ – API endpoints (e.g., factcheck.py)
• src/models/ – Pydantic models for request/response schemas
• src/utils/logging/ – centralized logging configuration
• notebooks/ & examples/ – tutorials and usage samples
• Configuration:
• .env-example, .env (environment variables)
• pyproject.toml & uv.lock (dependency management via uv)
• pytest.ini (test settings)
• GitHub workflows for CI
Key Architectural Insights from README
• Multi-agent pipeline: ClaimDetector → EvidenceHunter → VerdictWriter
• UI: Chainlit for step-by-step interactive experience
• API Framework: FastAPI for programmatic access
• Model Access: OpenRouter (and optional OpenAI Agents SDK)
• Cache: Redis for model results & evidence caching
• Database: Supabase with PGVector for vector embeddings and session persistence
a. Main Components
1. UI Layer
• Chainlit Web App (app.py)
• User Authentication (Chainlit built-in auth)
2. API Layer
• FastAPI Server (src/main.py → src/api endpoints)
3. Orchestrator
• verifact_manager.py (CLI)
• Internal Agent Manager (coordinates agents)
4. Agents
• ClaimDetector (src/verifact_agents/claim_detector.py)
• EvidenceHunter (src/verifact_agents/evidence_hunter.py)
• VerdictWriter (src/verifact_agents/verdict_writer.py)
5. External Services
• OpenRouter (OpenAI, Anthropic, Mistral models)
• Optional Serper API (web search)
6. Persistence
• Supabase (PostgreSQL + PGVector)
• Redis Cache
7. Utilities
• Logging subsystem (src/utils/logging)
• Configuration (environment variables validated by Pydantic)
b. Relationships & Data Flow
1. User → Chainlit UI
• UI sends user input (text or document) to the backend via WebSocket or HTTP
2. UI / CLI → FastAPI / verifact_manager
• UI calls FastAPI endpoints or verifact_manager CLI triggers pipeline
3. Orchestrator → Agents
• Sequence: ClaimDetector extracts claims → EvidenceHunter fetches evidence → VerdictWriter generates verdict
4. Agents ↔ External Model APIs
• Each agent calls OpenRouter (and OpenAI Agents SDK where configured)
5. EvidenceHunter → Optional Serper / Web Search API
6. Agents ↔ Redis Cache
• Cache intermediate results, model outputs, evidence
7. Final Results → Supabase
• Session persistence, embeddings stored in PGVector
8. FastAPI → Supabase
• Retrieves past sessions, user data, cached vectors
9. UI displays results with source citations and explanations
c. Architectural Patterns & Principles
• Modular Pipeline: Each agent is a pluggable component
• Separation of Concerns: UI, API, Agents, Persistence, Caching
• Dependency Injection & Config Validation: Pydantic settings
• Extensibility Points:
• New agents under src/verifact_agents
• Swap model providers via environment variables
d. Key Technologies
• Python 3.10+, FastAPI, Chainlit
• OpenAI Agent SDK, OpenRouter (model gateway)
• Supabase (Postgres + PGVector)
• Redis for caching
• uv (poetry-like dependency manager)
• Pydantic for config and data models
Final Advice
• How environment configuration (env vars) feeds into all services.
• Detail data flows: user input → claim extraction → evidence retrieval → verdict generation → persistence → UI display.
• Do not over-simplify: the multi-agent structure and data stores are central to VeriFact’s architecture.