# tanya-223/vaani_market architecture

> Architecture diagram of the GitHub repository tanya-223/vaani_market, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tanya-223/vaani_market
- Repository: https://github.com/tanya-223/vaani_market

## Overview

Vaani Market is a voice-first, multilingual Indian-market explainer. A browser sends spoken audio to the web server, which obtains a transcript and passes the turn to the orchestrator. The orchestrator applies deterministic refusal and clarification checks, plans the query, resolves tickers, gathers market facts or retrieval context, and produces a grounded answer guarded against unsupported numbers and advice. The web app returns text and display data and can synthesize spoken output. README documents several pipeline links; sampled excerpts confirm only some call sites, so unsampled links are cited to the README.

Main entry points: [`src/vaani/agent/orchestrate.py`](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/orchestrate.py) (Turn orchestrator), [`src/vaani/web/app.py`](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/web/app.py) (HTTP web server), [`src/vaani/retrieval/tier2.py`](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/tier2.py) (Hybrid company retrieval), [`src/vaani/web/static/app.js`](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/web/static/app.js) (Browser voice UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_webui["Browser voice UI<br/>[app.js]"]
  node_webserver["HTTP web server<br/>[app.py]"]
end

subgraph group_orchestration["Turn orchestration"]
  node_orchestrator["Turn orchestrator<br/>[orchestrate.py]"]
  node_advice["Advice classifier<br/>[advice.py]"]
  node_planner["Intent planner<br/>[planner.py]"]
  node_ticker["Ticker resolver<br/>[ticker_resolver.py]"]
  node_memory[("Session memory<br/>[memory.py]")]
end

subgraph group_knowledge["Market and retrieval"]
  node_facts["Grounded facts<br/>[facts.py]"]
  node_market["Market data tools<br/>[market.py]"]
  node_tier1["Glossary retrieval<br/>[tier1.py]"]
  node_glossary["Multilingual glossary<br/>[glossary.py]"]
  node_tier2["Hybrid company retrieval<br/>[tier2.py]"]
  node_corpus["Company notes<br/>[corpus.py]"]
  node_retrievalrouter["Retrieval budgets<br/>[router.py]"]
end

subgraph group_generation["Answer and safety"]
  node_refusal["Refusal responses<br/>[refusal.py]"]
  node_explainer["Answer explainer<br/>[explainer.py]"]
  node_numericgate["Numeric provenance gate<br/>[numeric_gate.py]"]
  node_outputguard["Advice output guard<br/>[advice.py]"]
end

subgraph group_integrations["Speech and model services"]
  node_stt["Prisma speech recognition<br/>[stt.py]"]
  node_tts["Timbre speech synthesis<br/>[tts.py]"]
  node_llm["LLM adapter<br/>[adapter.py]"]
end

node_user(("Market questioner"))
node_gnani{{"Gnani speech APIs"}}
node_yahoo{{"Yahoo Finance"}}
node_llmservice{{"LLM and embedding API"}}

node_user -->|"asks by voice"| node_webui
node_webui -->|"sends audio"| node_webserver
node_webserver -->|"transcribes audio"| node_stt
node_stt -->|"requests transcript"| node_gnani
node_webserver -->|"routes transcript"| node_orchestrator
node_orchestrator -->|"checks intent"| node_advice
node_orchestrator -->|"returns refusal"| node_refusal
node_orchestrator -->|"checks ambiguity"| node_ticker
node_orchestrator -->|"plans query"| node_planner
node_planner -->|"requests plan"| node_llm
node_orchestrator -->|"uses session"| node_memory
node_orchestrator -->|"queries concepts"| node_tier1
node_tier1 -->|"retrieves entries"| node_glossary
node_tier1 -->|"runs within budget"| node_retrievalrouter
node_orchestrator -->|"resolves planned ticker"| node_ticker
node_orchestrator -->|"builds facts"| node_facts
node_facts -->|"fetches market data"| node_market
node_market -->|"fetches quotes and news"| node_yahoo
node_orchestrator -->|"attaches company notes"| node_tier2
node_tier2 -->|"retrieves notes"| node_corpus
node_tier2 -->|"embeds queries"| node_llm
node_tier2 -->|"uses tier budgets"| node_retrievalrouter
node_orchestrator -->|"generates answer"| node_explainer
node_explainer -->|"requests explanation"| node_llm
node_orchestrator -->|"checks numeric provenance"| node_numericgate
node_orchestrator -->|"rejects unsafe output"| node_outputguard
node_llm -->|"sends chat and embeddings"| node_llmservice
node_orchestrator -->|"returns answer payload"| node_webserver
node_webserver -->|"synthesizes speech"| node_tts
node_tts -->|"requests audio"| node_gnani
node_webserver -->|"returns answer and audio"| node_webui
node_webui -->|"plays spoken answer"| node_user

click node_webui "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/web/static/app.js"
click node_webserver "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/web/app.py"
click node_orchestrator "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/orchestrate.py"
click node_advice "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/advice.py"
click node_refusal "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/refusal.py"
click node_planner "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/planner.py"
click node_ticker "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/ticker_resolver.py"
click node_memory "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/memory.py"
click node_facts "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/facts.py"
click node_market "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/data/market.py"
click node_tier1 "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/tier1.py"
click node_glossary "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/glossary.py"
click node_tier2 "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/tier2.py"
click node_corpus "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/corpus.py"
click node_retrievalrouter "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/router.py"
click node_explainer "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/explainer.py"
click node_numericgate "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/numeric_gate.py"
click node_outputguard "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/advice.py"
click node_stt "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/gnani/stt.py"
click node_tts "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/gnani/tts.py"
click node_llm "https://github.com/tanya-223/vaani_market/blob/main/src/vaani/llm/adapter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webui,node_webserver toneBlue
class node_orchestrator,node_advice,node_planner,node_ticker,node_memory toneAmber
class node_facts,node_market,node_tier1,node_glossary,node_tier2,node_corpus,node_retrievalrouter,node_gnani,node_llmservice toneMint
class node_refusal,node_explainer,node_numericgate,node_outputguard toneRose
class node_stt,node_tts,node_llm,node_user,node_yahoo toneIndigo
```

## Components

### Web experience

- [Browser voice UI](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/web/static/app.js): `src/vaani/web/static/app.js`
- [HTTP web server](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/web/app.py): `src/vaani/web/app.py`

### Turn orchestration

- [Turn orchestrator](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/orchestrate.py): `src/vaani/agent/orchestrate.py`
- [Advice classifier](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/advice.py): `src/vaani/agent/advice.py`
- [Intent planner](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/planner.py): `src/vaani/agent/planner.py`
- [Ticker resolver](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/ticker_resolver.py): `src/vaani/agent/ticker_resolver.py`
- [Session memory](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/memory.py): `src/vaani/agent/memory.py`

### Market and retrieval

- [Grounded facts](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/facts.py): `src/vaani/agent/facts.py`
- [Market data tools](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/data/market.py): `src/vaani/data/market.py`
- [Glossary retrieval](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/tier1.py): `src/vaani/retrieval/tier1.py`
- [Multilingual glossary](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/glossary.py): `src/vaani/retrieval/glossary.py`
- [Hybrid company retrieval](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/tier2.py): `src/vaani/retrieval/tier2.py`
- [Company notes](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/corpus.py): `src/vaani/retrieval/corpus.py`
- [Retrieval budgets](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/retrieval/router.py): `src/vaani/retrieval/router.py`

### Answer and safety

- [Refusal responses](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/refusal.py): `src/vaani/agent/refusal.py`
- [Answer explainer](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/explainer.py): `src/vaani/agent/explainer.py`
- [Numeric provenance gate](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/numeric_gate.py): `src/vaani/agent/numeric_gate.py`
- [Advice output guard](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/agent/advice.py): `src/vaani/agent/advice.py`

### Speech and model services

- [Prisma speech recognition](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/gnani/stt.py): `src/vaani/gnani/stt.py`
- [Timbre speech synthesis](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/gnani/tts.py): `src/vaani/gnani/tts.py`
- [LLM adapter](https://github.com/tanya-223/vaani_market/blob/main/src/vaani/llm/adapter.py): `src/vaani/llm/adapter.py`

### Other components

- **Market questioner**
- **Gnani speech APIs**
- **Yahoo Finance**
- **LLM and embedding API**

## Connections

- Market questioner → Browser voice UI: asks by voice
- Browser voice UI → HTTP web server: sends audio
- HTTP web server → Prisma speech recognition: transcribes audio (evidence: `src/vaani/web/app.py`)
- Prisma speech recognition → Gnani speech APIs: requests transcript
- HTTP web server → Turn orchestrator: routes transcript (evidence: `src/vaani/web/app.py`)
- Turn orchestrator → Advice classifier: checks intent (evidence: `src/vaani/agent/orchestrate.py`)
- Turn orchestrator → Refusal responses: returns refusal (evidence: `src/vaani/agent/orchestrate.py`)
- Turn orchestrator → Ticker resolver: checks ambiguity (evidence: `src/vaani/agent/orchestrate.py`)
- Turn orchestrator → Intent planner: plans query (evidence: `src/vaani/agent/orchestrate.py`)
- Intent planner → LLM adapter: requests plan (evidence: `src/vaani/agent/planner.py`)
- Turn orchestrator → Session memory: uses session (evidence: `src/vaani/agent/orchestrate.py`)
- Turn orchestrator → Glossary retrieval: queries concepts (evidence: `src/vaani/agent/orchestrate.py`)
- Glossary retrieval → Multilingual glossary: retrieves entries (evidence: `src/vaani/retrieval/tier1.py`)
- Glossary retrieval → Retrieval budgets: runs within budget (evidence: `src/vaani/retrieval/tier1.py`)
- Turn orchestrator → Ticker resolver: resolves planned ticker (evidence: `src/vaani/agent/orchestrate.py`)
- Turn orchestrator → Grounded facts: builds facts (evidence: `src/vaani/agent/orchestrate.py`)
- Grounded facts → Market data tools: fetches market data (evidence: `src/vaani/agent/facts.py`)
- Market data tools → Yahoo Finance: fetches quotes and news
- Turn orchestrator → Hybrid company retrieval: attaches company notes (evidence: `src/vaani/agent/orchestrate.py`)
- Hybrid company retrieval → Company notes: retrieves notes (evidence: `src/vaani/retrieval/tier2.py`)
- Hybrid company retrieval → LLM adapter: embeds queries (evidence: `src/vaani/retrieval/tier2.py`)
- Hybrid company retrieval → Retrieval budgets: uses tier budgets
- Turn orchestrator → Answer explainer: generates answer (evidence: `src/vaani/agent/orchestrate.py`)
- Answer explainer → LLM adapter: requests explanation (evidence: `src/vaani/agent/explainer.py`)
- Turn orchestrator → Numeric provenance gate: checks numeric provenance (evidence: `src/vaani/agent/orchestrate.py`)
- Turn orchestrator → Advice output guard: rejects unsafe output (evidence: `src/vaani/agent/orchestrate.py`)
- LLM adapter → LLM and embedding API: sends chat and embeddings (evidence: `src/vaani/llm/adapter.py`)
- Turn orchestrator → HTTP web server: returns answer payload (evidence: `src/vaani/web/app.py`)
- HTTP web server → Timbre speech synthesis: synthesizes speech (evidence: `src/vaani/web/app.py`)
- Timbre speech synthesis → Gnani speech APIs: requests audio
- HTTP web server → Browser voice UI: returns answer and audio
- Browser voice UI → Market questioner: plays spoken answer