hub_status
Freshness check for a locally installed Pipecat Context Hub index.
The hub is a local index of Pipecat docs, examples, and API source that coding
agents query over MCP. When it goes stale, or was built against a different
pipecat-ai release than the project being worked on, an agent cites APIs
that have since changed — and nothing surfaces that until the generated code is
wrong. This module produces the one-line warning the CLI prints in that case.
The hub publishes its index_metadata table as a documented read contract
precisely so a check like this stays cheap: every in-process hub query opens
ChromaDB, so importing the package or shelling out to its status command
would cost far more than the command being run. Reading the SQLite table
directly is sub-millisecond and needs nothing outside the standard library.
Every function here answers “unknown” rather than raising. A freshness hint must never break the command a user actually asked for.
The contract carries a metadata_contract_version, and its docs tell consumers
to go silent on a value they don’t recognise. This module doesn’t: every question
it asks has the same harmless remedy — run refresh — and going quiet on every
hub bump would cost more than an occasionally stale hint. Each value is validated
on its own instead, so a key that is missing, renamed, or unparseable yields
silence whatever the contract number says.
- pipecat.cli.hub_status.read_hub_metadata() dict[str, str] | None[source]
Every key in the hub’s metadata table, or None when it can’t be read.
Opens read-only with no lock wait. The database is WAL, so this neither blocks nor is blocked by a concurrent refresh or a running MCP server, and sees only committed state.
- pipecat.cli.hub_status.index_is_built() bool[source]
Whether a completed index refresh exists on this machine.
The signal
pipecat initneeds before offering to build one: an index cannot exist unless someone ranrefresh, so having one means this has already been dealt with, here or in another project.
- pipecat.cli.hub_status.project_pipecat_version(cwd: Path | None = None) str | None[source]
The
pipecat-aiversion installed in the project’s virtualenv.Deliberately not
importlib.metadata.version: the CLI is normally a globaluv tool, so that would report the tool’s own version rather than the project’s. Only$VIRTUAL_ENVand./.venvare consulted — walking up parent directories would find an unrelated venv in a monorepo and warn about a project the user isn’t working on.Returns None when the framework is installed as an editable checkout: the developer is pipecat, and no released version meaningfully describes it.