Metadata-Version: 2.4
Name: palveron-langchain
Version: 1.0.0
Summary: Official Palveron LangChain integration — automatic policy enforcement, PII masking, and audit trails for every LLM call.
Project-URL: Homepage, https://palveron.com
Project-URL: Documentation, https://docs.palveron.com/sdks
Project-URL: Repository, https://github.com/palveron/adapter-langchain
Project-URL: Issues, https://github.com/palveron/adapter-langchain/issues
Project-URL: Changelog, https://github.com/palveron/adapter-langchain/blob/main/CHANGELOG.md
Author-email: Palveron <hello@palveron.com>
License: MIT
License-File: LICENSE
Keywords: ai-governance,audit-trail,callback-handler,compliance,eu-ai-act,guardrails,langchain,palveron,pii-detection
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: langchain-core>=0.1
Requires-Dist: palveron-sdk>=1.0.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# palveron-langchain

PALVERON AI Governance adapter for **LangChain** — automatic policy checks, PII masking, and audit trails for every LLM call in your pipeline.

[![PyPI](https://img.shields.io/pypi/v/palveron-langchain.svg?style=flat-square)](https://pypi.org/project/palveron-langchain/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)

---

Add one callback handler. Every prompt, every tool call, every LLM output gets checked against your [PALVERON](https://palveron.com) governance policies. PII is detected. Secrets are caught. Blocked requests raise exceptions before they reach the model.

## Installation

```bash
pip install palveron-langchain
```

## Quick Start

```python
from palveron_langchain import PalveronCallbackHandler
from langchain_openai import ChatOpenAI

# Create the governance handler
handler = PalveronCallbackHandler(api_key="pv_live_xxx")

# Attach to any LangChain component
llm = ChatOpenAI(model="gpt-4o", callbacks=[handler])

# Every call is now governed
result = llm.invoke("Transfer $50,000 to account DE89370400440532013000")
# → PalveronGovernanceError: Blocked — PII detected (IBAN)
```

## What Gets Checked

| Event | When | What |
|-------|------|------|
| `on_llm_start` | Before text completion | Prompt text |
| `on_chat_model_start` | Before chat model call | All messages concatenated |
| `on_tool_start` | Before tool execution | Tool name + input |
| `on_llm_end` | After generation (optional) | LLM output text |

## Configuration

```python
handler = PalveronCallbackHandler(
    api_key="pv_live_xxx",
    base_url="https://gateway.palveron.com",  # On-prem endpoint
    check_prompts=True,       # Check inputs before LLM (default: True)
    check_outputs=False,      # Check LLM outputs (default: False)
    check_tools=True,         # Check tool inputs (default: True)
    raise_on_block=True,      # Raise exception on BLOCKED (default: True)
    fail_open=False,          # Allow calls when gateway down (default: False)
    metadata={"team": "ml"},  # Extra metadata on every trace
)
```

## Behavior on Decisions

| Decision | `raise_on_block=True` | `raise_on_block=False` |
|----------|----------------------|----------------------|
| `ALLOWED` | Call proceeds | Call proceeds |
| `MODIFIED` | Call proceeds, PII redaction logged | Call proceeds, PII redaction logged |
| `BLOCKED` | Raises `PalveronGovernanceError` | Logs warning, call proceeds |
| `ERROR` | Depends on `fail_open` | Depends on `fail_open` |

**Note:** LangChain callbacks are observational — they cannot modify prompts in-flight. For full input rewriting (PII masking before the LLM sees it), use the [PALVERON Gateway Proxy](https://docs.palveron.com/guides/gateway-proxy).

## Governance Records

Access the audit trail programmatically:

```python
# After running your chain
print(f"Blocked: {handler.blocked_count}")
print(f"Trace IDs: {handler.trace_ids}")

for record in handler.records:
    print(f"{record.event}: {record.decision} ({record.latency_ms:.0f}ms) — {record.trace_id}")
```

## Error Handling

```python
from palveron_langchain import PalveronCallbackHandler, PalveronGovernanceError

handler = PalveronCallbackHandler(api_key="pv_live_xxx")

try:
    result = llm.invoke("Send SSN 123-45-6789 to the client", config={"callbacks": [handler]})
except PalveronGovernanceError as e:
    print(e.decision)   # "BLOCKED"
    print(e.trace_id)   # "trc_abc123"
    print(e.reason)     # "PII detected: Social Security Number"
```

## With Agents

```python
from langchain.agents import create_react_agent

handler = PalveronCallbackHandler(api_key="pv_live_xxx", check_tools=True)

agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, callbacks=[handler])

# Both LLM calls AND tool executions are governed
result = agent_executor.invoke({"input": "Delete all customer records"})
```

## With Chains (LCEL)

```python
from langchain_core.prompts import ChatPromptTemplate

handler = PalveronCallbackHandler(api_key="pv_live_xxx")

chain = ChatPromptTemplate.from_template("Summarize: {text}") | llm
result = chain.invoke({"text": sensitive_doc}, config={"callbacks": [handler]})
```

## Requirements

- Python 3.9+
- `palveron-sdk` >= 0.5.0
- `langchain-core` >= 0.2.0

## Links

- [Documentation](https://docs.palveron.com/integrations/langchain)
- [PALVERON Dashboard](https://app.palveron.com)
- [palveron-sdk (Python)](https://pypi.org/project/palveron-sdk)
- [GitHub](https://github.com/palveron/palveron-langchain)

## License

[Apache 2.0](./LICENSE)
