🏛️ Avanam

A Production-Ready Multi-Agent RAG Document Intelligence Platform

A query runs the full pipeline: the Critic scores the first draft 0.61 and sends it back, the revised answer passes at 86%, and gets stamped with its sources.

📖 Overview

Avanam (ஆவணம் — Tamil for "document" or "record") is a high-performance, full-stack Document Intelligence Platform. It leverages a state-of-the-art Multi-Agent RAG (Retrieval-Augmented Generation) pipeline to not just retrieve information, but to actively synthesize, fact-check, and format insights from your documents.

Built as a demonstration of modern AI engineering, Avanam features a live-streaming agent visualization UI, allowing users to watch AI agents collaborate, debate, and revise their work in real-time.

The best part? The entire stack is architected to run 100% locally at $0 cost with zero cloud dependencies, utilizing Ollama with llama3.2:3b for LLM inference, local HuggingFace embeddings, and PostgreSQL.

✨ Key Features

• 🤖 4-Agent LangGraph Pipeline: A cyclic workflow featuring a Retriever, Analyst, Critic, and Formatter.
• 🔄 Autonomous Revision Loops: The Critic agent scores the Analyst's work. If confidence falls below 70%, the work is kicked back for revision automatically.
• ⚡ Live Agent Telemetry: An advanced React frontend consumes Server-Sent Events (SSE) to visualize exact agent states, progress bars, and intermediate outputs in real-time.
• 🗄️ Zero-Cost Local RAG: Uses sentence-transformers/all-MiniLM-L6-v2 running locally and FAISS (Facebook AI Similarity Search) for blazingly fast vector retrieval without API costs.
• 📄 Multi-Format Ingestion: Drag-and-drop support for PDF, DOCX, TXT, and Markdown files with automatic chunking and indexing.
• 📊 Analytics Dashboard: Tracks query latency, average agent confidence scores, and vector database health.
• 🐳 Production-Ready Infra: Fully containerized with Docker Compose, multi-stage Vite/Nginx frontend builds, structured JSON logging (structlog), and automated GitHub Actions CI/CD.

---

📸 Screenshots

The UI is designed as "The Records Office" — a registry for your documents. Answers that pass the Critic's fact-check are stamped with a vermilion confidence seal; anything below the 70% threshold is sent back for revision.

Chat home: ask a question or start from a suggested query.

Live agent telemetry: the Critic scored the draft 0.61 and sent it back to the Analyst for revision.

The finished record: a cited answer stamped VERIFIED at 86% confidence, revised once.

Document registry: drag-and-drop ingestion with per-file chunk counts.

Query ledger: latency, confidence, and revision history per query.

---

🧠 System Architecture

graph TD
    subgraph Frontend [React TypeScript UI]
        UI[Chat Interface]
        Viz[Agent Progress Visualizer]
    end

    subgraph Backend [FastAPI Backend]
        API[REST & SSE Endpoints]
        DB[(PostgreSQL)]
        
        subgraph LangGraph [LangGraph Multi-Agent Pipeline]
            R[🔍 Retriever Node]
            A[📊 Analyst Node]
            C[🧪 Critic Node]
            F[📝 Formatter Node]
            
            R --> A
            A --> C
            C -- "Score < 0.7" --> A
            C -- "Score >= 0.7" --> F
        end
        
        VS[(FAISS Vector Store)]
        Embed[HuggingFace Embeddings]
    end

    UI -- "Query" --> API
    API -- "Init" --> LangGraph
    LangGraph -- "Real-time SSE Events" --> Viz
    R <--> Embed
    R <--> VS
    API <--> DB

Loading

---

🛠️ Technology Stack

Backend

• Framework: FastAPI, Uvicorn
• AI Orchestration: LangGraph, LangChain
• LLM: Ollama (llama3.2:3b by default — runs fully local; see backend/.env.example for alternatives)
• Embeddings: HuggingFace all-MiniLM-L6-v2
• Vector Store: FAISS (CPU)
• Database & ORM: PostgreSQL, SQLAlchemy (asyncpg)
• Streaming: Server-Sent Events (sse-starlette)

Frontend

