Metadata-Version: 2.4
Name: auctra
Version: 0.3.4
Summary: Authority Protocol Python client — issue authority, execute actions, verify evidence
License-Expression: MIT
Project-URL: Homepage, https://auctra.tech/docs
Keywords: auctra,ai-agents,authority,delegation
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# auctra (Python SDK)

Stage 0/1 Python client — same Authority Protocol as `@auctra/sdk`.

Requires **Python 3.9+**.

```bash
pip install auctra==0.3.3
# local dev: pip install -e packages/python-sdk
```

## Quick start (with intent anchor)

Every governed action requires **`create_intent`** first, then pass the returned **`intent`** (id + `anchor_token`) on execute:

```python
from auctra import Auctra

client = Auctra(api_key="auctra_...", base_url="https://app.auctra.tech")

agent_id = "your-agent-uuid"
expires_at = "2027-01-01T00:00:00Z"

client.authority.issue(
    subject=agent_id,
    capabilities=["send_payment"],
    expires_at=expires_at,
    max_amount=500,
    max_lifetime_actions=100,
    max_lifetime_amount=10_000,
    currency="USD",
)

created = client.create_intent(
    title="Pay matched vendor invoices",
    intent_type="payment",
    risk_level="high",
    max_risk_level="critical",
    allowed_action_types=["send_payment"],
    expires_at=expires_at,
)
intent = created["intent"]

preview = client.action.evaluate(
    agent_id=agent_id,
    action_type="send_payment",
    payload={"amount": 50, "currency": "USD"},
    intent=intent,
)

decision = client.action.execute(
    agent_id=agent_id,
    action_type="send_payment",
    payload={"amount": 50, "currency": "USD", "target": "vendor:acme"},
    intent=intent,
    action={
        "target": "vendor:acme",
        "description": "Net-30 invoice payment",
        "risk_level": "medium",
    },
)

print(decision["decision"])
client.evidence.verify(payload=decision["evidence_payload"], evidence=decision["evidence"])
```

### New-client gotcha

Sending only `claimed_intent_id` (without `intent_anchor_token` or the `intent` object) returns **`require_approval`** (low) or **`blocked`** (medium+) with a reason about the missing anchor. Pass `intent=` from `create_intent`, or set both `claimed_intent_id` and `intent_anchor_token` explicitly. Missing intent entirely on medium+ is now **blocked**.

See [`docs/integrations/intent-anchors.md`](../../docs/integrations/intent-anchors.md).

## Threat-engine helpers (Engine 03 + 12)

**Lifetime budgets** — cap total actions or spend across the delegation lifetime:

```python
client.authority.issue(
    subject=agent_id,
    capabilities=["send_payment"],
    expires_at=expires_at,
    max_lifetime_actions=50,
    max_lifetime_amount=25_000,
    currency="USD",
)
```

**Untrusted tool/MCP outputs** — declare provenance on **medium+** / tool-sourced / RAG paths so responses cannot authorize the next action (Authority Gate blocks without `metadata.inputs`):

```python
from auctra import action_metadata_with_inputs, declare_tool_response_input

tool_input = declare_tool_response_input(
    tool_name="fetch_invoice",
    content_hash="sha256:…",
)

decision = client.action.execute(
    agent_id=agent_id,
    action_type="send_payment",
    payload={"amount": 50, "currency": "USD"},
    intent=intent,
    action={
        "target": "vendor:acme",
        "metadata": action_metadata_with_inputs(tool_input),
    },
)
```

Pass multiple inputs: `action_metadata_with_inputs(a, b)` or `{"inputs": [a, b]}` in `action["metadata"]`.

**Authority Gate responses** — evaluate/execute may include `gate_transcript` (defense-in-depth layers) and `threat_engines` on the JSON body, aligned with `@auctra/sdk@0.7.5`. See `docs/security/authority-gate.md`.

## Public surface

```text
declare_tool_response_input | action_metadata_with_inputs | InputProvenance
on_allowed | assert_authority_live
client.create_intent | list_intents
client.list_agents | create_agent | get_agent
client.list_api_keys
client.approve_action_request | reject_action_request
client.list_policies | create_policy | simulate_policy | publish_policy
client.get_authority_graph | get_authority_liveness | list_action_types | list_workload_identities
client.list_siem_endpoints | create_siem_endpoint | delete_siem_endpoint
client.list_incidents | open_incident | resolve_incident
client.list_compliance_packs | run_compliance_pack | list_compliance_runs
client.authority.issue | verify | delegate | revoke
client.action.evaluate | execute  (parent_action_id, execute_after)
client.get_action_request
client.evidence.verify
```
