docs/getting-started.md

Getting Started

This guide walks you from a fresh clone to a running chat session in either a Python virtualenv or a Docker container.

Prerequisites

• Python 3.12.x. Python 3.13 is currently blocked because some transitive dependencies still import audioop, which was removed in 3.13.
• Git.
• An OpenAI-compatible LLM endpoint. Any of the following work:
  • OpenAI (https://api.openai.com/v1)
  • Groq (https://api.groq.com/openai/v1)
  • Together AI (https://api.together.xyz/v1)
  • Azure OpenAI (https://<your-resource>.openai.azure.com/)
  • A local server such as LM Studio, Ollama, or vLLM exposing the OpenAI protocol.
• Docker (optional, only for the container path).

Option A: Python virtualenv

git clone https://github.com/ANI-IN/Multi-Agent-Customer-Support.git
cd Multi-Agent-Customer-Support

python3.12 -m venv venv
source venv/bin/activate            # Windows: venv\Scripts\activate

pip install --upgrade pip
pip install -r requirements.txt

cp .env.example .env
# Open .env and set OPENAI_API_KEY to your real key.

python app.py

Then open http://localhost:7860 in a browser.

The first launch downloads the Chinook sample SQL script (~1.5 MB) from GitHub and caches it as Chinook_Sqlite.sql at the repo root. Subsequent launches read the cache.

Option B: Docker

git clone https://github.com/ANI-IN/Multi-Agent-Customer-Support.git
cd Multi-Agent-Customer-Support

docker build -t music-support .

docker run --rm -p 7860:7860 \
  -e OPENAI_API_KEY=sk-... \
  -e MODEL_NAME=gpt-4o-mini \
  music-support

The Gradio app binds to 0.0.0.0:7860 inside the container and the published port 7860 on the host. Open http://localhost:7860.

Option C: Docker Compose

cp .env.example .env
# Edit .env, set OPENAI_API_KEY.

docker compose up --build

The compose service reads .env directly, restarts on failure, and exposes a basic HTTP healthcheck against the Gradio root.

Configure a Non-OpenAI Provider

Set both OPENAI_API_BASE and OPENAI_API_KEY in your environment. Examples:

Groq

OPENAI_API_BASE=https://api.groq.com/openai/v1
OPENAI_API_KEY=gsk_...
MODEL_NAME=llama-3.3-70b-versatile

Together AI

OPENAI_API_BASE=https://api.together.xyz/v1
OPENAI_API_KEY=...
MODEL_NAME=meta-llama/Llama-3.3-70B-Instruct-Turbo

Local server (LM Studio, Ollama, vLLM)

OPENAI_API_BASE=http://localhost:1234/v1
OPENAI_API_KEY=not-needed
MODEL_NAME=your-local-model

The supervisor routing relies on the model following structured instructions. Models below ~7B parameters often degrade routing accuracy on mixed queries.

First Conversation

The agent verifies your identity before exposing any account data. Try this sequence:

> My customer ID is 5
> What AC/DC albums do you have?
> What was my most recent purchase?
> I love rock music.

The last line is captured as a music preference and persisted across the session via the in-memory long-term store. If you restart the app the preference is lost (the store is in memory by design; see the roadmap in docs/architecture.md).

Running the Tests

pytest tests/ -v

The suite exercises the SQL helpers, identifier normalization, and every tool function against the in-memory Chinook database. It does not call any LLM, so no API key is needed.

Where to Go Next

• Read docs/architecture.md for a system tour with flowcharts, a sequence diagram, and a "what lives where" table.
• Read SECURITY.md for the disclosure process and the project's known sensitive surfaces.
• Read CONTRIBUTING.md when you are ready to open a pull request.