weaveforge 0.6.0__py3-none-any.whl

weaveforge/__init__.py

@@ -0,0 +1,72 @@
+"""weaveforge — Python SDK for WeaveForge.
+
+Push experiments, training curves, and figures into the same Supabase database
+the PWA reads, using the decorator as the one entry point::
+
+    from weaveforge import track_experiment
+
+    @track_experiment(name="beta-vae sweep", config={"beta": 4}, sync=["tensorboard"])
+    def train(run):
+        run.log_metric("val_loss", 0.11, step=100)
+        run.log_figure(fig, name="reconstruction")
+        return {"val_loss": 0.11}          # recorded as summary metrics
+
+Mirrors the web app's modular shape (``features/<name>/...``); the Supabase
+migrations are the shared source of truth (see ``docs/building/design.md`` §5.4).
+"""
+
+from .features.experiments import (
+    EXPERIMENT_STATUSES,
+    Experiment,
+    ExperimentStatus,
+    ExperimentValidationError,
+    ManageExperimentUseCase,
+    MetricPoint,
+    MetricSeries,
+    NewExperimentInput,
+    short_sha,
+)
+from .tracking import track, track_experiment
+
+# Hatch reads this as the package version (see pyproject [tool.hatch.version]).
+# The PyPI publish runs off the repo's vX.Y.Z tag, so this must be bumped in
+# step with it — PyPI refuses a re-upload of a version it already has.
+__version__ = "0.6.0"
+
+__all__ = [
+    "Experiment",
+    "ExperimentStatus",
+    "EXPERIMENT_STATUSES",
+    "NewExperimentInput",
+    "ExperimentValidationError",
+    "ManageExperimentUseCase",
+    "MetricPoint",
+    "MetricSeries",
+    "short_sha",
+    "track",
+    "track_experiment",
+    "Run",
+    "connect",
+    "Container",
+    "Settings",
+    "__version__",
+]
+
+
+def __getattr__(name: str):
+    """Lazily expose the connection layer so ``import weaveforge`` (and the
+    decorator) work without the ``supabase`` package installed — it's only
+    needed when you actually ``connect()``."""
+    if name == "Run":
+        from .features.experiments.application.run import Run
+
+        return Run
+    if name in ("connect", "Container"):
+        from . import container as _c
+
+        return getattr(_c, name)
+    if name == "Settings":
+        from .config import Settings
+
+        return Settings
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

weaveforge/cli.py

