Chaos Cypher v0.7.2: Chat Searches by Tag, Plus Headers for OpenAI-Compatible Proxies

Chaos Cypher v0.7.2 is out. It is a small release with two features. The chat assistant can now search by tag, under the same rule the MCP tools follow. The OpenAI provider can send extra HTTP headers, so an OpenAI-compatible proxy can route requests on them.

What you'll learn

• How the chat assistant uses tags, and why a tag it picks can only narrow a search
• One behavior change: a chat scoped to tags that match nothing is now refused
• How to send extra headers to an OpenAI-compatible proxy
• How to upgrade

Chat can search by tag

v0.7.0 added document tags and let MCP clients, the CLI and the API search inside a tag set. In 0.7.2 the chat assistant gets the same option. Its two search tools, GraphRAG Search and Semantic Search, now take tags and match (any or all), with the same descriptions as the MCP tools, and the chat prompt tells the model they exist. Ask "what do my harbour notes say about the lantern?" and the assistant can search only the documents carrying that tag.

A tag the assistant picks only ever narrows the search:

• No chat scope: the search covers only the documents carrying the tags. GraphRAG Search then takes its graph only from those documents, as the MCP tool does.
• A scoped chat (chat --tag, tag_ids or source_ids): the search covers the documents that are in the chat's scope and carry the tags. The chat's scope always applies, so a tag can never bring in a document from outside it.
• No match: if no document in reach carries the tags, the search returns nothing. It never falls back to searching everything.

A tag name the tag rule refuses comes back to the model as a tool error it can read. The details are in Chat — Tags the Assistant Picks.

In plain terms: you can ask the assistant about one tagged set of documents, and its searches stay inside that set.

Behavior change: a tag scope that matches nothing is refused

Before 0.7.2, creating a chat or changing its scope (POST /api/v1/chats, PATCH /api/v1/chats/{id}/scope) with tag_ids that carried no document, and no source_ids, gave you a chat that searched every document. It is now refused with a 400 error naming the problem, as chaoscypher chat --tag already refused. A refused re-scope keeps the chat's current scope. See Chat — Combining Scopes.

In plain terms: an empty tag scope used to mean "everything", and now it is an error you can see.

Extra headers for the OpenAI provider

If you point the OpenAI provider at an OpenAI-compatible proxy, the proxy may need a header to decide where a request goes, for example to keep it on a local model. The new setting llm.openai_default_headers sends extra HTTP headers with every OpenAI chat, extraction and import-summary request:

llm:
  openai_default_headers:
    X-Example-Route: local

From the environment, give it as a JSON object:

CHAOSCYPHER_LLM__OPENAI_DEFAULT_HEADERS='{"X-Example-Route": "local"}'

Empty, the default, sends nothing. Header values are masked like API keys in the Settings page, chaoscypher config show and the diagnostic bundle, and they are never logged. Names must be plain HTTP tokens with no line breaks, and Authorization is refused because the client sends it from the API key. OpenAI embeddings are configured separately and do not get these headers. See Configuration — OpenAI.

In plain terms: you can route Chaos Cypher's OpenAI calls through your own proxy, and the header values are treated as secrets.

Dependencies

The Docker images build on Python 3.14.9 (was 3.14.8). The web interface's build tools clear three advisories: minimatch, glob and the docs site's serialize-javascript move to fixed releases. They run only when the interface and docs are built, never in a running server.

Upgrading

Before upgrading, let the queue go idle. Stop new submissions and wait until /api/v1/queue/stats reports 0 pending tasks on every queue, then swap the image. This release changes no queue payloads and adds no migrations. Draining first is still the safe default, because the worker cannot negotiate payload versions yet.

docker pull ghcr.io/chaoscypherinc/chaoscypher:latest
pip install -U chaoscypher-cli

The full notes are in the changelog.

Next steps

• New to Chaos Cypher? GraphRAG with Ollama in 10 Minutes runs the whole stack locally, so your documents and the graph built from them stay on your machine.
• Already tagging documents? Open a chat and ask about one tag. The assistant can search only the documents carrying it.