noma-langchain-integration 0.1.0

Noma guardrail middleware integration for LangChain

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

pip install noma-langchain-integration

Quick start

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 two hooks automatically:

• before_agent — scans user messages before the agent processes them.
• after_agent — scans assistant messages after the agent responds.

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

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.

Guardrail actions

The Noma API returns one of three actions for each scan:

Action	Behavior
allow	Request passes through unchanged.
mask	Sensitive content in the message is replaced with an anonymized version. Falls back to block if anonymized content is unavailable.
block	An AIMessage with a block notice replaces the response and the agent jumps to end.

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").

Development

# Run unit tests
make tests

# Run integration tests (requires NOMA_API_KEY)
make integration_tests

# Lint and format
make lint
make format

# Type checking
make typing

Publishing

Publishing runs automatically after changes land on the main branch.

1. Bump version in pyproject.toml.
2. Merge the version bump to main.

The Publish PyPI GitHub Actions workflow can also be run manually from main for reruns after transient failures.

The workflow publishes to the PyPI project noma-langchain-integration with PyPI Trusted Publishing. No PyPI API token is required when the PyPI pending publisher is configured for this repository and publish_pypi.yml.