hum-cli 0.0.1__py3-none-any.whl

hum/runtime/loop.py

@@ -0,0 +1,247 @@
+"""The loop. One Runner drives one session tree. Policy and human are
+interchangeable turn sources; the difference between them is recorded, not
+special-cased. When a human overrides a gated proposal, the runner forks the
+pre-intervention state and lets the policy finish in shadow, so the world can
+grade both futures.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Callable
+
+from pydantic import BaseModel, Field
+
+from .autonomy import AutonomyPolicy, Level
+from .drivers import HumanDriver, PolicyDriver
+from .executor import Executor
+from .grader import Grader
+from .models import Intervention, Node, PreferencePair, Turn, Usage, Verdict
+from .prompt import system_prompt as default_prompt
+from .session import Session
+from .tools import ToolRegistry
+from .workspace import describe_change, fingerprint
+
+
+class RunConfig(BaseModel):
+    # "off": the policy acts; the human steers, edits, interrupts — all recorded.
+    # "earned": policy turns are gated by earned autonomy (backend-configured sessions).
+    gate: str = "off"
+    watch_workspace: bool = True  # notice files the human changed by hand between turns
+    max_turns: int = 200
+    max_wall_s: float = 3600.0
+    parallel_tools: bool = True
+    shadow: bool = True
+    shadow_max_turns: int = 100
+    task_class: str | None = None
+
+
+class RunResult(BaseModel):
+    leaf: str
+    verdict: Verdict | None = None
+    pairs: list[PreferencePair] = Field(default_factory=list)
+    turns: int = 0
+    usage: Usage = Field(default_factory=Usage)
+    stop_reason: str = "done"
+    level: Level | None = None
+
+
+class Runner:
+    def __init__(self, session: Session, executor: Executor, tools: ToolRegistry, policy: PolicyDriver, *,
+                 human: HumanDriver | None = None, grader: Grader | None = None, autonomy: AutonomyPolicy | None = None,
+                 config: RunConfig | None = None, system_prompt: str | None = None,
+                 shadow_policy_factory: Callable[[], PolicyDriver] | None = None):
+        self.session, self.executor, self.tools, self.policy = session, executor, tools, policy
+        self.human, self.grader, self.autonomy = human, grader, autonomy
+        self.cfg = config or RunConfig()
+        self.system_prompt = system_prompt or default_prompt()
+        self._shadow_factory = shadow_policy_factory or (lambda: PolicyDriver(self.policy.llm, author="shadow"))
+        self._shadows: list[tuple[str, asyncio.Task]] = []
+        self._tools_openai = tools.to_openai()
+        self.usage = Usage()
+        self.turns = 0
+        self._t0 = time.monotonic()
+        self.interventions = 0
+        self.task_class = self.cfg.task_class or session.task.get("task_class")
+        self._fp: str | None = None
+
+    def record_interrupt(self, note: str = "operator interrupted the model") -> Node:
+        """The person stopped a model turn mid-flight. The lost turn is not in the
+        tree (it never executed); the stop itself is."""
+        head = self.session.head("main")
+        n = self.session.append(Node(parent=head.id if head else None, branch="main",
+            turn=Turn(author="human", content=f"[{note}]"),
+            intervention=Intervention(kind="interrupt", target_node=head.id if head else None, note=note),
+            extra={"event": "interrupt"}))
+        self.interventions += 1
+        return n
+
+    # -- public -----------------------------------------------------------------
+    async def run(self, continue_from: str | None = None, initial: Turn | None = None) -> RunResult:
+        """``continue_from`` = head node of an ongoing session; ``initial`` = a human
+        message/action to apply first (a follow-up in a conversation)."""
+        leaf, reason = await self._drive("main", continue_from, self.executor, initial, self.policy, self.human, self.cfg.max_turns)
+        verdict = await self._grade(leaf, self.executor)
+        pairs = await self._collect_shadows(leaf, verdict)
+        level = None
+        if self.autonomy and self.task_class:
+            # Only policy-only outcomes count toward autonomy: an unsupervised main
+            # branch, or each shadow continuation.
+            if self.interventions == 0 and verdict is not None:
+                level = self.autonomy.update(self.task_class, verdict.passed)
+            for p in pairs:
+                if p.shadow_verdict is not None:
+                    level = self.autonomy.update(self.task_class, p.shadow_verdict.passed)
+            level = level or self.autonomy.level(self.task_class)
+        return RunResult(leaf=leaf, verdict=verdict, pairs=pairs, turns=self.turns, usage=self.usage, stop_reason=reason, level=level)
+
+    # -- core ---------------------------------------------------------------------
+    def _level(self) -> Level:
+        return self.autonomy.level(self.task_class) if self.autonomy else ("act" if self.human is None else "propose")
+
+    def _gated(self, turn: Turn) -> bool:
+        if self.human is None or not turn.acts or self.cfg.gate != "earned":
+            return False  # terminal claims are never gated: the grader decides
+        mutating = any(self.tools.is_mutating(c.name) for c in turn.tool_calls)
+        return AutonomyPolicy.gates(self._level(), mutating)
+
+    def _timed_out(self) -> bool:
+        return (time.monotonic() - self._t0) > self.cfg.max_wall_s
+
+    async def _drive(self, branch: str, parent: str | None, executor: Executor, initial: Turn | None,
+                     policy: PolicyDriver, human: HumanDriver | None, max_turns: int) -> tuple[str, str]:
+        node_parent = parent
+        pending: Turn | None = initial
+        intervention: Intervention | None = None
+        takeover = False
+        turns = 0
+        last_id = parent or ""
+        while turns < max_turns and not self._timed_out():
+            turn: Turn
+            if pending is not None:
+                turn, pending = pending, None
+            elif takeover:
+                action = await human.next()  # type: ignore[union-attr]
+                if action.intervention and action.intervention.kind == "release":
+                    takeover = False
+                    continue
+                if action.turn is None:
+                    continue
+                turn, intervention = action.turn.model_copy(update={"author": "human"}), None
+            else:
+                steer = human.pending() if human else None
+                if steer is not None:
+                    if steer.intervention and steer.intervention.kind == "takeover":
+                        takeover = True
+                        self.interventions += 1
+                        if steer.turn is None:
+                            continue
+                        turn, intervention = steer.turn.model_copy(update={"author": "human"}), steer.intervention
+                    elif steer.turn is not None:
+                        turn, intervention = steer.turn.model_copy(update={"author": "human"}), None
+                    else:
+                        continue
+                else:
+                    if self.cfg.watch_workspace and branch == "main":
+                        fp = await fingerprint(executor)
+                        if self._fp is not None and fp != self._fp:
+                            # files changed and no tool did it: the person did. Record it as their turn.
+                            desc = await describe_change(executor)
+                            n = self.session.append(Node(parent=node_parent, branch=branch,
+                                turn=Turn(author="human", content=f"[edited files by hand]\n{desc}".strip()),
+                                intervention=Intervention(kind="edit", target_node=node_parent, note="workspace changed outside the loop"),
+                                extra={"event": "human_edit"}))
+                            self.interventions += 1
+                            node_parent = last_id = n.id
+                        self._fp = fp
+                    msgs = self.session.messages(node_parent, self.system_prompt)
+                    turn = await policy.next(msgs, self._tools_openai)
+                    if self.cfg.watch_workspace and branch == "main" and self._fp is not None:
+                        fp2 = await fingerprint(executor)
+                        if fp2 != self._fp:
+                            # the person edited while the model was thinking; the model's turn did not see it
+                            desc = await describe_change(executor)
+                            n = self.session.append(Node(parent=node_parent, branch=branch,
+                                turn=Turn(author="human", content=f"[edited files by hand]\n{desc}".strip()),
+                                intervention=Intervention(kind="edit", target_node=node_parent, note="workspace changed while the model was thinking"),
+                                extra={"event": "human_edit"}))
+                            self.interventions += 1
+                            node_parent = last_id = n.id
+                            self._fp = fp2
+                    if turn.usage:
+                        self.usage = self.usage + turn.usage
+                    if self._gated(turn):
+                        action = await human.review(turn)  # type: ignore[union-attr]
+                        kind = action.intervention.kind if action.intervention else "accept"
+                        if kind != "accept":
+                            self.interventions += 1
+                            proposal_id = await self._spawn_shadow(node_parent, executor, turn) if self.cfg.shadow else None
+                            intervention = Intervention(kind=kind, target_node=proposal_id, note=action.intervention.note if action.intervention else None)
+                            if kind == "takeover":
+                                takeover = True
+                            if action.turn is None:
+                                # rejection without a replacement: tell the policy and let it retry
+                                note = Turn(author="human", content=f"[{kind}] {intervention.note or 'proposal not accepted'}")
+                                n = self.session.append(Node(parent=node_parent, branch=branch, turn=note, intervention=intervention))
+                                node_parent, last_id, intervention = n.id, n.id, None
+                                continue
+                            turn = action.turn.model_copy(update={"author": "human"})
+            # execute
+            results = await self.tools.call_many(turn.tool_calls, executor, self.cfg.parallel_tools) if turn.tool_calls else []
+            if results and self.cfg.watch_workspace and branch == "main":
+                self._fp = await fingerprint(executor)  # the loop's own changes are not the human's
+            node = self.session.append(Node(parent=node_parent, branch=branch, turn=turn, results=results, intervention=intervention))
+            intervention = None
+            node_parent = last_id = node.id
+            turns += 1
+            if branch == "main":
+                self.turns = turns
+            if not turn.tool_calls and (turn.author in ("policy", "shadow") or turn.done):
+                return last_id, "done"
+        return last_id, ("timeout" if self._timed_out() else "budget")
+
+    # -- shadow -------------------------------------------------------------------
+    async def _spawn_shadow(self, parent: str | None, executor: Executor, proposal: Turn) -> str:
+        """Fork the pre-intervention state; run the proposal and the policy's
+        continuation there. Returns the id of the proposal node on the shadow branch."""
+        snap = await executor.snapshot()
+        fex = await executor.fork(snap)
+        branch = self.session.new_branch_name("shadow")
+        shadow_policy = self._shadow_factory()
+        ready: asyncio.Future[str] = asyncio.get_event_loop().create_future()
+
+        async def go() -> tuple[str, Verdict | None]:
+            leaf, _ = await self._drive(branch, parent, fex, proposal.model_copy(update={"author": "shadow"}), shadow_policy, None, self.cfg.shadow_max_turns)
+            v = await self._grade(leaf, fex)
+            await fex.close()
+            return leaf, v
+
+        task = asyncio.create_task(go())
+        self._shadows.append((branch, task))
+        # the proposal node is appended synchronously on the first iteration of _drive; yield once so it exists
+        await asyncio.sleep(0)
+        first = self.session.branch_nodes(branch)
+        while not first:
+            await asyncio.sleep(0)
+            first = self.session.branch_nodes(branch)
+        return first[0].id
+
+    async def _collect_shadows(self, main_leaf: str, main_verdict: Verdict | None) -> list[PreferencePair]:
+        pairs: list[PreferencePair] = []
+        for branch, task in self._shadows:
+            leaf, v = await task
+            fork = self.session.branch_nodes(branch)[0].id
+            pairs.append(self.session.add_pair(PreferencePair(
+                fork_node=fork, human_leaf=main_leaf, shadow_leaf=leaf,
+                human_verdict=main_verdict, shadow_verdict=v, task_class=self.task_class)))
+        return pairs
+
+    # -- grading ------------------------------------------------------------------
+    async def _grade(self, leaf: str, executor: Executor) -> Verdict | None:
+        if self.grader is None or not leaf:
+            return None
+        v = await self.grader.grade(executor, self.session.task)
+        node = self.session.nodes[leaf]
+        node.verdict = v
+        self.session.update(node)
+        return v

hum/runtime/models.py

@@ -0,0 +1,132 @@
+"""Data model for one harness session.
+
+A session is a TREE of nodes. Each node holds one TURN (who acted, what they
+said, which tools they called), the tool RESULTS that followed, and, when a
+human acted on a policy proposal, the INTERVENTION that relates the two. The
+tree is the unit of data: the main branch is what actually happened; shadow
+branches are what the policy would have done had the human not intervened.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+Author = Literal["policy", "human", "shadow", "system"]
+InterventionKind = Literal["accept", "edit", "reject", "takeover", "release", "interrupt"]
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{uuid.uuid4().hex[:12]}"
+
+
+class ToolCall(BaseModel):
+    id: str
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResult(BaseModel):
+    call_id: str
+    name: str
+    content: str
+    ok: bool = True
+    elapsed_s: float = 0.0
+    raw_bytes: int | None = None  # size before observation shaping
+    extra: dict[str, Any] | None = None
+
+
+class Usage(BaseModel):
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_tokens: int = 0
+    cost_usd: float = 0.0
+
+    def __add__(self, o: "Usage") -> "Usage":
+        return Usage(
+            input_tokens=self.input_tokens + o.input_tokens,
+            output_tokens=self.output_tokens + o.output_tokens,
+            cache_tokens=self.cache_tokens + o.cache_tokens,
+            cost_usd=self.cost_usd + o.cost_usd,
+        )
+
+
+class Turn(BaseModel):
+    author: Author
+    content: str = ""
+    reasoning: str | None = None
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    model: str | None = None
+    usage: Usage | None = None
+    # Token custody when the serving side exposes it (training path).
+    prompt_token_ids: list[int] | None = None
+    completion_token_ids: list[int] | None = None
+    logprobs: list[float] | None = None
+    # A human turn with no tool calls is steering text, not a terminal turn,
+    # unless it says so explicitly.
+    done: bool = False
+
+    @property
+    def acts(self) -> bool:
+        return bool(self.tool_calls)
+
+
+class Intervention(BaseModel):
+    kind: InterventionKind
+    target_node: str | None = None  # the policy node acted upon (None for takeover/release)
+    note: str | None = None
+
+
+class Verdict(BaseModel):
+    passed: bool
+    score: float
+    grader: str
+    detail: dict[str, Any] = Field(default_factory=dict)
+    at: float = Field(default_factory=time.time)
+
+
+class Node(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("n"))
+    parent: str | None = None
+    branch: str = "main"
+    turn: Turn
+    results: list[ToolResult] = Field(default_factory=list)
+    intervention: Intervention | None = None
+    # Set on the policy node that a human acted on; points at the branch that
+    # carries the counterfactual continuation.
+    shadow_branch: str | None = None
+    verdict: Verdict | None = None
+    at: float = Field(default_factory=time.time)
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class PreferencePair(BaseModel):
+    """Two terminal states that share a fork point, each graded by the world.
+
+    The preference is the verdict, not a rater. Pairs where both sides pass or
+    both fail are kept (they are informative about the intervention's cost),
+    with ``preferred`` = None.
+    """
+
+    id: str = Field(default_factory=lambda: new_id("pp"))
+    fork_node: str
+    human_leaf: str
+    shadow_leaf: str
+    human_verdict: Verdict | None = None
+    shadow_verdict: Verdict | None = None
+    task_class: str | None = None
+
+    @property
+    def preferred(self) -> Literal["human", "shadow"] | None:
+        h, s = self.human_verdict, self.shadow_verdict
+        if h is None or s is None:
+            return None
+        if h.passed and not s.passed:
+            return "human"
+        if s.passed and not h.passed:
+            return "shadow"
+        if h.score != s.score:
+            return "human" if h.score > s.score else "shadow"
+        return None

