python-codex 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

pycodex/portable_server.py

@@ -1,56 +1,57 @@
-from __future__ import annotations
 
 import argparse
 import hashlib
 import json
 import threading
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from http.server import BaseHTTPRequestHandler
 from pathlib import Path
 from urllib.parse import unquote, urlparse
 
+from .compat import ThreadingHTTPServer
 from .portable import (
     DEFAULT_STORAGE_SERVER,
     HEALTHCHECK_PATH,
     STORAGE_API_PREFIX,
     _call_id_from_payload,
 )
+import typing
 
 
 class CodexStorageServer:
     def __init__(
         self,
-        root: str | Path,
-        host: str = "127.0.0.1",
-        port: int = 5577,
-    ) -> None:
+        root: 'typing.Union[str, Path]',
+        host: 'str' = "127.0.0.1",
+        port: 'int' = 5577,
+    ) -> 'None':
         self._root = Path(root).resolve()
         self._root.mkdir(parents=True, exist_ok=True)
         self._objects_dir = self._root / "objects"
         self._objects_dir.mkdir(parents=True, exist_ok=True)
         self._server = ThreadingHTTPServer((host, port), self._build_handler())
-        self._thread: threading.Thread | None = None
+        self._thread: 'typing.Union[threading.Thread, None]' = None
 
     @property
-    def host(self) -> str:
+    def host(self) -> 'str':
         return str(self._server.server_address[0])
 
     @property
-    def port(self) -> int:
+    def port(self) -> 'int':
         return int(self._server.server_address[1])
 
     @property
-    def server_address(self) -> str:
+    def server_address(self) -> 'str':
         return f"{self.host}:{self.port}"
 
     @property
-    def base_url(self) -> str:
+    def base_url(self) -> 'str':
         return f"http://{self.server_address}{STORAGE_API_PREFIX}"
 
     @property
-    def root(self) -> Path:
+    def root(self) -> 'Path':
         return self._root
 
-    def start(self) -> None:
+    def start(self) -> 'None':
         if self._thread is not None:
             return
         self._thread = threading.Thread(
@@ -60,7 +61,7 @@ class CodexStorageServer:
         )
         self._thread.start()
 
-    def stop(self) -> None:
+    def stop(self) -> 'None':
         self._server.shutdown()
         self._server.server_close()
         if self._thread is not None:
@@ -71,7 +72,7 @@ class CodexStorageServer:
         server = self
 
         class Handler(BaseHTTPRequestHandler):
-            def do_GET(self) -> None:  # noqa: N802
+            def do_GET(self) -> 'None':  # noqa: N802
                 path = urlparse(self.path).path
                 if path == HEALTHCHECK_PATH:
                     self._send_json(200, {"ok": True})
@@ -101,7 +102,7 @@ class CodexStorageServer:
                 self.end_headers()
                 self.wfile.write(payload)
 
-            def do_POST(self) -> None:  # noqa: N802
+            def do_POST(self) -> 'None':  # noqa: N802
                 path = urlparse(self.path).path
                 if path != f"{STORAGE_API_PREFIX}/put":
                     self._send_json(404, {"error": "not found"})
@@ -138,10 +139,10 @@ class CodexStorageServer:
                     },
                 )
 
-            def log_message(self, _format: str, *_args) -> None:
+            def log_message(self, _format: 'str', *_args) -> 'None':
                 return
 
-            def _send_json(self, status: int, payload: dict[str, object]) -> None:
+            def _send_json(self, status: 'int', payload: 'typing.Dict[str, object]') -> 'None':
                 body = json.dumps(payload).encode("utf-8")
                 self.send_response(status)
                 self.send_header("Content-Type", "application/json")
@@ -151,11 +152,11 @@ class CodexStorageServer:
 
         return Handler
 
-    def _object_path(self, call_id: str) -> Path:
+    def _object_path(self, call_id: 'str') -> 'Path':
         return self._objects_dir / f"{call_id}.bin"
 
 
