openrunner-sdk 0.1.0__tar.gz

openrunner_sdk-0.1.0/.gitignore

@@ -0,0 +1,226 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!src/web/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Node.js
+node_modules/
+*.tsbuildinfo
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+data/

openrunner_sdk-0.1.0/=6.0

@@ -0,0 +1,5 @@
+Collecting psutil
+  Using cached psutil-7.2.2-cp36-abi3-manylinux2010_x86_64.manylinux_2_12_x86_64.manylinux_2_28_x86_64.whl.metadata (22 kB)
+Using cached psutil-7.2.2-cp36-abi3-manylinux2010_x86_64.manylinux_2_12_x86_64.manylinux_2_28_x86_64.whl (155 kB)
+Installing collected packages: psutil
+Successfully installed psutil-7.2.2

openrunner_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: openrunner-sdk
+Version: 0.1.0
+Summary: OpenRunner SDK - W&B-compatible ML experiment tracking client
+Project-URL: Homepage, https://github.com/jqueguiner/openrunner
+Project-URL: Repository, https://github.com/jqueguiner/openrunner
+Project-URL: Issues, https://github.com/jqueguiner/openrunner/issues
+Author-email: JL Queguiner <jl@gladia.io>
+License: MIT
+Keywords: experiment-tracking,machine-learning,ml,mlops,wandb
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pillow>=10.0
+Requires-Dist: psutil>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: nvidia-ml-py>=12.0; extra == 'gpu'
+Provides-Extra: huggingface
+Requires-Dist: transformers>=4.30; extra == 'huggingface'
+Provides-Extra: lightning
+Requires-Dist: lightning>=2.0; extra == 'lightning'
+Provides-Extra: pytorch
+Requires-Dist: torch>=2.0; extra == 'pytorch'
+Description-Content-Type: text/markdown
+
+# OpenRunner SDK
+
+Open-source, self-hosted ML experiment tracking — a drop-in replacement for Weights & Biases.
+
+## Install
+
+```bash
+pip install openrunner-sdk
+```
+
+## Quick Start
+
+```bash
+export OPENRUNNER_API_KEY="or_your_key"
+export OPENRUNNER_BASE_URL="https://your-server.com"
+```
+
+```python
+import openrunner
+
+openrunner.init(project="my-project", config={"lr": 0.001})
+
+for epoch in range(10):
+    loss = train(epoch)
+    openrunner.log({"loss": loss, "epoch": epoch})
+
+openrunner.finish()
+```
+
+## Migrating from W&B
+
+```python
+import openrunner as wandb
+
+wandb.init(project="my-project")
+wandb.log({"loss": 0.5})
+wandb.finish()
+```
+
+## Features
+
+- **W&B-compatible API** — `init()`, `log()`, `finish()`, `config`, `summary`
+- **Non-blocking** — logging never slows down training
+- **Artifacts** — version datasets, models, checkpoints with SHA-256 dedup
+- **Media** — log images (`Image()`) and tables (`Table()`)
+- **Offline mode** — works without connectivity, sync later
+- **Framework integrations** — PyTorch, HuggingFace, Lightning
+- **CLI** — `openrunner login`, `openrunner sync`, `openrunner ls`
+- **System metrics** — GPU/CPU/memory monitoring via psutil
+
+## License
+
+MIT

openrunner_sdk-0.1.0/README.md

@@ -0,0 +1,53 @@
+# OpenRunner SDK
+
+Open-source, self-hosted ML experiment tracking — a drop-in replacement for Weights & Biases.
+
+## Install
+
+```bash
+pip install openrunner-sdk
+```
+
+## Quick Start
+
+```bash
+export OPENRUNNER_API_KEY="or_your_key"
+export OPENRUNNER_BASE_URL="https://your-server.com"
+```
+
+```python
+import openrunner
+
+openrunner.init(project="my-project", config={"lr": 0.001})
+
+for epoch in range(10):
+    loss = train(epoch)
+    openrunner.log({"loss": loss, "epoch": epoch})
+
+openrunner.finish()
+```
+
+## Migrating from W&B
+
+```python
+import openrunner as wandb
+
+wandb.init(project="my-project")
+wandb.log({"loss": 0.5})
+wandb.finish()
+```
+
+## Features
+
+- **W&B-compatible API** — `init()`, `log()`, `finish()`, `config`, `summary`
+- **Non-blocking** — logging never slows down training
+- **Artifacts** — version datasets, models, checkpoints with SHA-256 dedup
+- **Media** — log images (`Image()`) and tables (`Table()`)
+- **Offline mode** — works without connectivity, sync later
+- **Framework integrations** — PyTorch, HuggingFace, Lightning
+- **CLI** — `openrunner login`, `openrunner sync`, `openrunner ls`
+- **System metrics** — GPU/CPU/memory monitoring via psutil
+
+## License
+
+MIT

