commitlayer-integrations 0.1.0__py3-none-any.whl

commitlayer_integrations/tools.py

@@ -0,0 +1,244 @@
+"""Record an agent framework's tool call as a CommitLayer action, before the tool runs.
+
+The framework adapters (``commitlayer_langgraph``, ``commitlayer_crewai``, ``commitlayer_openai_agents``,
+``commitlayer_pydantic_ai``) all do the same thing at different hook points: when the agent is about to call a
+tool whose name is mapped, post the intent as an action and let the call proceed. This module is that one
+thing, with no framework imported, so the body a tool call produces can be asserted in a unit test.
+
+The agent may declare its intent. It may read the verdict. It must never control the independent facts, the
+governing contract, or the final evidence. Recording is fail-open by default: a verifier that is down must not
+stop the business action, and the tool's own result is never sent anywhere.
+
+Mapping
+-------
+``tools`` maps a tool name to what to record for it, in the same shape the MCP recorder's mapping file uses::
+
+    {
+      "refund_payment": {
+        "contract_id": "refund_workflow",
+        "action_type": "refund_order",
+        "subject": "arguments.order_id",
+        "subject_kind": "order",
+        "params": {"amount": "arguments.amount", "currency": "arguments.currency"},
+        "action_id": "refund:{arguments.order_id}"
+      }
+    }
+
+Paths (``subject``, every ``params`` value, ``compensates``) are dotted paths into the call: ``arguments.x.y``
+reads the tool's arguments; a bare ``x`` is shorthand for ``arguments.x``; ``tool``, ``call_id`` and
+``run_id`` are the call's own fields. ``action_id`` is a template whose ``{...}`` placeholders are the same
+paths; without one the id is ``{channel}:{tool}:{call_id}`` so a retried call updates the one record.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+log = logging.getLogger("commitlayer.integrations")
+
+__all__ = ["ToolMapping", "ToolRecorder", "MappingError", "build_tool_action", "resolve_path"]
+
+
+class MappingError(LookupError):
+    """A path or template could not be resolved against the tool call."""
+
+
+@dataclass(frozen=True)
+class ToolMapping:
+    contract_id: str
+    subject: str
+    params: Mapping[str, str] = field(default_factory=dict)
+    action_id: str | None = None
+    action_type: str | None = None
+    subject_kind: str | None = None
+    compensates: str | None = None
+    contract_version: int | None = None
+
+    @classmethod
+    def coerce(cls, value: ToolMapping | Mapping[str, Any]) -> ToolMapping:
+        if isinstance(value, ToolMapping):
+            return value
+        unknown = set(value) - set(cls.__dataclass_fields__)
+        if unknown:
+            raise MappingError(f"unknown mapping keys: {sorted(unknown)}")
+        if "contract_id" not in value or "subject" not in value:
+            raise MappingError("a tool mapping needs contract_id and subject")
+        return cls(**dict(value))
+
+
+def _step(value: Any, key: str, path: str) -> Any:
+    if isinstance(value, Mapping):
+        if key in value:
+            return value[key]
+        raise MappingError(f"{path!r}: no key {key!r}")
+    if isinstance(value, Sequence) and not isinstance(value, str | bytes):
+        try:
+            return value[int(key)]
+        except (ValueError, IndexError) as e:
+            raise MappingError(f"{path!r}: no index {key!r}") from e
+    if hasattr(value, key):
+        return getattr(value, key)
+    raise MappingError(f"{path!r}: {type(value).__name__} has no attribute {key!r}")
+
+
+def resolve_path(path: str, call: Mapping[str, Any]) -> Any:
+    """``arguments.x.y`` into the call; ``x.y`` means ``arguments.x.y``; ``tool``/``call_id``/``run_id`` are the
+    call's own fields."""
+    if not isinstance(path, str) or not path:
+        raise MappingError(f"path must be a non-empty string, got {path!r}")
+    parts = path.split(".")
+    if parts[0] not in ("arguments", "tool", "call_id", "run_id"):
+        parts = ["arguments", *parts]
+    value: Any = call
+    for key in parts:
+        value = _step(value, key, path)
+    return value
+
+
+_PLACEHOLDER = re.compile(r"\{([^{}]+)\}")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")  # noqa: UP017 - Python 3.10
+
+
+def build_tool_action(
+    mapping: ToolMapping | Mapping[str, Any],
+    *,
+    tool: str,
+    arguments: Mapping[str, Any] | None,
+    call_id: str | None = None,
+    run_id: str | None = None,
+    channel: str = "agent",
+    agent_id: str | None = None,
+    workflow_id: str | None = None,
+    requested_at: str | None = None,
+) -> dict[str, Any]:
+    """The exact ``POST /v1/actions`` body for one tool call. Pure."""
+    m = ToolMapping.coerce(mapping)
+    call = {
+        "tool": tool,
+        "arguments": dict(arguments or {}),
+        "call_id": call_id or "",
+        "run_id": run_id or "",
+    }
+    subject = resolve_path(m.subject, call)
+    if subject is None or subject == "":
+        raise MappingError(f"subject path {m.subject!r} resolved to nothing")
+    params = {name: resolve_path(p, call) for name, p in m.params.items()}
+    if m.action_id:
+        action_id = _PLACEHOLDER.sub(lambda mm: str(resolve_path(mm.group(1), call)), m.action_id)
+    else:
+        action_id = f"{channel}:{tool}:{call_id or uuid.uuid4().hex}"
+    if not action_id or len(action_id) > 120:
+        raise MappingError(f"action_id {action_id!r} must be 1-120 characters")
+    body: dict[str, Any] = {
+        "action_id": action_id,
+        "contract_id": m.contract_id,
+        "subject_id": str(subject),
+        "requested_at": requested_at or _now(),
+        "params": {**params, "tool": tool, **({"tool_call_id": call_id} if call_id else {})},
+        "channel": channel,
+    }
+    for k, v in (
+        ("agent_id", agent_id),
+        ("workflow_id", workflow_id or (run_id or None)),
+        ("action_type", m.action_type),
+        ("subject_kind", m.subject_kind),
+        ("compensates", resolve_path(m.compensates, call) if m.compensates else None),
+        ("contract_version", m.contract_version),
+    ):
+        if v is not None:
+            body[k] = v
+    return body
+
+
+class ToolRecorder:
+    """Records mapped tool calls through a :class:`commitlayer.Client`.
+
+    ``client`` is the SDK client holding a *recorder* key. ``tools`` is the mapping described in the module
+    docstring; a key with a server prefix (``stripe.refund_payment``) also matches the bare name. ``channel``
+    names the framework and is stored on every action. With ``fail_open`` (the default) a failure to record is
+    logged and the tool call goes ahead; with ``fail_open=False`` the exception reaches the caller, which
+    frameworks turn into a tool error. ``on_recorded`` receives the API's answer (``{action, verification,
+    allowance}``) for every recorded call.
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        tools: Mapping[str, ToolMapping | Mapping[str, Any]],
+        *,
+        channel: str = "agent",
+        agent_id: str | None = None,
+        workflow_id: str | None = None,
+        fail_open: bool = True,
+        warn_unmapped: bool = False,
+        on_recorded: Callable[[dict[str, Any]], None] | None = None,
+    ):
+        self.client = client
+        self.tools = {name: ToolMapping.coerce(m) for name, m in tools.items()}
+        self.channel = channel
+        self.agent_id = agent_id
+        self.workflow_id = workflow_id
+        self.fail_open = fail_open
+        self.warn_unmapped = warn_unmapped
+        self.on_recorded = on_recorded
+        self.recorded: list[dict[str, Any]] = []  # the API's answers, newest last
+        self._warned: set[str] = set()
+
+    def mapping_for(self, tool: str) -> ToolMapping | None:
+        if tool in self.tools:
+            return self.tools[tool]
+        for name, m in self.tools.items():
+            if "." in name and name.rsplit(".", 1)[1] == tool:
+                return m
+        return None
+
+    def record(
+        self,
+        tool: str,
+        arguments: Mapping[str, Any] | None,
+        *,
+        call_id: str | None = None,
+        run_id: str | None = None,
+    ) -> dict[str, Any] | None:
+        """Record one tool call if its name is mapped. Returns the API's answer, or ``None`` when the tool is
+        unmapped or (fail-open) recording failed."""
+        m = self.mapping_for(tool)
+        if m is None:
+            if self.warn_unmapped and tool not in self._warned:
+                self._warned.add(tool)
+                log.warning("commitlayer: tool %r is not mapped; not recorded", tool)
+            return None
+        try:
+            body = build_tool_action(
+                m,
+                tool=tool,
+                arguments=arguments,
+                call_id=call_id,
+                run_id=run_id,
+                channel=self.channel,
+                agent_id=self.agent_id,
+                workflow_id=self.workflow_id,
+            )
+            out = self.client.request("POST", "/v1/actions", body)
+        except Exception as e:  # noqa: BLE001 - the business action must not depend on the verifier
+            if not self.fail_open:
+                raise
+            log.warning("commitlayer: tool call %r not recorded: %s", tool, e)
+            return None
+        self.recorded.append(out)
+        if self.on_recorded:
+            self.on_recorded(out)
+        return out
+
+    def wait(self, action_id: str, *, timeout: float = 300.0) -> dict[str, Any]:
+        """The settled verification for a recorded action (``GET /v1/actions/{id}/wait``), through the SDK."""
+        return self.client.wait_for_settlement(action_id, timeout=timeout)

commitlayer_integrations/verdict.py

@@ -0,0 +1,119 @@
+"""The verdict a workflow waits for, reduced to what a completion gate needs.
+
+``GET /v1/actions/{ref}`` returns a full ``ActionVerification`` (lenses, checks, evidence, facts). A workflow
+engine stores activity and step results in its history, so the integrations hand back a small, JSON-serialisable
+summary instead: both verdicts, the settlement status, the reason codes and the headline. The evidence stays
+on the CommitLayer side, where it belongs: the workflow reads the verdict, it never carries the proof.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any, TypedDict
+
+
+class Verdict(TypedDict):
+    action_id: str | None
+    contract_id: str | None
+    contract_version: int | None
+    status: str  # "pending" | "settled" | "unverified"
+    settled: bool
+    outcome: str | None  # "PASS" | "FAIL" | "UNKNOWN"
+    policy: str | None  # "PASS" | "FAIL" | "UNKNOWN"
+    passed: bool  # both lenses PASS and settled
+    reason_codes: dict[str, list[str]]
+    reason_labels: dict[str, list[str]]
+    headline: str | None
+    settles_at: str | None
+    verdict_hash: str | None
+    timed_out: bool
+
+
+def _lens(lenses: Any, name: str) -> dict[str, Any]:
+    lens = lenses.get(name) if isinstance(lenses, dict) else None
+    return lens if isinstance(lens, dict) else {}
+
+
+def summarize_verification(payload: dict[str, Any]) -> Verdict:
+    """Reduce an ``ActionVerification`` (or a bare ``Action``) to a :class:`Verdict`.
+
+    ``status`` is ``settled`` once the window has closed and every source has caught up, ``pending`` while the
+    verdict is provisional, and ``unverified`` when the action has never been verified (``latest`` is null).
+    ``passed`` is true only for a **settled** verdict that is PASS under both lenses; a provisional PASS is not
+    a completion signal.
+    """
+    action = payload.get("action") if isinstance(payload.get("action"), dict) else payload
+    lenses = payload.get("lenses") or {}
+    outcome, policy = _lens(lenses, "outcome"), _lens(lenses, "policy")
+    latest = action.get("latest") if isinstance(action.get("latest"), dict) else {}
+    outcome_verdict = outcome.get("verdict") or latest.get("outcome")
+    policy_verdict = policy.get("verdict") or latest.get("policy")
+    status = payload.get("status") or latest.get("status") or ("unverified" if not lenses else "pending")
+    settled = status == "settled"
+    contract = payload.get("contract") if isinstance(payload.get("contract"), dict) else {}
+    summary = payload.get("summary") if isinstance(payload.get("summary"), dict) else {}
+    return Verdict(
+        action_id=action.get("action_id"),
+        contract_id=action.get("contract_id") or contract.get("id"),
+        contract_version=action.get("contract_version") or contract.get("version"),
+        status=status,
+        settled=settled,
+        outcome=outcome_verdict,
+        policy=policy_verdict,
+        passed=bool(settled and outcome_verdict == "PASS" and policy_verdict == "PASS"),
+        reason_codes={
+            "outcome": list(outcome.get("reason_codes") or []),
+            "policy": list(policy.get("reason_codes") or []),
+        },
+        reason_labels={
+            "outcome": list(outcome.get("reason_labels") or []),
+            "policy": list(policy.get("reason_labels") or []),
+        },
+        headline=summary.get("headline"),
+        settles_at=payload.get("settles_at") or latest.get("settles_at"),
+        verdict_hash=policy.get("verdict_hash"),
+        timed_out=False,
+    )
+
+
+def fetch_verification(client: Any, action_ref: str, hold_seconds: float = 0.0) -> dict[str, Any]:
+    """One read of the verification. With ``hold_seconds`` the API's completion gate
+    (``GET /v1/actions/{ref}/wait?timeout=``) holds the request until the verdict settles or that many seconds
+    pass (60 at most), so a poll returns the moment the last expected effect lands; without it, a plain
+    ``GET /v1/actions/{ref}``."""
+    hold = max(0, min(60, int(hold_seconds)))
+    if hold <= 0:
+        return client.get_action(action_ref)
+    return client.request("GET", f"/v1/actions/{action_ref}/wait?timeout={hold}")
+
+
+def poll_until_settled(
+    fetch: Callable[[], dict[str, Any]],
+    *,
+    timeout_seconds: float,
+    poll_seconds: float = 5.0,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+    on_poll: Callable[[Verdict], None] | None = None,
+    should_stop: Callable[[], bool] | None = None,
+) -> Verdict:
+    """Call ``fetch`` (``GET /v1/actions/{ref}``) until the verification settles or ``timeout_seconds`` pass.
+
+    Returns the last :class:`Verdict` seen, with ``timed_out`` set when the deadline passed first. ``on_poll``
+    runs after every fetch (a Temporal heartbeat, a log line); ``should_stop`` is checked before every sleep and
+    ends the wait early with ``timed_out: True`` (a cancellation request). Errors from ``fetch`` propagate: a
+    verifier that cannot be reached is not a verdict.
+    """
+    deadline = clock() + timeout_seconds
+    while True:
+        verdict = summarize_verification(fetch())
+        if on_poll:
+            on_poll(verdict)
+        if verdict["settled"]:
+            return verdict
+        remaining = deadline - clock()
+        if remaining <= 0 or (should_stop and should_stop()):
+            verdict["timed_out"] = True
+            return verdict
+        sleep(min(poll_seconds, remaining))

