micantis 1.2.4__tar.gz → 1.2.5__tar.gz

{micantis-1.2.4 → micantis-1.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: micantis
-Version: 1.2.4
+Version: 1.2.5
 Summary: Package to simplify Micantis API usage
 Author-email: Mykela DeLuca <mykela.deluca@micantis.io>
 License-Expression: MIT
@@ -1013,14 +1013,16 @@ for group in dupes:
 Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python script execution. Called from within a Python script running in the Micantis environment.
 
 #### Parameters
-- `execution_id`: **str (required)**
-  The execution ID (GUID) of the running or completed execution
+- `execution_id`: **str (optional inside cloud executions)**
+  The execution ID (GUID) of the running or completed execution. Defaults to the `WORKBOOK_EXECUTION_ID` environment variable, which cloud executions always set; required when running elsewhere. A non-GUID first positional argument is treated as `file_path`
 - `file_path`: **str (required)**
   Local path to the file to upload. Maximum size: 50 MB
 - `title`: **str (required)**
   Human-readable title for the artifact
 - `filename`: **str (optional)**
   Override the filename stored on the server. If not provided, derived from the title and file extension
+- `mime`: **str (optional)**
+  Content type stored for the artifact (e.g. `image/png`). If not provided, guessed from the file extension, falling back to `application/octet-stream`
 
 #### Returns
 - Dictionary with `'name'`, `'title'`, `'contentType'`, and `'sizeBytes'`
@@ -1028,22 +1030,19 @@ Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python sc
 #### 📘 Examples
 
 ```python
-# Upload a plot generated during a Python execution
-result = api.upload_execution_artifact(
-    execution_id="your-execution-guid",
-    file_path="voltage_plot.png",
-    title="Voltage vs Time"
-)
+# Inside a cloud execution — execution_id is resolved from the environment
+result = api.upload_execution_artifact("voltage_plot.png", title="Voltage vs Time")
 print(f"Uploaded: {result['name']} ({result['sizeBytes']:,} bytes)")
 ```
 
 ```python
-# Upload a CSV results file with a custom filename
+# Explicit execution ID with a custom filename and content type
 result = api.upload_execution_artifact(
     execution_id="your-execution-guid",
     file_path="results.csv",
     title="Cycle Summary Results",
-    filename="cycle_summary_2025.csv"
+    filename="cycle_summary_2025.csv",
+    mime="text/csv"
 )
 ```
 

{micantis-1.2.4 → micantis-1.2.5}/README.md

@@ -993,14 +993,16 @@ for group in dupes:
 Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python script execution. Called from within a Python script running in the Micantis environment.
 
 #### Parameters
-- `execution_id`: **str (required)**
-  The execution ID (GUID) of the running or completed execution
+- `execution_id`: **str (optional inside cloud executions)**
+  The execution ID (GUID) of the running or completed execution. Defaults to the `WORKBOOK_EXECUTION_ID` environment variable, which cloud executions always set; required when running elsewhere. A non-GUID first positional argument is treated as `file_path`
 - `file_path`: **str (required)**
   Local path to the file to upload. Maximum size: 50 MB
 - `title`: **str (required)**
   Human-readable title for the artifact
 - `filename`: **str (optional)**
   Override the filename stored on the server. If not provided, derived from the title and file extension
+- `mime`: **str (optional)**
+  Content type stored for the artifact (e.g. `image/png`). If not provided, guessed from the file extension, falling back to `application/octet-stream`
 
 #### Returns
 - Dictionary with `'name'`, `'title'`, `'contentType'`, and `'sizeBytes'`
@@ -1008,22 +1010,19 @@ Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python sc
 #### 📘 Examples
 
 ```python
-# Upload a plot generated during a Python execution
-result = api.upload_execution_artifact(
-    execution_id="your-execution-guid",
-    file_path="voltage_plot.png",
-    title="Voltage vs Time"
-)
+# Inside a cloud execution — execution_id is resolved from the environment
+result = api.upload_execution_artifact("voltage_plot.png", title="Voltage vs Time")
 print(f"Uploaded: {result['name']} ({result['sizeBytes']:,} bytes)")
 ```
 
 ```python
-# Upload a CSV results file with a custom filename
+# Explicit execution ID with a custom filename and content type
 result = api.upload_execution_artifact(
     execution_id="your-execution-guid",
     file_path="results.csv",
     title="Cycle Summary Results",
-    filename="cycle_summary_2025.csv"
+    filename="cycle_summary_2025.csv",
+    mime="text/csv"
 )
 ```
 

{micantis-1.2.4 → micantis-1.2.5}/micantis/api_wrapper.py

@@ -2,11 +2,15 @@ import requests
 import pandas as pd
 import io
 import json
+import mimetypes
 import os
 import re
 import time
+import tempfile
+import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Optional
+from urllib.parse import quote
 from msal import PublicClientApplication
 from azure.identity import (
     ManagedIdentityCredential,
@@ -43,6 +47,26 @@ def _apply_field_overrides(action, voltage, current, charge_capacity,
             action[key] = val
 
 
+def _is_guid(value) -> bool:
+    """True if value parses as a GUID — the format of execution IDs."""
+    try:
+        uuid.UUID(str(value))
+        return True
+    except ValueError:
+        return False
+
+
+# Content types that must not depend on the host OS mime registry
+# (Windows maps .csv to application/vnd.ms-excel, stored as an opaque artifact).
+_MIME_OVERRIDES = {
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".svg": "image/svg+xml",
+}
+
+
 class BatchUpdateResult:
     """
     Result of a batch metadata update call (`write_cell_metadata` / `write_data_metadata`).
@@ -2794,21 +2818,34 @@ class MicantisAPI:
             raise self._format_request_error(e)
 
     def upload_execution_artifact(self,
-                                  execution_id: str,
-                                  file_path: str,
-                                  title: str,
+                                  execution_id: str = None,
+                                  file_path: str = None,
+                                  title: str = None,
                                   filename: str = None,
-                                  timeout: int = 120) -> dict:
+                                  timeout: int = 120,
+                                  mime: str = None) -> dict:
         """
         Upload an artifact (output file) produced by a running Python execution.
 
+        Inside a cloud execution, execution_id can be omitted — it is resolved
+        from the WORKBOOK_EXECUTION_ID environment variable, which the runner
+        always sets. The natural call shape there is::
+
+            api.upload_execution_artifact('/tmp/plot.png', title='My Plot')
+
+        A first positional argument that is not a GUID is treated as file_path
+        (when file_path is not also given), so the line above works even though
+        the first parameter is execution_id.
+
         Automatically reauthenticates if the session is expired or missing.
         Prints an error message and returns None if the request ultimately fails.
 
         Parameters
         ----------
-        execution_id : str
+        execution_id : str, optional
             The execution ID (GUID) of the running or completed Python execution.
+            Defaults to the WORKBOOK_EXECUTION_ID environment variable (always
+            set inside cloud executions). Required when running outside one.
         file_path : str
             Local path to the file to upload (PNG, CSV, XLSX, JSON, PDF, etc.).
             Maximum file size: 50 MB.
@@ -2819,6 +2856,10 @@ class MicantisAPI:
             from the title and file extension.
         timeout : int, optional
             Request timeout in seconds. Default: 120.
+        mime : str, optional
+            Content type stored for the artifact (e.g. 'image/png'). If not
+            provided, guessed from the file_path extension, falling back to
+            'application/octet-stream'.
 
         Returns
         -------
@@ -2834,6 +2875,7 @@ class MicantisAPI:
                 title,
                 filename,
                 timeout,
+                mime,
             )
         except Exception as e:
             print(f"⚠️ upload_execution_artifact failed: {e}")
@@ -2844,28 +2886,61 @@ class MicantisAPI:
                                    file_path: str,
                                    title: str,
                                    filename: str,
-                                   timeout: int) -> dict:
+                                   timeout: int,
+                                   mime: str) -> dict:
         """
         Internal helper for upload_execution_artifact. Does not handle retries or printing.
 
         Raises
         ------
         RuntimeError
-            If the request fails or authentication is missing.
+            If arguments are missing or invalid, the request fails, or
+            authentication is missing.
         """
         if not self.headers:
             raise RuntimeError("Authentication required. Call authenticate() first.")
 
         self._refresh_token_if_needed()
 
