buro 0.0.1__py3-none-any.whl

buro/__init__.py

@@ -0,0 +1,201 @@
+"""Buro — an experiment tracker and lab journal made for humans and human-agent AI research."""
+
+__version__ = "0.0.1"
+
+import logging
+
+from buro.config import Config
+from buro.media import Audio, Image, Video
+from buro.run import Run
+from buro.settings import BuroSettings, configure, get_settings, resolve_api_key, resolve_api_url
+
+logger = logging.getLogger("buro")
+
+# Module-level state
+_active_run: Run | None = None
+
+
+def _title_case_slug(slug: str) -> str:
+    """Default display name from a slug. 'grpo-baseline' → 'Grpo Baseline'."""
+    return " ".join(part.capitalize() for part in slug.split("-"))
+
+
+def _public_url(api_url: str, ref: str) -> str:
+    """Best-effort canonical URL for the project, used in the INFO log."""
+    base = api_url.rstrip("/")
+    # Strip /api/v1 if present so we land on the web app, not the API.
+    for suffix in ("/api/v1", "/api"):
+        if base.endswith(suffix):
+            base = base[: -len(suffix)]
+            break
+    # Web routes live at /:teamSlug/:projectSlug (and /me/:projectSlug for
+    # personal projects), NOT /p/:ref — the /p/ prefix was a stale guess
+    # from when the route shape wasn't pinned down. ref already has the
+    # right shape ("slug" or "team/slug"); leave it as-is.
+    return f"{base}/{ref}"
+
+
+def setup(api_url: str | None = None, api_key: str | None = None,
+          project: str | None = None, **kwargs) -> None:
+    """Configure SDK settings."""
+    updates = {}
+    if api_url is not None: updates["api_url"] = api_url
+    if api_key is not None: updates["api_key"] = api_key
+    if project is not None: updates["project"] = project
+    updates.update(kwargs)
+    configure(**updates)
+
+
+def init(project: str | None = None, config: dict | None = None,
+         name: str | None = None, tags: list[str] | None = None,
+         group: str | None = None, job_type: str | None = None) -> Run:
+    """Initialize a new run.
+
+    `project` is a slug ref: 'project-slug' (personal) or 'team-slug/project-slug'
+    (team). UUIDs are not accepted. The project is resolved against the server;
+    if it doesn't exist, it is auto-created.
+    """
+    global _active_run
+
+    # Resolve ambient credentials (env / ~/.buro) into the singleton so
+    # both the resolver client below and Run() see the same values.
+    configure(api_url=resolve_api_url(), api_key=resolve_api_key())
+
+    s = get_settings()
+    ref = project or s.project
+    if not ref:
+        raise ValueError("project ref must be specified via init(project=) or setup(project=)")
+
+    # Lazy imports to avoid circulars and keep error surface small.
+    from buro.client import BuroClient
+    from buro.errors import (
+        InvalidProjectRefError,
+        ProjectNotFoundError,
+        TeamAccessDeniedError,
+        TeamNotFoundError,
+    )
+    from buro.slug_ref import parse_ref
+
+    # Validate format up front — never make a network call for malformed refs.
+    try:
+        team_slug, project_slug = parse_ref(ref)
+    except ValueError as e:
+        raise InvalidProjectRefError(ref, str(e)) from e
+
+    client = BuroClient(api_url=s.api_url, api_key=s.api_key)
+    try:
+        project_uuid = _resolve_or_create(
+            client, ref, team_slug, project_slug, api_url=s.api_url
+        )
+    finally:
+        client.close()
+
+    run = Run(settings=s, project_id=project_uuid, name=name, config=config,
+              tags=tags, group=group, job_type=job_type)
+    _active_run = run
+    return run
+
+
+def _resolve_or_create(client, ref, team_slug, project_slug, *, api_url) -> str:
+    """Resolve a project ref; auto-create on 404. Returns the project UUID."""
+    from buro.errors import (
+        InvalidProjectRefError,
+        ProjectNotFoundError,
+        TeamAccessDeniedError,
+        TeamNotFoundError,
+    )
+
+    status, body = client.resolve_project(ref)
+    if status == 200:
+        return body["id"]
+    if status == 403:
+        raise TeamAccessDeniedError(ref, body.get("detail", ""))
+    if status == 400:
+        raise InvalidProjectRefError(ref, body.get("detail", ""))
+    if status != 404:
+        raise ProjectNotFoundError(ref, f"unexpected resolver status {status}: {body}")
+
+    # 404 → auto-create.
+    create_status, create_body = client.create_project(
+        slug=project_slug,
+        name=_title_case_slug(project_slug),
+        team_slug=team_slug,
+    )
+    if create_status == 201:
+        logger.info("buro: created new project %r (%s)", ref, _public_url(api_url, ref))
+        return create_body["id"]
+    if create_status == 404:
+        # Server returns 404 when the team itself is missing (team form).
+        # For personal form a 404 here would be weird; treat as ProjectNotFound.
+        if team_slug is not None:
+            raise TeamNotFoundError(ref, create_body.get("detail", ""))
+        raise ProjectNotFoundError(ref, create_body.get("detail", ""))
+    if create_status == 403:
+        raise TeamAccessDeniedError(ref, create_body.get("detail", ""))
+    if create_status == 409:
+        # Race: someone else created the same slug between our resolve and create.
+        # Try resolving once more.
+        status2, body2 = client.resolve_project(ref)
+        if status2 == 200:
+            return body2["id"]
+        raise ProjectNotFoundError(
+            ref,
+            f"slug contention: create returned 409, retry resolve returned {status2}",
+        )
+    raise ProjectNotFoundError(ref, f"unexpected create status {create_status}: {create_body}")
+
+
+def log(metrics: dict, step: int | None = None) -> None:
+    """Log metrics to the active run."""
+    if _active_run is None:
+        raise RuntimeError("No active run. Call buro.init() first.")
+    _active_run.log(metrics, step=step)
+
+
+def finish() -> None:
+    """Finish the active run."""
+    global _active_run
+    if _active_run is None:
+        return
+    _active_run.finish()
+    _active_run = None
+
+
+class _ConfigProxy:
+    def __getattr__(self, name):
+        if _active_run is None: raise RuntimeError("No active run.")
+        return getattr(_active_run.config, name)
+    def __setattr__(self, name, value):
+        if _active_run is None: raise RuntimeError("No active run.")
+        setattr(_active_run.config, name, value)
+    def __getitem__(self, key):
+        if _active_run is None: raise RuntimeError("No active run.")
+        return _active_run.config[key]
+    def __setitem__(self, key, value):
+        if _active_run is None: raise RuntimeError("No active run.")
+        _active_run.config[key] = value
+    def update(self, d: dict):
+        if _active_run is None: raise RuntimeError("No active run.")
+        _active_run.config.update(d)
+
+
+class _SummaryProxy:
+    def __getattr__(self, name):
+        if _active_run is None: raise RuntimeError("No active run.")
+        return getattr(_active_run.summary, name)
+    def __setattr__(self, name, value):
+        if _active_run is None: raise RuntimeError("No active run.")
+        setattr(_active_run.summary, name, value)
+    def __getitem__(self, key):
+        if _active_run is None: raise RuntimeError("No active run.")
+        return _active_run.summary[key]
+    def __setitem__(self, key, value):
+        if _active_run is None: raise RuntimeError("No active run.")
+        _active_run.summary[key] = value
+    def as_dict(self):
+        if _active_run is None: raise RuntimeError("No active run.")
+        return _active_run.summary.as_dict()
+
+
+config = _ConfigProxy()
+summary = _SummaryProxy()

