localml 0.1.0__py3-none-any.whl

localml/__init__.py

@@ -0,0 +1,62 @@
+"""localml — Local ML experimentation platform SDK.
+
+Public API::
+
+    import localml as ml
+
+    ml.configure(api_url="http://localhost:8000", token="local-dev-token")
+
+    with ml.start_run(project="demo", config={"lr": 0.001}) as run:
+        ml.log_metrics({"accuracy": 0.91})
+        ml.log_artifact("outputs/model.safetensors")
+        version = ml.mlx.log_model(name="assistant", model_dir="./model")
+        job = ml.evaluate(model=version, dataset="datasets/eval.jsonl", metrics=["accuracy"])
+        job.wait()
+        ml.deploy(model=version, target="local")
+"""
+
+from __future__ import annotations
+
+from . import huggingface, jax, mlx, torch
+from .config import Config, configure
+from .exceptions import (
+    ArtifactUploadError,
+    AuthenticationError,
+    DeploymentError,
+    EvaluationFailedError,
+    LocalMLError,
+    ModelRegistrationError,
+    ValidationError,
+)
+from .ops import deploy, evaluate, log_artifact, log_metrics, log_params, register_model
+from .run import start_run
+from .types import Deployment, EvaluationJob, ModelVersion, Run
+
+__all__ = [
+    "ArtifactUploadError",
+    "AuthenticationError",
+    "Config",
+    "Deployment",
+    "DeploymentError",
+    "EvaluationFailedError",
+    "EvaluationJob",
+    "LocalMLError",
+    "ModelRegistrationError",
+    "ModelVersion",
+    "Run",
+    "ValidationError",
+    "configure",
+    "deploy",
+    "evaluate",
+    "huggingface",
+    "jax",
+    "log_artifact",
+    "log_metrics",
+    "log_params",
+    "mlx",
+    "register_model",
+    "start_run",
+    "torch",
+]
+
+__version__ = "0.1.0"

localml/_state.py

@@ -0,0 +1,31 @@
+"""Context-local tracking of the active run.
+
+Kept separate from the public API so adapters and ops modules can discover the current
+run without import cycles. Uses :class:`contextvars.ContextVar` so concurrent runs (e.g.
+in async or threaded notebooks) don't clobber each other.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+from .types import Run
+
+_current_run: ContextVar[Run | None] = ContextVar("localml_current_run", default=None)
+
+
+def set_current_run(run: Run | None) -> None:
+    _current_run.set(run)
+
+
+def get_current_run() -> Run:
+    run = _current_run.get()
+    if run is None:
+        raise RuntimeError(
+            "No active run. Use `with localml.start_run(...) as run:` before logging."
+        )
+    return run
+
+
+def maybe_current_run() -> Run | None:
+    return _current_run.get()

localml/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Framework adapter internals.
+
+The user-facing adapter namespaces are :mod:`localml.torch`, :mod:`localml.jax`,
+:mod:`localml.mlx`, and :mod:`localml.huggingface`. Shared packaging + registration logic
+lives in :mod:`localml.adapters.base`.
+"""

localml/adapters/base.py

