claroshq 0.1.0

ClarosHQ Python SDK — provider-neutral AI observability and tracing client (OpenAI, Anthropic, LangChain adapters)

claroshq — ClarosHQ Python SDK

claroshq is the official Python SDK for the ClarosHQ AI observability and governance platform. The core client is provider-neutral and model-neutral; provider-specific instrumentations (OpenAI, Anthropic Claude, LangChain) are shipped as optional extras and normalize events into a generic ClarosHQ trace and span schema.

Installation

Install the pinned 0.1.0 release from production PyPI:

python -m pip install claroshq==0.1.0

ClarosHQ Sprint 2 (S2-019) gates the public release on a clean-machine install proof against the same hosted index that external customers use. Until that proof has been recorded against production PyPI, the command above is the intended install path — the production upload of 0.1.0 is performed by the Publish SDK workflow on a sdk/v0.1.0 tag push and is gated by Omar's release decision. See docs/sprint-2/s2-019-builder-package.md for the current status and the release-target decision.

Install from TestPyPI (staging only)

TestPyPI is the staging index — it is used for the final dry-run of upload, metadata rendering, and fresh-environment install before the package is promoted to production PyPI. TestPyPI does not mirror production PyPI, so the --extra-index-url https://pypi.org/simple/ flag is required to resolve claroshq's runtime dependency httpx>=0.27 and any transitive dependencies:

python -m pip install claroshq==0.1.0 \
    --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/

A successful install from TestPyPI is a useful staging milestone, but it does not satisfy the ClarosHQ Sprint 1 commercial-completion gate — production PyPI is the release target for that.

Optional provider adapters

Optional provider adapters can be installed via extras (use the same ==0.1.0 pin to keep your install reproducible until you intentionally move to a newer release):

python -m pip install "claroshq[anthropic]==0.1.0"
python -m pip install "claroshq[langchain]==0.1.0"
python -m pip install "claroshq[all]==0.1.0"         # anthropic + langchain + openai

Note: there is no dedicated openai extra — openai is bundled with claroshq[all]. If you only need the OpenAI adapter, install the OpenAI client directly alongside claroshq (e.g. pip install claroshq==0.1.0 openai).

Editable install (contributors)

If you are working inside the ClarosHQ platform monorepo, install the SDK in editable mode with the development extras:

python -m venv sdk/.venv
sdk/.venv/Scripts/python -m pip install -U pip          # Windows
# source sdk/.venv/bin/activate                         # macOS / Linux
sdk/.venv/Scripts/python -m pip install -e "./sdk[dev]"

The dev extra installs pytest, ruff, black, mypy, pre-commit, build, and twine — everything needed to develop, lint, test, build, and publish the package.

Verify the install

After installing, confirm the SDK loaded correctly and reports the expected version:

python -c "import claroshq; print(claroshq.__version__)"

This should print:

0.1.0

Quickstart

import claroshq

claroshq.init(
    api_key="YOUR_CLAROSHQ_INGEST_KEY",
    endpoint="https://ingest.claroshq.ai",
)

# Auto-instrument every supported provider that is importable in this process:
claroshq.instrument_all()

# ... your existing OpenAI / Anthropic / LangChain code runs unchanged ...

claroshq.flush()

See the main repository README for the full local development and backend setup.

License

Apache-2.0. See the project metadata in pyproject.toml.