runtrace-ai 0.1.2__py3-none-any.whl

runtrace/__init__.py

@@ -0,0 +1,4 @@
+from .client import Run, RunTrace, configure, create_project, run, search
+
+__all__ = ["Run", "RunTrace", "configure", "create_project", "run", "search"]
+

runtrace/cli.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+from typing import Annotated
+
+import typer
+
+from .client import RunTrace
+from .credentials import resolve_connection, save_credentials
+
+
+app = typer.Typer(no_args_is_help=True, help="Track experiments and query RunTrace memory.")
+integrations_app = typer.Typer(no_args_is_help=True, help="Install RunTrace in supported agent CLIs.")
+app.add_typer(integrations_app, name="integrations")
+
+
+def client(base_url: str | None, api_token: str | None) -> RunTrace:
+    resolved_base_url, resolved_api_token = resolve_connection(base_url, api_token)
+    return RunTrace(base_url=resolved_base_url, api_token=resolved_api_token, strict=True)
+
+
+@app.command()
+def auth(
+    api_key: Annotated[str, typer.Argument(help="Agent API key, or '-' to read it from stdin.")],
+    base_url: str | None = typer.Option(None, envvar="RUNTRACE_BASE_URL", help="RunTrace API URL."),
+) -> None:
+    """Authenticate the CLI and MCP tool with an agent API key."""
+    if api_key == "-":
+        api_key = sys.stdin.readline().strip()
+    if not api_key:
+        raise typer.BadParameter("API key cannot be empty")
+
+    resolved_base_url, _ = resolve_connection(base_url, api_key)
+    status = RunTrace(
+        base_url=resolved_base_url,
+        api_token=api_key,
+        strict=True,
+    ).request("GET", "/api/v1/auth/status")
+    if not status.get("authenticated"):
+        raise typer.BadParameter("RunTrace rejected this API key")
+
+    path = save_credentials(resolved_base_url, api_key)
+    typer.echo(f"Authenticated with {resolved_base_url}. Credentials saved to {path}")
+
+
+@app.command()
+def search(
+    project: str,
+    query: str,
+    base_url: str | None = typer.Option(None, envvar="RUNTRACE_BASE_URL"),
+    api_token: str | None = typer.Option(None, envvar="RUNTRACE_API_TOKEN", hidden=True),
+    limit: int = 10,
+) -> None:
+    result = client(base_url, api_token).search(project, query, limit)
+    typer.echo(json.dumps(result, indent=2, default=str))
+
+
+@app.command("context")
+def context_command(
+    project: str,
+    base_url: str | None = typer.Option(None, envvar="RUNTRACE_BASE_URL"),
+    api_token: str | None = typer.Option(None, envvar="RUNTRACE_API_TOKEN", hidden=True),
+) -> None:
+    result = client(base_url, api_token).request("GET", f"/api/v1/projects/{project}/context")
+    typer.echo(json.dumps(result, indent=2, default=str))
+
+
+@app.command(
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+    help="Run a command and track structured RUNTRACE_METRIC/RUNTRACE_EVENT output.",
+)
+def exec(
+    ctx: typer.Context,
+    project: str = typer.Option(...),
+    name: str = typer.Option(...),
+    hypothesis: str = typer.Option(...),
+    reasoning: str = typer.Option(""),
+    base_url: str | None = typer.Option(None, envvar="RUNTRACE_BASE_URL"),
+    api_token: str | None = typer.Option(None, envvar="RUNTRACE_API_TOKEN", hidden=True),
+) -> None:
+    command = list(ctx.args)
+    if command and command[0] == "--":
+        command = command[1:]
+    if not command:
+        raise typer.BadParameter("Provide a command after --")
+    rt = client(base_url, api_token)
+    with rt.run(project, name, hypothesis, reasoning, command=" ".join(command)) as tracked:
+        process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, bufsize=1)
+        assert process.stdout
+        metric_pattern = re.compile(r"^RUNTRACE_METRIC\s+(\S+)=([+-]?[\d.]+)(?:\s+step=(\d+))?")
+        event_pattern = re.compile(r'^RUNTRACE_EVENT(?:\s+level=(\w+))?\s+message=["\']?(.*?)["\']?$')
+        for line in process.stdout:
+            sys.stdout.write(line)
+            if match := metric_pattern.match(line.strip()):
+                tracked.log_metric(match.group(1), float(match.group(2)), int(match.group(3)) if match.group(3) else None)
+            elif match := event_pattern.match(line.strip()):
+                tracked.log_event(match.group(2), match.group(1) or "info")
+        code = process.wait()
+        if code == 0:
+            tracked.finish("undecided", result_summary="Command completed successfully")
+        else:
+            tracked.abort(f"Command exited {code}")
+            raise typer.Exit(code)
+
+
+@integrations_app.command("install")
+def install_integration(
+    host: Annotated[str, typer.Argument(help="Agent CLI to configure: codex or claude")],
+    ref: str = typer.Option("master", help="RunTrace Git ref to install."),
+    dry_run: bool = typer.Option(False, help="Print commands without changing host configuration."),
+) -> None:
+    """Install the RunTrace plugin from its public repository marketplace."""
+    host = host.lower()
+    if host not in {"codex", "claude"}:
+        raise typer.BadParameter("Host must be 'codex' or 'claude'")
+    if not shutil.which(host):
+        raise typer.BadParameter(f"{host} is not installed or is not on PATH")
+    if host == "codex":
+        commands = [
+            ["codex", "plugin", "marketplace", "add", "vano04/RunTrace", "--ref", ref],
+            ["codex", "plugin", "add", "runtrace@runtrace"],
+        ]
+    else:
+        commands = [
+            ["claude", "plugin", "marketplace", "add", "vano04/RunTrace"],
+            ["claude", "plugin", "install", "runtrace@runtrace", "--scope", "user"],
+        ]
+    for command in commands:
+        typer.echo("$ " + " ".join(command))
+        if not dry_run:
+            subprocess.run(command, check=True)
+    typer.echo("RunTrace plugin installed. Run 'runtrace auth API_KEY' to authenticate it.")
+
+
+if __name__ == "__main__":
+    app()

