tavus-cli 0.2.0__tar.gz → 0.3.1__tar.gz

{tavus_cli-0.2.0 → tavus_cli-0.3.1}/.github/workflows/deploy-cloudflare-worker.yml

@@ -12,20 +12,26 @@ on:
           - test
           - stg
           - prod
+  push:
+    branches:
+      - main
 
 permissions:
   contents: read
 
+concurrency:
+  group: deploy-tavus-mcp-worker-${{ github.event_name == 'workflow_dispatch' && inputs.environment || 'prod' }}
+  cancel-in-progress: true
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    environment: ${{ inputs.environment }}
+    # Manual dispatch picks the requested environment; merges to main deploy prod.
+    environment: ${{ github.event_name == 'workflow_dispatch' && inputs.environment || 'prod' }}
     env:
       CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
       CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-      CLOUDFLARE_ENV: ${{ inputs.environment }}
-      TAVUS_API_KEY: ${{ secrets.TAVUS_API_KEY }}
-      MCP_BEARER_TOKEN: ${{ secrets.MCP_BEARER_TOKEN }}
+      CLOUDFLARE_ENV: ${{ github.event_name == 'workflow_dispatch' && inputs.environment || 'prod' }}
     defaults:
       run:
         working-directory: workers/tavus-mcp
@@ -41,6 +47,17 @@ jobs:
           cache: npm
           cache-dependency-path: workers/tavus-mcp/package-lock.json
 