hum/runtime/observe.py

@@ -0,0 +1,28 @@
+"""Observation shaping. The policy's context is the scarcest resource in the
+loop; what survives from a 40k-line job log is a harness decision, and one of
+the parameters later swept against reward. Defaults here are the v0 guess.
+"""
+from __future__ import annotations
+
+import re
+
+_ANSI = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+
+
+def shape(text: str, max_bytes: int = 16_000, head_fraction: float = 0.6) -> tuple[str, int]:
+    """Return (shaped_text, raw_byte_count). Keeps head and tail; marks the cut."""
+    text = _ANSI.sub("", text).replace("\r\n", "\n").replace("\r", "\n")
+    raw = len(text.encode("utf-8", errors="replace"))
+    if raw <= max_bytes:
+        return text, raw
+    head_n = int(max_bytes * head_fraction)
+    tail_n = max_bytes - head_n
+    head = text[:head_n]
+    tail = text[-tail_n:] if tail_n > 0 else ""
+    # cut on line boundaries where possible
+    if "\n" in head:
+        head = head[: head.rfind("\n") + 1]
+    if "\n" in tail:
+        tail = tail[tail.find("\n") + 1 :]
+    elided = raw - len(head.encode()) - len(tail.encode())
+    return f"{head}\n... [{elided} bytes elided by hum; re-run with a narrower command to see them] ...\n{tail}", raw