@@ -0,0 +1,54 @@
+"""Shared logic for framework adapters.
+
+Adapters are **stateless**: they validate inputs, package framework-specific artifacts,
+normalize metadata into the shared schema, and then call the common model-registration
+path. Each framework module (``torch``, ``jax``, ``mlx``, ``huggingface``) builds on these
+helpers so the platform core stays framework-neutral.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..client import get_client
+from ..exceptions import ValidationError
+from ..types import ModelVersion
+
+
+def require_dir(model_dir: str | Path, *, required_files: list[str] | None = None) -> Path:
+    """Validate that ``model_dir`` exists and contains any required files."""
+    path = Path(model_dir)
+    if not path.is_dir():
+        raise ValidationError(f"model_dir is not a directory: {path}")
+    for name in required_files or []:
+        if not (path / name).exists():
+            raise ValidationError(f"missing required file '{name}' in {path}")
+    return path
+
+
+def stage_artifact(path: Path) -> str:
+    """Stage a local artifact and return its URI.
+
+    Scaffold behavior: returns a ``file://`` URI pointing at the resolved path. Phase 2
+    replaces this with a real MinIO upload (direct or pre-signed) plus checksum.
+    """
+    return path.resolve().as_uri()
+
+
+def register(
+    *,
+    name: str,
+    framework: str,
+    artifact_uri: str,
+    metadata: dict[str, Any],
+) -> ModelVersion:
+    """Normalize metadata and register a model version via the control plane."""
+    base_meta = {"framework": framework}
+    base_meta.update(metadata)
+    return get_client().register_model_version(
+        name=name,
+        framework=framework,
+        artifact_uri=artifact_uri,
+        metadata=base_meta,
+    )

localml/cli.py

@@ -0,0 +1,62 @@
+"""Typer CLI for localml.
+
+Thin wrapper over the control-plane client. Run ``localml --help`` for usage.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+from .client import get_client
+from .config import configure, get_config
+
+app = typer.Typer(help="localml — local ML experimentation platform CLI", no_args_is_help=True)
+
+projects_app = typer.Typer(help="Manage projects")
+runs_app = typer.Typer(help="Inspect runs")
+models_app = typer.Typer(help="Inspect model versions")
+app.add_typer(projects_app, name="projects")
+app.add_typer(runs_app, name="runs")
+app.add_typer(models_app, name="models")
+
+
+def _echo(obj: Any) -> None:
+    typer.echo(json.dumps(obj, indent=2, default=str))
+
+
+@app.command()
+def config(
+    api_url: str = typer.Option(None, help="Control plane URL"),
+    token: str = typer.Option(None, help="Bearer token"),
+) -> None:
+    """Show or update the active SDK configuration."""
+    if api_url or token:
+        configure(api_url=api_url, token=token)
+    cfg = get_config()
+    _echo({"api_url": cfg.api_url, "token_set": bool(cfg.token), "timeout": cfg.timeout})
+
+
+@app.command()
+def health() -> None:
+    """Check control-plane health."""
+    client = get_client()
+    _echo(client._request("GET", "/health"))
+
+
+@runs_app.command("get")
+def runs_get(run_id: str) -> None:
+    """Fetch a run by id."""
+    _echo(get_client()._request("GET", f"/runs/{run_id}"))
+
+
+@models_app.command("get")
+def models_get(name: str) -> None:
+    """Fetch a model and its versions by name."""
+    _echo(get_client()._request("GET", f"/models/{name}"))
+
+
+if __name__ == "__main__":
+    app()

localml/client.py

