Generic AI Agent — Installation & Usage Guide

Generic AI Agent
LangGraph + LangChain + FastAPI
Orders · Scheduling · Information Q&A

Installation & Usage Guide

Windows 10/11 | Python 3.11+ | SQLite/PostgreSQL
 Generic AI Agent — Installation & Usage Guide

1. Overview
This is a generic AI agent backend that can operate as the intelligent assistant for any small
business. The only business-specific input is a PDF (or text) file describing the business. The
agent uses that file as its knowledge base and can handle:
• Order intake — build cart, add/remove items, handle modifiers, confirm and persist
• Appointment scheduling — check availability, book, reschedule, cancel
• Information Q&A — prices, hours, policies, FAQs, grounded in the PDF
• Complaint handling — look up past orders, acknowledge discrepancies
• Proactive behaviour — upsell suggestions, domain knowledge enrichment

Architecture
The agent is built with LangGraph as a directed graph:
START → intent_detector → planner ↔ tools → critic → END
• Planner: ReAct-style LLM agent that calls tools to fulfill requests
• Tools: 16 @tool-decorated functions (orders, appointments, knowledge, slots)
• Critic: validates draft reply against PDF rules before sending — loops back if violated
• RAG: PDF → chunks → embeddings (all-MiniLM-L6-v2) → ChromaDB + LLM
enrichment
• DB: SQLite (dev) / PostgreSQL (prod) via SQLAlchemy

2. Prerequisites
Required Software
Software Version Download
Python 3.11+ [Link]/downloads
Git Any [Link]
LLM API Key Gemini or [Link] OR
OpenAI [Link]

ℹ️ Gemini 2.0 Flash is the default and recommended LLM — fast and free-tier friendly. Get a
key at [Link].
 Generic AI Agent — Installation & Usage Guide

3. Installation (Windows)
Step 1 — Get the Code
Open Command Prompt or PowerShell and run:
git clone [Link]
cd generic_agent

Step 2 — Create a Virtual Environment

python -m venv venv
venv\Scripts\activate
You should see (venv) at the start of the prompt. Always activate the venv before running any
commands.

Step 3 — Install Dependencies

pip install -r [Link]
This installs FastAPI, LangChain, LangGraph, ChromaDB, SQLAlchemy, sentence-
transformers, pdfplumber, and all other dependencies. It may take 3–5 minutes the first time
(downloading the embedding model).

⚠️ If you see a CUDA/GPU error during sentence-transformers install, ignore it — the

model runs fine on CPU.

Step 4 — Configure Environment

copy .[Link] .env
Open .env in Notepad and fill in your API key:
# For Gemini (recommended):
GOOGLE_API_KEY=your_key_here
LLM_PROVIDER=gemini
LLM_MODEL=gemini-2.0-flash

# OR for OpenAI:
OPENAI_API_KEY=your_key_here
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini

Step 5 — Run Setup

python [Link]
This command:
• Creates the SQLite database (generic_agent.db) with all tables
• Seeds synthetic customer, order, and appointment data
• Ingests both sample business PDFs into ChromaDB (first run downloads the embedding
model — ~90 MB)
 Generic AI Agent — Installation & Usage Guide

Expected output:
[1/3] Creating database tables... ✅
[2/3] Seeding synthetic data... ✅
[3/3] Ingesting PDFs... ✅ mario_pizza: 28 chunks
✅ bright_smile_dental: 31 chunks

4. Running the Server

Start the FastAPI Server
uvicorn [Link]:app --port 5000 --reload
Open your browser to: [Link]
You should see:
{ "status": "ok", "business_id": "mario_pizza", "db": "ok", "vector_store":
"ok (28 chunks)" }

Interactive API Documentation

FastAPI auto-generates interactive docs. Open: [Link]
You can test every endpoint directly from the browser.

Test with the Interactive CLI (no server needed)

# Pizza restaurant:
python test_local.py mario_pizza

# Dental clinic:
python test_local.py bright_smile_dental
Type messages and press Enter. Type 'new' to start a fresh session, 'quit' to exit.

5. Running Smoke Tests

Full End-to-End Tests (server must be running)
# Terminal 1:
uvicorn [Link]:app --port 5000

# Terminal 2:
python tests/smoke_test.py
The smoke test runs 6 scenarios:
• Scenario 1: Full restaurant order — change mind → delivery → confirm
• Scenario 2: Dental appointment booking
 Generic AI Agent — Installation & Usage Guide

• Scenario 3: 10 info Q&A questions (grounded in PDF)

• Scenario 4: Complaint handling — missing item
• Scenario 5: Reschedule / cancel appointment
• Scenario 6: Domain knowledge — upsell + healthy options

Key API Endpoints

