podstack 1.3.13__tar.gz → 1.3.14__tar.gz

{podstack-1.3.13 → podstack-1.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: podstack
-Version: 1.3.13
+Version: 1.3.14
 Summary: Official Python SDK for Podstack GPU Notebook Platform
 Author-email: Podstack <support@podstack.ai>
 License-Expression: MIT
@@ -298,9 +298,9 @@ with registry.start_run(name="training-v1") as run:
     # Set tags
     registry.set_tag("framework", "pytorch")
 
-    # Log artifacts
-    registry.log_artifact("model.pt", "model")
-    registry.log_artifact("training_curves.png", "plots")
+    # Upload artifacts to cloud artifact store
+    registry.log_artifact("model.pt")
+    registry.log_artifact("training_curves.png", artifact_path="plots/curves.png")
 
     # Log dataset provenance (first-class resource, deduped by content hash)
     registry.log_dataset("imdb-reviews", path="data/imdb.csv", context="training")
@@ -316,7 +316,7 @@ with registry.start_run(name="training-v1") as run:
 ```python
 from podstack import registry
 
-# Log a model object (auto-detects framework)
+# Serialize and upload the model to the artifact store (auto-detects framework)
 registry.log_model(model, artifact_path="model", framework="pytorch")
 
 # Register in model registry
@@ -332,7 +332,7 @@ registry.set_model_stage("my-classifier", version=1, stage="production")
 # Set aliases
 registry.set_model_alias("my-classifier", alias="champion", version=1)
 
-# Load model from registry
+# Load model from any machine — files are downloaded automatically if missing locally
 model = registry.load_model("my-classifier", stage="production")
 ```
 
@@ -659,6 +659,155 @@ model = registry.get_model("sentiment-bert")
 lineage = registry.get_model_lineage(model.id)
 ```
 
+### Artifact Storage
+
+Podstack stores every artifact you log — model files, plots, CSV exports, anything — in the project's cloud artifact store. Artifacts are keyed by run ID, so the same file can be retrieved from any machine, by any project member, at any time.
+
+#### `log_artifact()` — upload a file for the active run
+
+```python
+# Upload a single file (uses the filename as the artifact path)
+registry.log_artifact("model.pt")
+
+# Upload with an explicit path inside the artifact store
+registry.log_artifact("training_curves.png", artifact_path="plots/curves.png")
+registry.log_artifact("feature_importance.csv", artifact_path="analysis/features.csv")
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `local_path` | `str` | required | Path to the local file to upload |
+| `artifact_path` | `str` | filename | Relative path inside the artifact store. Defaults to `os.path.basename(local_path)` |
+
+If the artifact store is temporarily unreachable, the SDK saves the file to a local fallback cache (`~/.podstack/artifacts/<run_id>/`) so your run is never interrupted.
+
+**Via the `Run` object** — equivalent to calling `registry.log_artifact()`:
+
+```python
+with registry.start_run("training-v1") as run:
+    run.log_artifact("confusion_matrix.png", artifact_path="plots/confusion_matrix.png")
+    run.log_artifact("model.pkl")
+```
+
+#### `list_artifacts()` — list all artifacts for a run
+
+```python
+artifacts = registry.list_artifacts(run_id)
+for a in artifacts:
+    print(f"{a['path']:40s}  {a['size'] / 1e6:.1f} MB  {a['last_modified']}")
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `run_id` | `str` | ID of the run to query |
+
+**Returns:** `list[dict]` — one entry per artifact:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `path` | `str` | Relative artifact path (e.g. `"plots/curves.png"`) |
+| `size` | `int` | File size in bytes |
+| `etag` | `str` | Content hash for integrity verification |
+| `last_modified` | `str` | ISO 8601 upload timestamp |
+
+#### `download_artifact()` — retrieve an artifact
+
+Downloads a specific artifact from the cloud store into a local directory. Falls back to the local cache when the store is unreachable.
+
+```python
+# Download a single file
+dest = registry.download_artifact("run-id", "model/model.pkl", "./downloads/")
+print(f"Saved to: {dest}")
+
+# Download a whole model directory
+dest = registry.download_artifact("run-id", "model", "./local_models/")
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `run_id` | `str` | ID of the run that logged the artifact |
+| `artifact_path` | `str` | Relative artifact path as logged (e.g. `"model/model.pkl"`) |
+| `local_path` | `str` | Destination directory |
+
+**Returns:** `str` — absolute path to the downloaded file or directory.
+
+**Raises:** `ArtifactNotFoundError` if the artifact cannot be found in the store or the local cache.
+
+#### Models as artifacts: `log_model()` and `load_model()`
+
+`log_model()` serializes your model to disk and uploads every resulting file to the artifact store in one call. `load_model()` resolves the registered model version, downloads any missing files from the store, then deserializes the model — so it works correctly from any machine regardless of where training happened.
+
+```python
+# ── Training machine ──────────────────────────────────────────────────────────
+with registry.start_run("bert-finetune-v3") as run:
+    # train...
+    registry.log_model(model, artifact_path="model", framework="pytorch")
+
+registry.register_model("sentiment-bert", run_id=run.id)
+registry.set_model_stage("sentiment-bert", version=3, stage="production")
+
+# ── Any machine (CI, inference server, colleague's laptop) ───────────────────
+# Model files are downloaded automatically from the artifact store if not cached
+model = registry.load_model("sentiment-bert", stage="production")
+```
+
+**`log_model()` parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model` | any | required | Model object (PyTorch, TensorFlow, sklearn, HuggingFace, or any picklable object) |
+| `artifact_path` | `str` | `"model"` | Sub-path inside the artifact store |
+| `framework` | `str` | auto-detected | `"pytorch"`, `"tensorflow"`, `"sklearn"`, `"huggingface"`, or `"pickle"` |
+| `metadata` | `dict` | `None` | Arbitrary key-value metadata stored as run params |
+
+**`load_model()` parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_name` | `str` | required | Registered model name |
+| `version` | `int` | `None` | Specific version to load. Mutually exclusive with `stage` |
+| `stage` | `str` | `None` | Stage to load from: `"development"`, `"staging"`, `"production"`, `"archived"` |
+| `framework` | `str` | from run params | Override framework for deserialization |
+
+#### Viewing artifacts in the dashboard
+
+Every artifact logged with `log_artifact()` or `log_model()` appears automatically in the **Artifacts tab** of the run's detail page in the Podstack dashboard. No extra steps are needed — the tab populates from the same store the SDK writes to.
+
+The Artifacts tab shows:
+
+| Column | Description |
+|--------|-------------|
+| **Path** | The relative artifact path as logged (e.g. `model/model.pkl`, `plots/curves.png`) |
+| **Type badge** | File extension, color-coded by category — model weights, data files, images, configs, etc. |
+| **Size** | Formatted file size (B / KB / MB) |
+| **Uploaded** | Timestamp of when the file was stored |
+| **Download** | One-click download button — opens a short-lived direct download link in the browser |
+
+A footer below the list shows the combined size of all artifacts for the run.
+
+```python
+# Everything logged here shows up in the dashboard Artifacts tab
+with registry.start_run("bert-finetune-v3") as run:
+    registry.log_params({"lr": 2e-5, "epochs": 3})
+    registry.log_metrics({"accuracy": 0.93})
+
+    # These all appear as separate rows in the Artifacts tab
+    registry.log_artifact("confusion_matrix.png", artifact_path="plots/confusion_matrix.png")
+    registry.log_artifact("feature_importance.csv", artifact_path="analysis/features.csv")
+    registry.log_model(model, artifact_path="model", framework="pytorch")
+    # ↳ each model file (model.pkl, config.json, etc.) appears as its own row
+```
+
+#### Access control
+
+Artifact upload and download URLs are issued by the registry API and require a valid API key and project membership. The URLs are short-lived, ensuring that access always reflects the current state of your project — a revoked key can no longer generate new URLs. Any member of a project can upload and download artifacts for runs within that project.
+
 ### List and Browse
 
 ```python
@@ -670,8 +819,12 @@ experiments = registry.list_experiments()
 # List models
 models = registry.list_models()
 
-# Download artifacts
-registry.download_artifact("run-id", "model/model.pt", "./downloads/")
+# List artifacts for a specific run
+artifacts = registry.list_artifacts(run_id)
+
+# Download a specific artifact to a local directory
+dest = registry.download_artifact("run-id", "model/model.pt", "./downloads/")
+print(f"Saved to: {dest}")
 ```
 
 ## GPU Runner - Direct Code Execution

{podstack-1.3.13 → podstack-1.3.14}/README.md

@@ -246,9 +246,9 @@ with registry.start_run(name="training-v1") as run:
     # Set tags
     registry.set_tag("framework", "pytorch")
 
-    # Log artifacts
-    registry.log_artifact("model.pt", "model")
-    registry.log_artifact("training_curves.png", "plots")
+    # Upload artifacts to cloud artifact store
+    registry.log_artifact("model.pt")
+    registry.log_artifact("training_curves.png", artifact_path="plots/curves.png")
 
     # Log dataset provenance (first-class resource, deduped by content hash)
     registry.log_dataset("imdb-reviews", path="data/imdb.csv", context="training")
@@ -264,7 +264,7 @@ with registry.start_run(name="training-v1") as run:
 ```python
 from podstack import registry
 
-# Log a model object (auto-detects framework)
+# Serialize and upload the model to the artifact store (auto-detects framework)
 registry.log_model(model, artifact_path="model", framework="pytorch")
 
 # Register in model registry
@@ -280,7 +280,7 @@ registry.set_model_stage("my-classifier", version=1, stage="production")
 # Set aliases
 registry.set_model_alias("my-classifier", alias="champion", version=1)
 
-# Load model from registry
+# Load model from any machine — files are downloaded automatically if missing locally
 model = registry.load_model("my-classifier", stage="production")
 ```
 
@@ -607,6 +607,155 @@ model = registry.get_model("sentiment-bert")
 lineage = registry.get_model_lineage(model.id)
 ```
 
+### Artifact Storage
+
+Podstack stores every artifact you log — model files, plots, CSV exports, anything — in the project's cloud artifact store. Artifacts are keyed by run ID, so the same file can be retrieved from any machine, by any project member, at any time.
+
+#### `log_artifact()` — upload a file for the active run
+
+```python
+# Upload a single file (uses the filename as the artifact path)
+registry.log_artifact("model.pt")
+
+# Upload with an explicit path inside the artifact store
+registry.log_artifact("training_curves.png", artifact_path="plots/curves.png")
+registry.log_artifact("feature_importance.csv", artifact_path="analysis/features.csv")
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `local_path` | `str` | required | Path to the local file to upload |
+| `artifact_path` | `str` | filename | Relative path inside the artifact store. Defaults to `os.path.basename(local_path)` |
+
+If the artifact store is temporarily unreachable, the SDK saves the file to a local fallback cache (`~/.podstack/artifacts/<run_id>/`) so your run is never interrupted.
+
+**Via the `Run` object** — equivalent to calling `registry.log_artifact()`:
+
+```python
+with registry.start_run("training-v1") as run:
+    run.log_artifact("confusion_matrix.png", artifact_path="plots/confusion_matrix.png")
+    run.log_artifact("model.pkl")
+```
+
+#### `list_artifacts()` — list all artifacts for a run
+
+```python
+artifacts = registry.list_artifacts(run_id)
+for a in artifacts:
+    print(f"{a['path']:40s}  {a['size'] / 1e6:.1f} MB  {a['last_modified']}")
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `run_id` | `str` | ID of the run to query |
+
+**Returns:** `list[dict]` — one entry per artifact:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `path` | `str` | Relative artifact path (e.g. `"plots/curves.png"`) |
+| `size` | `int` | File size in bytes |
+| `etag` | `str` | Content hash for integrity verification |
+| `last_modified` | `str` | ISO 8601 upload timestamp |
+
+#### `download_artifact()` — retrieve an artifact
+
+Downloads a specific artifact from the cloud store into a local directory. Falls back to the local cache when the store is unreachable.
+
+```python
+# Download a single file
+dest = registry.download_artifact("run-id", "model/model.pkl", "./downloads/")
+print(f"Saved to: {dest}")
+
+# Download a whole model directory
+dest = registry.download_artifact("run-id", "model", "./local_models/")
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `run_id` | `str` | ID of the run that logged the artifact |
+| `artifact_path` | `str` | Relative artifact path as logged (e.g. `"model/model.pkl"`) |
+| `local_path` | `str` | Destination directory |
+
+**Returns:** `str` — absolute path to the downloaded file or directory.
+
+**Raises:** `ArtifactNotFoundError` if the artifact cannot be found in the store or the local cache.
+
+#### Models as artifacts: `log_model()` and `load_model()`
+
+`log_model()` serializes your model to disk and uploads every resulting file to the artifact store in one call. `load_model()` resolves the registered model version, downloads any missing files from the store, then deserializes the model — so it works correctly from any machine regardless of where training happened.
+
+```python
+# ── Training machine ──────────────────────────────────────────────────────────
+with registry.start_run("bert-finetune-v3") as run:
+    # train...
+    registry.log_model(model, artifact_path="model", framework="pytorch")
+
+registry.register_model("sentiment-bert", run_id=run.id)
+registry.set_model_stage("sentiment-bert", version=3, stage="production")
+
+# ── Any machine (CI, inference server, colleague's laptop) ───────────────────
+# Model files are downloaded automatically from the artifact store if not cached
+model = registry.load_model("sentiment-bert", stage="production")
+```
+
+**`log_model()` parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model` | any | required | Model object (PyTorch, TensorFlow, sklearn, HuggingFace, or any picklable object) |
+| `artifact_path` | `str` | `"model"` | Sub-path inside the artifact store |
+| `framework` | `str` | auto-detected | `"pytorch"`, `"tensorflow"`, `"sklearn"`, `"huggingface"`, or `"pickle"` |
+| `metadata` | `dict` | `None` | Arbitrary key-value metadata stored as run params |
+
+**`load_model()` parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_name` | `str` | required | Registered model name |
+| `version` | `int` | `None` | Specific version to load. Mutually exclusive with `stage` |
+| `stage` | `str` | `None` | Stage to load from: `"development"`, `"staging"`, `"production"`, `"archived"` |
+| `framework` | `str` | from run params | Override framework for deserialization |
+
+#### Viewing artifacts in the dashboard
+
+Every artifact logged with `log_artifact()` or `log_model()` appears automatically in the **Artifacts tab** of the run's detail page in the Podstack dashboard. No extra steps are needed — the tab populates from the same store the SDK writes to.
+
+The Artifacts tab shows:
+
+| Column | Description |
+|--------|-------------|
+| **Path** | The relative artifact path as logged (e.g. `model/model.pkl`, `plots/curves.png`) |
+| **Type badge** | File extension, color-coded by category — model weights, data files, images, configs, etc. |
+| **Size** | Formatted file size (B / KB / MB) |
+| **Uploaded** | Timestamp of when the file was stored |
+| **Download** | One-click download button — opens a short-lived direct download link in the browser |
+
+A footer below the list shows the combined size of all artifacts for the run.
+
+```python
+# Everything logged here shows up in the dashboard Artifacts tab
+with registry.start_run("bert-finetune-v3") as run:
+    registry.log_params({"lr": 2e-5, "epochs": 3})
+    registry.log_metrics({"accuracy": 0.93})
+
+    # These all appear as separate rows in the Artifacts tab
+    registry.log_artifact("confusion_matrix.png", artifact_path="plots/confusion_matrix.png")
+    registry.log_artifact("feature_importance.csv", artifact_path="analysis/features.csv")
+    registry.log_model(model, artifact_path="model", framework="pytorch")
+    # ↳ each model file (model.pkl, config.json, etc.) appears as its own row
+```
+
+#### Access control
+
+Artifact upload and download URLs are issued by the registry API and require a valid API key and project membership. The URLs are short-lived, ensuring that access always reflects the current state of your project — a revoked key can no longer generate new URLs. Any member of a project can upload and download artifacts for runs within that project.
+
 ### List and Browse
 
 ```python
@@ -618,8 +767,12 @@ experiments = registry.list_experiments()
 # List models
 models = registry.list_models()
 
-# Download artifacts
-registry.download_artifact("run-id", "model/model.pt", "./downloads/")
+# List artifacts for a specific run
+artifacts = registry.list_artifacts(run_id)
+
+# Download a specific artifact to a local directory
+dest = registry.download_artifact("run-id", "model/model.pt", "./downloads/")
+print(f"Saved to: {dest}")
 ```
 
 ## GPU Runner - Direct Code Execution