-def build_parser() -> argparse.ArgumentParser:
+def build_parser() -> 'argparse.ArgumentParser':
     parser = argparse.ArgumentParser(
         prog="python -m pycodex.portable_server",
         description="Run a pycodex remote storage service for --put/--call testing.",
@@ -179,7 +180,7 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def main(argv: list[str] | None = None) -> int:
+def main(argv: 'typing.Union[typing.List[str], None]' = None) -> 'int':
     parser = build_parser()
     args = parser.parse_args(argv)
     server = CodexStorageServer(args.root, host=args.host, port=args.port)

pycodex/protocol.py

@@ -14,35 +14,35 @@
 本文件只定义这些抽象之间传递的数据结构，不包含具体执行逻辑。
 """
 
-from __future__ import annotations
-
 from copy import deepcopy
 import json
 from dataclasses import dataclass, field
-from typing import Any, Literal, TypeAlias
+from typing import Any
+from .compat import Literal, TypeAlias
+import typing
 
-JSONValue: TypeAlias = Any
-JSONDict: TypeAlias = dict[str, Any]
+JSONValue: 'TypeAlias' = Any
+JSONDict: 'TypeAlias' = typing.Dict[str, Any]
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class ToolSpec:
     """何时：AgentLoop 准备发起一轮模型请求时，随 `Prompt.tools` 一起发送。
     发送方：AgentLoop。
     接收方：ModelClient。
     """
 
-    name: str
-    description: str
-    input_schema: JSONDict | None = None
-    tool_type: Literal["function", "custom", "web_search"] = "function"
-    format: JSONDict | None = None
-    options: JSONDict | None = None
-    output_schema: JSONDict | None = None
-    supports_parallel: bool = True
-    raw_payload: JSONDict | None = None
-
-    def serialize(self) -> JSONDict:
+    name: 'str'
+    description: 'str'
+    input_schema: 'typing.Union[JSONDict, None]' = None
+    tool_type: 'Literal["function", "custom", "web_search"]' = "function"
+    format: 'typing.Union[JSONDict, None]' = None
+    options: 'typing.Union[JSONDict, None]' = None
+    output_schema: 'typing.Union[JSONDict, None]' = None
+    supports_parallel: 'bool' = True
+    raw_payload: 'typing.Union[JSONDict, None]' = None
+
+    def serialize(self) -> 'JSONDict':
         if self.raw_payload is not None:
             return deepcopy(self.raw_payload)
         if self.tool_type == "web_search":
@@ -76,17 +76,17 @@ class ToolSpec:
         return payload
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class UserMessage:
     """何时：外部发起一个新的用户 turn 时创建，并写入会话历史。
     发送方：外部调用方创建，AgentLoop 转发。
     接收方：AgentLoop 先接收，随后 ModelClient 在 `Prompt.input` 中看到它。
     """
 
-    text: str
-    role: Literal["user"] = "user"
+    text: 'str'
+    role: 'Literal["user"]' = "user"
 
-    def serialize(self) -> JSONDict:
+    def serialize(self) -> 'JSONDict':
         return {
             "type": "message",
             "role": self.role,
@@ -94,17 +94,17 @@ class UserMessage:
         }
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class AssistantMessage:
     """何时：模型要直接输出自然语言内容时产生，可作为中间文本或最终回复。
     发送方：ModelClient。
     接收方：AgentLoop。
     """
 
-    text: str
-    role: Literal["assistant"] = "assistant"
+    text: 'str'
+    role: 'Literal["assistant"]' = "assistant"
 
-    def serialize(self) -> JSONDict:
+    def serialize(self) -> 'JSONDict':
         return {
             "type": "message",
             "role": self.role,
@@ -112,18 +112,18 @@ class AssistantMessage:
         }
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class ContextMessage:
     """何时：ContextManager 为单轮模型请求注入额外上下文时构造。
     发送方：ContextManager。
     接收方：ModelClient。
     """
 
-    text: str | None = None
-    role: Literal["user", "developer"] = "user"
-    content_items: tuple[JSONDict, ...] | None = None
+    text: 'typing.Union[str, None]' = None
+    role: 'Literal["user", "developer"]' = "user"
+    content_items: 'typing.Union[typing.Tuple[JSONDict, ...], None]' = None
 
-    def serialize(self) -> JSONDict:
+    def serialize(self) -> 'JSONDict':
         if self.content_items is not None:
             content = list(self.content_items)
         else:
@@ -137,20 +137,20 @@ class ContextMessage:
         }
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class ToolCall:
     """何时：模型决定调用工具而不是只输出文本时产生。
     发送方：ModelClient。
     接收方：AgentLoop，随后由它转给 ToolRegistry 执行。
     """
 
-    call_id: str
-    name: str
-    arguments: JSONValue
-    tool_type: Literal["function", "custom"] = "function"
-    kind: Literal["tool_call"] = "tool_call"
+    call_id: 'str'
+    name: 'str'
+    arguments: 'JSONValue'
+    tool_type: 'Literal["function", "custom"]' = "function"
+    kind: 'Literal["tool_call"]' = "tool_call"
 
-    def serialize(self) -> JSONDict:
+    def serialize(self) -> 'JSONDict':
         if self.tool_type == "custom":
             return {
                 "type": "custom_tool_call",
@@ -170,7 +170,7 @@ class ToolCall:
         }
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class ReasoningItem:
     """何时：模型在一次 Responses 采样里产出 reasoning item 时产生。
     发送方：ModelClient。
@@ -178,30 +178,30 @@ class ReasoningItem:
     ModelClient。
     """
 
-    payload: JSONDict
-    kind: Literal["reasoning"] = "reasoning"
+    payload: 'JSONDict'
+    kind: 'Literal["reasoning"]' = "reasoning"
 
-    def serialize(self) -> JSONDict:
+    def serialize(self) -> 'JSONDict':
         return deepcopy(self.payload)
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class ToolResult:
     """何时：某个 `ToolCall` 执行完成后产生，用于喂回下一轮模型调用。
     发送方：ToolRegistry 产出，AgentLoop 追加并转发。
     接收方：AgentLoop 先接收，随后 ModelClient 在下一轮 `Prompt.input` 中看到它。
     """
 
-    call_id: str
-    name: str
-    output: JSONValue
-    content_items: tuple[JSONDict, ...] | None = None
-    success: bool | None = None
-    is_error: bool = False
-    tool_type: Literal["function", "custom"] = "function"
-    kind: Literal["tool_result"] = "tool_result"
+    call_id: 'str'
+    name: 'str'
+    output: 'JSONValue'
+    content_items: 'typing.Union[typing.Tuple[JSONDict, ...], None]' = None
+    success: 'typing.Union[bool, None]' = None
+    is_error: 'bool' = False
+    tool_type: 'Literal["function", "custom"]' = "function"
+    kind: 'Literal["tool_result"]' = "tool_result"
 
-    def output_text(self) -> str:
+    def output_text(self) -> 'str':
         if self.content_items is not None:
             text_parts = [
                 str(item.get("text", ""))
@@ -217,8 +217,8 @@ class ToolResult:
             return self.output
         return json.dumps(self.output, ensure_ascii=False)
 
-    def serialize(self) -> JSONDict:
-        payload_output: JSONValue
+    def serialize(self) -> 'JSONDict':
+        payload_output: 'JSONValue'
         if self.content_items is not None:
             payload_output = list(self.content_items)
         elif isinstance(self.output, str):
@@ -247,86 +247,84 @@ class ToolResult:
         return payload
 
 
-ConversationItem: TypeAlias = (
-    UserMessage | AssistantMessage | ContextMessage | ToolCall | ReasoningItem | ToolResult
-)
-ModelOutputItem: TypeAlias = AssistantMessage | ToolCall | ReasoningItem
-Operation: TypeAlias = "UserTurnOp | ShutdownOp"
+ConversationItem: 'TypeAlias' = typing.Union[typing.Union[typing.Union[typing.Union[typing.Union[UserMessage, AssistantMessage], ContextMessage], ToolCall], ReasoningItem], ToolResult]
+ModelOutputItem: 'TypeAlias' = typing.Union[typing.Union[AssistantMessage, ToolCall], ReasoningItem]
+Operation: 'TypeAlias' = "UserTurnOp | ShutdownOp"
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class Prompt:
     """何时：AgentLoop 每发起一轮模型采样前构造。
     发送方：AgentLoop。
     接收方：ModelClient。
     """
 
-    input: list[ConversationItem]
-    tools: list[ToolSpec]
-    parallel_tool_calls: bool = True
-    base_instructions: str | None = None
-    turn_id: str | None = None
-    turn_metadata: JSONDict | None = None
+    input: 'typing.List[ConversationItem]'
+    tools: 'typing.List[ToolSpec]'
+    parallel_tool_calls: 'bool' = True
+    base_instructions: 'typing.Union[str, None]' = None
+    turn_id: 'typing.Union[str, None]' = None
+    turn_metadata: 'typing.Union[JSONDict, None]' = None
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class ModelResponse:
     """何时：ModelClient 完成一轮 `Prompt` 处理后返回。
     发送方：ModelClient。
     接收方：AgentLoop。
     """
 
-    items: list[ModelOutputItem]
+    items: 'typing.List[ModelOutputItem]'
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class ModelStreamEvent:
     """何时：ModelClient 处理 `Prompt` 的过程中有流式中间结果时产生。
     发送方：ModelClient。
     接收方：AgentLoop。
     """
 
-    kind: str
-    payload: JSONDict = field(default_factory=dict)
+    kind: 'str'
+    payload: 'JSONDict' = field(default_factory=dict)
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class TurnResult:
     """何时：一个 turn 已经收敛，AgentLoop 决定结束本轮时返回。
     发送方：AgentLoop。
     接收方：外部调用方。
     """
 
-    turn_id: str
-    output_text: str | None
-    iterations: int
-    response_items: tuple[ModelOutputItem, ...]
-    history: tuple[ConversationItem, ...]
+    turn_id: 'str'
+    output_text: 'typing.Union[str, None]'
+    iterations: 'int'
+    response_items: 'typing.Tuple[ModelOutputItem, ...]'
+    history: 'typing.Tuple[ConversationItem, ...]'
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class AgentEvent:
     """何时：主循环运行过程中发生阶段性事件时发出，例如模型调用、工具开始/结束。
     发送方：AgentLoop。
     接收方：可选的事件观察者 / 回调。
     """
 
-    kind: str
-    turn_id: str
-    payload: dict[str, object] = field(default_factory=dict)
+    kind: 'str'
+    turn_id: 'str'
+    payload: 'typing.Dict[str, object]' = field(default_factory=dict)
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class UserTurnOp:
     """何时：运行时要提交一个新的用户请求时创建。
     发送方：外部运行时调用方。
     接收方：AgentRuntime。
     """
 
-    texts: list[str]
+    texts: 'typing.List[str]'
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class ShutdownOp:
     """何时：运行时要停止外层提交循环时创建。
     发送方：外部运行时调用方。
@@ -336,12 +334,12 @@ class ShutdownOp:
     pass
 
 
-@dataclass(frozen=True, slots=True)
+@dataclass(frozen=True, )
 class Submission:
     """何时：任意运行时操作要进入 AgentRuntime 队列时创建。
     发送方：外部运行时调用方。
     接收方：AgentRuntime 的提交队列 / 外层循环。
     """
 
-    id: str
-    op: Operation
+    id: 'str'
+    op: 'Operation'

pycodex/runtime.py

@@ -1,44 +1,45 @@
-from __future__ import annotations
 
 import asyncio
 from collections import deque
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING
 
 from .agent import AgentLoop, EventHandler, NOOP_EVENT_HANDLER, TurnInterrupted
+from .compat import Literal
 from .protocol import AgentEvent, Operation, ShutdownOp, Submission, TurnResult, UserTurnOp
 from .utils import uuid7_string
+import typing
 
 if TYPE_CHECKING:
     from .runtime_services import RuntimeEnvironment
 
 
-@dataclass(slots=True)
+@dataclass
 class _QueuedSubmission:
-    submission: Submission
-    turn_id: str
-    futures: list[asyncio.Future[TurnResult | None]]
+    submission: 'Submission'
+    turn_id: 'str'
+    futures: 'typing.List[asyncio.Future[typing.Union[TurnResult, None]]]'
 
 
 class AgentRuntime:
     """Thin outer queue that mirrors the Rust `submission_loop` shape."""
 
-    def __init__(self, agent_loop: AgentLoop, runtime_environment: RuntimeEnvironment | None = None) -> None:
+    def __init__(self, agent_loop: 'AgentLoop', runtime_environment: 'typing.Union[RuntimeEnvironment, None]' = None) -> 'None':
         self._agent_loop = agent_loop
         self.runtime_environment = runtime_environment
-        self._enqueue_queue: deque[_QueuedSubmission] = deque()
-        self._steer_queue: deque[_QueuedSubmission] = deque()
+        self._enqueue_queue: 'deque[_QueuedSubmission]' = deque()
+        self._steer_queue: 'deque[_QueuedSubmission]' = deque()
         self._queue_lock = asyncio.Lock()
         self._queue_event = asyncio.Event()
-        self._current_submission: _QueuedSubmission | None = None
-        self._current_task: asyncio.Task[TurnResult] | None = None
+        self._current_submission: 'typing.Union[_QueuedSubmission, None]' = None
+        self._current_task: 'typing.Union[asyncio.Task[TurnResult], None]' = None
         self._event_handler = NOOP_EVENT_HANDLER
         self._agent_loop.set_event_handler(self._handle_agent_event)
 
-    def set_event_handler(self, event_handler: EventHandler = NOOP_EVENT_HANDLER) -> None:
+    def set_event_handler(self, event_handler: 'EventHandler' = NOOP_EVENT_HANDLER) -> 'None':
         self._event_handler = event_handler
 
-    async def submit_user_turn(self, text: str) -> TurnResult:
+    async def submit_user_turn(self, text: 'str') -> 'TurnResult':
         _submission_id, future = await self.enqueue_user_turn(text, queue="enqueue")
         result = await future
         assert result is not None
@@ -46,19 +47,19 @@ class AgentRuntime:
 
     async def enqueue_user_turn(
         self,
-        text: str,
-        queue: Literal["enqueue", "steer"] = "enqueue",
-    ) -> tuple[str, asyncio.Future[TurnResult | None]]:
-        future: asyncio.Future[TurnResult | None] = asyncio.get_running_loop().create_future()
+        text: 'str',
+        queue: 'Literal["enqueue", "steer"]' = "enqueue",
+    ) -> 'typing.Tuple[str, asyncio.Future[typing.Union[TurnResult, None]]]':
+        future: 'asyncio.Future[typing.Union[TurnResult, None]]' = asyncio.get_running_loop().create_future()
         return await self._enqueue_user_turn_to_queue(
             text,
             future,
             queue=queue,
         )
 
