tulip-frameworks 0.1.0__py3-none-any.whl

tulip_frameworks/__init__.py

@@ -0,0 +1,54 @@
+# Copyright 2026 Tulip Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Drop Tulip's control runtime into the agent framework you already use.
+
+``import tulip_frameworks`` exposes only the framework-agnostic core — it pulls in
+**no** third-party framework package. Import a bridge explicitly to use it::
+
+    from tulip_frameworks.langchain import gate_langchain_tool   # needs [langchain]
+    from tulip_frameworks.openai_agents import gate_openai_tool  # needs [openai-agents]
+
+Each bridge wraps the same primitive, :func:`tulip_frameworks.core.gate_callable`, so
+the action your agent already takes runs only after it clears the admission gate.
+"""
+
+from __future__ import annotations
+
+from tulip_frameworks.actions import (
+    ActionSpec,
+    asset_from_args,
+    default_action,
+    resolve_action,
+)
+from tulip_frameworks.approval import ApprovalBridge, gateway_bridge
+from tulip_frameworks.core import (
+    DENIED,
+    HELD,
+    Mode,
+    VerificationResult,
+    gate_callable,
+    held_result,
+    is_held,
+)
+from tulip_frameworks.policy_presets import action_gate_policy
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DENIED",
+    "HELD",
+    "ActionSpec",
+    "ApprovalBridge",
+    "Mode",
+    "VerificationResult",
+    "__version__",
+    "action_gate_policy",
+    "asset_from_args",
+    "default_action",
+    "gate_callable",
+    "gateway_bridge",
+    "held_result",
+    "is_held",
+    "resolve_action",
+]

tulip_frameworks/_sync.py

@@ -0,0 +1,37 @@
+# Copyright 2026 Tulip Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Run an async gated callable from a sync framework hook (CrewAI's ``_run``)."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def run_sync(awaitable: Awaitable[T]) -> T:
+    """Run ``awaitable`` to completion from sync code, loop-running or not.
+
+    CrewAI executes tools synchronously. If no event loop is running we use
+    :func:`asyncio.run`; if one is (rare for a sync tool body), we offload to a
+    worker thread so we don't try to nest loops.
+    """
+
+    async def _drive() -> T:
+        return await awaitable
+
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(_drive())
+
+    import concurrent.futures
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+        return pool.submit(asyncio.run, _drive()).result()
+
+
+__all__ = ["run_sync"]

tulip_frameworks/actions.py

@@ -0,0 +1,84 @@
+# Copyright 2026 Tulip Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Deriving a Tulip :class:`~tulip.security.Action` from a tool call.
+
+The gate reasons over an :class:`Action` — its ``asset``, ``blast_radius``,
+``environment``, ``kind`` and ``tags``. A bridge can supply that three ways:
+
+1. a constant :class:`Action` (risk is the same regardless of arguments),
+2. a callable ``(name, kwargs) -> Action`` (the recommended form — risk usually
+   varies with the call's arguments), or
+3. nothing, in which case :func:`default_action` builds a conservative one.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from tulip.control import Action
+
+#: An :class:`Action`, or a callable that derives one from ``(name, kwargs)``.
+ActionSpec = Action | Callable[[str, Mapping[str, Any]], Action]
+
+#: Argument names commonly naming the asset an action touches, in priority order.
+_ASSET_KEYS = (
+    "asset",
+    "host",
+    "hostname",
+    "target",
+    "resource",
+    "resource_id",
+    "account",
+    "user",
+    "username",
+    "email",
+    "order_id",
+    "id",
+    "ip",
+    "url",
+)
+
+
+def asset_from_args(kwargs: Mapping[str, Any]) -> str:
+    """Best-effort asset label from a tool call's arguments."""
+    for key in _ASSET_KEYS:
+        value = kwargs.get(key)
+        if value:
+            return str(value)
+    return ""
+
+
+def default_action(
+    name: str,
+    kwargs: Mapping[str, Any],
+    *,
+    environment: str = "unknown",
+    kind: str = "",
+) -> Action:
+    """A conservative :class:`Action` for ``name`` when none was supplied.
+
+    Fail-safe by construction: ``environment="unknown"`` plus the stock
+    :class:`~tulip.security.ControlPolicy` (which requires a verification score)
+    lands an un-verified call on ``require_human`` rather than auto-allowing it.
+    """
+    return Action(
+        name=name,
+        asset=asset_from_args(kwargs),
+        blast_radius=1,
+        environment=environment,
+        kind=kind,
+    )
+
+
+def resolve_action(spec: ActionSpec | None, name: str, kwargs: Mapping[str, Any]) -> Action:
+    """Resolve an :class:`ActionSpec` (or ``None``) into a concrete :class:`Action`."""
+    if spec is None:
+        return default_action(name, kwargs)
+    if isinstance(spec, Action):
+        return spec
+    return spec(name, kwargs)
+
+
+__all__ = ["ActionSpec", "asset_from_args", "default_action", "resolve_action"]

