cq-sdk 0.15.0

Python SDK for cq — shared agent knowledge commons

cq-sdk

Python SDK for cq — the shared agent knowledge commons.

Lets any Python application query, propose, confirm, and flag knowledge units against a remote cq API, or store locally when no remote is configured.

Installation

uv add cq-sdk

Or with pip:

pip install cq-sdk

Quick Start

from cq import Client, FlagReason

cq = Client()  # Auto-discovers config; falls back to local-only.

# Query.
results = cq.query(domains=["api", "stripe"], language="python")

# Propose.
ku = cq.propose(
    summary="Stripe 402 means card_declined",
    detail="Check error.code, not error.type.",
    action="Handle card_declined explicitly.",
    domains=["api", "stripe"],
)

# Confirm / flag.
cq.confirm(ku.id)
cq.flag(ku.id, reason=FlagReason.STALE)

# Get the canonical agent prompts.
from cq import prompts

skill_prompt = prompts.skill()
reflect_prompt = prompts.reflect()

Configuration

The client reads configuration from environment variables:

Variable	Description	Default
CQ_ADDR	Remote cq API address	None (local-only)
CQ_API_KEY	API key	None
CQ_LOCAL_DB_PATH	Local SQLite path	~/.local/share/cq/local.db
CQ_LOCAL_DATABASE_URL	Local store connection URL (e.g. sqlite:///abs/path/local.db)	None (falls back to CQ_LOCAL_DB_PATH)

Or pass directly:

cq = Client(
    addr="http://localhost:3000",
    local_db_path=Path("~/.local/share/cq/local.db").expanduser(),
)

Custom storage

The local store is pluggable. By default the SDK opens a SQLite file at the path above; you can point it at a different backend or supply your own.

• By connection string. Set CQ_LOCAL_DATABASE_URL (for example sqlite:///abs/path/local.db); it takes precedence over CQ_LOCAL_DB_PATH. cq.create_store performs the same resolution programmatically.

• By injection. Pass any cq.Store to the store argument:

  from cq import Client, InMemoryStore
  
  client = Client(store=InMemoryStore())
  

• Bring your own. Implement the cq.Store protocol (get, all, insert, update, delete, query, stats, close) and inject it via store=. Reuse the shared ranker cq.rank_candidates from your query, and verify the implementation against the conformance suite in tests/conformance.py.

Selection precedence: store= > CQ_LOCAL_DATABASE_URL > local_db_path/CQ_LOCAL_DB_PATH > XDG default. A first-party PostgreSQL adapter is planned as the cq-sdk[postgres] extra; until then a postgresql:// URL raises NotImplementedError naming the install.

Knowledge tiers

Every knowledge unit has a tier: local (on-disk SQLite, never leaves the machine), private (stored on the remote API at CQ_ADDR, visible to every client pointing at the same remote), or public (open commons; not yet available).

With a remote configured, cq.propose(...) sends the unit to the remote and returns it tagged private; with no remote, or if the remote is unreachable, it writes the unit locally as local.

See the top-level README for the full description.

Dev Setup

uv sync --group dev

Testing

make test

Linting

make lint

License

Apache License 2.0