commitlayer_integrations-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: commitlayer-integrations
+Version: 0.1.0
+Summary: CommitLayer integrations for agent frameworks and workflow runtimes: LangGraph, CrewAI, OpenAI Agents SDK, Pydantic AI, Temporal and Inngest
+Author-email: "Asterfold Labs, Inc." <hello@commitlayer.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://commitlayer.ai
+Project-URL: Documentation, https://commitlayer.ai/docs
+Project-URL: Changelog, https://commitlayer.ai/changelog
+Project-URL: Source, https://github.com/kobikwelu/stateprf-svcs/tree/main/integrations/python
+Keywords: ai-agents,verification,audit,mcp,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: commitlayer>=0.1.0
+Provides-Extra: temporal
+Requires-Dist: temporalio>=1.5; extra == "temporal"
+Provides-Extra: inngest
+Requires-Dist: inngest>=0.4; extra == "inngest"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=1.0; extra == "langgraph"
+Requires-Dist: langchain-core>=1.0; extra == "langgraph"
+Provides-Extra: crewai
+Requires-Dist: crewai>=1.0; extra == "crewai"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.4; extra == "openai-agents"
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim>=1.0; extra == "pydantic-ai"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: temporalio>=1.5; extra == "dev"
+Requires-Dist: inngest>=0.4; extra == "dev"
+Dynamic: license-file
+
+# commitlayer-integrations (Python)
+
+CommitLayer for agent frameworks and durable-workflow runtimes. One distribution, six optional packages, built on the
+[`commitlayer` SDK](../../sdk/python/README.md):
+
+| Package | Framework or runtime | Install |
+|---|---|---|
+| [`commitlayer_langgraph`](commitlayer_langgraph/README.md) | LangGraph, LangChain v1 agents | `pip install 'commitlayer-integrations[langgraph]'` |
+| [`commitlayer_crewai`](commitlayer_crewai/README.md) | CrewAI | `pip install 'commitlayer-integrations[crewai]'` |
+| [`commitlayer_openai_agents`](commitlayer_openai_agents/README.md) | OpenAI Agents SDK | `pip install 'commitlayer-integrations[openai-agents]'` |
+| [`commitlayer_pydantic_ai`](commitlayer_pydantic_ai/README.md) | Pydantic AI | `pip install 'commitlayer-integrations[pydantic-ai]'` |
+| [`commitlayer_temporal`](commitlayer_temporal/README.md) | Temporal (`temporalio`) | `pip install 'commitlayer-integrations[temporal]'` |
+| [`commitlayer_inngest`](commitlayer_inngest/README.md) | Inngest (`inngest`) | `pip install 'commitlayer-integrations[inngest]'` |
+
+The four framework packages share one mapping and one recorder (`commitlayer_integrations.tools.ToolRecorder`):
+a tool name maps to a contract, the argument that holds the subject, and the arguments that are the action's
+parameters, in the same shape the MCP recorder's mapping file uses. Each framework package is the hook at
+which that recorder runs: a `wrap_tool_call` wrapper for LangGraph, a `before_tool_call` hook for CrewAI,
+`RunHooks` for the OpenAI Agents SDK, a `WrapperToolset` for Pydantic AI. None of them imports its framework
+at module load, so the tests run without any of them installed.
+
+Each one does the same two things in its runtime's own terms:
+
+1. **Record the agent's intent before the work runs** (an activity, a step) as an action under a contract:
+   `POST /v1/actions` with the contract, subject and parameters taken from the call's own arguments. The
+   result of the work is never sent.
+2. **Gate completion on the verdict**: wait for `GET /v1/actions/{ref}` to report a *settled* verification and
+   branch on PASS / FAIL / UNKNOWN. The workflow does not tell the customer "done" until the verdict is PASS.
+
+The workflow engine makes the process durable. CommitLayer independently verifies the result, from the
+systems of record, after the fact. The agent may declare its intent. It may read the verdict. It must never
+control the independent facts, the governing contract, or the final evidence.
+
+Python 3.10+. Both packages import without their runtime SDK installed (the SDK is imported lazily), so a
+service that uses only one of them does not need the other.
+
+```bash
+pip install ./sdk/python ./integrations/python[temporal,inngest]   # from this repository
+export COMMITLAYER_API_KEY=spk_...                                   # never log or print it
+.venv/bin/python -m pytest integrations/python/tests -q              # no Temporal server, no Inngest dev server
+```