tulip_frameworks/adk.py

@@ -0,0 +1,85 @@
+# Copyright 2026 Tulip Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Google ADK bridge — gate an Agent Development Kit tool behind Tulip's gate.
+
+    from google.adk.agents import Agent
+    from google.adk.tools import FunctionTool
+    from tulip_frameworks.adk import gate_adk_tool
+    from tulip_frameworks.policy_presets import action_gate_policy
+    from tulip.control import Action, AuditTrail
+
+    def disable_user(email: str) -> str:
+        "Disable an account."
+        return idp.disable(email)
+
+    trail = AuditTrail()
+    gated = gate_adk_tool(
+        FunctionTool(func=disable_user),
+        action=lambda n, a: Action(name=n, asset=a["email"],
+            environment="production", kind="identity"),
+        policy=action_gate_policy(), trail=trail)
+    # agent = Agent(model="gemini-2.0-flash", tools=[gated])
+
+Accepts an ADK ``FunctionTool`` or a bare Python function. Needs the ``adk``
+extra: ``pip install tulip-frameworks[adk]``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tulip.control import AuditTrail, ControlPolicy
+from tulip.security import Evidence
+
+from tulip_frameworks.actions import ActionSpec
+from tulip_frameworks.approval import ApprovalBridge
+from tulip_frameworks.core import Mode, VerificationResult, gate_callable
+
+
+def _require_adk() -> Any:
+    try:
+        from google.adk.tools import FunctionTool
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ImportError("Google ADK support needs: pip install tulip-frameworks[adk]") from exc
+    return FunctionTool
+
+
+def gate_adk_tool(
+    tool: Any,
+    *,
+    action: ActionSpec,
+    policy: ControlPolicy,
+    trail: AuditTrail | None = None,
+    mode: Mode = "soft",
+    finding: Evidence | None = None,
+    verdict: VerificationResult | None = None,
+    principal: str = "agent",
+    approval: ApprovalBridge | None = None,
+) -> Any:
+    """Return an ADK ``FunctionTool`` whose action is gated by :func:`admit`.
+
+    ``tool`` may be an ADK ``FunctionTool`` or a plain function. The gated callable
+    keeps the original name, docstring, and signature (so ADK builds the right
+    function declaration), and runs the action only after it clears policy.
+    """
+    function_tool = _require_adk()
+    inner = getattr(tool, "func", tool)  # FunctionTool.func, or a bare function
+    name = str(getattr(tool, "name", None) or getattr(inner, "__name__", "tool"))
+    gated = gate_callable(
+        inner,
+        name=name,
+        action=action,
+        policy=policy,
+        trail=trail,
+        mode=mode,
+        finding=finding,
+        verdict=verdict,
+        principal=principal,
+        approval=approval,
+        serialize=True,  # a held result must be a string for the model
+    )
+    return function_tool(func=gated)
+
+
+__all__ = ["gate_adk_tool"]

tulip_frameworks/approval.py

@@ -0,0 +1,56 @@
+# Copyright 2026 Tulip Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Out-of-band approval — a small Protocol the gateway's broker already satisfies.
+
+When a tool is gated in ``mode="soft"`` and an action is held for a human, you can
+hand :func:`tulip_frameworks.core.gate_callable` an :class:`ApprovalBridge`. The held
+result then carries an ``approval_id`` the agent can poll, while a human approves or
+denies on a side channel the agent has no access to.
+
+This is a structural Protocol on purpose: it has **no import-time dependency** on
+``tulip-gateway`` (which is not yet on PyPI). ``tulip_gateway.policy.approval``'s
+``ApprovalBroker`` matches it in shape; :func:`gateway_bridge` adapts one when present.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ApprovalBridge(Protocol):
+    """Submit a held action for out-of-band approval and check its state."""
+
+    def submit(self, principal: str, tool: str, args: Mapping[str, Any]) -> str:
+        """Record a pending approval; return an id the agent can poll."""
+        ...
+
+    def state(self, approval_id: str) -> str | None:
+        """Current state for an id — e.g. ``"pending"`` / ``"approved"`` / ``"denied"``."""
+        ...
+
+
+def gateway_bridge(broker: Any) -> ApprovalBridge:
+    """Adapt a ``tulip_gateway`` ``ApprovalBroker`` to the :class:`ApprovalBridge` shape.
+
+    The broker's ``submit`` returns an ``ApprovalRecord``; this thin adapter returns
+    its ``approval_id`` instead, and maps ``get`` to :meth:`ApprovalBridge.state`.
+    """
+
+    class _Bridge:
+        def submit(self, principal: str, tool: str, args: Mapping[str, Any]) -> str:
+            record = broker.submit(principal, tool, dict(args))
+            return str(getattr(record, "approval_id", record))
+
+        def state(self, approval_id: str) -> str | None:
+            record = broker.get(approval_id)
+            if record is None:
+                return None
+            return str(getattr(record, "state", record))
+
+    return _Bridge()
+
+
+__all__ = ["ApprovalBridge", "gateway_bridge"]

