# langchain-nobulex

Compliance middleware for LangChain agents with hash-chained audit trails.

Enforce covenant rules on agent tool calls, block forbidden actions, and maintain a tamper-proof audit log — ready for **EU AI Act** compliance requirements.

## Installation

```bash
pip install langchain-nobulex
```

## Quick Start

```python
from langchain_nobulex import create_agent, NobulexComplianceMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=tools,
    middleware=[
        NobulexComplianceMiddleware(
            rules="permit read; forbid transfer where amount > 500; require log_all;"
        )
    ]
)
```

## How It Works

**Define rules** using a simple covenant DSL:

- `permit <action>` — explicitly allow a tool/action
- `forbid <action> [where <condition>]` — block a tool/action, optionally with conditions
- `require <behavior>` — declare required behaviors (e.g., `log_all`)

**The middleware**:

1. Intercepts every tool call from the model
2. Matches it against your covenant rules
3. Blocks forbidden actions before they execute
4. Logs every action (allowed and blocked) in a SHA-256 hash-chained audit trail

**Verify integrity** independently:

```python
from langchain_nobulex import verify

log = agent.get_audit_log()
assert verify(log)  # True if chain is intact, False if tampered
```

## Audit Trail

Every entry in the audit log contains:

| Field | Description |
|-------|-------------|
| `timestamp` | ISO 8601 UTC timestamp |
| `action` | Tool/action name |
| `params` | Tool arguments |
| `allowed` | Whether the action was permitted |
| `matching_rule` | The rule that matched |
| `prev_hash` | SHA-256 hash of the previous entry |
| `hash` | SHA-256 hash of this entry |

Each hash links to the previous entry, forming a tamper-evident chain. Use `verify()` to independently validate the entire chain.

## EU AI Act Compliance

This middleware supports EU AI Act (Regulation 2024/1689) requirements for high-risk AI systems:

- **Article 14 — Human oversight**: Rules let operators define boundaries before deployment
- **Article 12 — Record-keeping**: Hash-chained audit logs provide tamper-proof records of all AI actions
- **Article 9 — Risk management**: Forbidden rules act as runtime guardrails against identified risks
- **Independent verification**: The `verify()` function enables third-party audit of the action log

## API Reference

### `NobulexComplianceMiddleware(rules: str)`

Main middleware class. Pass a covenant rules string.

- `after_model(response)` — intercepts and filters tool calls
- `wrap_tool_call(tool_call)` — hook for per-execution logging
- `after_agent(state)` — attaches audit log to final agent state
- `get_audit_log()` — returns the full audit trail as a list of dicts
- `get_audit_log_json()` — returns the audit trail as formatted JSON

### `verify(audit_log)`

Independently validates a hash-chained audit log. Returns `True` if intact.

### `create_agent(model, tools, middleware)`

Creates a middleware-aware agent wrapper.

## License

MIT