buro/_compat.py

@@ -0,0 +1,37 @@
+"""wandb-API compatibility helpers — see sdk/docs/wandb-compatibility.md.
+
+L2 (accepted-ignored): emit_once — INFO, dedup per (process, api, param)
+L3 (degraded):         warn      — WARNING, every call
+L4 (unsupported):      unsupported — returns NotImplementedError
+"""
+import logging
+from threading import Lock
+
+_logger = logging.getLogger("buro.compat")
+_seen: set[tuple[str, str, str]] = set()
+_lock = Lock()
+
+
+def emit_once(level: str, api: str, param: str, message: str) -> None:
+    """L2 — INFO once per (process, api, param). Dedup is per-process."""
+    key = (level, api, param)
+    with _lock:
+        if key in _seen:
+            return
+        _seen.add(key)
+    _logger.info(message)
+
+
+def warn(level: str, api: str, param: str, message: str) -> None:
+    """L3 — WARNING every call. No dedup."""
+    # level/api/param accepted for call-site symmetry with emit_once;
+    # reserved for future structured logging (e.g., emitting JSON events).
+    _logger.warning(message)
+
+
+def unsupported(api: str, param: str = "") -> NotImplementedError:
+    """L4 — caller raises with the returned error for migration guidance."""
+    return NotImplementedError(
+        f"buro: {api}({param}) is not supported. "
+        f"See sdk/docs/wandb-compatibility.md for the migration path."
+    )