tulip_frameworks/core.py

@@ -0,0 +1,177 @@
+# Copyright 2026 Tulip Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""The framework-agnostic gate — the only place that calls :func:`tulip.security.admit`.
+
+Every per-framework bridge (``langchain``, ``langgraph``, ``openai_agents``, …) is a
+thin re-wrapper around :func:`gate_callable`. Give it the callable that performs a
+side effect plus the :class:`~tulip.security.Action` that describes it, and it returns
+an async callable that runs the side effect **only** if the action clears policy —
+holding for a human or denying otherwise, and recording the decision on a
+tamper-evident :class:`~tulip.security.AuditTrail` either way.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any, Literal
+
+from tulip.control import (
+    Action,
+    AdmissionError,
+    AuditTrail,
+    ControlPolicy,
+    admit,
+)
+from tulip.security import (
+    Evidence,
+    as_json,
+)
+from tulip.security import (
+    VerificationResult as VerificationResult,
+    # re-exported for callers that pass a verification result,
+)
+
+from tulip_frameworks.actions import ActionSpec, resolve_action
+from tulip_frameworks.approval import ApprovalBridge
+
+#: How a held/denied action surfaces. ``"soft"`` returns an LLM-readable result the
+#: agent loop can react to; ``"raise"`` re-raises :class:`~tulip.security.AdmissionError`.
+Mode = Literal["soft", "raise"]
+
+#: ``status`` value on a soft-mode result when an action is held for a human.
+HELD = "held_for_approval"
+#: ``status`` value on a soft-mode result when an action is denied outright.
+DENIED = "denied"
+
+
+def _ensure_async(fn: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
+    """Adapt a sync-or-async callable into an awaitable one (called with kwargs)."""
+    if inspect.iscoroutinefunction(fn):
+        return fn
+
+    async def _wrapped(**kwargs: Any) -> Any:
+        result = fn(**kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    return _wrapped
+
+
+def held_result(
+    decision: Any,
+    *,
+    kwargs: Mapping[str, Any],
+    principal: str,
+    approval: ApprovalBridge | None,
+) -> dict[str, Any]:
+    """Build the structured result returned in soft mode when an action doesn't admit.
+
+    On ``require_human`` and an ``approval`` bridge is given, an approval is submitted
+    out of band and its id is embedded so the agent can poll for the human decision.
+    """
+    action: Action = decision.action
+    out: dict[str, Any] = {
+        "status": DENIED if decision.outcome == "deny" else HELD,
+        "outcome": decision.outcome,
+        "action": action.name,
+        "asset": action.asset,
+        "reason": decision.reason,
+    }
+    if decision.outcome != "deny" and approval is not None:
+        out["approval_id"] = approval.submit(principal, action.name, dict(kwargs))
+        out["next"] = "call approval_status(approval_id) once a human decides"
+    return out
+
+
+def gate_callable(
+    fn: Callable[..., Any],
+    *,
+    name: str,
+    action: ActionSpec,
+    policy: ControlPolicy,
+    trail: AuditTrail | None = None,
+    mode: Mode = "soft",
+    finding: Evidence | None = None,
+    verdict: VerificationResult | None = None,
+    principal: str = "agent",
+    approval: ApprovalBridge | None = None,
+    serialize: bool = False,
+) -> Callable[..., Awaitable[Any]]:
+    """Wrap ``fn`` so it runs only after its :class:`Action` clears the admission gate.
+
+    Args:
+        fn: The callable that performs the side effect (sync or async). Invoked with
+            the gated callable's keyword arguments.
+        name: A stable tool name used in the audit record and held result.
+        action: An :class:`~tulip.security.Action`, or a callable
+            ``(name, kwargs) -> Action`` that derives one per call (the recommended
+            form — risk usually varies with the arguments).
+        policy: The governing :class:`~tulip.security.ControlPolicy`. For arbitrary
+            tools with no verification, prefer
+            :func:`tulip_frameworks.policy_presets.action_gate_policy`.
+        trail: An :class:`~tulip.security.AuditTrail` to record every decision on.
+        mode: ``"soft"`` (default) returns a held/denied result the LLM can read;
+            ``"raise"`` re-raises :class:`~tulip.security.AdmissionError`.
+        finding / verdict: Optional grounded evidence + verification, forwarded to the
+            gate so a fully grounded caller gets the complete trust chain.
+        principal: Identity recorded against an out-of-band approval.
+        approval: Optional :class:`~tulip_frameworks.approval.ApprovalBridge` to submit
+            a ``require_human`` hold to (e.g. the gateway's broker).
+        serialize: If ``True``, the soft-mode held/denied result is returned as a JSON
+            string (what a string-typed tool result needs). If ``False`` (default), it
+            is returned as a ``dict``.
+
+    Returns:
+        An async callable. On allow it returns whatever ``fn`` returns; in soft mode
+        on hold/deny it returns the held result; in raise mode it raises.
+    """
+    perform_async = _ensure_async(fn)
+
+    async def gated(**kwargs: Any) -> Any:
+        act = resolve_action(action, name, kwargs)
+
+        async def perform() -> Any:
+            return await perform_async(**kwargs)
+
+        try:
+            return await admit(
+                act, perform, policy=policy, finding=finding, verdict=verdict, trail=trail
+            )
+        except AdmissionError as exc:
+            if mode == "raise":
+                raise
+            result = held_result(
+                exc.decision, kwargs=kwargs, principal=principal, approval=approval
+            )
+            return as_json(result) if serialize else result
+
+    gated.__name__ = name
+    # Preserve the wrapped tool's signature + docstring so frameworks that build
+    # their arg schema by introspecting the callable (ADK, LlamaIndex, …) see the
+    # real parameters rather than the gated wrapper's ``**kwargs``.
+    try:
+        gated.__signature__ = inspect.signature(fn)  # type: ignore[attr-defined]
+    except (TypeError, ValueError):
+        pass
+    if getattr(fn, "__doc__", None):
+        gated.__doc__ = fn.__doc__
+    return gated
+
+
+def is_held(result: Any) -> bool:
+    """Whether a soft-mode result represents a held/denied action (dict form)."""
+    return isinstance(result, Mapping) and result.get("status") in {HELD, DENIED}
+
+
+__all__ = [
+    "DENIED",
+    "HELD",
+    "Mode",
+    "VerificationResult",
+    "gate_callable",
+    "held_result",
+    "is_held",
+]

tulip_frameworks/crewai.py

@@ -0,0 +1,88 @@
+# Copyright 2026 Tulip Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""CrewAI bridge — gate a CrewAI tool's action behind Tulip's admission gate.
+
+    from crewai.tools import BaseTool
+    from tulip_frameworks.crewai import gate_crewai_tool
+    from tulip_frameworks.policy_presets import action_gate_policy
+    from tulip.control import Action, AuditTrail
+
+    trail = AuditTrail()
+    safe_tool = gate_crewai_tool(
+        my_refund_tool,
+        action=lambda n, a: Action(name=n, asset=a["order_id"],
+            kind="payment", environment="production"),
+        policy=action_gate_policy(), trail=trail)
+    # crew = Crew(agents=[agent], tasks=[task])  # agent uses safe_tool
+
+CrewAI runs tools synchronously, so the gated coroutine is driven via a sync bridge.
+Needs the ``crewai`` extra: ``pip install tulip-frameworks[crewai]``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tulip.control import AuditTrail, ControlPolicy
+from tulip.security import Evidence
+
+from tulip_frameworks._sync import run_sync
+from tulip_frameworks.actions import ActionSpec
+from tulip_frameworks.approval import ApprovalBridge
+from tulip_frameworks.core import Mode, VerificationResult, gate_callable
+
+
+def _require_crewai() -> Any:
+    try:
+        from crewai.tools import BaseTool
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ImportError("CrewAI support needs: pip install tulip-frameworks[crewai]") from exc
+    return BaseTool
+
+
+def gate_crewai_tool(
+    tool: Any,
+    *,
+    action: ActionSpec,
+    policy: ControlPolicy,
+    trail: AuditTrail | None = None,
+    mode: Mode = "soft",
+    finding: Evidence | None = None,
+    verdict: VerificationResult | None = None,
+    principal: str = "agent",
+    approval: ApprovalBridge | None = None,
+) -> Any:
+    """Return a CrewAI ``BaseTool`` whose action is gated by :func:`admit`.
+
+    Keeps the original ``name``, ``description`` and ``args_schema``. The wrapped
+    ``_run`` drives the async gate synchronously (CrewAI's execution model).
+    """
+    base_tool = _require_crewai()
+    inner = getattr(tool, "_run", None) or tool.run
+    gated = gate_callable(
+        inner,
+        name=tool.name,
+        action=action,
+        policy=policy,
+        trail=trail,
+        mode=mode,
+        finding=finding,
+        verdict=verdict,
+        principal=principal,
+        approval=approval,
+        serialize=True,  # a held result must be a string for the LLM
+    )
+
+    class _GatedTool(base_tool):  # type: ignore[misc, valid-type]
+        name: str = tool.name
+        description: str = tool.description
+        args_schema: Any = getattr(tool, "args_schema", None)
+
+        def _run(self, **kwargs: Any) -> Any:
+            return run_sync(gated(**kwargs))
+
+    return _GatedTool()
+
+
+__all__ = ["gate_crewai_tool"]

tulip_frameworks/langchain.py

@@ -0,0 +1,94 @@
+# Copyright 2026 Tulip Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""LangChain bridge — gate a LangChain tool's action behind Tulip's admission gate.
+
+    from langchain_core.tools import tool
+    from tulip_frameworks.langchain import gate_langchain_tool
+    from tulip_frameworks.policy_presets import action_gate_policy
+    from tulip.control import Action, AuditTrail
+
+    @tool
+    async def refund(order_id: str, amount_usd: float) -> str:
+        "Issue a customer refund."
+        return payments.refund(order_id, amount_usd)
+
+    trail = AuditTrail()
+    safe_refund = gate_langchain_tool(
+        refund,
+        action=lambda name, a: Action(name=name, asset=a["order_id"],
+            blast_radius=1, kind="payment", environment="production"),
+        policy=action_gate_policy(), trail=trail)
+    # agent = create_react_agent(model, tools=[safe_refund])
+
+Needs the ``langchain`` extra: ``pip install tulip-frameworks[langchain]``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from tulip.control import AuditTrail, ControlPolicy
+from tulip.security import Evidence
+
+from tulip_frameworks.actions import ActionSpec
+from tulip_frameworks.approval import ApprovalBridge
+from tulip_frameworks.core import Mode, VerificationResult, gate_callable
+
+if TYPE_CHECKING:
+    from langchain_core.tools import StructuredTool
+
+
+def _require_langchain() -> Any:
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ImportError(
+            "LangChain support needs: pip install tulip-frameworks[langchain]"
+        ) from exc
+    return StructuredTool
+
+
+def gate_langchain_tool(
+    tool: Any,
+    *,
+    action: ActionSpec,
+    policy: ControlPolicy,
+    trail: AuditTrail | None = None,
+    mode: Mode = "soft",
+    finding: Evidence | None = None,
+    verdict: VerificationResult | None = None,
+    principal: str = "agent",
+    approval: ApprovalBridge | None = None,
+) -> StructuredTool:
+    """Return a LangChain ``StructuredTool`` whose action is gated by :func:`admit`.
+
+    The returned tool keeps the original ``name``, ``description`` and ``args_schema``,
+    so it is a drop-in replacement in any agent/graph that consumed the original. It is
+    async (``coroutine``); use it where the runtime awaits tools (e.g. LangGraph).
+    """
+    structured_tool = _require_langchain()
+    # The underlying callable: prefer the async impl, else the sync one.
+    inner = getattr(tool, "coroutine", None) or tool.func
+    gated = gate_callable(
+        inner,
+        name=tool.name,
+        action=action,
+        policy=policy,
+        trail=trail,
+        mode=mode,
+        finding=finding,
+        verdict=verdict,
+        principal=principal,
+        approval=approval,
+        serialize=True,  # a held result must be a string for the LLM's tool message
+    )
+    return structured_tool.from_function(
+        coroutine=gated,
+        name=tool.name,
+        description=tool.description,
+        args_schema=tool.args_schema,
+    )
+
+
+__all__ = ["gate_langchain_tool"]