Metadata-Version: 2.4
Name: arbiter-sdk
Version: 0.1.1
Summary: Official Python SDK for the Arbiter Control Plane for AI Agents
Project-URL: Homepage, https://arbitertrust.com
Project-URL: Repository, https://github.com/sumitbirru1-halo/arbiter-sdk
Author: Arbiter
License-Expression: ISC
Keywords: ai-agents,arbiter,control-plane,policy-engine,runtime-evaluation,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Arbiter Python SDK

Official Python client for the Arbiter Control Plane. Same governance semantics as
`@arbiterhq/sdk` (Node): **evaluate → allow | hold | deny**.

**Package:** `arbiter-sdk==0.1.1`  
**Import:** `from arbiter import ArbiterRuntime`

## Install

```bash
pip install arbiter-sdk==0.1.1
```

Authority Connect (`arbiter connect --apply`) installs the public pin configured in the CLI
(currently `arbiter-sdk==0.1.0` or newer compatible pins) into Python projects after confirmation.
When you are developing inside the Arbiter monorepo, Connect may use an on-disk editable
path instead.

### Development / contributor only

```bash
pip install -e packages/python
# or:
export ARBITER_PYTHON_SDK_PIP_SPEC=/path/to/arbiter_sdk-0.1.1-py3-none-any.whl
```

Do not use the editable monorepo path as the customer install instruction.

## Environment variables

| Variable | Purpose |
|---|---|
| `ARBITER_API_KEY` | Workspace API key (`arb_test_*`) or agent credential (`arb_agent_*`) |
| `ARBITER_BASE_URL` | Control Plane base URL (default `https://api.arbitertrust.com`) |
| `ARBITER_AGENT` | Required for workspace API keys; stable agent external id for Discovery |

You can also pass `api_key`/`credential`, `base_url`, and `agent` to `ArbiterRuntime(...)`.

## Quick start

```python
from arbiter import ArbiterRuntime

runtime = ArbiterRuntime()  # reads ARBITER_API_KEY / ARBITER_BASE_URL / ARBITER_AGENT
runtime.connect(framework="custom", runtimeType="python")

result = runtime.evaluate("send_payment", amount=100)

if result.decision == "allow":
    ...
elif result.decision == "deny":
    ...
elif result.decision == "hold":
    # Approval HOLD includes approval_request_id for Dashboard / Authorizations Approve.
    # API keys cannot approve. This package does not expose completeHeldEvaluation;
    # Node SDK and Authority Gate can complete held evaluations in-process.
    # Discovery HOLD requires a human to Adopt the agent, then retry evaluate.
    ...
```

## Governance boundaries

Arbiter governs agents. It does not replace human security decisions:

- Discovery observes runtimes. **Humans Adopt** agents before enforcement begins.
- Approval HOLD pauses side effects. **Humans Approve** (or deny) in the Dashboard.
- Connect and this SDK never auto-Adopt Discovery resources.
- Connect and this SDK never auto-Approve HOLD decisions.
- API keys cannot approve; approval requires a human session.

Normal lifecycle:

```
connect / observe → Adopt (human) → evaluate → allow | hold | deny
                              hold (approval) → Approve (human) → continue
```

## API surface

| Symbol | Purpose |
|---|---|
| `ArbiterRuntime` | Client: `api_key`/`credential`, `agent`, `base_url`, `connect()`, `evaluate()` |
| `evaluate(...)` | `POST /evaluate` → normalized decision models |
| `AllowEvaluateResult` / `DenyEvaluateResult` / hold variants | Decision shapes |
| `ArbiterError` / `ArbiterTimeoutError` / `ArbiterConfigError` | Deterministic errors |
| `normalize_evaluate_result` | Raw JSON → typed result |

## Companion packages

| Package | Version |
|---|---|
| `@arbiterhq/cli` | `0.3.0` |
| `@arbiterhq/sdk` | `0.3.5` (docs/version identity; companion CLI `0.3.0`) |
| `@arbiterhq/gate` | `0.1.0` |
