create-windy 0.2.20 → 0.2.22

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,
+    )

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

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import uuid
+
+from .contracts import AgentError, JsonValue, StartRunRequest
+from .engine import (
+    AgentEngineAdapter,
+    ApprovalRequired,
+    EngineCompleted,
+    EngineRunRequest,
+    OutputDelta,
+    SafeEngineError,
+    ToolCompleted,
+    ToolRequested,
+    UsageReported,
+)
+from .store import IdempotencyConflictError, RunRecord, RunStore
+
+
+class RunNotFoundError(Exception):
+    pass
+
+
+class OperationNotFoundError(Exception):
+    pass
+
+
+class AgentRunService:
+    def __init__(self, engine: AgentEngineAdapter, store: RunStore) -> None:
+        self.engine = engine
+        self.store = store
+        self._tasks: set[asyncio.Task[None]] = set()
+
+    async def start(
+        self,
+        request: StartRunRequest,
+        idempotency_key: str,
+    ) -> RunRecord:
+        if not self.engine.supports(request.operation_key):
+            raise OperationNotFoundError
+        fingerprint = request_fingerprint(request.operation_key, request.input)
+        candidate = RunRecord(
+            run_id=f"run_{uuid.uuid4().hex}",
+            operation_key=request.operation_key,
+            input=request.input,
+            idempotency_key=idempotency_key,
+            fingerprint=fingerprint,
+        )
+        record, created = await self.store.create_or_get(candidate)
+        if created:
+            task = asyncio.create_task(self._execute(record, request))
+            self._tasks.add(task)
+            task.add_done_callback(self._tasks.discard)
+        return record
+
+    async def get(self, run_id: str) -> RunRecord:
+        record = await self.store.get(run_id)
+        if record is None:
+            raise RunNotFoundError
+        return record
+
+    async def cancel(self, run_id: str) -> RunRecord:
+        record = await self.get(run_id)
+        if record.terminal:
+            return record
+        await self.engine.cancel(run_id)
+        await self.store.append(run_id, "run.cancelled")
+        return record
+
+    async def _execute(
+        self,
+        record: RunRecord,
+        invocation: StartRunRequest,
+    ) -> None:
+        await self.store.append(record.run_id, "run.started")
+        try:
+            request = EngineRunRequest(
+                run_id=record.run_id,
+                operation_key=record.operation_key,
+                input=record.input,
+                instructions=invocation.instructions,
+                user_prompt=invocation.user_prompt,
+                allowed_tools=tuple(invocation.allowed_tools),
+                limits=invocation.limits,
+                execution_grant=invocation.execution_grant,
+                tool_host_url=invocation.tool_host_url,
+            )
+            async with asyncio.timeout(invocation.limits.max_duration_seconds):
+                async for signal in self.engine.execute(request):
+                    if isinstance(signal, EngineCompleted):
+                        await self.store.complete(record.run_id, signal.output)
+                        return
+                    await self._append_signal(record.run_id, signal)
+            await self._fail(
+                record.run_id,
+                SafeEngineError(
+                    "STREAM_INTERRUPTED",
+                    "Agent Runtime 未返回终态",
+                    retryable=True,
+                ),
+            )
+        except SafeEngineError as error:
+            await self._fail(record.run_id, error)
+        except TimeoutError:
+            await self._fail(
+                record.run_id,
+                SafeEngineError(
+                    "RUN_TIMEOUT",
+                    "Agent Run 执行超时",
+                    retryable=True,
+                ),
+            )
+        except Exception:
+            await self._fail(
+                record.run_id,
+                SafeEngineError(
+                    "RUNTIME_UNAVAILABLE",
+                    "Agent Runtime 执行失败",
+                    retryable=True,
+                ),
+            )
+
+    async def _append_signal(self, run_id: str, signal: object) -> None:
+        if isinstance(signal, OutputDelta):
+            await self.store.append(run_id, "output.delta", {"text": signal.text})
+        elif isinstance(signal, ToolRequested):
+            await self.store.append(
+                run_id,
+                "tool.requested",
+                {"toolCallId": signal.tool_call_id, "toolKey": signal.tool_key},
+            )
+        elif isinstance(signal, ApprovalRequired):
+            await self.store.append(
+                run_id,
+                "approval.required",
+                {"workItemId": signal.work_item_id},
+            )
+        elif isinstance(signal, ToolCompleted):
+            await self.store.append(
+                run_id,
+                "tool.completed",
+                {"toolCallId": signal.tool_call_id},
+            )
+        elif isinstance(signal, UsageReported):
+            await self.store.append(
+                run_id,
+                "usage.reported",
+                {"usage": signal.usage},
+            )
+        else:
+            raise TypeError("unsupported engine signal")
+
+    async def _fail(self, run_id: str, failure: SafeEngineError) -> None:
+        error = AgentError(
+            code=failure.code,
+            message=failure.safe_message,
+            request_id=f"request_{uuid.uuid4().hex}",
+            retryable=failure.retryable,
+        )
+        await self.store.append(
+            run_id,
+            "run.failed",
+            {"error": error.model_dump(by_alias=True)},
+        )
+
+
+def request_fingerprint(operation_key: str, input_value: JsonValue) -> str:
+    encoded = json.dumps(
+        {"operationKey": operation_key, "input": input_value},
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+__all__ = ["AgentRunService", "IdempotencyConflictError"]