openrunner_sdk-0.1.0/openrunner/__init__.py

@@ -0,0 +1,273 @@
+"""OpenRunner SDK - W&B-compatible ML experiment tracking.
+
+Public API:
+    openrunner.init(project=..., name=..., config=...)  -> Run
+    openrunner.log({"loss": 0.5}, step=10)              -> None
+    openrunner.finish(exit_code=0)                      -> None
+    openrunner.config       -> Config proxy
+    openrunner.summary      -> Summary proxy
+    openrunner.run          -> active Run or None
+    openrunner.Image        -> Image class for media logging
+    openrunner.Table        -> Table class for structured data
+    openrunner.Artifact     -> Artifact class for versioned file collections
+    openrunner.log_artifact -> Upload an artifact
+    openrunner.use_artifact -> Download an artifact (cached)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from openrunner.artifact import Artifact
+from openrunner.config import Config
+from openrunner.media import Image, Table
+from openrunner.run import Run
+from openrunner.settings import SDKSettings
+from openrunner.summary import Summary
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger("openrunner")
+
+# Active run state
+_active_run: Run | None = None
+
+
+# ---------------------------------------------------------------------------
+# Proxy objects for module-level config/summary access
+# ---------------------------------------------------------------------------
+
+class _ConfigProxy:
+    """Proxy that delegates attribute access to the active run's Config.
+
+    Since Python modules can't have properties, this proxy object sits
+    at ``openrunner.config`` and forwards all access to ``_active_run.config``.
+    """
+
+    def __getattr__(self, name: str) -> Any:
+        if _active_run is not None:
+            return getattr(_active_run.config, name)
+        raise AttributeError(f"No active run -- call openrunner.init() first")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if _active_run is not None:
+            setattr(_active_run.config, name, value)
+        else:
+            logger.warning("openrunner.config: no active run -- call openrunner.init() first")
+
+    def __getitem__(self, key: str) -> Any:
+        if _active_run is not None:
+            return _active_run.config[key]
+        raise KeyError(f"No active run -- call openrunner.init() first")
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if _active_run is not None:
+            _active_run.config[key] = value
+        else:
+            logger.warning("openrunner.config: no active run -- call openrunner.init() first")
+
+    def __repr__(self) -> str:
+        if _active_run is not None:
+            return repr(_active_run.config)
+        return "ConfigProxy(no active run)"
+
+
+class _SummaryProxy:
+    """Proxy that delegates attribute access to the active run's Summary."""
+
+    def __getattr__(self, name: str) -> Any:
+        if _active_run is not None:
+            return getattr(_active_run.summary, name)
+        raise AttributeError(f"No active run -- call openrunner.init() first")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if _active_run is not None:
+            setattr(_active_run.summary, name, value)
+        else:
+            logger.warning("openrunner.summary: no active run -- call openrunner.init() first")
+
+    def __getitem__(self, key: str) -> Any:
+        if _active_run is not None:
+            return _active_run.summary[key]
+        raise KeyError(f"No active run -- call openrunner.init() first")
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if _active_run is not None:
+            _active_run.summary[key] = value
+        else:
+            logger.warning("openrunner.summary: no active run -- call openrunner.init() first")
+
+    def __repr__(self) -> str:
+        if _active_run is not None:
+            return repr(_active_run.summary)
+        return "SummaryProxy(no active run)"
+
+
+# Module-level proxy instances
+config = _ConfigProxy()
+summary = _SummaryProxy()
+
+
+# ---------------------------------------------------------------------------
+# Public API functions
+# ---------------------------------------------------------------------------
+
+def init(
+    project: str | None = None,
+    name: str | None = None,
+    config: dict[str, Any] | None = None,
+    tags: list[str] | None = None,
+    notes: str | None = None,
+    group: str | None = None,
+    job_type: str | None = None,
+    id: str | None = None,
+    resume: bool | str | None = None,
+    **kwargs: Any,
+) -> Run | None:
+    """Initialize a new run.
+
+    Creates a run on the server, starts the background sender thread,
+    and returns the Run object. Never raises -- SDK failures must not
+    crash training code.
+
+    Args:
+        project: Project name (or OPENRUNNER_PROJECT env var, or "uncategorized").
+        name: Display name for the run.
+        config: Hyperparameter dict (sent to server at init time, SDK-12).
+        tags: List of tags for the run.
+        notes: Notes/description for the run.
+        group: Group name for related runs.
+        job_type: Job type label.
+        id: Custom run ID (8-char alphanumeric generated if not provided).
+        resume: Resume mode -- True/"allow" (resume if exists, fresh otherwise)
+                or "must" (error if parent not found). The ``id`` parameter
+                is treated as the parent run ID when resuming.
+
+    Returns:
+        The Run object, or None if initialization fails.
+    """
+    global _active_run
+
+    try:
+        settings = SDKSettings()
+
+        # Resolve project
+        resolved_project = project or settings.project or "uncategorized"
+
+        # Warn if no API key (skip in offline mode)
+        if not settings.api_key and settings.mode != "offline":
+            logger.warning(
+                "No API key set. Set OPENRUNNER_API_KEY or WANDB_API_KEY "
+                "environment variable for server communication."
+            )
+
+        # Create run
+        run = Run(
+            project=resolved_project,
+            name=name,
+            config_dict=config,
+            tags=tags,
+            notes=notes,
+            group=group,
+            job_type=job_type,
+            run_id=id,
+            settings=settings,
+            resume=resume,
+        )
+
+        _active_run = run
+        return run
+
+    except Exception as e:
+        logger.warning("openrunner.init() failed: %s", e)
+        return None
+
+
+def log(
+    data: dict[str, Any],
+    step: int | None = None,
+    commit: bool = True,
+) -> None:
+    """Log metrics. Never raises -- training must not be interrupted.
+
+    Args:
+        data: Dict of metric key-value pairs.
+        step: Explicit step value.
+        commit: If True (default), finalize the current step.
+    """
+    try:
+        if _active_run is None:
+            logger.warning("openrunner.log(): no active run -- call openrunner.init() first")
+            return
+        _active_run.log(data, step=step, commit=commit)
+    except Exception as e:
+        logger.warning("openrunner.log() failed: %s", e)
+
+
+def finish(
+    exit_code: int | None = None,
+    quiet: bool | None = None,
+) -> None:
+    """Finish the active run. Never raises.
+
+    Args:
+        exit_code: Optional exit code.
+        quiet: If True, suppress the finish message.
+    """
+    global _active_run
+
+    try:
+        if _active_run is None:
+            return
+        _active_run.finish(exit_code=exit_code, quiet=quiet or False)
+        _active_run = None
+    except Exception as e:
+        logger.warning("openrunner.finish() failed: %s", e)
+        _active_run = None
+
+
+def log_artifact(artifact: Artifact) -> dict[str, Any] | None:
+    """Upload an artifact to the active run. Never raises.
+
+    Args:
+        artifact: The Artifact object with files added via add_file/add_dir.
+
+    Returns:
+        Server response dict with version info, or None on failure.
+    """
+    try:
+        if _active_run is None:
+            logger.warning("openrunner.log_artifact(): no active run")
+            return None
+        return _active_run.log_artifact(artifact)
+    except Exception as e:
+        logger.warning("openrunner.log_artifact() failed: %s", e)
+        return None
+
+
+def use_artifact(name: str, version: int | None = None) -> Path | None:
+    """Download an artifact and cache locally. Never raises.
+
+    Args:
+        name: Artifact name.
+        version: Specific version number, or None for latest.
+
+    Returns:
+        Path to the local artifact directory, or None on failure.
+    """
+    try:
+        if _active_run is None:
+            logger.warning("openrunner.use_artifact(): no active run")
+            return None
+        return _active_run.use_artifact(name, version)
+    except Exception as e:
+        logger.warning("openrunner.use_artifact() failed: %s", e)
+        return None
+
+
+@property  # type: ignore[misc]
+def run() -> Run | None:
+    """Return the active run, or None."""
+    return _active_run