pi-python-core 0.10.2__py3-none-any.whl → 0.11.0__py3-none-any.whl

pi_python/_version.py

@@ -1 +1 @@
-__version__ = "0.10.2"
+__version__ = "0.11.0"

pi_python/agent.py

@@ -69,6 +69,8 @@ class Agent:
         thinking_budgets: dict[str, int] | None = None,
         transport: str | None = None,
         session_id: str | None = None,
+        auto_session_id: bool = True,
+        cache_session_id: str | None = None,
         get_api_key: Callable | None = None,
         on_payload: Callable | None = None,
         on_response: Callable | None = None,
@@ -87,6 +89,21 @@ class Agent:
         if type(include_tool_origin) is not bool:
             raise ConfigurationError("include_tool_origin must be a boolean")
         self.include_tool_origin = include_tool_origin
+        if type(auto_session_id) is not bool:
+            raise ConfigurationError("auto_session_id must be a boolean")
+        if cache_session_id is not None:
+            if (
+                not isinstance(cache_session_id, str)
+                or not 1 <= len(cache_session_id) <= 64
+                or any(not "!" <= char <= "~" for char in cache_session_id)
+            ):
+                raise ConfigurationError(
+                    "cache_session_id must contain 1–64 printable ASCII characters without spaces"
+                )
+            if not auto_session_id:
+                raise ConfigurationError("cache_session_id requires auto_session_id=True")
+        self._auto_session_id = auto_session_id
+        self._cache_session_id = cache_session_id
         self._queues = MessageQueues(steering_mode, follow_up_mode)
         if provider is not None and stream_fn is not None:
             raise ConfigurationError("Pass provider or stream_fn, not both")
@@ -148,6 +165,23 @@ class Agent:
         self._settled = asyncio.Event()
         self._settled.set()
 
+    @property
+    def cache_session_id(self) -> str | None:
+        """Agent-managed Codex cache fallback, independent of explicit session_id.
+
+        Save this alongside history and restore it with cache_session_id=... .
+        Reading it does not enable connection reuse. Explicit session_id takes
+        precedence on requests; cache_retention='none' suppresses both on the wire.
+        """
+        if (
+            not self._auto_session_id
+            or getattr(self.provider, "supports_agent_cache_session", False) is not True
+        ):
+            return None
+        if self._cache_session_id is None:
+            self._cache_session_id = str(uuid4())
+        return self._cache_session_id
+
     @property
     def steering_mode(self) -> str:
         return self._queues.steering_mode
@@ -265,6 +299,7 @@ class Agent:
             raise AgentBusyError("Cannot reset while running")
         baseline = current_system_message(self._messages)
         self._messages = [baseline] if baseline else []
+        self._cache_session_id = None
         self._last_error = None
         self._run = None
         self.clear_all_queues()

pi_python/features.py

@@ -20,6 +20,7 @@ FEATURES = MCP_FEATURES | frozenset(
         "loop-portal-v1",
         "nested-agent-ownership-v1",
         "application-tool-batches-v1",
+        "codex-auto-cache-session-v1",
         "plugin-requires-v1",
     }
 )

pi_python/loop.py

@@ -105,6 +105,14 @@ async def stream_response(run: Run) -> tuple[AssistantMessage, bool]:
         deepcopy(context.options),
         model_info=deepcopy(model) if isinstance(model, ModelInfo) else None,
     )