@@ -0,0 +1,73 @@
+"""``weaveforge`` command-line interface.
+
+A thin presentation layer over the SDK (SRP): it parses args and calls the same
+``connect`` / ``track`` the library exposes — no business logic of its own.
+
+    weaveforge list [--project NAME]
+    weaveforge import-tb  <logdir>          [--name N] [--project P]
+    weaveforge import-wandb <entity/proj/id> [--name N] [--project P]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    from .container import connect
+
+    c = connect(project=args.project)
+    rows = c.experiments.list()
+    if not rows:
+        print("No experiments.")
+        return 0
+    for e in rows:
+        metrics = ", ".join(f"{k}={v}" for k, v in list(e.metrics.items())[:4])
+        print(f"{e.status:<9} {e.name}" + (f"  [{metrics}]" if metrics else ""))
+    return 0
+
+
+def _import(source_id: str, ref: str, args: argparse.Namespace) -> int:
+    from .tracking import track
+
+    name = args.name or f"{source_id} import"
+    with track(name, sync={source_id: ref}, project=args.project) as run:
+        print(f"Imported {source_id} '{ref}' into experiment {run.id}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="weaveforge", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_list = sub.add_parser("list", help="list experiments")
+    p_list.add_argument("--project", help="project name to scope to")
+    p_list.set_defaults(func=_cmd_list)
+
+    p_tb = sub.add_parser("import-tb", help="import TensorBoard scalars")
+    p_tb.add_argument("logdir")
+    p_tb.add_argument("--name")
+    p_tb.add_argument("--project")
+    p_tb.set_defaults(func=lambda a: _import("tensorboard", a.logdir, a))
+
+    p_wb = sub.add_parser("import-wandb", help="import a wandb run")
+    p_wb.add_argument("run_path", help="entity/project/run_id")
+    p_wb.add_argument("--name")
+    p_wb.add_argument("--project")
+    p_wb.set_defaults(func=lambda a: _import("wandb", a.run_path, a))
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

weaveforge/config.py

@@ -0,0 +1,68 @@
+"""Environment-driven configuration for the SDK.
+
+The SDK talks to the WeaveForge web app over HTTP using a single bearer
+token (copied from the dashboard) so users don't need to paste Supabase URL /
+keys into their training environment.
+
+Kept separate from ``container.py`` so wiring stays a pure function of a
+``Settings`` object.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+_PROJECT_VARS = ("WEAVEFORGE_PROJECT_ID",)
+_PROJECT_NAME_VARS = ("WEAVEFORGE_PROJECT",)
+_TOKEN_VARS = ("WEAVEFORGE_TOKEN", "WEAVEFORGE_API_TOKEN")
+_API_URL_VARS = ("WEAVEFORGE_API_URL",)
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+def _first(names: tuple[str, ...]) -> str | None:
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+@dataclass
+class Settings:
+    api_url: str
+    token: str
+    #: Optional active project to scope experiments to (matches the web app's
+    #: project switcher). ``None`` = the user's default/unscoped rows.
+    project_id: str | None = None
+    #: Optional project *name*, resolved to an id at connect time when
+    #: ``project_id`` isn't given — friendlier than hunting for a UUID.
+    project_name: str | None = None
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        api_url = _first(_API_URL_VARS)
+        token = _first(_TOKEN_VARS)
+        missing = [
+            label
+            for label, value in (
+                ("WEAVEFORGE_TOKEN", token),
+                ("WEAVEFORGE_API_URL", api_url),
+            )
+            if not value
+        ]
+        if missing:
+            raise ConfigError(
+                "Missing required environment variables: "
+                + ", ".join(missing)
+                + ". Set it to the dashboard-issued bearer token (see python/README.md)."
+            )
+        return cls(
+            api_url=api_url,  # type: ignore[arg-type]
+            token=token,  # type: ignore[arg-type]
+            project_id=_first(_PROJECT_VARS),
+            project_name=_first(_PROJECT_NAME_VARS),
+        )

weaveforge/container.py

