Metadata-Version: 2.4
Name: atomlabs
Version: 1.0.1
Summary: ATOM AI Governance SDK — pre-execution governance for every AI call
Home-page: https://atomlabs.app
Author: Atom Labs
Author-email: info@atomlabs.app
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# atomlabs

Pre-execution AI governance for every model you use.

## Install

```bash
# From a local checkout (editable)
pip install -e /path/to/lcac/sdk

# Or directly from git
pip install git+https://github.com/atomlabs/atom-sdk-python.git
```

Requires Python 3.8+ and `requests>=2.28.0`.

## Quick Start

```python
from atomlabs import ATOMClient, GovernanceBlockError

client = ATOMClient(
    api_key="lcac_your_key_here",
    tenant_id="your-tenant-id"
)

# Make a governed call
result = client.governed_call(
    "Analyze this customer complaint...",
    provider="groq"
)

if client.is_allowed(result):
    print(client.get_output(result))
    print(f"RIS Level: {client.get_ris_level(result)}")
    print(f"CII Score: {client.get_cii_score(result)}")

# Raise exception if blocked
try:
    output = client.governed_call_or_raise(
        "Your prompt here",
        provider="anthropic"
    )
except GovernanceBlockError as e:
    print(f"Blocked: {e.reason}")
    print(f"RIS: {e.ris_level}, CII: {e.cii}")
```

## Methods

| Method | Description |
|---|---|
| `governed_call()` | Make a governed AI call, returns full envelope |
| `governed_call_or_raise()` | Call or raise `GovernanceBlockError` on block |
| `is_allowed(result)` | Check if decision is allow |
| `is_blocked(result)` | Check if decision is block |
| `get_ris_level(result)` | Get RIS-0 through RIS-4 |
| `get_cii_score(result)` | Get CII float 0.0–1.0 |
| `get_output(result)` | Get model response text |
| `get_drift_score(result)` | Get semantic drift score |
| `get_traces()` | Get recent governance traces |
| `get_usage()` | Get tenant usage stats |
| `health()` | Check platform health |
| `create_agent()` | Create a governed agent |
| `list_agents()` | List tenant agents |
| `run_agent()` | Execute a governed agent run |
| `get_agent_policy()` | Read agent governance policy |
| `set_agent_policy()` | Update agent governance policy |

## Team Management

User management (invites, roles, listing) is handled via the console UI at
https://console.atomlabs.app or the HTTP API under `/api/tenants/{tenant_id}/users`.
Native SDK methods for team management will ship in a future release.

Roles available via the API: `admin` · `developer` · `viewer` · `security_officer`

## Webhooks

Webhook management (create, list, delete) is available via the HTTP API at
`/api/tenants/{tenant_id}/webhooks` and the console UI. Native Python SDK
methods will ship in a future release.

Payloads are signed with HMAC-SHA256. Verify the `X-ATOM-Signature` header.

## Local Models

```python
# Use a local GGUF model (zero data egress)
result = client.governed_call(
    "Your prompt",
    provider="local",
    model="llama-3.2-3b-instruct.Q4_K_M.gguf"
)
```

Local models run on your infrastructure. No data leaves your environment.

## Providers

`groq` · `anthropic` · `gemini` · `mistral` · `openai` · `local`

## CLI

```bash
# Health check
python -m atomlabs health --api-key lcac_... --tenant-id your-tenant

# Make a governed call
python -m atomlabs call --input "Your prompt" --provider groq \
  --api-key lcac_... --tenant-id your-tenant

# Or via environment variables
export ATOM_API_KEY=lcac_...
export ATOM_TENANT_ID=your-tenant
python -m atomlabs health
python -m atomlabs call --input "Your prompt"
python -m atomlabs traces --limit 10
python -m atomlabs agents
```

## Documentation

https://console.atomlabs.app/docs