• Framework: React 19, TypeScript, Vite
• State Management: Zustand
• Animations: Framer Motion
• Styling: Custom CSS design system ("The Records Office" — ledger greens, record paper, and a vermilion confidence seal)
• Markdown: react-markdown, remark-gfm

DevOps

• Containerization: Docker, Docker Compose
• Web Server: Nginx (Alpine)
• CI/CD: GitHub Actions (Automated Linting & Pytest)

---

🚀 Getting Started

Prerequisites

• Docker and Docker Compose
• At least 8GB RAM available for the Ollama LLM model
• No API keys needed — everything runs locally!

Installation

1. Clone the repository

   git clone https://github.com/imthi16/Avanam.git
   cd Avanam

2. Configure Environment Variables (optional) The stack runs out-of-the-box with sane defaults — no API keys required. To customize (model, thresholds, ports), copy the example file:

   cp backend/.env.example backend/.env

3. Start the Application Spin up the entire stack using Docker Compose:

   docker compose up --build -d     # or: make up

   (Note: The first run will automatically pull the llama3.2:3b model (~2GB) and the HuggingFace embedding model. This may take several minutes depending on your internet speed.)

4. Access the Platform

   • Frontend UI: http://localhost:3000
   • Backend API Docs: http://localhost:8000/docs

---

🕵️ How the Multi-Agent Pipeline Works

Avanam moves beyond simple "Retrieval Augmented Generation" by employing a team of specialized agents:

1. 🔍 Retriever Agent: Translates the user's query into a vector representation and searches the FAISS index for the top-5 most relevant document chunks.
2. 📊 Analyst Agent: Synthesizes the retrieved chunks into a comprehensive answer, carefully mapping every statement back to a specific source citation. It also extracts a structured list of its core "claims".
3. 🧪 Critic Agent: The quality-assurance engine. It takes the Analyst's claims and cross-references them against the original source text to check for hallucinations. It outputs a Confidence Score (0.0 to 1.0). If the score is below 0.7, it triggers a Revision Loop, sending actionable feedback back to the Analyst.
4. 📝 Formatter Agent: Takes the final, approved analysis and formats it into a highly readable Markdown response, appending interactive source citations.

---

📁 Project Structure

├── backend/
│   ├── app/
│   │   ├── agents/          # LangGraph Nodes (router, retriever, analyst, critic, formatter)
│   │   ├── api/             # FastAPI Routes (query, documents, health)
│   │   ├── core/            # Database, LLM client, Event Bus (SSE), Structured Logger
│   │   ├── models/          # SQLAlchemy ORM and Pydantic schemas
│   │   └── services/        # FAISS Vector Store, Document Chunking, HuggingFace
│   ├── alembic/             # Database migrations (applied automatically on startup)
│   ├── tests/               # Pytest suite
│   ├── pyproject.toml       # Tooling config (ruff, black, pytest)
│   └── Dockerfile           # Non-root image with migration entrypoint
├── frontend/
│   ├── src/
│   │   ├── components/      # React components (AgentProgress, Chat, Documents, Dashboard)
│   │   ├── hooks/           # useSSE (Streaming event parser)
│   │   ├── services/        # API Client
│   │   ├── store/           # Zustand global state
│   │   └── index.css        # Premium Design System
│   └── nginx.conf           # Nginx reverse proxy configuration
├── scripts/                 # Manual smoke tests against a running stack
├── docker-compose.yml       # Multi-container orchestration
├── Makefile                 # Common dev tasks (make help)
└── .github/workflows/       # CI/CD Pipelines

---

🧑‍💻 Development

make help          # list all targets
make up            # build + start the Docker stack
make test          # backend test suite
make lint          # ruff + black + eslint (same checks as CI)
make format        # auto-format the backend
make smoke         # upload a doc + run a query against a running stack

For local (non-Docker) backend development, install deps with pip install -r backend/requirements-dev.txt, start Postgres/Redis/Ollama (e.g. docker compose up postgres redis ollama -d), then make backend-dev.

Optional: pip install pre-commit && pre-commit install to run the linters on every commit.

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ for modern AI engineering.