behaviorweave 0.1.0__tar.gz

behaviorweave-0.1.0/.env.example

@@ -0,0 +1,2 @@
+# Copy to .env locally, keep the real value out of git, and load it in your shell.
+EXPLABS_API_KEY=<your-api-key>

behaviorweave-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+on:
+  push:
+  pull_request:
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - run: uv run pytest
+      - run: uv run ruff check .
+      - run: uv run black --check .
+      - run: uv run pyrefly check
+      - run: uv run mkdocs build --strict
+      - run: uv build

behaviorweave-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyrefly/
+site/
+dist/
+build/
+*.egg-info/
+.coverage
+.env

behaviorweave-0.1.0/.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_install:
+      - pip install uv
+      - uv sync --extra dev
+mkdocs:
+  configuration: mkdocs.yml
+formats: all

behaviorweave-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+Initial alpha architecture and deterministic behavioral policy core.

behaviorweave-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+Use Python 3.12 and uv. Run:
+
+```text
+uv sync
+uv run pytest
+uv run ruff check .
+uv run black --check .
+uv run pyrefly check
+uv run mkdocs build --strict
+uv build
+```
+
+Keep pattern detection, policy selection, and intervention execution separate. Add
+tests for scope, duplicate delivery, concurrency, and serialization when changing
+state behavior.

behaviorweave-0.1.0/LICENSE

