Metadata-Version: 2.4
Name: openbox-sdk-python
Version: 1.0.0
Summary: OpenBox base SDK - governance contracts, strict gate, identity/signing, evaluate client, context runtime, OTel span wire serialization, and generic instrumentation shared by every OpenBox framework SDK
Author-email: OpenBox Team <tino@openbox.ai>
License-Expression: MIT
Keywords: governance,observability,openbox,opentelemetry,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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.11
Requires-Dist: cryptography<47,>=43
Requires-Dist: httpx<1,>=0.28.0
Requires-Dist: opentelemetry-api<1.40.0,>=1.38.0
Requires-Dist: opentelemetry-sdk<1.40.0,>=1.38.0
Provides-Extra: db
Requires-Dist: asyncpg>=0.29.0; extra == 'db'
Requires-Dist: opentelemetry-instrumentation-asyncpg<0.61b0,>=0.59b0; extra == 'db'
Requires-Dist: opentelemetry-instrumentation-dbapi<0.61b0,>=0.59b0; extra == 'db'
Requires-Dist: opentelemetry-instrumentation-redis<0.61b0,>=0.59b0; extra == 'db'
Requires-Dist: opentelemetry-instrumentation-sqlalchemy<0.61b0,>=0.59b0; extra == 'db'
Requires-Dist: pymongo>=4.6.0; extra == 'db'
Requires-Dist: redis>=5.0.0; extra == 'db'
Requires-Dist: sqlalchemy>=2.0.0; extra == 'db'
Requires-Dist: wrapt>=1.16.0; extra == 'db'
Provides-Extra: http
Requires-Dist: opentelemetry-instrumentation-httpx<0.61b0,>=0.59b0; extra == 'http'
Requires-Dist: opentelemetry-instrumentation-requests<0.61b0,>=0.59b0; extra == 'http'
Requires-Dist: opentelemetry-instrumentation-urllib3<0.61b0,>=0.59b0; extra == 'http'
Requires-Dist: opentelemetry-instrumentation-urllib<0.61b0,>=0.59b0; extra == 'http'
Requires-Dist: requests>=2.31.0; extra == 'http'
Description-Content-Type: text/markdown

# openbox-sdk-python

OpenBox base SDK (`import openbox_core`) — the standalone core every OpenBox
framework SDK builds on. It owns:

- **Contracts** — event and result dataclasses (`EventEnvelope`,
  `EvaluationResult`, `ApprovalResult`, `Verdict`).
- **Always-strict governance gate** — malformed event/runtime contracts raise
  `ContractError` before send; there are no configurable gate modes.
- **Identity & signing** — AIP DID validation + Ed25519 request signing,
  byte-compatible with the Temporal SDK signing contract.
- **Evaluate client** — sync + async calls to OpenBox Core
  (`/api/v1/governance/evaluate`, `/approval`, `/auth/validate`).
- **Context & runtime** — `ActivityContext`, `ContextStore`, trace
  correlation, `FrameworkAdapter` protocol, `OpenBoxRuntime`.
- **OTel span wire serialization** — OTel spans are the internal source of
  truth, projected to the current Core `SpanData` wire shape before send.
- **Generic instrumentation** — HTTP/DB/file/function wrappers with a
  started/completed hook runtime enforcing preflight before real operations.
- **Conformance kit** — reusable fixtures framework SDKs run to prove parity.

Framework SDKs (Temporal, LangGraph, LangChain, DeepAgent, CrewAI) are thin
adapters: they bind framework lifecycle into `ActivityContext`, emit lifecycle
events, and translate `EvaluationResult` into native behavior.

## Framework SDK integration

New framework SDK developers and agents should start with
[the OpenBox Python Framework SDK Integration guide](.github/instructions/openbox-sdk-python.instructions.md).
It describes how to build a framework SDK on top of this base package without
reimplementing config, signing, governance gates, hook wire payloads, or
conformance fixtures.

## Install

```bash
uv sync                 # core
uv sync --extra http    # + HTTP instrumentation targets
uv sync --extra db      # + DB instrumentation targets
```

## Import safety

`openbox_core.__init__` and all `openbox_core.contracts.*` modules import
without pulling in `httpx`, `cryptography`, `requests`, or OTel
instrumentation — safe for constrained framework paths such as the Temporal
workflow sandbox. `tests/test_import_safety.py` enforces this in CI.

## Development

```bash
uv sync --all-extras
uv run pytest
uv run ruff check .
```
