context.md

# Via: Paytm Merchant Copilot - Project Context

## 1. Problem Statement
SMB merchants on the Paytm platform struggle with payment failures, delayed settlements, manual reconciliation, and invoicing/collections. Existing dashboards are passive, overwhelming, and require proactive monitoring. When things go wrong (e.g., a drop in UPI success rate or a pending settlement), merchants often lack the time or expertise to analyze the data and take immediate action.

## 2. The Solution: 'Via'
**Via** is an Actionable Intelligence Agent (an MCP Client) accessed directly through Telegram. It serves as a conversational, voice-first control layer over merchants' Paytm infrastructure. 
Instead of just being a Q&A chatbot, Via follows a core philosophy of:
**Insight → Reason → Action → Execution**

For example, when asked "Why was yesterday's collection low?", Via doesn't just return a number. It gives the insight (collection dropped by 18%), the reason (UPI success rate dropped), and immediately offers an actionable execution (e.g., "Would you like me to send payment links for the failed orders?").

## 3. UX & Interface
- **Platform:** Telegram Bot
- **Input Types:** Text and Voice (`.ogg` files)
- **Voice UX:** SMB merchants (often speaking Hindi or Hinglish) can simply send voice notes like *"refund last payment"*. The bot uses Telegram's voice capabilities smoothly to deliver a natural, low-friction experience.

## 4. Multi-Model AI Architecture
To balance cost, speed, and intelligence, Via utilizes a layered model stack:
1. **Input Layer (Speech-to-Text):** `whisper-large-v3-turbo` 
   - Transcribes Telegram `.ogg` voice notes, excellent for Hinglish natively.
2. **Intent & Routing (Fast & Cheap):** `llama-3.1-8b-instant` 
   - Rapidly classifies the merchant's intent, extracts entities, and routes queries.
3. **Reasoning & Execution (The "Brain"):** `gpt-oss-20b` or **Gemini** 
   - Handles the complex financial logic, analyzes data patterns, generates insights, and formats the final responses.
4. **Safety Verification (Optional/Critical Tasks):** `gpt-oss-safeguard-20b` 
   - Ensures sensitive operations like "initiate refund" are double-checked for authorization and intent.

## 5. Backend Architecture & Tool Integration
- **Stack:** Python, FastAPI, python-telegram-bot.
- **MCP Mock Tools (Simulating Paytm APIs):**
  - **Orders:** `fetch_order_list`
  - **Payment Links:** `create_link`, `fetch_link`, `fetch_transaction`
  - **Refunds:** `initiate_refund`, `check_refund_status`, `fetch_refund_list`
  - **Settlements:** `get_settlement_summary`, `get_settlement_detail`

*Note: The backend avoids heavy frameworks like React in favor of a clean, instantly demo-able chat interface that highlights the actual value: the MCP tool-calling and the multi-model intelligence.*

## 6. Conversational Memory & Context Awareness
To ensure Via is not a stateless bot, it maintains a **rolling conversational memory** per user (using Telegram's `chat_id`):
- **Short-Term Memory (Session State):** A fast, in-memory buffer (e.g., Python `dict` or Redis) stores the last 20 interactions or can store the summary till this point in chat of all the conversations. This payload is passed to the LLM's `messages` array so the AI always remembers the *tone* of the user, *recent tool results*, and *previously asked questions*. 
- **Tool-Call Continuity:** If a user says "Refund the last one we talked about," the AI can inspect the most recent `initiate_refund` or `fetch_transaction` MCP tool execution to determine precisely which order the user meant.Just ensure that its not stale data... like time wise... can use last 5 mins
- **Context Injection:** When an order or settlement requires action, the backend injects system prompts framing the exact state: *"The user just saw a drop in UPI success; guide them to routing updates."*

- **Sensitive stuff** redirect to relevent section of paytm app, so that user continues from there... 


## 7. Voice UX & Hinglish Support