Metadata-Version: 2.4
Name: behaviorweave
Version: 1.1.0
Summary: Deterministic behavioral policies and interventions for LangGraph and LangChain agents.
Keywords: agents,agxai,ai-safety,guardrails,intervention,langchain,langgraph,policy
Author: S MUNI HARISH
Author-email: S MUNI HARISH <samamuniharish@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: agxai[langgraph]>=1.0.2,<2
Requires-Dist: langchain>=1.4.9,<2
Requires-Dist: langchain-core>=1.7.6,<2
Requires-Dist: langgraph>=1.2.20,<2
Requires-Dist: opentelemetry-api>=1.45.2,<2 ; extra == 'otel'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/smuniharish/behaviorweave
Project-URL: Documentation, https://behaviorweave.readthedocs.io/
Project-URL: Changelog, https://github.com/smuniharish/behaviorweave/blob/master/CHANGELOG.md
Project-URL: Issues, https://github.com/smuniharish/behaviorweave/issues
Project-URL: Repository, https://github.com/smuniharish/behaviorweave
Provides-Extra: otel
Description-Content-Type: text/markdown

<div align="center">

# BehaviorWeave

**Async behavioral policies and interventions for LangGraph and LangChain agents.**

[![CI](https://github.com/smuniharish/behaviorweave/actions/workflows/ci.yml/badge.svg)](https://github.com/smuniharish/behaviorweave/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/behaviorweave.svg)](https://pypi.org/project/behaviorweave/)
[![Python](https://img.shields.io/pypi/pyversions/behaviorweave.svg)](https://pypi.org/project/behaviorweave/)
[![Docs](https://readthedocs.org/projects/behaviorweave/badge/?version=latest)](https://behaviorweave.readthedocs.io/en/latest/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/smuniharish/behaviorweave/blob/master/LICENSE)

</div>

Agents repeat tool calls, retry failing dependencies, and bounce work between specialists.
BehaviorWeave detects these patterns deterministically and returns typed interventions:
your application decides when to nudge, escalate, request review, or stop.

![BehaviorWeave architecture](https://raw.githubusercontent.com/smuniharish/behaviorweave/master/docs/assets/diagrams/architecture.png)

## Highlights

- **Deterministic and explainable:** pattern, count, threshold, policy, and provenance;
  no model call is needed to evaluate a policy.
- **Async-first:** engine, storage, audit, and lifecycle operations are awaitable.
- **LangChain middleware:** guard `create_agent` and Deep Agents tool calls; scope by thread,
  append guidance, block configured kinds, and track outcomes.
- **Customizable:** ABCs for patterns, stores, and sinks; inject every agxai capability,
  plugin, configuration, and exporter.
- **Durable history:** LangGraph BaseStore adapter and PostgreSQL/Redis reference stores;
  persisted middleware halts and reusable conformance tests.
- **Reliable:** scope isolation, idempotent redelivery, atomic state transitions, and
  100% source line and branch coverage.

## Install

```bash
pip install behaviorweave
```

Or `uv add behaviorweave`. Supports Python 3.12 through 3.15.

## Quickstart

```python
import asyncio
from behaviorweave import BehaviorEngine, BehaviorEvent, InterventionType, PolicyRule


async def main():
    async with BehaviorEngine(
        policies=[
            PolicyRule("nudge", "repeated_tool_call", 2, InterventionType.NUDGE),
            PolicyRule("stop", "repeated_tool_call", 3, InterventionType.STOP),
        ]
    ) as engine:
        kinds = []
        for _ in range(3):
            decision = await engine.process(
                BehaviorEvent.tool_call("get_alarm", {"machine": "ETCH-3"}, scope="incident-42")
            )
            kinds.append(decision.intervention.kind.value)
        print(kinds)  # ['noop', 'nudge', 'stop']


asyncio.run(main())
```

### Guard a LangChain agent

<!-- skip-snippet: requires a configured provider-backed model and application tools -->
```python
from langchain.agents import create_agent
from behaviorweave.integrations.langchain import BehaviorWeaveMiddleware

agent = create_agent(model, tools=[get_alarm], middleware=[BehaviorWeaveMiddleware(engine)])
result = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "Inspect ETCH-3."}]},
    config={"configurable": {"thread_id": "incident-42"}},
)
```

The second identical call receives `[BehaviorWeave:nudge]` guidance. The third is blocked
before the tool runs. The engine returns decisions; enforcement belongs to the middleware
or your host application.

## Built-in patterns

| Pattern | Detects |
| --- | --- |
| `repeated_tool_call` | Consecutive identical tool calls. |
| `repeated_node_execution` | Consecutive executions of one node. |
| `failure_streak`, `retry_streak`, `success_streak` | Consecutive outcomes. |
| `delegation_streak` | Repeated delegation to one agent. |
| `oscillation` | Back-and-forth handoffs or delegations. |
| `event_frequency` | Total occurrences of each event identity. |

Policies select thresholds, priorities, per-policy cooldowns, once-only behavior, and
intervention kinds. Configure the built-in pattern classes or subclass the `Pattern` ABC.

## Integrations and customization

| Surface | Available customization |
| --- | --- |
| LangChain | Scope, block kinds, sync/async decision hook, formatter, middleware name. |
| LangGraph | Host-owned routing/checkpoints, event adapters, BaseStore namespace and TTL. |
| agxai | Config, registry, identity, plugins, custom capture, store, exporter, attribution, explanation, disclosure and capture policies. |
| Audit | Async `AuditSink`, in-memory sink, `CompositeAuditSink` fan-out, and `AgxaiAuditSink` for semantic decisions. |
| Metrics | `OpenTelemetryMetricsSink` counts decisions on any `MeterProvider` (`otel` extra). |
| Storage | Async `BehaviorStateStore` ABC with scope release, and PostgreSQL/Redis reference implementations. |
| MCP / Swarm / Deep Agents | Guards at real tool, delegation, and handoff boundaries. |

See the [downstream inventory](https://behaviorweave.readthedocs.io/en/latest/integrations/compatibility/).
agxai is used for provenance and explanations; BehaviorWeave owns behavioral decisions.

## Examples and Agent Skills

The [twenty async examples](https://github.com/smuniharish/behaviorweave/tree/master/examples)
cover middleware, MCP, graph loops, Swarm, Deep Agents, concurrent runs, durable databases,
agxai semantic audit, OpenTelemetry traces and metrics, and batch replay. Configure model credentials through environment
variables; database/OTel examples support local Podman services.

The [Agent Skills](https://github.com/smuniharish/behaviorweave/tree/master/behaviorweave-skills)
teach agents how to integrate and extend the package, with executable checks and evaluations.

## Documentation and project

- [Quickstart](https://behaviorweave.readthedocs.io/en/latest/getting-started/quickstart/)
- [Concepts](https://behaviorweave.readthedocs.io/en/latest/guide/concepts/events/)
- [Integrations](https://behaviorweave.readthedocs.io/en/latest/integrations/langchain/)
- [API reference](https://behaviorweave.readthedocs.io/en/latest/api/)
- [Changelog](https://github.com/smuniharish/behaviorweave/blob/master/CHANGELOG.md)
- [Contributing](https://github.com/smuniharish/behaviorweave/blob/master/CONTRIBUTING.md)
- [Code of Conduct](https://github.com/smuniharish/behaviorweave/blob/master/CODE_OF_CONDUCT.md)
- [Security](https://github.com/smuniharish/behaviorweave/blob/master/SECURITY.md)

Apache License 2.0. See [LICENSE](https://github.com/smuniharish/behaviorweave/blob/master/LICENSE).
