sernixa 0.1.0__tar.gz

sernixa-0.1.0/PKG-INFO

@@ -0,0 +1,378 @@
+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.