+        # Forgive the natural call shape api.upload_execution_artifact('/tmp/plot.png', title=...):
+        # a non-GUID first argument is the file path, and the execution ID comes from the environment.
+        if execution_id is not None and not _is_guid(execution_id):
+            if file_path is None:
+                file_path = execution_id
+                execution_id = None
+            else:
+                raise RuntimeError(
+                    f"execution_id '{execution_id}' is not an execution GUID. Inside a cloud "
+                    "execution you can omit execution_id entirely — it is read from the "
+                    "WORKBOOK_EXECUTION_ID environment variable automatically."
+                )
+
+        if execution_id is None:
+            execution_id = os.environ.get("WORKBOOK_EXECUTION_ID")
+            if not execution_id:
+                raise RuntimeError(
+                    "No execution_id provided and WORKBOOK_EXECUTION_ID is not set. Inside a "
+                    "cloud execution the variable is set automatically; outside one, pass "
+                    "execution_id explicitly."
+                )
+
+        if not file_path:
+            raise RuntimeError("file_path is required.")
+        if not title:
+            raise RuntimeError("title is required.")
+
         url = f"{self.service_url}/publicapi/v1/python/executions/{execution_id}/artifacts"
 
+        ext = os.path.splitext(file_path)[1].lower()
+        content_type = (mime or _MIME_OVERRIDES.get(ext)
+                        or mimetypes.guess_type(file_path)[0] or "application/octet-stream")
+
         try:
             with open(file_path, 'rb') as f:
                 form_data = {'title': (None, title)}
                 if filename is not None:
                     form_data['filename'] = (None, filename)
