Metadata-Version: 2.5
Name: noma-langchain-integration
Version: 0.2.0
Summary: Noma guardrail middleware integration for LangChain
Project-URL: Homepage, https://github.com/Noma-Security/langchain-noma-integration-package
Project-URL: Source, https://github.com/Noma-Security/langchain-noma-integration-package
Project-URL: Issues, https://github.com/Noma-Security/langchain-noma-integration-package/issues
Author: Noma Security
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain<2.0.0,>=1.0.0
Description-Content-Type: text/markdown

# noma-langchain-integration

Noma guardrail middleware for LangChain agents. Scans user and assistant messages to detect and handle unsafe content before and after agent execution.

## Installation

```bash
pip install noma-langchain-integration
```

## Quick start

```python
from langchain.agents import create_agent
from langchain_noma.middleware import NomaGuardrailMiddleware

middleware = NomaGuardrailMiddleware(
    api_key="noma-...",  # or set NOMA_API_KEY env var
)

agent = create_agent(
    model="openai:gpt-4.1",
    tools=[...],
    middleware=[middleware],
)
```

The middleware runs these hooks automatically:

- **`before_agent`** — scans user messages before the agent processes them.
- **`wrap_tool_call`** — scans each tool call's arguments before the tool runs, and its output before the model sees it.
- **`after_agent`** — scans assistant messages after the agent responds.

| Content | Block | Mask |
|---|---|---|
| User prompt | Before the model runs | Before the model runs |
| Tool call arguments | Tool is not run; the model gets an error tool message | Tool runs with masked arguments |
| Tool output | Replaced with an error tool message | Replaced with masked output |
| Final response | Replaced with a block message | Replaced with masked text |

Both sync and async hooks are supported (`abefore_agent`, `awrap_tool_call`, `aafter_agent`).

Tool scanning needs a Noma broker that supports the `before_tool`/`after_tool` phases. An older broker rejects them; tool calls then run unscanned (as in 0.1.x) and `after_agent` still scans the final response.

**Streaming:** response tokens (including tool-call arguments the model generates) stream before `after_agent` runs, so they are not blocked or masked in the stream; only the final state is. Use `invoke`/`ainvoke` when output must not reach users unscanned. Tool output is scanned before it is emitted.

Scans also send the agent's available tools (name, description and parameters, in OpenAI tool format), taken from the tools bound to the model call and kept in the run's own agent state, so parallel runs never mix them up. A run's first `before_agent` scan goes out without them, since no model call has happened yet; with a checkpointer, later turns of a conversation include them from the start. Requires `langchain>=1.2.9`; on older versions scans are sent without tools.

## Configuration

All parameters are optional and keyword-only:

| Parameter | Type | Default | Description |
|---|---|---|---|
| `api_key` | `str \| None` | `NOMA_API_KEY` env | API key for the Noma service. Required when using the Noma SaaS endpoint. |
| `application_id` | `str \| None` | `NOMA_APPLICATION_ID` env or `"langchain"` | Application identifier sent with each scan request. |
| `block_failures` | `bool` | `True` | When `True` (fail-closed), block requests if the AIDR API is unreachable. When `False` (fail-open), allow requests through on scan failure. |

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `NOMA_API_KEY` | Yes (SaaS) | API key. Can also be passed via the `api_key` constructor parameter. |
| `NOMA_APPLICATION_ID` | No | Override the application identifier (defaults to `"langchain"`). |
