behaviorweave 0.1.0__py3-none-any.whl

behaviorweave/__init__.py

@@ -0,0 +1,27 @@
+"""Behavioral policy and intervention framework for graph agents."""
+
+from .engine import BehaviorEngine
+from .events import BehaviorEvent, EventType, Outcome
+from .interventions import AuditRecord, Intervention, InterventionDecision, InterventionType
+from .patterns import PatternObservation, built_in_patterns
+from .policies import PolicyEngine, PolicyRule
+from .state import BehaviorState, InMemoryBehaviorStateStore
+
+__all__ = [
+    "AuditRecord",
+    "BehaviorEngine",
+    "BehaviorEvent",
+    "BehaviorState",
+    "EventType",
+    "InMemoryBehaviorStateStore",
+    "Intervention",
+    "InterventionDecision",
+    "InterventionType",
+    "Outcome",
+    "PatternObservation",
+    "PolicyEngine",
+    "PolicyRule",
+    "built_in_patterns",
+]
+
+__version__ = "0.1.0"

behaviorweave/engine.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .events import BehaviorEvent
+from .interventions import Intervention, InterventionDecision, InterventionType
+from .patterns import Pattern, built_in_patterns
+from .policies import PolicyEngine, PolicyRule
+from .state import BehaviorStateStore, InMemoryBehaviorStateStore, with_cooldown
+
+
+class BehaviorEngine:
+    def __init__(
+        self,
+        *,
+        policies: Iterable[PolicyRule] = (),
+        patterns: Iterable[Pattern] | None = None,
+        state_store: BehaviorStateStore | None = None,
+    ) -> None:
+        self.store = state_store or InMemoryBehaviorStateStore()
+        self.patterns = tuple(patterns or built_in_patterns())
+        self.policy_engine = PolicyEngine(policies)
+        self._rules = self.policy_engine.rules
+
+    def process(self, event: BehaviorEvent) -> InterventionDecision:
+        decisions: list[InterventionDecision] = []
+        for pattern in self.patterns:
+            if pattern.matches(event):
+                observation = pattern.observe(event, self.store)
+                decision = self.policy_engine.evaluate(observation)
+                decisions.append(decision)
+                if decision.intervention.kind is not InterventionType.NOOP:
+                    rule = next(
+                        (r for r in self._rules if r.policy_id == decision.intervention.policy),
+                        None,
+                    )
+                    if rule and rule.cooldown:
+                        state = self.store.get(observation.state_key)
+                        if state:
+                            self.store.put(
+                                observation.state_key,
+                                with_cooldown(
+                                    state, event.timestamp + rule.cooldown, rule.policy_id
+                                ),
+                            )
+        if not decisions:
+            return InterventionDecision(intervention=Intervention(InterventionType.NOOP))
+        return max(
+            decisions,
+            key=lambda d: (
+                d.intervention.kind in {InterventionType.STOP, InterventionType.PAUSE},
+                d.intervention.kind is not InterventionType.NOOP,
+                d.explanation.count if d.explanation else 0,
+            ),
+        )

behaviorweave/events.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from hashlib import sha256
+from uuid import uuid4
+
+
+class EventType(StrEnum):
+    TOOL_CALL = "tool_call"
+    NODE_EXECUTION = "node_execution"
+    AGENT_HANDOFF = "agent_handoff"
+    DELEGATION = "delegation"
+    OUTCOME = "outcome"
+    RETRY = "retry"
+    CUSTOM = "custom"
+
+
+class Outcome(StrEnum):
+    SUCCESS = "success"
+    FAILURE = "failure"
+    RETRY = "retry"
+
+
+@dataclass(frozen=True, slots=True)
+class BehaviorEvent:
+    event_type: EventType
+    scope: str
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    event_id: str = field(default_factory=lambda: str(uuid4()))
+    execution_id: str | None = None
+    thread_id: str | None = None
+    run_id: str | None = None
+    node_name: str | None = None
+    tool_name: str | None = None
+    agent_name: str | None = None
+    target_agent: str | None = None
+    outcome: Outcome | None = None
+    metadata: Mapping[str, object] = field(default_factory=dict)
+    provenance_ref: str | None = None
+    fingerprint: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.scope.strip():
+            raise ValueError("scope must not be empty")
+        if self.timestamp.tzinfo is None:
+            raise ValueError("timestamp must be timezone-aware")
+
+    @classmethod
+    def tool_call(
+        cls,
+        tool_name: str,
+        arguments: Mapping[str, object] | None = None,
+        *,
+        scope: str,
+        event_id: str | None = None,
+    ) -> BehaviorEvent:
+        args = dict(arguments or {})
+        fingerprint = f"{tool_name}({json.dumps(args, sort_keys=True, separators=(',', ':'))})"
+        return cls(
+            EventType.TOOL_CALL,
+            scope=scope,
+            tool_name=tool_name,
+            metadata={"arguments": args},
+            event_id=event_id or str(uuid4()),
+            fingerprint=fingerprint,
+        )
+
+    @classmethod
+    def outcome_event(
+        cls,
+        outcome: Outcome,
+        *,
+        scope: str,
+        event_id: str | None = None,
+        metadata: Mapping[str, object] | None = None,
+    ) -> BehaviorEvent:
+        return cls(
+            EventType.OUTCOME,
+            scope=scope,
+            outcome=outcome,
+            event_id=event_id or str(uuid4()),
+            metadata=dict(metadata or {}),
+        )
+
+    def identity(self) -> str:
+        if self.event_type in {EventType.AGENT_HANDOFF, EventType.DELEGATION}:
+            return f"{self.agent_name or 'unknown'}->{self.target_agent or 'unknown'}"
+        raw = self.fingerprint or self.node_name or self.tool_name or self.agent_name
+        return raw or self.event_type.value
+
+    def idempotency_key(self) -> str:
+        return self.event_id or sha256(self.to_json().encode()).hexdigest()
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "event_type": self.event_type.value,
+            "scope": self.scope,
+            "timestamp": self.timestamp.isoformat(),
+            "event_id": self.event_id,
+            "execution_id": self.execution_id,
+            "thread_id": self.thread_id,
+            "run_id": self.run_id,
+            "node_name": self.node_name,
+            "tool_name": self.tool_name,
+            "agent_name": self.agent_name,
+            "target_agent": self.target_agent,
+            "outcome": self.outcome.value if self.outcome else None,
+            "metadata": dict(self.metadata),
+            "provenance_ref": self.provenance_ref,
+            "fingerprint": self.fingerprint,
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), sort_keys=True)

behaviorweave/integrations/__init__.py

@@ -0,0 +1 @@
+"""Framework integration boundaries."""

behaviorweave/integrations/langchain/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import LangChainEventAdapter
+
+__all__ = ["LangChainEventAdapter"]

behaviorweave/integrations/langchain/adapter.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ...events import BehaviorEvent, EventType, Outcome
+
+
+class LangChainEventAdapter:
+    """Adapter for public LangChain v1 callback payloads; no monkey-patching."""
+
+    def tool_start(
+        self, tool_name: str, *, scope: str, arguments: Mapping[str, object] | None = None
+    ) -> BehaviorEvent:
+        return BehaviorEvent.tool_call(tool_name, arguments, scope=scope)
+
+    def tool_error(self, *, scope: str, error_type: str) -> BehaviorEvent:
+        return BehaviorEvent.outcome_event(
+            Outcome.FAILURE, scope=scope, metadata={"error_type": error_type}
+        )
+
+    def retry(self, *, scope: str) -> BehaviorEvent:
+        return BehaviorEvent(EventType.RETRY, scope=scope, outcome=Outcome.RETRY)

behaviorweave/integrations/langgraph/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import LangGraphEventAdapter
+
+__all__ = ["LangGraphEventAdapter"]

behaviorweave/integrations/langgraph/adapter.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ...events import BehaviorEvent, EventType, Outcome
+
+
+class LangGraphEventAdapter:
+    """Translate public callback/runtime payloads into normalized events."""
+
+    def node(
+        self, node_name: str, *, scope: str, metadata: Mapping[str, object] | None = None
+    ) -> BehaviorEvent:
+        return BehaviorEvent(
+            EventType.NODE_EXECUTION,
+            scope=scope,
+            node_name=node_name,
+            metadata=dict(metadata or {}),
+        )
+
+    def tool(
+        self, tool_name: str, *, scope: str, arguments: Mapping[str, object] | None = None
+    ) -> BehaviorEvent:
+        return BehaviorEvent.tool_call(tool_name, arguments, scope=scope)
+
+    def outcome(self, outcome: Outcome, *, scope: str) -> BehaviorEvent:
+        return BehaviorEvent.outcome_event(outcome, scope=scope)