@@ -0,0 +1,89 @@
+"""Composition root.
+
+The ONE place that knows concrete implementations and wires them to the
+interfaces the rest of the SDK depends on (Dependency Inversion — the Python
+mirror of ``apps/web/src/bootstrap.ts``).
+
+The SDK authenticates with a single bearer token and talks to the web app's
+`/api/sdk/*` endpoints (which apply RLS using the user's session token). This
+keeps Supabase URL/keys out of training environments.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .config import Settings
+from .features.experiments.application.manage_experiment import ManageExperimentUseCase
+from .features.experiments.infrastructure.api_artifact_storage import ApiArtifactStorage
+from .features.experiments.infrastructure.api_experiment_repository import ApiExperimentRepository
+from .features.experiments.infrastructure.api_metric_repository import ApiMetricRepository
+from .features.projects.infrastructure.api_project_reader import ApiProjectReader
+from .infrastructure.api_client import ApiClient
+from .shared.clock import SystemClock, UuidGenerator
+
+
+@dataclass
+class Container:
+    """Wired dependencies. Everything downstream depends on the interfaces these
+    implement, never on Supabase directly."""
+
+    user_id: str
+    project_id: str | None
+    experiments: ApiExperimentRepository
+    metrics: ApiMetricRepository
+    artifacts: ApiArtifactStorage
+    manage_experiment: ManageExperimentUseCase
+    projects: ApiProjectReader
+    api: ApiClient
+    #: Kept so a long run can re-authenticate if the token rotates.
+    _settings: Settings
+
+    def resolve_project(self, name: str) -> str | None:
+        """Look up a project id by name (RLS-scoped to you)."""
+        return self.projects.id_by_name(name)
+
+    def reauth(self) -> None:
+        """No-op for bearer-token auth. If you rotate the token, create a new
+        Container via connect()."""
+        return None
+
+
+def connect(settings: Settings | None = None, project: str | None = None) -> Container:
+    """Build the container. ``project`` (a name) overrides the configured
+    project for this connection."""
+    settings = settings or Settings.from_env()
+    api = ApiClient(settings.api_url, settings.token)
+    who = api.get("/api/sdk/whoami")
+    user_id = who.get("userId")
+    if not user_id:
+        raise RuntimeError("Token rejected by server (no userId).")
+
+    projects = ApiProjectReader(api)
+    project_name = project or settings.project_name
+    project_id = settings.project_id if project is None else None
+    if project_id is None and project_name:
+        project_id = projects.id_by_name(project_name)
+        if project_id is None:
+            raise RuntimeError(
+                f'No project named "{project_name}" found for this account. '
+                "Create it in the dashboard, or set WEAVEFORGE_PROJECT_ID."
+            )
+
+    experiments = ApiExperimentRepository(api, project_id)
+    metrics = ApiMetricRepository(api)
+    artifacts = ApiArtifactStorage(api)
+    manage = ManageExperimentUseCase(
+        experiments, SystemClock(), UuidGenerator(), metrics
+    )
+    return Container(
+        user_id=user_id,
+        project_id=project_id,
+        experiments=experiments,
+        metrics=metrics,
+        artifacts=artifacts,
+        manage_experiment=manage,
+        projects=projects,
+        api=api,
+        _settings=settings,
+    )

weaveforge/features/__init__.py

@@ -0,0 +1,3 @@
+"""Feature modules. Each is a vertical slice with the same internal shape
+(``domain`` / ``application`` / ``infrastructure``) as the web app, so adding
+one never requires editing another (see ``docs/building/design.md`` §3.1)."""

weaveforge/features/experiments/__init__.py

@@ -0,0 +1,38 @@
+"""experiments — the public API of the experiments feature module.
+
+Others import from here, never from the internals (``docs/building/design.md`` §3.1).
+The Supabase adapters in ``infrastructure`` are intentionally *not* re-exported:
+they are wired only at the composition root (``weaveforge.container``).
+"""
+
+from .application import ManageExperimentUseCase
+from .domain import (
+    EXPERIMENT_STATUSES,
+    Experiment,
+    ExperimentFilter,
+    ExperimentStatus,
+    ExperimentValidationError,
+    IExperimentRepository,
+    IMetricRepository,
+    MetricPoint,
+    MetricSeries,
+    NewExperimentInput,
+    create_experiment,
+    short_sha,
+)
+
+__all__ = [
+    "Experiment",
+    "ExperimentStatus",
+    "EXPERIMENT_STATUSES",
+    "NewExperimentInput",
+    "ExperimentFilter",
+    "ExperimentValidationError",
+    "create_experiment",
+    "short_sha",
+    "IExperimentRepository",
+    "IMetricRepository",
+    "MetricPoint",
+    "MetricSeries",
+    "ManageExperimentUseCase",
+]

weaveforge/features/experiments/application/__init__.py

@@ -0,0 +1,5 @@
+"""Experiments application layer — orchestration only (no SDK calls)."""
+
+from .manage_experiment import ManageExperimentUseCase
+
+__all__ = ["ManageExperimentUseCase"]

weaveforge/features/experiments/application/git.py

@@ -0,0 +1,46 @@
+"""Best-effort capture of the local git state, so a run is automatically pinned
+to a repo / branch / commit (the whole point of the experiments feature). Never
+raises: outside a repo, or with git absent, every field is just ``None``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+
+def _git(*args: str, cwd: str | None = None) -> str | None:
+    try:
+        out = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=True,
+        )
+        return out.stdout.strip() or None
+    except (subprocess.SubprocessError, OSError):
+        return None
+
+
+def _normalize_remote(url: str | None) -> str | None:
+    """Turn an ssh/`.git` remote into a browsable https URL (matches the web
+    app's commit-link expectations)."""
+    if not url:
+        return None
+    url = url.strip()
+    if url.startswith("git@") and ":" in url:
+        host, path = url[4:].split(":", 1)
+        url = f"https://{host}/{path}"
+    if url.endswith(".git"):
+        url = url[:-4]
+    return url
+
+
+def capture_git_state(cwd: str | None = None) -> dict[str, str | None]:
+    branch = _git("rev-parse", "--abbrev-ref", "HEAD", cwd=cwd)
+    return {
+        "repo_url": _normalize_remote(_git("config", "--get", "remote.origin.url", cwd=cwd)),
+        "commit_sha": _git("rev-parse", "HEAD", cwd=cwd),
+        "branch": None if branch == "HEAD" else branch,
+    }

