openrunner-sdk 2.24.2__tar.gz → 2.37.0__tar.gz

{openrunner_sdk-2.24.2 → openrunner_sdk-2.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrunner-sdk
-Version: 2.24.2
+Version: 2.37.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

openrunner_sdk-2.37.0/openrunner/CLAUDE.md

@@ -0,0 +1,151 @@
+# OpenRunner SDK — Datasets (HuggingFace-style)
+
+`openrunner.datasets` is a near drop-in replacement for `huggingface_hub` +
+`datasets` for **org-level, reference-only** datasets (metadata, tags, card,
+optional small preview — no full content stored). `repo_id` is `"org/name"`.
+
+```python
+from openrunner import datasets as ord
+
+ord.create_dataset("gladia/wmt-en-fr", modality="Text", tasks=["translation"],
+                   languages=["en", "fr"], num_examples=40_000_000,
+                   format="parquet", source_uri="hf:wmt/wmt14",
+                   card="# WMT En-Fr\n...", preview=[{"en": "hi", "fr": "salut"}])
+
+ord.list_datasets(org="gladia")        # -> [DatasetInfo, ...]
+info = ord.dataset_info("gladia/wmt-en-fr")
+ds   = ord.load_dataset("gladia/wmt-en-fr")   # HF rows if source is hf:*, else metadata+preview
+ord.set_dataset_card("gladia/wmt-en-fr", md)  # update README
+ord.link_run("gladia/wmt-en-fr", run_id)      # lineage dataset -> run -> model
+ord.push_dataset("gladia/wmt-en-fr", license="cc-by-4.0")  # create-or-update
+```
+
+**ALWAYS link the dataset(s) a run uses** — pass `datasets=` to `init` so every
+run has data lineage (no "no dataset linked" reproducibility gap):
+
+```python
+openrunner.init(project="gladia/age-gender-sentiment-emotion", name="v15",
+                datasets=["03822df0-...", "gladia/fleurs"])   # UUID or org/name
+```
+
+(`openrunner.sync_environment(..., link_datasets=[...])` and
+`/openrunner:sync-env --link-dataset ID` do the same when pushing a local env.)
+
+`load_dataset` delegates to HF `datasets.load_dataset` when `source_uri` is
+`hf:org/name` and the package is installed; otherwise returns a `LoadedDataset`
+(`.info`, `.rows`, iterable). Facets match the HF Hub: modality, format,
+dataset_type (standard/benchmark/traces), tasks, languages, size.
+
+### Charts & diagrams in cards
+Dataset cards and model cards render markdown with two live graphic blocks —
+use them instead of static tables/images, with REAL data only:
+- ```` ```echarts ```` + a valid ECharts option (JSON) → a live chart
+  (line/bar/scatter/pie, and `series.type:"graph"` for node-edge dependency
+  graphs). e.g. plot per-subset row counts or eval metrics.
+- ```` ```mermaid ```` → a flowchart / sequence / ER diagram for pipeline or
+  schema. Rendered in `securityLevel:"strict"`.
+
+## Managed (governed) uploads
+
+Bind a dataset to **one** org storage connection so uploads flow through the API
+— credentials never leave the server, and every file is tracked (who/what/size/
+sha256/content-type). This avoids scattered connections and opaque bucket blobs.
+
+```python
+# bind at create (connection = org storage-connection NAME or UUID)
+ord.create_dataset("gladia/my-text-set", modality="Text", format="parquet",
+                   connection="ML.text-datasets")   # -> source_type="managed"
+
+ord.upload_file("gladia/my-text-set", "train.parquet")           # one file
+ord.upload_folder("gladia/my-text-set", "./data")                # whole tree
+ord.list_files("gladia/my-text-set")  # [{path,size_bytes,sha256,content_type,uploaded_by}]
+
+# or bind lazily on first upload of an unbound dataset:
+ord.upload_file("gladia/my-text-set", "train.parquet", connection="ML.text-datasets")
+```
+
+CLI: `openrunner datasets create … --connection ML.text-datasets`,
+`openrunner datasets upload org/name FILE_OR_DIR…`, `openrunner datasets files org/name`.
+
+Files land under `s3://<bucket>/<conn.prefix>/datasets/<org_id>/<name>/<path>`;
+`source_uri` is set to that prefix and `source_type` becomes `managed`.
+
+Uploading does **not** index/embed. To make a managed dataset searchable, build
+a LanceDB index (written to the same connection) — opt-in:
+
+```python
+ord.index_dataset("gladia/my-text-set", text_columns=["en", "fr"])  # FTS, no external svc
+ord.search_dataset("gladia/my-text-set", "translation", limit=10)
+ord.index_dataset("gladia/my-text-set", embed=True)  # + vectors, only if a server embedder is set
+```
+
+CLI: `openrunner datasets index org/name --text-col en --text-col fr`,
+`openrunner datasets search org/name "translation"`. FTS indexes a single
+combined `_text` column so one query spans all text fields; preview/search read
+the LanceDB table on the dataset's own connection.
+
+# OpenRunner MCP Integration
+
+When the user publishes a MODEL, or asks to write/update a model card:
+- FIRST call `mcp__openrunner__openrunner_model_card_standard` (pass `model_type`/`task`)
+  to get the rules + a fill-in template. Follow it exactly.
+- Ground every number in REAL data — read run `summary` (metrics live there),
+  `config`, environment, the project's AI sessions and repo reports. NEVER
+  fabricate a number; flag unknowns as `must benchmark`. Label each figure
+  `(ours, measured, <protocol>)` or as an external published reference.
+- Write the card with `mcp__openrunner__openrunner_set_model_card` (it validates
+  against the standard and returns non-blocking warnings). It only ever PATCHes
+  `card_markdown` — never touch other fields/runs/weights.
+- From the SDK: `openrunner.set_model_card(name, md)` / `openrunner.get_model_card(name)`,
+  `openrunner.MODEL_CARD_STANDARD`, `openrunner.model_card_template()`,
+  `openrunner.validate_model_card(md)`. CLI: `openrunner upload-artifact ... --card card.md`.
+  Call `log_artifact`/`link_artifact` EXACTLY ONCE per version (a second call
+  duplicates the version).
+
+When the user says a model is "done", wants to hand it over / ship / deploy it, or
+asks how to make a model ready for product (the ML / inference / foundations teams):
+- FIRST call `mcp__openrunner__openrunner_handover_standard` (pass `model_name`) to
+  get the Gladia Model Handover Standard: 13 mandatory deliverables, Definition of
+  Done, enablement session, ownership transfer, maturity tags POC/BETA/PROD-READY.
+- "It's done" != "ready for product". Ownership only transfers when the receiving
+  team can operate, modify, retrain and deploy WITHOUT the author.
+- Assess each deliverable against REAL artifacts/runs; fill gaps (model card via
+  `openrunner_model_card_standard`, benchmarks vs Solaria baselines, license
+  analysis, repro script, ops/COGS, known gaps with owner+ETA).
+- Validate with `mcp__openrunner__openrunner_validate_handover` (pass a `status`
+  map + `maturity`). Never call a model PROD-READY while a BLOCKING gap is open.
+- SDK: `openrunner.HANDOVER_STANDARD`, `handover_ticket_template(name)`,
+  `validate_handover(status, maturity=...)`. CLI: `openrunner handover standard|ticket|check`.
+  Slash command: `/openrunner:handover`.
+
+When the user asks about training metrics, loss charts, run data, or experiment results:
+- Use `mcp__openrunner__openrunner_watch_run` to show ASCII sparkline charts
+- Use `mcp__openrunner__openrunner_get_run_metrics` for raw metrics
+- Use `mcp__openrunner__openrunner_list_runs` to find runs
+- Use `mcp__openrunner__openrunner_search_sessions` to search AI session history
+
+Do NOT parse log files or grep for metrics when OpenRunner MCP tools are available.
+
+When the user asks to monitor a training, diagnose loss curves, or get training
+advice (diverging, overfitting, plateau, NaN loss, LR tuning):
+- Use `mcp__openrunner__openrunner_monitor_training` for a health verdict
+  (HEALTHY / IMPROVING / PLATEAUED / OVERFITTING / UNSTABLE / DIVERGING) plus
+  per-metric trend, plateau, instability and overfitting signals.
+- Run `/openrunner:training-recommendations [run_id]` for actionable fixes.
+
+When the user makes or describes a deliberate decision (changing a param,
+switching strategy, picking an architecture, a data/process/tooling choice):
+- Use `mcp__openrunner__openrunner_log_decision` to document it (context,
+  rationale, alternatives; `source_runs` for the run(s) it was decided from,
+  `param`/`old_value`/`new_value` for a param change, optional `markdown` body
+  + `attachment_url` PDF).
+- Use `mcp__openrunner__openrunner_set_decision_runs` to attach resulting runs.
+- Use `mcp__openrunner__openrunner_list_decisions` to review the decision log.
+- Run `/openrunner:log-decision` for a guided capture.
+- Decisions render to HTML/PDF: `GET /projects/{id}/decisions/{id}/render?format=pdf`.
+
+When the user asks about papers, research, or sessions:
+- Use `mcp__openrunner__openrunner_search_papers` for paper content
+- Use `mcp__openrunner__openrunner_search_research` for research plans
+- Use `mcp__openrunner__openrunner_search_sessions` for AI session history
+- Use `mcp__openrunner__openrunner_update_paper` to modify paper sections

{openrunner_sdk-2.24.2 → openrunner_sdk-2.37.0}/openrunner/__init__.py

@@ -35,6 +35,9 @@ Public API:
     openrunner.launch       -> Create a remote execution job
     openrunner.launch.from_run -> Re-launch from a previous run's config
     openrunner.LaunchJob    -> Job handle with .wait() and .cancel()
+    openrunner.reload_run   -> Reload a run to resume/recalibrate/restart it
+    openrunner.reload_environment -> Reload a full experiment env (config, data,
+                               checkpoints, model card, AI sessions) to iterate
     openrunner.trace        -> Decorator for LLM call tracing (supports sample_rate)
     openrunner.trace.patch_openai -> Auto-trace OpenAI chat completions
     openrunner.Prompt       -> Versioned prompt management (get/render/publish)
@@ -65,6 +68,43 @@ from pathlib import Path
 from typing import Any
 
 from openrunner.artifact import Artifact
+from openrunner.model_card import (
+    MODEL_CARD_STANDARD,
+    model_card_standard,
+    model_card_template,
+    validate_model_card,
+)
+from openrunner.handover import (
+    HANDOVER_STANDARD,
+    HANDOVER_DELIVERABLES,
+    MATURITY_TAGS,
+    MATURITY_DEFINITIONS,
+    OPTIMIZATION_SWEEP_GUIDE,
+    handover_standard,
+    handover_ticket_template,
+    optimization_sweep_guide,
+    validate_handover,
+)
+import openrunner.datasets as datasets
+from openrunner.datasets import (
+    DatasetInfo,
+    DatasetsClient,
+    create_dataset,
+    dataset_info,
+    index_dataset,
+    list_datasets,
+    link_project,
+    list_files,
+    load_dataset,
+    add_derivation,
+    push_dataset,
+    search_dataset,
+    set_dataset_card,
+    set_storage_policy,
+    upload_file,
+    upload_sharded,
+    upload_folder,
+)
 from openrunner.config import Config
 from openrunner.model import Model
 from openrunner.prompt import MessagesPrompt, Prompt, StringPrompt
@@ -92,8 +132,21 @@ from openrunner.media import (
 from openrunner.cost import add_cost
 from openrunner.dataset import Dataset
 from openrunner.query_api import Api
+from openrunner.reload import (
+    reload_run,
+    ReloadedExperiment,
+    reload_environment,
+    ExperimentEnvironment,
+    reload_project,
+    ProjectEnvironment,
+    check_reproducibility,
+    ReproReport,
+    dataset_handle,
+)
+from openrunner.sync import sync_environment, scan_environment
+from openrunner.projects import create_project
 from openrunner.run import Run
-from openrunner.settings import SDKSettings
+from openrunner.settings import SDKSettings, resolve_project, pin_project
 from openrunner.summary import Summary
 from openrunner.sweep import agent, sweep
 from openrunner.evaluation import EvaluationLogger, Scorer, evaluate, scorer
@@ -112,6 +165,9 @@ from openrunner.trace import trace, patch_openai as _patch_openai, set_thread_id
 import openrunner.scorers as scorers
 import openrunner.plot as plot
 import openrunner.gpu as gpu
+import openrunner.autoresearch as autoresearch
+import openrunner.research as research
+import openrunner.machine as machine
 
 # Attach from_run as a method on the launch function for
 # openrunner.launch.from_run() syntax
@@ -121,10 +177,14 @@ launch.from_run = _launch_from_run  # type: ignore[attr-defined]
 # openrunner.trace.patch_openai() syntax
 trace.patch_openai = _patch_openai  # type: ignore[attr-defined]
 
-__version__ = "2.24.2"
+__version__ = "2.37.0"
 
 logger = logging.getLogger("openrunner")
 
+
+class _RequireOrgError(ValueError):
+    """Raised (and never swallowed) when a run is created without an explicit org."""
+
 # Auto-install/update slash commands + MCP on import if version changed
 def _auto_install_on_import():
     try:
@@ -424,6 +484,7 @@ def init(
     config_exclude_keys: list[str] | None = None,
     config_include_keys: list[str] | None = None,
     allow_val_change: bool = False,
+    datasets: list[str] | str | None = None,
     **kwargs: Any,
 ) -> Run | None:
     """Initialize a new run.
@@ -468,6 +529,10 @@ def init(
         allow_val_change: If True, allow overwriting existing config values.
                    If False (default), setting a config key that already has
                    a different value raises ValueError.
+        datasets: Dataset(s) to link to this run for data lineage — a UUID,
+                   'org/name', or a list of them. ALWAYS pass the dataset(s) a
+                   run trains/evaluates on so the run is reproducible (no
+                   "no dataset linked" gap). Failures are logged, never raised.
 
     Returns:
         The Run object, or None if initialization fails.
@@ -526,8 +591,16 @@ def init(
         if resume is None and settings.resume:
             resume = settings.resume
 
-        # Resolve project
+        # Resolve project — REQUIRE explicit "org/project". A bare name (or the
+        # "uncategorized" fallback) resolves ambiguously across orgs, so reject
+        # it loudly (raised below — not swallowed by the resilience wrapper).
         resolved_project = project or settings.project or "uncategorized"
+        if "/" not in resolved_project or not resolved_project.split("/", 1)[0].strip():
+            raise _RequireOrgError(
+                f"project must be 'org/project' (got {resolved_project!r}). "
+                "A bare project name is rejected — set e.g. project='gladia/my-project' "
+                "or OPENRUNNER_PROJECT='gladia/my-project'."
+            )
 
         # Warn if no API key (skip in offline mode)
         if not settings.api_key and settings.mode != "offline":
@@ -577,6 +650,20 @@ def init(
             except Exception as e:
                 logger.warning("openrunner.init() save_code failed: %s", e)
 
+        # Auto-link datasets to the run (data lineage) — avoids the run-level
+        # "no dataset linked" reproducibility gap. Accepts UUIDs or 'org/name'.
+        if datasets:
+            refs = [datasets] if isinstance(datasets, str) else list(datasets)
+            try:
+                from openrunner import datasets as _ds
+                for ref in refs:
+                    try:
+                        _ds.link_run(ref, run.id)
+                    except Exception as e:  # noqa: BLE001
+                        logger.warning("init() could not link dataset %r: %s", ref, e)
+            except Exception as e:  # noqa: BLE001
+                logger.warning("init() dataset linking unavailable: %s", e)
+
         # Auto-import TensorBoard logs if requested
         if sync_tensorboard_path:
             try:
@@ -608,6 +695,8 @@ def init(
 
         return run
 
+    except _RequireOrgError:
+        raise  # hard-fail: never push to an ambiguous/wrong org
     except Exception as e:
         logger.warning("openrunner.init() failed: %s", e)
         return None
@@ -810,6 +899,43 @@ def link_artifact(
         return None
 
 
+def set_model_card(name: str, card_markdown: str) -> dict[str, Any] | None:
+    """Set the model card on a published artifact. Never raises.
+
+    Validates against ``MODEL_CARD_STANDARD`` (warnings are logged, not
+    enforced), then PATCHes ``card_markdown`` on the artifact named ``name`` in
+    the active run's project.
+
+    Args:
+        name: Artifact name (the model you published).
+        card_markdown: Full markdown card body. See ``MODEL_CARD_STANDARD`` and
+            ``model_card_template()``.
+
+    Returns:
+        The updated artifact dict, or None on failure.
+    """
+    try:
+        if _active_run is None:
+            logger.warning("openrunner.set_model_card(): no active run — call init() first")
+            return None
+        return _active_run.set_model_card(name, card_markdown)
+    except Exception as e:
+        logger.warning("openrunner.set_model_card() failed: %s", e)
+        return None
+
+
+def get_model_card(name: str) -> str | None:
+    """Return the current card_markdown for an artifact by name. Never raises."""
+    try:
+        if _active_run is None:
+            logger.warning("openrunner.get_model_card(): no active run — call init() first")
+            return None
+        return _active_run.get_model_card(name)
+    except Exception as e:
+        logger.warning("openrunner.get_model_card() failed: %s", e)
+        return None
+
+
 def use_artifact(
     name: str, version: int | None = None, alias: str | None = None
 ) -> Path | None: