tavus-cli 0.1.0__py3-none-any.whl

tavus_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: tavus-cli
+Version: 0.1.0
+Summary: Tavus CLI and MCP server for agentic persona creation and editing.
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonpatch>=1.33
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tavus-cli
+
+Agent-facing surfaces that let another agent (Claude, Codex, or any MCP-aware client) drive Tavus persona creation end-to-end — separate from the human-facing Conversational Persona Builder.
+
+## What's here
+
+- **MCP server.** Persona CRUD plus mutations for tools, KB, guardrails, pronunciation dicts, layers, and objectives. Local stdio for IDE-embedded clients, remote (Cloudflare Worker) for hosted agents.
+- **CLI.** Scripted persona authoring + publish. `tavus persona list / options / patch`, JSON round-tripping, OS-keychain auth.
+- **Codex skill.** Publishable skill so an external agent can invoke the MCP server and CLI without reading the full Tavus API.
+
+## Why standalone (not under Conversational Persona Builder)
+
+The CPB project is the **human** builder — replica-driven, in-product. This repo is for **agents driving the API** without that UI. Adjacent in code and concepts, but a different deliverable and audience.
+
+## Out of scope (for now)
+
+- Replica/video preview surfaces (lives in CPB)
+- Marketplace / sharing UX
+- Multi-tenant auth beyond the existing dev-portal token model
+
+## Local Setup
+
+```bash
+uv sync --extra dev
+cp .env.example .env
+```
+
+By default the CLI targets production (`PROD`). To switch to the test DB, either set
+`TAVUS_ENV=TEST` in `.env` / your shell or pass `--env TEST` to the CLI. You can set
+`TAVUS_API_KEY` directly for automation or run:
+
+```bash
+uv run tavus auth login
+```
+
+Examples:
+
+```bash
+# Production defaults; only the API key is required.
+TAVUS_API_KEY=... uv run tavus persona list
+
+# Test DB without URL overrides.
+TAVUS_ENV=TEST TAVUS_API_KEY=... uv run tavus persona list
+uv run tavus --env TEST persona list
+```
+
+The login flow opens the dev-portal at `/dev/cli-authorize` with a loopback callback URL and an
+anti-CSRF state. The dev-portal mints an API key for your signed-in user (tagged `source: cli`) and
+POSTs it back to the loopback receiver. The CLI stores that key in the OS keychain under the
+selected environment. No Firebase config lives in the CLI — the browser side handles all of it.
+
+## CLI
+
+Install the CLI from PyPI:
+
+```bash
+uv tool install tavus-cli
+```
+
+Or run it without installing:
+
+```bash
+uvx --from tavus-cli tavus doctor
+```
+
+Local development commands:
+
+```bash
+uv run tavus doctor
+uv run tavus persona list
+uv run tavus persona options <persona_id>
+uv run tavus persona patch <persona_id> --op replace --path /persona_name --value '"New Name"'
+```
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "tavus": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/tavus-mcp", "tavus-mcp"]
+    }
+  }
+}
+```
+
+MCP tools return data and file manifests. They do not write files.
+
+## Cloudflare Worker
+
+The remote MCP server lives in `workers/tavus-mcp/` and uses Cloudflare's
+stateless `createMcpHandler` transport at `/mcp`.
+
+```bash
+cd workers/tavus-mcp
+npm install
+cp .dev.vars.example .dev.vars
+npm run dev
+```
+
+The local remote-MCP endpoint is `http://127.0.0.1:8787/mcp`.
+
+### Hosted remote MCP
+
+Hosted remote MCP clients should point directly at the HTTPS `/mcp` URL. Do not
+put a Tavus API key or shared bearer token in client config. The Worker exposes
+standard OAuth metadata, dynamic client registration, authorize, and token
+endpoints so MCP clients can authenticate through Tavus browser auth.
+
+Claude Code example:
+
+```bash
+claude mcp add -s user --transport http tavus https://mcp.tavus-preview.io/mcp
+```
+
+The OAuth authorize step redirects to Tavus developer portal
+`/dev/cli-authorize?mode=oauth`. After the user signs in, the portal mints a
+per-user Tavus API key and redirects back to the MCP client's loopback callback.
+The Worker exchanges that code for an MCP bearer token, then forwards the bearer
+to RQH as `x-api-key`. This keeps Tavus API keys user-scoped and out of MCP
+client configuration.
+
+Developer portal must support the `mode=oauth` authorize flow for remote MCP
+auth to complete. If a local portal is running on port 3000, test the full
+browser-auth path against TEST with:
+
+```bash
+cd workers/tavus-mcp
+npm run dev -- --env test --var TAVUS_DEV_PORTAL_URL:http://localhost:3000
+
+claude mcp add -s user --transport http tavus-dev http://127.0.0.1:8787/mcp
+```
+
+Keep the Worker environment aligned with the portal environment that minted the
+key. For example, a TEST key from a local or dev portal must hit a Worker running
+with `--env test`, otherwise downstream Tavus API calls will return 401.
+
+For Tavus deployment, configure these Cloudflare/GitHub environment secrets:
+
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_ACCOUNT_ID`
+- `TAVUS_API_KEY` and `MCP_BEARER_TOKEN` only if you need the legacy shared-token fallback
+
+Then run the `Deploy Tavus MCP Worker` workflow for `test`, `stg`, or `prod`.
+The `prod` Wrangler route is configured as a custom domain on `mcp.tavus.io`;
+use `https://mcp.tavus-preview.io/mcp` as the Cloudflare-owned endpoint until
+`mcp.tavus.io` DNS resolves.
+For direct Wrangler usage, the default config targets production; use
+`wrangler deploy --env test` or `wrangler dev --env test` to point at TEST.
+
+Useful production checks:
+
+```bash
+curl https://mcp.tavus-preview.io/.well-known/oauth-protected-resource/mcp
+curl https://mcp.tavus-preview.io/.well-known/oauth-authorization-server
+curl -i https://mcp.tavus-preview.io/mcp
+```
+
+Unauthenticated `/mcp` should return `401` with a `WWW-Authenticate` header that
+points at the protected-resource metadata URL. A `404 Not Found` at discovery
+usually means the Worker version serving the custom domain does not include the
+OAuth routes yet.
+
+## Codex Skill
+
+A publishable Codex skill for this repo lives at `skills/tavus-agentic-personas/`.
+It documents the CLI and MCP workflows, safe persona patching, environment setup,
+and concrete examples for agents using this toolkit.
+
+Install it by copying that folder into `${CODEX_HOME:-$HOME/.codex}/skills/`, or
+publish the folder directly through whatever skill distribution flow you use.

