firstops 0.2.0__py3-none-any.whl

firstops/tools.py

@@ -0,0 +1,318 @@
+"""The base-API tool decorator — govern any callable.
+
+``@firstops.tool`` wraps a function so each call is forwarded to sentinel as a
+``pre_tool_use`` event (block / modify args) and a ``post_tool_use`` event
+(audit). It is the harness-agnostic floor: it audits everywhere and blocks
+where the surrounding harness propagates a raised exception (per the design's
+Discovery A, raising is the block mechanism for the base layer).
+
+Coverage is honest: a decorated tool is governed; an un-decorated one is not.
+For framework built-ins the developer never authored, use the harness adapter
+instead (it hooks the execution boundary).
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+import logging
+from typing import Any, Callable
+
+from firstops import _runtime
+from firstops.channels import classify, mcp_info
+from firstops.events import (
+    CHANNEL_MCP,
+    EVENT_POST_TOOL_USE,
+    EVENT_PRE_TOOL_USE,
+    ActionEvent,
+    Decision,
+)
+
+logger = logging.getLogger("firstops")
+
+# Attributes that mark an already-built framework tool object (LangChain
+# StructuredTool, LlamaIndex FunctionTool, etc.). We refuse to wrap these —
+# the user must decorate the underlying function before the framework wraps it.
+_TOOL_OBJECT_MARKERS = ("invoke", "ainvoke", "args_schema", "_run")
+
+
+# Names of tools governed by @firstops.tool this process — used by
+# firstops.coverage to reconcile declared-vs-governed and surface gaps.
+_GOVERNED_TOOLS: set[str] = set()
+
+
+def governed_tool_names() -> set[str]:
+    """Return the set of tool names governed by @firstops.tool."""
+    return set(_GOVERNED_TOOLS)
+
+
+class FirstOpsPolicyError(Exception):
+    """Raised when sentinel denies a governed tool call."""
+
+    def __init__(self, tool_name: str, reason: str, policy_id: str = ""):
+        self.tool_name = tool_name
+        self.reason = reason
+        self.policy_id = policy_id
+        super().__init__(f"FirstOps blocked tool {tool_name!r}: {reason}")
+
+
+def tool(fn: Callable | None = None, *, name: str | None = None):
+    """Decorator that governs a tool function. Usable as ``@tool`` or ``@tool(name=...)``."""
+
+    def decorator(func: Callable) -> Callable:
+        _check_wrappable(func)
+        tool_name = name or getattr(func, "__name__", "tool")
+        # Register BOTH the governance name and the function's __name__ so a
+        # coverage check that enumerates tools by either key sees it governed.
+        _GOVERNED_TOOLS.add(tool_name)
+        fn_name = getattr(func, "__name__", None)
+        if fn_name:
+            _GOVERNED_TOOLS.add(fn_name)
+
+        # Order matters: async-gen and generator are NOT coroutine functions,
+        # so they must be detected first or they'd fall into the sync wrapper
+        # and return an un-iterated (async)generator with the body unexecuted.
+        if inspect.isasyncgenfunction(func):
+            # Govern EAGERLY at call time (the wrapper is a plain function that
+            # returns the async generator), so a DENY blocks before any
+            # iteration rather than on the first __anext__.
+            @functools.wraps(func)
+            def agwrapper(*args: Any, **kwargs: Any):
+                args, kwargs = _govern(func, tool_name, args, kwargs)
+                return _agen_iterate(func, tool_name, args, kwargs)
+
+            return agwrapper
+
+        if inspect.isgeneratorfunction(func):
+
+            @functools.wraps(func)
+            def gwrapper(*args: Any, **kwargs: Any):
+                args, kwargs = _govern(func, tool_name, args, kwargs)
+                return _gen_iterate(func, tool_name, args, kwargs)
+
+            return gwrapper
+
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def awrapper(*args: Any, **kwargs: Any) -> Any:
+                args, kwargs = _govern(func, tool_name, args, kwargs)
+                result = None
+                error: Exception | None = None
+                try:
+                    result = await func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    error = e
+                    raise
+                finally:
+                    _audit_post(tool_name, result, error)
+
+            return awrapper
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            args, kwargs = _govern(func, tool_name, args, kwargs)
+            result = None
+            error: Exception | None = None
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception as e:
+                error = e
+                raise
+            finally:
+                _audit_post(tool_name, result, error)
+
+        return wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+# Sentinel marker for "the result is a stream we didn't materialize".
+_STREAM_SENTINEL = object()
+
+
+def _gen_iterate(func, tool_name, args, kwargs):
+    """Drive a generator tool, auditing once after it's exhausted/aborted."""
+    error: Exception | None = None
+    try:
+        yield from func(*args, **kwargs)
+    except Exception as e:
+        error = e
+        raise
+    finally:
+        _audit_post(tool_name, _STREAM_SENTINEL, error)
+
+
+async def _agen_iterate(func, tool_name, args, kwargs):
+    """Async analogue of :func:`_gen_iterate`."""
+    error: Exception | None = None
+    try:
+        async for item in func(*args, **kwargs):
+            yield item
+    except Exception as e:
+        error = e
+        raise
+    finally:
+        _audit_post(tool_name, _STREAM_SENTINEL, error)
+
+
+def _check_wrappable(func: Callable) -> None:
+    if (
+        inspect.isfunction(func)
+        or inspect.ismethod(func)
+        or inspect.iscoroutinefunction(func)
+        or inspect.isgeneratorfunction(func)
+        or inspect.isasyncgenfunction(func)
+    ):
+        return
+    if callable(func) and any(hasattr(func, m) for m in _TOOL_OBJECT_MARKERS):
+        raise TypeError(
+            f"@firstops.tool expects a plain function, not a built framework tool "
+            f"object ({type(func).__name__}). Decorate the underlying function "
+            f"before the framework wraps it (put @firstops.tool innermost)."
+        )
+    if not callable(func):
+        raise TypeError(f"@firstops.tool expects a callable, got {type(func).__name__}")
+    # Other callables (functools.partial, lambdas) are allowed.
+
+
+def _govern(
+    func: Callable, tool_name: str, args: tuple, kwargs: dict
+) -> tuple[tuple, dict]:
+    """Run the pre_tool_use evaluation and apply the decision to the call args."""
+    tool_input = _bind_inputs(func, args, kwargs)
+    decision = _evaluate_pre(tool_name, tool_input)
+    return _apply_pre(func, decision, tool_name, args, kwargs)
+
+
+def _jsonable(value: Any) -> Any:
+    try:
+        json.dumps(value)
+        return value
+    except (TypeError, ValueError):
+        return repr(value)
+
+
+def _bind_inputs(func: Callable, args: tuple, kwargs: dict) -> dict[str, Any]:
+    """Map a call's args/kwargs to a JSON-able {param: value} dict."""
+    try:
+        bound = inspect.signature(func).bind_partial(*args, **kwargs)
+        bound.apply_defaults()
+        return {k: _jsonable(v) for k, v in bound.arguments.items()}
+    except (TypeError, ValueError):
+        out: dict[str, Any] = {f"arg{i}": _jsonable(a) for i, a in enumerate(args)}
+        out.update({k: _jsonable(v) for k, v in kwargs.items()})
+        return out
+
+
+def _evaluate_pre(tool_name: str, tool_input: dict[str, Any]) -> Decision | None:
+    rt = _runtime.runtime()
+    if rt is None:
+        return None  # not initialized — no governance, run normally
+    channel = classify(tool_name)
+    event = ActionEvent(
+        event_type=EVENT_PRE_TOOL_USE,
+        tool_name=tool_name,
+        channel=channel,
+        tool_input=tool_input,
+        mcp=mcp_info(tool_name) if channel == CHANNEL_MCP else None,
+        # The decorator rebinds args from a modify payload, so request-path
+        # scrub is applicable — let sentinel ship modify, not escalate to deny.
+        producer_can_apply_modify=True,
+    )
+    return rt.enforcement.evaluate(event)
+
+
+def _apply_pre(
+    func: Callable, decision: Decision | None, tool_name: str, args: tuple, kwargs: dict
+) -> tuple[tuple, dict]:
+    if decision is None:
+        return args, kwargs
+    if decision.blocked:
+        raise FirstOpsPolicyError(tool_name, decision.reason, decision.policy_id)
+    if decision.modified and decision.modified_payload:
+        rebound = _rebind(func, decision.modified_payload, args, kwargs)
+        if rebound is not None:
+            return rebound
+        # We signalled producer_can_apply_modify, so sentinel shipped a scrub
+        # instead of a deny. If it doesn't fit the signature, fail CLOSED —
+        # running the tool with unscrubbed args is worse than blocking.
+        logger.warning(
+            "firstops: could not apply modify to %s; blocking (fail closed)", tool_name
+        )
+        raise FirstOpsPolicyError(
+            tool_name,
+            "policy required a modification this tool could not apply",
+            decision.policy_id,
+        )
+    return args, kwargs
+
+
+def _rebind(
+    func: Callable, payload: bytes, args: tuple, kwargs: dict
+) -> tuple[tuple, dict] | None:
+    """Overlay sentinel's scrubbed inputs onto the call, respecting param kinds.
+
+    Returns (args, kwargs) honoring positional-only / *args / **kwargs, or None
+    if the payload can't be applied (caller then falls open to original args).
+    """
+    try:
+        new_input = json.loads(payload)
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(new_input, dict):
+        return None
+    try:
+        sig = inspect.signature(func)
+        bound = sig.bind_partial(*args, **kwargs)
+        bound.apply_defaults()
+        merged = dict(bound.arguments)
+        merged.update(new_input)
+
+        out_args: list[Any] = []
+        out_kwargs: dict[str, Any] = {}
+        consumed = set()
+        for pname, param in sig.parameters.items():
+            if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                out_args.extend(merged.get(pname, ()) or ())
+            elif param.kind == inspect.Parameter.VAR_KEYWORD:
+                out_kwargs.update(merged.get(pname, {}) or {})
+            elif pname in merged:
+                if param.kind == inspect.Parameter.POSITIONAL_ONLY:
+                    out_args.append(merged[pname])
+                else:
+                    out_kwargs[pname] = merged[pname]
+            consumed.add(pname)
+        # Validate the reconstruction actually binds before returning it.
+        sig.bind(*out_args, **out_kwargs)
+        return tuple(out_args), out_kwargs
+    except (TypeError, ValueError):
+        return None
+
+
+def _audit_post(tool_name: str, result: Any, error: Exception | None = None) -> None:
+    """Emit a post_tool_use audit event. Best-effort: never affects the call."""
+    rt = _runtime.runtime()
+    if rt is None:
+        return
+    try:
+        if error is not None:
+            output: dict[str, Any] = {"error": repr(error)}
+        elif result is _STREAM_SENTINEL:
+            output = {"result": "<stream>"}
+        else:
+            output = {"result": _jsonable(result)}
+        event = ActionEvent(
+            event_type=EVENT_POST_TOOL_USE,
+            tool_name=tool_name,
+            channel=classify(tool_name),
+            tool_output=output,
+        )
+        rt.enforcement.evaluate(event)
+    except Exception as e:  # pragma: no cover - defensive
+        logger.debug("firstops post-eval failed for %s: %s", tool_name, e)

