AI Agents Alfa

AI Agents Alfa is a multi-agent retrieval-augmented generation (RAG) playground tailored for educational and experimentation purposes. The project combines a FastAPI backend, a Next.js frontend, and a PostgreSQL + pgvector persistence layer to let you ingest documents, route questions through specialized agents, and experiment with different large language model (LLM) providers.

Key Capabilities

• FastAPI backend that provisions default agents, users, and access control lists for rapid demos.
• Document ingestion pipeline with OCR/HTML parsing, chunking, and pgvector-powered semantic search.
• Chat orchestration layer that can call OpenAI, DeepSeek, Google Gemini (Vertex), and xAI Grok models with automatic fallback logic.
• Next.js client for authentication, agent switching, and chat sessions against the backend.
• Docker Compose stack for running PostgreSQL, the backend (with debugpy enabled), and the frontend in one command.

Repository Layout

• backend/ – FastAPI application (app/main.py) plus agents, RAG utilities, and provider integrations.
• frontend/ – Next.js app located under app/ with simple login + chat UI.
• db/init/ – Database bootstrap scripts (pgvector extension).
• docker-compose.yml – Local stack definition for database, backend, and frontend services.
• .env.example – Sample environment configuration for local experiments.

Prerequisites

• Docker Desktop (or Docker Engine + Docker Compose plugin) or
• Python 3.13+, Node.js 20+, and PostgreSQL 15+ if running services manually.

Quick Start (Docker Compose)

1. Copy the sample environment file and adjust secrets:

   cd D:\Projects\EDUARDO\REPOS\DLV1
   copy .env.example .env

   At minimum, set OPENAI_API_KEY (and any other provider keys you intend to use). Replace demo credentials in AUTH_USERS, AUTH_TOKEN_SECRET, and API_KEY if you do not want to rely on the defaults from backend/app/defaults.py.
2. Launch the stack:

   docker compose up --build

3. Once the containers are healthy:
   • Backend REST API: http://localhost:18000 (interactive docs at /docs).
   • Frontend UI: http://localhost:13000.
4. Sign in using one of the auto-seeded demo accounts (username → password):
   • owner → ownerpass
   • demo → demo123
   • admin-local → local123
   • admin-intl → intl123
   • admin-logistics → logistics123

The backend automatically creates the database schema, loads the default agents (local regulations, international regulations, logistics, litigation), and assigns access control lists on startup.

Manual Development Setup

Backend (FastAPI)

1. Create and activate a virtual environment with Python 3.13+.
2. Install dependencies:

   cd backend
   pip install -e .

3. Provision PostgreSQL with pgvector enabled and export DATABASE_URL, OPENAI_API_KEY, and any other provider-specific keys.
4. Run the API:

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

   The startup lifecycle calls init_db() which creates tables if they do not exist and seeds default principals/agents.

Frontend (Next.js)

1. Install dependencies:

   cd frontend
   npm install

2. Start the dev server:

   npm run dev

3. Ensure NEXT_PUBLIC_API_BASE points to the backend (http://localhost:8000 or http://localhost:18000 if using Docker).

Core Workflows

• Document ingestion – POST /documents/upload accepts PDF, DOCX, PPTX, RTF, or HTML files, performs parsing/OCR, and stores chunks in Postgres. Additional routes provide page maps, consolidated context, verification, and exports.
• Chat – POST /chat/ask routes questions through the selected agent (agent field) and LLM provider (provider field). Retrieval is handled by app.rag.search_chunks.
• Agents – GET /agents lists available agents; access is filtered by the authenticated user’s ACL.
• Auth – POST /auth/login issues JWT tokens backed by AUTH_TOKEN_SECRET. Use /auth/me and /auth/logout to manage sessions.

Environment Reference

• DATABASE_URL – SQLAlchemy connection string (defaults to the Postgres service from Docker Compose).
• AUTH_USERS – Comma-separated username:password:role entries used when seeding credentials.
• OPENAI_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, GROK_API_KEY – Provider credentials; leave blank to disable a provider.
• EMBEDDING_MODEL, CHAT_MODEL, MAX_CHUNK_CHARS, TOP_K, etc. – Tune retrieval and generation behavior; see backend/app/config.py for the full list.
• ALLOWED_ORIGINS – CORS configuration for the frontend; "*" allows any origin.
• NEXT_PUBLIC_API_BASE – Frontend base URL for API calls.

Testing Notes

• The backend ships with exploratory scripts under backend/app/testing/ for Gemini integrations. Formal automated tests are not yet included; add your own test harness before using this in production scenarios.
• Because this project is provided for learning/experimentation, review and harden security, validation, and audit logging before exposing it publicly.

Educational Use Only

This codebase is intentionally verbose and configurable to help you study multi-agent RAG orchestration. Do not treat it as production-ready software: secure secrets, validate inputs, and perform thorough testing before deploying beyond a lab setting.