weaveforge/features/experiments/application/manage_experiment.py

@@ -0,0 +1,109 @@
+"""Use-case for experiments. Orchestration only (DIP): add, change status
+(stamping started/finished timestamps), record summary metrics, and append
+step-indexed history. Port of ``manage-experiment.use-case.ts``, extended with
+``record_history`` for the metric-curve table (0016).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from ....shared.clock import Clock, IdGenerator
+from ..domain.experiment import (
+    Experiment,
+    ExperimentStatus,
+    ExperimentValidationError,
+    NewExperimentInput,
+    create_experiment,
+)
+from ..domain.experiment_repository import IExperimentRepository
+from ..domain.metric_point import MetricPoint
+from ..domain.metric_repository import IMetricRepository
+
+_TERMINAL: tuple[ExperimentStatus, ...] = ("done", "failed", "abandoned")
+
+
+class ManageExperimentUseCase:
+    def __init__(
+        self,
+        repository: IExperimentRepository,
+        clock: Clock,
+        ids: IdGenerator,
+        metrics: IMetricRepository | None = None,
+    ) -> None:
+        self._repo = repository
+        self._clock = clock
+        self._ids = ids
+        self._metrics = metrics
+
+    def add(self, data: NewExperimentInput) -> Experiment:
+        exp = create_experiment(data, clock=self._clock, ids=self._ids)
+        self._repo.save(exp)
+        return exp
+
+    def set_status(
+        self,
+        id: str,
+        status: ExperimentStatus,
+        *,
+        existing: Experiment | None = None,
+    ) -> Experiment:
+        def change(e: Experiment) -> Experiment:
+            now = self._clock.now_iso()
+            e.status = status
+            if status == "running" and not e.started_at:
+                e.started_at = now
+            if status in _TERMINAL:
+                e.finished_at = now
+            return e
+
+        return self._mutate(id, change, existing=existing)
+
+    def record_metrics(
+        self,
+        id: str,
+        metrics: dict[str, Any],
+        *,
+        existing: Experiment | None = None,
+    ) -> Experiment:
+        def change(e: Experiment) -> Experiment:
+            e.metrics = {**e.metrics, **metrics}
+            return e
+
+        return self._mutate(id, change, existing=existing)
+
+    def add_artifacts(
+        self,
+        id: str,
+        links: Iterable[str],
+        *,
+        existing: Experiment | None = None,
+    ) -> Experiment:
+        def change(e: Experiment) -> Experiment:
+            existing_links = set(e.artifacts)
+            for link in links:
+                if link not in existing_links:
+                    e.artifacts.append(link)
+                    existing_links.add(link)
+            return e
+
+        return self._mutate(id, change, existing=existing)
+
+    def record_history(self, points: Iterable[MetricPoint]) -> None:
+        if self._metrics is None:
+            raise ExperimentValidationError(
+                "No metric repository wired — cannot record step history."
+            )
+        self._metrics.append(points)
+
+    def remove(self, id: str) -> None:
+        self._repo.delete(id)
+
+    def _mutate(self, id: str, change, *, existing: Experiment | None = None) -> Experiment:
+        base = existing if existing is not None else self._repo.get_by_id(id)
+        if base is None:
+            raise ExperimentValidationError(f'No experiment with id "{id}".')
+        updated = change(base)
+        self._repo.save(updated)
+        return updated

weaveforge/features/experiments/application/run.py

@@ -0,0 +1,174 @@
+"""The ``Run`` — the one handle every capability hangs off.
+
+A run wraps a single experiment row and buffers step-indexed metric history so
+training loops can log cheaply. It's created and finalized by :func:`track` /
+:func:`track_experiment`, which stamp status and flush on exit. New capabilities
+(more loggers, more artifact kinds) become new ``Run`` methods or new registered
+sync sources — never new call sites in user code. That's the design intent
+behind "the decorator does everything down the line."
+"""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Callable, Iterable
+from datetime import datetime, timezone
+from typing import Any
+
+from ....sync.registry import SyncRegistry, default_registry
+from ....sync.source import ArtifactSource, MetricSource, Mirror
+from ...experiments.domain.experiment import Experiment, ExperimentStatus
+from ...experiments.domain.metric_point import MetricPoint
+from .manage_experiment import ManageExperimentUseCase
+
+#: Uploader signature: (experiment_id, name, data, content_type) -> link URL.
+Uploader = Callable[[str, str, bytes, str], str]
+
+_FLUSH_EVERY = 1000
+_CONTENT_TYPES = {
+    "png": "image/png",
+    "webp": "image/webp",
+    "svg": "image/svg+xml",
+    "pdf": "application/pdf",
+}
+
+
+class Run:
+    def __init__(
+        self,
+        manage: ManageExperimentUseCase,
+        experiment: Experiment,
+        *,
+        uploader: Uploader | None = None,
+        registry: SyncRegistry = default_registry,
+        mirror: Mirror | None = None,
+    ) -> None:
+        self._manage = manage
+        self.experiment = experiment
+        self._uploader = uploader
+        self._registry = registry
+        self._mirror = mirror
+        self._buffer: list[MetricPoint] = []
+        self._last: dict[str, float] = {}
+        self._fig_seq = 0
+
+    @property
+    def id(self) -> str:
+        return self.experiment.id
+
+    # --- metrics ---------------------------------------------------------
+    def log_metric(self, name: str, value: float, step: int | None = None) -> None:
+        """One metric sample. With ``step`` it joins the curve (history); without
+        a step it's a summary value written to ``experiments.metrics``."""
+        if step is None:
+            self.log_summary({name: value})
+            return
+        wall = datetime.now(timezone.utc).isoformat()
+        self._buffer.append(MetricPoint(self.id, name, int(step), float(value), wall))
+        self._last[name] = float(value)
+        if self._mirror is not None:
+            self._mirror.log({name: float(value)}, int(step))
+        if len(self._buffer) >= _FLUSH_EVERY:
+            self.flush()
+
+    def log_metrics(self, metrics: dict[str, float], step: int | None = None) -> None:
+        if step is None:
+            self.log_summary(metrics)
+            return
+        for name, value in metrics.items():
+            self.log_metric(name, value, step)
+
+    def log_summary(self, metrics: dict[str, Any]) -> None:
+        """Merge flat summary values into ``experiments.metrics`` (the chips the
+        dashboard shows)."""
+        self.experiment = self._manage.record_metrics(
+            self.id, dict(metrics), existing=self.experiment
+        )
+
+    # --- artifacts -------------------------------------------------------
+    def log_figure(self, figure: Any, name: str | None = None, fmt: str = "png") -> str:
+        """Save a matplotlib (or any ``savefig``-capable) figure and attach it.
+
+        Duck-typed on ``savefig`` so this needs no matplotlib import; the
+        ``[figures]`` extra only adds WebP compression on top (see sync.matplotlib).
+        """
+        buf = io.BytesIO()
+        figure.savefig(buf, format=fmt, bbox_inches="tight")
+        self._fig_seq += 1
+        fname = name or f"figure-{self._fig_seq}"
+        if "." not in fname:
+            fname = f"{fname}.{fmt}"
+        ctype = _CONTENT_TYPES.get(fmt, "application/octet-stream")
+        return self.log_bytes(fname, buf.getvalue(), ctype)
+
+    def log_bytes(
+        self, name: str, data: bytes, content_type: str = "application/octet-stream"
+    ) -> str:
+        if self._uploader is None:
+            raise RuntimeError(
+                "This run has no artifact storage wired — cannot upload bytes. "
+                "Use a run created via track()/track_experiment(), or pass log_artifact(url)."
+            )
+        url = self._uploader(self.id, name, data, content_type)
+        self.experiment = self._manage.add_artifacts(self.id, [url], existing=self.experiment)
+        return url
+
+    def log_artifact(self, url: str) -> None:
+        """Attach an already-hosted link (a wandb run, an S3 object, …)."""
+        self.experiment = self._manage.add_artifacts(self.id, [url], existing=self.experiment)
+
+    # --- status ----------------------------------------------------------
+    def set_status(self, status: ExperimentStatus) -> None:
+        self.experiment = self._manage.set_status(self.id, status, existing=self.experiment)
+        # A run has one ending, and this is where every path reaches it: the
+        # mirror is told once and then forgotten, so a later status change
+        # cannot reopen a run somebody else has already closed.
+        if self._mirror is not None:
+            self._mirror.finish(status)
+            self._mirror = None
+
+    # --- sync sources ----------------------------------------------------
+    def sync(self, source_id: str, ref: Any) -> None:
+        """Pull curves and/or artifacts from a registered source.
+
+        Works with any source in the registry, so a user's own ``MetricSource``
+        is driven by the exact same call as the built-in ones (Open/Closed)."""
+        source = self._registry.get(source_id)
+        # A source may be a MetricSource, an ArtifactSource, or both; the
+        # runtime-checkable protocols let us dispatch on the roles it fills.
+        if isinstance(source, MetricSource):
+            self._ingest_series(source.read(ref))
+        if isinstance(source, ArtifactSource):
+            self._ingest_artifacts(source.collect(ref))
+
+    def sync_tensorboard(self, logdir: str) -> None:
+        self.sync("tensorboard", logdir)
+
+    def sync_wandb(self, run_path: str) -> None:
+        self.sync("wandb", run_path)
+
+    def _ingest_series(self, series: Iterable[Any]) -> None:
+        for s in series:
+            self._buffer.extend(s.to_points(self.id))
+            if s.last_value is not None:
+                self._last[s.metric] = s.last_value
+            if len(self._buffer) >= _FLUSH_EVERY:
+                self.flush()
+
+    def _ingest_artifacts(self, artifacts: Iterable[Any]) -> None:
+        for art in artifacts:
+            if art.url:
+                self.log_artifact(art.url)
+            elif art.data is not None:
+                self.log_bytes(art.name, art.data, art.content_type)
+
+    # --- lifecycle -------------------------------------------------------
+    def flush(self) -> None:
+        """Persist buffered history and fold the latest per-metric value into the
+        summary so the dashboard shows final numbers even without the chart."""
+        if self._buffer:
+            self._manage.record_history(self._buffer)
+            self._buffer.clear()
+        if self._last:
+            self.log_summary(dict(self._last))
+            self._last.clear()