Metadata-Version: 2.4
Name: langchain-comply54
Version: 0.3.0
Summary: LangChain / LangGraph integration for comply54 — African AI agent compliance enforcement
Author-email: Oluwajuwon Omotayo <ginuxtechacademy@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://comply54.io/langchain
Project-URL: Repository, https://github.com/comply54/langchain-comply54
Project-URL: Issues, https://github.com/comply54/langchain-comply54/issues
Project-URL: Changelog, https://github.com/comply54/langchain-comply54/blob/main/CHANGELOG.md
Keywords: langchain,langgraph,comply54,africa,compliance,ai-governance,guardrails,ndpa,cbn,fintech,data-protection,nigeria,kenya,opa,rego
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Office/Business :: Financial
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: comply54[langgraph]>=0.3.0

# langchain-comply54

LangChain and LangGraph integration for [comply54](https://comply54.io) — runtime compliance enforcement for AI agents operating under African data protection and financial-sector regulations.

## Overview

`langchain-comply54` wraps the comply54 policy engine as a first-class LangGraph node and LangChain tool. It intercepts agent tool calls **before execution**, evaluates them against African regulatory frameworks (NDPA 2023, CBN, NFIU, Ghana DPA, Kenya DPA, and 15+ more), and either blocks the call or lets it through — all in-process, with no OPA binary or external service required.

```
Agent → Comply54Guard → [deny] → ToolMessage error back to agent
                      → [allow] → Tools execute normally
```

## Installation

```bash
pip install langchain-comply54
```

## Quick Start — LangGraph Guard Node

The recommended pattern is `Comply54Guard` as a pre-execution node in a LangGraph ReAct graph:

```python
from langchain_comply54 import Comply54Guard, comply54_route
from comply54.sectors import NigeriaFintechCompliance
from langgraph.graph import StateGraph, MessagesState, END
from langgraph.prebuilt import ToolNode

# 1. Build your tools and agent as normal
tools = [transfer_funds_tool, lookup_account_tool]
tool_node = ToolNode(tools)
agent_node = build_agent(tools)  # your LLM + tools

# 2. Create the guard
guard = Comply54Guard(
    NigeriaFintechCompliance(),
    context={"kyc_tier": 3, "customer_verified": True},
)

# 3. Wire it into the graph between agent and tools
graph = StateGraph(MessagesState)
graph.add_node("agent", agent_node)
graph.add_node("comply54_guard", guard)
graph.add_node("tools", tool_node)

graph.set_entry_point("agent")
graph.add_conditional_edges("agent", should_continue,
    {"comply54_guard": "comply54_guard", END: END})
graph.add_conditional_edges("comply54_guard", comply54_route,
    {"tools": "tools", "agent": "agent"})
graph.add_edge("tools", "agent")

app = graph.compile()
```

When the agent attempts a tool call that violates compliance policy, `Comply54Guard` injects a `ToolMessage` with a structured denial that the agent can explain to the user:

```json
{
  "blocked": true,
  "decision": "deny",
  "reason": "CBN NIP Framework: single transfer of ₦15,000,000 exceeds the ₦10,000,000 per-transaction cap",
  "regulation": "CBN Transaction Limits & Controls",
  "audit_id": "a3f2c1d4-...",
  "jurisdictions": ["NG"]
}
```

## Compliance Decision Outcomes

Every evaluation returns one of four outcomes:

| Decision | Meaning | Guard behaviour |
|---|---|---|
| `allow` | All checks passed | Tool executes normally |
| `audit` | Action logged for regulatory trail | Tool executes; state gets `compliance_result` |
| `escalate` | Elevated-risk action — human review recommended | Tool executes by default; blocked if `block_on_escalate=True` |
| `deny` | Hard regulatory violation | Tool blocked; agent receives structured `ToolMessage` error |

## Available Sector Packs

| Import | Jurisdictions | Key Regulations |
|---|---|---|
| `NigeriaFintechCompliance` | NG | NDPA 2023, CBN NIP (₦10M cap), NFIU AML/CFT, BVN/NIN |
| `NigeriaHealthCompliance` | NG | NDPA 2023, NHA, NHIA — patient data & health records |
| `NigeriaInsuranceCompliance` | NG | NDPA 2023, NIIRA 2025 (replaces Insurance Act 2003) |
| `KenyaFintechCompliance` | KE | Kenya Data Protection Act 2019, CBK guidelines |
| `PanAfricanCompliance` | NG, KE, GH, RW, EG, MU, ZA, TZ, UG | 9-jurisdiction pack |

```python
from comply54.sectors import (
    NigeriaFintechCompliance,
    NigeriaHealthCompliance,
    NigeriaInsuranceCompliance,
    KenyaFintechCompliance,
    PanAfricanCompliance,
)
```

## Patterns

### Block on escalate

```python
guard = Comply54Guard(
    NigeriaFintechCompliance(),
    block_on_escalate=True,  # treat escalate as deny
)
```

### Per-request context from agent state

Merge dynamic context (e.g. session KYC tier, consent flags) at evaluation time:

```python
# Set compliance_context in your agent state before the guard runs
state["compliance_context"] = {
    "kyc_tier": user.kyc_tier,
    "customer_verified": user.is_verified,
    "consent_documented": user.has_data_transfer_consent,
}
```

### LangChain StructuredTool (self-check pattern)

For agents that should self-check before acting rather than being intercepted automatically:

```python
from langchain_comply54 import comply54_tool
from comply54.sectors import NigeriaFintechCompliance

# The agent can call this tool to ask "is this action allowed?"
compliance_check = comply54_tool(NigeriaFintechCompliance())
tools = [transfer_funds_tool, compliance_check]
```

### Legacy state-dict node

For LangGraph graphs that pass structured state rather than messages:

```python
from langchain_comply54 import compliance_node
from comply54.sectors import NigeriaFintechCompliance

node = compliance_node(NigeriaFintechCompliance())
# state must contain: action, params, output, context
# node writes back: compliance_result, compliance_blocked, compliance_message
```

## Compliance Certificate

Every evaluation produces an auditor-exportable compliance certificate:

```python
result = guard._compliance.check(action="transfer_funds", params={"amount": 5_000_000})
cert = result.to_certificate(
    sector_pack="NigeriaFintechCompliance",
    jurisdictions=["NG"],
    regulations=["NDPA 2023", "CBN FPR"],
)
print(cert.to_json())
```

## Requirements

- Python 3.9+
- `comply54[langgraph] >= 0.3.0` (installed automatically)
- No OPA binary, no Docker, no external services

## Links

- [comply54 documentation](https://comply54.io)
- [comply54 on PyPI](https://pypi.org/project/comply54/)
- [Source repository](https://github.com/comply54/langchain-comply54)
- [African regulatory policy reference](https://github.com/kingztech2019/agt-policies-nigeria)

## License

Apache 2.0
