agent-learning-kit 0.1.0__py3-none-any.whl

fi/alk/harness/sources.py

@@ -0,0 +1,253 @@
+"""Where an agent comes from, and how a session reaches it.
+
+A folder of source code is one kind of agent, not the only kind. The same agent may arrive as a
+provider connection with a system prompt and a tool schema, as a platform definition, or as a
+spec somebody pasted in. The stage that reads an agent is the same in all of those cases; what
+differs is where it looks and what it is allowed to touch.
+
+So the method stays in the skill and the location lives here. Supporting a new kind of agent is
+registering one class, not editing any stage.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class AgentSource(Protocol):
+    """Everything a stage needs in order to reach one agent."""
+
+    kind: str
+    name: str
+
+    def workdir(self) -> Path:
+        """The directory the session runs in."""
+
+    def builtin_tools(self) -> tuple[str, ...]:
+        """Built-in tools this source needs granted."""
+
+    def servers(self) -> dict[str, Any]:
+        """In-process tool servers this source provides, if any."""
+
+    def briefing(self) -> str:
+        """What to tell the model about where this agent's truth lives."""
+
+
+@dataclass
+class RepoSource:
+    """An agent that exists as source code on disk."""
+
+    name: str
+    root: Path
+    kind: str = "repo"
+
+    def workdir(self) -> Path:
+        return self.root
+
+    def builtin_tools(self) -> tuple[str, ...]:
+        return ("Read", "Glob", "Grep")
+
+    def servers(self) -> dict[str, Any]:
+        return {}
+
+    def briefing(self) -> str:
+        ignored = {
+            ".git",
+            ".venv",
+            "node_modules",
+            "__pycache__",
+            "artifacts",
+            "build",
+            "dist",
+        }
+        indexed: list[str] = []
+        for path in sorted(self.root.rglob("*")):
+            try:
+                relative = path.relative_to(self.root)
+            except ValueError:
+                continue
+            if any(part in ignored for part in relative.parts) or not path.is_file():
+                continue
+            indexed.append(relative.as_posix())
+            if len(indexed) >= 240:
+                break
+        return (
+            f"This agent is a repository at {self.root}. Its truth is the source code: the tool "
+            "registrations, the function signatures, the validation logic, and whatever holds "
+            "its data. Read it with Read, Glob and Grep. Documentation describes intent; the "
+            "code describes behaviour, and where they disagree the code wins. Never glob the "
+            "entire repository: dependency caches such as .venv and node_modules are irrelevant. "
+            "Start from this pre-indexed source/config file list and read only relevant files:\n"
+            + "\n".join(f"- {name}" for name in indexed)
+        )
+
+
+@dataclass
+class GitHubSource(RepoSource):
+    """A public GitHub repository cloned into this harness session."""
+
+    url: str = ""
+    kind: str = "github"
+
+    def briefing(self) -> str:
+        return (
+            f"This agent was cloned from {self.url or 'GitHub'} into {self.root}. Its truth is "
+            "the cloned source code: the tool registrations, function signatures, validation "
+            "logic, and whatever holds its data. Read it with Read, Glob and Grep."
+        )
+
+
+def clone_github_repository(url: str, destination: Path) -> Path:
+    """Shallow-clone one public GitHub repository into a session-owned directory."""
+    from .github import parse_github_location
+
+    try:
+        location = parse_github_location(url)
+    except ValueError as exc:
+        raise ValueError(
+            "use a public HTTPS GitHub repository or branch URL, such as "
+            "https://github.com/owner/repo/tree/branch"
+        ) from exc
+    if destination.exists():
+        raise ValueError(f"the session source directory already exists: {destination}")
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    command = ["git", "clone", "--depth", "1"]
+    if location.ref:
+        command.extend(["--branch", location.ref])
+    command.extend([location.clone_url, str(destination)])
+    completed = subprocess.run(
+        command,
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    if completed.returncode:
+        detail = completed.stderr.strip() or "git clone failed"
+        raise RuntimeError(detail)
+    return destination
+
+
+@dataclass
+class SpecSource:
+    """An agent supplied directly as a prompt and a tool schema, with no repository.
+
+    This is the shape a hosted provider gives back, so it is also the fallback whenever a
+    connection can be read once and handed over as text.
+    """
+
+    name: str
+    system_prompt: str
+    tool_schema: list[dict[str, Any]] = field(default_factory=list)
+    data: dict[str, Any] = field(default_factory=dict)
+    scratch: Path = Path(".")
+    kind: str = "spec"
+
+    def workdir(self) -> Path:
+        return self.scratch
+
+    def builtin_tools(self) -> tuple[str, ...]:
+        return ()
+
+    def servers(self) -> dict[str, Any]:
+        return {}
+
+    def briefing(self) -> str:
+        parts = [
+            "This agent is supplied as a definition, not a repository. Everything knowable "
+            "about it is below; there is no code to open, so do not guess at anything absent.",
+            f"SYSTEM PROMPT:\n{self.system_prompt}",
+        ]
+        if self.tool_schema:
+            parts.append(
+                f"TOOL SCHEMA:\n{json.dumps(self.tool_schema, indent=2)[:6000]}"
+            )
+        if self.data:
+            parts.append(f"DATA:\n{json.dumps(self.data, indent=2)[:6000]}")
+        return "\n\n".join(parts)
+
+
+@dataclass
+class ProviderSource:
+    """A sanitized definition fetched from an externally hosted provider.
+
+    A connect-only provider agent has no repository in the sandbox.  Representing its empty
+    source directory as a :class:`RepoSource` gives an authoring model filesystem tools and can
+    make it wander outside that directory looking for an implementation.  The provider profile
+    is the complete source of truth for this mode, so expose only that profile and no file tools.
+    """
+
+    name: str
+    profile: dict[str, Any]
+    scratch: Path = Path(".")
+    kind: str = "provider"
+
+    def workdir(self) -> Path:
+        return self.scratch
+
+    def builtin_tools(self) -> tuple[str, ...]:
+        return ()
+
+    def servers(self) -> dict[str, Any]:
+        return {}
+
+    def briefing(self) -> str:
+        return (
+            "This is an externally hosted provider agent, not a repository. The sanitized "
+            "provider definition below is authoritative for its conversation, prompt, model, "
+            "voice, states, and tool schemas. There is no source code to search or open. Do not "
+            "invent behavior or tool inputs that are absent from this definition.\n\n"
+            f"PROVIDER DEFINITION:\n{json.dumps(self.profile, indent=2, sort_keys=True)}"
+        )
+
+
+_REGISTRY: dict[str, Callable[..., AgentSource]] = {
+    "repo": lambda **kw: RepoSource(name=kw["name"], root=Path(kw["root"])),
+    "github": lambda **kw: GitHubSource(
+        name=kw["name"], root=Path(kw["root"]), url=kw.get("url", "")
+    ),
+    "spec": lambda **kw: SpecSource(
+        name=kw["name"],
+        system_prompt=kw.get("system_prompt", ""),
+        tool_schema=kw.get("tool_schema") or [],
+        data=kw.get("data") or {},
+        scratch=Path(kw.get("scratch", ".")),
+    ),
+    "provider": lambda **kw: ProviderSource(
+        name=kw["name"],
+        profile=kw.get("profile") or {},
+        scratch=Path(kw.get("scratch", ".")),
+    ),
+}
+
+
+def register_source(kind: str, factory: Callable[..., AgentSource]) -> None:
+    """Add a kind of agent. A provider connection is a class and one line here."""
+    _REGISTRY[kind] = factory
+
+
+def resolve(kind: str, **kwargs: Any) -> AgentSource:
+    if kind not in _REGISTRY:
+        raise NotImplementedError(
+            f"no agent source of kind {kind!r}; registered kinds are "
+            f"{', '.join(sorted(_REGISTRY))}"
+        )
+    # An empty root used to resolve to the current directory, which is worse than failing: every
+    # later stage then reads a real path, finds the harness's own repository, and reports that the
+    # agent has no code on disk. Nothing downstream can tell that apart from an agent that really
+    # was given as a specification.
+    if "root" in kwargs and not str(kwargs.get("root") or "").strip():
+        raise ValueError(
+            f"a {kind!r} source needs the path its code lives at, and none was given. If this "
+            "agent has no code on disk, it is not this kind of source."
+        )
+    return _REGISTRY[kind](**kwargs)
+
+
+def supported() -> tuple[str, ...]:
+    return tuple(sorted(_REGISTRY))

fi/alk/harness/spend.py

@@ -0,0 +1,140 @@
+"""What the harness itself spent, written where a deleted sandbox cannot take it with it.
+
+Every model call the harness makes arrives at one place, `Stage`'s handling of `StageDone`, so the
+ledger is fed from there rather than from each stage's own code: a writer added later is counted
+without anybody remembering to count it. Parallel scenario writers and the suite review each open
+their own session, which is why per-call-site accounting would have missed most of a large run's
+spend.
+
+The file is rewritten after every turn so the newest total is always on disk. A run that dies
+mid-turn loses that turn only, and the platform reads the file while the sandbox is alive.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+JOURNAL_ALIAS = "ALK_SPEND_JOURNAL"
+
+_stages: dict[str, dict[str, Any]] = {}
+_path: Path | None = None
+
+
+def journal_to(path: str | os.PathLike[str] | None) -> None:
+    """Where to keep the ledger. Nothing is written until this is set or the alias names a path."""
+    global _path
+    _path = Path(path) if path else None
+    if _path is not None:
+        _flush()
+
+
+def _destination() -> Path | None:
+    if _path is not None:
+        return _path
+    named = os.environ.get(JOURNAL_ALIAS, "").strip()
+    return Path(named) if named else None
+
+
+def record(
+    stage: str,
+    usd: float | None,
+    turns: int = 0,
+    models: set[str] | None = None,
+    tokens_in: int = 0,
+    tokens_out: int = 0,
+    tokens_cached: int = 0,
+) -> None:
+    """Add one session's reported spend. A backend that cannot price a call reports None.
+
+    ``tokens_cached`` is the part of ``tokens_in`` the provider served from its own cache. It is
+    reported rather than discounted, because the table here carries no cache rate and a guessed
+    one would be a made-up figure presented as a price. Carrying the count is what lets anyone
+    reconciling a bill see the size of the overstatement instead of inheriting it silently: two
+    reruns of the same authoring produced byte-identical ledgers four times apart in wall clock,
+    which is what caching looks like when nothing records it.
+    """
+    name = (stage or "stage").strip() or "stage"
+    entry = _stages.setdefault(
+        name,
+        {
+            "usd": 0.0,
+            "turns": 0,
+            "models": [],
+            "priced": 0,
+            "unpriced": 0,
+            "tokens_in": 0,
+            "tokens_out": 0,
+            "tokens_cached": 0,
+        },
+    )
+    if usd is None:
+        entry["unpriced"] += 1
+    else:
+        entry["usd"] = round(entry["usd"] + float(usd), 6)
+        entry["priced"] += 1
+    entry["turns"] += int(turns or 0)
+    entry["tokens_in"] += int(tokens_in or 0)
+    entry["tokens_out"] += int(tokens_out or 0)
+    entry["tokens_cached"] += int(tokens_cached or 0)
+    for model in sorted(models or set()):
+        if model not in entry["models"]:
+            entry["models"].append(model)
+    _flush()
+
+
+def total_usd() -> float:
+    return round(sum(float(entry["usd"]) for entry in _stages.values()), 6)
+
+
+def unpriced_turns() -> int:
+    """Turns whose backend reported no price. Nonzero means the total is a floor, not the answer."""
+    return sum(int(entry["unpriced"]) for entry in _stages.values())
+
+
+def snapshot() -> dict[str, Any]:
+    return {
+        "schema": "futureagi.harness-spend.v1",
+        "total_usd": total_usd(),
+        "unpriced_turns": unpriced_turns(),
+        "stages": [
+            {
+                "stage": name,
+                **{
+                    key: entry[key]
+                    for key in (
+                        "usd",
+                        "turns",
+                        "models",
+                        "priced",
+                        "unpriced",
+                        "tokens_in",
+                        "tokens_out",
+                        "tokens_cached",
+                    )
+                },
+            }
+            for name, entry in sorted(_stages.items())
+        ],
+    }
+
+
+def _flush() -> None:
+    destination = _destination()
+    if destination is None:
+        return
+    try:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        # Written whole, then moved: a poll that reads mid-write must never see half a total.
+        handle = tempfile.NamedTemporaryFile(
+            "w", dir=destination.parent, prefix=".spend-", suffix=".json", delete=False
+        )
+        with handle as writing:
+            json.dump(snapshot(), writing, indent=2, sort_keys=True)
+        os.replace(handle.name, destination)
+    except OSError:
+        # Accounting must never be the reason a stage fails.
+        pass

fi/alk/harness/tool_trace_proxy.py

@@ -0,0 +1,104 @@
+"""Bundle-owned observable HTTP tool proxy used by hosted process environments."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib import error, request
+
+import psycopg
+
+PORT = int(os.environ["PORT"])
+UPSTREAM = os.environ["UPSTREAM_URL"].rstrip("/")
+DATABASE_URL = os.environ["DATABASE_URL"]
+
+
+def _record(
+    name: str, arguments: object, result: object, ok: bool, failure: str = ""
+) -> None:
+    try:
+        with psycopg.connect(DATABASE_URL, autocommit=True) as connection:
+            connection.execute(
+                "INSERT INTO _alk_tool_trace(name, arguments, result, ok, error, at) "
+                "VALUES (%s, %s, %s, %s, %s, %s)",
+                (
+                    name,
+                    json.dumps(arguments),
+                    json.dumps(result),
+                    ok,
+                    failure,
+                    time.time(),
+                ),
+            )
+    except Exception:
+        # Evidence persistence must never alter the target tool response.
+        pass
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *_args: object) -> None:
+        return
+
+    def do_GET(self) -> None:  # noqa: N802 - BaseHTTPRequestHandler API
+        if self.path == "/health":
+            self.send_response(200)
+            self.end_headers()
+            return
+        self._forward()
+
+    def do_POST(self) -> None:  # noqa: N802 - BaseHTTPRequestHandler API
+        self._forward()
+
+    def _forward(self) -> None:
+        size = int(self.headers.get("content-length") or 0)
+        body = self.rfile.read(size) if size else b""
+        try:
+            arguments = json.loads(body) if body else {}
+        except ValueError:
+            arguments = {"_raw": body.decode("utf-8", errors="replace")}
+        outgoing = request.Request(
+            UPSTREAM + self.path,
+            data=body if self.command != "GET" else None,
+            method=self.command,
+            headers={
+                "content-type": self.headers.get("content-type", "application/json")
+            },
+        )
+        name = self.path.split("?", 1)[0].rstrip("/").rsplit("/", 1)[-1] or "unknown"
+        try:
+            with request.urlopen(outgoing, timeout=30) as response:
+                content = response.read()
+                status = int(response.status)
+                response_type = response.headers.get("content-type", "application/json")
+            try:
+                result = json.loads(content) if content else None
+            except ValueError:
+                result = content.decode("utf-8", errors="replace")
+            _record(name, arguments, result, status < 400)
+            self.send_response(status)
+            self.send_header("content-type", response_type)
+            self.send_header("content-length", str(len(content)))
+            self.end_headers()
+            self.wfile.write(content)
+        except error.HTTPError as exc:
+            content = exc.read()
+            failure = content.decode("utf-8", errors="replace")[:2000]
+            _record(name, arguments, None, False, failure)
+            self.send_response(exc.code)
+            self.send_header("content-length", str(len(content)))
+            self.end_headers()
+            self.wfile.write(content)
+        except Exception as exc:
+            _record(name, arguments, None, False, f"{type(exc).__name__}: unavailable")
+            content = json.dumps({"detail": "tool_upstream_unavailable"}).encode()
+            self.send_response(502)
+            self.send_header("content-type", "application/json")
+            self.send_header("content-length", str(len(content)))
+            self.end_headers()
+            self.wfile.write(content)
+
+
+if __name__ == "__main__":
+    ThreadingHTTPServer(("127.0.0.1", PORT), Handler).serve_forever()