hum/runtime/prompt.py

@@ -0,0 +1,9 @@
+SYSTEM_PROMPT = """You are an engineer working inside a real system. You have native tools; call them directly and read their output before acting again. Prefer small, verifiable steps. Do not claim a result you have not observed. When the task is complete, reply with a short summary and no tool calls.
+{tools_note}{world_note}"""
+
+
+def system_prompt(tools_note: str = "", world_note: str = "") -> str:
+    return SYSTEM_PROMPT.format(
+        tools_note=(f"\n\nTools beyond the basics:\n{tools_note}" if tools_note else ""),
+        world_note=(f"\n\nAbout this system:\n{world_note}" if world_note else ""),
+    )

hum/runtime/session.py

@@ -0,0 +1,139 @@
+"""Session tree with append-only JSONL persistence.
+
+Every node is written the moment it exists, so a crashed or timed-out run
+still leaves a complete prefix on disk. ``messages()`` rebuilds the chat
+context for any node by walking its lineage, which is how a branch (human or
+shadow) is re-entered from any point.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .models import Node, PreferencePair, Turn, new_id
+
+
+class Session:
+    def __init__(self, task: dict[str, Any], session_id: str | None = None, path: Path | None = None):
+        self.id = session_id or new_id("s")
+        self.task = task  # {"instruction": str, "task_class": str|None, ...}
+        self.path = path
+        self.nodes: dict[str, Node] = {}
+        self.order: list[str] = []
+        self.pairs: list[PreferencePair] = []
+        self._branches: dict[str, str] = {}  # branch -> head node id
+        if path is not None:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps({"kind": "session", "id": self.id, "task": task}) + "\n")
+
+    # -- tree -------------------------------------------------------------
+    def append(self, node: Node) -> Node:
+        if node.parent is not None and node.parent not in self.nodes:
+            raise KeyError(f"unknown parent {node.parent}")
+        self.nodes[node.id] = node
+        self.order.append(node.id)
+        self._branches[node.branch] = node.id
+        self._persist({"kind": "node", **node.model_dump(mode="json")})
+        return node
+
+    def update(self, node: Node) -> None:
+        """Re-persist a node whose verdict / shadow pointer was set after the fact."""
+        self.nodes[node.id] = node
+        self._persist({"kind": "node_update", **node.model_dump(mode="json")})
+
+    def add_pair(self, pair: PreferencePair) -> PreferencePair:
+        self.pairs.append(pair)
+        self._persist({"kind": "pair", **pair.model_dump(mode="json")})
+        return pair
+
+    def head(self, branch: str = "main") -> Node | None:
+        nid = self._branches.get(branch)
+        return self.nodes[nid] if nid else None
+
+    def lineage(self, node_id: str | None) -> list[Node]:
+        out: list[Node] = []
+        while node_id is not None:
+            n = self.nodes[node_id]
+            out.append(n)
+            node_id = n.parent
+        out.reverse()
+        return out
+
+    def branch_nodes(self, branch: str) -> list[Node]:
+        return [self.nodes[i] for i in self.order if self.nodes[i].branch == branch]
+
+    def new_branch_name(self, prefix: str = "shadow") -> str:
+        n = sum(1 for b in self._branches if b.startswith(prefix))
+        return f"{prefix}-{n + 1}"
+
+    # -- chat reconstruction ---------------------------------------------
+    def messages(self, node_id: str | None, system_prompt: str) -> list[dict[str, Any]]:
+        """OpenAI-style messages for the lineage ending at ``node_id``.
+
+        Policy and shadow turns render as assistant turns. Human turns that act
+        (tool calls) also render as assistant turns: from the model's point of
+        view the work simply happened. Human turns that only speak render as
+        user turns (steering). Authorship is kept on the node, not in the chat.
+        """
+        msgs: list[dict[str, Any]] = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": self.task["instruction"]},
+        ]
+        for n in self.lineage(node_id):
+            t = n.turn
+            if t.author == "human" and not t.acts:
+                if t.content:
+                    msgs.append({"role": "user", "content": t.content})
+                continue
+            if t.author == "system":
+                msgs.append({"role": "user", "content": t.content})
+                continue
+            a: dict[str, Any] = {"role": "assistant", "content": t.content or None}
+            if t.tool_calls:
+                a["tool_calls"] = [
+                    {
+                        "id": c.id,
+                        "type": "function",
+                        "function": {"name": c.name, "arguments": json.dumps(c.arguments)},
+                    }
+                    for c in t.tool_calls
+                ]
+            msgs.append(a)
+            for r in n.results:
+                msgs.append({"role": "tool", "tool_call_id": r.call_id, "name": r.name, "content": r.content})
+        return msgs
+
+    # -- persistence ------------------------------------------------------
+    def _persist(self, rec: dict[str, Any]) -> None:
+        if self.path is None:
+            return
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+
+    @classmethod
+    def load(cls, path: Path) -> "Session":
+        s: Session | None = None
+        with path.open(encoding="utf-8") as f:
+            for line in f:
+                rec = json.loads(line)
+                kind = rec.pop("kind")
+                if kind == "session":
+                    s = cls(rec["task"], session_id=rec["id"], path=None)
+                    s.path = None
+                elif kind in ("node", "node_update"):
+                    assert s is not None
+                    node = Node.model_validate(rec)
+                    if kind == "node":
+                        s.nodes[node.id] = node
+                        s.order.append(node.id)
+                        s._branches[node.branch] = node.id
+                    else:
+                        s.nodes[node.id] = node
+                elif kind == "pair":
+                    assert s is not None
+                    s.pairs.append(PreferencePair.model_validate(rec))
+        assert s is not None, "empty session file"
+        s.path = path
+        return s

hum/runtime/store.py

@@ -0,0 +1,26 @@
+"""Where sessions and autonomy live on a machine: ``~/.hum`` (override with
+``HUM_HOME``). One JSONL per session, one autonomy file per home.
+"""
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+
+def home() -> Path:
+    p = Path(os.environ.get("HUM_HOME") or Path.home() / ".hum")
+    (p / "sessions").mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def session_path(session_id: str) -> Path:
+    return home() / "sessions" / f"{time.strftime('%Y%m%d-%H%M%S')}-{session_id}.jsonl"
+
+
+def autonomy_path() -> Path:
+    return home() / "autonomy.json"
+
+
+def list_sessions() -> list[Path]:
+    return sorted((home() / "sessions").glob("*.jsonl"))