-                form_data['file'] = (os.path.basename(file_path), f)
+                form_data['file'] = (os.path.basename(file_path), f, content_type)
 
                 # Exclude Content-Type so requests sets the multipart boundary correctly
                 headers = {k: v for k, v in self.headers.items() if k.lower() != 'content-type'}
@@ -2882,6 +2957,114 @@ class MicantisAPI:
         except requests.exceptions.RequestException as e:
             raise self._format_request_error(e)
 
+    def list_attachments(self, timeout: int = 30) -> list:
+        """
+        List the files attached to the Moose conversation that launched this script.
+
+        Only works inside a Moose-triggered cloud execution (uses WORKBOOK_EXECUTION_ID).
+        Automatically reauthenticates if the session is expired or missing. Prints an error
+        and returns None on failure.
+
+        Returns
+        -------
+        list of dict or None
+            One entry per attachment: {"name", "contentType", "sizeBytes"}.
+        """
+        try:
+            return self._retry_on_auth_failure(self._list_attachments, timeout)
+        except Exception as e:
+            print(f"⚠️ list_attachments failed: {e}")
+            return None
+
+    def _list_attachments(self, timeout: int) -> list:
+        if not self.headers:
+            raise RuntimeError("Authentication required. Call authenticate() first.")
+        self._refresh_token_if_needed()
+
+        execution_id = os.environ.get("WORKBOOK_EXECUTION_ID")
+        if not execution_id:
+            raise RuntimeError(
+                "list_attachments is only available inside a cloud execution (WORKBOOK_EXECUTION_ID is not set)."
+            )
+
+        try:
+            r = self.session.get(
+                f"{self.service_url}/publicapi/v1/python/executions/{execution_id}/attachments",
+                headers=self.headers,
+                timeout=timeout,
+            )
+            r.raise_for_status()
+            return r.json()
+        except requests.exceptions.RequestException as e:
+            raise self._format_request_error(e)
+
+    def download_attachment(self, name: str, output_path: str = None,
+                            return_type: str = "bytes", timeout: int = 120):
+        """
+        Download a file attached to the Moose conversation that launched this script, by name,
+        WITHOUT inlining its bytes into your script source. Use this for any conversation
+        attachment too large to paste in — inlining data into the script is bounded by the
+        per-turn output budget (a few KB), but this streams the file into the container.
+
+        Only works inside a Moose-triggered cloud execution (uses WORKBOOK_EXECUTION_ID). Call
+        list_attachments() first to get exact names. Automatically reauthenticates if the
+        session is expired or missing. Prints an error and returns None on failure.
+
+        Parameters
+        ----------
+        name : str
+            Exact attachment filename (from list_attachments()).
+        output_path : str, optional
+            Where to save the file when return_type='path'. Defaults to a temp file.
+        return_type : str, optional
+            'bytes' (default) returns the raw bytes; 'path' writes the file to disk and returns
+            the path (best for large files); 'text' returns a UTF-8-decoded str.
+        timeout : int, optional
+            Request timeout in seconds. Default: 120.
+
+        Returns
+        -------
+        bytes | str | None
+            The attachment content per return_type, or None on failure.
+        """
+        try:
+            return self._retry_on_auth_failure(
+                self._download_attachment, name, output_path, return_type, timeout)
+        except Exception as e:
+            print(f"⚠️ download_attachment failed: {e}")
+            return None
+
+    def _download_attachment(self, name: str, output_path: str, return_type: str, timeout: int):
+        if not self.headers:
+            raise RuntimeError("Authentication required. Call authenticate() first.")
+        self._refresh_token_if_needed()
+
+        execution_id = os.environ.get("WORKBOOK_EXECUTION_ID")
+        if not execution_id:
+            raise RuntimeError(
+                "download_attachment is only available inside a cloud execution (WORKBOOK_EXECUTION_ID is not set)."
+            )
+
+        url = (f"{self.service_url}/publicapi/v1/python/executions/{execution_id}"
+               f"/attachments/{quote(name)}")
+
+        try:
+            with self.session.get(url, headers=self.headers, timeout=timeout, stream=True) as r:
+                r.raise_for_status()
+                if return_type == "path":
+                    path = output_path or os.path.join(tempfile.gettempdir(), os.path.basename(name))
+                    with open(path, "wb") as f:
+                        for chunk in r.iter_content(chunk_size=1024 * 1024):
+                            if chunk:
+                                f.write(chunk)
+                    return path
+                content = r.content
+                if return_type == "text":
+                    return content.decode("utf-8", errors="replace")
+                return content
+        except requests.exceptions.RequestException as e:
+            raise self._format_request_error(e)
+
     # ─────────────────────────────────────────
     # Job management (async operation polling)
     # ─────────────────────────────────────────

