nodloop 0.6.6__py3-none-any.whl

nodloop/__init__.py

@@ -0,0 +1,5 @@
+"""Record AI runs and the verdicts people give on them, and hand the knowledge they approve to the next run in the same place"""
+
+from .client import Client, Decision, Item, Knowledge, ToolError
+
+__all__ = ["Client", "Decision", "Item", "Knowledge", "ToolError"]

nodloop/binary.py

@@ -0,0 +1,67 @@
+"""Finds the nodloop binary the client runs and fetches the release one when there is none."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import platform
+import shutil
+import tarfile
+import urllib.request
+from pathlib import Path
+
+REPO = "jeon-jihyeon/nodloop"
+
+
+def home_bin() -> Path:
+    return Path.home() / ".nodloop" / "bin"
+
+
+def find(version: str) -> str:
+    """The binary to run.
+
+    1. NODLOOP_BIN when it is set
+    2. the stable link the Claude Code plugin keeps under ~/.nodloop/bin
+    3. nodloop on PATH
+    4. the release of the version, fetched once into ~/.nodloop/bin/v<version> and checked against its checksums
+    """
+    if env := os.environ.get("NODLOOP_BIN"):
+        return env
+    stable = home_bin() / "nodloop"
+    if stable.exists():
+        return str(stable)
+    if found := shutil.which("nodloop"):
+        return found
+    return str(fetch(version))
+
+
+def archive_name() -> str:
+    system = platform.system().lower()
+    machine = {"x86_64": "amd64", "amd64": "amd64", "arm64": "arm64", "aarch64": "arm64"}[platform.machine().lower()]
+    return f"nodloop_{system}_{machine}.tar.gz"
+
+
+def fetch(version: str) -> Path:
+    """The release binary of the version, refused when its archive does not match checksums.txt."""
+    target = home_bin() / f"v{version}" / "nodloop"
+    if target.exists():
+        return target
+    base = f"https://github.com/{REPO}/releases/download/v{version}"
+    name = archive_name()
+    archive = urllib.request.urlopen(f"{base}/{name}", timeout=60).read()
+    sums = urllib.request.urlopen(f"{base}/checksums.txt", timeout=30).read().decode()
+    want = next((line.split()[0] for line in sums.splitlines() if line.split()[1:] == [name]), "")
+    if not want or hashlib.sha256(archive).hexdigest() != want:
+        raise RuntimeError(f"checksum of {base}/{name} does not match checksums.txt")
+    with tarfile.open(fileobj=io.BytesIO(archive)) as tar:
+        member = tar.extractfile("nodloop")
+        if member is None:
+            raise RuntimeError(f"{name} holds no nodloop binary")
+        data = member.read()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    partial = target.with_suffix(".partial")
+    partial.write_bytes(data)
+    partial.chmod(0o755)
+    partial.replace(target)
+    return target

nodloop/claude_agent.py

@@ -0,0 +1,65 @@
+"""Claude Agent SDK hooks for nodloop, the same loop the Claude Code plugin runs
+
+1. UserPromptSubmit adds the approved items of the place as context
+2. Stop records the last answer as a run naming the items it got
+3. PreToolUse denies a call an approved veto blocks and asks about one it hands to a person
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from claude_agent_sdk import HookMatcher
+
+from .client import Client, Item
+
+Labels = dict[str, list[str]]
+
+
+class NodloopHooks:
+    """Pass hooks() as the hooks of ClaudeAgentOptions
+
+    Use one instance per conversation because it keeps the items of the turn and the id of the last run
+    """
+
+    def __init__(self, client: Client, producer: str, labels: Labels | None = None) -> None:
+        self.client = client
+        self.producer = producer
+        self.labels = labels or {}
+        self.applied: list[Item] = []
+        # The run the last answer was recorded as so a verdict can cite it
+        self.run: str = ""
+
+    def hooks(self) -> dict[str, list[HookMatcher]]:
+        return {
+            "UserPromptSubmit": [HookMatcher(hooks=[self.prompt])],
+            "Stop": [HookMatcher(hooks=[self.stop])],
+            "PreToolUse": [HookMatcher(hooks=[self.pre_tool_use])],
+        }
+
+    async def prompt(self, input_data: dict[str, Any], tool_use_id: str | None, context: Any) -> dict[str, Any]:
+        knowledge = await self.client.knowledge(self.producer, self.labels)
+        self.applied = knowledge.items
+        if not knowledge.text:
+            return {}
+        return {"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": knowledge.text}}
+
+    async def stop(self, input_data: dict[str, Any], tool_use_id: str | None, context: Any) -> dict[str, Any]:
+        # Claude Code sends the last answer under last_assistant_message
+        # A turn without one records nothing
+        answer = input_data.get("last_assistant_message") or ""
+        if answer.strip():
+            self.run = await self.client.record(self.producer, answer, self.labels, self.applied)
+        return {}
+
+    async def pre_tool_use(self, input_data: dict[str, Any], tool_use_id: str | None, context: Any) -> dict[str, Any]:
+        decision = await self.client.check_call(input_data["tool_name"], input_data.get("tool_input") or {}, self.producer)
+        if decision.allowed:
+            return {}
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny" if decision.action == "block" else "ask",
+                "permissionDecisionReason": f"nodloop veto {decision.veto}: {decision.reason}",
+            }
+        }

