mainsequence 4.4.4__tar.gz → 4.4.5__tar.gz

{mainsequence-4.4.4/mainsequence.egg-info → mainsequence-4.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.4.4
+Version: 4.4.5
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.4.4 → mainsequence-4.4.5}/mainsequence/client/agent_runtime_models.py

@@ -318,6 +318,77 @@ class Agent(ShareableObjectMixin, BaseObjectOrm, BasePydanticModel):
             raise_for_response(response, payload=payload)
         return response.json()
 
+    def get_or_create_session_with_handle(
+        self,
+        *,
+        handle_unique_id: str,
+        name: str | None = None,
+        llm_provider: str | None = None,
+        llm_model: str | None = None,
+        llm_thinking: str | None = None,
+        session_metadata: dict[str, Any] | None = None,
+        timeout=None,
+    ) -> AgentSession:
+        """
+        Get or create this user's reusable session slot for this Agent.
+
+        Hits:
+            POST <detail_url>get_or_create_session_with_handle/
+
+        Request contract:
+        - `handle_unique_id` is required and is the stable session-slot key scoped
+          by `(agent, authenticated user)`.
+        - `name` is optional display text for a newly created session.
+        - LLM fields are creation-time overrides only. If the handle already has a
+          current session, the backend returns that session unchanged.
+        - `session_metadata` is creation-time caller metadata.
+
+        The response is expected to contain either a top-level `session` object or a
+        direct AgentSession payload. The SDK returns the AgentSession object.
+        """
+        resolved_handle_unique_id = str(handle_unique_id or "").strip()
+        if not resolved_handle_unique_id:
+            raise ValueError("handle_unique_id is required")
+
+        body: dict[str, Any] = {
+            "handle_unique_id": resolved_handle_unique_id,
+        }
+        if name is not None:
+            body["name"] = str(name)
+        if llm_provider is not None:
+            body["llm_provider"] = str(llm_provider)
+        if llm_model is not None:
+            body["llm_model"] = str(llm_model)
+        if llm_thinking is not None:
+            body["llm_thinking"] = str(llm_thinking)
+        if session_metadata is not None:
+            body["session_metadata"] = session_metadata
+
+        url = f"{self.get_detail_url()}get_or_create_session_with_handle/"
+        payload = {"json": serialize_to_json(body)}
+        response = make_request(
+            s=self.build_session(),
+            loaders=self.LOADERS,
+            r_type="POST",
+            url=url,
+            payload=payload,
+            time_out=timeout,
+        )
+        if response.status_code not in (200, 201):
+            raise_for_response(response, payload=payload)
+
+        response_payload = response.json()
+        session_payload = (
+            response_payload.get("session")
+            if isinstance(response_payload, dict)
+            else response_payload
+        )
+        if not isinstance(session_payload, dict):
+            raise TypeError(
+                "get_or_create_session_with_handle response must include a session object"
+            )
+        return AgentSession(**session_payload)
+
     def get_latest_session(self, timeout=None):
         """
         Fetch the latest recorded session for this agent.

{mainsequence-4.4.4 → mainsequence-4.4.5/mainsequence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.4.4
+Version: 4.4.5
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.4.4 → mainsequence-4.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence"
-version = "4.4.4"
+version = "4.4.5"
 description = "Main Sequence SDK "
 readme = "README.md"
 requires-python = ">=3.11"

{mainsequence-4.4.4 → mainsequence-4.4.5}/tests/test_filter_normalization.py

@@ -1555,6 +1555,105 @@ def test_agent_a2a_allocation_sends_caller_session_uid(monkeypatch):
     }
 
 
+def test_agent_get_or_create_session_with_handle_posts_stable_handle_contract(monkeypatch):
+    captured = {}
+    agent_uid = "e0e75693-4110-464c-93e0-82c7fd9c9a23"
+    session_uid = "3f1cc452-43ec-49cb-b2ba-87dbac164d29"
+    user_uid = "fdf409f7-d16f-4f71-986b-9057db6c7eca"
+    agent = agent_models_mod.Agent(
+        uid=agent_uid,
+        name="Research Copilot",
+        agent_type="custom",
+        agent_unique_id="research-copilot",
+        description="Research assistant.",
+        agent_card=None,
+        llm_provider="openai",
+        llm_model="gpt-5.4",
+        llm_thinking="medium",
+    )
+
+    class FakeResponse:
+        status_code = 201
+        content = b'{"ok": true}'
+
+        @staticmethod
+        def json():
+            return {
+                "created": True,
+                "handle_unique_id": "portfolio-review-q2-2026",
+                "handle_uid": "6f91f6a7-d706-49c6-a910-8667aa0468a5",
+                "session": {
+                    "uid": session_uid,
+                    "agent_uid": agent_uid,
+                    "agent_name": "Research Copilot",
+                    "agent_type": "custom",
+                    "created_by_user_uid": user_uid,
+                    "parent_session_uid": None,
+                    "name": "Quarterly portfolio review",
+                    "status": "running",
+                    "runtime_state": "running",
+                    "working": True,
+                    "started_at": "2026-01-01T00:00:00Z",
+                    "ended_at": None,
+                    "llm_provider": "openai",
+                    "llm_model": "gpt-5.4",
+                    "llm_thinking": "",
+                    "engine_name": "codex",
+                    "runtime_config_snapshot": {},
+                    "error_detail": "",
+                    "thread_id": "",
+                    "session_metadata": {"portfolio_uid": "portfolio-123"},
+                    "bound_handles": [
+                        {
+                            "handle_unique_id": "portfolio-review-q2-2026",
+                            "owner_user_uid": user_uid,
+                            "is_locked": False,
+                        }
+                    ],
+                },
+            }
+
+    def _fake_make_request(*, s, loaders, r_type, url, payload, time_out=None):
+        captured["r_type"] = r_type
+        captured["url"] = url
+        captured["payload"] = payload
+        captured["timeout"] = time_out
+        return FakeResponse()
+
+    monkeypatch.setattr(agent_models_mod, "make_request", _fake_make_request)
+
+    session = agent.get_or_create_session_with_handle(
+        handle_unique_id="portfolio-review-q2-2026",
+        name="Quarterly portfolio review",
+        llm_provider="openai",
+        llm_model="gpt-5.4",
+        llm_thinking="",
+        session_metadata={"portfolio_uid": "portfolio-123"},
+        timeout=13,
+    )
+
+    assert session.uid == session_uid
+    assert session.name == "Quarterly portfolio review"
+    assert captured == {
+        "r_type": "POST",
+        "url": (
+            f"{agent_models_mod.Agent.get_object_url()}/{agent_uid}/"
+            "get_or_create_session_with_handle/"
+        ),
+        "payload": {
+            "json": {
+                "handle_unique_id": "portfolio-review-q2-2026",
+                "name": "Quarterly portfolio review",
+                "llm_provider": "openai",
+                "llm_model": "gpt-5.4",
+                "llm_thinking": "",
+                "session_metadata": {"portfolio_uid": "portfolio-123"},
+            }
+        },
+        "timeout": 13,
+    }
+
+
 def _class_base_names_from_source(path: pathlib.Path) -> dict[str, list[str]]:
     tree = ast.parse(path.read_text(encoding="utf-8"))
     out: dict[str, list[str]] = {}