@@ -0,0 +1,208 @@
+"""HTTPX client for the FastAPI control plane.
+
+Thin wrapper that handles auth headers, retries on transient HTTP failures, and maps
+non-2xx responses to typed SDK exceptions. Create-style calls accept an idempotency key so
+they can be safely retried.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from .config import Config, get_config
+from .exceptions import (
+    AuthenticationError,
+    DeploymentError,
+    LocalMLError,
+    ModelRegistrationError,
+    ValidationError,
+)
+from .types import Deployment, EvaluationJob, ModelVersion, Run
+
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class Client:
+    """Synchronous control-plane client."""
+
+    def __init__(self, config: Config | None = None) -> None:
+        self.config = config or get_config()
+        headers = {}
+        if self.config.token:
+            headers["Authorization"] = f"Bearer {self.config.token}"
+        self._http = httpx.Client(
+            base_url=self.config.api_url,
+            headers=headers,
+            timeout=self.config.timeout,
+        )
+
+    # -- low-level ---------------------------------------------------------------
+
+    def _request(self, method: str, path: str, *, idempotent: bool = False, **kwargs: Any) -> Any:
+        attempts = self.config.max_retries if (method == "GET" or idempotent) else 1
+        if idempotent:
+            kwargs.setdefault("headers", {})
+            kwargs["headers"].setdefault("Idempotency-Key", str(uuid.uuid4()))
+        last_exc: Exception | None = None
+        for attempt in range(attempts):
+            try:
+                resp = self._http.request(method, path, **kwargs)
+            except httpx.TransportError as exc:  # network-level, retry
+                last_exc = exc
+                time.sleep(min(2**attempt, 5))
+                continue
+            if resp.status_code in _RETRYABLE_STATUS and attempt < attempts - 1:
+                time.sleep(min(2**attempt, 5))
+                continue
+            return self._handle(resp)
+        raise LocalMLError(f"request failed after {attempts} attempts: {last_exc}")
+
+    @staticmethod
+    def _handle(resp: httpx.Response) -> Any:
+        if resp.is_success:
+            return resp.json() if resp.content else None
+        detail = resp.text
+        if resp.status_code == 401:
+            raise AuthenticationError(detail)
+        if resp.status_code in (400, 422):
+            raise ValidationError(detail)
+        raise LocalMLError(f"HTTP {resp.status_code}: {detail}")
+
+    # -- runs --------------------------------------------------------------------
+
+    def create_run(self, project: str, config: dict[str, Any]) -> Run:
+        data = self._request(
+            "POST", "/runs", idempotent=True, json={"project": project, "config": config}
+        )
+        return Run(id=data["id"], project=data["project"], status=data.get("status", "running"))
+
+    def log_metrics(self, run_id: str, metrics: dict[str, float], step: int | None = None) -> None:
+        self._request("POST", f"/runs/{run_id}/metrics", json={"metrics": metrics, "step": step})
+
+    def log_params(self, run_id: str, params: dict[str, Any]) -> None:
+        self._request("POST", f"/runs/{run_id}/params", json={"params": params})
+
+    def log_artifact(self, run_id: str, uri: str, artifact_type: str) -> None:
+        self._request(
+            "POST",
+            f"/runs/{run_id}/artifacts",
+            json={"uri": uri, "artifact_type": artifact_type},
+        )
+
+    def complete_run(self, run_id: str, status: str) -> None:
+        self._request("POST", f"/runs/{run_id}/metrics", json={"metrics": {}, "status": status})
+
+    # -- models ------------------------------------------------------------------
+
+    def register_model_version(
+        self,
+        name: str,
+        framework: str,
+        artifact_uri: str,
+        metadata: dict[str, Any],
+    ) -> ModelVersion:
+        try:
+            data = self._request(
+                "POST",
+                f"/models/{name}/versions",
+                idempotent=True,
+                json={
+                    "model_name": name,
+                    "framework": framework,
+                    "artifact_uri": artifact_uri,
+                    "metadata": metadata,
+                },
+            )
+        except ValidationError as exc:
+            raise ModelRegistrationError(str(exc)) from exc
+        return ModelVersion(
+            id=data["id"],
+            model_name=data["model_name"],
+            version=data["version"],
+            framework=data["framework"],
+            artifact_uri=data["artifact_uri"],
+            status=data.get("status", "created"),
+        )
+
+    # -- evaluations -------------------------------------------------------------
+
+    def create_evaluation(
+        self, model_version_id: str, dataset_uri: str, metrics: list[str]
+    ) -> EvaluationJob:
+        data = self._request(
+            "POST",
+            "/evaluations",
+            idempotent=True,
+            json={
+                "model_version_id": model_version_id,
+                "dataset_uri": dataset_uri,
+                "metrics": metrics,
+            },
+        )
+        return EvaluationJob(
+            id=data["id"],
+            model_version_id=data["model_version_id"],
+            status=data.get("status", "queued"),
+            metrics=data.get("metrics"),
+            _client=self,
+        )
+
+    def get_evaluation(self, job_id: str) -> EvaluationJob:
+        data = self._request("GET", f"/evaluations/{job_id}")
+        return EvaluationJob(
+            id=data["id"],
+            model_version_id=data["model_version_id"],
+            status=data["status"],
+            metrics=data.get("metrics"),
+            _client=self,
+        )
+
+    # -- deployments -------------------------------------------------------------
+
+    def create_deployment(self, model_version_id: str, target: str) -> Deployment:
+        try:
+            data = self._request(
+                "POST",
+                "/deployments",
+                idempotent=True,
+                json={"model_version_id": model_version_id, "target": target},
+            )
+        except ValidationError as exc:
+            raise DeploymentError(str(exc)) from exc
+        return Deployment(
+            id=data["id"],
+            model_version_id=data["model_version_id"],
+            target=data["target"],
+            status=data.get("status", "active"),
+            endpoint_url=data.get("endpoint_url"),
+            _client=self,
+        )
+
+    def predict(self, deployment_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", f"/deployments/{deployment_id}/predict", json=payload)
+
+    def close(self) -> None:
+        self._http.close()
+
+
+_default_client: Client | None = None
+
+
+def get_client() -> Client:
+    """Return a process-wide default client, creating it on first use."""
+    global _default_client
+    if _default_client is None:
+        _default_client = Client()
+    return _default_client
+
+
+def reset_client() -> None:
+    """Drop the cached default client (e.g. after reconfiguring)."""
+    global _default_client
+    if _default_client is not None:
+        _default_client.close()
+    _default_client = None

localml/config.py

@@ -0,0 +1,97 @@
+"""SDK configuration.
+
+Configuration precedence (highest first):
+
+1. Explicit arguments to :func:`configure`.
+2. Environment variables (``LOCALML_API_URL``, ``LOCALML_API_TOKEN``).
+3. ``~/.localml/config.toml``.
+4. Built-in defaults.
+
+The active config is process-global; the control plane remains the source of truth for
+all platform state.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import SupportsFloat, SupportsIndex
+
+DEFAULT_API_URL = "http://localhost:8000"
+CONFIG_PATH = Path.home() / ".localml" / "config.toml"
+
+
+@dataclass
+class Config:
+    """Resolved SDK configuration."""
+
+    api_url: str = DEFAULT_API_URL
+    token: str | None = None
+    timeout: float = 30.0
+    max_retries: int = 3
+
+
+_active: Config | None = None
+
+
+def _load_file(path: Path = CONFIG_PATH) -> dict[str, object]:
+    if not path.exists():
+        return {}
+    with path.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def _float_config(value: object, default: float) -> float:
+    if isinstance(value, str | bytes | bytearray | SupportsFloat | SupportsIndex):
+        return float(value)
+    return default
+
+
+def _int_config(value: object, default: int) -> int:
+    if isinstance(value, str | bytes | bytearray | SupportsIndex):
+        return int(value)
+    return default
+
+
+def configure(
+    api_url: str | None = None,
+    token: str | None = None,
+    *,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+) -> Config:
+    """Set and return the active SDK configuration.
+
+    Values not provided fall back to environment variables, then the config file, then
+    built-in defaults.
+    """
+    global _active
+    file_cfg = _load_file()
+
+    cfg = Config(
+        api_url=(
+            api_url
+            or os.environ.get("LOCALML_API_URL")
+            or str(file_cfg.get("api_url", DEFAULT_API_URL))
+        ),
+        token=(
+            token
+            or os.environ.get("LOCALML_API_TOKEN")
+            or (str(file_cfg["token"]) if "token" in file_cfg else None)
+        ),
+        timeout=timeout if timeout is not None else _float_config(file_cfg.get("timeout"), 30.0),
+        max_retries=(
+            max_retries if max_retries is not None else _int_config(file_cfg.get("max_retries"), 3)
+        ),
+    )
+    _active = cfg
+    return cfg
+
+
+def get_config() -> Config:
+    """Return the active config, initializing from env/file/defaults on first use."""
+    if _active is None:
+        return configure()
+    return _active

