Install VAANI¶

VAANI and create-vaani-app are private Google Artifact Registry packages. The public PyPI project named vaani is unrelated.

Developer registry authentication¶

These credentials let a developer or CI job download packages. They are not used by a running voicebot.

Prerequisites:

Python 3.11–3.13
Node 20+ and npm
uv
Google Cloud CLI
read-only roles/artifactregistry.reader access to project birla-loyalty-voice-bot

Authenticate and install the keyring that lets uv obtain short-lived Google credentials:

gcloud auth application-default login
uv tool install keyring --with keyrings.google-artifactregistry-auth
export UV_INDEX="https://oauth2accesstoken@asia-south1-python.pkg.dev/birla-loyalty-voice-bot/vaani-python/simple/"

oauth2accesstoken is Google's fixed keyring username, not a token. In CI, use an approved workload identity with read-only Artifact Registry access.

Bot runtime credentials¶

After installation, the bot needs separate credentials for LiveKit and the STT, reasoning, and TTS providers selected by its preset. Artifact Registry Reader access does not give the bot access to LiveKit, Deepgram, Google models, SmallestAI, or any business API. Conversely, bot runtime credentials do not grant package-download access.

Copy the generated .env.example to .env for local work. In production, inject the same named values from a secret manager. Never put either credential class in source, TOML, a production lock, a frontend bundle, or a prompt.

Create an application¶

Run the private Starter from GAR. --no-cache and the exact version select the reviewed 0.2.1rc19 artifact:

UV_KEYRING_PROVIDER=subprocess uvx --no-cache \
  --default-index "https://oauth2accesstoken@asia-south1-python.pkg.dev/birla-loyalty-voice-bot/vaani-python/simple/" \
  --from "create-vaani-app==0.2.1rc19" \
  create-vaani-app my-voicebot

The generated backend/pyproject.toml and backend/uv.lock pin vaani[cartesia,deepgram,elevenlabs,google,noise-cancellation,openrouter,sarvam,silero,smallestai] 1.0.0rc43 to the same private registry. The lock records the approved wheel SHA-256, and uv sync --locked enforces that artifact identity. Setup then verifies the installed version and module location. Its optional local-wheel path also requires and checks that exact digest. Keep those generated pins unchanged.

The generated application is deliberately business-neutral. It does not add employee references, milestone flows, or any other consumer-specific call fields. Add only the browser-safe fields your bot needs in backend/src/<package>/call_context.py; the frontend renders that backend schema automatically.

Continue in Run a browser voice call to add runtime credentials, understand the three generated scripts, and speak to the bot.

Birla production consumers¶

The Starter is intentionally generic: rc19 generates starter-default@1 and the matching starter-production@1 deployment/lock. It does not generate a Birla production configuration. A Birla consumer must use its own reviewed environment profile, production deployment, and production lock compiled for the same birla-prod-v42@14 preset. Do not change only profile in a generic Starter environment while retaining starter-production@1; the deployment and lock identities must match the selected preset.

VAANI rc43 exports the Birla source-default alias separately. Inspect the installed runtime and the consumer's selected production files together:

python - <<'PY'
from pathlib import Path
import tomllib

from vaani import BIRLA_PROD_V42

production = tomllib.loads(
    Path("backend/environments/production@1.toml").read_text()
)
print("BIRLA_PROD_V42:", BIRLA_PROD_V42.exact)
print("environment profile:", production["profile"])
print("production deployment:", production["production_deployment"])
print("production lock:", production["production_lock"])
PY

For a correctly prepared Birla consumer this prints the alias birla-prod-v42@14 and files whose deployment and lock both bind that same preset. The generic Starter output should continue to report starter-default@1; use a Birla consumer repository's reviewed files for production rather than mutating those generated files in place.

Install only the runtime¶

vaani==1.0.0rc43 is the current private release. Its source commit, uploaded hashes, and clean-install proof are recorded in release status:

uv venv --python 3.13
uv pip install \
  --python .venv/bin/python \
  --index "$UV_INDEX" \
  --default-index "https://pypi.org/simple" \
  --index-strategy first-index \
  --keyring-provider subprocess \
  "vaani[deepgram,google,recording-gcs,smallestai]==1.0.0rc43"

Add the extras required by the selected preset. For example, the published rc43 birla-prod-v42@14 preset requires recording-gcs, silero, and smallestai. The provider guide lists each built-in preset.

Confirm the correct package¶

.venv/bin/python - <<'PY'
from importlib.metadata import version
from pathlib import Path
import vaani

print("version:", version("vaani"))
print("module:", Path(vaani.__file__).resolve())
PY

The module must come from the intended virtual environment. Use release status when auditing a particular artifact's digest and provenance.

Next: run a browser voice call.