firstops-0.2.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: firstops
+Version: 0.2.0
+Summary: Govern MCP, tool calls, and LLM traffic for AI agents — across LangGraph, Claude Agent SDK, and OpenAI Agents.
+Project-URL: Homepage, https://firstops.dev
+Project-URL: Documentation, https://github.com/firstops-dev/firstops-python
+Project-URL: Repository, https://github.com/firstops-dev/firstops-python
+Project-URL: Issues, https://github.com/firstops-dev/firstops-python/issues
+Author-email: FirstOps <dev@firstops.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,claude,dpop,governance,guardrails,langchain,langgraph,llm,mcp,openai-agents,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: all
+Requires-Dist: claude-agent-sdk; extra == 'all'
+Requires-Dist: langchain-mcp-adapters; extra == 'all'
+Requires-Dist: langchain-openai; extra == 'all'
+Requires-Dist: langchain>=1.0; extra == 'all'
+Requires-Dist: langgraph; extra == 'all'
+Requires-Dist: openai-agents; extra == 'all'
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk; extra == 'claude'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langchain-mcp-adapters; extra == 'langgraph'
+Requires-Dist: langchain-openai; extra == 'langgraph'
+Requires-Dist: langchain>=1.0; extra == 'langgraph'
+Requires-Dist: langgraph; extra == 'langgraph'
+Provides-Extra: openai
+Requires-Dist: openai-agents; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# FirstOps Python SDK
+
+Govern what your AI agents do. FirstOps applies identity, policy enforcement, credential brokering, and audit to every **LLM call**, **tool call**, and **MCP call** your agent makes — across LangGraph, the Claude Agent SDK, and the OpenAI Agents SDK, or any custom loop.
+
+```bash
+pip install "firstops[langgraph]"   # or [claude], [openai], [all]
+```
+
+- **Python 3.10+**
+- Core deps: `cryptography`, `httpx`. Your agent framework comes in via the extra you pick.
+
+---
+
+## What FirstOps governs
+
+| Surface | How it's wired | What you get |
+|---|---|---|
+| **LLM calls** | point the model `base_url` at the local sidecar | inspect prompts/responses, scrub PII, block, audit |
+| **Tool calls** | one adapter (or `@firstops.tool`) | block / rewrite args / audit — including framework built-ins |
+| **MCP servers** | point the MCP client at the local proxy | server-side policy + **credential brokering** (the agent never holds the upstream token) |
+
+Every action is evaluated by FirstOps and returns `allow` / `deny` / `modify` — your agent logic doesn't change.
+
+## Quick start (LangGraph)
+
+```python
+import firstops
+from firstops.integrations.langgraph import FirstOpsMiddleware
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI
+
+fo = firstops.init(
+    agent_id="<agent-uuid>",                      # from the FirstOps dashboard
+    private_key_pem=open("agent-key.pem").read(),
+)
+
+# Route the LLM through FirstOps; wire one middleware to govern every tool call.
+llm = ChatOpenAI(model="gpt-4o-mini", base_url=firstops.llm_base_url("openai"), api_key="sk-...")
+agent = create_agent(model=llm, tools=[...], middleware=[FirstOpsMiddleware(fo)])
+
+agent.invoke({"messages": [{"role": "user", "content": "..."}]})
+```
+
+The whole integration is `init()` + a `base_url` swap + one middleware. See [`examples/`](examples/) for runnable agents, including MCP.
+
+## Other harnesses
+
+**Claude Agent SDK** — one `PreToolUse` hook governs every tool (built-ins, MCP, custom):
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions
+from firstops.integrations.claude import firstops_hooks
+
+options = ClaudeAgentOptions(hooks=firstops_hooks(fo), permission_mode="bypassPermissions")
+async for _ in query(prompt="...", options=options):
+    pass
+```
+
+**OpenAI Agents SDK** — a guardrail per tool + the model routed through the sidecar:
+
+```python
+from agents import Agent, function_tool, set_default_openai_client
+from firstops.integrations.openai_agents import firstops_tool_input_guardrail
+from openai import AsyncOpenAI
+
+set_default_openai_client(AsyncOpenAI(base_url=firstops.llm_base_url("openai"), api_key="sk-..."))
+guard = firstops_tool_input_guardrail(fo)
+
+@function_tool(tool_input_guardrails=[guard])
+def send_email(to: str, body: str) -> str: ...
+```
+
+**Any framework / custom loop** — the base API:
+
+```python
+@firstops.tool          # govern any callable: block / scrub args / audit
+def send_email(to: str, body: str): ...
+```
+
+## MCP servers
+
+Point your MCP client at the local proxy; FirstOps brokers the upstream credentials.
+
+```python
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+mcp = MultiServerMCPClient({"notion": {"url": firstops.mcp_url("<connection-id>"), "transport": "streamable_http"}})
+tools = await mcp.get_tools()
+```
+
+## Management client
+
+Provision agents and connections from your backend:
+
+```python
+from firstops import FirstOps
+
+admin = FirstOps(api_key="fo_key_...")
+agent = admin.agents.create(name="research-bot")      # -> id + private_key (shown once)
+admin.connections.register(principal_id=agent.id, name="slack", upstream_url="https://mcp.slack.com/sse")
+```
+
+## How it works
+
+`firstops.init()` starts a local sidecar and establishes the agent's identity (a DPoP-bound principal — RFC 9449). Tool and LLM actions are forwarded to the FirstOps gateway, which evaluates them against your policies and returns the verdict; MCP and LLM traffic flow through the sidecar with credentials brokered. Enforcement fails open on infrastructure errors; authentication fails closed.
+
+## Documentation
+
+- Guides: <https://firstops.dev/docs>
+- Repository: <https://github.com/firstops-dev/firstops-python>
+
+## License
+
+MIT

firstops-0.2.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+firstops/__init__.py,sha256=mkGIkRos4vMr3sOXNM6kWBAyIaY8JvyKQRaH8x3jFMk,1363
+firstops/_identity.py,sha256=SHUwdPsXZOgZBH15MNfk1NcvGK_0sFVVNJixB0Kl_Iw,2171
+firstops/_runtime.py,sha256=YUJ8ZrT-r83W6wFwT79OQlcj7tjB9_xVqdmGIoQmBnQ,4928
+firstops/channels.py,sha256=e14hhV6IYE8I3A9PZdzH59_sSzr7sfxDhkdexqg6etA,1445
+firstops/client.py,sha256=L6CgVbeHx0rrt5_quIfHxAyLMwBGMfQEf6jtTD_QT2c,14413
+firstops/coverage.py,sha256=ri-xyeANYPfzQr5kTreZ7R9ciI9sCEIJ6BQMHO1U-bE,2859
+firstops/dpop.py,sha256=CnrrRalG_JflWvHKXzWhPpfQxB_9aHPaph0GLgqT1CY,2765
+firstops/enforcement.py,sha256=1RxSlPSbUH2Hm1kLOYX7RCyd8cBc8gjTUg4e1l1a-gw,2751
+firstops/events.py,sha256=uiPow8-mefOW3kZz1JHLBkJoyX4ukTMcxQGllQFu0To,6779
+firstops/llm.py,sha256=LUHE_tzgtJ5T-GjY9aVq4yD7fhRmXxCqPblovcl4SSE,1753
+firstops/proxy.py,sha256=-ApBofk5yiOhpOfM7zFPad_PzSWJajUiPhC8GQ_xlPc,16283
+firstops/tools.py,sha256=_-py7p1DayfOFvMD-JeiR-sl581k1KSlg0RuOLonz0c,11642
+firstops/integrations/__init__.py,sha256=ItugNKg3EZ_mEM8hiExAGAUaTMTzYZ6ov0EexWqhemU,573
+firstops/integrations/_common.py,sha256=9gXsCoT9myPnjNPhGuRSkYHRrPNKQo4N-z1X6xZ0iQw,4615
+firstops/integrations/claude.py,sha256=ECjZZ557IoWpVo1pilLbF3QCAk_OfHa4ryL2gC73eDQ,3155
+firstops/integrations/langgraph.py,sha256=gHgRgr_05XmJkdoY_a8YvfviZYxS4lfJSQhmmArLg74,3395
+firstops/integrations/openai_agents.py,sha256=InP2g7NZ_Eh_RDuWgBa-8ZSZo8ZA_L8bRP9SigQFHwc,3406
+firstops-0.2.0.dist-info/METADATA,sha256=D7E2pjSyVykj38yyyUXXJhgnKda-OXF5bWc3bgojW-E,6269
+firstops-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+firstops-0.2.0.dist-info/licenses/LICENSE,sha256=4QQ3p8KL54k-TogpPIWwCf_EvT1H8PquBqcToweyzKA,1065
+firstops-0.2.0.dist-info/RECORD,,

firstops-0.2.0.dist-info/WHEEL

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

firstops-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FirstOps
+
+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.