Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/yohangr3/agentelanggrafh/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you from a fresh checkout to a fully operational chat session. You’ll configure the required AWS and database credentials, start all services, verify the health endpoint, and send your first Spanish-language financial query through the React UI. The entire flow takes about five minutes once prerequisites are in place.

​
Prerequisites

Before you begin, make sure you have the following installed and accessible:
  • Python 3.12+ — the project targets requires-python = ">=3.12" in pyproject.toml
  • uv — the package and virtual-environment manager used throughout (uv sync, uv run)
  • Node.js 18+ — required for the React/Vite frontend
  • Docker & Docker Compose — needed for the all-in-one Compose workflow (includes Redis)
  • AWS account with:
    • Amazon Bedrock access enabled for Claude Sonnet 4.5 in your region
    • An Amazon Cognito User Pool and App Client for authentication
  • MySQL database containing your SAP ERP schema (accessible from your machine or a tunnel)
1

Clone the repository

git clone https://github.com/yohangr3/agentelanggrafh.git
cd agentelanggrafh
2

Configure environment variables

Copy the provided example file and fill in every required value:
cp .env.example .env
Open .env in your editor. The minimum required variables are:
.env
# MySQL (SAP ERP database)
DB_HOST=your-rds-host.region.rds.amazonaws.com
DB_PORT=3306
DB_USER=admin
DB_PASSWORD=your-db-password
DB_NAME=iafinagent

# AWS Bedrock
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=us.anthropic.claude-sonnet-4-5-20250929-v1:0

# AWS Cognito authentication
COGNITO_USER_POOL_ID=us-east-1_XXXXXXXXX
COGNITO_CLIENT_ID=your-cognito-app-client-id

# Redis (overridden automatically when using Docker Compose)
REDIS_URL=redis://localhost:6379/0
BEDROCK_EMBEDDING_MODEL_ID defaults to amazon.titan-embed-text-v2:0. You only need to override it if you are using a different embeddings model or cross-region inference prefix.
3

Start all services with Docker Compose

The Compose file at infra/docker/docker-compose.yml starts three services: redis, app (FastAPI backend on port 8000), and frontend (React SPA served on port 5173). The app service overrides REDIS_URL to point to the Compose-internal Redis container.
docker compose -f infra/docker/docker-compose.yml up
The backend will automatically build the FAISS Schema Registry on first start, which indexes every table in your MySQL database using Amazon Titan V2 embeddings.
Schema Registry cold-start: On a fresh database connection, building the FAISS index can take up to 120 seconds. The startup sequence enforces this as a hard timeout — if it is exceeded the process exits with RuntimeError: Schema Registry build timed out during startup. Subsequent starts are faster because the schema metadata is cached in Redis.
4

Or run backend and frontend separately

If you prefer to develop without Docker, run each service independently:
# Install Python dependencies into a managed venv
uv sync

# Start the FastAPI server with hot reload
uv run uvicorn src.api.main:app --reload
Make sure Redis is running locally on redis://localhost:6379/0 (or update REDIS_URL in your .env).
5

Verify the health endpoint

Once the backend is up, confirm the service is healthy and the database connection is live:
curl http://localhost:8000/health
A successful response looks like:
{
  "status": "healthy",
  "database": "connected",
  "environment": "development",
  "langsmith_enabled": false,
  "metrics_enabled": true
}
A "status": "degraded" response means the MySQL connection failed — double-check DB_HOST, DB_USER, and DB_PASSWORD.
6

Open the chat UI and send your first query

Navigate to http://localhost:5173 in your browser. You will be prompted to log in via your AWS Cognito User Pool. After authenticating, type a financial question in Spanish into the chat input, for example:
¿Cuáles son los 10 centros de costo con mayor gasto en el último trimestre?
The agent will classify the intent, link relevant tables via semantic search, generate SQL, validate it, execute it against your ERP database, and stream back a result table, KPI cards, and an auto-selected chart.
7

Run the test suite

Validate your setup with the unit tests before making any code changes:
uv run pytest tests/unit -v
For full integration tests (requires a live database and AWS credentials):
uv run pytest tests/integration -v

​
What’s next?

Architecture

Understand how the two-level LangGraph design works, including routing, the self-correction loop, and the HITL gate.

Chat API reference

Explore the /chat REST endpoint and the /ws/chat WebSocket for streaming per-node events to custom frontends.

Build docs developers (and LLMs) love

Get started for freeTalk to us