+    if (
+        getattr(run.provider, "supports_agent_cache_session", False) is True
+        and not request.options.get("session_id")
+        and request.options.get("cache_retention") != "none"
+    ):
+        cache_session_id = run.agent.cache_session_id
+        if cache_session_id is not None:
+            request._set_cache_session_id(cache_session_id)
     if run.hooks.get_api_key:
         request.api_key = await run.hook(
             "get_api_key", getattr(run.provider, "name", request.model)

pi_python/provider.py

@@ -28,6 +28,20 @@ class ModelRequest:
     on_response: Callable | None = field(default=None, repr=False)
     on_provider_stream_event: Callable | None = field(default=None, repr=False)
 
+    def _set_cache_session_id(self, value: str) -> None:
+        # Per-request metadata, deliberately outside the public dataclass fields
+        # and options. It must never be interpreted as a transport session_id.
+        self._agent_cache_session_id = value
+
+    @property
+    def cache_session_id(self) -> str | None:
+        """Optional Agent-owned cache affinity, never a transport session.
+
+        Providers opt in with supports_agent_cache_session=True. This property
+        is not a dataclass field and does not change serialized request options.
+        """
+        return getattr(self, "_agent_cache_session_id", None)
+
 
 @dataclass
 class ModelEvent:
@@ -109,6 +123,10 @@ def has_default_stream() -> bool:
 
 
 class DefaultProvider:
+    @property
+    def supports_agent_cache_session(self) -> bool:
+        return getattr(_default_stream, "supports_agent_cache_session", False) is True
+
     @property
     def name(self) -> str:
         return getattr(_default_stream, "name", "custom")

pi_python/providers/openai.py

@@ -318,6 +318,14 @@ class OpenAIProvider(RemoteProvider):
                 position += 1
         return items, transcript
 
+    def _cache_key(self, request: ModelRequest) -> str | None:
+        if request.options.get("cache_retention", "short") == "none":
+            return None
+        key = request.options.get("session_id")
+        if not key and getattr(self, "supports_agent_cache_session", False) is True:
+            key = request.cache_session_id
+        return key[:64] if isinstance(key, str) else key
+
     def build_request(self, request: ModelRequest, chatgpt_sign_in: bool = False) -> dict[str, Any]:
         model = self.model_info(request)
         compat = model.compat
@@ -334,9 +342,7 @@ class OpenAIProvider(RemoteProvider):
         retention = options.get("cache_retention", "short")
         if retention not in {"none", "short", "long"}:
             raise ConfigurationError("Invalid cache_retention")
-        key = options.get("session_id") if retention != "none" else None
-        if isinstance(key, str) and len(key) > 64:
-            key = key[:64]
+        key = self._cache_key(request)
         body: dict[str, Any] = {
             "model": request.model,
             "input": items,
@@ -436,13 +442,17 @@ class OpenAIProvider(RemoteProvider):
                     "OpenAI-Beta": "responses=experimental",
                 }
             )
