Metadata-Version: 2.4
Name: sernixa
Version: 0.1.0
Summary: Sernixa Python SDK
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.0
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=0.80.0; extra == "crewai"
Provides-Extra: frameworks
Requires-Dist: langchain>=0.1.0; extra == "frameworks"
Requires-Dist: crewai>=0.80.0; extra == "frameworks"

# Sernixa Python SDK

Sernixa gates Python function execution through a deterministic approval engine. The backend decides whether an action is allowed, auto-approved, blocked, or pending human review; the SDK executes the wrapped business function locally only after an approved-style decision.

The SDK is intentionally small: it does not execute business logic in the
Sernixa backend, and it does not pretend to be a full agent framework. It gives
you low-friction interception points for plain Python, LangChain, CrewAI, and
MCP-style tool boundaries.

## Quickstart

```bash
pip install -e packages/sernixa
export SERNIXA_BASE_URL=http://localhost:8000
export SERNIXA_API_KEY="$YOUR_LOCAL_DEV_TOKEN"
```

```python
import sernixa

@sernixa.intercept(
    intent_id="customer-notes",
    risk_level="LOW",
    operation_class="read",
    data_sensitivity="internal",
    systems_touched=["postgres"],
    metadata={"ticket": "DEMO-1"},
)
def summarize_customer(customer_id: str) -> str:
    return f"summary for {customer_id}"

print(summarize_customer("cus_123"))
```

If Sernixa returns `approved`, `auto_approved`, or `executed`, the function runs locally. If it returns `pending_review`, the SDK polls until a terminal decision or timeout.

## Configuration

- `SERNIXA_BASE_URL`: Sernixa API URL. Defaults to `http://localhost:8000`.
- `SERNIXA_API_KEY`: bearer token for the API.
- `SERNIXA_POLL_INTERVAL_SECONDS`: approval poll interval. Defaults to `2`.
- `SERNIXA_POLL_TIMEOUT_SECONDS`: approval wait timeout. Defaults to `600`.
- `SERNIXA_TIMEOUT_SECONDS`: per-request HTTP timeout. Defaults to `10`.
- `SERNIXA_MAX_RETRIES`: retries for transient network errors, `429`, and `5xx`. Defaults to `2`.
- `SERNIXA_LOG_LEVEL`: optional SDK logger level such as `INFO` or `DEBUG`.
- `SERNIXA_DEBUG`: set to `true` for verbose SDK request/decision logging.

You can also configure a client directly:

```python
import os
from sernixa import Client

client = Client(
    base_url="http://localhost:8000",
    api_key=os.environ["SERNIXA_API_KEY"],
    poll_interval=1,
    poll_timeout=120,
    timeout_seconds=10,
    max_retries=2,
)
```

## Intercepting Functions

```python
@client.intercept(
    intent_id="billing-adjustment",
    risk_level="HIGH",
    operation_class="financial",
    data_sensitivity="financial",
    systems_touched=["stripe", "postgres"],
)
def adjust_invoice(invoice_id: str, amount_cents: int) -> None:
    ...
```

High and critical risk actions are never auto-approved by Sernixa. They remain pending review even when similar low-risk actions have a strong approval history.

## Async Functions

The same decorator works on coroutines:

```python
@client.intercept(
    intent_id="agent-read",
    risk_level="LOW",
    operation_class="read",
    data_sensitivity="internal",
    systems_touched=["vectordb"],
)
async def run_agent(query: str) -> str:
    return await agent.ainvoke(query)
```

## Decision Handling

```python
from sernixa import is_approved_status, is_terminal_status

assert is_approved_status("auto_approved")
assert is_terminal_status("rejected")
```

The SDK raises explicit exceptions for reviewer and policy outcomes:

```python
from sernixa.exceptions import (
    SernixaBlockedError,
    SernixaConfigurationError,
    SernixaExpiredError,
    SernixaRateLimitError,
    SernixaRejectedError,
    SernixaTimeoutError,
    SernixaValidationError,
)

try:
    adjust_invoice("inv_123", 1000)
except SernixaBlockedError as exc:
    print(f"Blocked by policy: {exc.reason}")
except SernixaRejectedError as exc:
    print(f"Rejected by reviewer: {exc.reason}")
except SernixaExpiredError:
    print("Approval expired before a reviewer decided.")
except SernixaTimeoutError:
    print("SDK timed out waiting for a decision.")
```

Configuration and payload mistakes fail before the business function runs:

- `SernixaConfigurationError`: invalid base URL, timeout, poll, or retry settings.
- `SernixaValidationError`: malformed action metadata such as an empty `intent_id`, invalid `risk_level`, or non-JSON metadata.
- `SernixaRateLimitError`: the backend kept returning `429` after retries.

## Extra Review Metadata

Use `metadata` for non-sensitive context that helps the approver understand the action:

```python
@sernixa.intercept(
    intent_id="support-note",
    risk_level="LOW",
    operation_class="update",
    data_sensitivity="internal",
    systems_touched=["postgres"],
    metadata={"change_ticket": "SUP-1842", "env": "local-demo"},
)
def write_support_note(...):
    ...
```

Core governance fields such as `risk_level` and `idempotency_key` cannot be overridden by extra metadata.

## V3 Delegation Context

For local multi-agent workflows, create a delegation token through Sernixa and
attach it while any delegatee agent runs protected tools:

```python
from sernixa import Client, delegation_scope, with_delegation

client = Client()
token = client.create_delegation_token(
    delegator_agent_id="orchestrator-agent",
    delegatee_agent_id="worker-agent",
    scope=delegation_scope(
        max_risk_level="low",
        allowed_operation_classes=["read"],
        allowed_data_sensitivities=["internal"],
        resources={"repo": ["sernixa"]},
    ),
    tool_subset=["view-details"],
)

with with_delegation(
    agent_id="worker-agent",
    token_id=token["token_id"],
    signing_secret=os.environ["SERNIXA_REQUEST_SIGNING_SECRET"],
    chain_id=token["chain_id"],
    runtime_id="local-worker-runtime",
    service_identity="spiffe://local/agent/worker-agent",
):
    view_details()
```

The SDK signs each delegated request with a canonical envelope, timestamp,
nonce, request body hash, key ID, and runtime identity metadata. Sernixa
verifies the request signature, replay status, token signature, hash chain,
expiry, delegatee identity, and scope before the existing approval logic runs.

## LangChain Adapter

Use the decorator when you control the tool function:

```python
from langchain.tools import tool
from sernixa.adapters import langchain_tool

@tool
@langchain_tool(
    intent_id="finance-tool",
    risk_level="HIGH",
    operation_class="financial",
    data_sensitivity="financial",
    systems_touched=["stripe"],
)
def transfer_funds_tool(amount_cents: int, destination_account: str) -> str:
    """Transfer funds after Sernixa approval."""
    ...
```

Use the object proxy when a tool object already exists:

```python
from sernixa.adapters import secure_langchain_tool

protected_tool = secure_langchain_tool(
    existing_tool,
    intent_id="customer-lookup",
    risk_level="LOW",
    operation_class="read",
    data_sensitivity="internal",
    systems_touched=["crm"],
)

result = protected_tool.invoke({"customer_id": "cus_123"})
```

Install LangChain separately if you use the adapter:

```bash
pip install "sernixa[langchain]"
```

The proxy guards `invoke`, `ainvoke`, `run`, `arun`, and direct calls where the
underlying tool exposes them. It forwards unknown attributes to the wrapped tool.

## CrewAI Adapter

Use the decorator for plain functions that become CrewAI tools:

```python
from sernixa.adapters import crewai_tool

@crewai_tool(
    intent_id="ticket-update",
    risk_level="HIGH",
    operation_class="update",
    data_sensitivity="internal",
    systems_touched=["ticketing"],
)
def update_ticket(ticket_id: str, note: str) -> str:
    return "updated"
```

Use the object proxy for existing CrewAI-style tool objects:

```python
from sernixa.adapters import secure_crewai_tool

protected_tool = secure_crewai_tool(
    existing_tool,
    intent_id="crew-ticket-update",
    risk_level="HIGH",
    operation_class="update",
    data_sensitivity="internal",
    systems_touched=["ticketing"],
)

protected_tool.run("SEC-1842")
```

Install CrewAI separately if you use CrewAI itself:

```bash
pip install "sernixa[crewai]"
```

The SDK proxy supports the common `run`, `_run`, and direct-call execution
shapes without requiring CrewAI as a hard dependency.

## MCP Boundary Helpers

Sernixa does not implement the full MCP protocol in this SDK. The real support
in this pass is an honest boundary wrapper for MCP-style tool dispatch:

```python
from sernixa.adapters import McpToolBoundary

boundary = McpToolBoundary(server_name="workspace-mcp", toolset_id="toolset-prod")

def read_file(path: str) -> str:
    return open(path).read()

result = boundary.invoke(
    tool_name="read_file",
    arguments={"path": "/workspace/report.md"},
    handler=read_file,
    intent_id="mcp-read-file",
    risk_level="LOW",
    operation_class="read",
    data_sensitivity="internal",
    client_name="local-agent-host",
)
```

Place this at the host/router boundary before dispatching a tool call to the
underlying MCP server/tool implementation. Planned next work is first-class MCP
server middleware and protocol-aware request/response adapters.

## State Model

- `executed`: Sernixa allowed the action and the SDK executed the local function.
- `auto_approved`: Sernixa policy allowed execution without human review.
- `pending_review`: the SDK is waiting for a reviewer and polling the approval.
- `rejected`: a reviewer denied the action; the SDK raises `SernixaRejectedError`.
- `blocked`: policy/security denied the action; the SDK raises `SernixaBlockedError`.
- `expired`: approval TTL elapsed; the SDK raises `SernixaExpiredError`.
- `failed`: backend replay/execution evidence failed; the SDK raises `SernixaError`.

## Troubleshooting

- `Action blocked`: inspect `exc.reason` and the approval/audit page. Dangerous primitives and invalid signatures fail closed.
- `SernixaValidationError`: fix empty IDs, invalid risk levels, empty `systems_touched`, or non-JSON metadata.
- `SernixaConfigurationError`: check `SERNIXA_BASE_URL`, timeout, poll, and retry values.
- `SernixaRateLimitError`: reduce agent concurrency or increase backend limits for the environment.
- `SernixaTimeoutError`: the approval is still pending after `SERNIXA_POLL_TIMEOUT_SECONDS`.
- Browser works but SDK fails: verify `SERNIXA_API_KEY` and that the backend URL is reachable from the Python process.

## Local And Hosted Configuration

Local demo:

```bash
export SERNIXA_BASE_URL=http://localhost:8000
export SERNIXA_API_KEY=e2e-admin
export SERNIXA_POLL_INTERVAL_SECONDS=1
```

Hosted or shared environment:

```bash
export SERNIXA_BASE_URL=https://sernixa.example.com
export SERNIXA_API_KEY="$SERNIXA_SERVICE_TOKEN"
export SERNIXA_TIMEOUT_SECONDS=10
export SERNIXA_MAX_RETRIES=2
```

Use real bearer tokens, HTTPS, shared nonce/rate-limit storage, and production
KMS/HSM signing before treating a hosted environment as production.

Current backend handoff note: local SDK examples target the demo API. A
production-like Sernixa backend must run with `AUTH_BYPASS=false`, real bearer
tokens, Redis-backed replay/rate-limit state, and a Postgres-backed audit store.
The present repo intentionally fails closed in `RUNTIME_MODE=production_like`
until that Postgres runtime store is implemented.

## Local Examples

- `examples/basic_auto_approval/`: local walkthrough showing low-risk, repeated approval memory, and high-risk pending behavior.
- `examples/multi_agent_delegation/`: generic orchestrator/worker delegation token flow.
- `examples/sernixa-sdk/`: lower-level sync, async, LangChain, CrewAI, MCP boundary, and compose smoke examples.
