MalekManai1/carthage-historical-guide-agent

An AI-powered multilingual historical guide for Carthage, Tunisia, built with RAG, LangChain, PostgreSQL/pgvector, FastAPI, React, and Llama 3.1. # Historical Guide RAG Agent MVP autonome pour un agent guide historique RAG centré sur Carthage, Tunisie. ## Features - **Historical Guide Agent** — RAG-grounded answers with sources (Groq Llama 3.1) - **Memory Agent** — Session preferences, monument follow-ups - **Hybrid retrieval** — pgvector + keyword + intent scoring (~83% Top-1) - **Optional web fallback** — DuckDuckGo search when local RAG is insufficient (disabled by default) - **`POST /api/chat`** — Main integration endpoint - **`POST /api/circuits/recommend`** — Algorithmic circuit recommendation (CircuitAgent) - **Evaluation suite** — Retrieval (30 Q) + chat (40 cases) - **Optional UI** — React/Vite chat + circuit planner in `frontend/simple-chat-ui/` ## Quick start ### 1. Database ```bash docker compose up -d cp .env.example .env # Edit .env: set DATABASE_URL and LLM_API_KEY ``` ### 2. Python environment ```bash cd backend python -m venv venv venv\Scripts\activate # Windows pip install -r requirements.txt alembic upgrade head ``` ### 3. Load data and embeddings ```bash python scripts/ingest_excel.py python scripts/import_circuit_datasets.py # CircuitAgent graph + monuments CSV python scripts/chunk_documents.py python scripts/generate_embeddings.py ``` ### 4. Run API ```bash uvicorn app.main:app --reload ``` - Swagger: localhost - Health: localhost ### 5. Test chat ```bash curl -X POST localhost \ -H "Content-Type: application/json" \ -d "{\"session_id\":\"test_01\",\"message\":\"Explique-moi les Thermes d'\''Antonin.\",\"language\":\"fr\"}" ``` ### 6. Test circuit recommendation ```bash curl -X POST localhost \ -H "Content-Type: application/json" \ -d "{\"session_id\":\"session_001\",\"type_tarif\":\"etudiant\",\"budget_max\":30,\"transport\":\"walking\",\"mobilite\":\"normale\",\"duration_minutes\":120,\"zone\":\"Carthage\",\"preferences\":{\"epoques\":[\"Romaine\"],\"fonctions\":[\"muse …