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

{openrunner_sdk-2.24.2 → openrunner_sdk-2.37.4}/.gitignore

@@ -237,3 +237,7 @@ data/
 # MkDocs build output
 /site/
 .claude/worktrees/
+
+# Never commit DB dumps / backups (may contain prod user data)
+*.sql
+backup_*

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

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