buro/buffer.py

@@ -0,0 +1,44 @@
+import threading
+from datetime import datetime, timezone
+from typing import Callable
+
+
+class MetricBuffer:
+    """Thread-safe metric buffer with configurable flush."""
+
+    def __init__(self, flush_callback: Callable[[list[dict]], None] | None = None,
+                 flush_batch_size: int = 1000):
+        self._buffer: list[dict] = []
+        self._lock = threading.Lock()
+        self._flush_callback = flush_callback
+        self._flush_batch_size = flush_batch_size
+
+    def add(self, metric_name: str, step: int, value: float) -> None:
+        point = {
+            "metric_name": metric_name,
+            "step": step,
+            "value": value,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        should_flush = False
+        with self._lock:
+            self._buffer.append(point)
+            if self._flush_callback and len(self._buffer) >= self._flush_batch_size:
+                should_flush = True
+        if should_flush:
+            self.flush()
+
+    def drain(self) -> list[dict]:
+        with self._lock:
+            items = self._buffer
+            self._buffer = []
+        return items
+
+    def flush(self) -> None:
+        items = self.drain()
+        if items and self._flush_callback:
+            self._flush_callback(items)
+
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._buffer)

buro/cli.py

@@ -0,0 +1,130 @@
+"""The `buro` command-line interface.
+
+Commands:
+  buro login    — browser device-flow login; stores ~/.buro/credentials
+  buro logout   — remove the stored credentials
+  buro whoami   — print the email for the stored credentials
+"""
+
+import time
+import webbrowser
+
+import httpx
+import typer
+
+from buro import credentials
+from buro.settings import DEFAULT_API_URL
+
+API_PREFIX = "/api/v1"
+
+app = typer.Typer(help="Buro CLI", no_args_is_help=True)  # pragma: no mutate (cosmetic CLI config)
+
+
+def _base(api_url: str) -> str:
+    return api_url.rstrip("/") + API_PREFIX  # pragma: no mutate (rstrip char-set is equivalent for our urls)
+
+
+def _fetch_email(api_url: str, api_key: str) -> str:
+    with httpx.Client(
+        base_url=_base(api_url),
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=30.0,  # pragma: no mutate (timeout value not behaviorally observable)
+    ) as http:
+        resp = http.get("/auth/me")
+        resp.raise_for_status()
+        return resp.json()["email"]
+
+
+def _poll_for_key(http: httpx.Client, device_code: str, interval: int) -> str:
+    """Poll device/token until terminal. Returns the api_key on approval;
+    raises typer.Exit(1) on denied/expired."""
+    while True:
+        time.sleep(interval)
+        resp = http.post("/auth/device/token", json={"device_code": device_code})
+        resp.raise_for_status()
+        body = resp.json()
+        status = body["status"]
+        if status == "approved":
+            return body["api_key"]
+        if status == "pending":
+            continue
+        if status == "slow_down":
+            interval += 5
+            continue
+        if status == "denied":
+            typer.echo("Authorization was denied.")
+            raise typer.Exit(code=1)
+        # expired or anything unexpected
+        typer.echo("The login request expired. Run `buro login` again.")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def login(
+    api_url: str = typer.Option(
+        DEFAULT_API_URL, "--api-url", help="Buro server URL."  # pragma: no mutate (help text)
+    ),
+):
+    """Log in via the browser and store an API key."""
+    try:
+        with httpx.Client(base_url=_base(api_url), timeout=30.0) as http:  # pragma: no mutate (timeout value not behaviorally observable)
+            resp = http.post("/auth/device/code")
+            resp.raise_for_status()
+            data = resp.json()
+            complete = data["verification_uri_complete"]
+            typer.echo(f"Your verification code: {data['user_code']}")
+            if webbrowser.open(complete):
+                typer.echo(f"Opened your browser to {complete}")
+            else:
+                typer.echo(f"Open this URL to authorize: {complete}")
+            typer.echo("Waiting for approval...")
+            api_key = _poll_for_key(http, data["device_code"], data["interval"])
+    except httpx.HTTPError as exc:
+        typer.echo(f"Could not reach the Buro server: {exc}")
+        raise typer.Exit(code=1)
+
+    credentials.save(api_url=api_url, api_key=api_key)
+    # The key is already saved; a failure fetching the display name should
+    # not fail an otherwise-successful login.
+    try:
+        email = _fetch_email(api_url, api_key)
+    except httpx.HTTPError:
+        typer.echo("Logged in. (Could not fetch your account details.)")
+        return
+    typer.echo(f"Logged in as {email}")
+
+
+@app.command()
+def logout():
+    """Remove the stored credentials."""
+    if credentials.clear():
+        typer.echo("Logged out.")
+    else:
+        typer.echo("Not logged in.")
+
+
+@app.command()
+def whoami(
+    api_url: str = typer.Option(None, "--api-url", help="Override the stored server URL."),  # pragma: no mutate (help text)
+):
+    """Print the email for the stored credentials."""
+    creds = credentials.load()
+    api_key = creds.get("api_key")
+    if not api_key:
+        typer.echo("Not logged in.")
+        raise typer.Exit(code=1)
+    url = api_url or creds.get("api_url") or DEFAULT_API_URL
+    try:
+        email = _fetch_email(url, api_key)
+    except httpx.HTTPError as exc:
+        typer.echo(f"Could not reach the Buro server: {exc}")
+        raise typer.Exit(code=1)
+    typer.echo(email)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":  # pragma: no mutate
+    main()