tavus_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+tavus_mcp/__init__.py,sha256=Bf7n7dPjnq7c9WlpNZLme3c42IvUZ9-bb-E_vgqA-7I,89
+tavus_mcp/server.py,sha256=an9P5iR-sj__HxUruUnTLvniP0qpTiZs8lt2vMOV5Kc,31264
+tavus_mcp/cli/__init__.py,sha256=CPUhfWHPc8tnymQrvJrZhmoe_KjBRLLKLtWTyMAEMnI,25
+tavus_mcp/cli/main.py,sha256=D8eACndt1a5A6X5wHY7V9mv_1vakUfv6rbiqGma2gvE,49021
+tavus_mcp/sdk/__init__.py,sha256=X9ok70MA8F-64iVlbJVmAlWdx7cfP0NgYYsCFFfGF5U,266
+tavus_mcp/sdk/env.py,sha256=zT8Szz-mJNmeViNcW9EUNJiFvGEP0L_f6l4YaaZ321k,3668
+tavus_mcp/sdk/errors.py,sha256=yLOU2TaXvCoce8JExfIKbNlFJtKqsL3qe53bwDJgt7g,1121
+tavus_mcp/sdk/patch.py,sha256=0aW1oKWGRJmm2wzUYjrn49fCJ4ipntKEnFneFtF02j8,2999
+tavus_mcp/sdk/auth/__init__.py,sha256=nTCHxup2HMZy3-uT53uaNWzK2uE1TY5lNPoYcSSlC_w,20
+tavus_mcp/sdk/auth/keyring_store.py,sha256=lNGVxHINa6Ehuq009VRNbLb1cZazc95i9yKNdzZnmMw,577
+tavus_mcp/sdk/auth/oauth.py,sha256=m_gcVP1Et5kmr2pqFw54__m9sufeyFbQN7sM0K2mDVI,4401
+tavus_mcp/sdk/auth/session.py,sha256=szXMvqbZ_PUb7f_WNq3wuOZfhC-JG1DwLK8tSN7FVDk,1316
+tavus_mcp/sdk/client/__init__.py,sha256=Gb6QAvnRcWqgH7TlXr7q0lq1AKqwBP6GL5PeiEev-i8,77
+tavus_mcp/sdk/client/http.py,sha256=zUK7bKCxjv4Ch9iZuNFUH9pOLeD2GObUEAWaDggIoHQ,17352
+tavus_mcp/sdk/recipes/__init__.py,sha256=W01VrBmZdZ5JHT9weSdDmddtOCXTw5pFyMm3sNiPKnE,350
+tavus_mcp/sdk/recipes/build_and_verify.py,sha256=-pW1ygLZ1UEkSbOkt2KwE_DXl9Lwdy4FzhOzG4o_o9M,22290
+tavus_mcp/sdk/recipes/options.py,sha256=EbR1Grp8gNoqtxC45LrC-mkogCPXHHDkXS9cHAMaEnQ,2365
+tavus_mcp/sdk/recipes/quickstart.py,sha256=aJBtjHDJAHp-BoMkhFAHp0epoL0LG8WC14LILNRnIiA,1604
+tavus_mcp/sdk/recipes/scaffold_embed.py,sha256=GXYNFul4yt5i_Z4JeP3cl6c9II19sYJGd94GeDZkK_c,3366
+tavus_mcp/sdk/recipes/templates.py,sha256=4G_aua4pw7bhef7JtByF2aiTJ_X0-P2BlN1l6EGx1io,2038
+tavus_mcp/sdk/recipes/tool_reuse.py,sha256=S-MIQOxwTYVve7G0wtuDv81EeqnXusExpzSb3bdXJEY,5047
+tavus_mcp/sdk/schemas/__init__.py,sha256=pbnhbdK1FDOlZbVRUuvcFeHFmGrLUXth92_i4ZewZ6I,354
+tavus_mcp/sdk/schemas/file_manifest.py,sha256=B8wf28z_6LWZAuVyVkSYo88-b1RxKP-idthBjZLVlQs,507
+tavus_mcp/sdk/schemas/guardrail.py,sha256=FecA71IaHSGNvPOZkDq_KZO20l81jiTFAqbFIhxiT1o,2932
+tavus_mcp/sdk/schemas/objective.py,sha256=WQ93RhYBD2EWy6HmYkGSy9Yf-ujvL97WSiIEGUGFF6k,5060
+tavus_mcp/sdk/schemas/persona.py,sha256=DYs2wUauvoH52FkNDArEIOF2LpAnlgG04sgsyauRQ1E,6048
+tavus_mcp/sdk/schemas/pronunciation.py,sha256=Ym_5hANzo_6VlFUGnmUVq6Bp1sggOg9AEIScAuj1lRA,2649
+tavus_mcp/sdk/schemas/tool.py,sha256=fC-GPwcPU-Dx1aBswE3ojHXAnOQajsRXyW13Mmak0v0,12546
+tavus_cli-0.1.0.dist-info/METADATA,sha256=gop-inPMlolxVLjvdF3iFe4U3aaCFKl436ESFwIMG0k,6612
+tavus_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tavus_cli-0.1.0.dist-info/entry_points.txt,sha256=nNdleVFT8Fgd60Nx3Ce8soJAbBnV7Hk6Hd0Jy3MEm_4,83
+tavus_cli-0.1.0.dist-info/RECORD,,

tavus_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tavus_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+tavus = tavus_mcp.cli.main:app
+tavus-mcp = tavus_mcp.server:main

tavus_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""Tavus CLI and MCP server package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

tavus_mcp/cli/__init__.py

@@ -0,0 +1 @@
+"""Typer CLI package."""