create-windy 0.2.19 → 0.2.21

package/template/apps/agent-server/src/southwind_agent_server/deterministic.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+from .engine import (
+    EngineCompleted,
+    EngineRunRequest,
+    EngineSignal,
+    OutputDelta,
+    UsageReported,
+)
+
+
+class DeterministicEngineAdapter:
+    """Deterministic test adapter. It never calls a model or remote service."""
+
+    operations = frozenset({"test.echo", "test.wait", "test.fail"})
+
+    def __init__(self) -> None:
+        self._cancellations: dict[str, asyncio.Event] = {}
+
+    def supports(self, operation_key: str) -> bool:
+        return operation_key in self.operations
+
+    async def execute(
+        self,
+        request: EngineRunRequest,
+    ) -> AsyncIterator[EngineSignal]:
+        cancellation = self._cancellations.setdefault(request.run_id, asyncio.Event())
+        try:
+            if request.operation_key == "test.fail":
+                raise RuntimeError("upstream-secret-body")
+            if request.operation_key == "test.wait":
+                await cancellation.wait()
+                return
+
+            text = "deterministic"
+            if isinstance(request.input, dict):
+                input_text = request.input.get("text")
+                if isinstance(input_text, str):
+                    text = input_text
+            yield OutputDelta(text)
+            yield UsageReported({"source": "unknown"})
+            yield EngineCompleted(request.input)
+        finally:
+            self._cancellations.pop(request.run_id, None)
+
+    async def cancel(self, run_id: str) -> None:
+        cancellation = self._cancellations.get(run_id)
+        if cancellation is not None:
+            cancellation.set()