buro/client.py

@@ -0,0 +1,189 @@
+import logging
+import httpx
+
+_API_PREFIX = "/api/v1"
+
+logger = logging.getLogger(__name__)
+
+
+class BuroHTTPError(Exception):
+    """Raised when the server returns an unexpected status that the SDK
+    can't recover from (5xx, network errors). 4xx codes the SDK knows how to
+    handle (400/403/404 on resolve/create) are returned as (status, body)
+    tuples instead — see resolve_project / create_project.
+    """
+
+
+class BuroClient:
+    """Thin synchronous HTTP client for the Buro server API."""
+
+    def __init__(self, api_url: str, api_key: str):
+        self._base = api_url.rstrip("/") + _API_PREFIX
+        self._http = httpx.Client(
+            base_url=self._base,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=30.0,
+        )
+
+    def close(self):
+        self._http.close()
+
+    def create_run(self, project_id: str, name: str | None = None, config: dict | None = None,
+                   tags: list[str] | None = None, group: str | None = None,
+                   job_type: str | None = None, system_info: dict | None = None) -> dict:
+        payload = {"project_id": project_id}
+        if name is not None: payload["name"] = name
+        if config is not None: payload["config"] = config
+        if tags is not None: payload["tags"] = tags
+        if group is not None: payload["group"] = group
+        if job_type is not None: payload["job_type"] = job_type
+        if system_info is not None: payload["system_info"] = system_info
+        resp = self._http.post("/runs", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def update_run(self, run_id: str, config: dict | None = None, summary: dict | None = None,
+                   tags: list[str] | None = None, name: str | None = None) -> dict:
+        payload: dict = {}
+        if config is not None: payload["config"] = config
+        if summary is not None: payload["summary"] = summary
+        if tags is not None: payload["tags"] = tags
+        if name is not None: payload["name"] = name
+        resp = self._http.patch(f"/runs/{run_id}", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def finish_run(self, run_id: str) -> dict:
+        resp = self._http.post(f"/runs/{run_id}/finish")
+        resp.raise_for_status()
+        return resp.json()
+
+    def report_exit(
+        self,
+        run_id: str,
+        reason: str,
+        detail: dict | None = None,
+    ) -> None:
+        """POST /runs/{run_id}/exit — SDK-attested terminal state.
+
+        Best-effort: ALL failures (transport errors AND HTTP status errors
+        from the server) are logged and swallowed. This is called from
+        atexit / signal handlers where raising would mask the original
+        cause of process termination and could hang shutdown. HTTP and
+        transport errors get distinct log lines so they can be told apart
+        when grepping logs — a 5xx is a server bug; a transport error is
+        a connectivity issue.
+        """
+        try:
+            resp = self._http.post(
+                f"/runs/{run_id}/exit",
+                json={"reason": reason, "detail": detail},
+            )
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            logger.warning(
+                "Failed to report run exit (reason=%s): server returned HTTP %d",  # pragma: no mutate
+                reason,
+                exc.response.status_code,
+            )
+        except Exception:
+            logger.warning(
+                "Failed to report run exit (reason=%s); server crash detector "  # pragma: no mutate
+                "will fall back to terminal_reason=unknown after the 5-min "  # pragma: no mutate
+                "heartbeat timeout.",  # pragma: no mutate — log strings not asserted exactly; caplog uses substring match
+                reason,
+            )
+
+    def heartbeat(self, run_id: str) -> None:
+        resp = self._http.post(f"/runs/{run_id}/heartbeat")
+        resp.raise_for_status()
+
+    def send_metrics(self, run_id: str, metrics: list[dict]) -> dict:
+        resp = self._http.post(f"/runs/{run_id}/metrics", json={"metrics": metrics})
+        resp.raise_for_status()
+        return resp.json()
+
+    def create_media(
+        self,
+        run_id: str,
+        metric_name: str,
+        step: int,
+        file_ext: str,
+        file_size: int,
+        caption: str | None = None,
+        sidecar: dict | None = None,
+    ) -> dict:
+        """POST /runs/{run_id}/media — creates a media_records row + returns presigned upload URL."""
+        body: dict = {
+            "metric_name": metric_name,
+            "step": step,
+            "file_ext": file_ext,
+            "file_size": file_size,
+        }
+        if caption is not None:
+            body["caption"] = caption
+        if sidecar:
+            body["sidecar"] = sidecar
+        resp = self._http.post(f"/runs/{run_id}/media", json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    def post_logs(self, run_id: str, batch: dict) -> None:
+        """POST a batch of log lines for a run. Accepts 200/202; raises on other non-2xx."""
+        resp = self._http.post(f"/runs/{run_id}/logs", json=batch)
+        if resp.status_code not in (200, 202):
+            resp.raise_for_status()
+
+    def upload_media(self, upload_url: str, data: bytes, content_type: str) -> None:
+        resp = httpx.put(upload_url, content=data, headers={"Content-Type": content_type})
+        resp.raise_for_status()
+
+    def resolve_project(self, ref: str) -> tuple[int, dict]:
+        """Look up a project by ref. Returns (status, body). 200 means resolved;
+        400/403/404 mean the caller decides how to react (typically auto-create
+        on 404 for personal/team form). 5xx raises BuroHTTPError."""
+        r = self._http.get("/projects/resolve", params={"ref": ref})
+        if r.status_code >= 500:
+            raise BuroHTTPError(f"resolver 5xx: {r.text}")
+        return r.status_code, r.json()
+
+    def find_missing_code_blobs(self, run_id: str, sha256s: list[str]) -> dict:
+        """POST /runs/{id}/code-manifest:find-missing"""
+        resp = self._http.post(
+            f"/runs/{run_id}/code-manifest:find-missing",
+            json={"sha256s": sha256s},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def finalize_code_manifest(
+        self,
+        run_id: str,
+        version: int,
+        complete: bool,
+        files: list[dict],
+    ) -> dict:
+        """POST /runs/{id}/code-manifest:finalize"""
+        resp = self._http.post(
+            f"/runs/{run_id}/code-manifest:finalize",
+            json={"version": version, "complete": complete, "files": files},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def create_project(
+        self, *, slug: str, name: str, team_slug: str | None = None,
+        description: str | None = None,
+    ) -> tuple[int, dict]:
+        """Create a project with the given slug. team_slug=None → personal;
+        team_slug=<slug> → team-scoped. Returns (status, body). 201 = created;
+        404 = team unknown; 403 = team exists but not a member; 409 = slug
+        collision. 5xx raises BuroHTTPError."""
+        scope: dict = {"type": "team", "team_slug": team_slug} if team_slug else {"type": "user"}
+        body = {"scope": scope, "slug": slug, "name": name}
+        if description is not None:
+            body["description"] = description
+        r = self._http.post("/projects", json=body)
+        if r.status_code >= 500:
+            raise BuroHTTPError(f"create-project 5xx: {r.text}")
+        return r.status_code, r.json()