{micantis-1.2.4 → micantis-1.2.5}/micantis.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: micantis
-Version: 1.2.4
+Version: 1.2.5
 Summary: Package to simplify Micantis API usage
 Author-email: Mykela DeLuca <mykela.deluca@micantis.io>
 License-Expression: MIT
@@ -1013,14 +1013,16 @@ for group in dupes:
 Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python script execution. Called from within a Python script running in the Micantis environment.
 
 #### Parameters
-- `execution_id`: **str (required)**
-  The execution ID (GUID) of the running or completed execution
+- `execution_id`: **str (optional inside cloud executions)**
+  The execution ID (GUID) of the running or completed execution. Defaults to the `WORKBOOK_EXECUTION_ID` environment variable, which cloud executions always set; required when running elsewhere. A non-GUID first positional argument is treated as `file_path`
 - `file_path`: **str (required)**
   Local path to the file to upload. Maximum size: 50 MB
 - `title`: **str (required)**
   Human-readable title for the artifact
 - `filename`: **str (optional)**
   Override the filename stored on the server. If not provided, derived from the title and file extension
+- `mime`: **str (optional)**
+  Content type stored for the artifact (e.g. `image/png`). If not provided, guessed from the file extension, falling back to `application/octet-stream`
 
 #### Returns
 - Dictionary with `'name'`, `'title'`, `'contentType'`, and `'sizeBytes'`
@@ -1028,22 +1030,19 @@ Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python sc
 #### 📘 Examples
 
 ```python
-# Upload a plot generated during a Python execution
-result = api.upload_execution_artifact(
-    execution_id="your-execution-guid",
-    file_path="voltage_plot.png",
-    title="Voltage vs Time"
-)
+# Inside a cloud execution — execution_id is resolved from the environment
+result = api.upload_execution_artifact("voltage_plot.png", title="Voltage vs Time")
 print(f"Uploaded: {result['name']} ({result['sizeBytes']:,} bytes)")
 ```
 
 ```python
-# Upload a CSV results file with a custom filename
+# Explicit execution ID with a custom filename and content type
 result = api.upload_execution_artifact(
     execution_id="your-execution-guid",
     file_path="results.csv",
     title="Cycle Summary Results",
-    filename="cycle_summary_2025.csv"
+    filename="cycle_summary_2025.csv",
+    mime="text/csv"
 )
 ```
 

{micantis-1.2.4 → micantis-1.2.5}/micantis.egg-info/SOURCES.txt

@@ -9,4 +9,5 @@ micantis.egg-info/SOURCES.txt
 micantis.egg-info/dependency_links.txt
 micantis.egg-info/requires.txt
 micantis.egg-info/top_level.txt
-tests/test_batch_update_result.py
+tests/test_batch_update_result.py
+tests/test_upload_execution_artifact.py

