# Kybernis Python SDK (beta)

This SDK lets multi-agent builders (LangGraph, CrewAI, LangChain) route tool calls through the Kybernis execution gate, emit execution spans, and report tool health/cost.

## Install (local dev)
- Add sdk/python to your PYTHONPATH or vendor the package into your app.
- Or set `KYB_SDK_PATH` to the absolute path of sdk/python.

## Minimal usage
- Set env: `KYB_API_BASE`, `KYB_API_KEY`, `KYB_TENANT_ID`, `KYB_RUN_ID`
- Enable SDK: `KYB_SDK_ON=1`

## Audit CLI
- Install the package and run `kybernis-audit templates`
- Quickstart a local manual audit recipe with `kybernis-audit quickstart --recipe mutation`
- Create a run with `kybernis-audit run --template-id DARE --source-run-id <run_id>`
- Replay a run with `kybernis-audit replay --audit-run-id <audit_run_id>`

The SDK provides:
- `KybernisClient` for tool registry, health, events, cost, and gate requests.
- `kyb_tool` decorator to gate tool calls before framework-level HITL.
- `install()` auto-patches requests/httpx to inject Kybernis headers.
- `derive_idempotency_key()` to match proxy idempotency hashing.
- `span()` helpers for non-HTTP execution spans.
- Side-effect helpers: `webhook()`, `email()`, `charge()`.

## SDK modes (A2A + proxy and A2A + MCP)
You can choose how the SDK routes governance and enforcement:

- **Proxy-first**: auto install HTTP patches + A2A lifecycle only.
- **MCP-first**: A2A lifecycle + MCP tools for governance.
- **Hybrid**: both proxy patches and MCP tools.

Python:
```python
from kybernis import KybernisSDK

sdk = KybernisSDK(agent, mode="hybrid", tool_map={"chat": "kyb.decide"})
```

Env:
```
KYB_SDK_MODE=hybrid
KYB_SDK_METHOD_TOOL_MAP={"chat":"kyb.decide"}
```

## Method interception controls
- `KYB_SDK_AUTO_INTERCEPT=1` wrap all public methods on the framework instance.
- `KYB_SDK_PROXY_MODE=1` return a proxy object that intercepts methods via `__getattr__`.
- `KYB_SDK_METHOD_ALLOWLIST=chat,run` only wrap these methods.
- `KYB_SDK_METHOD_BLOCKLIST=render,draw` skip these methods.

## Env flags
- `KYB_SDK_ON=1` enable SDK
- `KYB_API_BASE` control plane base URL
- `KYB_API_KEY` auth token (preferred)
- `KYB_API_TOKEN` auth token (legacy)
- `KYB_TENANT_ID` tenant scope
- `KYB_RUN_ID` run scope (set per run)
- `KYB_SDK_MODE=proxy-first|mcp-first|hybrid` SDK routing mode
- `KYB_SDK_METHOD_TOOL_MAP` JSON map of method name -> MCP tool name
- `KYB_TOOL_REGISTER=1` auto-register tools
- `KYB_GATE_AUTO_APPROVE=1` auto-approve gate unless overridden
- `KYB_TOOL_CALL_LIMIT=0` per-tool call limit (0 = unlimited)
- `KYB_ENFORCE_EGRESS=1` fail-closed if HTTP(S)_PROXY is not set