behaviorweave/integrations/langgraph_xai/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import LangGraphXAIEventAdapter
+
+__all__ = ["LangGraphXAIEventAdapter"]

behaviorweave/integrations/langgraph_xai/adapter.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ...events import BehaviorEvent, EventType
+
+
+class LangGraphXAIEventAdapter:
+    """Consume an xAI context reference without importing private xAI modules."""
+
+    def event(
+        self, payload: Mapping[str, object], *, scope: str, provenance_ref: str | None = None
+    ) -> BehaviorEvent:
+        raw_type = str(payload.get("event_type", EventType.CUSTOM.value))
+        try:
+            event_type = EventType(raw_type)
+        except ValueError:
+            event_type = EventType.CUSTOM
+        return BehaviorEvent(
+            event_type,
+            scope=scope,
+            node_name=_text(payload.get("node_name")),
+            tool_name=_text(payload.get("tool_name")),
+            agent_name=_text(payload.get("agent_name")),
+            target_agent=_text(payload.get("target_agent")),
+            metadata=dict(payload),
+            provenance_ref=provenance_ref,
+        )
+
+    @staticmethod
+    def instrument_graph(
+        graph: object,
+        *,
+        application_id: str = "behaviorweave",
+        tenant_id: str = "default",
+        graph_id: str = "graph",
+    ) -> object:
+        """Instrument a compiled graph through langgraph-xai's public runtime API."""
+        from langgraph_xai import XAIRuntime
+
+        runtime = XAIRuntime(application_id=application_id, tenant_id=tenant_id, graph_id=graph_id)
+        return runtime.instrument(graph)
+
+
+def _text(value: object) -> str | None:
+    return value if isinstance(value, str) else None

behaviorweave/interventions.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from .events import BehaviorEvent
+from .state import BehaviorState
+
+
+class InterventionType(StrEnum):
+    NOOP = "noop"
+    NUDGE = "nudge"
+    WARNING = "warning"
+    REDIRECT = "redirect"
+    RETRY = "retry"
+    ESCALATE = "escalate"
+    HUMAN_REVIEW = "human_review"
+    FORCE_SYNTHESIS = "force_synthesis"
+    PAUSE = "pause"
+    STOP = "stop"
+    CUSTOM = "custom"
+
+
+@dataclass(frozen=True, slots=True)
+class Intervention:
+    kind: InterventionType
+    message: str | None = None
+    reason: str = ""
+    pattern: str | None = None
+    policy: str | None = None
+    scope: str | None = None
+    severity: str = "info"
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class Explanation:
+    pattern: str
+    count: int
+    threshold: int | None
+    policy: str | None
+    reason: str
+    provenance_ref: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class InterventionDecision:
+    intervention: Intervention
+    explanation: Explanation | None = None
+    suppressed: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class AuditRecord:
+    """Immutable observable policy audit record; never contains chain-of-thought."""
+
+    event: BehaviorEvent
+    pattern: str | None
+    state: BehaviorState | None
+    decision: InterventionDecision

