pipecat-ai-context-hub 0.2.0__tar.gz

pipecat_ai_context_hub-0.2.0/.claude/settings.json

@@ -0,0 +1 @@
+{ "attribution": { "commit": "", "pr": "" } }

pipecat_ai_context_hub-0.2.0/.env.example

@@ -0,0 +1,87 @@
+# Extra GitHub repos to ingest (comma-separated org/repo slugs).
+# These are appended to the default repos:
+#   pipecat-ai/pipecat, pipecat-ai/pipecat-examples, pipecat-ai/pipecat-flows,
+#   daily-co/daily-python, pipecat-ai/pipecat-client-web,
+#   pipecat-ai/pipecat-client-web-transports,
+#   pipecat-ai/pipecat-client-react-native-transports,
+#   pipecat-ai/voice-ui-kit, pipecat-ai/pipecat-prebuilt
+# PIPECAT_HUB_EXTRA_REPOS="your-org/repo-1,your-org/repo-2"
+#
+# NOTE: only Python (.py/.pyi), TypeScript (.ts/.tsx), and RST (docs/**.rst)
+# are parsed. Swift/Kotlin/C++ client SDKs (pipecat-client-ios,
+# pipecat-client-android, pipecat-client-cxx, pipecat-esp32) clone but yield
+# ZERO source/API chunks (only a few README/config fallback chunks) until a
+# grammar for those languages exists — they won't surface in search_api.
+# Entries below that duplicate a default are deduped automatically — harmless
+# to leave in.
+
+# --------------------------------------------------------------------------
+# Recommended extras — copy/uncomment what you need
+# --------------------------------------------------------------------------
+
+# Client SDKs & transports (web, mobile, native)
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/pipecat-client-web,pipecat-ai/pipecat-client-web-transports,pipecat-ai/pipecat-client-react-native-transports,pipecat-ai/pipecat-websocket-transport,pipecat-ai/pipecat-client-ios,pipecat-ai/pipecat-client-ios-daily,pipecat-ai/pipecat-client-ios-small-webrtc,pipecat-ai/pipecat-client-android,pipecat-ai/pipecat-client-android-transports,pipecat-ai/pipecat-client-cxx,pipecat-ai/pipecat-client-cxx-daily,pipecat-ai/pipecat-esp32"
+
+# UI components & voice UI kit
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/voice-ui-kit,pipecat-ai/pipecat-ui"
+
+# Conversation flows & structured dialogues
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/pipecat-flows,pipecat-ai/pipecat-flows-editor"
+
+# Cloud, CLI, and dev tools
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/pipecat-cli,pipecat-ai/tail,pipecat-ai/whisker,pipecat-ai/skills"
+
+# Quickstart templates
+# (pipecat-quickstart* repos are archived — use the CLI: `uv tool install pipecat-ai-cli` then `pipecat init quickstart`)
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/pipecat-prebuilt"
+
+# Audio, turn detection & benchmarks
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/smart-turn,pipecat-ai/hosted-smart-turn,pipecat-ai/pipecat-krisp,pipecat-ai/stt-benchmark,pipecat-ai/gb-benchmarks"
+
+# Example apps & demos
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/peekaboo,pipecat-ai/gemini-live-web-starter,pipecat-ai/instant-voice-demo,pipecat-ai/openai-realtime-todo-example,pipecat-ai/pipecat.ai-agents,pipecat-ai/pipecat-mcp-server"
+
+# Gradient Bang ecosystem
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/gradient-bang,pipecat-ai/gradient-bang-subagents,pipecat-ai/gradient-bang-synth-forge,pipecat-ai/gb-context-viewer"
+
+# NVIDIA integrations
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/nvidia-sgmaker"
+
+# iOS demo apps
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/pipecat-client-ios-gemini-live-websocket-demo,pipecat-ai/pipecat-client-ios-openai-realtime-webrtc-demo"
+
+# --------------------------------------------------------------------------
+# All recommended pipecat-ai repos in one line (copy and uncomment):
+# PIPECAT_HUB_EXTRA_REPOS="pipecat-ai/pipecat-client-web,pipecat-ai/pipecat-client-web-transports,pipecat-ai/pipecat-client-react-native-transports,pipecat-ai/pipecat-websocket-transport,pipecat-ai/pipecat-client-ios,pipecat-ai/pipecat-client-ios-daily,pipecat-ai/pipecat-client-ios-small-webrtc,pipecat-ai/pipecat-client-ios-gemini-live-websocket-demo,pipecat-ai/pipecat-client-ios-openai-realtime-webrtc-demo,pipecat-ai/pipecat-client-android,pipecat-ai/pipecat-client-android-transports,pipecat-ai/pipecat-client-cxx,pipecat-ai/pipecat-client-cxx-daily,pipecat-ai/pipecat-esp32,pipecat-ai/voice-ui-kit,pipecat-ai/pipecat-ui,pipecat-ai/pipecat-flows,pipecat-ai/pipecat-flows-editor,pipecat-ai/pipecat-cli,pipecat-ai/tail,pipecat-ai/whisker,pipecat-ai/skills,pipecat-ai/pipecat-prebuilt,pipecat-ai/smart-turn,pipecat-ai/hosted-smart-turn,pipecat-ai/pipecat-krisp,pipecat-ai/stt-benchmark,pipecat-ai/gb-benchmarks,pipecat-ai/peekaboo,pipecat-ai/gemini-live-web-starter,pipecat-ai/instant-voice-demo,pipecat-ai/openai-realtime-todo-example,pipecat-ai/pipecat.ai-agents,pipecat-ai/pipecat-mcp-server,pipecat-ai/gradient-bang,pipecat-ai/gradient-bang-subagents,pipecat-ai/gradient-bang-synth-forge,pipecat-ai/gb-context-viewer,pipecat-ai/nvidia-sgmaker"
+# --------------------------------------------------------------------------
+
+# Entire repos to skip locally if an upstream source is tainted.
+# PIPECAT_HUB_TAINTED_REPOS="your-org/bad-repo,other-org/paused-repo"
+
+# Specific upstream refs to skip locally.
+# Format: org/repo@ref where ref is a tag or commit SHA/prefix.
+# PIPECAT_HUB_TAINTED_REFS="pipecat-ai/pipecat@v0.0.9,pipecat-ai/pipecat-examples@deadbeef"
+
+# --------------------------------------------------------------------------
+# Startup model pre-warm (default: on)
+# --------------------------------------------------------------------------
+# On `serve` boot, the hub loads the embedding model (and cross-encoder if
+# enabled) so the first MCP query doesn't pay a cold-start cost. On Windows
+# CPU this can otherwise hang the first query for 30-130s — longer than
+# Claude Code's tool-permission window, which surfaces as a spurious
+# disconnect.
+#
+# Set to 0 to skip pre-warm (faster boot, slower first query):
+# PIPECAT_HUB_WARMUP=0
+
+# --------------------------------------------------------------------------
+# Index-staleness footer (default: 7 days)
+# --------------------------------------------------------------------------
+# When the local index is older than this many days, every tool response (MCP
+# and the CLI subcommands) carries an `index_staleness` field nudging you to
+# run `refresh`. The field is absent while the index is fresh.
+#
+# Set to 0 (or any value <= 0) to disable the footer entirely. Non-numeric or
+# non-finite values (e.g. inf, nan) are rejected with a warning and fall back
+# to the 7-day default.
+# PIPECAT_HUB_STALE_AFTER_DAYS=7