runtrace/client.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import platform
+import socket
+import subprocess
+import sys
+import threading
+import time
+import uuid
+import warnings
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+import httpx
+import psutil
+
+
+def _git(args: list[str], cwd: str) -> str | None:
+    try:
+        return subprocess.check_output(["git", *args], cwd=cwd, text=True, stderr=subprocess.DEVNULL, timeout=2).strip()
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _metadata(cwd: str) -> dict[str, Any]:
+    return {
+        "host_metadata": {
+            "hostname": socket.gethostname(),
+            "platform": platform.platform(),
+            "cpu_count": psutil.cpu_count(),
+            "memory_bytes": psutil.virtual_memory().total,
+        },
+        "environment_metadata": {
+            "python": sys.version.split()[0],
+            "executable": sys.executable,
+            "argv": sys.argv,
+        },
+        "git_commit": _git(["rev-parse", "HEAD"], cwd),
+        "git_branch": _git(["branch", "--show-current"], cwd),
+        "git_dirty": bool(_git(["status", "--porcelain"], cwd)),
+    }
+
+
+class RunTrace:
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        api_token: str | None = None,
+        strict: bool = False,
+        timeout: float = 5.0,
+        *,
+        api_key: str | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_token = api_token or api_key
+        self.strict = strict
+        self.client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {self.api_token}"} if self.api_token else {},
+        )
+        self._buffer: deque[tuple[str, str, dict[str, Any], str]] = deque(maxlen=2000)
+        self._lock = threading.Lock()
+        atexit.register(self.flush)
+
+    def request(self, method: str, path: str, payload: dict[str, Any] | None = None, *, buffer: bool = False, request_id: str | None = None) -> Any:
+        request_id = request_id or str(uuid.uuid4())
+        try:
+            response = self.client.request(method, path, json=payload, headers={"X-Request-ID": request_id})
+            response.raise_for_status()
+            return response.json() if response.content else None
+        except (httpx.HTTPError, OSError):
+            if buffer:
+                with self._lock:
+                    self._buffer.append((method, path, payload or {}, request_id))
+                warnings.warn(f"RunTrace is unavailable; buffered {method} {path}", RuntimeWarning, stacklevel=2)
+                return None
+            if self.strict:
+                raise
+            return None
+
+    def flush(self) -> int:
+        sent = 0
+        with self._lock:
+            pending = list(self._buffer)
+        for method, path, payload, request_id in pending:
+            try:
+                response = self.client.request(method, path, json=payload, headers={"X-Request-ID": request_id})
+                response.raise_for_status()
+            except (httpx.HTTPError, OSError):
+                break
+            with self._lock:
+                if self._buffer and self._buffer[0][3] == request_id:
+                    self._buffer.popleft()
+            sent += 1
+        return sent
+
+    def search(self, project: str, query: str, limit: int = 10, include_archived: bool = False) -> dict[str, Any] | None:
+        return self.request("POST", "/api/v1/search", {"project": project, "query": query, "limit": limit, "include_archived": include_archived})
+
+    def create_project(self, name: str, slug: str, description: str = "") -> dict[str, Any] | None:
+        return self.request("POST", "/api/v1/projects", {"name": name, "slug": slug, "description": description})
+
+    def run(self, project: str, name: str, hypothesis: str = "", reasoning: str = "", tags: list[str] | None = None, **kwargs: Any) -> "Run":
+        return Run(self, project, name, hypothesis, reasoning, tags or [], kwargs)
+
+
+class Run:
+    def __init__(self, client: RunTrace, project: str, name: str, hypothesis: str, reasoning: str, tags: list[str], options: dict[str, Any]):
+        self.client = client
+        self.project = project
+        self.name = name
+        self.hypothesis = hypothesis
+        self.reasoning = reasoning
+        self.tags = tags
+        self.options = options
+        self.id: str | None = None
+        self.display_id: str | None = None
+        self._finished = False
+
+    def __enter__(self) -> "Run":
+        cwd = self.options.pop("working_directory", os.getcwd())
+        configuration = dict(self.options.pop("configuration", {}))
+        configuration["tags"] = self.tags
+        payload = {
+            "name": self.name,
+            "hypothesis": self.hypothesis,
+            "reasoning": self.reasoning,
+            "working_directory": cwd,
+            "command": " ".join(sys.argv),
+            "configuration": configuration,
+            **_metadata(cwd),
+            **self.options,
+        }
+        created = self.client.request("POST", f"/api/v1/projects/{self.project}/runs", payload)
+        if not created:
+            if self.client.strict:
+                raise RuntimeError("RunTrace server unavailable")
+            return self
+        self.id = created["id"]
+        self.display_id = created["display_id"]
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> bool:
+        if exc is not None:
+            self.abort(str(exc))
+        elif not self._finished:
+            self.finish("undecided")
+        return False
+
+    def _send(self, path: str, payload: dict[str, Any], *, buffer: bool = True) -> Any:
+        if not self.id:
+            return None
+        return self.client.request("POST", f"/api/v1/runs/{self.id}/{path}", payload, buffer=buffer)
+
+    def log_metric(self, name: str, value: float, step: int | None = None, timestamp: str | None = None) -> None:
+        self.log_metrics({name: value}, step=step, timestamp=timestamp)
+
+    def log_metrics(self, values: dict[str, float], step: int | None = None, timestamp: str | None = None) -> None:
+        self._send("metrics", {"metrics": [{"name": name, "value": value, "step": step, "timestamp": timestamp} for name, value in values.items()]})
+
+    def log_param(self, name: str, value: Any) -> None:
+        self.log_params({name: value})
+
+    def log_params(self, values: dict[str, Any]) -> None:
+        self._send("parameters", {"parameters": values})
+
+    def log_event(self, message: str, level: str = "info", event_type: str | None = None, metadata: dict[str, Any] | None = None) -> None:
+        self._send("events", {"message": message, "level": level, "event_type": event_type, "metadata": metadata or {}})
+
+    def log_reasoning(self, text: str, stage: str = "during") -> None:
+        self.log_event(text, event_type=f"reasoning.{stage}")
+
+    def set_tags(self, tags: list[str]) -> None:
+        self.tags = tags
+        self.log_param("tags", tags)
+
+    def link_run(self, run_id: str, relationship: str) -> None:
+        self.log_event(f"Linked {run_id} as {relationship}", event_type="run.relationship", metadata={"run_id": run_id, "relationship": relationship})
+
+    def _upload_artifact(self, name: str, content: Any, content_type: str, metadata: dict[str, Any] | None = None, kind: str = "artifact") -> dict[str, Any] | None:
+        if not self.id:
+            return None
+        try:
+            artifact_metadata = {"kind": kind, **(metadata or {})}
+            response = self.client.client.post(
+                f"/api/v1/runs/{self.id}/artifacts",
+                files={"file": (name, content, content_type)},
+                data={"metadata": json.dumps(artifact_metadata)},
+            )
+            response.raise_for_status()
+            return response.json()
+        except (OSError, httpx.HTTPError):
+            if self.client.strict:
+                raise
+            warnings.warn(f"RunTrace could not upload artifact {name}", RuntimeWarning, stacklevel=2)
+            return None
+
+    def log_artifact(self, path: str, name: str | None = None, metadata: dict[str, Any] | None = None, kind: str = "artifact") -> dict[str, Any] | None:
+        artifact_path = Path(path)
+        try:
+            with artifact_path.open("rb") as handle:
+                return self._upload_artifact(name or artifact_path.name, handle, "application/octet-stream", metadata, kind)
+        except OSError:
+            if self.client.strict:
+                raise
+            warnings.warn(f"RunTrace could not upload artifact {artifact_path}", RuntimeWarning, stacklevel=2)
+            return None
+
+    def log_text(self, name: str, content: str, kind: str = "log", metadata: dict[str, Any] | None = None) -> dict[str, Any] | None:
+        """Save previewable text output such as stdout, stderr, reports, or logs."""
+        return self._upload_artifact(name, content.encode("utf-8"), "text/plain", metadata, kind)
+
+    def log_config(self, values: dict[str, Any], name: str = "config.json", metadata: dict[str, Any] | None = None) -> dict[str, Any] | None:
+        """Save configuration as both queryable parameters and a versioned JSON artifact."""
+        self.log_params(values)
+        return self._upload_artifact(name, json.dumps(values, indent=2, sort_keys=True).encode("utf-8"), "application/json", metadata, "config")
+
+    def finish(self, outcome: str, result_summary: str | None = None, conclusion: str | None = None) -> None:
+        disposition = {"success": "kept", "partial_success": "kept", "failure": "discarded", "inconclusive": "undecided"}.get(outcome, outcome)
+        self._send("finish", {"disposition": disposition, "result_summary": result_summary or "", "conclusion": conclusion or ""}, buffer=False)
+        self._finished = True
+
+    def abort(self, reason: str | None = None) -> None:
+        self._send("crash", {"error_summary": reason or "Run aborted"}, buffer=False)
+        self._finished = True
+
+
+_default = RunTrace(
+    base_url=os.getenv("RUNTRACE_BASE_URL", "http://localhost:8000"),
+    api_token=os.getenv("RUNTRACE_API_TOKEN") or os.getenv("RUNTRACE_API_KEY"),
+)
+
+
+def configure(
+    base_url: str = "http://localhost:8000",
+    api_token: str | None = None,
+    strict: bool = False,
+    *,
+    api_key: str | None = None,
+) -> RunTrace:
+    global _default
+    _default = RunTrace(base_url=base_url, api_token=api_token or api_key, strict=strict)
+    return _default
+
+
+def run(project: str, hypothesis: str, reasoning: str = "", name: str | None = None, tags: list[str] | None = None, **kwargs: Any) -> Run:
+    return _default.run(project, name or hypothesis[:80], hypothesis, reasoning, tags, **kwargs)
+
+
+def search(project: str, query: str, limit: int = 10) -> dict[str, Any] | None:
+    return _default.search(project, query, limit)
+
+
+def create_project(name: str, slug: str, description: str = "") -> dict[str, Any] | None:
+    return _default.create_project(name, slug, description)