nodloop/client.py

@@ -0,0 +1,206 @@
+"""The client of the nodloop MCP tools over a local binary or a nodloop server"""
+
+from __future__ import annotations
+
+import json
+import os
+from contextlib import AsyncExitStack
+from dataclasses import dataclass, field
+from typing import Any
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client
+
+from . import binary
+
+__all__ = ["Client", "Decision", "Item", "Knowledge", "ToolError"]
+
+# The binary release the client fetches when no nodloop is installed
+VERSION = "0.6.6"
+
+
+class ToolError(RuntimeError):
+    """A tool answered an error such as a refused proposal"""
+
+
+@dataclass(frozen=True)
+class Item:
+    """One approved knowledge version a run receives"""
+
+    id: str
+    version: int
+    kind: str
+    content: str
+    scope: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def ref(self) -> dict[str, Any]:
+        return {"id": self.id, "version": self.version}
+
+
+@dataclass(frozen=True)
+class Decision:
+    """What a tool call may do: allow, block or ask"""
+
+    action: str
+    veto: str = ""
+    reason: str = ""
+
+    @property
+    def allowed(self) -> bool:
+        return self.action == "allow"
+
+
+@dataclass(frozen=True)
+class Knowledge:
+    """The approved items a run receives and the text that carries them into its prompt"""
+
+    items: list[Item]
+    # Empty without items so a prompt gains nothing
+    text: str
+
+
+class Client:
+    """The nodloop tools of one process or of a nodloop server
+
+    1. by default it starts `nodloop mcp` over stdio, so nothing runs as a server
+    2. record_dir names the records and else NODLOOP_RECORD_DIR, config.json or ~/.nodloop/records decide as in the CLI
+    3. url and key connect to `nodloop server serve` instead, where the key decides the tenant and the role
+    4. use it as an async context manager so the process or the connection ends with the block
+    """
+
+    def __init__(
+        self,
+        record_dir: str | None = None,
+        binary_path: str | None = None,
+        url: str | None = None,
+        key: str | None = None,
+    ) -> None:
+        self._record_dir = record_dir
+        self._binary = binary_path
+        self._url = url
+        self._key = key
+        self._stack = AsyncExitStack()
+        self._session: ClientSession | None = None
+
+    async def __aenter__(self) -> Client:
+        try:
+            await self._connect()
+        except BaseException:
+            # A failed handshake such as a refused key closes what it opened since __aexit__ never runs
+            await self._stack.aclose()
+            raise
+        return self
+
+    async def _connect(self) -> None:
+        if self._url:
+            http = create_mcp_http_client(headers={"Authorization": f"Bearer {self._key}"} if self._key else None)
+            await self._stack.enter_async_context(http)
+            streams = await self._stack.enter_async_context(streamable_http_client(self._url, http_client=http))
+        else:
+            env = dict(os.environ)
+            if self._record_dir:
+                env["NODLOOP_RECORD_DIR"] = os.path.abspath(self._record_dir)
+            params = StdioServerParameters(command=self._binary or binary.find(VERSION), args=["mcp"], env=env)
+            streams = await self._stack.enter_async_context(stdio_client(params))
+        read, write = streams[0], streams[1]
+        self._session = await self._stack.enter_async_context(ClientSession(read, write))
+        await self._session.initialize()
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self._stack.aclose()
+        self._session = None
+
+    async def call(self, name: str, arguments: dict[str, Any]) -> Any:
+        """The structured answer of one tool, raising ToolError when the tool refused"""
+        if self._session is None:
+            raise RuntimeError("use the client inside async with")
+        result = await self._session.call_tool(name, arguments)
+        text = "\n".join(getattr(c, "text", "") for c in result.content)
+        # mcp 2 names the fields in snake case and mcp 1 in camel case
+        if getattr(result, "is_error", None) or getattr(result, "isError", None):
+            raise ToolError(text)
+        structured = getattr(result, "structured_content", None) or getattr(result, "structuredContent", None)
+        if structured is not None:
+            return structured
+        return json.loads(text) if text else None
+
+    async def knowledge(self, producer: str, labels: dict[str, list[str]] | None = None) -> Knowledge:
+        """The approved items a run of the producer with the labels receives and the text to put in its prompt"""
+        answer = await self.call("knowledge_for", {"producer": producer, "labels": labels or {}})
+        items = [Item(i["id"], i["version"], i["kind"], i["content"], i.get("scope", {})) for i in answer.get("items") or []]
+        return Knowledge(items, answer.get("context", ""))
+
+    async def record(
+        self,
+        producer: str,
+        output: Any,
+        labels: dict[str, list[str]] | None = None,
+        applied: list[Item] | None = None,
+        subject: str = "",
+    ) -> str:
+        """Records one output and returns the run id a verdict cites"""
+        args: dict[str, Any] = {"producer": producer, "output": output, "labels": labels or {}}
+        if applied:
+            args["applied"] = [i.ref for i in applied]
+        if subject:
+            args["subject"] = subject
+        return (await self.call("run", args))["trace_id"]
+
+    async def judge(
+        self,
+        run: str,
+        verdict: str,
+        reason: str = "",
+        reason_code: str = "",
+        edited: Any = None,
+        reviewer: str = "",
+    ) -> None:
+        """Records a verdict on a run: approve, edit with the corrected output, reject with what was wrong, or withdraw an earlier one"""
+        args: dict[str, Any] = {"trace_id": run, "verdict": verdict}
+        for key, value in (("reason", reason), ("reason_code", reason_code), ("reviewer", reviewer)):
+            if value:
+                args[key] = value
+        if edited is not None:
+            args["edited_output"] = edited
+        await self.call("feedback", args)
+
+    async def propose(
+        self,
+        kind: str,
+        content: str,
+        from_run: str = "",
+        producer: str = "",
+        labels: dict[str, list[str]] | None = None,
+        new_labels: bool = False,
+        item_id: str = "",
+        veto: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Proposes a candidate a person approves later, from a corrected run or for a producer and labels
+
+        veto names a tool call the judgment forbids as tool, when and example, as the MCP tool propose takes it
+        """
+        args: dict[str, Any] = {"kind": kind, "content": content}
+        if veto:
+            args["veto"] = veto
+        for key, value in (("from", from_run), ("producer", producer), ("id", item_id)):
+            if value:
+                args[key] = value
+        if labels:
+            args["labels"] = labels
+        if new_labels:
+            args["new_labels"] = True
+        return await self.call("propose", args)
+
+    async def approve(self, item_id: str, version: int, approver: str) -> dict[str, Any]:
+        """Approves a candidate on behalf of the named person"""
+        return await self.call("approve", {"id": item_id, "version": version, "approver": approver})
+
+    async def check_call(self, tool: str, arguments: dict[str, Any], producer: str = "") -> Decision:
+        """Whether a veto approved for the producer blocks or asks about a tool call before the agent runs it
+
+        An empty producer checks against the vetoes of every producer
+        """
+        answer = await self.call("check_call", {"tool": tool, "input": arguments, "producer": producer})
+        return Decision(answer["action"], answer.get("veto", ""), answer.get("reason", ""))

nodloop/langchain.py

@@ -0,0 +1,62 @@
+"""LangChain agents middleware for nodloop
+
+1. every model call gets the approved items of the place in its system message
+2. the final answer of the agent is recorded as a run naming the items it got
+3. every tool call is checked against the approved vetoes and a blocked one answers the model with the reason
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import AIMessage, SystemMessage, ToolMessage
+
+from .client import Client, Item
+
+Labels = dict[str, list[str]]
+
+
+class NodloopMiddleware(AgentMiddleware):
+    """Use one instance per agent run because it keeps the items and the run id of that run
+
+    labels is a mapping or a function of the agent state that returns one
+    """
+
+    def __init__(self, client: Client, producer: str, labels: Labels | Callable[[Any], Labels] | None = None) -> None:
+        super().__init__()
+        self.client = client
+        self.producer = producer
+        self.labels = labels or {}
+        self.applied: list[Item] = []
+        # The run the final answer was recorded as so a verdict can cite it
+        self.run: str = ""
+
+    def _labels(self, state: Any) -> Labels:
+        return self.labels(state) if callable(self.labels) else self.labels
+
+    async def awrap_model_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        knowledge = await self.client.knowledge(self.producer, self._labels(request.state))
+        self.applied = knowledge.items
+        if not knowledge.text:
+            return await handler(request)
+        base = request.system_message.content if request.system_message else ""
+        system = SystemMessage(content=f"{base}\n\n{knowledge.text}" if base else knowledge.text)
+        return await handler(request.override(system_message=system))
+
+    async def aafter_agent(self, state: Any, runtime: Any) -> None:
+        answers = [m for m in state["messages"] if isinstance(m, AIMessage)]
+        if answers:
+            self.run = await self.client.record(self.producer, answers[-1].text, self._labels(state), self.applied)
+
+    async def awrap_tool_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        call = request.tool_call
+        decision = await self.client.check_call(call["name"], call.get("args") or {}, self.producer)
+        if decision.allowed:
+            return await handler(request)
+        return ToolMessage(
+            content=f"nodloop veto {decision.veto} stopped this call: {decision.reason}",
+            tool_call_id=call["id"],
+            status="error",
+        )

nodloop/openai_agents.py

@@ -0,0 +1,61 @@
+"""OpenAI Agents SDK hooks for nodloop
+
+1. instructions puts the approved items of the place after the instructions of the agent
+2. the hooks record the final output of the agent as a run naming the items it got
+3. veto_guardrail checks every tool call against the approved vetoes and rejects a blocked one with the reason
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+from agents import RunHooks, ToolGuardrailFunctionOutput, tool_input_guardrail
+
+from .client import Client, Item
+
+Labels = dict[str, list[str]]
+
+
+class NodloopHooks(RunHooks):
+    """Pass it as hooks to Runner.run and its instructions as the instructions of the agent
+
+    Use one instance per run because it keeps the items and the run id of that run
+    """
+
+    def __init__(self, client: Client, producer: str, labels: Labels | None = None) -> None:
+        self.client = client
+        self.producer = producer
+        self.labels = labels or {}
+        self.applied: list[Item] = []
+        # The run the final output was recorded as so a verdict can cite it
+        self.run: str = ""
+
+    def instructions(self, base: str) -> Callable[[Any, Any], Any]:
+        """Dynamic instructions: the base and the approved items under it"""
+
+        async def build(context: Any, agent: Any) -> str:
+            knowledge = await self.client.knowledge(self.producer, self.labels)
+            self.applied = knowledge.items
+            return f"{base}\n\n{knowledge.text}" if knowledge.text else base
+
+        return build
+
+    async def on_agent_end(self, context: Any, agent: Any, output: Any) -> None:
+        text = output if isinstance(output, str) else json.dumps(output, default=str)
+        self.run = await self.client.record(self.producer, text, self.labels, self.applied)
+
+
+def veto_guardrail(client: Client, producer: str = "") -> Any:
+    """A tool input guardrail for function_tool(tool_input_guardrails=[...]) checking the vetoes approved for the producer"""
+
+    @tool_input_guardrail
+    async def nodloop_veto(data: Any) -> ToolGuardrailFunctionOutput:
+        arguments = json.loads(data.context.tool_arguments or "{}")
+        decision = await client.check_call(data.context.tool_name, arguments, producer)
+        if decision.allowed:
+            return ToolGuardrailFunctionOutput.allow()
+        return ToolGuardrailFunctionOutput.reject_content(f"nodloop veto {decision.veto} stopped this call: {decision.reason}")
+
+    return nodloop_veto

nodloop-0.6.6.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: nodloop
+Version: 0.6.6
+Summary: Record AI runs and the verdicts people give on them, and hand the knowledge they approve to the next run in the same place
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: mcp>=2.0
+Provides-Extra: claude-agent
+Requires-Dist: claude-agent-sdk>=0.1; extra == 'claude-agent'
+Provides-Extra: langchain
+Requires-Dist: langchain>=1.0; extra == 'langchain'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.3.3; extra == 'openai-agents'

nodloop-0.6.6.dist-info/RECORD

@@ -0,0 +1,9 @@
+nodloop/__init__.py,sha256=2PHpTd0LOK3-A9gMP8o92KVvMOVTztIr9PwGkozOi84,263
+nodloop/binary.py,sha256=pUrwMmhTT8aqdnyICDY5ZOJ_uH4tItEDzi1pCtuUrT8,2311
+nodloop/claude_agent.py,sha256=sGwJ_rtEXhGUknXBtKvgbIea57KEXOHXg7GeMRWF7YU,2705
+nodloop/client.py,sha256=nEXdO3-haqUVQNTR6-nZnqAXXhdgVhMl9TWe4XU-j3o,7964
+nodloop/langchain.py,sha256=i-qt7kojSPU8ItordDZty5XfRqQI45ZaUPukWbJRTkY,2647
+nodloop/openai_agents.py,sha256=xuDLXV4yJJqAfEooZguHQSB4BPTk8qig-m8PXUUK2Vc,2497
+nodloop-0.6.6.dist-info/METADATA,sha256=PmiJPjHcZ5uLaBxirdUquJAkZRYPz0JHMKi8ecpzWy0,516
+nodloop-0.6.6.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+nodloop-0.6.6.dist-info/RECORD,,

nodloop-0.6.6.dist-info/WHEEL

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