pipecat_ai_context_hub-0.2.0/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,42 @@
+name: Bug Report
+description: Report a crash, error, or unexpected behavior
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Describe the bug and how to reproduce it.
+      placeholder: |
+        1. Ran `pipecat-context-hub refresh --force`
+        2. Got error: "ChromaDB collection not found"
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: |
+        Run this in your terminal and paste the output:
+        ```
+        echo "Python: $(python3 --version)" && echo "uv: $(uv --version)" && echo "OS: $(uname -srm)" && uv run pipecat-context-hub --version 2>/dev/null || echo "version: unknown"
+        ```
+      render: text
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / error output
+      description: Paste any relevant error messages or stack traces.
+      render: text

pipecat_ai_context_hub-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Pipecat Community
+    url: https://discord.gg/pipecat
+    about: Ask questions and get help from the Pipecat community

pipecat_ai_context_hub-0.2.0/.github/ISSUE_TEMPLATE/retrieval-quality.yml

@@ -0,0 +1,140 @@
+name: Retrieval Quality Issue
+description: Report missing, irrelevant, or poorly ranked results from the MCP server
+labels: ["retrieval-quality"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Before filing
+
+        Run the diagnostic prompt below in your coding agent (Claude Code, Cursor, etc.)
+        to generate a structured report. Paste the output in the **Diagnostic Report** field.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you search for, and what was wrong with the results?
+      placeholder: |
+        I searched for "WebSocket transport" using search_docs but got results
+        about HTTP transports instead. The actual WebSocket docs page wasn't
+        in the results at all.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+      description: What result or content should have been returned?
+      placeholder: |
+        I expected the docs page at /guides/learn/transports with the WebSocket
+        section to be the top result.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: issue-type
+    attributes:
+      label: Issue type
+      options:
+        - Missing result (expected content not returned)
+        - Wrong ranking (right content buried below irrelevant results)
+        - Bad chunking (result truncated or split at wrong boundary)
+        - Stale content (result is outdated, index not reflecting latest)
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: tool
+    attributes:
+      label: Which MCP tool?
+      options:
+        - search_docs
+        - search_examples
+        - search_api
+        - get_doc
+        - get_example
+        - get_code_snippet
+        - check_deprecation
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostic-report
+    attributes:
+      label: Diagnostic Report
+      description: |
+        Paste the output from the diagnostic prompt below. Copy the prompt into your
+        coding agent, fill in YOUR_QUERY and YOUR_TOOL, and paste the full output here.
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostic-prompt
+    attributes:
+      label: Diagnostic Prompt (copy this into your agent)
+      description: Copy the prompt below, replace the placeholders, and run it in your coding agent.
+      render: markdown
+      value: |
+        ```
+        I'm diagnosing a retrieval quality issue with the pipecat-context-hub MCP server.
+        Run the following steps using the MCP tools and format the output as a single
+        markdown report I can paste into a GitHub issue.
+
+        ## Parameters
+        - Query: "YOUR_QUERY_HERE"
+        - Tool: YOUR_TOOL_HERE (search_docs | search_examples | search_api | get_code_snippet)
+        - Filters used: YOUR_FILTERS_HERE (e.g., area="guides", domain="backend", class_name="DailyTransport", or "none")
+        - Pipecat version (if applicable): YOUR_VERSION_HERE (e.g., "0.0.95" or "not set")
+
+        ## Steps
+
+        1. **Hub status** — call `get_hub_status` and report:
+           - server_version
+           - last_refresh_at
+           - total_records and counts_by_type
+           - framework_version (if set)
+
+        2. **Reproduce the search** — call the failing tool with the exact query and
+           filters above. For the results, report:
+           - Number of hits returned
+           - For each of the top 5 hits: score, title or chunk_id, snippet (first 100 chars),
+             match_type, version_compatibility (if present), citation.path
+           - The full evidence report: confidence, low_confidence, confidence_rationale,
+             next_retrieval_queries
+
+        3. **Broaden the search** — re-run the same query with all filters removed and
+           limit=20. Report:
+           - Did the expected result appear? At what rank and score?
+           - If yes, which filter excluded it?
+           - If no, proceed to step 4.
+
+        4. **Check if content is indexed** — if the expected result is a doc page, try
+           `get_doc(path="EXPECTED_PATH")`. If it's an API symbol, try
+           `search_api(query="SYMBOL_NAME", limit=5)`. If it's an example, try
+           `search_examples(query="EXAMPLE_NAME", limit=5)`. Report:
+           - Was the content found by direct lookup?
+           - If found: what was its chunk_id, content_type, and metadata?
+           - If not found: the content is likely not indexed.
+
+        5. **Try alternative queries** — run 2-3 rephrased queries or multi-concept
+           queries (using ` + ` syntax) against the same tool. Report:
+           - Each query tried and the top 3 results (score, title/chunk_id)
+           - Did any alternative surface the expected result?
+
+        ## Output format
+
+        Format everything as a single markdown block with these sections:
+        - **Hub Status**: table of status fields
+        - **Original Query Results**: numbered list of top 5 hits with scores
+        - **Evidence Report**: confidence, rationale, and next queries
+        - **Broadened Search**: whether expected result appeared and at what rank
+        - **Direct Lookup**: whether content exists in the index
+        - **Alternative Queries**: table of queries tried and top results
+        - **Diagnosis**: your assessment of why the result is missing or poorly ranked
+          (e.g., "content not indexed", "filter too narrow", "embedding mismatch",
+          "chunking split the relevant content", "staleness penalty")
+        ```

pipecat_ai_context_hub-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,181 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - "chore/**"
+      - "feature/**"
+      - "bug/**"
+      - "refactor/**"
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Floor (3.12) + ceiling (3.14, the highest version requires-python allows).
+        python-version: ["3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7.6.0
+        with:
+          version: "0.9.18"
+
+      - name: Sync dependencies
+        run: uv sync --frozen --extra dev --group dev
+
+      - name: Ruff
+        run: uv run ruff check src/ tests/
+
+      - name: Mypy
+        run: uv run mypy src/ tests/
+
+      - name: Pytest
+        run: uv run pytest tests/ -v
+
+  # Stable required-status-check name. Branch protection requires "Quality";
+  # the matrix above reports per-leg names ("Quality (py3.12)", …), so this
+  # gate aggregates them under the single name protection expects. Bump the
+  # matrix without touching branch-protection settings.
+  quality-gate:
+    name: Quality
+    runs-on: ubuntu-latest
+    needs: [quality]
+    if: always()
+    steps:
+      - name: Require all Quality matrix legs to pass
+        env:
+          RESULT: ${{ needs.quality.result }}
+        run: |
+          echo "Quality matrix aggregate result: $RESULT"
+          test "$RESULT" = "success"
+
+  windows-smoke:
+    name: Windows smoke (chromadb 1.x, py${{ matrix.python-version }})
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.14 proves the cp314 compiled stack (torch/onnxruntime/tokenizers)
+        # installs and the chromadb 1.x index paths work on Windows — the platform
+        # where cp314 wheel availability was least certain.
+        python-version: ["3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7.6.0
+        with:
+          version: "0.9.18"
+
+      - name: Sync dependencies
+        # Proves chromadb 1.5.9 (and the rest of the stack) resolves and installs
+        # from wheels on Windows — the primary cross-platform risk of the 1.x bump.
+        run: uv sync --frozen --extra dev --group dev
+
+      - name: ChromaDB index smoke
+        # Scope: the chromadb 1.5.9 cross-platform risk surface plus the
+        # path-handling tests that previously assumed POSIX separators. `Sync
+        # dependencies` above already proved the wheel installs on Windows; the
+        # chromadb tests then build real ChromaDB 1.x indexes in temp dirs and
+        # exercise the upsert/query/get paths + Client.close lifecycle, the
+        # non-mutating format-detection probe (reads chroma.sqlite3), and
+        # metadata typing.
+        #
+        # test_taxonomy / test_github_ingest / test_cli / test_hub_status are now
+        # included: the ingest layer normalizes logical repo-relative paths to
+        # forward slashes via Path.as_posix() (github_ingest.py, taxonomy.py), so
+        # stored `path` / `source_url` / taxonomy keys are "/"-separated on every
+        # platform and these tests pass under Windows "\\". tests/integration/ is
+        # still excluded (its serve tests use POSIX-only select() on pipes);
+        # Linux CI runs everything.
+        run: >-
+          uv run pytest -v
+          tests/unit/test_index_store.py
+          tests/unit/test_format_detection.py
+          tests/unit/test_metadata_types.py
+          tests/unit/test_taxonomy.py
+          tests/unit/test_github_ingest.py
+          tests/unit/test_cli.py
+          tests/unit/test_hub_status.py
+
+  security:
+    name: Security
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7.6.0
+        with:
+          version: "0.9.18"
+
+      - name: Sync dependencies
+        run: uv sync --frozen --extra dev --group dev
+
+      - name: Dependency Audit
+        # KEEP IN SYNC with the `audit-deps` recipe in justfile — the local
+        # recipe must mirror this --ignore-vuln set exactly so `just audit-deps`
+        # passes iff this gate passes. Enforced by tests/unit/test_audit_sync.py
+        # (drift fails the suite).
+        #
+        # PYSEC-2026-139 (torch, CVE-2026-4538): local-only pt2-loader
+        # deserialization with no upstream fix released. Reached only via
+        # sentence-transformers; the hub never loads untrusted pt2 artifacts.
+        #
+        # CVE-2026-45829 (chromadb, GHSA-f4j7-r4q5-qw2c): pre-auth code injection
+        # in chromadb's HTTP SERVER mode — arbitrary code execution via the
+        # /api/v2/.../collections endpoint with a malicious model repo and
+        # trust_remote_code=true. Affects 1.0.0-1.5.9 with no fixed release yet
+        # (1.5.9 is the latest 1.x). Unreachable here: the hub runs the embedded
+        # PersistentClient only (no server, no HTTP endpoint, no listener) and
+        # never uses chromadb's embedding functions / trust_remote_code.
+        #
+        # CVE-2025-3000 (torch, GHSA-rrmf-rvhw-rf47 / PYSEC-2025-194): memory
+        # corruption in torch.jit.script. Low severity, local-only, and no
+        # upstream fix released (vulnerable range <= 2.12.0, no patched version).
+        # Unreachable here: the hub uses sentence-transformers embeddings and the
+        # cross-encoder reranker; it never calls torch.jit.script.
+        #
+        # The unfiltered biweekly security-audit.yml job re-surfaces all three so
+        # the ignores cannot silently outlive their upstream patches.
+        run: >-
+          uv run pip-audit --local --progress-spinner off
+          --ignore-vuln PYSEC-2026-139
+          --ignore-vuln CVE-2026-45829
+          --ignore-vuln CVE-2025-3000
+
+      - name: Bandit
+        run: uv run bandit -r src
+
+      - name: Generate SBOM
+        run: |
+          mkdir -p artifacts/security
+          uv run cyclonedx-py environment --output-reproducible --of JSON -o artifacts/security/sbom.json
+
+      - name: Upload SBOM
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom
+          path: artifacts/security/sbom.json

pipecat_ai_context_hub-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,169 @@
+name: Release
+
+# Publishes pipecat-context-hub to PyPI via trusted publishing (OIDC — no API
+# tokens stored in the repo).
+#
+# Two entry points:
+#   - Publishing a GitHub release (the normal path, see docs/CONTRIBUTING.md
+#     "Release Process") builds, verifies, and uploads to PyPI.
+#   - workflow_dispatch publishes to TestPyPI — a dry-run path for verifying
+#     the build and the trusted-publishing wiring without touching the real
+#     index.
+#
+# Naming: the PyPI distribution is `pipecat-ai-context-hub` (org convention —
+# official packages are pipecat-ai*); the command and MCP server name stay
+# `pipecat-context-hub`. A console-script alias makes
+# `uvx pipecat-ai-context-hub <cmd>` resolve.
+#
+# One-time setup: the project is published under the `pipecat` PyPI org
+# (https://pypi.org/org/pipecat/). A PyPI org owner adds a GitHub trusted
+# publisher — for the first release, as a "pending publisher" from the
+# `pipecat` org's "Publishing" settings (the project does not exist yet) — with
+#   owner: pipecat-ai (GitHub org), repository: pipecat-context-hub,
+#   workflow: release.yml, environment: pypi (testpypi on test.pypi.org),
+#   project name: pipecat-ai-context-hub.
+# See docs/CONTRIBUTING.md "Maintainer Setup" for the full flow.
+# Until that exists, the publish jobs fail with an OIDC error — the build job
+# still validates the artifacts.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# uv CLI version, single source of truth for all jobs below. Keep in sync with
+# the `astral-sh/setup-uv` version pinned in `.github/workflows/ci.yml`.
+env:
+  UV_VERSION: "0.9.18"
+
+jobs:
+  build:
+    name: Build & verify artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      # Pinned to 3.12 for a reproducible release build; the published sdist +
+      # wheel are version-agnostic. Update alongside the ci.yml matrix floor.
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check --strict dist/*
+
+      - name: Tag matches package version (release only)
+        # Guards the "forgot to bump pyproject before tagging" release: the
+        # tag vX.Y.Z must equal the version baked into the wheel. The
+        # _SERVER_VERSION half of the pair is enforced by the unit suite
+        # (tests/unit/test_server.py::TestVersionConsistency) in regular CI.
+        if: github.event_name == 'release'
+        # TAG is passed via env (not interpolated into the script body) so a
+        # crafted tag name cannot inject shell — see GitHub's workflow-injection
+        # guidance.
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          wheels=(dist/*.whl)
+          test "${#wheels[@]}" -eq 1 || {
+            echo "::error::expected exactly one wheel in dist/, found ${#wheels[@]}: ${wheels[*]}"
+            exit 1
+          }
+          WHEEL_VERSION=$(unzip -p "${wheels[0]}" '*.dist-info/METADATA' | awk '/^Version:/{print $2; exit}')
+          echo "wheel=$WHEEL_VERSION tag=$TAG"
+          test "v$WHEEL_VERSION" = "$TAG" || {
+            echo "::error::Tag $TAG does not match package version $WHEEL_VERSION — bump pyproject.toml and _SERVER_VERSION before tagging."
+            exit 1
+          }
+
+      - name: Wheel smoke test (clean venv, away from the repo)
+        # Installs the built wheel into a fresh venv and exercises it from a
+        # directory outside the checkout, so works-only-in-repo assumptions
+        # (missing package data, path expectations) fail here instead of on
+        # users. `serve` on an empty index must exit 2 with the refresh hint —
+        # proving the console script, imports, and config defaults all work
+        # from the wheel alone.
+        run: |
+          uv venv /tmp/wheel-smoke
+          VIRTUAL_ENV=/tmp/wheel-smoke uv pip install dist/*.whl
+          cd /tmp
+          /tmp/wheel-smoke/bin/pipecat-context-hub --help
+          set +e
+          PIPECAT_HUB_DATA_DIR=$(mktemp -d) /tmp/wheel-smoke/bin/pipecat-context-hub serve 2>/tmp/serve-err.txt
+          code=$?
+          set -e
+          cat /tmp/serve-err.txt
+          test "$code" -eq 2 || { echo "::error::expected exit 2 on empty index, got $code"; exit 1; }
+          grep -q "refresh" /tmp/serve-err.txt
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pipecat-ai-context-hub/
+    permissions:
+      # Trusted publishing: PyPI validates the workflow's OIDC token instead
+      # of an API key. Requires the trusted-publisher config described at the
+      # top of this file.
+      id-token: write
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        run: uv publish
+
+  publish-testpypi:
+    name: Publish to TestPyPI (dry run)
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/pipecat-ai-context-hub/
+    permissions:
+      id-token: write
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: ${{ env.UV_VERSION }}
+
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        # TestPyPI rejects re-uploads of an existing version; for repeat dry
+        # runs bump the version locally or accept the failure as "already
+        # validated".
+        run: uv publish --publish-url https://test.pypi.org/legacy/
+