Metadata-Version: 2.4
Name: kitelogik
Version: 0.2.1
Summary: Governance middleware for AI agents — policy enforcement, credential lifecycle, audit trail.
Author: Kite Logik Contributors
License: Apache-2.0
Project-URL: Homepage, https://www.kitelogik.com
Project-URL: Repository, https://github.com/kitelogik/kitelogik
Project-URL: Documentation, https://github.com/kitelogik/kitelogik#readme
Project-URL: Bug Tracker, https://github.com/kitelogik/kitelogik/issues
Project-URL: Changelog, https://github.com/kitelogik/kitelogik/blob/main/CHANGELOG.md
Project-URL: Source Code, https://github.com/kitelogik/kitelogik
Keywords: ai,agents,governance,opa,policy,llm,security,mcp,guardrails
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: anthropic>=0.40.0
Requires-Dist: opentelemetry-api>=1.27.0
Requires-Dist: opentelemetry-sdk>=1.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Requires-Dist: livereload>=2.7.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: google
Requires-Dist: google-genai>=0.3.0; extra == "google"
Dynamic: license-file

# Kite Logik

[![CI](https://github.com/kitelogik/kitelogik/actions/workflows/ci.yml/badge.svg)](https://github.com/kitelogik/kitelogik/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/badge/tests-605%20passing-brightgreen)](https://github.com/kitelogik/kitelogik/actions)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org)
[![PyPI](https://img.shields.io/pypi/v/kitelogik.svg)](https://pypi.org/project/kitelogik/)

**Governance middleware for Python AI agents.** Kite Logik governs what your agents can do, what they can spawn, what they can access, and what resources they can consume — enforced at the infrastructure level, not the prompt level.

Other tools test prompts. Other tools validate LLM outputs. Kite Logik governs the **agent itself.**

```
A prompt-based guardrail is a suggestion.
Kite Logik is a lock.
```

## Why Kite Logik

Prompt-level guardrails rely on the model cooperating. Kite Logik doesn't.

- **Infrastructure enforcement** — Rules are evaluated by OPA and enforced at the policy gate. The model cannot override a deny.
- **Agent-level governance** — Not just tool calls. Agent spawn, delegation, plans, resource budgets, and data access are all policy-controlled.
- **OPA/Rego policies** — The same policy language security teams already use for Kubernetes. Deterministic, testable, version-controlled.
- **Zero-trust sessions** — Every agent gets a scoped, short-lived credential. Least privilege by default.
- **Immutable audit trail** — Every governance decision is logged, timestamped, and integrity-hashed. SQL triggers prevent tampering.

## What Kite Logik Governs

| Governance Event | What's Evaluated | Example |
|---|---|---|
| **Tool calls** | Every tool invocation, before execution | "Block file writes outside /tmp" |
| **Agent spawn** | Agent creation with requested capabilities | "Max delegation depth is 2" |
| **Delegation** | Agent-to-agent task handoff | "Child scopes must be subset of parent" |
| **Plans** | Proposed action sequence, before any step runs | "Deny plans with blocked tools" |
| **Resource budgets** | Token spend, API calls, compute time | "Deny if session budget exhausted" |
| **Data access** | Classification-based flow control | "Confidential data stays in primary session" |

All events flow through the same pipeline:

```
Governance Event → Credential Check → OPA Evaluation → ALLOW / DENY
                                                         ↓ (rare, high-stakes only)
                                                       HITL Escalation
```

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│                     CONTROL PLANE                        │
│  Agent lifecycle · Delegation chains · Resource budgets  │
│  Plan-before-execute · Data classification               │
└──────────────────────────┬───────────────────────────────┘
                           │
            ┌──────────────▼──────┐
            │  EMBEDDED SDK       │
            │  @governed          │
            │  GovernedToolbox    │
            │  Framework adapters │
            │  (in-process)       │
            └──────────────┬──────┘
                           │
    ┌──────────────────────▼───────────────────────────────┐
    │              TETHER (Policy Engine)                   │
    │  OPA/Rego or Regorus · Deny-by-default · Fail-closed │
    │  YAML or Rego policies · 2-tier hierarchy            │
    └──────────────────────┬───────────────────────────────┘
                           │
            ┌──────────────▼──────────────┐
            │  ANCHOR                     │
            │  Credential broker          │
            │  Audit log                  │
            │  HITL queue                 │
            │  OpenTelemetry              │
            └─────────────────────────────┘
```

### Deployment Modes

| Mode | Who Uses It | How |
|---|---|---|
| **Embedded SDK** | Individual developers & teams | `@governed` decorator wraps tool functions in-process. Zero network hop. Add governance to any agent in 3 lines. |

> **Enterprise:** The Governance Gateway (centralized HTTP API enforcement) is available in [Kite Logik Enterprise](mailto:licensing@kitelogik.com).

## Getting Started

> **Prerequisite:** Kite Logik evaluates every governance event through an OPA policy engine over HTTP. You need OPA reachable at `http://localhost:8181` before any of the examples below will succeed — without it, `PolicyGate` fails closed and every call raises `GovernanceError`. The easiest path is Docker; the scaffold below writes a ready-to-use `docker-compose.yml`.

**New project** — scaffold a governed agent in seconds:

```bash
pip install kitelogik
kitelogik init my-agent           # creates agent.py, policies/, docker-compose.yml
cd my-agent
docker compose up -d opa          # start OPA policy engine on :8181
python agent.py                   # see ALLOW / BLOCK decisions immediately
```

This creates a `policies/policy.yaml` with starter rules, compiles it to Rego, and generates an `agent.py` that runs governance demos. Set `ANTHROPIC_API_KEY` to enable an interactive Claude agent loop.

**Existing project** — add governance to any tool function. You'll need OPA running at `http://localhost:8181` — either run it via Docker directly:

```bash
pip install kitelogik
docker run -d --name opa -p 8181:8181 \
    -v "$(pwd)/policies:/policies:ro" \
    openpolicyagent/opa:latest run --server --addr :8181 /policies
```

…or point at an existing OPA server by passing `base_url=` to `OPAClient(...)`.

```python
from kitelogik import governed, PolicyGate, OPAClient, SessionContext

gate = PolicyGate(opa_client=OPAClient())  # defaults to http://localhost:8181
ctx  = SessionContext(session_id="s1", user_role="support",
                      session_scopes=["read_customer", "approve_refund"])

@governed(gate=gate, context=ctx)
async def approve_refund(customer_id: str, amount: float) -> str:
    return payment_api.refund(customer_id, amount)
```

## Integrate in 3 Lines

**Decorator** — wrap any function:

```python
from kitelogik import governed, PolicyGate, OPAClient, SessionContext

gate = PolicyGate(opa_client=OPAClient())
ctx  = SessionContext(session_id="s1", user_role="support",
                      session_scopes=["read_customer", "approve_refund_under_100"])

@governed(gate=gate, context=ctx)
async def approve_refund(customer_id: str, amount: float) -> str:
    return payment_api.refund(customer_id, amount)

# approve_refund("cust_123", 50.0)   → OPA allows, runs normally
# approve_refund("cust_123", 500.0)  → OPA denies, raises GovernanceError
```

**OpenAI** — drop into your existing tool loop:

```python
from kitelogik.adapters.openai import OpenAIAdapter

adapter = OpenAIAdapter(gate=gate, context=ctx)
adapter.register("approve_refund", approve_refund_fn, schema=schema)

tools = adapter.openai_tool_schemas()       # pass to OpenAI API
results = await adapter.execute_all(calls)  # governed execution
```

**LangChain** — wrap tools or an entire toolkit:

```python
from kitelogik.adapters.langchain import govern_toolkit

tools = govern_toolkit(existing_tools, gate=gate, context=ctx)
agent = create_react_agent(llm, tools=tools)
```

**11 framework adapters** — OpenAI, LangChain, CrewAI, OpenAI Agents SDK, LangGraph, Google ADK, PydanticAI, LlamaIndex, Semantic Kernel, Haystack, Dify. All share the same governance pipeline — see the docstrings in `kitelogik/adapters/` for per-framework usage examples.

**Browse runnable examples** — every snippet above has a standalone script in [`examples/`](examples/) (decorator, GovernedToolbox, OpenAI, LangChain, HITL escalation). Start with [`examples/01_decorator.py`](examples/01_decorator.py).

## Writing Policies

### Option A: YAML (no Rego required)

Write policies in YAML and compile to Rego:

```yaml
# policies/custom_rules.yaml
version: 1
package: kitelogik.custom_rules
rules:
  - name: block_high_refunds
    when:
      action: approve_refund
      args.amount: { gt: 1000 }
    then: deny
    reason: "Refunds over $1000 require escalation"

  - name: allow_read_ops
    when:
      action: { in: [read_customer, list_transactions] }
      context.session_scopes: { contains: read_customer }
    then: allow
    risk_tier: INFORMATIONAL
```

```bash
kitelogik compile policies/custom_rules.yaml   # generates .rego file
kitelogik validate                              # check syntax
```

### Option B: Rego (full control)

Policies are OPA/Rego files in `kitelogik/policies/`. Every file starts with `default allow := false` (deny-by-default).

```rego
package kitelogik.financial

import future.keywords.if
import future.keywords.in

default allow := false

# Allow refunds under $100 for support agents with the right scope
allow if {
    input.action == "approve_refund"
    "approve_refund_under_100" in input.context.session_scopes
    input.context.user_role in {"support_agent", "manager"}
    input.args.amount <= 100
}
```

Agent lifecycle policies work the same way:

```rego
package kitelogik.agent_lifecycle

import future.keywords.if
import future.keywords.in
import future.keywords.every

default allow := false
default deny := false

# Allow spawn when within depth limit and capabilities are valid
allow if {
    input.event_type == "agent.spawn"
    input.context.delegation_depth <= 2
    every cap in input.requested_capabilities {
        cap in input.context.session_scopes
    }
}

# Deny spawn when delegation depth exceeds limit
deny if {
    input.event_type == "agent.spawn"
    input.context.delegation_depth > 2
}
```

See `kitelogik/policies/examples/` for annotated templates and `kitelogik/policies/library/` for ready-to-use starter policies.

## Session Credentials

Every agent session gets a scoped, short-lived credential. The policy gate validates it on every governance event. Agents cannot expand their own permissions.

```python
from kitelogik.anchor.credentials import CredentialBroker

broker = CredentialBroker()
token = broker.issue(session_id="s1", scopes=["read_customer"], ttl_seconds=300)

# Delegation narrows scope — child never gets more than parent
child_token = broker.delegate(
    parent_token_id=token.token_id,
    requested_scopes=["read_customer"],  # must be subset of parent
    session_id="s1_worker",
)
```

## Risk Tiers

| Tier | Examples | Default Outcome |
|---|---|---|
| `INFORMATIONAL` | Read-only lookups, memory queries | Auto-allow |
| `OPERATIONAL` | Write/update operations | Allow if scoped |
| `TRANSACTIONAL_HIGH` | High-value financial operations | Policy-defined (HITL optional) |
| `DESTRUCTIVE` | Delete, bulk operations | Policy-defined |
| `SECURITY_CRITICAL` | Shell access, credential ops, path traversal | Hard block |

HITL escalation is triggered **only when OPA policy explicitly sets `requires_hitl := true`** — for high-stakes situations like wire transfers or restricted data access. Most governance decisions resolve instantly with zero human delay.

## Project Structure

```
kitelogik/
  __init__.py       Public API re-exports
  governed.py       @governed decorator, GovernedToolbox
  adapters/         11 framework adapters
  cli.py            CLI entry point
  tether/           Policy engine: OPA client, Regorus client, hierarchy, sanitizer
  anchor/           Credential broker, HITL queue, session tokens
  memory/           Agent memory with trust tiers and provenance
  agents/           Agent session loop
  audit/            Immutable append-only audit log
  observability/    OpenTelemetry tracing
  mcp/              MCP client with supply chain verification
  policies/         OPA/Rego rules, YAML compiler, starter library, examples
tests/              605 tests across unit, integration, adversarial, fuzz, benchmark suites
```

## OSS vs Enterprise

The OSS gives you the full governance pipeline for your agents. Enterprise gives you governance at organizational scale.

| Feature | OSS | Enterprise |
|---|:---:|:---:|
| **Governance Pipeline** | | |
| OPA policy engine (Tether) | Y | Y |
| Regorus in-process Rego engine (experimental) | Y | Y |
| YAML policy frontend (`kitelogik compile`) | Y | Y |
| 2-tier policy hierarchy (global + project) | Y | Y |
| Tool call governance | Y | Y |
| Agent lifecycle governance (spawn, delegate, plan) | Y | Y |
| Resource budget enforcement | Y | Y |
| Data classification labels | Y | Y |
| Compliance CLI with OWASP ASI mapping | Y | Y |
| Cross-agent governance (org-wide budgets) | | Y |
| **Runtime** | | |
| Docker sandbox (network isolation, resource limits) | | Y |
| Firecracker MicroVM | | Y |
| **Credentials & Access** | | |
| Session-scoped credentials with delegation | Y | Y |
| SSO (SAML/OIDC) | | Y |
| RBAC (Admin, Author, Operator, Viewer) | | Y |
| **Storage** | | |
| SQLite backends (HITL, credentials, audit, memory) | Y | Y |
| PostgreSQL backends (HA, connection pooling) | | Y |
| **Observability** | | |
| OpenTelemetry tracing | Y | Y |
| Prometheus `/metrics` endpoint | | Y |
| Real-time governance dashboard | | Y |
| SIEM webhook (Splunk, Datadog, Elastic) | | Y |
| Policy intelligence dashboard (analytics) | | Y |
| **Operations** | | |
| Starter policy library | Y | Y |
| Governance Gateway (centralized HTTP API) | | Y |
| Orchestrator (multi-agent delegation coordination) | | Y |
| Compliance export packs (SOC 2, HIPAA, FedRAMP) | | Y |
| Agent fleet management | | Y |
| Multi-tenant policy isolation | | Y |
| Policy simulation / what-if analysis | | Y |
| Governance marketplace (compliance packs) | | Y |
| **Framework Adapters** | | |
| OpenAI, LangChain, CrewAI, OpenAI Agents SDK, LangGraph | Y | Y |
| Google ADK, PydanticAI, LlamaIndex, Semantic Kernel, Haystack, Dify | Y | Y |
| **HITL** | | |
| HITL queue (high-stakes escalation) | Y | Y |
| Anchor API (REST endpoints for HITL approval) | | Y |
| HITL SLA tracking | | Y |

For enterprise licensing: [licensing@kitelogik.com](mailto:licensing@kitelogik.com)

## Development

```bash
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
docker compose up -d opa    # start OPA policy engine

make test           # 605 tests (520 unit + 85 adversarial)
make lint           # ruff check + format

# Policy management
kitelogik compile kitelogik/policies/examples/example_rules.yaml   # YAML → Rego
kitelogik validate                                        # check Rego syntax
kitelogik compliance                                      # OWASP ASI audit

# Benchmarks — measured latency on the agent's critical path
docker compose up -d opa
python benchmarks/bench_gate.py             # policy gate: p50 ~3ms, p95 ~8ms
python benchmarks/bench_memory_session.py   # memory + credential broker (no OPA)
```

## Requirements

- Python 3.11+
- Docker (for OPA policy engine) — `docker compose up -d opa`
- No API key needed for `quickstart.py` or policy testing

## Further Reading

- [Examples](examples/) — runnable scripts for each integration pattern
- [Contributing](CONTRIBUTING.md)
- [Security Policy](SECURITY.md)
- [Changelog](CHANGELOG.md)

---

**Kite Logik** — Governance middleware for Python AI agents.
