Upload 40 files

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.11-slim
+
+WORKDIR /code
+
+# Copy and install requirements as root
+COPY ./requirements.txt /code/requirements.txt
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+# Set up a new user named "user" with user ID 1000
+RUN useradd -m -u 1000 user
+
+# Switch to the "user" user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR $HOME/app
+
+# Copy the rest of the app with correct ownership
+COPY --chown=user . $HOME/app
+
+# Expose port 7860 which is the default for Hugging Face Spaces
+EXPOSE 7860
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,10 @@
----
-title: Via Demo
-emoji: 📈
-colorFrom: gray
-colorTo: red
-sdk: docker
-pinned: false
-license: mit
----
+# Via
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Via is a Python service for handling Telegram workflows and backend integrations.
+
+## Quick Start
+
+1. Create and activate a virtual environment.
+2. Install dependencies from `requirements.txt`.
+3. Copy `.env.example` to `.env` and fill in required values.
+4. Run the app according to project scripts and setup docs.

README_SETUP.md

@@ -0,0 +1,176 @@
+# Via Telegram Setup Guide (Simple V1)
+
+This guide gets your bot working on Telegram with:
+- mocked Paytm-like MCP tools (local only)
+- Groq inference APIs for LLM (and optional STT)
+
+No real Paytm payment APIs are used.
+
+## 1) Prerequisites
+
+- Python 3.11+
+- A Telegram account
+- A bot token from [@BotFather](https://t.me/BotFather)
+- A public HTTPS URL for webhook testing (for local dev use [ngrok](https://ngrok.com/))
+- A Groq API key from [Groq Console](https://console.groq.com/keys)
+
+## 2) Install and configure
+
+From project root:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements.txt
+cp .env.example .env
+```
+
+Set `.env` values:
+
+```env
+APP_ENV=dev
+TELEGRAM_BOT_TOKEN=<your_telegram_bot_token>
+TELEGRAM_WEBHOOK_SECRET=<long_random_string>
+
+GROQ_API_KEY=<your_groq_api_key>
+LLM_INFERENCE_URL=https://api.groq.com/openai/v1/chat/completions
+LLM_INFERENCE_API_KEY=
+LLM_MODEL=llama-3.3-70b-versatile
+
+STT_INFERENCE_URL=https://api.groq.com/openai/v1/audio/transcriptions
+STT_API_KEY=
+STT_MODEL=whisper-large-v3-turbo
+
+DB_PATH=via.sqlite3
+```
+
+## 3) Run the API
+
+```bash
+source .venv/bin/activate
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Health check:
+
+```bash
+curl http://127.0.0.1:8000/health
+```
+
+Expected:
+
+```json
+{"status":"ok","env":"dev"}
+```
+
+## 4) Expose local server to Telegram
+
+In a second terminal:
+
+```bash
+ngrok http 8000
+```
+
+Copy the HTTPS forwarding URL, e.g. `https://abc123.ngrok-free.app`.
+
+## 5) Register Telegram webhook
+
+Replace placeholders and run:
+
+```bash
+curl -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://<YOUR_PUBLIC_HOST>/telegram/webhook",
+    "secret_token": "<TELEGRAM_WEBHOOK_SECRET>"
+  }'
+```
+
+Verify webhook:
+
+```bash
+curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getWebhookInfo"
+```
+
+`url` should point to `/telegram/webhook` and `last_error_message` should be empty.
+
+## 6) Test from Telegram app
+
+Open your bot chat and send:
+
+- `show recent orders`
+- `show settlement summary`
+- `create payment link 250`
+- `refund txn-2001 amount 50`
+- `confirm`
+- `/debug last_update_type` (shows current Telegram update type and last processed type)
+
+Voice test:
+- Send a voice note like: `refund txn-2001 amount 30`
+- Bot should reply with transcript + action prompt.
+
+## 7) Expected behavior
+
+- Orders/links/refunds/settlements come from local mock DB.
+- Refund mutation is gated:
+  - first message prepares action
+  - `confirm` executes it
+- Tool calls are audited in `tool_audit` table.
+
+## 8) Quick troubleshooting
+
+- `401 invalid webhook secret`
+  - `.env` secret and Telegram `setWebhook secret_token` must match exactly.
+
+- Telegram webhook not hitting local app
+  - ensure ngrok URL is alive and `/telegram/webhook` is reachable.
+  - re-run `setWebhook` each time ngrok URL changes.
+
+- LLM fallback generic/error response
+  - verify `GROQ_API_KEY` is valid.
+  - verify `LLM_INFERENCE_URL` is `.../chat/completions`.
+  - check model name in `LLM_MODEL`.
+
+- Voice transcription unavailable
+  - verify `STT_INFERENCE_URL` ends with `/audio/transcriptions`.
+  - verify `STT_API_KEY` (or `GROQ_API_KEY`) is present.
+  - ensure your bot received a real Telegram `voice` message (not audio/file attachment).
+
+## 9) Local validation before Telegram
+
+Run tests:
+
+```bash
+python3 -m pytest -q
+```
+
+Seed richer mock scenarios (recommended before Telegram testing):
+
+```bash
+python3 -m scripts.seed_scenarios
+```
+
+This seeds multiple situations:
+- healthy collections day
+- UPI failure dip day
+- pending + successful refunds
+- multiple settlement payouts
+- active/expired payment links
+
+Manual webhook simulation:
+
+```bash
+curl -X POST http://127.0.0.1:8000/telegram/webhook \
+  -H "Content-Type: application/json" \
+  -H "X-Telegram-Bot-Api-Secret-Token: <TELEGRAM_WEBHOOK_SECRET>" \
+  -d '{
+    "message": {
+      "chat": {"id": 12345},
+      "text": "show settlement summary"
+    }
+  }'
+```
+
+---
+
+If you want, next step can be a production-ready `README.md` with Render deploy instructions and persistent Postgres instead of SQLite.

app/__init__.py

@@ -0,0 +1 @@
+"""Via application package."""

app/agent/orchestrator.py

@@ -0,0 +1,92 @@
+import re
+from typing import Any
+
+from app.db.repo import Repository
+from app.llm.client import LlmClient
+from app.tools.mock_paytm import MockPaytmTools
+
+
+class Orchestrator:
+    def __init__(self, repo: Repository, tools: MockPaytmTools, llm: LlmClient) -> None:
+        self.repo = repo
+        self.tools = tools
+        self.llm = llm
+
+    def handle_user_text(self, telegram_id: str, text: str, input_type: str = "text") -> str:
+        user_id = self.repo.ensure_user(telegram_id)
+        cleaned = (text or "").strip()
+        lowered = cleaned.lower()
+
+        if lowered.startswith("confirm"):
+            response = self._handle_confirmation(telegram_id)
+            self.repo.save_message(user_id, input_type, cleaned, response)
+            return response
+
+        if "settlement" in lowered:
+            summary = self.tools.get_settlement_summary()
+            s = summary["summary"]
+            response = (
+                f"📊 <b>Settlement</b>\n"
+                f"Gross: <b>₹{s['gross']:,.0f}</b> | Fee: ₹{s['fee']:,.0f} | Net: <b>₹{s['net']:,.0f}</b>"
+            )
+            self.repo.save_message(user_id, input_type, cleaned, response)
+            return response
+
+        if "order" in lowered:
+            data = self.tools.fetch_order_list()
+            top = ", ".join(f"<code>{o['order_id']}</code> {o['status']}" for o in data["orders"][:3])
+            response = f"📋 <b>{data['count']} orders</b>\n{top}"
+            self.repo.save_message(user_id, input_type, cleaned, response)
+            return response
+
+        if "link" in lowered and any(ch.isdigit() for ch in lowered):
+            amount = self._extract_first_amount(cleaned) or 100.0
+            link = self.tools.create_link(amount=amount)
+            response = f"✅ Payment link <code>{link['link_id']}</code> created for <b>₹{link['amount']:,.0f}</b>"
+            self.repo.save_message(user_id, input_type, cleaned, response)
+            return response
+
+        if "refund" in lowered:
+            txn_id = self._extract_token(cleaned, r"(TXN[-_ ]?\d+)")
+            amount = self._extract_first_amount(cleaned) or 100.0
+            if not txn_id:
+                response = "⚠️ Need a transaction ID to refund — e.g. <code>TXN-2001</code>"
+                self.repo.save_message(user_id, input_type, cleaned, response)
+                return response
+            self.repo.upsert_pending_action(
+                telegram_id,
+                action_type="initiate_refund",
+                payload={"txn_id": txn_id.replace(" ", "-").replace("_", "-"), "amount": amount},
+            )
+            response = f"💸 Refund <code>{txn_id}</code> for <b>₹{amount:,.0f}</b>\n\nReply <b>confirm</b> to proceed."
+            self.repo.save_message(user_id, input_type, cleaned, response)
+            return response
+
+        context = self.repo.get_recent_context(user_id)
+        llm_text = self.llm.generate(cleaned, history=context)
+        self.repo.save_message(user_id, input_type, cleaned, llm_text)
+        return llm_text
+
+    def _handle_confirmation(self, telegram_id: str) -> str:
+        pending = self.repo.pop_pending_action(telegram_id)
+        if not pending:
+            return "Nothing pending to confirm."
+        if pending["action_type"] == "initiate_refund":
+            payload = pending["payload"]
+            result = self.tools.initiate_refund(payload["txn_id"], float(payload["amount"]))
+            return f"✅ Refund initiated\n<code>{result['refund_id']}</code> — {result['status']}"
+        return "Pending action type not supported."
+
+    @staticmethod
+    def _extract_first_amount(text: str) -> float | None:
+        match = re.search(r"(\d+(?:\.\d{1,2})?)", text)
+        if not match:
+            return None
+        return float(match.group(1))
+
+    @staticmethod
+    def _extract_token(text: str, pattern: str) -> str | None:
+        match = re.search(pattern, text, re.IGNORECASE)
+        if not match:
+            return None
+        return str(match.group(1)).upper()

app/config.py

@@ -0,0 +1,38 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Settings:
+    app_env: str
+    telegram_bot_token: str
+    telegram_webhook_secret: str
+    llm_inference_url: str
+    llm_inference_api_key: str
+    llm_model: str
+    stt_inference_url: str
+    stt_api_key: str
+    stt_model: str
+    db_path: str
+
+
+def load_settings() -> Settings:
+    groq_key = os.getenv("GROQ_API_KEY", "")
+    llm_key = os.getenv("LLM_INFERENCE_API_KEY", "") or groq_key
+    stt_key = os.getenv("STT_API_KEY", "") or llm_key or groq_key
+    return Settings(
+        app_env=os.getenv("APP_ENV", "dev"),
+        telegram_bot_token=os.getenv("TELEGRAM_BOT_TOKEN", ""),
+        telegram_webhook_secret=os.getenv("TELEGRAM_WEBHOOK_SECRET", "local-secret"),
+        llm_inference_url=os.getenv(
+            "LLM_INFERENCE_URL", "https://api.groq.com/openai/v1/chat/completions"
+        ),
+        llm_inference_api_key=llm_key,
+        llm_model=os.getenv("LLM_MODEL", "llama-3.3-70b-versatile"),
+        stt_inference_url=os.getenv(
+            "STT_INFERENCE_URL", "https://api.groq.com/openai/v1/audio/transcriptions"
+        ),
+        stt_api_key=stt_key,
+        stt_model=os.getenv("STT_MODEL", "whisper-large-v3-turbo"),
+        db_path=os.getenv("DB_PATH", "via.sqlite3"),
+    )

app/db/models.py

@@ -0,0 +1,78 @@
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    telegram_id TEXT UNIQUE NOT NULL,
+    preferred_language TEXT DEFAULT 'en'
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    input_type TEXT NOT NULL,
+    transcript_text TEXT,
+    response_text TEXT,
+    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY(user_id) REFERENCES users(id)
+);
+
+CREATE TABLE IF NOT EXISTS orders (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    order_id TEXT UNIQUE NOT NULL,
+    amount REAL NOT NULL,
+    status TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS payments (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    txn_id TEXT UNIQUE NOT NULL,
+    order_id TEXT NOT NULL,
+    mode TEXT NOT NULL,
+    status TEXT NOT NULL,
+    gateway TEXT NOT NULL,
+    amount REAL NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS payment_links (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    link_id TEXT UNIQUE NOT NULL,
+    amount REAL NOT NULL,
+    customer_name TEXT,
+    status TEXT NOT NULL DEFAULT 'ACTIVE',
+    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS refunds (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    refund_id TEXT UNIQUE NOT NULL,
+    txn_id TEXT NOT NULL,
+    amount REAL NOT NULL,
+    status TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS settlements (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    payout_id TEXT UNIQUE NOT NULL,
+    payout_date TEXT NOT NULL,
+    gross REAL NOT NULL,
+    fee REAL NOT NULL,
+    net REAL NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tool_audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_name TEXT NOT NULL,
+    args_json TEXT NOT NULL,
+    result_json TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS pending_actions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    telegram_id TEXT UNIQUE NOT NULL,
+    action_type TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+"""

app/db/repo.py

@@ -0,0 +1,254 @@
+import json
+import sqlite3
+from contextlib import contextmanager
+from typing import Any
+
+from app.db.models import SCHEMA_SQL
+
+
+class Repository:
+    def __init__(self, db_path: str) -> None:
+        self.db_path = db_path
+        self._initialize()
+
+    @contextmanager
+    def _connect(self):
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+        finally:
+            conn.close()
+
+    def _initialize(self) -> None:
+        with self._connect() as conn:
+            conn.executescript(SCHEMA_SQL)
+            conn.commit()
+
+    def ensure_user(self, telegram_id: str) -> int:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT id FROM users WHERE telegram_id = ?", (telegram_id,)
+            ).fetchone()
+            if row:
+                return int(row["id"])
+            cursor = conn.execute(
+                "INSERT INTO users(telegram_id) VALUES(?)",
+                (telegram_id,),
+            )
+            conn.commit()
+            return int(cursor.lastrowid)
+
+    def save_message(
+        self, user_id: int, input_type: str, transcript_text: str, response_text: str
+    ) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO messages(user_id, input_type, transcript_text, response_text)
+                VALUES(?, ?, ?, ?)
+                """,
+                (user_id, input_type, transcript_text, response_text),
+            )
+            conn.commit()
+
+    def get_last_input_type_for_telegram_user(self, telegram_id: str) -> str | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                """
+                SELECT m.input_type
+                FROM messages m
+                JOIN users u ON u.id = m.user_id
+                WHERE u.telegram_id = ?
+                ORDER BY m.id DESC
+                LIMIT 1
+                """,
+                (telegram_id,),
+            ).fetchone()
+            return str(row["input_type"]) if row else None
+
+    def get_recent_context(
+        self, user_id: int, limit: int = 20, max_age_minutes: int = 5,
+    ) -> list[dict[str, str]]:
+        """Return recent messages as LLM-ready [{role, content}, ...] list.
+
+        Only includes messages from the last *max_age_minutes* to avoid
+        injecting stale context from earlier sessions.
+        """
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT transcript_text, response_text
+                FROM messages
+                WHERE user_id = ?
+                  AND created_at >= datetime('now', ?)
+                ORDER BY id DESC
+                LIMIT ?
+                """,
+                (user_id, f"-{max_age_minutes} minutes", limit),
+            ).fetchall()
+        messages: list[dict[str, str]] = []
+        for row in reversed(rows):
+            messages.append({"role": "user", "content": row["transcript_text"]})
+            messages.append({"role": "assistant", "content": row["response_text"]})
+        return messages
+
+    def log_tool(self, tool_name: str, args: dict[str, Any], result: dict[str, Any]) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO tool_audit(tool_name, args_json, result_json)
+                VALUES(?, ?, ?)
+                """,
+                (tool_name, json.dumps(args), json.dumps(result)),
+            )
+            conn.commit()
+
+    def upsert_pending_action(
+        self, telegram_id: str, action_type: str, payload: dict[str, Any]
+    ) -> None:
+        payload_json = json.dumps(payload)
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO pending_actions(telegram_id, action_type, payload_json)
+                VALUES(?, ?, ?)
+                ON CONFLICT(telegram_id) DO UPDATE SET
+                    action_type = excluded.action_type,
+                    payload_json = excluded.payload_json
+                """,
+                (telegram_id, action_type, payload_json),
+            )
+            conn.commit()
+
+    def pop_pending_action(self, telegram_id: str) -> dict[str, Any] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT action_type, payload_json FROM pending_actions WHERE telegram_id = ?",
+                (telegram_id,),
+            ).fetchone()
+            if not row:
+                return None
+            conn.execute("DELETE FROM pending_actions WHERE telegram_id = ?", (telegram_id,))
+            conn.commit()
+            return {
+                "action_type": row["action_type"],
+                "payload": json.loads(row["payload_json"]),
+            }
+
+    def create_payment_link(self, link_id: str, amount: float, customer_name: str) -> dict[str, Any]:
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO payment_links(link_id, amount, customer_name) VALUES(?, ?, ?)",
+                (link_id, amount, customer_name),
+            )
+            conn.commit()
+        return {"link_id": link_id, "amount": amount, "customer_name": customer_name, "status": "ACTIVE"}
+
+    def get_payment_link(self, link_id: str) -> dict[str, Any] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT link_id, amount, customer_name, status FROM payment_links WHERE link_id = ?",
+                (link_id,),
+            ).fetchone()
+            if not row:
+                return None
+            return dict(row)
+
+    def list_orders(self, limit: int = 10) -> list[dict[str, Any]]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT order_id, amount, status, created_at FROM orders ORDER BY id DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+            return [dict(row) for row in rows]
+
+    def create_refund(self, refund_id: str, txn_id: str, amount: float, status: str) -> dict[str, Any]:
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT INTO refunds(refund_id, txn_id, amount, status) VALUES(?, ?, ?, ?)",
+                (refund_id, txn_id, amount, status),
+            )
+            conn.commit()
+        return {"refund_id": refund_id, "txn_id": txn_id, "amount": amount, "status": status}
+
+    def get_refund(self, refund_id: str) -> dict[str, Any] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT refund_id, txn_id, amount, status FROM refunds WHERE refund_id = ?",
+                (refund_id,),
+            ).fetchone()
+            return dict(row) if row else None
+
+    def list_refunds(self, limit: int = 10) -> list[dict[str, Any]]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT refund_id, txn_id, amount, status, created_at FROM refunds ORDER BY id DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+            return [dict(row) for row in rows]
+
+    def get_settlement_summary(self) -> dict[str, Any]:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT COALESCE(SUM(gross), 0) AS gross, COALESCE(SUM(fee), 0) AS fee, COALESCE(SUM(net), 0) AS net FROM settlements"
+            ).fetchone()
+            return dict(row)
+
+    def list_settlement_details(self, limit: int = 20) -> list[dict[str, Any]]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT payout_id, payout_date, gross, fee, net FROM settlements ORDER BY payout_date DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+            return [dict(row) for row in rows]
+
+    def clear_mock_data(self) -> None:
+        with self._connect() as conn:
+            conn.execute("DELETE FROM tool_audit")
+            conn.execute("DELETE FROM pending_actions")
+            conn.execute("DELETE FROM messages")
+            conn.execute("DELETE FROM payment_links")
+            conn.execute("DELETE FROM refunds")
+            conn.execute("DELETE FROM payments")
+            conn.execute("DELETE FROM settlements")
+            conn.execute("DELETE FROM orders")
+            conn.commit()
+
+    def seed_demo_data(self, force: bool = False) -> None:
+        with self._connect() as conn:
+            has_orders = conn.execute("SELECT COUNT(*) AS c FROM orders").fetchone()["c"]
+            if has_orders and not force:
+                return
+            if force:
+                conn.execute("DELETE FROM payment_links")
+                conn.execute("DELETE FROM refunds")
+                conn.execute("DELETE FROM payments")
+                conn.execute("DELETE FROM settlements")
+                conn.execute("DELETE FROM orders")
+
+            # Scenario A: Healthy day with mostly successful UPI/card payments.
+            conn.execute("INSERT INTO orders(order_id, amount, status) VALUES ('ORD-1001', 799.0, 'SUCCESS')")
+            conn.execute("INSERT INTO orders(order_id, amount, status) VALUES ('ORD-1002', 1299.0, 'SUCCESS')")
+            conn.execute("INSERT INTO payments(txn_id, order_id, mode, status, gateway, amount) VALUES ('TXN-2001', 'ORD-1001', 'UPI', 'SUCCESS', 'MOCK_GATEWAY_A', 799.0)")
+            conn.execute("INSERT INTO payments(txn_id, order_id, mode, status, gateway, amount) VALUES ('TXN-2002', 'ORD-1002', 'CC', 'SUCCESS', 'MOCK_GATEWAY_A', 1299.0)")
+
+            # Scenario B: UPI dip and checkout failures.
+            conn.execute("INSERT INTO orders(order_id, amount, status) VALUES ('ORD-1003', 499.0, 'FAILED')")
+            conn.execute("INSERT INTO orders(order_id, amount, status) VALUES ('ORD-1004', 650.0, 'FAILED')")
+            conn.execute("INSERT INTO payments(txn_id, order_id, mode, status, gateway, amount) VALUES ('TXN-2003', 'ORD-1003', 'UPI', 'FAILED', 'MOCK_GATEWAY_B', 499.0)")
+            conn.execute("INSERT INTO payments(txn_id, order_id, mode, status, gateway, amount) VALUES ('TXN-2004', 'ORD-1004', 'UPI', 'FAILED', 'MOCK_GATEWAY_B', 650.0)")
+
+            # Scenario C: Refund queue with mixed statuses.
+            conn.execute("INSERT INTO refunds(refund_id, txn_id, amount, status) VALUES ('RFND-3001', 'TXN-2001', 99.0, 'SUCCESS')")
+            conn.execute("INSERT INTO refunds(refund_id, txn_id, amount, status) VALUES ('RFND-3002', 'TXN-2004', 300.0, 'PENDING')")
+
+            # Scenario D: Settlement delays and payout variances.
+            conn.execute("INSERT INTO settlements(payout_id, payout_date, gross, fee, net) VALUES ('PAYOUT-4001', '2026-03-20', 2098.0, 42.0, 2056.0)")
+            conn.execute("INSERT INTO settlements(payout_id, payout_date, gross, fee, net) VALUES ('PAYOUT-4002', '2026-03-19', 1450.0, 31.0, 1419.0)")
+            conn.execute("INSERT INTO settlements(payout_id, payout_date, gross, fee, net) VALUES ('PAYOUT-4003', '2026-03-18', 980.0, 22.0, 958.0)")
+
+            # Scenario E: Existing payment links for follow-up checks.
+            conn.execute("INSERT INTO payment_links(link_id, amount, customer_name, status) VALUES ('LINK-5001', 550.0, 'Aman Traders', 'ACTIVE')")
+            conn.execute("INSERT INTO payment_links(link_id, amount, customer_name, status) VALUES ('LINK-5002', 1200.0, 'Neha Retail', 'EXPIRED')")
+            conn.commit()

app/llm/client.py

@@ -0,0 +1,95 @@
+from typing import Any
+
+import requests
+
+
+class LlmClient:
+    def __init__(self, inference_url: str, api_key: str, model: str) -> None:
+        self.inference_url = inference_url
+        self.api_key = api_key
+        self.model = model
+
+    def generate(self, prompt: str, history: list[dict[str, str]] | None = None) -> str:
+        if not self.inference_url:
+            return "I can help with orders, links, refunds, and settlements. Tell me what you want to check."
+        try:
+            payload = {
+                "model": self.model,
+                "messages": [
+                    {"role": "system", "content": (
+                        "You are Via, a merchant's payment copilot on Telegram.\n\n"
+                        "RULES:\n"
+                        "- Be brief. 2-3 lines by default. Only expand if the user asks "
+                        "\"tell me more\", \"details\", or \"explain\".\n"
+                        "- Use Telegram HTML formatting ONLY (never markdown):\n"
+                        "  <b>bold</b> for key numbers and labels,\n"
+                        "  <i>italic</i> for emphasis,\n"
+                        "  <code>TXN-2001</code> for IDs.\n"
+                        "- Lead with the answer. No preamble like \"Here are my insights:\" "
+                        "or \"Based on the data:\".\n"
+                        "- Sound human — like a sharp assistant texting, not an AI writing "
+                        "a report. No bullet-point essays.\n"
+                        "- Use ₹ for currency (Indian merchants).\n"
+                        "- If data shows a problem, state it plainly and offer ONE actionable "
+                        "next step — not a 10-point plan.\n"
+                        "- Use line breaks to separate thoughts. Never use markdown "
+                        "(**, ##, -). Only HTML tags.\n"
+                        "- Emojis sparingly: ✅ ❌ ⚠️ 📊 for status indicators only.\n"
+                        "- Never end with \"Let me know if you'd like me to elaborate\" or "
+                        "similar filler.\n"
+                        "- NEVER make up data, transaction IDs, or order details.\n"
+                        "- If you do not have the requested information in your chat history, "
+                        "explicitly state that you don't know or ask the user to provide the exact ID."
+                    )},
+                    *(history or []),
+                    {"role": "user", "content": prompt},
+                ],
+                "temperature": 0.0,
+            }
+            headers: dict[str, Any] = {"Content-Type": "application/json"}
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            response = requests.post(
+                self._normalize_chat_url(self.inference_url),
+                json=payload,
+                headers=headers,
+                timeout=20,
+            )
+            response.raise_for_status()
+            data = response.json()
+        except requests.HTTPError as exc:
+            status = exc.response.status_code if exc.response is not None else "unknown"
+            return (
+                f"LLM provider returned HTTP {status}. "
+                "Please check API key permissions/quota. I can still run mocked tools "
+                "for orders, links, refunds, and settlements."
+            )
+        except requests.RequestException:
+            return (
+                "LLM provider is currently unreachable. "
+                "I can still run mocked tools for orders, links, refunds, and settlements."
+            )
+
+        if isinstance(data, dict) and "success" in data:
+            if not data.get("success"):
+                return (
+                    f"LLM provider error: {data.get('error', 'unknown_error')}. "
+                    "I can still run mocked tools for orders, links, refunds, and settlements."
+                )
+            try:
+                return data["data"]["choices"][0]["message"]["content"]
+            except (KeyError, IndexError, TypeError):
+                return str(data.get("data", data))
+        try:
+            return data["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError):
+            return str(data)
+
+    @staticmethod
+    def _normalize_chat_url(url: str) -> str:
+        normalized = (url or "").rstrip("/")
+        if normalized.endswith("/chat/completions"):
+            return normalized
+        if normalized.endswith("/openai/v1"):
+            return f"{normalized}/chat/completions"
+        return normalized

app/main.py

@@ -0,0 +1,49 @@
+from fastapi import FastAPI, Header, HTTPException
+
+from app.agent.orchestrator import Orchestrator
+from app.config import load_settings
+from app.db.repo import Repository
+from app.llm.client import LlmClient
+from app.telegram.handler import TelegramHandler
+from app.tools.mock_paytm import MockPaytmTools
+from app.voice.stt import SttClient
+
+settings = load_settings()
+repo = Repository(settings.db_path)
+repo.seed_demo_data()
+tools = MockPaytmTools(repo)
+llm_client = LlmClient(
+    inference_url=settings.llm_inference_url,
+    api_key=settings.llm_inference_api_key,
+    model=settings.llm_model,
+)
+stt_client = SttClient(
+    settings.stt_inference_url,
+    settings.stt_api_key,
+    model=settings.stt_model,
+)
+orchestrator = Orchestrator(repo, tools, llm_client)
+telegram_handler = TelegramHandler(orchestrator, stt_client, settings.telegram_bot_token)
+
+app = FastAPI(title="Via Copilot API", version="0.1.0")
+
+
+@app.get("/")
+def read_root() -> dict[str, str]:
+    return {"message": "Via Copilot webhook server is running!"}
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok", "env": settings.app_env}
+
+
+@app.post("/telegram/webhook")
+def telegram_webhook(
+    update: dict,
+    x_telegram_bot_api_secret_token: str | None = Header(default=None),
+) -> dict:
+    expected_secret = settings.telegram_webhook_secret
+    if expected_secret and x_telegram_bot_api_secret_token != expected_secret:
+        raise HTTPException(status_code=401, detail="invalid webhook secret")
+    return telegram_handler.process_update(update)

app/telegram/handler.py

@@ -0,0 +1,111 @@
+from typing import Any
+
+import requests
+
+from app.agent.orchestrator import Orchestrator
+from app.voice.stt import SttClient, SttProviderError
+
+
+class TelegramHandler:
+    def __init__(
+        self,
+        orchestrator: Orchestrator,
+        stt_client: SttClient,
+        bot_token: str,
+    ) -> None:
+        self.orchestrator = orchestrator
+        self.stt_client = stt_client
+        self.bot_token = bot_token
+
+    def process_update(self, update: dict[str, Any]) -> dict[str, Any]:
+        message = update.get("message") or {}
+        chat = message.get("chat") or {}
+        chat_id = chat.get("id")
+        if chat_id is None:
+            return {"ok": True, "skipped": "no_chat"}
+        telegram_id = str(chat_id)
+
+        if "text" in message:
+            text = str(message.get("text", ""))
+            if text.strip().lower() == "/debug last_update_type":
+                last_type = self.orchestrator.repo.get_last_input_type_for_telegram_user(
+                    telegram_id
+                )
+                current_type = "text"
+                debug_msg = (
+                    f"debug current_update_type={current_type}, "
+                    f"last_processed_input_type={last_type or 'none'}"
+                )
+                self._send_message(chat_id, debug_msg)
+                return {
+                    "ok": True,
+                    "input_type": "text",
+                    "reply": debug_msg,
+                    "debug": True,
+                }
+            reply = self.orchestrator.handle_user_text(telegram_id, text, input_type="text")
+            self._send_message(chat_id, reply)
+            return {"ok": True, "input_type": "text", "reply": reply}
+
+        if "voice" in message:
+            transcript = self._transcribe_media(message["voice"], "voice.ogg")
+            reply = self.orchestrator.handle_user_text(
+                telegram_id, transcript, input_type="voice"
+            )
+            self._send_message(chat_id, f"Transcribed: {transcript}\n\n{reply}")
+            return {"ok": True, "input_type": "voice", "reply": reply, "transcript": transcript}
+
+        if "audio" in message:
+            transcript = self._transcribe_media(message["audio"], "audio.m4a")
+            reply = self.orchestrator.handle_user_text(
+                telegram_id, transcript, input_type="voice"
+            )
+            self._send_message(chat_id, f"Transcribed: {transcript}\n\n{reply}")
+            return {"ok": True, "input_type": "voice", "reply": reply, "transcript": transcript}
+
+        return {"ok": True, "skipped": "unsupported_message_type"}
+
+    def _transcribe_media(self, media_obj: dict[str, Any], default_filename: str) -> str:
+        file_id = media_obj.get("file_id")
+        if not file_id or not self.bot_token:
+            return "voice transcription unavailable in local mode"
+        try:
+            file_resp = requests.get(
+                f"https://api.telegram.org/bot{self.bot_token}/getFile",
+                params={"file_id": file_id},
+                timeout=20,
+            )
+            file_resp.raise_for_status()
+            file_path = file_resp.json().get("result", {}).get("file_path")
+            if not file_path:
+                return "unable to fetch media file path from Telegram"
+
+            dl_resp = requests.get(
+                f"https://api.telegram.org/file/bot{self.bot_token}/{file_path}", timeout=30
+            )
+            dl_resp.raise_for_status()
+            filename = file_path.split("/")[-1] if "/" in file_path else default_filename
+            if "." not in filename:
+                filename = default_filename
+            transcript = self.stt_client.transcribe_bytes(dl_resp.content, filename=filename)
+            return transcript or "empty transcription"
+        except SttProviderError as exc:
+            return (
+                "voice transcription failed. "
+                f"provider_detail={exc}. "
+                "Tip: Telegram voice notes are usually OGG; if this keeps failing, send an audio file in m4a/mp3."
+            )
+        except requests.RequestException:
+            return "voice transcription failed due to Telegram network issue"
+
+    def _send_message(self, chat_id: int, text: str) -> None:
+        if not self.bot_token:
+            return
+        try:
+            requests.post(
+                f"https://api.telegram.org/bot{self.bot_token}/sendMessage",
+                json={"chat_id": chat_id, "text": text, "parse_mode": "HTML"},
+                timeout=20,
+            )
+        except requests.RequestException:
+            return

app/tools/mock_paytm.py

@@ -0,0 +1,57 @@
+import time
+from typing import Any
+
+from app.db.repo import Repository
+
+
+class MockPaytmTools:
+    def __init__(self, repo: Repository) -> None:
+        self.repo = repo
+
+    def create_link(self, amount: float, customer_name: str = "merchant_customer") -> dict[str, Any]:
+        link_id = f"LINK-{int(time.time())}"
+        result = self.repo.create_payment_link(link_id=link_id, amount=amount, customer_name=customer_name)
+        self.repo.log_tool("create_link", {"amount": amount, "customer_name": customer_name}, result)
+        return result
+
+    def fetch_link(self, link_id: str) -> dict[str, Any]:
+        result = self.repo.get_payment_link(link_id)
+        payload = result or {"error": "link_not_found", "link_id": link_id}
+        self.repo.log_tool("fetch_link", {"link_id": link_id}, payload)
+        return payload
+
+    def fetch_order_list(self, limit: int = 10) -> dict[str, Any]:
+        rows = self.repo.list_orders(limit=limit)
+        result = {"orders": rows, "count": len(rows)}
+        self.repo.log_tool("fetch_order_list", {"limit": limit}, result)
+        return result
+
+    def initiate_refund(self, txn_id: str, amount: float) -> dict[str, Any]:
+        refund_id = f"RFND-{int(time.time())}"
+        result = self.repo.create_refund(refund_id=refund_id, txn_id=txn_id, amount=amount, status="PENDING")
+        self.repo.log_tool("initiate_refund", {"txn_id": txn_id, "amount": amount}, result)
+        return result
+
+    def check_refund_status(self, refund_id: str) -> dict[str, Any]:
+        result = self.repo.get_refund(refund_id)
+        payload = result or {"error": "refund_not_found", "refund_id": refund_id}
+        self.repo.log_tool("check_refund_status", {"refund_id": refund_id}, payload)
+        return payload
+
+    def fetch_refund_list(self, limit: int = 10) -> dict[str, Any]:
+        rows = self.repo.list_refunds(limit=limit)
+        result = {"refunds": rows, "count": len(rows)}
+        self.repo.log_tool("fetch_refund_list", {"limit": limit}, result)
+        return result
+
+    def get_settlement_summary(self) -> dict[str, Any]:
+        summary = self.repo.get_settlement_summary()
+        result = {"summary": summary}
+        self.repo.log_tool("get_settlement_summary", {}, result)
+        return result
+
+    def get_settlement_detail(self, limit: int = 20) -> dict[str, Any]:
+        rows = self.repo.list_settlement_details(limit=limit)
+        result = {"settlements": rows, "count": len(rows)}
+        self.repo.log_tool("get_settlement_detail", {"limit": limit}, result)
+        return result

app/voice/stt.py

@@ -0,0 +1,77 @@
+from typing import Any
+
+import requests
+
+
+class SttProviderError(Exception):
+    pass
+
+
+class SttClient:
+    def __init__(self, inference_url: str, api_key: str, model: str = "whisper-large-v3") -> None:
+        self.inference_url = inference_url
+        self.api_key = api_key
+        self.model = model
+
+    def transcribe_bytes(self, audio_bytes: bytes, filename: str = "voice.ogg") -> str:
+        if not self.inference_url:
+            return "voice transcription unavailable in local mode"
+        headers: dict[str, Any] = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        data = {
+            "model": self.model,
+            "response_format": "verbose_json",
+            "temperature": "0",
+        }
+        safe_filename = self._ensure_supported_extension(filename)
+        mime_candidates = [None] + self._mime_candidates(safe_filename)
+        last_error: str | None = None
+        for mime in mime_candidates:
+            try:
+                if mime is None:
+                    files = {"file": (safe_filename, audio_bytes)}
+                else:
+                    files = {"file": (safe_filename, audio_bytes, mime)}
+                response = requests.post(
+                    self.inference_url, headers=headers, files=files, data=data, timeout=40
+                )
+                response.raise_for_status()
+                payload = response.json()
+                text = str(payload.get("text", "")).strip()
+                if text:
+                    return text
+                return "empty transcription"
+            except requests.HTTPError as exc:
+                status = exc.response.status_code if exc.response is not None else "unknown"
+                body = ""
+                if exc.response is not None:
+                    body = exc.response.text[:300]
+                last_error = f"stt_http_{status}: {body}"
+            except requests.RequestException as exc:
+                last_error = f"stt_network_error: {exc}"
+        raise SttProviderError(last_error or "stt_unknown_error")
+
+    @staticmethod
+    def _mime_candidates(filename: str) -> list[str]:
+        lower = (filename or "").lower()
+        if lower.endswith(".ogg") or lower.endswith(".oga"):
+            # Telegram voice notes are typically OGG/OPUS.
+            return ["audio/ogg", "audio/webm", "application/octet-stream"]
+        if lower.endswith(".opus"):
+            return ["audio/ogg", "application/octet-stream"]
+        if lower.endswith(".mp3"):
+            return ["audio/mpeg", "application/octet-stream"]
+        if lower.endswith(".m4a"):
+            return ["audio/mp4", "application/octet-stream"]
+        if lower.endswith(".wav"):
+            return ["audio/wav", "application/octet-stream"]
+        return ["application/octet-stream"]
+
+    @staticmethod
+    def _ensure_supported_extension(filename: str) -> str:
+        lower = (filename or "").lower()
+        supported = (".flac", ".mp3", ".mp4", ".mpeg", ".mpga", ".m4a", ".ogg", ".opus", ".wav", ".webm")
+        if any(lower.endswith(ext) for ext in supported):
+            return filename
+        return "voice.ogg"

context.md

@@ -0,0 +1,50 @@
+# 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
+
+

paytm llm api.md

@@ -0,0 +1,104 @@
+import requests
+
+# Configuration
+API_KEY = "<YOUR_API_KEY>"
+BASE_URL = "https://api.paytmai.com"
+
+# Audio file
+audio_file = open("audio.mp3", "rb")
+
+# Request payload
+files = {"file": audio_file}
+data = {
+    "model": "whisper-large-v3",
+    "response_format": "json",
+    "temperature": 0
+}
+
+headers = {"Authorization": f"Bearer {API_KEY}"}
+response = requests.post(f"{BASE_URL}/v1/audio/transcriptions", files=files, data=data, headers=headers)
+
+result = response.json()
+print(result["text"])
+
+
+THE ABOVE IS FOR WHISPER...
+
+
+import requests
+
+# Configuration
+API_KEY = "<YOUR_API_KEY>"  # Get from /v1/user/me/api-key
+BASE_URL = "https://api.inference.paytm.com/v1"
+
+# Request payload
+payload = {
+    "model": "llama-3.1-8b-instant",
+    "messages": [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Your message here"}
+    ],
+    "temperature": 0.7,
+    "max_tokens": 1024,
+    "top_p": 0.95,
+    "top_k": 50,
+    "frequency_penalty": 0,
+    "presence_penalty": 0,
+    "repetition_penalty": 1,
+    "stream": True
+}
+
+# Make request
+headers = {
+    "Authorization": f"Bearer {API_KEY}",
+    "Content-Type": "application/json"
+}
+response = requests.post(
+    f"{BASE_URL}/ai/playground",
+    json=payload,
+    headers=headers
+)
+
+result = response.json()
+if result["success"]:
+    print(result["data"]["choices"][0]["message"]["content"])
+else:
+    print(f"Error: {result['error']}")
+
+
+THE ABOVE IS FOR LLM
+
+
+
+BELOW ARE CURL
+
+
+curl -X POST https://api.inference.paytm.com/v1/ai/playground \
+  -H "Authorization: Bearer <YOUR_API_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "llama-3.1-8b-instant",
+    "messages": [
+      {"role": "system", "content": "You are a helpful assistant."},
+      {"role": "user", "content": "Your message here"}
+    ],
+    "temperature": 0.7,
+    "max_tokens": 1024,
+    "top_p": 0.95,
+    "top_k": 50,
+    "frequency_penalty": 0,
+    "presence_penalty": 0,
+    "repetition_penalty": 1,
+    "stream": true
+  }'
+
+
+  curl -X POST https://api.paytmai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer <YOUR_API_KEY>" \
+  -F "file=@audio.mp3" \
+  -F "model=whisper-large-v3" \
+  -F "response_format=json" \
+  -F "temperature=0"
+
+
+  ![alt text](image.png)

paytm_llm_api_docs.md

@@ -0,0 +1,152 @@
+# Paytm Payment MCP Server & AI Router API Documentation
+
+This documentation is curated for Large Language Models (LLMs) and developers integrating Paytm's Model Context Protocol (MCP) Server and AI Router services. It covers everything from conversational AI integration to specific transactional workflows and routing configurations.
+
+---
+
+## Part 1: Paytm MCP Server
+
+Paytm MCP Server enables AI agents and developers to securely access Paytm's Payments and Business Payments APIs securely via the Model Context Protocol (MCP). 
+
+### Main Features
+- **Smart Payment Ops**: Automate refund workflows, settlement tracking, and transaction status checks.
+- **Context-Aware AI Assistants**: Trigger queries via natural language (e.g. \"Create a ₹500 payment link\").
+- **Agentic AI Payments**: Provide enhanced automated and dynamic shopping experiences.
+
+### MCP Tools Available
+The MCP exposes a set of tools mapped to Paytm's underlying REST APIs. An LLM agent can invoke these exact tools:
+
+| Tool Name                            | Description                                                                                                   | Underlying API Context                                         |
+|--------------------------------------|---------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
+| `create_link`                        | Creates a new payment link.                                                                                   | Create Link API                                                |
+| `fetch_link`                         | Fetches details of a created payment link.                                                                    | Fetch Link API                                                 |
+| `fetch_transaction`                  | Fetches transaction details specific to a payment link.                                                       | Fetch Transaction Link API                                     |
+| `fetch_order_list`                   | Fetches list of orders within a 30-day date range.                                                            | Order List API                                                 |
+| `initiate_refund`                    | Initiates a refund for a specific transaction.                                                                | Initiate Refund API                                            |
+| `check_refund_status`                | Checks the status of a previously initiated refund.                                                           | Check Refund Status API                                        |
+| `fetch_refund_list`                  | Fetches a list of refunds within a 30-day date range.                                                         | Fetch Refund List API                                          |
+| `get_settlement_summary`             | Retrieves overall summary details of payouts for a date range or payout ID.                                   | Get Settlement Summary API                                     |
+| `get_settlement_detail`              | Retrieves a granular/transactional view of all settled transactions at the payout level.                      | Get Settlement Details API                                     |
+| `get_settlement_order_details`       | Retrieves settlement details at an order level (needs payout date and order ID).                              | Get Settlement Order Details API                               |
+| `get_settlement_transaction_details` | Retrieves settlement details of a specific order based on transaction ID.                                     | Get Settlement Transaction Details API                         |
+
+### Deployment Modes
+1. **Remote MCP (Recommended)**: Hosted by Paytm. Requires requesting a `Client ID` and `Secret Key` from `devsupport@paytmpayments.com`. You will use your `PAYTM_MID`. Cursor setup via `generate_mcp_token_cursor.sh` to generate a JWT token.
+2. **Local MCP (Self-Hosted)**: Run locally via `Claude Desktop`.
+   - Requires Python 3.12+, `uv`, and Claude Desktop.
+   - Env variables required: `PAYTM_MID`, `PAYTM_KEY_SECRET`.
+   - `claude_desktop_config.json` uses `uv path --directory <dir> run paytm_mcp.py`.
+
+---
+
+## Part 2: AI Router Payment Flow
+
+The AI Router serves to centralize the checkout process and smartly route payments across configured payment aggregators (PAs)/payment gateways (PGs).
+
+### Standard Transaction Journey
+1. **Initiation**: Merchant initiates the transaction by calling the **Create Order API**.
+2. **Token Generation**: AI Router creates an order and returns a **Transaction Token** along with an Order ID.
+3. **Fetch Options**: Merchant calls **Fetch Payment Options API** to retrieve available payment methods.
+4. **Checkout Rendering**: AI Router provides the configured options, which populate the cashier page.
+5. **Execution**: User selects an option and clicks Pay. The **Pay API** is then called.
+6. **Routing**: AI Router intelligently evaluates and routes the transaction to the most appropriate PA/PG.
+7. **Processing**: Gateway processes the transaction and returns status to AI Router.
+8. **Verification**: 
+   - Polling: Merchant polls the **Order Status API** (using the Order ID).
+   - Server-to-Server: Alternatively, AI Router triggers a real-time **Payment Webhook** with the updated payment status.
+
+---
+
+## Part 3: AI Router Routing Rule Configuration
+
+If no rules are created, the AI Router defaults to selecting the gateway with the highest historical/real-time success probability. Merchants can explicitly define routing constraints via the dashboard or APIs.
+
+### 1. Gateway Routing Configuration
+Routing can be applied to One-Time payments and Subscription payments.
+- **UPI Routing**: Filtered by UPI Intent vs. UPI Collect, and optionally limited by transaction amount ranges.
+- **Bank Mandates Routing**: Filtered by Mandate Type (Netbanking vs Debit Card) and applied against specific Issuing Banks.
+- **Cards Routing**: Rules set by card attributes (Credit, Debit, Prepaid, Visa, Mastercard, RuPay, Amex, Diners, Issuing Bank).
+  - **Cost-Based Routing**: Optimizes for gateway costs.
+    - *Relative Cost*: Ranked priority preference according to cheapest.
+    - *Absolute Cost*: Flat value or percentage based. Minimum Success Rate baselines can also be configured so cheap traffic ensures minimum reliability.
+
+### 2. API Based / Enforced Routing
+Transaction-level control that overrides dashboard configurations, primarily used for targeted business campaigns/promotions.
+- **How to Use**: Pass special parameter variables via code during runtime.
+- **Payload**: Provide `enforcedRoutingParam` inside the `txnRoutingParams` object.
+- **Endpoint Injection**: This object must be pushed in either the **Create Order API** or **Pay API**. (If a conflict exists between the two, parameters sent via the Pay API take precedence).
+
+---
+
+## Part 4: General Developer Implementation Notes & FAQs
+- **Gateways requirement**: Merchants must independently onboard with third-party payment aggregators. Once keys are received, submit them statically inside the Paytm AI Router Dashboard.
+- **Fallback Logic**: If the lowest cost gateway drops below the success rate baseline, AI Router will auto-skip to the next cheapest that meets strict success margins.
+- **Integration**: The unified AI Router architecture prevents merchants from having to build split/custom integrations for every gateway backend. Call the AI Router suite uniformly, and routing configs isolate the complexities.
+
+---
+
+## Part 5: Core Transaction APIs
+1. **Initiate Transaction API**: Used to create an order and retrieve a transaction token.
+   - Endpoint: `POST /theia/api/v1/initiateTransaction?mid={MID}&orderId={ORDERID}`
+   - Body contains: `requestType` (Payment), `txnAmount` (value, currency), `userInfo` (custId), `callbackUrl`
+2. **Process Transaction API**: Used to process the payment using the generated token.
+   - Body contains: `paymentMode` (e.g., `CC`, `DC`, `NET_BANKING`, `UPI`, `BALANCE`), `cardInfo`, `channelCode`.
+3. **Transaction Status API**: Query the status of a specific order.
+   - Body contains: `ORDERID`, `MID`. Returns `STATUS` (e.g., `TXN_SUCCESS`, `TXN_FAILURE`).
+
+---
+
+## Part 6: JS Checkout Integration
+A customized frontend layer that natively displays payment options on the merchant's site.
+1. Inject the script: `<script src="https://securegw.paytm.in/merchantpgpui/checkoutjs/merchants/{MID}.js"></script>`
+2. Initialize and Invoke:
+   ```javascript
+   var config = { "root": "", "flow": "DEFAULT", "data": { "orderId": "{ORDERID}", "token": "{TXN_TOKEN}", "tokenType": "TXN_TOKEN", "amount": "{AMOUNT}" }, "handler": { "notifyMerchant": function(eventName,data){ ... } } };
+   window.Paytm.CheckoutJS.init(config).then(function() {
+       window.Paytm.CheckoutJS.invoke();
+   });
+   ```
+
+---
+
+## Part 7: Subscriptions
+- **Initiate Subscription API**: Used to create a subscription mandate.
+- **List Subscriptions API**: Used to view active/inactive mandates.
+- **JS Checkout for Subscriptions**: Extends JS Checkout by passing subscription-specific flags (e.g., `requestType: "SUBSCRIBE"`) during checkout initialization.
+
+---
+
+## Part 8: Post-Transaction & Financials
+1. **Refund API**: Initiate a partial or full refund against a `TXNID`.
+   - Requires: `ORDERID`, `TXNID`, `refId` (merchant-generated unique refund ID), `refundAmount`.
+2. **Settlement APIs**:
+   - **Settlement Summary API**: Fetches the gross/net settlement summary against the Payout Date.
+   - **Settlement Detail API**: Provides transactional-level granularity of an executed settlement.
+
+---
+
+## Part 9: Webhooks & Callbacks
+1. **Payment Status Webhook**: Paytm pushes real-time server-to-server updates when an order transitions to a terminal state (Success/Failure).
+   - Payload includes: `ORDERID`, `TXNID`, `TXNAMOUNT`, `STATUS`, `RESPCODE`, `RESPMSG`, `CHECKSUMHASH`.
+   - Merchants must validate the `CHECKSUMHASH` against their `PAYTM_KEY_SECRET` to prevent spoofing.
+   - Webhook URL is setup via the Merchant Dashboard.
+
+---
+
+## Part 10: AI Router Analytics & Reports
+Paytm provides a rich dashboard for visualizing and analyzing transaction data. This is particularly useful when building merchant-facing LLM agents that need to query or interpret performance graphs, failures, and reconciliations.
+
+### 1. Analytics Dashboards
+- **Successful Payments Analysis**: Tracks successful payment volumes. Supports Historical Benchmarking (Yesterday, Current Week vs Last Week, Current Month comparisons) and Historic Trends. Can overlay **Gateways**, **Payment Source**, and **Moving Averages**.
+- **Total Collection Analysis**: Similar to volume tracking, but tracks the Total Collection Amount in INR. 
+- **Success Rate Analysis**: Tracks the transaction success percentage. Includes **Failure Reasons Analytics** (identifies if the failure was caused by the user, bank, or the router) and highlights the top failure contributors.
+
+### 2. Standard Reports
+- **Payments Report**: Offers a List View (Transaction ID, Date, Order ID, Payment Source, Gateway, Amount) and a Detailed View (Response Codes, Customer details). Allows single-click refund initiation.
+- **Refunds Report**: Offers List View and Detailed View (shows RRN [Refund Reference Number]).
+- **Bulk Refunds**: Merchants can upload a CSV (containing `TXN_ID`, `REFUND_AMOUNT`, and `REFUND_REASON`) to process mass bulk refunds directly from the dashboard panel.
+
+### 3. Report Generation and Downloads
+- **Exporting**: Reports can be downloaded offline (CSV/Excel/PDF) or emailed directly.
+- **Constraints**: Maximum querying duration for a single report export is 3 months.
+- **Filters Supported**: Date/Time Range, Specific Payment Gateway, Payment Source (CC/DC/UPI), Status (Success, Pending, Failed), Order ID, etc.

requirements.txt

@@ -0,0 +1,5 @@
+fastapi
+uvicorn
+requests
+pytest
+httpx

scripts/seed_scenarios.py

@@ -0,0 +1,14 @@
+from app.config import load_settings
+from app.db.repo import Repository
+
+
+def main() -> None:
+    settings = load_settings()
+    repo = Repository(settings.db_path)
+    repo.seed_demo_data(force=True)
+    print("Mock scenarios seeded successfully.")
+    print(f"Database path: {settings.db_path}")
+
+
+if __name__ == "__main__":
+    main()

tests/test_context_memory.py

@@ -0,0 +1,148 @@
+"""Tests for the new conversational-memory / rolling-context feature."""
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+from app.agent.orchestrator import Orchestrator
+from app.db.repo import Repository
+from app.llm.client import LlmClient
+from app.tools.mock_paytm import MockPaytmTools
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_repo(tmp_path: Path) -> Repository:
+    repo = Repository(str(tmp_path / "ctx.sqlite3"))
+    repo.seed_demo_data()
+    return repo
+
+
+def _make_orchestrator(tmp_path: Path) -> tuple[Orchestrator, Repository, LlmClient]:
+    repo = _make_repo(tmp_path)
+    tools = MockPaytmTools(repo)
+    llm = LlmClient("", "", "test-model")
+    orch = Orchestrator(repo, tools, llm)
+    return orch, repo, llm
+
+
+# ---------------------------------------------------------------------------
+# repo.get_recent_context
+# ---------------------------------------------------------------------------
+
+def test_get_recent_context_returns_history(tmp_path: Path) -> None:
+    repo = _make_repo(tmp_path)
+    uid = repo.ensure_user("u1")
+
+    repo.save_message(uid, "text", "hello", "hi there")
+    repo.save_message(uid, "text", "show orders", "found 4 orders")
+    repo.save_message(uid, "voice", "refund status", "no pending refunds")
+
+    ctx = repo.get_recent_context(uid)
+    # 3 exchanges -> 6 messages (user + assistant each)
+    assert len(ctx) == 6
+    assert ctx[0] == {"role": "user", "content": "hello"}
+    assert ctx[1] == {"role": "assistant", "content": "hi there"}
+    assert ctx[-2] == {"role": "user", "content": "refund status"}
+    assert ctx[-1] == {"role": "assistant", "content": "no pending refunds"}
+
+
+def test_get_recent_context_empty_for_new_user(tmp_path: Path) -> None:
+    repo = _make_repo(tmp_path)
+    uid = repo.ensure_user("brand-new-user")
+    ctx = repo.get_recent_context(uid)
+    assert ctx == []
+
+
+def test_get_recent_context_respects_limit(tmp_path: Path) -> None:
+    repo = _make_repo(tmp_path)
+    uid = repo.ensure_user("u2")
+
+    for i in range(10):
+        repo.save_message(uid, "text", f"msg-{i}", f"reply-{i}")
+
+    ctx = repo.get_recent_context(uid, limit=3)
+    # limit=3 means 3 DB rows -> 6 role messages, but only the most recent 3 exchanges
+    assert len(ctx) == 6
+    assert ctx[0]["content"] == "msg-7"  # oldest of the 3 kept
+    assert ctx[-1]["content"] == "reply-9"  # newest
+
+
+# ---------------------------------------------------------------------------
+# LlmClient.generate – payload structure
+# ---------------------------------------------------------------------------
+
+def test_generate_builds_payload_with_history(tmp_path: Path) -> None:
+    llm = LlmClient("https://example.com/v1/chat/completions", "key", "model")
+    history = [
+        {"role": "user", "content": "hi"},
+        {"role": "assistant", "content": "hello"},
+    ]
+
+    with patch("app.llm.client.requests.post") as mock_post:
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {
+            "choices": [{"message": {"content": "test reply"}}]
+        }
+        mock_resp.raise_for_status = MagicMock()
+        mock_post.return_value = mock_resp
+
+        result = llm.generate("what now?", history=history)
+
+    assert result == "test reply"
+    called_payload = mock_post.call_args.kwargs.get("json") or mock_post.call_args[1].get("json")
+    msgs = called_payload["messages"]
+    # system + 2 history + current user = 4
+    assert len(msgs) == 4
+    assert msgs[0]["role"] == "system"
+    assert msgs[1] == {"role": "user", "content": "hi"}
+    assert msgs[2] == {"role": "assistant", "content": "hello"}
+    assert msgs[3] == {"role": "user", "content": "what now?"}
+
+
+def test_generate_works_without_history() -> None:
+    """Backward compat: calling generate without history still works."""
+    llm = LlmClient("https://example.com/v1/chat/completions", "key", "model")
+
+    with patch("app.llm.client.requests.post") as mock_post:
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {
+            "choices": [{"message": {"content": "ok"}}]
+        }
+        mock_resp.raise_for_status = MagicMock()
+        mock_post.return_value = mock_resp
+
+        result = llm.generate("just a prompt")
+
+    assert result == "ok"
+    called_payload = mock_post.call_args.kwargs.get("json") or mock_post.call_args[1].get("json")
+    msgs = called_payload["messages"]
+    # system + user = 2  (no history)
+    assert len(msgs) == 2
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator integration – context flows through
+# ---------------------------------------------------------------------------
+
+def test_orchestrator_passes_context_to_llm(tmp_path: Path) -> None:
+    """When the orchestrator falls through to the LLM path, it should
+    include prior context in the generate() call."""
+    orch, repo, llm = _make_orchestrator(tmp_path)
+    uid = repo.ensure_user("t-100")
+
+    # Seed a prior message so there's context to retrieve
+    repo.save_message(uid, "text", "show orders", "found 4 orders")
+
+    with patch.object(llm, "generate", return_value="mocked reply") as mock_gen:
+        reply = orch.handle_user_text("t-100", "tell me more about the first one")
+
+    assert reply == "mocked reply"
+    # Verify generate was called with history kwarg containing prior context
+    args, kwargs = mock_gen.call_args
+    assert "history" in kwargs
+    assert len(kwargs["history"]) == 2  # 1 prior exchange = 2 messages
+    assert kwargs["history"][0]["content"] == "show orders"
+    assert kwargs["history"][1]["content"] == "found 4 orders"

tests/test_mock_tools.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+from app.db.repo import Repository
+from app.tools.mock_paytm import MockPaytmTools
+
+
+def test_create_and_fetch_link(tmp_path: Path) -> None:
+    repo = Repository(str(tmp_path / "mock.sqlite3"))
+    tools = MockPaytmTools(repo)
+
+    created = tools.create_link(250.0, "Amit")
+    fetched = tools.fetch_link(created["link_id"])
+
+    assert fetched["link_id"] == created["link_id"]
+    assert fetched["amount"] == 250.0
+    assert fetched["customer_name"] == "Amit"
+
+
+def test_refund_workflow(tmp_path: Path) -> None:
+    repo = Repository(str(tmp_path / "refund.sqlite3"))
+    tools = MockPaytmTools(repo)
+
+    initiated = tools.initiate_refund("TXN-2001", 99.0)
+    status = tools.check_refund_status(initiated["refund_id"])
+
+    assert status["refund_id"] == initiated["refund_id"]
+    assert status["txn_id"] == "TXN-2001"
+    assert status["status"] == "PENDING"

tests/test_orchestrator.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+from app.agent.orchestrator import Orchestrator
+from app.db.repo import Repository
+from app.llm.client import LlmClient
+from app.tools.mock_paytm import MockPaytmTools
+
+
+def build_orchestrator(tmp_path: Path) -> Orchestrator:
+    repo = Repository(str(tmp_path / "orch.sqlite3"))
+    repo.seed_demo_data()
+    tools = MockPaytmTools(repo)
+    llm = LlmClient("", "", "llama-3.1-8b-instant")
+    return Orchestrator(repo, tools, llm)
+
+
+def test_order_query_returns_summary(tmp_path: Path) -> None:
+    orchestrator = build_orchestrator(tmp_path)
+    response = orchestrator.handle_user_text("123", "show recent orders")
+    assert "orders" in response
+    assert "<b>" in response
+
+
+def test_refund_requires_confirm_then_executes(tmp_path: Path) -> None:
+    orchestrator = build_orchestrator(tmp_path)
+    preview = orchestrator.handle_user_text("123", "refund txn-2001 amount 20")
+    assert "confirm" in preview.lower()
+
+    confirmed = orchestrator.handle_user_text("123", "confirm")
+    assert "Refund initiated" in confirmed

tests/test_smoke.py

@@ -0,0 +1,26 @@
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+
+def test_health() -> None:
+    client = TestClient(app)
+    response = client.get("/health")
+    assert response.status_code == 200
+    assert response.json()["status"] == "ok"
+
+
+def test_webhook_text_message() -> None:
+    client = TestClient(app)
+    payload = {
+        "message": {"chat": {"id": 101}, "text": "show settlement summary"},
+    }
+    response = client.post(
+        "/telegram/webhook",
+        json=payload,
+        headers={"X-Telegram-Bot-Api-Secret-Token": "local-secret"},
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert data["ok"] is True
+    assert data["input_type"] == "text"

tests/test_telegram_handler.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+from app.agent.orchestrator import Orchestrator
+from app.db.repo import Repository
+from app.llm.client import LlmClient
+from app.telegram.handler import TelegramHandler
+from app.tools.mock_paytm import MockPaytmTools
+from app.voice.stt import SttClient
+
+
+def build_handler(tmp_path: Path) -> TelegramHandler:
+    repo = Repository(str(tmp_path / "telegram.sqlite3"))
+    repo.seed_demo_data(force=True)
+    orchestrator = Orchestrator(repo, MockPaytmTools(repo), LlmClient("", "", "llama"))
+    stt = SttClient("", "", "whisper-large-v3-turbo")
+    return TelegramHandler(orchestrator, stt, bot_token="")
+
+
+def test_voice_update_without_bot_token_falls_back(tmp_path: Path) -> None:
+    handler = build_handler(tmp_path)
+    result = handler.process_update(
+        {"message": {"chat": {"id": 999}, "voice": {"file_id": "abc123"}}}
+    )
+    assert result["ok"] is True
+    assert result["input_type"] == "voice"
+    assert "transcription unavailable" in result["transcript"]
+
+
+def test_audio_update_is_supported(tmp_path: Path) -> None:
+    handler = build_handler(tmp_path)
+    result = handler.process_update(
+        {"message": {"chat": {"id": 999}, "audio": {"file_id": "xyz123"}}}
+    )
+    assert result["ok"] is True
+    assert result["input_type"] == "voice"
+    assert "transcription unavailable" in result["transcript"]