Metadata-Version: 2.4
Name: arqera
Version: 0.3.0
Summary: Python SDK for ARQERA -- AI governance as an API
Author-email: ARQERA <engineering@arqera.io>
License-Expression: Apache-2.0
Project-URL: Homepage, https://arqera.io
Project-URL: Documentation, https://docs.arqera.io/sdk/python
Project-URL: Repository, https://github.com/Arqera-IO/ARQERA
Project-URL: Issues, https://github.com/Arqera-IO/ARQERA/issues
Project-URL: Changelog, https://github.com/Arqera-IO/ARQERA/blob/main/sdk/python/CHANGELOG.md
Keywords: arqera,ai,governance,compliance,trust,evidence,audit,sdk,api,eu-ai-act
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: typing-extensions>=4.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"
Dynamic: license-file

# arqera

**Govern any AI action with one API call.**

The official Python SDK for [ARQERA](https://arqera.io) -- AI governance as an API. Evaluate actions against governance policies, query trust scores, and maintain a tamper-evident audit trail, all from Python.

## Installation

```bash
pip install arqera
```

**Requirements:** Python 3.9+. Zero required dependencies (uses only the standard library).

## Quick start

```python
from arqera import Arqera

client = Arqera(api_key="ak_live_...")

# Evaluate an action against governance policies
result = client.governance.evaluate(
    action="email.send",
    description="Send welcome email to new user",
)

print(result.verdict)     # "proceed", "review", or "deny"
print(result.confidence)  # 0.95
print(result.approved)    # True
```

## Governance evaluation

Every AI action -- sending an email, deleting data, deploying a model -- can be
evaluated against ARQERA's governance laws before execution:

```python
from arqera import Arqera, ArqeraError

client = Arqera(api_key="ak_live_...")

# Simple evaluation
result = client.governance.evaluate(action="data.export")

# With full context
result = client.governance.evaluate(
    action="model.deploy",
    description="Deploy sentiment model to production",
    context={
        "model_id": "sentiment-v3",
        "environment": "production",
        "user_role": "ml-engineer",
    },
)

if result.approved:
    deploy_model()
else:
    print(f"Blocked: {result.reasons}")
```

### Verdict object

The `evaluate()` method returns a `Verdict` with these fields:

| Field | Type | Description |
|-------|------|-------------|
| `verdict` | `str` | `"proceed"`, `"review"`, or `"deny"` |
| `action` | `str` | The action that was evaluated |
| `confidence` | `float` | Confidence score (0.0 -- 1.0) |
| `reasons` | `list[str]` | Reasons supporting the decision |
| `laws_evaluated` | `list[str]` | Which governance laws were checked |
| `approved` | `bool` | Shorthand for `verdict == "proceed"` |

## Trust scores

Query the trust score for your account:

```python
trust = client.governance.trust_score()
print(f"Overall: {trust.overall}")
print(f"Components: {trust.components}")
```

## Evidence trail

Search and export the tamper-evident audit trail:

```python
# Search recent evidence
artifacts = client.governance.search_evidence(
    artifact_type="governance_evaluation",
    start_date="2026-01-01",
    page_size=20,
)
for artifact in artifacts:
    print(f"{artifact.artifact_type}: {artifact.created_at}")

# Verify chain integrity
result = client.governance.verify_evidence(artifact_id=42)

# Export for compliance audit
export = client.governance.export_evidence(
    export_format="json",
    artifact_types=["governance_evaluation"],
)
```

## Error handling

```python
from arqera import Arqera, ArqeraError, RateLimitError, AuthenticationError

client = Arqera(api_key="ak_live_...")

try:
    result = client.governance.evaluate(action="email.send")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ArqeraError as e:
    print(f"API error ({e.status_code}): {e.message}")
```

### Exception hierarchy

| Exception | HTTP Status | When |
|-----------|-------------|------|
| `AuthenticationError` | 401 | Invalid or missing API key |
| `AuthorizationError` | 403 | Key lacks required permissions |
| `NotFoundError` | 404 | Resource does not exist |
| `ValidationError` | 422 | Invalid request payload |
| `RateLimitError` | 429 | Rate limit exceeded |
| `ServerError` | 5xx | ARQERA server error |
| `NetworkError` | -- | DNS, timeout, connection refused |
| `ArqeraError` | any | Base class for all SDK errors |

## Configuration

```python
client = Arqera(
    api_key="ak_live_...",                         # or set ARQERA_API_KEY env var
    base_url="https://api.arqera.com/api/v1",      # default
    timeout=30,                                     # seconds
    max_retries=2,                                  # retries on 429/5xx
)
```

The `api_key` parameter can be omitted if the `ARQERA_API_KEY` environment
variable is set:

```bash
export ARQERA_API_KEY="ak_live_..."
```

```python
client = Arqera()  # picks up ARQERA_API_KEY from env
```

## Links

- [Documentation](https://docs.arqera.io)
- [API Reference](https://docs.arqera.io/api)
- [Dashboard](https://app.arqera.io)
- [Changelog](https://github.com/arqera/arqera-python/blob/main/CHANGELOG.md)

## License

Apache 2.0. See [LICENSE](LICENSE) for details.