package/template/apps/agent-server/src/southwind_agent_server/engine.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from .contracts import AgentErrorCode, JsonValue, RuntimeLimits, RuntimeToolDefinition
+
+
+@dataclass(frozen=True)
+class EngineRunRequest:
+    run_id: str
+    operation_key: str
+    input: JsonValue
+    instructions: str = ""
+    user_prompt: str = ""
+    allowed_tools: tuple[RuntimeToolDefinition, ...] = ()
+    limits: RuntimeLimits = field(default_factory=RuntimeLimits)
+    execution_grant: str = ""
+    tool_host_url: str = ""
+
+
+@dataclass(frozen=True)
+class OutputDelta:
+    text: str
+
+
+@dataclass(frozen=True)
+class ToolRequested:
+    tool_call_id: str
+    tool_key: str
+
+
+@dataclass(frozen=True)
+class ApprovalRequired:
+    work_item_id: str
+
+
+@dataclass(frozen=True)
+class ToolCompleted:
+    tool_call_id: str
+
+
+@dataclass(frozen=True)
+class UsageReported:
+    usage: dict[str, JsonValue]
+
+
+@dataclass(frozen=True)
+class EngineCompleted:
+    output: JsonValue
+
+
+type EngineSignal = (
+    OutputDelta
+    | ToolRequested
+    | ApprovalRequired
+    | ToolCompleted
+    | UsageReported
+    | EngineCompleted
+)
+
+
+class SafeEngineError(Exception):
+    def __init__(
+        self,
+        code: AgentErrorCode,
+        message: str,
+        *,
+        retryable: bool,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.safe_message = message
+        self.retryable = retryable
+
+
+class AgentEngineAdapter(Protocol):
+    """Internal engine seam. HTTP DTO and ADK types must not cross it."""
+
+    def supports(self, operation_key: str) -> bool: ...
+
+    def execute(self, request: EngineRunRequest) -> AsyncIterator[EngineSignal]: ...
+
+    async def cancel(self, run_id: str) -> None: ...

package/template/apps/agent-server/src/southwind_agent_server/openai_engine.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+
+from .contracts import JsonValue
+from .engine import (
+    AgentEngineAdapter,
+    EngineCompleted,
+    EngineRunRequest,
+    EngineSignal,
+    OutputDelta,
+    SafeEngineError,
+    ToolCompleted,
+    ToolRequested,
+    UsageReported,
+)
+from .openai_provider import OpenAiCompatibleProvider, ProviderToolCall
+from .tool_host import ToolHostClient, ToolInvocation
+
+
+class OpenAiCompatibleEngineAdapter(AgentEngineAdapter):
+    def __init__(
+        self,
+        provider: OpenAiCompatibleProvider,
+        tool_host: ToolHostClient,
+    ) -> None:
+        self._provider = provider
+        self._tool_host = tool_host
+        self._cancellations: dict[str, asyncio.Event] = {}
+
+    def supports(self, operation_key: str) -> bool:
+        return bool(operation_key.strip())
+
+    async def execute(
+        self,
+        request: EngineRunRequest,
+    ) -> AsyncIterator[EngineSignal]:
+        validate_runtime_request(request)
+        cancellation = self._cancellations.setdefault(
+            request.run_id,
+            asyncio.Event(),
+        )
+        allowed = {tool.key for tool in request.allowed_tools}
+        messages: list[dict[str, JsonValue]] = [
+            {"role": "system", "content": request.instructions},
+            {"role": "user", "content": request.user_prompt},
+        ]
+        output_bytes = 0
+        try:
+            for _round in range(self._provider.config.max_tool_rounds):
+                cancelled(cancellation)
+                turn = await self._provider.complete_turn(
+                    messages,
+                    request.allowed_tools,
+                )
+                if turn.tool_calls:
+                    messages.append(assistant_tool_message(turn.tool_calls))
+                    async for signal in self._execute_tools(
+                        request,
+                        turn.tool_calls,
+                        allowed,
+                        messages,
+                        cancellation,
+                    ):
+                        yield signal
+                    continue
+                for delta in turn.text_deltas:
+                    output_bytes += len(delta.encode())
+                    if output_bytes > request.limits.max_output_bytes:
+                        raise SafeEngineError(
+                            "BUDGET_EXCEEDED",
+                            "Agent 输出超过 Operation 上限",
+                            retryable=False,
+                        )
+                    yield OutputDelta(delta)
+                yield UsageReported(turn.usage or {"source": "unknown"})
+                yield EngineCompleted({"text": turn.text})
+                return
+            raise SafeEngineError(
+                "BUDGET_EXCEEDED",
+                "Agent Tool 调用轮次超过上限",
+                retryable=False,
+            )
+        finally:
+            self._cancellations.pop(request.run_id, None)
+
+    async def _execute_tools(
+        self,
+        request: EngineRunRequest,
+        calls: list[ProviderToolCall],
+        allowed: set[str],
+        messages: list[dict[str, JsonValue]],
+        cancellation: asyncio.Event,
+    ) -> AsyncIterator[EngineSignal]:
+        for call in calls:
+            cancelled(cancellation)
+            if not call.call_id or not call.name or call.name not in allowed:
+                raise SafeEngineError(
+                    "TOOL_DENIED",
+                    "模型请求了未授权 Tool",
+                    retryable=False,
+                )
+            arguments = parse_arguments(call.arguments)
+            yield ToolRequested(call.call_id, call.name)
+            result = await self._tool_host.execute(
+                request.tool_host_url,
+                ToolInvocation(
+                    request.run_id,
+                    call.call_id,
+                    call.name,
+                    arguments,
+                    request.execution_grant,
+                ),
+            )
+            yield ToolCompleted(call.call_id)
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": call.call_id,
+                    "content": json.dumps(
+                        result,
+                        ensure_ascii=False,
+                        separators=(",", ":"),
+                    ),
+                }
+            )
+
+    async def cancel(self, run_id: str) -> None:
+        event = self._cancellations.get(run_id)
+        if event is not None:
+            event.set()
+
+    async def health(self) -> None:
+        await self._provider.health()
+
+
+def validate_runtime_request(request: EngineRunRequest) -> None:
+    if (
+        not request.instructions.strip()
+        or not request.user_prompt.strip()
+        or not request.execution_grant.strip()
+        or not request.tool_host_url.strip()
+    ):
+        raise SafeEngineError(
+            "INVALID_INPUT",
+            "Agent Operation 运行计划不完整",
+            retryable=False,
+        )
+
+
+def cancelled(event: asyncio.Event) -> None:
+    if event.is_set():
+        raise SafeEngineError(
+            "RUN_CANCELLED",
+            "Agent Run 已取消",
+            retryable=False,
+        )
+
+
+def parse_arguments(raw: str) -> dict[str, JsonValue]:
+    try:
+        value = json.loads(raw or "{}")
+    except json.JSONDecodeError:
+        raise SafeEngineError(
+            "TOOL_DENIED",
+            "Agent Tool 参数无效",
+            retryable=False,
+        ) from None
+    if not isinstance(value, dict):
+        raise SafeEngineError(
+            "TOOL_DENIED",
+            "Agent Tool 参数必须是对象",
+            retryable=False,
+        )
+    return value
+
+
+def assistant_tool_message(
+    calls: list[ProviderToolCall],
+) -> dict[str, JsonValue]:
+    return {
+        "role": "assistant",
+        "content": None,
+        "tool_calls": [
+            {
+                "id": call.call_id,
+                "type": "function",
+                "function": {
+                    "name": call.name,
+                    "arguments": call.arguments,
+                },
+            }
+            for call in calls
+        ],
+    }