{micantis-1.2.4 → micantis-1.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "micantis"
-version = "1.2.4"
+version = "1.2.5"
 description = "Package to simplify Micantis API usage"
 authors = [
     { name = "Mykela DeLuca", email = "mykela.deluca@micantis.io" }

micantis-1.2.5/tests/test_upload_execution_artifact.py

@@ -0,0 +1,110 @@
+"""
+Unit tests for upload_execution_artifact argument resolution and multipart content type.
+
+Mocks the HTTP layer so it can run anywhere without a live server. Exercises the
+four supported call shapes:
+- Path-only positional + title + mime → execution_id resolved from WORKBOOK_EXECUTION_ID
+- Classic positional (guid, path, title) → unchanged, content type guessed from extension
+- Full keyword form → unchanged
+- No execution_id anywhere and no env var → clear printed error, returns None
+
+Run:  pytest
+"""
+from .test_batch_update_result import _make_api, _mock_response
+
+EXEC_ID = "11111111-2222-3333-4444-555555555555"
+OTHER_EXEC_ID = "99999999-8888-7777-6666-555555555555"
+
+RESULT_BODY = {
+    "name": "plot.png",
+    "title": "My Plot",
+    "contentType": "image/png",
+    "sizeBytes": 9,
+}
+
+
+def test_path_first_positional_resolves_execution_id_from_env(monkeypatch, tmp_path):
+    # The natural cloud call shape: file path first, no execution_id anywhere.
+    api = _make_api()
+    api.session.post.return_value = _mock_response(200, RESULT_BODY)
+    monkeypatch.setenv("WORKBOOK_EXECUTION_ID", EXEC_ID)
+
+    png = tmp_path / "plot.png"
+    png.write_bytes(b"\x89PNG fake")
+
+    result = api.upload_execution_artifact(str(png), title="My Plot", mime="image/png")
+
+    assert result == RESULT_BODY
+    url = api.session.post.call_args.args[0]
+    assert url == f"https://fake.test/publicapi/v1/python/executions/{EXEC_ID}/artifacts"
+    name, fobj, content_type = api.session.post.call_args.kwargs["files"]["file"]
+    assert name == "plot.png"
+    assert content_type == "image/png"
+    print("PASS: path-first positional resolves WORKBOOK_EXECUTION_ID and sends mime")
+
+
+def test_classic_positional_shape_unchanged(monkeypatch, tmp_path):
+    # (execution_id, file_path, title) keeps working; explicit GUID wins over the env var,
+    # and the part content type is guessed from the file extension when mime is omitted.
+    api = _make_api()
+    api.session.post.return_value = _mock_response(200, RESULT_BODY)
+    monkeypatch.setenv("WORKBOOK_EXECUTION_ID", OTHER_EXEC_ID)
+
+    png = tmp_path / "voltage_profile.png"
+    png.write_bytes(b"\x89PNG fake")
+
+    result = api.upload_execution_artifact(EXEC_ID, str(png), "Voltage Profile")
+
+    assert result == RESULT_BODY
+    url = api.session.post.call_args.args[0]
+    assert url == f"https://fake.test/publicapi/v1/python/executions/{EXEC_ID}/artifacts"
+    name, fobj, content_type = api.session.post.call_args.kwargs["files"]["file"]
+    assert name == "voltage_profile.png"
+    assert content_type == "image/png"
+    print("PASS: classic positional (guid, path, title) unchanged; mime guessed from extension")
+
+
+def test_keyword_shape_unchanged(monkeypatch, tmp_path):
+    api = _make_api()
+    api.session.post.return_value = _mock_response(200, RESULT_BODY)
+    monkeypatch.delenv("WORKBOOK_EXECUTION_ID", raising=False)
+
+    csv = tmp_path / "results.csv"
+    csv.write_text("a,b\n1,2\n")
+
+    result = api.upload_execution_artifact(
+        execution_id=EXEC_ID,
+        file_path=str(csv),
+        title="Analysis Results",
+        filename="cycle_summary.csv",
+    )
+
+    assert result == RESULT_BODY
+    url = api.session.post.call_args.args[0]
+    assert url == f"https://fake.test/publicapi/v1/python/executions/{EXEC_ID}/artifacts"
+    files = api.session.post.call_args.kwargs["files"]
+    assert files["filename"] == (None, "cycle_summary.csv")
+    name, fobj, content_type = files["file"]
+    assert name == "results.csv"
+    # Pinned by _MIME_OVERRIDES, independent of the host OS mime registry.
+    assert content_type == "text/csv"
+    print("PASS: full keyword form unchanged; filename part still sent")
+
+
+def test_missing_execution_id_and_env_var_reports_clear_error(monkeypatch, tmp_path, capsys):
+    # Outside a cloud execution with no explicit execution_id: P-03 convention —
+    # print the real error (naming the env var) and return None, no HTTP call.
+    api = _make_api()
+    monkeypatch.delenv("WORKBOOK_EXECUTION_ID", raising=False)
+
+    csv = tmp_path / "out.csv"
+    csv.write_text("a,b\n")
+
+    result = api.upload_execution_artifact(file_path=str(csv), title="Out")
+
+    assert result is None
+    out = capsys.readouterr().out
+    assert "upload_execution_artifact failed" in out
+    assert "WORKBOOK_EXECUTION_ID" in out
+    api.session.post.assert_not_called()
+    print("PASS: missing execution_id + env var → clear error naming WORKBOOK_EXECUTION_ID")