localml 0.1.0__tar.gz

localml-0.1.0/.env.example

@@ -0,0 +1,26 @@
+# Copy to .env and adjust as needed. These defaults work with docker-compose.yml.
+
+# Control plane
+LOCALML_API_TOKEN=local-dev-token
+LOCALML_AUTH_BYPASS=true
+
+# Postgres
+POSTGRES_USER=localml
+POSTGRES_PASSWORD=localml
+POSTGRES_DB=localml
+DATABASE_URL=postgresql+psycopg://localml:localml@postgres:5432/localml
+
+# Redis
+REDIS_URL=redis://redis:6379/0
+
+# MinIO (S3-compatible)
+MINIO_ROOT_USER=minioadmin
+MINIO_ROOT_PASSWORD=minioadmin
+MINIO_ENDPOINT=http://minio:9000
+MINIO_BUCKET=localml-artifacts
+
+# MLflow
+MLFLOW_TRACKING_URI=http://mlflow:5000
+
+# Serving runtime
+SERVING_URL=http://serving:11434

localml-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Report a reproducible problem with localml.
+title: "Bug: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Steps, commands, or code needed to reproduce the issue.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: localml version
+      placeholder: "0.1.0"
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, OS, architecture, and relevant dependency versions.

localml-0.1.0/.github/actions/setup-uv/action.yml

@@ -0,0 +1,20 @@
+name: Set up uv with Python
+description: Install uv and Python with the project's pinned defaults.
+
+inputs:
+  python-version:
+    description: Python version to install. Defaults to the project's floor.
+    required: false
+    default: "3.11"
+  enable-cache:
+    description: Pass-through to astral-sh/setup-uv enable-cache.
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        python-version: ${{ inputs.python-version }}
+        enable-cache: ${{ inputs.enable-cache }}

localml-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+-
+
+## Checks
+
+- [ ] `uv run pytest`
+- [ ] `uv run ruff check`
+- [ ] `uv run ruff format --check`
+- [ ] `uv run ty check src/`

localml-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  UV_FROZEN: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-uv
+        with:
+          enable-cache: ${{ github.event_name == 'push' }}
+      - run: uv sync
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run ty check src/
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-uv
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: ${{ github.event_name == 'push' }}
+      - run: uv sync
+      - run: uv run pytest ${{ matrix.python-version != '3.11' && '--no-cov' || '' }}
+
+  audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-uv
+        with:
+          enable-cache: ${{ github.event_name == 'push' }}
+      - run: uvx pip-audit --require-hashes --strict -r <(uv pip compile pyproject.toml --group dev --generate-hashes)

localml-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_FROZEN: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+          lfs: true
+      - uses: ./.github/actions/setup-uv
+      - run: uv sync
+      - name: Build docs
+        run: uv run zensical build
+      - name: Verify docs output
+        run: test -f site/index.html
+      - name: Setup Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+      - name: Upload artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

localml-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions: {}
+
+env:
+  UV_FROZEN: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+      - name: Verify tag matches pyproject version
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          [[ "$TAG" == "$VERSION" ]] || { echo "::error::Tag $GITHUB_REF_NAME does not match pyproject version $VERSION"; exit 1; }
+          if curl -sf "https://pypi.org/pypi/localml/$VERSION/json" >/dev/null 2>&1; then
+            echo "::error::Version $VERSION already exists on PyPI"
+            exit 1
+          fi
+      - uses: ./.github/actions/setup-uv
+      - run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment:
+      name: pypi
+      url: https://pypi.org/p/localml
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GH_REPO: ${{ github.repository }}
+      TAG: ${{ github.ref_name }}
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create or update GitHub Release
+        run: |
+          gh release view "$TAG" >/dev/null 2>&1 || gh release create "$TAG" --generate-notes
+          gh release upload "$TAG" --clobber dist/*

localml-0.1.0/.github/workflows/zizmor.yml

@@ -0,0 +1,26 @@
+name: Audit workflows
+
+on:
+  push:
+    branches: [main]
+    paths: [".github/workflows/**", ".github/actions/**"]
+  pull_request:
+    paths: [".github/workflows/**", ".github/actions/**"]
+
+permissions:
+  actions: read
+  contents: read
+
+jobs:
+  zizmor:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          persist-credentials: false
+      - uses: zizmorcore/zizmor-action@5f14fd08f7cf1cb1609c1e344975f152c7ee938d # v0.5.6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          advanced-security: false
+          annotations: true

localml-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+site/
+.venv/
+venv/
+
+# Tooling
+.cache/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Env / secrets
+.env
+~/.localml/
+
+# Local data / volumes
+data/
+*.db
+*.sqlite3
+mlruns/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

localml-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.14
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

localml-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

localml-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project are documented here, following
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-06
+
+### Added
+
+- Initial local ML experimentation platform scaffold.

localml-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+## Development setup
+
+This project uses [`uv`](https://docs.astral.sh/uv/); `uv.lock` is canonical and CI runs
+with `UV_FROZEN=true`.
+
+```sh
+git clone https://github.com/guenp/localml
+cd localml
+uv sync
+pre-commit install
+```
+
+## Running checks locally
+
+```sh
+uv run pytest
+uv run ruff check
+uv run ruff format --check
+uv run ty check src/
+uv run zensical build
+pre-commit run --all-files
+```
+
+## Pull request workflow
+
+1. Branch off `main`, make changes, add/update tests.
+2. Run the checks above.
+3. Open a PR. PR titles become release notes via `gh release create --generate-notes`,
+   so write them imperative and user-facing.
+4. CI must pass: lint, the test matrix, docs, workflow audit, and `pip-audit`.
+
+Reflect user-visible changes in [CHANGELOG.md](CHANGELOG.md) under `[Unreleased]`.
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, then push a matching tag:
+
+```sh
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The release workflow verifies the tag matches the version, builds, publishes to PyPI via
+Trusted Publishing (OIDC), and creates a GitHub Release.

localml-0.1.0/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.

localml-0.1.0/Makefile

@@ -0,0 +1,37 @@
+.PHONY: install lint fmt format-check typecheck docs test up down logs seed reset
+
+install:
+	uv sync
+
+lint:
+	uv run ruff check
+
+fmt:
+	uv run ruff format
+
+format-check:
+	uv run ruff format --check
+
+typecheck:
+	uv run ty check src/
+
+docs:
+	uv run zensical build
+
+test:
+	uv run pytest
+
+up:
+	docker compose up -d
+
+down:
+	docker compose down
+
+logs:
+	docker compose logs -f
+
+seed:
+	uv run python scripts/seed.py
+
+reset:
+	uv run python scripts/reset.py

localml-0.1.0/PKG-INFO

@@ -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).