@@ -0,0 +1,89 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+      "You" shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, provided that You meet the following conditions:
+      (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+      (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You shall be under the terms and conditions of this License.
+
+   6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall any Contributor be liable to You for damages arising from this License.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the Work, You may offer and charge for support, warranty, indemnity, or other liability obligations.
+
+   END OF TERMS AND CONDITIONS
+
+Copyright 2026 Muni Harish

behaviorweave-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: behaviorweave
+Version: 0.1.0
+Summary: Behavioral policy and intervention framework for LangGraph and LangChain agents.
+Author: S Muni Harish
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,behavior,intervention,langchain,langgraph,policy
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: <3.13,>=3.12
+Requires-Dist: langchain>=1.0
+Requires-Dist: langgraph-xai>=0.1.0
+Requires-Dist: langgraph>=1.0
+Provides-Extra: dev
+Requires-Dist: black>=25.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: langchain[mcp]>=1.4; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.6; extra == 'dev'
+Requires-Dist: pyrefly>=0.18; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: deepagents; extra == 'examples'
+Requires-Dist: langgraph-swarm; extra == 'examples'
+Provides-Extra: mcp
+Requires-Dist: langchain[mcp]>=1.4; extra == 'mcp'
+Provides-Extra: real-model
+Requires-Dist: langchain-openai>=1.0; extra == 'real-model'
+Description-Content-Type: text/markdown
+
+# BehaviorWeave
+
+Behavioral policy and intervention framework for LangGraph and LangChain agents.
+
+BehaviorWeave observes normalized execution events, detects deterministic behavioral
+patterns, evaluates explicit policies, and emits intervention decisions. It does not
+execute interventions, replace LangGraph, capture chain-of-thought, or require LangSmith.
+
+## Why BehaviorWeave?
+
+Agent frameworks are designed to execute models, tools, routing, and graph transitions.
+They intentionally leave application-specific behavioral governance to the host system.
+That creates a gap when an otherwise capable agent starts repeating a tool call, cycling
+through retries, repeatedly delegating work, or continuing after a failure streak.
+
+BehaviorWeave fills that gap with a small, deterministic policy layer:
+
+- **Make recurring behavior explicit.** Normalize observable tool calls, node execution,
+  outcomes, retries, and delegations into events that can be evaluated consistently.
+- **Keep decisions explainable.** Policies map known patterns and thresholds to a
+  structured intervention with the pattern, count, scope, reason, and policy ID.
+- **Preserve framework ownership.** LangChain and LangGraph still own agent execution,
+  tool invocation, routing, persistence, and interrupts. Your application decides how
+  to apply a `nudge`, `pause`, `human_review`, or `stop` decision.
+- **Avoid prompt-only guardrails.** A prompt can ask an agent not to repeat itself, but
+  it cannot provide deterministic, scope-isolated behavioral history at the runtime
+  boundary.
+- **Support progressive intervention.** Start with a nudge, escalate after continued
+  behavior, or require human review without embedding policy logic into every tool or
+  graph node.
+
+Use BehaviorWeave when you need deterministic operational controls around observable
+agent behavior. It is not a replacement for model safety controls, authorization,
+schema validation, LangGraph persistence, or a general-purpose event-processing system.
+
+## Architecture
+
+```text
+LangGraph/LangChain -> langgraph-xai context -> BehaviorEvent
+  -> fingerprint -> pattern state -> policy -> InterventionDecision -> host runtime
+```
+
+The core is framework-neutral internally. Adapters at `behaviorweave.integrations`
+translate framework callbacks and preserve provenance references supplied by
+`langgraph-xai`.
+
+## Quickstart
+
+```python
+from behaviorweave import BehaviorEngine, BehaviorEvent, EventType, PolicyRule, InterventionType
+
+engine = BehaviorEngine(
+    policies=[PolicyRule("repeat-tool", "repeated_tool_call", 3, InterventionType.NUDGE)]
+)
+for i in range(3):
+    decision = engine.process(BehaviorEvent.tool_call("get_alarm", {"machine": "ETCH-3"},
+                                                     scope="thread-1"))
+assert decision.intervention.kind is InterventionType.NUDGE
+```
+
+Install with `uv sync`; see [docs](docs/index.md) for the full architecture and integrations.
+
+## Live integrations
+
+The checked-in tests are deterministic. The real execution examples construct LangChain
+v1 agents, call actual LangChain tools, and apply BehaviorWeave at the tool/delegation
+boundary. See [live examples](docs/live-examples.md) for the opt-in real model setup;
+provider credentials are read only from the environment.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

behaviorweave-0.1.0/README.md

@@ -0,0 +1,72 @@
+# BehaviorWeave
+
+Behavioral policy and intervention framework for LangGraph and LangChain agents.
+
+BehaviorWeave observes normalized execution events, detects deterministic behavioral
+patterns, evaluates explicit policies, and emits intervention decisions. It does not
+execute interventions, replace LangGraph, capture chain-of-thought, or require LangSmith.
+
+## Why BehaviorWeave?
+
+Agent frameworks are designed to execute models, tools, routing, and graph transitions.
+They intentionally leave application-specific behavioral governance to the host system.
+That creates a gap when an otherwise capable agent starts repeating a tool call, cycling
+through retries, repeatedly delegating work, or continuing after a failure streak.
+
+BehaviorWeave fills that gap with a small, deterministic policy layer:
+
+- **Make recurring behavior explicit.** Normalize observable tool calls, node execution,
+  outcomes, retries, and delegations into events that can be evaluated consistently.
+- **Keep decisions explainable.** Policies map known patterns and thresholds to a
+  structured intervention with the pattern, count, scope, reason, and policy ID.
+- **Preserve framework ownership.** LangChain and LangGraph still own agent execution,
+  tool invocation, routing, persistence, and interrupts. Your application decides how
+  to apply a `nudge`, `pause`, `human_review`, or `stop` decision.
+- **Avoid prompt-only guardrails.** A prompt can ask an agent not to repeat itself, but
+  it cannot provide deterministic, scope-isolated behavioral history at the runtime
+  boundary.
+- **Support progressive intervention.** Start with a nudge, escalate after continued
+  behavior, or require human review without embedding policy logic into every tool or
+  graph node.
+
+Use BehaviorWeave when you need deterministic operational controls around observable
+agent behavior. It is not a replacement for model safety controls, authorization,
+schema validation, LangGraph persistence, or a general-purpose event-processing system.
+
+## Architecture
+
+```text
+LangGraph/LangChain -> langgraph-xai context -> BehaviorEvent
+  -> fingerprint -> pattern state -> policy -> InterventionDecision -> host runtime
+```
+
+The core is framework-neutral internally. Adapters at `behaviorweave.integrations`
+translate framework callbacks and preserve provenance references supplied by
+`langgraph-xai`.
+
+## Quickstart
+
+```python
+from behaviorweave import BehaviorEngine, BehaviorEvent, EventType, PolicyRule, InterventionType
+
+engine = BehaviorEngine(
+    policies=[PolicyRule("repeat-tool", "repeated_tool_call", 3, InterventionType.NUDGE)]
+)
+for i in range(3):
+    decision = engine.process(BehaviorEvent.tool_call("get_alarm", {"machine": "ETCH-3"},
+                                                     scope="thread-1"))
+assert decision.intervention.kind is InterventionType.NUDGE
+```
+
+Install with `uv sync`; see [docs](docs/index.md) for the full architecture and integrations.
+
+## Live integrations
+
+The checked-in tests are deterministic. The real execution examples construct LangChain
+v1 agents, call actual LangChain tools, and apply BehaviorWeave at the tool/delegation
+boundary. See [live examples](docs/live-examples.md) for the opt-in real model setup;
+provider credentials are read only from the environment.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

behaviorweave-0.1.0/SECURITY.md

@@ -0,0 +1,8 @@
+# Security
+
+BehaviorWeave records observable execution metadata only. Do not put secrets, tokens,
+prompts containing credentials, or private model reasoning in event metadata. State
+serialization uses JSON and never evaluates policy strings or arbitrary code.
+
+In-memory state is process-local and should not be treated as a durable security
+boundary. Validate and redact payloads at the integration boundary.

behaviorweave-0.1.0/docs/PRODUCTION_READINESS.md

@@ -0,0 +1,20 @@
+# Production readiness
+
+| Area | Classification |
+|---|---|
+| Event/pattern/policy boundaries | Implemented and tested |
+| Scope isolation and engine isolation | Implemented and tested |
+| In-process concurrency | Implemented and tested |
+| Idempotency | Implemented and tested |
+| LangGraph-xAI public integration | Implemented; upstream API compatibility validated |
+| LangGraph/LangChain adapters | Implemented; local MCP tool execution tested |
+| Real provider execution | Flagship smoke scenarios validated manually; remains credential-dependent and opt-in |
+| Durable/distributed persistence | Future |
+| Swarm and Deep Agents adapters | Experimental examples |
+| Semantic detection | Future |
+| Security and privacy guidance | Implemented |
+| Package/docs/CI quality gates | Implemented and locally validated |
+
+The alpha release does not claim distributed state safety or stable upstream adapter
+contracts. Future roadmap items include Redis/PostgreSQL stores, richer temporal
+expressions, and OpenTelemetry hooks.

behaviorweave-0.1.0/docs/PROJECT_STRUCTURE.md

@@ -0,0 +1,18 @@
+# Project structure
+
+```text
+src/behaviorweave/
+  events.py                  immutable normalized events
+  state.py                   scoped atomic state store
+  patterns.py                composable behavioral detectors
+  policies.py                deterministic policy rules
+  interventions.py           decision and explanation models
+  engine.py                  orchestration boundary
+  integrations/              LangGraph, LangChain, and xAI adapters
+tests/                       deterministic unit and concurrency coverage
+examples/                    provider-free runnable demonstrations as single files
+docs/                        user, architecture, and compatibility documentation
+```
+
+Framework integrations translate observations only. Core modules never import private
+LangGraph or LangChain internals.

behaviorweave-0.1.0/docs/VALIDATION_REPORT.md

@@ -0,0 +1,45 @@
+# Validation report
+
+Executed in the repository on 2026-09-23:
+
+| Check | Result |
+|---|---|
+| Python | PASS — uv-managed CPython 3.12.14 |
+| uv | PASS — 0.12.15 |
+| BehaviorWeave | PASS — 0.1.0 |
+| langgraph | PASS — 1.2.12 |
+| langchain | PASS — 1.4.2; public `create_agent` signature inspected |
+| langgraph-xai | PASS — 0.1.0 |
+| langgraph-swarm | NOT TESTED — example extra not installed |
+| deepagents | NOT TESTED — example extra not installed |
+| pytest | PASS — 7 tests (including local stdio MCP discovery and execution) |
+| ruff | PASS |
+| black | PASS |
+| pyrefly | PASS |
+| MkDocs | PASS — strict build |
+| ReadTheDocs | NOT TESTED — configuration supplied |
+| wheel/sdist | PASS — `uv build` |
+| clean install | PASS — wheel built and editable environment imported |
+| real provider smoke test | PASS — owner executed provider-backed flagship examples on 2026-09-23 using an environment-local credential; see execution evidence below |
+| local stdio MCP discovery/execution | PASS — tool discovery and three guarded calls verified |
+| remote MCP/live provider execution | NOT TESTED — requires an endpoint and a credential |
+
+Commands used: `uv lock`, `uv sync --extra dev`, `uv run pytest -q`,
+`uv run ruff check .`, `uv run black --check .`, `uv run pyrefly check`,
+`uv run mkdocs build --strict`, and `uv build`.
+
+## Provider-backed smoke evidence
+
+The package owner executed the following opt-in examples locally on 2026-09-23. The
+credential remained in the owner's environment and was not copied into this report.
+
+| Example | Result |
+|---|---|
+| `examples/01_langchain_agent.py` | PASS — the live agent returned an alarm result, observed a repeated tool call, and received an instruction to reuse the existing result. |
+| `examples/03_langgraph_custom_graph.py` | PASS — the compiled LangGraph workflow returned a structured operational incident report. |
+| `examples/04_langgraph_multi_agent.py` | PASS — the live supervisor/specialist workflow returned a preliminary pressure-incident report with containment and investigation actions. |
+| `examples/15_complete_agent_guard.py` | PASS — the LangGraph plus `langgraph-xai` guarded-agent workflow returned a pressure warning, historical context, and recommended action. |
+
+Provider-generated prose is not asserted byte-for-byte because model responses are
+non-deterministic. The deterministic suite remains the source of behavioral
+regression assertions.