commitlayer_integrations-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+commitlayer_crewai/__init__.py,sha256=2VGPEOM1FXhFp-dyNrDMwRFXtGZ7MH-6TIkxgqmAT_I,3389
+commitlayer_inngest/__init__.py,sha256=d-qOYpcowojmr-oOdPIKGHofkp6eNSKXhwtysh91NT8,811
+commitlayer_inngest/steps.py,sha256=Mq5gNTKr1TXjqWECOpGUuFDQDflPZf8-AEK3y9MA9QQ,12960
+commitlayer_integrations/__init__.py,sha256=URPBvFvt7UCJP8jiZXpo4kfazwHAKRHhYOef_vhrqJA,381
+commitlayer_integrations/tools.py,sha256=VVBkPFDQm4l25XrG2Bx58jthJ0Rb-SIgMibDOiVkGho,9690
+commitlayer_integrations/verdict.py,sha256=2EESrr9xnQTVkfJPn8Ic3Gs8rTTwp5vk-zswq4Oi0sg,5445
+commitlayer_integrations-0.1.0.dist-info/licenses/LICENSE,sha256=0vhmIhIFNhgH1c9Yg3fPGr0tYr606CAcOisVbgKTbb8,1077
+commitlayer_langgraph/__init__.py,sha256=-A7mSMTX4smbIceNsSiEJGfn_91nmsGJQ8MRID1EgUg,5398
+commitlayer_openai_agents/__init__.py,sha256=P5jKsEbv0Edem225WylZqS3jGrnYuJ-D8NeUpx974Jk,3042
+commitlayer_pydantic_ai/__init__.py,sha256=wW7i5rXXIWqO50-cVbqAIHJe6_ZgYvlV0LH8_noP-Ak,2439
+commitlayer_temporal/__init__.py,sha256=lHDjZcfiubPcWb21YtmKVJxfc-DIjTdbp2Sg6OCyY4U,1663
+commitlayer_temporal/interceptor.py,sha256=TMdgtfSEQeMIGYUt4qcQRsxgMi8_N10Btx_rvbpQHmY,5420
+commitlayer_temporal/mapping.py,sha256=wwhJP7QbYI4quIS29E7Xo9W25thV2C3J79W9tr0KpTI,7673
+commitlayer_temporal/verifier.py,sha256=z_Bino7UdV56NKIEXDLQuzCEgX1geMLoaLbs8e886ZU,4785
+commitlayer_integrations-0.1.0.dist-info/METADATA,sha256=ny0-llKqq6xjYGCb7Gw0Z_8CafKGwaN8qh8aiwp2vmg,4871
+commitlayer_integrations-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+commitlayer_integrations-0.1.0.dist-info/top_level.txt,sha256=sM14akMmwD692F8a02p68hRtWXAm4IRO4d_P4zYWLyM,157
+commitlayer_integrations-0.1.0.dist-info/RECORD,,

