EscalAI — Consumer Escalation Agent

A LangGraph-based case manager for consumer complaints, exposed as a self-hosted MCP server (Streamable HTTP) with a web-based simulator standing in for the Alexa+ voice experience.

It only drafts and tracks. It never sends anything on your behalf, and it is not legal advice.

Built for the Build, Ship, Shape: Amazon Developer Hackathon (Alexa+ track).

Quick start (for judges)

git clone https://github.com/shrutijagadale0725-rgb/EscalAI.git
cd EscalAI
python -m venv .venv
.venv\Scripts\activate        # Windows; use `source .venv/bin/activate` on Mac/Linux
pip install -r requirements.txt
python -m escalation_agent.mcp_server

Open http://127.0.0.1:8000. No API key is needed. Groq is optional and only improves natural-language understanding, and the app is fully functional on its deterministic fallback without it.

Run python -m escalation_agent.mcp_server from the folder that contains the escalation_agent package.

A 2-minute tour: click New complaint, describe a problem (try: "My earbuds from Amazon arrived broken, order OD-12345, Rs 2499"), and confirm the details. Tell the agent "I sent it" and the reply window starts. Then type things like "it's been 6 days" or "it's 26th oct" and watch it track the deadline and escalate. You can also turn on Read aloud and use the mic button for voice in and out.

Related MCP server: Klarefi MCP

What it does

Walks a consumer complaint through a four-stage escalation ladder:

1. Seller support: a direct complaint letter

2. The platform's grievance officer: required acknowledgment/redress under the Consumer Protection (E-Commerce) Rules, 2020

3. The National Consumer Helpline (1800-11-4000 / consumerhelpline.gov.in)

4. The Consumer Commission: a formal filing at e-Jagriti (e-jagriti.gov.in), tiered by claim value (District / State / National Commission)

At each stage it drafts a letter, tracks the real reply-window deadline, and pauses for you to confirm you've sent it. If the window passes with no reply, it escalates automatically. You can stop a case at any point, or reopen a stopped case to pick back up from where you left it, including a case stopped right at the filing decision.

Why this architecture

Devpost's hackathon FAQ confirms Alexa+'s gated developer tools are not available to participants this cycle. A self-hosted MCP server plus your own web-based simulator is the explicitly sanctioned stand-in, judged on equal footing. So the "voice assistant" here is a browser page with mic input and speech output, talking to the same MCP tools an Alexa+ skill would call.

How it understands you

Free text goes through /api/understand, which tries Groq (an LLM) first for natural-language routing and field extraction. It silently falls back to deterministic regex matching if there's no GROQ_API_KEY set or the Groq call fails for any reason.

While a case is in the waiting stage, a second Groq pass handles free-form check-ins: relative durations ("it's been 8 days"), absolute dates ("it's 23 nov"), and fact-grounded questions ("when will I hear back?"). The model gets a real callable action (advance_days) instead of generating free text, and any free-text answer is only accepted if every number in it matches a known fact about the case. Anything it can't safely answer falls back to "not sure, check back" rather than guessing.

Once a case is finished (resolved, stopped or ready to file), closing remarks like "thanks" or "ok" get a friendly reply. They don't start a new complaint, but a real new complaint still does.

Running with Groq (optional)

$env:GROQ_API_KEY="your-key-here"       # PowerShell
$env:GROQ_MODEL="openai/gpt-oss-120b"   # optional override

export GROQ_API_KEY="your-key-here"     # macOS / Linux

MCP tools exposed

The simulator

• Voice in and out: a mic button for speech input, optional Read aloud with a selectable voice.

• Case management: every case is saved and resumable from the sidebar, and each has a delete button (with confirmation) that removes the case and its full LangGraph history.

• Inline message editing: hover a message you sent and click the pencil. The bubble turns into an editable box in place, and saving resends from that point. This replays the chat visually and does not rewind actions like "I sent it" that already moved a live case forward.

• Copy message: a copy icon on every message.

• Resizable panes, official-channel links at each escalation stage, and a landing page explaining what the agent does and doesn't do with your data.

Built with

Python, LangGraph (with SqliteSaver persistence), FastAPI/Starlette, the mcp Python SDK, Groq, SQLite, and plain HTML/CSS/JavaScript.

Testing

Run from the folder that contains the escalation_agent package and tests/:

python -m pytest -v

All 26 tests pass. Use python -m pytest rather than bare pytest so the project folder is on the import path (or add a pytest.ini containing pythonpath = . next to tests/).

Covers the full escalation ladder, real-clock vs. simulated-clock behavior, the MCP Streamable HTTP endpoint end-to-end, the HTTP API's security hardening (origin checks, content-type checks), and regression tests for bugs found during development. See FRICTION_LOG.md for what went wrong along the way and how it was fixed.

Roadmap

• Deadline reminders. Notify the user as each reply window nears its end (seller support, grievance officer, National Consumer Helpline) so a deadline isn't missed. Planned as an in-app banner first, then email or browser notifications.

• More regions and rules. Add other countries' consumer-protection ladders through rules.yaml.

• Real Alexa+ device. Connect the same MCP tools to an Alexa+ Agent Skill once developer access is available.

AI assistance

Built with help from Claude (Anthropic, via claude.ai) for architecture design, debugging, code generation and documentation. Groq powers the optional runtime language understanding.

Disclaimer

This tool drafts messages and tracks deadlines. It is not legal advice. Stage windows in rules.yaml are verified against public sources as of the dates noted there. Always confirm current rules and fees on the official sites (e-jagriti.gov.in, consumerhelpline.gov.in) before relying on a deadline or filing.

License

MIT, see LICENSE.