localml/exceptions.py

@@ -0,0 +1,35 @@
+"""Typed SDK exceptions.
+
+All SDK errors derive from :class:`LocalMLError` so callers can catch the whole family
+with a single ``except`` while still being able to discriminate specific failures.
+"""
+
+from __future__ import annotations
+
+
+class LocalMLError(Exception):
+    """Base class for all localml SDK errors."""
+
+
+class AuthenticationError(LocalMLError):
+    """Raised when the API rejects the configured token (HTTP 401)."""
+
+
+class ValidationError(LocalMLError):
+    """Raised for invalid arguments or rejected requests (HTTP 400/422)."""
+
+
+class ArtifactUploadError(LocalMLError):
+    """Raised when an artifact upload fails or is incomplete."""
+
+
+class ModelRegistrationError(LocalMLError):
+    """Raised when registering a model version fails."""
+
+
+class EvaluationFailedError(LocalMLError):
+    """Raised when an evaluation job ends in a ``failed`` state."""
+
+
+class DeploymentError(LocalMLError):
+    """Raised when a deployment cannot be created or activated."""

localml/huggingface.py

@@ -0,0 +1,33 @@
+"""Hugging Face framework adapter — ``localml.huggingface``.
+
+Captures ``config.json``, tokenizer files, safetensors/bin weights, generation config, and
+Hugging Face model metadata.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .adapters import base
+from .types import ModelVersion
+
+
+def log_pretrained(
+    name: str,
+    model_dir: str,
+    *,
+    metadata: dict[str, Any] | None = None,
+) -> ModelVersion:
+    """Register a Hugging Face pretrained model directory as a model version.
+
+    Example::
+
+        ml.huggingface.log_pretrained(name="hf-assistant", model_dir="./model")
+    """
+    path = base.require_dir(model_dir, required_files=["config.json"])
+    meta: dict[str, Any] = {"source": "huggingface"}
+    meta.update(metadata or {})
+    artifact_uri = base.stage_artifact(path)
+    return base.register(
+        name=name, framework="huggingface", artifact_uri=artifact_uri, metadata=meta
+    )

localml/jax.py

@@ -0,0 +1,48 @@
+"""JAX framework adapter — ``localml.jax``.
+
+Captures PyTree parameters, training state, an Orbax checkpoint directory, shape/dtype
+metadata, the JAX version, and optional sharding metadata.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .adapters import base
+from .types import ModelVersion
+
+
+def log_checkpoint(
+    name: str,
+    *,
+    params: Any | None = None,
+    state: Any | None = None,
+    config: dict[str, Any] | None = None,
+    checkpoint_format: str = "orbax",
+    checkpoint_dir: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> ModelVersion:
+    """Register a JAX checkpoint as a model version.
+
+    Example::
+
+        ml.jax.log_checkpoint(
+            name="ranker",
+            params=params,
+            state=train_state,
+            config=config,
+            checkpoint_format="orbax",
+        )
+
+    Scaffold note: real Orbax serialization + sharding capture land in Phase 2.
+    """
+    meta: dict[str, Any] = {"checkpoint_format": checkpoint_format, "config": config or {}}
+    meta.update(metadata or {})
+
+    target = Path(checkpoint_dir) if checkpoint_dir else Path(f"./.localml/jax/{name}")
+    target.mkdir(parents=True, exist_ok=True)
+    # TODO(phase2): orbax.checkpoint save of params/state; capture shape/dtype + jax version.
+    artifact_uri = base.stage_artifact(target)
+
+    return base.register(name=name, framework="jax", artifact_uri=artifact_uri, metadata=meta)

localml/mlx.py

@@ -0,0 +1,32 @@
+"""MLX framework adapter — ``localml.mlx``.
+
+Captures MLX model files, tokenizer/config, quantization metadata, the MLX version, and
+Apple Silicon runtime metadata.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .adapters import base
+from .types import ModelVersion
+
+
+def log_model(
+    name: str,
+    model_dir: str,
+    *,
+    quantization: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> ModelVersion:
+    """Register an MLX model directory as a model version.
+
+    Example::
+
+        ml.mlx.log_model(name="assistant", model_dir="./mlx_model", quantization="4bit")
+    """
+    path = base.require_dir(model_dir)
+    meta: dict[str, Any] = {"runtime": "mlx", "quantization": quantization}
+    meta.update(metadata or {})
+    artifact_uri = base.stage_artifact(path)
+    return base.register(name=name, framework="mlx", artifact_uri=artifact_uri, metadata=meta)

localml/ops.py

@@ -0,0 +1,75 @@
+"""Top-level lifecycle operations exposed on the ``localml`` namespace.
+
+These are thin convenience wrappers that resolve the active run/client and delegate to the
+control plane. Framework-specific model logging lives in :mod:`localml.adapters`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ._state import get_current_run
+from .client import get_client
+from .types import Deployment, EvaluationJob, ModelVersion
+
+
+def log_metrics(metrics: dict[str, float], *, step: int | None = None) -> None:
+    """Log scalar metrics to the active run."""
+    run = get_current_run()
+    get_client().log_metrics(run.id, metrics, step=step)
+
+
+def log_params(params: dict[str, Any]) -> None:
+    """Log hyperparameters / config values to the active run."""
+    run = get_current_run()
+    get_client().log_params(run.id, params)
+
+
+def log_artifact(path: str, *, artifact_type: str = "file") -> None:
+    """Register a local artifact with the active run.
+
+    Note: in this scaffold the path is recorded as-is. Real uploads to MinIO (direct or
+    pre-signed URL) land in Phase 2 — see ROADMAP.md.
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"artifact path does not exist: {path}")
+    run = get_current_run()
+    get_client().log_artifact(run.id, uri=str(p.resolve()), artifact_type=artifact_type)
+
+
+def register_model(
+    name: str,
+    artifact_uri: str,
+    *,
+    framework: str = "generic",
+    metadata: dict[str, Any] | None = None,
+) -> ModelVersion:
+    """Register a new model version from an already-staged artifact URI."""
+    return get_client().register_model_version(
+        name=name,
+        framework=framework,
+        artifact_uri=artifact_uri,
+        metadata=metadata or {},
+    )
+
+
+def evaluate(
+    model: ModelVersion | str,
+    dataset: str,
+    metrics: list[str],
+) -> EvaluationJob:
+    """Queue an evaluation job for a model version against a dataset."""
+    model_version_id = model.id if isinstance(model, ModelVersion) else model
+    return get_client().create_evaluation(
+        model_version_id=model_version_id,
+        dataset_uri=dataset,
+        metrics=metrics,
+    )
+
+
+def deploy(model: ModelVersion | str, target: str = "local") -> Deployment:
+    """Deploy a model version to a serving target (currently ``local``)."""
+    model_version_id = model.id if isinstance(model, ModelVersion) else model
+    return get_client().create_deployment(model_version_id=model_version_id, target=target)

localml/run.py

@@ -0,0 +1,39 @@
+"""Run lifecycle context manager."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+from ._state import set_current_run
+from .client import get_client
+from .types import Run
+
+
+@contextmanager
+def start_run(project: str, config: dict[str, Any] | None = None) -> Iterator[Run]:
+    """Start a tracked run and set it as the active run for the duration of the block.
+
+    On a clean exit the run is marked ``completed``; on an exception it is marked
+    ``failed`` and the exception propagates.
+
+    Example::
+
+        with localml.start_run(project="demo", config={"lr": 1e-3}) as run:
+            localml.log_metrics({"accuracy": 0.91})
+    """
+    client = get_client()
+    run = client.create_run(project=project, config=config or {})
+    set_current_run(run)
+    try:
+        yield run
+    except Exception:
+        run.status = "failed"
+        client.complete_run(run.id, status="failed")
+        raise
+    else:
+        run.status = "completed"
+        client.complete_run(run.id, status="completed")
+    finally:
+        set_current_run(None)

localml/torch.py

@@ -0,0 +1,44 @@
+"""PyTorch framework adapter — ``localml.torch``.
+
+Captures ``state_dict``, model config, optional input/output schema, the PyTorch version,
+and Python dependencies, then registers the result as a shared model version.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .adapters import base
+from .types import ModelVersion
+
+
+def log_model(
+    model: Any,
+    name: str,
+    *,
+    example_input: Any | None = None,
+    metadata: dict[str, Any] | None = None,
+    save_dir: str | None = None,
+) -> ModelVersion:
+    """Serialize a PyTorch model and register it as a model version.
+
+    Example::
+
+        ml.torch.log_model(
+            model=model, name="classifier", example_input=batch, metadata={"architecture": "resnet"}
+        )
+
+    Scaffold note: real ``state_dict`` serialization and schema inference land in Phase 2.
+    """
+    meta: dict[str, Any] = {"task": None}
+    meta.update(metadata or {})
+    if example_input is not None:
+        meta["has_example_input"] = True
+
+    target = Path(save_dir) if save_dir else Path(f"./.localml/torch/{name}")
+    target.mkdir(parents=True, exist_ok=True)
+    # TODO(phase2): torch.save(model.state_dict(), target / "model.pt"); capture versions.
+    artifact_uri = base.stage_artifact(target)
+
+    return base.register(name=name, framework="pytorch", artifact_uri=artifact_uri, metadata=meta)

localml/types.py

@@ -0,0 +1,98 @@
+"""Shared platform primitives returned by the SDK.
+
+These mirror the control-plane resources. They are intentionally thin data holders; the
+server remains the source of truth. ``EvaluationJob`` and ``Deployment`` carry helper
+methods that round-trip back through the API.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .exceptions import EvaluationFailedError
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+@dataclass
+class Run:
+    """One tracked experiment execution."""
+
+    id: str
+    project: str
+    status: str = "running"
+
+
+@dataclass
+class ModelVersion:
+    """Immutable record of a specific model artifact and its metadata."""
+
+    id: str
+    model_name: str
+    version: int
+    framework: str
+    artifact_uri: str
+    status: str = "created"
+
+
+@dataclass
+class EvaluationJob:
+    """Background job that evaluates a model version against a dataset."""
+
+    id: str
+    model_version_id: str
+    status: str = "queued"
+    metrics: dict[str, float] | None = None
+    _client: Client | None = field(default=None, repr=False, compare=False)
+
+    _TERMINAL = frozenset({"completed", "failed"})
+
+    def refresh(self) -> EvaluationJob:
+        """Fetch the latest job state from the control plane."""
+        if self._client is None:
+            return self
+        latest = self._client.get_evaluation(self.id)
+        self.status = latest.status
+        self.metrics = latest.metrics
+        return self
+
+    def wait(self, *, timeout: float = 600.0, poll_interval: float = 1.0) -> EvaluationJob:
+        """Poll until the job reaches a terminal state.
+
+        Uses exponential backoff capped at 10s. Raises :class:`EvaluationFailedError`
+        if the job ends in ``failed``.
+        """
+        deadline = time.monotonic() + timeout
+        interval = poll_interval
+        while self.status not in self._TERMINAL:
+            if time.monotonic() > deadline:
+                raise EvaluationFailedError(
+                    f"evaluation {self.id} timed out (status={self.status})"
+                )
+            time.sleep(interval)
+            interval = min(interval * 2, 10.0)
+            self.refresh()
+        if self.status == "failed":
+            raise EvaluationFailedError(f"evaluation {self.id} failed")
+        return self
+
+
+@dataclass
+class Deployment:
+    """Active or historical serving configuration for a model version."""
+
+    id: str
+    model_version_id: str
+    target: str = "local"
+    status: str = "active"
+    endpoint_url: str | None = None
+    _client: Client | None = field(default=None, repr=False, compare=False)
+
+    def predict(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Send a prediction request to the deployed model's endpoint."""
+        if self._client is None:
+            raise RuntimeError("deployment is not bound to a client")
+        return self._client.predict(self.id, payload)

localml-0.1.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: localml
+Version: 0.1.0
+Summary: Local ML experimentation platform demo SDK and control plane
+Project-URL: Homepage, https://github.com/guenp/localml
+Project-URL: Documentation, https://guenp.github.io/localml/
+Project-URL: Repository, https://github.com/guenp/localml
+Project-URL: Changelog, https://github.com/guenp/localml/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/guenp/localml/issues
+Author: Guenevere Prawiroatmodjo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: local-development,machine-learning,mlops,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: typer>=0.12
+Provides-Extra: api
+Requires-Dist: alembic>=1.13; extra == 'api'
+Requires-Dist: boto3>=1.34; extra == 'api'
+Requires-Dist: fastapi>=0.110; extra == 'api'
+Requires-Dist: mlflow>=2.12; extra == 'api'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'api'
+Requires-Dist: redis>=5.0; extra == 'api'
+Requires-Dist: sqlalchemy>=2.0; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'api'
+Description-Content-Type: text/markdown
+
+# localml
+
+[![CI](https://github.com/guenp/localml/actions/workflows/ci.yml/badge.svg)](https://github.com/guenp/localml/actions/workflows/ci.yml)
+
+A **local ML experimentation platform demo** that runs entirely on an Apple Silicon
+workstation. It demonstrates the core architecture of a production ML platform at local
+scale: a Python SDK, framework adapters, experiment tracking, a model registry, artifact
+storage, evaluation jobs, and local model serving.
+
+> Status: **early scaffold.** Most components are stubs with coherent interfaces. See
+> [`ROADMAP.md`](./ROADMAP.md) for what's planned and [`docs/design.md`](./docs/design.md)
+> for the full software design document.
+
+## What's here
+
+```
+localml/
+├── src/localml/          # Python SDK (`import localml as ml`)
+│   ├── adapters/         # torch / jax / mlx / huggingface framework adapters
+│   ├── client.py         # HTTPX client for the control plane
+│   ├── config.py         # ~/.localml/config.toml handling
+│   ├── exceptions.py     # typed SDK errors
+│   ├── run.py            # run context manager
+│   ├── types.py          # Run / ModelVersion / EvaluationJob / Deployment
+│   └── cli.py            # Typer CLI
+├── services/
+│   ├── api/              # FastAPI control plane
+│   ├── worker/           # Redis-backed evaluation worker
+│   └── mlflow/           # MLflow tracking + registry image
+├── docs/                 # Zensical documentation site and design document
+├── docker-compose.yml    # Local stack: api, worker, postgres, redis, minio, mlflow, serving
+└── tests/
+```
+
+## Architecture (at a glance)
+
+```mermaid
+flowchart LR
+    User[SDK / CLI / Notebook] --> API[FastAPI control plane]
+    API --> MLflow[MLflow<br/>tracking + registry]
+    API --> DB[(Postgres<br/>metadata)]
+    API --> Store[(MinIO<br/>artifacts)]
+    API --> Queue[Redis<br/>job queue]
+    API --> Serving[Local inference<br/>Ollama / MLX]
+    Queue --> Worker[Worker]
+    Worker --> Store
+    Worker --> DB
+```
+
+The control plane (Postgres) is the source of truth for platform metadata. MLflow holds
+experiment tracking state, MinIO holds artifacts, and Redis holds transient job state.
+
+## Quick start
+
+### 1. Bring up the stack
+
+```bash
+cp .env.example .env
+docker compose up -d
+```
+
+This starts Postgres, Redis, MinIO, MLflow, the FastAPI control plane, the worker, and a
+local serving runtime.
+
+| Service       | URL                     |
+| ------------- | ----------------------- |
+| Control plane | http://localhost:8000   |
+| API docs      | http://localhost:8000/docs |
+| MLflow UI     | http://localhost:5000   |
+| MinIO console | http://localhost:9001   |
+
+### 2. Install the SDK
+
+```bash
+uv sync           # or: pip install -e .
+```
+
+### 3. Run the example workflow
+
+```python
+import localml as ml
+
+ml.configure(api_url="http://localhost:8000", token="local-dev-token")
+
+with ml.start_run(project="local-demo", config={"model": "tiny-llm"}) as run:
+    ml.log_params({"batch_size": 4, "quantization": "4bit"})
+    ml.log_metrics({"baseline_accuracy": 0.82})
+
+    version = ml.huggingface.log_pretrained(
+        name="tiny-assistant",
+        model_dir="./models/tiny-assistant",
+        metadata={"task": "chat", "runtime": "mlx"},
+    )
+
+    eval_job = ml.evaluate(
+        model=version,
+        dataset="datasets/eval.jsonl",
+        metrics=["exact_match", "latency_p95"],
+    )
+    eval_job.wait()
+
+    deployment = ml.deploy(model=version, target="local")
+    print(deployment.predict({"prompt": "Explain model registries simply."}))
+```
+
+### CLI
+
+```bash
+localml --help
+localml projects list
+localml runs get <run_id>
+```
+
+## Development
+
+Uses [`uv`](https://docs.astral.sh/uv/) for Python and dependency management; `uv.lock` is
+canonical and CI runs with `UV_FROZEN=true`.
+
+```bash
+uv sync
+pre-commit install
+
+uv run pytest               # tests with coverage
+uv run ruff check           # lint
+uv run ruff format --check  # format check
+uv run ty check src/        # type check
+uv run zensical serve       # live-preview the docs
+```
+
+Docs are authored in `docs/` and built with [Zensical](https://zensical.org);
+`docs.yml` deploys them to GitHub Pages on every push to `main`.
+
+## Model lifecycle
+
+```
+created → candidate → staging → production → deprecated → archived
+       ↘ failed (from candidate/staging)  ↘ archived (terminal)
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

localml-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+localml/__init__.py,sha256=qCJbPjMEAiafeI9yE6A5bpkprJudTwAy6geIdAu8Ga8,1564
+localml/_state.py,sha256=2Klfw468iQVkVz8NQvOMlU1r6Js3M2zfd56zCEt7HjE,834
+localml/cli.py,sha256=5-x4GX8O4eJi6X_Guj914PPc7Xil59Le39MVt1mWKks,1643
+localml/client.py,sha256=YgmY7avfUexfsc_F_gHgqDkJ81WzQQT5VT7h-dYdEJE,7255
+localml/config.py,sha256=xMvsczgau0AeloYXPZRGdNjGkpOPRaWm7oXp9k-_Sro,2547
+localml/exceptions.py,sha256=EsDxXQ5pkTP5gA_wOrO0N420ugH6Fxogp9rXSHm93B8,977
+localml/huggingface.py,sha256=VdOp-rWV25HBGhKtvPXY6Cmj4geExxeJwzVd_BYuP6Y,935
+localml/jax.py,sha256=srGhJ5aSvIMDV8PrGveAcvr4WO5Qa8C76YWzL18z_XA,1475
+localml/mlx.py,sha256=jZjA3CfHFRtgn6UlPQrjZitCWfDO2-pGHtHZFp_Cjso,909
+localml/ops.py,sha256=tK063QX3DBiR9sVOnTko78kKN3CKTd2qb_up6MXJh5M,2512
+localml/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+localml/run.py,sha256=BJNqYn2VcjHgZ2vpfjVcrb-ZO_x-Dax1ni4_4Y4MfJE,1137
+localml/torch.py,sha256=CCzwP3BAAMN3IhszsgK7v3a5t105JH15JKOcGpRiq8c,1395
+localml/types.py,sha256=BZN_6GuOFeME2g35vll_sXGU368yBPaREGGqPEpZ5dQ,2952
+localml/adapters/__init__.py,sha256=8Vi0Cw7Ie99fzp3P2qCu1T2elDh7-aGCFiv3WiWUOn8,247
+localml/adapters/base.py,sha256=7xzhJd6wJ0i36buaeXFDbNcNHH4hf3MFb2nhCf3oX-I,1777
+localml-0.1.0.dist-info/METADATA,sha256=n2H7KixwkCiNC5HO-G7avo1m7rkzV6IT-o3GT9Vv27I,6060
+localml-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+localml-0.1.0.dist-info/entry_points.txt,sha256=xgFy7ist_6zSy97ermiBJwaIFdQ170Z03LglaKz42XU,44
+localml-0.1.0.dist-info/licenses/LICENSE,sha256=SBXDdJAtgrn8Y3ZseXAIE6WsLLcdGPhstydvQ01HDa4,1081
+localml-0.1.0.dist-info/RECORD,,

localml-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

localml-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+localml = localml.cli:app

localml-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guenevere Prawiroatmodjo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.