package/template/apps/agent-server/src/southwind_agent_server/openai_provider.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import cast
+
+import httpx
+
+from .config import (
+    EnvironmentSecretResolver,
+    OpenAiCompatibleConfig,
+)
+from .contracts import AgentErrorCode, JsonValue, RuntimeToolDefinition
+from .engine import SafeEngineError
+
+
+@dataclass
+class ProviderToolCall:
+    call_id: str = ""
+    name: str = ""
+    arguments: str = ""
+
+
+@dataclass
+class ProviderTurn:
+    text_deltas: list[str] = field(default_factory=list)
+    tool_calls: list[ProviderToolCall] = field(default_factory=list)
+    usage: dict[str, JsonValue] | None = None
+
+    @property
+    def text(self) -> str:
+        return "".join(self.text_deltas)
+
+
+class OpenAiCompatibleProvider:
+    def __init__(
+        self,
+        config: OpenAiCompatibleConfig,
+        resolver: EnvironmentSecretResolver,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.config = config
+        self._resolver = resolver
+        self._transport = transport
+
+    async def health(self) -> None:
+        async with self._client() as client:
+            try:
+                response = await client.get("/models")
+                await self._bounded_body(response)
+            except httpx.HTTPError as error:
+                raise provider_failure(error) from None
+        if not response.is_success:
+            raise provider_status_failure(response.status_code)
+
+    async def complete_turn(
+        self,
+        messages: list[dict[str, JsonValue]],
+        tools: tuple[RuntimeToolDefinition, ...],
+    ) -> ProviderTurn:
+        payload: dict[str, JsonValue] = {
+            "model": self.config.model,
+            "messages": cast(JsonValue, messages),
+            "stream": True,
+            "stream_options": {"include_usage": True},
+        }
+        if tools:
+            payload["tools"] = [tool_schema(tool) for tool in tools]
+        turn = ProviderTurn()
+        async with self._client() as client:
+            try:
+                async with client.stream(
+                    "POST",
+                    "/chat/completions",
+                    json=payload,
+                ) as response:
+                    if not response.is_success:
+                        await self._bounded_stream(response)
+                        raise provider_status_failure(response.status_code)
+                    await self._consume_stream(response, turn)
+            except SafeEngineError:
+                raise
+            except httpx.HTTPError as error:
+                raise provider_failure(error) from None
+        return turn
+
+    def _client(self) -> httpx.AsyncClient:
+        api_key = (
+            self._resolver.resolve(self.config.api_key_ref)
+            if self.config.api_key_ref
+            else None
+        )
+        headers = {"accept": "text/event-stream"}
+        if api_key:
+            headers["authorization"] = f"Bearer {api_key}"
+        timeout = httpx.Timeout(
+            self.config.request_timeout_seconds,
+            connect=self.config.connect_timeout_seconds,
+        )
+        return httpx.AsyncClient(
+            base_url=f"{self.config.base_url}/",
+            headers=headers,
+            timeout=timeout,
+            transport=self._transport,
+        )
+
+    async def _consume_stream(
+        self,
+        response: httpx.Response,
+        turn: ProviderTurn,
+    ) -> None:
+        consumed = 0
+        async for line in response.aiter_lines():
+            consumed += len(line.encode()) + 1
+            if consumed > self.config.max_response_bytes:
+                raise SafeEngineError(
+                    "PROVIDER_UNAVAILABLE",
+                    "模型响应超过安全上限",
+                    retryable=False,
+                )
+            if not line.startswith("data:"):
+                continue
+            data = line.removeprefix("data:").strip()
+            if not data or data == "[DONE]":
+                continue
+            try:
+                chunk = json.loads(data)
+                consume_chunk(chunk, turn)
+            except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+                raise SafeEngineError(
+                    "PROVIDER_UNAVAILABLE",
+                    "模型返回协议无效",
+                    retryable=True,
+                ) from None
+
+    async def _bounded_stream(self, response: httpx.Response) -> bytes:
+        body = bytearray()
+        async for chunk in response.aiter_bytes():
+            body.extend(chunk)
+            if len(body) > self.config.max_response_bytes:
+                break
+        return bytes(body)
+
+    async def _bounded_body(self, response: httpx.Response) -> bytes:
+        body = await response.aread()
+        if len(body) > self.config.max_response_bytes:
+            raise SafeEngineError(
+                "PROVIDER_UNAVAILABLE",
+                "模型响应超过安全上限",
+                retryable=False,
+            )
+        return body
+
+
+def consume_chunk(value: object, turn: ProviderTurn) -> None:
+    if not isinstance(value, dict):
+        raise TypeError
+    usage = value.get("usage")
+    if isinstance(usage, dict):
+        turn.usage = usage_value(usage)
+    choices = value.get("choices")
+    if not isinstance(choices, list) or not choices:
+        return
+    choice = choices[0]
+    if not isinstance(choice, dict):
+        raise TypeError
+    delta = choice.get("delta")
+    if not isinstance(delta, dict):
+        return
+    content = delta.get("content")
+    if isinstance(content, str) and content:
+        turn.text_deltas.append(content)
+    raw_calls = delta.get("tool_calls")
+    if not isinstance(raw_calls, list):
+        return
+    for raw in raw_calls:
+        if not isinstance(raw, dict):
+            raise TypeError
+        index = raw.get("index")
+        if not isinstance(index, int) or index < 0:
+            raise TypeError
+        while len(turn.tool_calls) <= index:
+            turn.tool_calls.append(ProviderToolCall())
+        call = turn.tool_calls[index]
+        call_id = raw.get("id")
+        if isinstance(call_id, str):
+            call.call_id += call_id
+        function = raw.get("function")
+        if isinstance(function, dict):
+            name = function.get("name")
+            arguments = function.get("arguments")
+            if isinstance(name, str):
+                call.name += name
+            if isinstance(arguments, str):
+                call.arguments += arguments
+
+
+def tool_schema(tool: RuntimeToolDefinition) -> JsonValue:
+    return {
+        "type": "function",
+        "function": {
+            "name": tool.key,
+            "description": tool.description,
+            "parameters": {
+                "type": "object",
+                "additionalProperties": True,
+            },
+        },
+    }
+
+
+def usage_value(raw: dict[object, object]) -> dict[str, JsonValue]:
+    values = {
+        "inputTokens": raw.get("prompt_tokens"),
+        "outputTokens": raw.get("completion_tokens"),
+        "totalTokens": raw.get("total_tokens"),
+    }
+    measurements = {
+        key: value
+        for key, value in values.items()
+        if isinstance(value, int) and value >= 0
+    }
+    return (
+        {"source": "provider-reported", **measurements}
+        if measurements
+        else {"source": "unknown"}
+    )
+
+
+def provider_failure(error: httpx.HTTPError) -> SafeEngineError:
+    del error
+    return SafeEngineError(
+        "PROVIDER_UNAVAILABLE",
+        "模型服务暂不可用",
+        retryable=True,
+    )
+
+
+def provider_status_failure(status: int) -> SafeEngineError:
+    code: AgentErrorCode = "RATE_LIMITED" if status == 429 else "PROVIDER_UNAVAILABLE"
+    return SafeEngineError(
+        code,
+        "模型服务限流" if status == 429 else "模型服务暂不可用",
+        retryable=status == 429 or status >= 500,
+    )