+      - name: Validate deployment secrets
+        run: |
+          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ]; then
+            echo "::error::Missing CLOUDFLARE_API_TOKEN GitHub secret for environment '$CLOUDFLARE_ENV'."
+            exit 1
+          fi
+          if [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
+            echo "::error::Missing CLOUDFLARE_ACCOUNT_ID GitHub secret for environment '$CLOUDFLARE_ENV'."
+            exit 1
+          fi
+
       - name: Install dependencies
         run: npm ci
 
@@ -50,19 +67,5 @@ jobs:
       - name: Test
         run: npm run test
 
-      - name: Configure legacy shared-token fallback secrets
-        run: |
-          if [ -n "${TAVUS_API_KEY:-}" ]; then
-            printf '%s' "$TAVUS_API_KEY" | npx wrangler secret put TAVUS_API_KEY --env "$CLOUDFLARE_ENV"
-          else
-            echo "Skipping TAVUS_API_KEY; OAuth user bearer tokens do not require the legacy fallback."
-          fi
-
-          if [ -n "${MCP_BEARER_TOKEN:-}" ]; then
-            printf '%s' "$MCP_BEARER_TOKEN" | npx wrangler secret put MCP_BEARER_TOKEN --env "$CLOUDFLARE_ENV"
-          else
-            echo "Skipping MCP_BEARER_TOKEN; OAuth user bearer tokens do not require the legacy fallback."
-          fi
-
       - name: Deploy Worker
         run: npx wrangler deploy --env "$CLOUDFLARE_ENV"

{tavus_cli-0.2.0 → tavus_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tavus-cli
-Version: 0.2.0
+Version: 0.3.1
 Summary: Tavus CLI and MCP server for agentic PAL creation and editing.
 Requires-Python: >=3.11
 Requires-Dist: fastmcp>=2.0.0
@@ -94,8 +94,29 @@ uv run tavus doctor
 uv run tavus pal list
 uv run tavus pal options <pal_id>
 uv run tavus pal patch <pal_id> --op replace --path /pal_name --value '"New Name"'
+uv run tavus pal capabilities list <pal_id>
+uv run tavus pal capabilities attach <pal_id> web_search
+uv run tavus pal capabilities attach <pal_id> slide_presenter --document-id <document_id> --slides-trigger walk_the_deck
+uv run tavus document create --url https://example.com/handbook.pdf --tag onboarding
+TAVUS_PORTAL_BEARER_TOKEN=<firebase-id-token> uv run tavus document upload ./handbook.pdf --tag onboarding
+uv run tavus pal knowledge add <pal_id> --document-id <document_id>
+TAVUS_PORTAL_BEARER_TOKEN=<firebase-id-token> uv run tavus pal knowledge upload <pal_id> ./handbook.pdf
 ```
 
+`pal capabilities` mirrors PAL Maker's built-in capability surface:
+Magic Canvas (`magic_canvas`), Slide Presenter (`slide_presenter`), Web Search
+(`web_search`), Perception (`perception`), and Memory (`memory`). The first,
+second, third, and fifth map to RQH PAL skills; Perception maps to
+`layers.perception`.
+
+`document` and `pal knowledge` mirror PAL Maker's Knowledge section. With a
+normal Tavus API key, create Knowledge documents from an already reachable URL
+via RQH `/v2/documents`. Local file upload uses the same portal-only flow as
+PAL Maker (local file -> tavus-api upload/S3 URL -> RQH document record), so it
+requires `TAVUS_PORTAL_BEARER_TOKEN`. PAL Knowledge attachment uses
+`document_ids` and `document_tags`; RAG tuning lives under
+`layers.knowledge_base`.
+
 ## MCP
 
 ```json
@@ -160,13 +181,19 @@ 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:
+For Tavus deployment, configure these GitHub environment secrets for each
+deployable environment (`test`, `stg`, `prod`):
 
 - `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`.
+Worker runtime secrets, such as the legacy `TAVUS_API_KEY` or
+`MCP_BEARER_TOKEN` fallback, should be set in Cloudflare with
+`wrangler secret put <NAME> --env <environment>`. They persist across deploys;
+the GitHub workflow does not read or overwrite them.
+
+Merges to `main` automatically run the `Deploy Tavus MCP Worker` workflow for
+`prod`. You can also run the workflow manually 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.

{tavus_cli-0.2.0 → tavus_cli-0.3.1}/README.md

@@ -74,8 +74,29 @@ uv run tavus doctor
 uv run tavus pal list
 uv run tavus pal options <pal_id>
 uv run tavus pal patch <pal_id> --op replace --path /pal_name --value '"New Name"'
+uv run tavus pal capabilities list <pal_id>
+uv run tavus pal capabilities attach <pal_id> web_search
+uv run tavus pal capabilities attach <pal_id> slide_presenter --document-id <document_id> --slides-trigger walk_the_deck
+uv run tavus document create --url https://example.com/handbook.pdf --tag onboarding
+TAVUS_PORTAL_BEARER_TOKEN=<firebase-id-token> uv run tavus document upload ./handbook.pdf --tag onboarding
+uv run tavus pal knowledge add <pal_id> --document-id <document_id>
+TAVUS_PORTAL_BEARER_TOKEN=<firebase-id-token> uv run tavus pal knowledge upload <pal_id> ./handbook.pdf
 ```
 
+`pal capabilities` mirrors PAL Maker's built-in capability surface:
+Magic Canvas (`magic_canvas`), Slide Presenter (`slide_presenter`), Web Search
+(`web_search`), Perception (`perception`), and Memory (`memory`). The first,
+second, third, and fifth map to RQH PAL skills; Perception maps to
+`layers.perception`.
+
+`document` and `pal knowledge` mirror PAL Maker's Knowledge section. With a
+normal Tavus API key, create Knowledge documents from an already reachable URL
+via RQH `/v2/documents`. Local file upload uses the same portal-only flow as
+PAL Maker (local file -> tavus-api upload/S3 URL -> RQH document record), so it
+requires `TAVUS_PORTAL_BEARER_TOKEN`. PAL Knowledge attachment uses
+`document_ids` and `document_tags`; RAG tuning lives under
+`layers.knowledge_base`.
+
 ## MCP
 
 ```json
@@ -140,13 +161,19 @@ 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:
+For Tavus deployment, configure these GitHub environment secrets for each
+deployable environment (`test`, `stg`, `prod`):
 
 - `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`.
+Worker runtime secrets, such as the legacy `TAVUS_API_KEY` or
+`MCP_BEARER_TOKEN` fallback, should be set in Cloudflare with
+`wrangler secret put <NAME> --env <environment>`. They persist across deploys;
+the GitHub workflow does not read or overwrite them.
+
+Merges to `main` automatically run the `Deploy Tavus MCP Worker` workflow for
+`prod`. You can also run the workflow manually 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.

tavus_cli-0.3.1/docs/usage-observability.md

@@ -0,0 +1,65 @@
+# MCP and CLI usage observability
+
+The Tavus CLI, local MCP server, and hosted MCP Worker identify their downstream
+Tavus API requests with a source-specific user agent:
+
+| Surface | User agent |
+| --- | --- |
+| CLI | `tavus-cli/<version>` |
+| Local MCP server | `tavus-mcp/<version>` |
+| Hosted MCP Worker | `tavus-mcp-worker/0.1.0` |
+
+They also send the matching low-cardinality `X-Tavus-Client-Source` header. The
+header is available for future structured attribution; the user agent works with
+request-handler's current access logging today.
+
+## SigNoz data path
+
+Request-handler already exports an access-log pair for each authenticated Tavus
+API request. Both records share an OpenTelemetry trace ID:
+
+- `log_request_data` records URL, method, request body, and the tagged user agent.
+- `after_request_logging` records route, HTTP status, auth type, and authenticated
+  `user_id`.
+
+In SigNoz, scope the logs to `service.name = request-handler` and
+`deployment.environment = prod`, select request records whose body contains one
+of the user-agent prefixes above, and join the response record on `trace_id`.
+
+That joined dataset supports the usage dashboard:
+
+| Question | Signal |
+| --- | --- |
+| How many people use it? | distinct authenticated `user_id`, split by surface |
+| How much is it used? | request count and requests per user over time |
+| How successful is it? | 2xx/3xx share versus 4xx/5xx share |
+| What query types run? | normalized HTTP method and Tavus API route |
+| How large are queries? | byte length of the logged request-body field |
+| Which errors occur? | response status distribution, split by route and surface |
+
+The existing [MCP Dashboard](https://tavus.us.signoz.cloud/dashboard/019affed-8fd9-756e-a889-d5da6157c976)
+only contains five legacy `mcp.*` latency panels. Those metrics had no matching
+data in the 30 days checked on July 31, 2026, and the dashboard does not currently
+measure adoption or CLI usage. Replace them with this production-only layout:
+
+- KPI row: API requests, unique users, success rate, and requests per user.
+- Hourly trends: requests and unique users, each split by CLI, local MCP, and
+  hosted MCP.
+- Tables: method plus normalized route family, request-body size percentiles,
+  and HTTP 4xx/5xx codes.
+
+The ClickHouse queries for that layout were dry-run against the current
+request-handler log schema. The final `tavus-*` filters are expected to return no
+historical rows until this source tagging is released.
+
+## Boundaries
+
+- Collection starts when this change is deployed/released; it does not recreate
+  reliable historical surface attribution.
+- Counts are downstream Tavus API requests, not top-level MCP tool calls or CLI
+  invocations. Local-only operations such as help, auth status, path listing, and
+  embed scaffolding do not generate an API request and are not counted.
+- No API key, prompt, or request body is added to telemetry by this change. The
+  source tags contain only the product surface and package version. Request-handler
+  continues applying its existing API-key truncation and 64 KiB body-redaction
+  policy.

{tavus_cli-0.2.0 → tavus_cli-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tavus-cli"
-version = "0.2.0"
+version = "0.3.1"
 description = "Tavus CLI and MCP server for agentic PAL creation and editing."
 readme = "README.md"
 requires-python = ">=3.11"

{tavus_cli-0.2.0 → tavus_cli-0.3.1}/skills/tavus-agentic-pals/SKILL.md

@@ -100,6 +100,26 @@ PAL tools:
 - `tavus_patch_pal(pal_id, ops)`
 - `tavus_describe_pal_options(pal_id)`
 - `tavus_pal_from_template(template, pal_name, business_context, default_face_id, layers)`
+- `tavus_skill_list()`
+- `tavus_pal_skills_list(pal_id)`
+- `tavus_pal_skill_attach|patch|detach(pal_id, skill_id, config?)`
+- `tavus_pal_capability_catalog()`
+- `tavus_pal_capabilities_list(pal_id)`
+- `tavus_pal_capability_attach|patch|detach(pal_id, capability_id, ...)`
+
+Knowledge document tools:
+
+- `tavus_document_list(limit?, page?, status?, tags?, participant_tags?, name_or_uuid?, verbose?)`
+- `tavus_document_get(document_id, verbose?)`
+- `tavus_document_create(document_url, document_name?, tags?, participant_tags?, crawl?, custom_description?, is_customer_support_document?, font_size_aware_extraction?)`
+- `tavus_document_upload(local_path, document_name?, tags?, participant_tags?, custom_description?, is_customer_support_document?, font_size_aware_extraction?, bucket_name?, region?, sign_duration?)` — requires `TAVUS_PORTAL_BEARER_TOKEN`; with only a Tavus API key, use `tavus_document_create` with a public/presigned URL
+- `tavus_document_tags(search?, page?, limit?)`
+- `tavus_document_chunks(document_id, collection?, limit?, offset?)`
+- `tavus_document_recrawl(document_id, crawl?)`
+- `tavus_pal_knowledge_list(pal_id)`
+- `tavus_pal_knowledge_add|remove|replace(pal_id, document_ids?, document_tags?)`
+- `tavus_pal_knowledge_settings_patch(pal_id, rag_score_threshold?, rag_n_chunks?, rag_surrounding_chunk_radius?, enable_rag_observability_app_messages?, use_procedure_goalchain?)`
+- `tavus_pal_knowledge_upload(pal_id, local_path, ...)` — upload a local file and attach it to the PAL by default; requires `TAVUS_PORTAL_BEARER_TOKEN`
 
 Conversation and resource tools:
 
@@ -107,7 +127,7 @@ Conversation and resource tools:
 - `tavus_conversation_create(pal_id, face_id, conversation_name)`
 - `tavus_conversation_end(conversation_id)`
 - `tavus_quickstart(system_prompt, pal_name, face_id)`
-- `tavus_resource_list(resource, limit)` for `guardrails`, `objectives`, `documents`, `voices`, or `tools`
+- `tavus_resource_list(resource, limit)` for `guardrails`, `objectives`, `documents`, `voices`, `skills`, or `tools`
 - `tavus_scaffold_embed(conversation_url, target, component_name)`
 
 `tavus_scaffold_embed` returns a file manifest. The MCP host agent writes files if the user wants files created.
@@ -138,6 +158,23 @@ Autonomous build + verify (one call drives the full loop):
 
 Before patching an existing pal, call `tavus_describe_pal_options` or `tavus pal options`. Use its `available` resources and `schemas.patchable_paths` output to choose valid IDs and patch paths.
 
+For PAL Maker capabilities, prefer `tavus_pal_capability_*` or
+`uv run tavus pal capabilities ...` over raw JSON Patch. Supported capability
+ids are `magic_canvas`, `slide_presenter`, `web_search`, `perception`, and
+`memory` (also accepts the portal ids `builtin:magic_canvas`,
+`builtin:slide_presenter`, `builtin:web_search`, and `skill:memory`). Magic
+Canvas, Slide Presenter, Web Search, and Memory persist through
+`/pals/{id}/skills`; Perception persists through `/layers/perception`.
+
+For PAL Knowledge, prefer `tavus_pal_knowledge_*` or
+`uv run tavus pal knowledge ...` over raw JSON Patch. The Knowledge section is
+`document_ids` plus `document_tags`, and RAG tuning lives under
+`layers.knowledge_base`. Use `tavus_document_chunks` before making content
+claims about an uploaded document; it reads the text RQH actually indexed.
+The Tavus API-key path creates documents from an already reachable URL. Local
+file upload goes through the developer-portal upload endpoint and needs a
+Firebase portal bearer token in `TAVUS_PORTAL_BEARER_TOKEN`.
+
 Prefer focused patches over full rebuilds:
 
 ```json

{tavus_cli-0.2.0 → tavus_cli-0.3.1}/src/tavus_mcp/__init__.py

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