runtrace/credentials.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_BASE_URL = "http://localhost:8000"
+
+
+def credentials_path() -> Path:
+    override = os.getenv("RUNTRACE_CREDENTIALS_FILE")
+    if override:
+        return Path(override).expanduser()
+    config_home = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return config_home / "runtrace" / "credentials.json"
+
+
+def load_credentials() -> dict[str, str]:
+    try:
+        payload: Any = json.loads(credentials_path().read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return {
+        key: value
+        for key in ("base_url", "api_token")
+        if isinstance((value := payload.get(key)), str) and value
+    }
+
+
+def resolve_connection(
+    base_url: str | None = None,
+    api_token: str | None = None,
+) -> tuple[str, str | None]:
+    saved = load_credentials()
+    resolved_base_url = (
+        base_url
+        or os.getenv("RUNTRACE_BASE_URL")
+        or saved.get("base_url")
+        or DEFAULT_BASE_URL
+    )
+    resolved_api_token = (
+        api_token
+        or os.getenv("RUNTRACE_API_TOKEN")
+        or os.getenv("RUNTRACE_API_KEY")
+        or saved.get("api_token")
+    )
+    return resolved_base_url.rstrip("/"), resolved_api_token
+
+
+def save_credentials(base_url: str, api_token: str) -> Path:
+    path = credentials_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    try:
+        path.parent.chmod(0o700)
+    except OSError:
+        pass
+
+    temporary_name: str | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=".credentials-",
+            delete=False,
+        ) as temporary:
+            temporary_name = temporary.name
+            json.dump({"base_url": base_url.rstrip("/"), "api_token": api_token}, temporary)
+            temporary.write("\n")
+            temporary.flush()
+            os.fsync(temporary.fileno())
+        os.chmod(temporary_name, 0o600)
+        os.replace(temporary_name, path)
+    finally:
+        if temporary_name:
+            try:
+                Path(temporary_name).unlink()
+            except FileNotFoundError:
+                pass
+    return path