Metadata-Version: 2.5
Name: norcaster-langchain
Version: 0.1.2
Summary: Norcaster check for LangChain: your agent asks Norcaster for a decision (allow, hide or block) before each call to the AI provider, and Norcaster keeps a record of every answer.
Project-URL: Homepage, https://www.norcaster.com
Author-email: "Norcaster (Navego AB)" <security@norcaster.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai-governance,audit-evidence,langchain,langgraph,middleware
Requires-Python: >=3.12
Requires-Dist: langchain<2,>=1.2.11
Requires-Dist: norcaster<0.2,>=0.1.5
Provides-Extra: test
Requires-Dist: langchain-openai<2,>=1.0.0; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# norcaster-langchain

For an agent built with [LangChain](https://docs.langchain.com/oss/python/langchain/overview). Before
every call the agent makes to the AI provider, it asks Norcaster for a decision. Norcaster answers
from the app's rules and keeps a record of every answer. The agent then calls the provider itself:
your app is not re-pointed, and your provider keys stay where they are.

| Norcaster's decision | What the agent does |
|---|---|
| **allow** | Calls the provider with the conversation as it is. |
| **hide** | Calls the provider with the version Norcaster returned, with the sensitive data hidden. |
| **block** | Does not call the provider. The run stops with an error that names the decision and the record. |

It can also ask about the model's answer before the agent uses it: see [Answer checks](#answer-checks).

**Status:** new. Tested with LangChain 1.2.11 and 1.5.0.

## Set up

You need a Norcaster key with the `runs:write` scope and the id of the app in Norcaster.

1. Install the adapter into the Python environment that runs your agent. It brings the Norcaster
   SDK (`norcaster`) with it:

   ```bash
   pip install norcaster-langchain
   ```

2. Add the middleware to your agent. It is one entry in the list, placed last:

   ```python
   import os

   from langchain.agents import create_agent
   from norcaster_langchain import NorcasterCheckMiddleware
   from norcaster import NorcasterCloudClient

   norcaster = NorcasterCloudClient(os.environ["NORCASTER_API_KEY"], "https://api.norcaster.com")

   agent = create_agent(
       model,
       tools,
       middleware=[NorcasterCheckMiddleware(norcaster, deployment_id="<the app's id>")],
   )
   ```

3. Run the agent once. The model's answer carries the record's id
   (`message.response_metadata["norcaster"]["receipt_id"]`), and the same call is in the app's
   records in Norcaster, marked **Checked**.

[`examples/agent.py`](examples/agent.py) is a small agent that shows allow, hide, block and what
happens when Norcaster can't be reached. Its provider is a stand-in inside the script, so only the
checks leave your machine.

**Put the middleware last.** LangChain runs the list from the outside in, so a middleware placed
after this one can change the conversation after it was checked.

## What the record shows

The app asked Norcaster before it called the provider.

What it does not show:

- **What the agent sent afterwards.** Norcaster does not see the provider call. The record holds a
  SHA-256 of the conversation as the adapter sent it to Norcaster (the text and the tool calls, as
  chat messages). It is not a hash of the bytes LangChain sent to the provider.
- **That every call was checked.** Only model calls that go through this middleware are. See below.
- **Anything about the provider's answer**, unless [answer checks](#answer-checks) are on. Then
  the record of the answer shows your app asked about a text: not that the text was the
  provider's answer, or what your app did with it afterwards.

If you need a record that nothing reached the provider unchecked, send the app's traffic through
the Norcaster gateway instead.

The conversation is sent to Norcaster to be checked. If your data may not leave your network, this
adapter does not change that; a Norcaster you host yourself does.

## What is checked

**Every model call of the agent, not only the first.** An agent that uses a tool three times in a
row makes four model calls, and each one is checked before it is made. Each check covers
everything that call sends:

- the system prompt and the user's messages;
- the agent's earlier answers;
- the arguments of tool calls from earlier steps;
- the results of tools, which is how a secret a tool read is stopped before it goes to the provider.

A streamed call is checked before the stream starts. Sync and async runs are checked the same way.

**What is not checked:**

- **The model's answer, and the tool calls it asks for, when it asks for them**, unless you turn
  on [answer checks](#answer-checks). Without them a tool runs with the arguments the model wrote,
  and Norcaster reads those arguments at the next model call, with the rest of the conversation,
  after the tool has run.
- **Tool definitions, the model's name and its settings.**
- **The model's own reasoning** that some providers send back with the conversation. Providers
  sign it, so it is sent on as it is and Norcaster is not asked about it.
- **Model calls made outside this middleware:** another middleware that calls a model itself
  (summarization, tool selection), a sub-agent built without the middleware, a tool that calls a
  model, a call your code makes directly.
- **An `extra_body` or `model_kwargs` chosen per run**, as a configurable field
  (`init_chat_model(configurable_fields=...)`, `configurable_fields(...)`): the middleware can't
  see it. Don't make either one configurable on a model the agent checks.

**Images, files and audio** in a message meet your app's rules for them, the same rules the
Norcaster gateway applies (allow, warn or block, and limits on how many, how large and which types).
Each is checked as the OpenAI chat part it would be, and Norcaster gets a description of each inline
one (the SHA-256 of its bytes, its size, media type and pixel size), never the file. Nothing reads
what it shows, and the record lists it as not read. A hide changes only the text: the files go to
the model as they were. This takes LangChain's own image, file and audio blocks, OpenAI's and
Anthropic's. Requires `norcaster` 0.1.5 or later, and a Norcaster from 19 November 2026 or later.

**What is refused.** A call that holds anything a check can't read is not sent: a file the OpenAI
chat shape can't hold (an image by file id, a document by URL, a plain-text document, video, audio
other than WAV and MP3, a file in a tool's result), or the result of a tool the provider runs itself.
The run stops with `NorcasterCannotCheck` and Norcaster is not asked. This is so that nothing goes
to the provider unread.

The same goes for a model whose settings carry content of their own:
- `messages`, `input`, `instructions` or `prompt` in `extra_body` (on the model, on a bound model,
  or in a middleware's `model_settings`);
- `instructions` or a stored `prompt` set on the model;
- a predicted output (`prediction`, OpenAI's Predicted Outputs) in `model_kwargs`, in `extra_body`,
  on a bound model or in a middleware's `model_settings`. It is usually the same file a message
  holds, and a check doesn't read it, so a hide in that file would go out unhidden there.

The OpenAI client would send that beside or in place of the checked messages. Put it in the
agent's system prompt or messages instead, and leave `prediction` out.

### When the decision is hide

Norcaster's hidden text is written into a copy of the conversation, in every place it lives: the
message's text, the tool call's arguments, the tool's result. The provider gets the copy. The
conversation your app keeps is unchanged.

Two things to know:

- The model sees the placeholder, not the value. If it then calls a tool with the hidden value,
  the tool gets the placeholder.
- If the hidden version can't be written back exactly, the call is not sent
  (`NorcasterCannotCheck`). It is never sent with the original text.

## Answer checks

Off unless you turn them on. With `check_output=True` the middleware also asks Norcaster about each
of the model's answers, after every model call of the run and before the agent uses it
(`POST /v1/check/output`): its text, and the tool calls it asks for (each tool's name and its
arguments), so before the agent's tools node runs any of them:

```python
NorcasterCheckMiddleware(norcaster, deployment_id="<the app's id>", check_output=True)
```

| Norcaster's decision on the answer | What the agent gets |
|---|---|
| **allow** | The answer as the model wrote it. |
| **hide** | A copy with Norcaster's hidden text, and each tool call's arguments with the sensitive values hidden, in every place the message keeps them (`tool_calls`, the provider's content blocks, `additional_kwargs`). The tool runs with those arguments. The answer's token list (`logprobs`), which spells out the original words, is left out. |
| **block** | Nothing. The run stops with `NorcasterBlocked`, `about == "answer"`. A tool the answer asked for does not run. |

The answer's check is recorded under the same request as the check before the call, so the app's
records show one call with two decisions. Its receipt is on the answer, under
`response_metadata["norcaster"]["answer"]`. Each model call that answers with text or tool calls
adds one more round trip to Norcaster, before any tool runs.

**The app's rules must cover answers.** If they don't, Norcaster refuses the check:
`NorcasterCheckRefused` with code `output_rules_off` and `about == "answer"`. It happens after the
provider has answered, on every call, until the rules cover answers or `check_output` is off.

**What is read:** the answer's text, which is its string content or its text blocks run together,
and its tool calls: `tool_calls` (each tool's name and its `args` as compact JSON), the ones
LangChain couldn't parse (`invalid_tool_calls`, their arguments as the text the model wrote) and
OpenAI's older `function_call`. An answer that is only tool calls is asked about too.

**When a tool call is hidden:** the tool runs with placeholders in place of the sensitive values,
in JSON of the same shape (the same keys and value types; the tool's name never changes). A
placeholder can change what a tool does: a mail tool would get `[REDACTED: EMAIL]` as the address.
If a tool can't run with a placeholder, treat hide as block in that tool. A hide that can't be
written into every copy of the call withholds the answer (`NorcasterCannotCheck`).

**What is handed on unread:**

- **The model's reasoning** (thinking blocks). Providers sign it, so it is handed on as it is,
  after a hide too: it can still hold what the hide took out of the text.
- **A refusal kept outside the text** (`additional_kwargs["refusal"]`), and usage.
- **Provider metadata** other than `logprobs`. Citations keep their offsets into the original text.

**What is withheld:** an answer that holds an image, a file, audio, or any part of a kind the
adapter doesn't know (results of tools the provider runs itself among them). It is never handed on
unread: `NorcasterCannotCheck`, `about == "answer"`. So is an answer that is hidden and was also
parsed into a structured response, from its text (`response_format` with the provider's structured
output) or from a tool call's arguments: the structured response holds the original words. Allowed,
it is handed on.

**The check engine in your own network** reads tool calls too. An older engine refuses them (409
`tool_calls_not_on_engine`), and the answer is withheld.

**An older `norcaster` SDK that can't ask about tool calls** (0.1.1 or older; this adapter requires
`norcaster>=0.1.2`, so only an SDK installed around that rule): an answer with tool calls is withheld
(`NorcasterCannotCheck`), never handed on with its tool calls unread. Answers with text only are
checked as before.

**What the record shows:** that the app asked about the answer and its tool calls, and which tools
(never their arguments). Not what the agent then did, or which tools ran.

**Streaming.** LangChain tells callbacks about the model's answer inside the model call, before
any middleware gets it back. So, with answer checks on:

- **`stream_mode="messages"`** (alone or with other modes, sync or async): the model call is tagged
  `nostream`, and the stream carries each step's checked answer as one message at the end of the
  step, not token by token. LangChain still streams from the provider; your app gets the first
  words once the provider has finished and Norcaster has decided. `"updates"` and `"values"` work
  as before.
- **Refused before anything is sent** (`NorcasterCannotCheck`): `astream_events`, `astream_log`,
  and a callback of your own that takes the answer as it is written (`on_llm_new_token`), set on
  the run or on the model.
- **Tracers (LangSmith) and other callbacks** are still told about the provider's answer as it
  came when the model call ends (`on_llm_end`), as they are told about each step's messages before
  a hide. Don't hand the answer on from a callback.

**When Norcaster can't be reached after the model answered,** the answer is withheld:
`NorcasterUnreachable` with `about == "answer"`. With `when_unreachable="let_through"` the agent
gets the answer, `response_metadata["norcaster"]["answer"]` says `"decision": "unchecked"`, and
Norcaster records it as an answer let through without a check, under the request it belongs to.
When the request itself was let through, its answer is not asked about: the one record stands for
the call.

**Retry and fallback middleware** placed before this one (`ModelRetryMiddleware`,
`ModelFallbackMiddleware`) retry or fall back on a block too, so the provider is called again. Each
try is checked and leaves its own records. The same holds for a blocked request.

## A graph you built yourself

The middleware works with `create_agent`. A graph built by hand with LangGraph, or a plain chain,
has no place for it: LangChain offers no hook around a model call there. Call the same check
yourself, right before the node calls the model:

```python
from norcaster_langchain import check_messages

def call_model(state):
    checked = check_messages(norcaster, state["messages"], deployment_id="<the app's id>")
    answer = model.invoke(checked.messages)          # the messages to send: hidden when told to
    return {"messages": [checked.stamp(answer)]}     # the answer, with the record's id on it
```

`acheck_messages` is the same for async code. A block raises `NorcasterBlocked` before the model
is called.

**Here the check happens only where you call it.** A node that calls the model without it is not
checked and leaves no record. Call the model with the checked messages and no other content: an
`extra_body` or `model_kwargs` that holds messages, input, instructions, a prompt or a `prediction`
would reach the provider unchecked, and here nothing refuses it.

To ask about the answer too, call `check_answer` on it before the node returns it:

```python
from norcaster_langchain import check_answer, check_messages

def call_model(state):
    checked = check_messages(norcaster, state["messages"], deployment_id="<the app's id>")
    answer = model.invoke(checked.messages, config={"tags": ["nostream"]})
    return {"messages": [check_answer(norcaster, answer, checked, deployment_id="<the app's id>")]}
```

It returns the answer to use, with both receipts on it, and raises as the middleware does.
`acheck_answer` is the same for async code. The `nostream` tag keeps `stream_mode="messages"` from
sending the provider's answer before it is checked; the checked answer goes out when the node
returns. Without it, a streamed graph hands on the provider's tokens first.

## Settings

| Setting | Default | What it is |
|---|---|---|
| `client` | required | Your `NorcasterCloudClient`. It holds the key and your Norcaster address. |
| `deployment_id` | the key's app | The app's id. Leave it out only when the key belongs to one app. |
| `when_unreachable` | `"block"` | `"block"` or `"let_through"`. See below. |
| `on_unchecked` | none | Called every time a call is let through without a check. |
| `timeout` | `10` | Seconds to wait for Norcaster's answer. |
| `check_output` | `False` | Also ask about the text of each of the model's answers. See [Answer checks](#answer-checks). |

These are the Norcaster SDK's own settings for a check, passed on unchanged. A wrong setting is
refused when the middleware is built, so the app does not start with it.

**One middleware per app.** Each agent that is its own app in Norcaster gets its own
`deployment_id`, so each has its own rules and its own records.

## What your code gets

**The record's id, on every answer.** Each answer of the model carries the check that came before
the call that produced it:

```python
answer.response_metadata["norcaster"]
# {"decision": "hide", "receipt_id": "88bfb959-…", "content_sha256": "8cdc…", "rules_version": 3,
#  "decided_at": "2026-11-12T16:07:41.512+00:00", "request_id": "chk_…"}
```

With answer checks on, the answer's own check is under `"answer"`, with the same keys:

```python
answer.response_metadata["norcaster"]["answer"]
# {"decision": "allow", "receipt_id": "5d0c…", "content_sha256": "1f3a…", "rules_version": 3,
#  "decided_at": "2026-11-12T16:07:42.104+00:00", "request_id": "chk_…"}
```

It stays in the agent's messages and shows wherever you trace them. It never holds the
conversation, the answer or the key.

**An error when the call is not made, or the answer is not handed on.** All of them are
`NorcasterCheckError`, from the SDK. `about` says which: `"request"` (the provider was not called)
or `"answer"` (the provider answered and the answer was withheld).

| Error | When |
|---|---|
| `NorcasterBlocked` | The decision was block. It has `code`, `reason`, `suggestion` and `receipt_id`. |
| `NorcasterUnreachable` | Norcaster could not be reached and the call was not let through. |
| `NorcasterCheckRefused` | Norcaster refused the check: a wrong or revoked key, a missing scope, a stopped app, the rate limit, too much content, rules that don't cover answers (`output_rules_off`). |
| `NorcasterCannotCheck` | The call or the answer holds something a check can't read, the hidden version could not be written back, or the run is streamed in a way that would hand on the answer before it is checked. |

A block looks like this, and never repeats what was blocked:

```
NorcasterBlocked: Norcaster's decision was block (contextual_block). A secret or access credential
was detected in an earlier message in this conversation. The provider was not called.
Receipt: 8070b112-3270-45eb-ad0e-7cad5dbe55a0.
```

The error stops the agent's run. Catch it where you call the agent.

## When Norcaster can't be reached

"Can't be reached" means no connection, no answer within `timeout`, or an error on Norcaster's side.

**By default the call is blocked:** `NorcasterUnreachable`, and the provider is not called. With
answer checks on, an answer is withheld the same way ([Answer checks](#answer-checks)).

`when_unreachable="let_through"` makes the call instead. Every call that is let through is
recorded, each time:

1. A warning in your app's log (logger `norcaster.check`), with the call's id and its SHA-256.
2. Your `on_unchecked` function is called with it.
3. On the model's answer: `response_metadata["norcaster"]` says `"decision": "unchecked"` and
   carries the id.
4. In Norcaster, once it answers again: the next check that succeeds reports what was let through,
   and it shows in the app's records as **Let through without a check**.

The record holds a SHA-256 of the conversation, when it happened and why. It never holds the
conversation itself. No rule ran on a call that was let through, and it is not counted as a check.

Know these limits before you turn it on:

- A call that is let through goes to the provider as the agent wrote it. Nothing is hidden.
- Calls waiting to be reported are kept in your app's memory. If the app stops before Norcaster
  answers again, your own log line is the only record. `norcaster.report_unchecked()` sends what
  is waiting; call it when your app shuts down.
- At most 10,000 wait at a time. Past that, calls are blocked.
- A refusal from Norcaster always blocks, whatever the setting.

## Limits to know

- **Each model call is one check.** An agent run with five model calls is five checks. A check
  draws on the same rate limit as a request through Norcaster's gateway: 600 a minute by default,
  shared by all of one person's keys, or by one service account's or agent's keys. Over the limit,
  Norcaster refuses and the call is blocked. Like gatewayed requests, checks don't count toward the
  plan's monthly request limit yet.
- **Each model call waits for Norcaster's answer.** Measured against a local Norcaster: about
  11 ms for a short prompt and about 19 ms for a 4 KB conversation, at the median. A hosted
  Norcaster adds the network round trip.
- **Each check sends the whole conversation so far**, so the wait grows as the conversation does.
  More than 1,000,000 characters is refused.
- **Answer checks read text only**, and add one round trip per model call that answers with text.
  A streamed answer reaches your app once the provider has finished and Norcaster has decided.
  See [Answer checks](#answer-checks).
- **Async runs: one Norcaster client per event loop.** The SDK keeps one connection open for async
  checks, and it belongs to the event loop that first used it.

## Develop

The tests need LangChain, LangChain's OpenAI package and the SDK from this repository
(`sdk/python`). From this folder:

```bash
PYTHONPATH=src:../../sdk/python/src uv run --isolated --no-project --python 3.12 \
  --with "langchain==1.5.0" --with "langchain-openai>=1.0.0,<2" --with "httpx>=0.24" --with "pytest>=7" \
  python -m pytest -q
```

- `test/test_conversation.py`: what is sent to Norcaster for each kind of message, and how a hidden
  version is written back.
- `test/test_agent.py`: the middleware inside a real agent, with a stand-in model.
- `test/test_answer.py`: answer checks, in an agent, in a streamed run, and by hand.
- `test/test_openai_wire.py`: the same on LangChain's real OpenAI chat model, against a stand-in
  provider on `127.0.0.1`, to show what goes over the wire.
- `test/test_example.py`: the example agent.

Norcaster is a stand-in on `127.0.0.1` in all of them. No provider and no Norcaster API is called.
