Metadata-Version: 2.5
Name: vaad
Version: 1.1.0
Summary: OpenAI-compatible gateway that makes small local models produce correct tool calls from Hindi and Hinglish.
Author: Satyansh Gaur
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Natural Language :: Hindi
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: dateparser>=1.2
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4.22
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: livekit
Requires-Dist: livekit-agents>=1.0; extra == 'livekit'
Provides-Extra: pipecat
Requires-Dist: pipecat-ai>=1.0; extra == 'pipecat'
Description-Content-Type: text/markdown

# vaad

**vaad is the value guard between speech-to-text and your tools for Hindi/Hinglish agents. It never lets a
wrong amount, time or date execute silently: it is sure, or it asks.** It parses spoken-form values ("dedh
hazaar" = 1500, "saade aath baje", lakh/crore, quantities, phone numbers, tense-aware "kal"), with a span, a
calibrated confidence and an audit trail, and works as a library, a CLI, a Pipecat processor
(`pip install "vaad[pipecat]"`), a LiveKit Agents mixin (`pip install "vaad[livekit]"`) or an OpenAI-compatible gateway. See [docs/POSITIONING.md](docs/POSITIONING.md).

```sh
vaad guard "kal saade aath baje dedh lakh rupaye bhej do" --ref-date 2026-11-09
# use: amount 150000   confirm: "₹1,50,000, sahi hai?"   ask: "'saade aath baje': subah ya shaam?"
```

Live demo against a local model (Qwen3.5-4B, synthetic requests; `python examples/demo_payment.py`,
[transcript](docs/demo/payment_demo_qwen3.5-4b.txt)):

```text
User: 9876501234 pe paanch sau rupaye bhej do
  without vaad: send_money(amount_inr=50000)      <- wrong in 4 of 4 runs
  with vaad:    "₹500, sahi hai?"
User: 98123 45670 ko dedh hazaar transfer kar do
  without vaad: send_money(amount_inr=1000)       <- wrong in 4 of 4 runs
  with vaad:    "1,500, sahi hai?"
```

This compares the bare model with the guard's output; it is not an end-to-end run of the guard in front of the model.

```python
from datetime import date
from vaad.canon import annotate_turn

annotate_turn("mera order kal tak bhej do, dedh hazaar rupaye", date(2026, 10, 24))
# 'mera order kal [=2026-10-25] tak bhej do, dedh hazaar [=1500] rupaye'
```

**What is measured** (details and caveats in [docs/RESULTS.md](docs/RESULTS.md), calibration in
[docs/CALIBRATION.md](docs/CALIBRATION.md)):

- On 189 held-out human-typed tool-calling tasks, the normalizer raised pass^4 by 16 to 22 points on three
  small models (all intervals above 0) and cut wrong values from 23-42% to 7-9% with `canon.mode: both`.
- Outputs the parser is at least 90% sure of were right 97-100% of the time on held-out data.
- These tasks were written to contain values. In real chat such values are rare, and spoken input through
  ASR is **not tested yet** (planned for v2, see [docs/AUDIO_SPEC.md](docs/AUDIO_SPEC.md)).
- Lexicons are AI-written and not yet native-reviewed.

**Status:** pre-alpha. See [docs/](docs/README.md) for the plan, results, methods, data, architecture and
decisions.

## Development

Requires [uv](https://docs.astral.sh/uv/).

```sh
uv sync
uv run pytest                     # tests
uv run ruff check . && uv run ruff format --check .
uv run mypy                       # strict on canon/, router/, grammar/
uv run python -m harness.leakage  # gate 10
uv run vaad serve --config config/vaad.yaml   # copy from config/vaad.example.yaml
```

## Layout

| Path | What |
|---|---|
| `src/vaad/server/` | FastAPI proxy, OpenAI-compatible routes, tracing |
| `src/vaad/router/` | language ID, difficulty signals, routing policy |
| `src/vaad/grammar/` | schema tightening, post-generation validation |
| `src/vaad/canon/` | the canonicalizer: numbers, money, dates, times, phones, units |
| `harness/` | task sets, runner, metrics, bootstrap intervals, reports |
| `quants/` | Indic-calibrated GGUF quant recipes and reliability cards |
| `tests/` | unit, golden, property and integration tests |

## License

Apache-2.0.