-    async def shutdown(self) -> None:
+    async def shutdown(self) -> 'None':
         submission = Submission(id=uuid7_string(), op=ShutdownOp())
-        future: asyncio.Future[TurnResult | None] = asyncio.get_running_loop().create_future()
+        future: 'asyncio.Future[typing.Union[TurnResult, None]]' = asyncio.get_running_loop().create_future()
         self._enqueue_queue.append(
             _QueuedSubmission(
                 submission=submission,
@@ -69,7 +70,7 @@ class AgentRuntime:
         self._queue_event.set()
         await future
 
-    async def run_forever(self) -> None:
+    async def run_forever(self) -> 'None':
         while True:
             queued = await self._next_submission()
             submission = queued.submission
@@ -114,7 +115,7 @@ class AgentRuntime:
                 self._current_submission = None
 
     @staticmethod
-    def operation_name(op: Operation) -> str:
+    def operation_name(op: 'Operation') -> 'str':
         if isinstance(op, UserTurnOp):
             return "user_turn"
         if isinstance(op, ShutdownOp):
@@ -123,10 +124,10 @@ class AgentRuntime:
 
     async def _enqueue_user_turn_to_queue(
         self,
-        text: str,
-        future: asyncio.Future[TurnResult | None],
-        queue: Literal["enqueue", "steer"],
-    ) -> tuple[str, asyncio.Future[TurnResult | None]]:
+        text: 'str',
+        future: 'asyncio.Future[typing.Union[TurnResult, None]]',
+        queue: 'Literal["enqueue", "steer"]',
+    ) -> 'typing.Tuple[str, asyncio.Future[typing.Union[TurnResult, None]]]':
         if queue == "steer" and self._has_active_turn():
             self._agent_loop.interrupt_asap = True
 
@@ -154,10 +155,10 @@ class AgentRuntime:
             self._queue_event.set()
             return submission.id, future
 
-    async def _next_submission(self) -> _QueuedSubmission:
+    async def _next_submission(self) -> '_QueuedSubmission':
         while True:
             async with self._queue_lock:
-                queued: _QueuedSubmission | None = None
+                queued: 'typing.Union[_QueuedSubmission, None]' = None
                 if self._steer_queue:
                     queued = self._steer_queue.popleft()
                 elif self._enqueue_queue:
@@ -171,27 +172,27 @@ class AgentRuntime:
 
     @staticmethod
     def _finish_submission_result(
-        queued: _QueuedSubmission,
-        result: TurnResult | None,
-    ) -> None:
+        queued: '_QueuedSubmission',
+        result: 'typing.Union[TurnResult, None]',
+    ) -> 'None':
         for future in queued.futures:
             if not future.done():
                 future.set_result(result)
 
     @staticmethod
     def _finish_submission_exception(
-        queued: _QueuedSubmission,
-        exc: Exception,
-    ) -> None:
+        queued: '_QueuedSubmission',
+        exc: 'Exception',
+    ) -> 'None':
         for future in queued.futures:
             if not future.done():
                 future.set_exception(exc)
 
-    def _has_active_turn(self) -> bool:
+    def _has_active_turn(self) -> 'bool':
         current_task = self._current_task
         return current_task is not None and not current_task.done()
 
-    def _handle_agent_event(self, event: AgentEvent) -> None:
+    def _handle_agent_event(self, event: 'AgentEvent') -> 'None':
         queued = self._current_submission
         if queued is None:
             self._event_handler(event)