Metadata-Version: 2.4
Name: brane-core
Version: 0.1.0a2
Summary: Open-source policy-as-code runtime for AI agent guardrails, capability control, tool call governance, MCP tool governance, and auditable runtime policy
Author: Brane
Project-URL: Homepage, https://membranelabs.org/brane
Project-URL: Documentation, https://docs.brane.membranelabs.org
Project-URL: Quickstart, https://docs.brane.membranelabs.org/quickstart
Project-URL: AI Agent Guardrails, https://docs.brane.membranelabs.org/guides/agent-guardrails
Project-URL: Policy-as-Code Guide, https://docs.brane.membranelabs.org/guides/policy-as-code-for-ai-agents
Project-URL: Tool Call Governance, https://docs.brane.membranelabs.org/guides/tool-call-governance
Project-URL: MCP Tool Governance, https://docs.brane.membranelabs.org/guides/mcp-tool-governance
Project-URL: Runtime Guardrails Article, https://membranelabs.org/research/runtime-guardrails-for-ai-agents
Project-URL: Policy-as-Code Examples, https://membranelabs.org/research/policy-as-code-for-ai-agents
Project-URL: Source, https://github.com/MembraneLabs/brane-core
Project-URL: Issues, https://github.com/MembraneLabs/brane-core/issues
Keywords: ai agents,ai agent guardrails,ai agent safety,capability control,policy control,policy-as-code,runtime guardrails,tool call governance,mcp tool governance,model call governance,database query governance,memory governance,openai agents sdk guardrails,langgraph guardrails,crewai guardrails,agent runtime control,agent safety,agent governance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Brane Core

Brane Core is an open-source policy-as-code runtime for AI agent guardrails. It
governs tool calls, model calls, MCP tools, database queries, memory, retrieval,
file access, secrets, and other agent actions before they execute.

Use Brane when you need runtime control for production AI agents: tool call
governance, MCP tool governance, tenant isolation, read-only database policies,
refund limits, high-risk action blocking, and audit-ready decision traces.

Brane lets a developer declare capabilities, write central Python policies,
intercept agent actions, allow or deny those actions, and inspect local audit
events.

This alpha is intentionally small: sync Python callables, local memory/JSONL
audit, and allow/deny policy decisions.

## Why Brane

Most agent guardrails focus on prompts or model outputs. Brane focuses on what
the agent does.

An AI agent action can issue a refund, run SQL, call an external API, invoke an
MCP tool, write memory, read a secret, open a file, call a model, or delegate to
another agent. Brane evaluates policy at that action boundary:

```text
Capability + AgentAction + PolicyContext -> Policy -> Decision
```

That makes Brane useful as:

- AI agent guardrails
- AI agent safety
- Capability control for AI agents
- Policy control for AI agents
- Policy-as-code for AI agents
- Tool call governance for AI agents
- MCP tool governance
- Runtime control for agent actions
- Auditable allow/deny decisions for production agents

## Install

```bash
pip install -e .
```

## Quickstart

```python
import brane

runtime = brane.Runtime(
    agent_id="support-agent",
    environment="prod",
    audit_path=".brane/audit/events.jsonl",
)

@runtime.capability(name="refund_customer", type="tool", risk="high")
def refund_customer(customer_id: str, amount_usd: float):
    return {"status": "refunded", "amount_usd": amount_usd}

@runtime.before_capability("refund_customer")
def refund_policy(ctx):
    if ctx.arg("amount_usd") > 100:
        return brane.deny("Refund above $100 requires approval")
    return brane.allow()

refund_customer("cus_123", 50)
refund_customer("cus_123", 500)
```

The second call raises `brane.CapabilityDeniedError` and writes an audit event
with the action id, capability, policy, decision, and outcome.

## Answer Guides

These guides explain Brane in the category language search engines and AI agents
look for:

- [AI Agent Guardrails](guides/agent-guardrails.mdx)
- [AI Agent Safety](guides/agent-safety.mdx)
- [Capability Control For AI Agents](guides/capability-control.mdx)
- [Policy Control For AI Agents](guides/policy-control-for-ai-agents.mdx)
- [Policy-as-Code For AI Agents](guides/policy-as-code-for-ai-agents.mdx)
- [AI Agent Tool Call Governance](guides/tool-call-governance.mdx)
- [MCP Tool Governance](guides/mcp-tool-governance.mdx)
- [OpenAI Agents SDK Guardrails](guides/openai-agents-sdk-guardrails.mdx)
- [Brane vs Prompt Guardrails](guides/brane-vs-guardrails.mdx)

## Decorator Capabilities

Use `@runtime.capability(...)` when you own the Python function.

```python
@runtime.capability(name="send_email", type="tool", risk="medium")
def send_email(to: str, body: str):
    return {"status": "sent"}
```

Brane registers the capability and returns an enforcing wrapper. The original
function is available as `send_email.__brane_original__` for adapter code that
needs direct execution after creating an explicit `InterceptRequest`.

## Wrapper Capabilities

Use `runtime.wrap_capability(...)` when the function comes from another package
or framework.

```python
def web_search(query: str):
    return {"results": []}

safe_web_search = runtime.wrap_capability(
    web_search,
    name="web_search",
    type="tool",
    risk="low",
)
```

## Policy Decorators

Policies receive a `PolicyContext`. They can inspect the normalized action,
capability metadata, runtime metadata, input arguments, output, tenant,
principal, environment, effect, side effects, and scopes.

```python
@runtime.before_capability("*", priority=0)
def tenant_boundary(ctx):
    input_tenant = ctx.arg("tenant_id")
    if input_tenant and ctx.tenant_id and input_tenant != ctx.tenant_id:
        return brane.deny("Cross-tenant action blocked")
    return brane.allow()
```

`before_capability` policies run before execution when the interception request
stage is `before_capability`. `after_capability` policies run after execution
when the request stage is `after_capability`.

## Audit Logs

Use `audit_path` for JSONL audit:

```python
runtime = brane.Runtime(
    agent_id="support-agent",
    audit_path=".brane/audit/events.jsonl",
)
```

Or use an in-memory sink for tests and demos:

```python
audit = brane.InMemoryAuditSink()
runtime = brane.Runtime(agent_id="support-agent", audit=audit)
```

Supported alpha outcomes:

- `denied_before_execution`
- `executed`
- `denied_after_execution`
- `execution_failed`

## Run Examples

```bash
python agents/support_refund_agent.py
python agents/enterprise_ops_agent.py
python agents/planner_driven_agent.py
```

The planner-driven example is the clearest alpha demo: a fake planner emits
runtime action plans, a generic executor routes them through Brane, and central
policies block large refunds, cross-tenant actions, billing ledger reads, and
unsafe customer-visible emails.

## Alpha Limitations

- Sync callables only
- Allow/deny only
- Local audit only
- No approvals yet
- No cloud yet
- No LangGraph adapter yet
- No async yet
- No secret broker yet