commitlayer_integrations-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

commitlayer_integrations-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asterfold Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commitlayer_integrations-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,7 @@
+commitlayer_crewai
+commitlayer_inngest
+commitlayer_integrations
+commitlayer_langgraph
+commitlayer_openai_agents
+commitlayer_pydantic_ai
+commitlayer_temporal

commitlayer_langgraph/__init__.py

@@ -0,0 +1,111 @@
+"""CommitLayer for LangGraph and LangChain agents: record a tool call as an action before the tool runs.
+
+Two entry points, both built on :class:`commitlayer_integrations.tools.ToolRecorder`:
+
+* :func:`record_tool_calls` returns a ``wrap_tool_call`` function for ``langgraph.prebuilt.ToolNode`` and for
+  the LangChain v1 ``create_agent`` middleware list. It records the mapped call and then hands it to the
+  framework's handler unchanged; the tool's result is never sent to CommitLayer.
+* :func:`verdict_gate_node` returns a graph node that waits for a recorded action's verdict to settle and
+  writes it into the state, so the graph branches on PASS / FAIL / UNKNOWN instead of on the tool's own word.
+
+Nothing here imports LangGraph or LangChain: the wrapper and the node are plain callables with the shapes
+those libraries call, so this module works with any version that keeps them, and can be unit-tested without
+either installed.
+
+    from commitlayer import Client
+    from commitlayer_langgraph import record_tool_calls
+    from langgraph.prebuilt import ToolNode
+
+    recorder = ToolRecorder(Client(agent_id="support-bot"), MAPPING)
+    tools = ToolNode([refund_payment, close_ticket], wrap_tool_call=record_tool_calls(recorder))
+
+    # or, with LangChain v1 agents:
+    from langchain.agents import create_agent
+    agent = create_agent(model, tools=[...], middleware=[record_tool_calls(recorder)])
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from commitlayer_integrations.tools import ToolRecorder
+
+__all__ = ["record_tool_calls", "verdict_gate_node", "CHANNEL"]
+
+CHANNEL = "langgraph"
+
+
+def _call_fields(request: Any) -> tuple[str, dict[str, Any], str | None, str | None]:
+    """Tool name, arguments, tool call id and run id from a ``ToolCallRequest`` (or anything shaped like one)."""
+    tc = getattr(request, "tool_call", None) or {}
+    name = tc.get("name") if isinstance(tc, Mapping) else getattr(tc, "name", None)
+    args = tc.get("args") if isinstance(tc, Mapping) else getattr(tc, "args", None)
+    call_id = tc.get("id") if isinstance(tc, Mapping) else getattr(tc, "id", None)
+    run_id = None
+    runtime = getattr(request, "runtime", None)
+    config = getattr(runtime, "config", None) if runtime is not None else None
+    if isinstance(config, Mapping):
+        run_id = (config.get("metadata") or {}).get("thread_id") or (config.get("configurable") or {}).get(
+            "thread_id"
+        )
+    return str(name or ""), dict(args or {}), call_id, run_id
+
+
+def record_tool_calls(recorder: ToolRecorder) -> Callable[[Any, Callable[[Any], Any]], Any]:
+    """A ``wrap_tool_call(request, handler)`` function that records the mapped call, then runs it.
+
+    Works as the ``wrap_tool_call`` argument of ``ToolNode`` and as an item of ``create_agent``'s
+    ``middleware`` list (LangChain accepts a bare function there through its ``@wrap_tool_call`` decorator;
+    pass ``langchain.agents.middleware.wrap_tool_call(record_tool_calls(recorder))`` on versions that require
+    the decorator). The recorder's ``channel`` is set to ``langgraph`` unless it already names something else.
+    """
+    if recorder.channel == "agent":
+        recorder.channel = CHANNEL
+
+    def wrap_tool_call(request: Any, handler: Callable[[Any], Any]) -> Any:
+        name, args, call_id, run_id = _call_fields(request)
+        if name:
+            recorder.record(name, args, call_id=call_id, run_id=run_id)
+        return handler(request)
+
+    wrap_tool_call.__name__ = "commitlayer_record_tool_calls"
+    return wrap_tool_call
+
+
+def verdict_gate_node(
+    recorder: ToolRecorder,
+    *,
+    action_id: Callable[[Mapping[str, Any]], str | None] | str = "commitlayer_action_id",
+    key: str = "commitlayer_verdict",
+    timeout: float = 300.0,
+) -> Callable[[Mapping[str, Any]], dict[str, Any]]:
+    """A node that waits for a recorded action's verdict to settle and writes it into the state.
+
+    ``action_id`` is the state key holding the action id (default ``commitlayer_action_id``) or a callable
+    over the state returning it; when it is missing, the node uses the last action the recorder recorded.
+    The node returns ``{key: {"status", "outcome", "policy", "headline", "verification"}}``; a conditional
+    edge then routes PASS to the happy path and FAIL or UNKNOWN to recovery. A timeout is reported as
+    ``status: "pending"`` and is the graph's decision, never a success.
+    """
+
+    def node(state: Mapping[str, Any]) -> dict[str, Any]:
+        aid = action_id(state) if callable(action_id) else state.get(action_id)
+        if not aid and recorder.recorded:
+            aid = (recorder.recorded[-1].get("action") or {}).get("action_id")
+        if not aid:
+            return {key: {"status": "unrecorded", "outcome": None, "policy": None, "headline": None}}
+        v = recorder.wait(str(aid), timeout=timeout)
+        lenses = v.get("lenses") or {}
+        return {
+            key: {
+                "status": "pending" if v.get("timed_out") else v.get("status"),
+                "outcome": (lenses.get("outcome") or {}).get("verdict"),
+                "policy": (lenses.get("policy") or {}).get("verdict"),
+                "headline": (v.get("summary") or {}).get("headline"),
+                "verification": v,
+            }
+        }
+
+    node.__name__ = "commitlayer_verdict_gate"
+    return node