Metadata-Version: 2.4
Name: atomlabs
Version: 1.0.0
Summary: ATOM AI Governance SDK — pre-execution governance for every AI call
Home-page: https://github.com/qstackfield/atomlabs-sdk
Author: Atom Labs
Author-email: info@atomlabs.app
License: MIT
Project-URL: Homepage, https://atomlabs.app
Project-URL: Documentation, https://console.atomlabs.app/docs
Project-URL: Source, https://github.com/qstackfield/atomlabs-sdk
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
Classifier: Programming Language :: Python :: 3.8
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: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# atomlabs

Pre-execution AI governance for every model you use.

## Install

```bash
pip install git+https://github.com/qstackfield/atomlabs-sdk.git
```

Or for local development:

```bash
git clone https://github.com/qstackfield/atomlabs-sdk.git
cd atomlabs-sdk
pip install -e .
```

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 |

| `get_webhooks()` | List registered webhook endpoints |
| `create_webhook(url, events)` | Register a new webhook endpoint |
| `delete_webhook(webhook_id)` | Remove a webhook endpoint |
| `invite_user(email, role)` | Invite a team member (admin/developer/viewer/security_officer) |
| `list_users()` | List all team members for this tenant |

## Team Management

```python
# Invite a team member
client.invite_user("alice@company.com", role="developer")

# List current team
users = client.list_users()
for user in users:
    print(f"{user['email']} — {user['role']}")
```

Roles: `admin` · `developer` · `viewer` · `security_officer`

## Webhooks

```python
# Register a webhook endpoint
client.create_webhook(
    url="https://your-app.com/atom-webhooks",
    events=["governance.block", "governance.warn", "governance.allow"]
)

# List registered webhooks
hooks = client.get_webhooks()

# Delete a webhook
client.delete_webhook(hook_id)
```

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