-            if (
-                request.options.get("session_id")
-                and request.options.get("cache_retention") != "none"
-            ):
-                headers["session-id"] = headers["x-client-request-id"] = request.options[
-                    "session_id"
-                ][:64]
+            cache_key = self._cache_key(request)
+            if cache_key:
+                if request.options.get("session_id"):
+                    # Preserve the existing precedence of explicit session_id.
+                    headers["session-id"] = headers["x-client-request-id"] = cache_key
+                else:
+                    # Automatic defaults must not overwrite application headers.
+                    supplied = {name.lower() for name in headers}
+                    for name in ("session-id", "x-client-request-id"):
+                        if name not in supplied:
+                            headers[name] = cache_key
         if (
             self.name == "openai"
             and request.options.get("session_id")
@@ -458,7 +468,8 @@ class OpenAIProvider(RemoteProvider):
         body = await self.payload(request, self.build_request(request, chatgpt))
         if transport == "websocket-cached" and not request.options.get("session_id"):
             raise ConfigurationError("websocket-cached requires session_id")
-        # Pi caches a connection per session unless caching is disabled for the request.
+        # Only an application-supplied session_id can opt into connection reuse
+        # and response continuation. The Agent's cache fallback never reaches here.
         cached = (
             request.options.get("session_id")
             if request.options.get("cache_retention") != "none"
@@ -645,6 +656,7 @@ class OpenAIProvider(RemoteProvider):
 class OpenAICodexProvider(OpenAIProvider):
     name = "openai-codex"
     api = "openai-codex-responses"
+    supports_agent_cache_session = True
 
     def __init__(
         self, *, base_url: str = "https://chatgpt.com/backend-api/codex", **kwargs: Any

{pi_python_core-0.10.2.dist-info → pi_python_core-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pi-python-core
-Version: 0.10.2
+Version: 0.11.0
 Summary: An embeddable asyncio agent core with opt-in Claude and OpenAI providers
 License-Expression: MIT
 License-File: LICENSE
@@ -111,7 +111,7 @@ Apart from `provider_chat`, which needs real credentials, every example runs off
 
 The run loop, event order, hooks, queues, and the handling of errors and cancellation all match Pi, and this is checked differentially: the same inputs go to the pinned upstream code and to this library, and the model requests, tool calls, events and final transcript are compared item by item. All cases currently agree: 25 for the core loop, 50 for model connectors, 2 for multi-turn WebSocket, and 44 error-classification samples. The plugin rules for skills, prompt templates and frontmatter are compared the same way against Pi's coding-agent code.
 
-A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. Plugins are the one piece taken from that layer: an optional module that reads Pi's package format and builds an ordinary Agent from it. This project uses its own version numbers and is not an official Pi release.
+A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. The Agent also supplies cache-only session IDs for Codex, a responsibility upstream assigns to its coding-agent layer; see [cache sessions and the opt-out](docs/PROVIDERS.md#automatic-codex-cache-sessions). Plugins are another piece taken from that layer: an optional module that reads Pi's package format and builds an ordinary Agent from it. This project uses its own version numbers and is not an official Pi release.
 
 ## Documentation
 

{pi_python_core-0.10.2.dist-info → pi_python_core-0.11.0.dist-info}/RECORD

@@ -3,22 +3,22 @@ pi_python/_mcp_host.py,sha256=CXio-tiEeUCUfdl65tatwSrzIOYdgecdS00sO6tNy5k,8630
 pi_python/_mcp_interaction.py,sha256=jPL-C8wLjBDV9tOdvGVFfXOl8-1FQIDJLq-MojlzXaM,43851
 pi_python/_mcp_process.py,sha256=4szi5gMEP_0GUGOcV-oLPUuVQAUSb0ToAaiM979zHME,6324
 pi_python/_mcp_sampling.py,sha256=BcWCrPgjsRC-GNx65fIB-JPq2WzWnoBK2w9iTnyPUww,12148
-pi_python/_version.py,sha256=A_AARqtxTOj_AQTpjpgOxNx-UOBio5wYFfZ2mrdMKfs,23
-pi_python/agent.py,sha256=86_mWt2oysz0Llv0LkQRnGKjYsloVElkQFnrkE5ZXv0,18206
+pi_python/_version.py,sha256=raMu9XA9JEjvdoTmFqcOw7qhJX24rYDP7XmS59TAO-Q,23
+pi_python/agent.py,sha256=5yd5D_hDGwp74dtvH1SCQUQdLFpc1nxTqAEKBbleSDQ,19797
 pi_python/cancellation.py,sha256=DoQVdX7DcQdVLkl4OvhcpMhKZJEW0Kscl2-xxF6i6Y0,608
 pi_python/errors.py,sha256=65lT0nYfzqxRfUlFG-Y9vgYxfDHEuFiBfgqmFnX9_O8,675
 pi_python/estimate.py,sha256=dQQJ9UEGp57F3wO_CcU2oubgPe841ttgpUseK3Fu_0w,5048
 pi_python/events.py,sha256=HFYaPB9-yjOvmuM2Ly7SgfWDMJJfX9e1Q7ethqOHSB8,4626
-pi_python/features.py,sha256=V9Yhh1APuN8KaLMrAx8s00xeDLAF0ydh5jI5FCT9ZQg,1681
+pi_python/features.py,sha256=Q7X1ke7FcGCyb8XURw4iDa2-wfbaWQQCdbR4-Zh5fsk,1720
 pi_python/function_tools.py,sha256=DO8fZD-n5i62w22zLIjblCOTwnG8N-HIoSUo4yOpRM4,18862
 pi_python/hooks.py,sha256=jm6ep78NjdHxIPZvcOXTZIPxkfBMkffVTNzLvnHS9mM,1321
 pi_python/limits.py,sha256=K1aP1cFH4fVhtWIXqpWMmpkB9AI0wK-bz3Xd2hxnOs4,1157
-pi_python/loop.py,sha256=nr3P6fXnrG21DFXPCGMGTKssE30jJmMoWi4bKIWxOu0,18904
+pi_python/loop.py,sha256=Q67rzG0eERY3Y_NMDdCIbKZiadgdcF2sSB83qni92ms,19263
 pi_python/lowlevel.py,sha256=56wtwqD0Ur1AGAXGa7zclb1IpmRPFpSEss_nspkAdrI,5514
 pi_python/mcp.py,sha256=f7VOiOeBwJ48SrowJWmqtH3d-iavrv2GZo2KH45qeTA,16713
 pi_python/messages.py,sha256=jUoQxR-UZbIQYWu257dGiCx8K5z_RV89fJpHgv4t-Ww,18068
 pi_python/models.py,sha256=IejtaWvbURM9vv_2kkoDzfto2TR0OSLjuQeOh3IJZ1k,6094
-pi_python/provider.py,sha256=k_VfJu5WOQla_LkglTDAq5s-77ejCj4YRTyhJ8onZBo,4259
+pi_python/provider.py,sha256=WH1-8YQKuV0PrBTLdNJKN9oXYnnOQiCxt4kD2BL-ebw,5047
 pi_python/proxy.py,sha256=kpEUoE1oDkJW7VVaV72slN3uJUFgYR4Q6jtYOEe8LmQ,12159
 pi_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pi_python/queues.py,sha256=nQ5xRSA3MMOHMs_ZJnG9sT3-d_yKn72oSnxXqiKPrcI,3032
@@ -41,10 +41,10 @@ pi_python/providers/anthropic.py,sha256=PCH9h9WHNXbz7Pv01NM1d8NtHANthLRaU1mZUVUc
 pi_python/providers/common.py,sha256=z8dB2pIc-dRscPAppnA3ZwF_wJygunQb9pI9Wl4CvaA,8051
 pi_python/providers/completions.py,sha256=vcqoLfJ-9quMREEEAJcHYs3Oq-A0Sz8Q1NV1QLd3OJA,51362
 pi_python/providers/oauth.py,sha256=ZY8j7P-I-R6hZ8sInkGao957KWNGsqfvMF0F-YzlSgU,22786
-pi_python/providers/openai.py,sha256=p0WHDnojAYb7mUX8EbComwEU_XskcYoMhMIR07QlSfc,30196
+pi_python/providers/openai.py,sha256=c2xzfRd0RgYxbtgl-ruA0yLySq5W63mmwyu_HFQm2g0,30931
 pi_python/providers/transport.py,sha256=B1mGKlVEqYGVK1MlcA9opwRhnuUYGuaYuTslNC3O8xs,26772
-pi_python_core-0.10.2.dist-info/METADATA,sha256=SGNj48Q5U-Q-Z0AVANvz5CQoJVcLqYkMjEkXZN3AFA4,8939
-pi_python_core-0.10.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pi_python_core-0.10.2.dist-info/licenses/LICENSE,sha256=BFf1vOw7OyEWBd-10aSQQv1jjzaGpBD-CZwkolrxPEg,1069
-pi_python_core-0.10.2.dist-info/licenses/NOTICE,sha256=fJna16fm1ECHN7zVZhtyNmjLw8KGxGp8mL9blISF1K0,633
-pi_python_core-0.10.2.dist-info/RECORD,,
+pi_python_core-0.11.0.dist-info/METADATA,sha256=m36iv6YTPLV0GsXN29gp-rIwgRQSnO8m-uAtgvsovYs,9146
+pi_python_core-0.11.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pi_python_core-0.11.0.dist-info/licenses/LICENSE,sha256=BFf1vOw7OyEWBd-10aSQQv1jjzaGpBD-CZwkolrxPEg,1069
+pi_python_core-0.11.0.dist-info/licenses/NOTICE,sha256=fJna16fm1ECHN7zVZhtyNmjLw8KGxGp8mL9blISF1K0,633
+pi_python_core-0.11.0.dist-info/RECORD,,