Endpoint Method Description
/health GET Health check — DB + vector store status
/agent/chat POST Main chat endpoint (send message, get reply)
/business/load_pdf POST Load or reload a business PDF
/admin/orders GET List all orders in DB
/admin/appointments GET List all appointments in DB
/admin/sessions/{id} GET View session conversation + state
/admin/logs/{id} GET View full audit log for a session

6. Using a Different Business (Swap PDF)

To run the agent for your own business, you need one PDF or text file describing the business.
There are two ways to load it:

Option A — Update .env (persistent)

1. Place your PDF in the sample_data/ folder (e.g. my_bakery.pdf)
2. Edit .env and set:
BUSINESS_PDF_PATH=./sample_data/my_bakery.pdf
BUSINESS_ID=my_bakery
3. Re-run setup: python [Link]
4. Restart the server: uvicorn [Link]:app --port 5000 --reload

Option B — Hot-reload via API (while server is running)

curl -X POST [Link] \
-H "Content-Type: application/json" \
-d "{\"pdf_path\":
\"./sample_data/my_bakery.pdf\", \"business_id\": \"my_bakery\", \"force_re
ingest\": true}"
Then pass business_id in your /agent/chat requests:
{ "message": "What do you sell?", "business_id": "my_bakery" }

ℹ️ The PDF should describe: services/products and prices, opening hours, policies
(cancellation, delivery, etc.), staff/providers (for scheduling), any special rules. The more
 Generic AI Agent — Installation & Usage Guide

detail in the PDF, the better the agent performs.

7. Logs & Debugging

Log Files
All activity is logged to:
• Console (stdout) — real-time during development
• ./logs/[Link] — persistent log file
Every log line includes timestamp, session ID, and event type. Example:
2025-04-10 14:22:01 | INFO | [Link] | TOOL_CALL | session=abc123 |
tool=add_item_to_order | inputs={...}
2025-04-10 14:22:02 | INFO | [Link] | RETRIEVAL | session=abc123 |
query='large pepperoni' | chunks=5
2025-04-10 14:22:03 | INFO | [Link] | CRITIC | session=abc123 |
status=PASS

Audit Log in Database

Every tool call, LLM prompt, retrieval, and DB write is also written to the audit_logs table. View
with:
GET [Link]

Change Log Level

In .env, set LOG_LEVEL=DEBUG for more verbose output (shows full LLM prompts and all
retrieved chunks).

8. Troubleshooting
Common Errors
Error Fix
ModuleNotFoundError Run: pip install -r [Link] in activated venv
GOOGLE_API_KEY not set Copy .[Link] to .env and add your key
'No knowledge base found' Run python [Link] to ingest the PDF first
Port 5000 in use Change port: uvicorn [Link]:app --port 5001
[Link] Delete generic_agent.db and re-run python [Link]
ChromaDB collection error Delete ./chroma_db folder and re-run python [Link]
Slow first response Normal — embedding model loads on first call (~30 sec)
 Generic AI Agent — Installation & Usage Guide

LLM returns empty reply Check API key validity and quota in .env

⚠️ Always activate the virtual environment (venv\Scripts\activate) before running any

Python command. If you see 'python not found', check your PATH or use py instead of
python.

9. Technology Stack
Component Choice Reason
API Server FastAPI + Uvicorn Fast, async, auto-generates docs
Agent Framework LangGraph + Stateful graph, tool-calling, ReAct
LangChain
LLM Gemini 2.0 Flash Fast, free-tier, configurable in .env
(default)
Database (POC) SQLite Zero setup on Windows, identical schema to
Postgres
Database (Prod) PostgreSQL See notes below for upgrade path
Vector Store ChromaDB (local) No Docker needed for POC, easy persistence
Embeddings all-MiniLM-L6-v2 Fast, local, no API key, good quality
PDF Parsing pdfplumber Handles tables + text well

PostgreSQL Upgrade Path (Post-POC)

To switch from SQLite to PostgreSQL:
5. Install PostgreSQL 15+ from [Link]/download/windows
6. Create a database: CREATE DATABASE agent_db;
7. In .env, change: DATABASE_URL=postgresql://user:password@localhost/agent_db
8. For vector search: install pgvector extension and switch ChromaDB to pgvector
9. Run: python [Link] (tables auto-created by SQLAlchemy)

10. Quick Start Card

ℹ️ Copy these 5 commands to get running from zero on a fresh Windows machine.

10. python -m venv venv && venv\\Scripts\\activate

 Generic AI Agent — Installation & Usage Guide

11. pip install -r [Link]

12. copy .[Link] .env (then edit with your API key)
13. python [Link]
14. uvicorn [Link]:app --port 5000 --reload

Then test: python test_local.py mario_pizza