Imported from pxtroniwnl/eunomia (AGENTS.md). Install upstream with npx skills add pxtroniwnl/eunomia. Copyright stays with the author.

Eunomia — AI Agent Instructions

This file provides essential context for any AI coding assistant working on this repository.

Project Overview

Eunomia is a production-ready RAG (Retrieval-Augmented Generation) web application for Colombian legal compliance verification. It helps startups verify compliance with SIC, Habeas Data, and labor laws with zero hallucinations.

Critical Rules

Zero-Hallucination Mandate

• ALL LLM responses MUST be grounded in retrieved context
• The system MUST refuse to answer when context is insufficient
• Every response MUST include source citations (law name, article number)

Zero-Cost Mandate

• ALL dependencies and services MUST have free tiers or be fully open-source
• NEVER introduce paid API requirements
• NEVER suggest using paid services as "better alternatives"
• Approved free services: Google Gemini (AI Studio), Groq, Qdrant Cloud (free tier), HuggingFace models

Language

• ALL code, comments, docstrings, commit messages, and documentation MUST be in English
• Spanish appears ONLY in the legal corpus data and UI text targeting Colombian users

Architecture

See docs/C4_MODEL.md for the full C4 architecture documentation.

Key Decisions

1. Backend: Python + FastAPI + LangChain (NOT Django, NOT Flask)
2. Frontend: Next.js 15 App Router + TypeScript + shadcn/ui
3. Vector DB: Qdrant (NOT Pinecone, NOT Weaviate, NOT ChromaDB)
4. Embeddings: Local BAAI/bge-m3 via SentenceTransformers (NOT OpenAI embeddings)
5. Reranker: Local BAAI/bge-reranker-v2-m3 (NOT Cohere reranker)
6. LLM: Abstracted provider pattern — Gemini 2.0 Flash (primary) and Groq Llama 3.3 70B (backup)

Directory Structure

• backend/src/eunomia/ — Python backend source
  • api/routes/ — FastAPI route handlers
  • core/llm/ — LLM provider abstraction
  • core/retrieval/ — Vector store, embeddings, reranker, BM25
  • core/pipeline.py — Main RAG orchestrator
  • core/prompts.py — System prompts for citation enforcement
  • models/ — Pydantic schemas
  • utils/ — Citation extraction utilities
• frontend/src/ — Next.js source
  • app/ — App Router pages and API routes
  • components/ — React components
  • lib/ — Utilities and API client
  • hooks/ — Custom React hooks

Development Workflow

Running Tests

# Backend
cd backend && uv run pytest -v

# Frontend
cd frontend && npm run test

Linting

# Backend (Ruff)
cd backend && uv run ruff check . && uv run ruff format .

# Frontend (ESLint + Prettier)
cd frontend && npm run lint && npm run format

RAG Pipeline Architecture

The pipeline follows this flow:

1. Query Analysis — Extract intent and key legal concepts
2. Hybrid Retrieval — Dense (BGE-M3 vectors in Qdrant) + Lexical (BM25)
3. Reranking — Cross-encoder reranker (BGE reranker v2 M3) for precision
4. Context Assembly — Top-K documents formatted into LLM context
5. Response Generation — LLM generates response with mandatory citations
6. Citation Validation — Extract and validate legal citations in the response

Common Pitfalls to Avoid

1. DO NOT hardcode API keys — always use environment variables
2. DO NOT use Any type in Python — use proper type hints
3. DO NOT skip error handling in async code
4. DO NOT mock external services in integration tests — use dependency injection
5. DO NOT install new dependencies without verifying they are free/open-source
6. DO NOT add comments that explain obvious code — only document complex logic
7. DO NOT use console.log in frontend production code — use proper logging