Metadata-Version: 2.4
Name: claroshq
Version: 0.1.0
Summary: ClarosHQ Python SDK — provider-neutral AI observability and tracing client (OpenAI, Anthropic, LangChain adapters)
Project-URL: Homepage, https://github.com/claroshqai/platform
Project-URL: Repository, https://github.com/claroshqai/platform
Project-URL: Issues, https://github.com/claroshqai/platform/issues
Project-URL: Documentation, https://github.com/claroshqai/platform/tree/main/sdk
Project-URL: Changelog, https://github.com/claroshqai/platform/releases
Project-URL: Source, https://github.com/claroshqai/platform/tree/main/sdk
Author-email: ClarosHQ <support@claroshq.ai>
Maintainer-email: ClarosHQ <support@claroshq.ai>
License-Expression: Apache-2.0
Keywords: ai,anthropic,claroshq,langchain,llm,monitoring,observability,openai,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: all
Requires-Dist: anthropic<1,>=0.34; extra == 'all'
Requires-Dist: langchain<1,>=0.2; extra == 'all'
Requires-Dist: openai<2,>=1; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic<1,>=0.34; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: black>=24; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: openai<2,>=1; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-mock>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain<1,>=0.2; extra == 'langchain'
Description-Content-Type: text/markdown

# claroshq — ClarosHQ Python SDK

[![PyPI version](https://img.shields.io/pypi/v/claroshq.svg)](https://pypi.org/project/claroshq/)
[![Python versions](https://img.shields.io/pypi/pyversions/claroshq.svg)](https://pypi.org/project/claroshq/)
[![License](https://img.shields.io/pypi/l/claroshq.svg)](https://github.com/claroshqai/platform/blob/main/sdk/pyproject.toml)

`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:

```bash
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](../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:

```bash
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):

```bash
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](https://github.com/claroshqai/platform),
install the SDK in editable mode with the development extras:

```bash
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:

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

This should print:

```text
0.1.0
```

## Quickstart

```python
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](https://github.com/claroshqai/platform#readme)
for the full local development and backend setup.

## License

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