behaviorweave/patterns.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .events import BehaviorEvent, EventType, Outcome
+from .state import BehaviorState, BehaviorStateStore, advance_state
+
+
+@dataclass(frozen=True, slots=True)
+class PatternObservation:
+    pattern_id: str
+    scope: str
+    fingerprint: str
+    state_key: str
+    count: int
+    crossed: bool
+    state: BehaviorState
+    reason: str
+
+
+class Pattern(Protocol):
+    @property
+    def pattern_id(self) -> str: ...
+
+    def matches(self, event: BehaviorEvent) -> bool: ...
+    def observe(self, event: BehaviorEvent, store: BehaviorStateStore) -> PatternObservation: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ConsecutivePattern:
+    pattern_id: str
+    event_types: frozenset[EventType]
+    outcome: Outcome | None = None
+    identity_field: str = "identity"
+
+    def matches(self, event: BehaviorEvent) -> bool:
+        return event.event_type in self.event_types and (
+            self.outcome is None or event.outcome is self.outcome
+        )
+
+    def observe(self, event: BehaviorEvent, store: BehaviorStateStore) -> PatternObservation:
+        fingerprint = event.identity()
+        key = f"{event.scope}:{self.pattern_id}"
+        previous = store.get(key)
+        state = store.update(
+            key,
+            lambda current: advance_state(
+                current,
+                pattern_id=self.pattern_id,
+                scope=event.scope,
+                fingerprint=fingerprint,
+                event_id=event.idempotency_key(),
+                timestamp=event.timestamp,
+            ),
+        )
+        return PatternObservation(
+            self.pattern_id,
+            event.scope,
+            fingerprint,
+            key,
+            state.count,
+            state.count > (previous.count if previous else 0),
+            state,
+            f"{self.pattern_id} observed {state.count} consecutive times",
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class FrequencyPattern:
+    pattern_id: str
+    event_types: frozenset[EventType]
+    window_size: int = 10
+
+    def matches(self, event: BehaviorEvent) -> bool:
+        return event.event_type in self.event_types
+
+    def observe(self, event: BehaviorEvent, store: BehaviorStateStore) -> PatternObservation:
+        fingerprint = event.identity()
+        key = f"{event.scope}:{self.pattern_id}:{fingerprint}"
+        state = store.update(
+            key,
+            lambda current: advance_state(
+                current,
+                pattern_id=self.pattern_id,
+                scope=event.scope,
+                fingerprint=fingerprint,
+                event_id=event.idempotency_key(),
+                timestamp=event.timestamp,
+                consecutive=False,
+            ),
+        )
+        return PatternObservation(
+            self.pattern_id,
+            event.scope,
+            fingerprint,
+            key,
+            state.count,
+            True,
+            state,
+            f"{fingerprint} occurred {state.count} times",
+        )
+
+
+def built_in_patterns() -> tuple[Pattern, ...]:
+    return (
+        ConsecutivePattern("repeated_tool_call", frozenset({EventType.TOOL_CALL})),
+        ConsecutivePattern("repeated_node_execution", frozenset({EventType.NODE_EXECUTION})),
+        ConsecutivePattern("failure_streak", frozenset({EventType.OUTCOME}), Outcome.FAILURE),
+        ConsecutivePattern(
+            "retry_streak", frozenset({EventType.RETRY, EventType.OUTCOME}), Outcome.RETRY
+        ),
+        ConsecutivePattern("success_streak", frozenset({EventType.OUTCOME}), Outcome.SUCCESS),
+        ConsecutivePattern("delegation_streak", frozenset({EventType.DELEGATION})),
+        FrequencyPattern("event_frequency", frozenset(set(EventType))),
+    )

behaviorweave/policies.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import timedelta
+
+from .interventions import Explanation, Intervention, InterventionDecision, InterventionType
+from .patterns import PatternObservation
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyRule:
+    policy_id: str
+    pattern_id: str
+    threshold: int
+    intervention: InterventionType
+    priority: int = 0
+    cooldown: timedelta | None = None
+    once_only: bool = False
+    message: str | None = None
+    severity: str = "info"
+
+
+class PolicyEngine:
+    def __init__(self, rules: Iterable[PolicyRule] = ()) -> None:
+        self.rules = tuple(rules)
+
+    def evaluate(self, observation: PatternObservation) -> InterventionDecision:
+        candidates = [
+            r
+            for r in self.rules
+            if r.pattern_id == observation.pattern_id and observation.count >= r.threshold
+        ]
+        if not candidates:
+            return InterventionDecision(
+                Intervention(
+                    InterventionType.NOOP, pattern=observation.pattern_id, scope=observation.scope
+                )
+            )
+        rule = max(
+            candidates,
+            key=lambda r: (
+                r.priority,
+                r.threshold,
+                r.intervention in {InterventionType.STOP, InterventionType.PAUSE},
+            ),
+        )
+        state = observation.state
+        already = rule.policy_id in state.intervention_history
+        active = (
+            state.cooldown_until is not None
+            and state.last_seen is not None
+            and state.cooldown_until > state.last_seen
+        )
+        if (rule.once_only and already) or active:
+            return InterventionDecision(
+                Intervention(
+                    InterventionType.NOOP,
+                    reason="cooldown or once-only",
+                    pattern=rule.pattern_id,
+                    policy=rule.policy_id,
+                    scope=observation.scope,
+                ),
+                suppressed=True,
+            )
+        reason = rule.message or observation.reason
+        intervention = Intervention(
+            rule.intervention,
+            message=rule.message,
+            reason=reason,
+            pattern=rule.pattern_id,
+            policy=rule.policy_id,
+            scope=observation.scope,
+            severity=rule.severity,
+        )
+        return InterventionDecision(
+            intervention,
+            Explanation(
+                observation.pattern_id, observation.count, rule.threshold, rule.policy_id, reason
+            ),
+        )

behaviorweave/state.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import copy
+import json
+from collections.abc import Callable
+from dataclasses import dataclass, field, replace
+from datetime import UTC, datetime, timedelta
+from threading import RLock
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class BehaviorState:
+    pattern_id: str
+    scope: str
+    count: int = 0
+    first_seen: datetime | None = None
+    last_seen: datetime | None = None
+    previous_fingerprint: str | None = None
+    current_fingerprint: str | None = None
+    event_count: int = 0
+    window_start: datetime | None = None
+    window_end: datetime | None = None
+    threshold_state: bool = False
+    cooldown_until: datetime | None = None
+    intervention_history: tuple[str, ...] = ()
+    seen_event_ids: tuple[str, ...] = ()
+    metadata: dict[str, object] = field(default_factory=dict)
+    version: int = 0
+
+    def json(self) -> str:
+        data = (
+            {**self.__dict__}
+            if hasattr(self, "__dict__")
+            else {name: getattr(self, name) for name in self.__dataclass_fields__}
+        )
+        for key in ("first_seen", "last_seen", "window_start", "window_end", "cooldown_until"):
+            if data[key]:
+                data[key] = data[key].isoformat()
+        return json.dumps(data, sort_keys=True)
+
+
+class BehaviorStateStore(Protocol):
+    def get(self, key: str) -> BehaviorState | None: ...
+    def update(
+        self, key: str, fn: Callable[[BehaviorState | None], BehaviorState]
+    ) -> BehaviorState: ...
+    def put(self, key: str, state: BehaviorState) -> None: ...
+    def delete(self, key: str) -> None: ...
+
+
+class InMemoryBehaviorStateStore:
+    def __init__(self, ttl: timedelta | None = None) -> None:
+        self._states: dict[str, tuple[BehaviorState, datetime | None]] = {}
+        self._lock = RLock()
+        self._ttl = ttl
+
+    def get(self, key: str) -> BehaviorState | None:
+        with self._lock:
+            entry = self._states.get(key)
+            if entry is None:
+                return None
+            state, expires = entry
+            if expires and expires <= datetime.now(UTC):
+                del self._states[key]
+                return None
+            return copy.deepcopy(state)
+
+    def put(self, key: str, state: BehaviorState) -> None:
+        with self._lock:
+            expires = datetime.now(UTC) + self._ttl if self._ttl else None
+            self._states[key] = (copy.deepcopy(state), expires)
+
+    def update(
+        self, key: str, fn: Callable[[BehaviorState | None], BehaviorState]
+    ) -> BehaviorState:
+        with self._lock:
+            current = self.get(key)
+            updated = fn(current)
+            if updated.count < 0:
+                raise ValueError("behavior state count cannot be negative")
+            self.put(key, updated)
+            return copy.deepcopy(updated)
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._states.pop(key, None)
+
+
+def advance_state(
+    current: BehaviorState | None,
+    *,
+    pattern_id: str,
+    scope: str,
+    fingerprint: str,
+    event_id: str,
+    timestamp: datetime,
+    consecutive: bool = True,
+) -> BehaviorState:
+    if current and event_id in current.seen_event_ids:
+        return current
+    same = current is not None and current.current_fingerprint == fingerprint
+    count = (current.count + 1) if current and (same or not consecutive) else 1
+    seen = ((current.seen_event_ids if current else ()) + (event_id,))[-256:]
+    return BehaviorState(
+        pattern_id=pattern_id,
+        scope=scope,
+        count=count,
+        first_seen=current.first_seen if current and count > 1 else timestamp,
+        last_seen=timestamp,
+        previous_fingerprint=current.current_fingerprint if current else None,
+        current_fingerprint=fingerprint,
+        event_count=(current.event_count if current else 0) + 1,
+        window_start=current.window_start if current and count > 1 else timestamp,
+        window_end=timestamp,
+        threshold_state=current.threshold_state if current else False,
+        cooldown_until=current.cooldown_until if current else None,
+        intervention_history=current.intervention_history if current else (),
+        seen_event_ids=seen,
+        metadata=current.metadata if current else {},
+        version=(current.version if current else 0) + 1,
+    )
+
+
+def with_cooldown(state: BehaviorState, until: datetime, intervention: str) -> BehaviorState:
+    return replace(
+        state,
+        cooldown_until=until,
+        intervention_history=(*state.intervention_history, intervention),
+    )

behaviorweave-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,19 @@
+behaviorweave/__init__.py,sha256=RL6IZoOcehapokpF3TxlpBDS3gTHOkyxQjG5pnqRuxo,795
+behaviorweave/engine.py,sha256=qI2WTnQVZeYSf0-hhKP1LYAykbaDRIbk1hgFAQyvfLw,2392
+behaviorweave/events.py,sha256=pLBd9S69zKAXjzwe4LRshMu_535BYsgz5PL3JiOaOMs,3871
+behaviorweave/interventions.py,sha256=S6sCWMrXYQ-36AKmL-8tghAyW1Bww1R3kKKFHPdIAhg,1509
+behaviorweave/patterns.py,sha256=iSEdpzOoS3IEaEcChuPu5OivZofxrUgknqirAS0XHaU,3881
+behaviorweave/policies.py,sha256=DZQBvAdQdVRCPNfFQz1iFaB0FLwzYlUk4-HXyQMETIE,2722
+behaviorweave/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+behaviorweave/state.py,sha256=PZrlok9Fo88wIvMmePOuy5Olf548jXvPvIlLcRdParE,4732
+behaviorweave/integrations/__init__.py,sha256=NbCvMM3_fyEf1fHqJkZZm9ySSDUvnfpDbgGIh1bBc6o,41
+behaviorweave/integrations/langchain/__init__.py,sha256=XLWYK4e20AUTUWaojQDBlfDD0y6jOfy4jtyH-mPc-4M,83
+behaviorweave/integrations/langchain/adapter.py,sha256=IqazjclFG-VhPa8NNgEtU3sgmqM3yCrPuAwoz8Pn9Zs,817
+behaviorweave/integrations/langgraph/__init__.py,sha256=6zBXtF-6uFfQ4CBvxrrDbgKlSEnH8Nc32Jai3dxLfSg,83
+behaviorweave/integrations/langgraph/adapter.py,sha256=CjwVIyMgbfpW8D3N6OSGlLU6dwXAd-kMzT41Re1VPXM,915
+behaviorweave/integrations/langgraph_xai/__init__.py,sha256=h3Mg6Y6-Vcvx9sbkToJyR2wJIayQ_oB32lOP5WiMCbA,89
+behaviorweave/integrations/langgraph_xai/adapter.py,sha256=lM1x1Fj98WqtSlxNpcSATtteAH2WYyRP3E8fD7PRvA4,1593
+behaviorweave-0.1.0.dist-info/METADATA,sha256=mu6GrmE6aPVKKxRkjtT-3L83fCut_0zvYRfbZgLTDLI,4688
+behaviorweave-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+behaviorweave-0.1.0.dist-info/licenses/LICENSE,sha256=Dn-qZoMNVTHD58VIaIgQoMowI7-pUQ69KxOPJyikfZw,5890
+behaviorweave-0.1.0.dist-info/RECORD,,

behaviorweave-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

behaviorweave-0.1.0.dist-info/licenses/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