Tata Motors Sales Concierge

A web application where any Tata Motors prospect or owner converses with a Sales Concierge — by voice or chat — and is served by a fleet of specialist AI agents.

Documentation

Read in order before touching code:

1. docs/PRD.md — what we're building and why
2. docs/ARCHITECTURE.md — LangGraph spine, FastAPI surface, Postgres schema, provider routing
3. docs/AGENTS.md — charters and tool tables for the 9 agents
4. docs/UI.md — design tokens and the 10 Stitch screens
5. docs/BUILD.md — 12 sequenced milestones with verification commands

Quick start

# 1. Copy env template and fill in API keys (or keep PROVIDER_USE_MOCKS=true for keyless dev)
cp .env.example .env

# 2. Install dependencies (Python via uv, JS via pnpm)
make install

# 3. Start Postgres, run migrations, load seed data
make db-up
make migrate
make seed

# 4. Run backend (:8000) and frontend (:3000) in parallel
make dev

Then open http://localhost:3000.

Stack

Layer	Choice
Agent brain	Gemini 2.5 Pro (primary) · OpenAI GPT-5 (fallback)
Orchestration	LangGraph + Postgres checkpointing
Backend	Python 3.12 + FastAPI (async)
Frontend	Next.js 15 App Router + TypeScript + Tailwind
Database	Postgres 16 + SQLAlchemy 2.0 (async)
Image gen	Gemini 2.5 Flash Image
Maps	Gemini Maps Platform

Build status

This repository is built vertically per docs/BUILD.md. Current scope: Milestones 1–4 (Spine → Tool Registry → Concierge graph with Sales sub-agent → Streaming /concierge UI). Milestones 5–12 are documented extension points.

Milestone	Status
M1 — Spine	✅ shipped
M2 — Tool registry	✅ shipped
M3 — Concierge graph + Sales	✅ shipped
M4 — Streaming + /concierge UI	✅ shipped
M5–M12	🚧 follow-up phases

Layout

tata-concierge/
├── backend/           Python + FastAPI + LangGraph
├── frontend/          Next.js 15 App Router
├── data/              catalog_seed.json (real Tata catalog)
├── docs/              PRD, ARCHITECTURE, AGENTS, UI, BUILD
├── examples/          concierge_graph.py reference implementation
├── scripts/           make verify-mN scripts
├── stitch/            Stitch reference HTML (placeholder)
├── docker-compose.yml
├── Makefile
└── .env.example