create-windy 0.6.12 → 0.6.14

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

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import cast
+
+from .context_message_digest import (
+    bytes_digest,
+    canonical_json_digest,
+    message_content_digest,
+)
+from .context_version_port import PreparedContext, context_unavailable
+from .contracts import JsonValue
+from .engine import PreparedArtifact
+
+
+@dataclass(frozen=True)
+class AttemptContextPreparation:
+    context: PreparedContext
+    messages: list[dict[str, JsonValue]]
+    insertion_start: int
+
+
+def governed_envelope(
+    preparation: AttemptContextPreparation,
+    run_id: str,
+    model_attempt_id: str,
+    messages: list[dict[str, JsonValue]],
+    provider_request: bytes,
+    deployment_key: str,
+    model: str,
+    prompt_version: str,
+    artifacts: tuple[PreparedArtifact, ...],
+) -> dict[str, JsonValue]:
+    payload = _provider_payload(provider_request, messages, model)
+    source_start = preparation.insertion_start
+    source_end = source_start + len(preparation.context.sources)
+    message_entries: list[JsonValue] = []
+    for ordinal, message in enumerate(messages):
+        recovery_content = _recovery_content(message, artifacts)
+        message_entries.append(
+            {
+                "ordinal": ordinal,
+                "role": cast(str, message.get("role")),
+                "content": recovery_content,
+                # digest covers actual governed Provider content; recoveryDigest
+                # covers the encrypted, ArtifactRef-only recovery projection.
+                "digest": _message_digest(message),
+                "recoveryDigest": message_content_digest(
+                    cast(str, message.get("role")), recovery_content
+                ),
+                "origins": _message_origins(
+                    preparation,
+                    run_id,
+                    model_attempt_id,
+                    prompt_version,
+                    artifacts,
+                    ordinal,
+                    message,
+                    source_start,
+                    source_end,
+                ),
+            }
+        )
+    return {
+        "provider": {
+            "deploymentKey": deployment_key,
+            "model": model,
+            "requestDigest": bytes_digest(provider_request),
+            "toolsDigest": canonical_json_digest(payload.get("tools")),
+            "outputSchemaDigest": canonical_json_digest(payload.get("response_format")),
+        },
+        "messages": message_entries,
+    }
+
+
+def _message_origins(
+    preparation: AttemptContextPreparation,
+    run_id: str,
+    model_attempt_id: str,
+    prompt_version: str,
+    artifacts: tuple[PreparedArtifact, ...],
+    ordinal: int,
+    message: dict[str, JsonValue],
+    source_start: int,
+    source_end: int,
+) -> list[JsonValue]:
+    if source_start <= ordinal < source_end:
+        source = preparation.context.sources[ordinal - source_start]
+        return [
+            {
+                "type": "context-source",
+                "sourceId": source.id,
+                "sourceVersion": source.version,
+                "digest": source.digest,
+                "source": source.reference(),
+            }
+        ]
+    role = message.get("role")
+    digest = _message_digest(message)
+    if ordinal == 0 and role == "system":
+        return [
+            {
+                "type": "instructions",
+                "sourceId": f"{run_id}:instructions",
+                "sourceVersion": prompt_version,
+                "digest": digest,
+            }
+        ]
+    if role == "user":
+        origins: list[JsonValue] = [
+            {
+                "type": "user-prompt",
+                "sourceId": f"{run_id}:user-prompt",
+                "sourceVersion": run_id,
+                "digest": digest,
+            }
+        ]
+        for artifact in artifacts:
+            origins.append(
+                {
+                    "type": "artifact",
+                    "sourceId": artifact.sha256,
+                    "sourceVersion": artifact.sha256,
+                    "digest": artifact.sha256,
+                }
+            )
+        return origins
+    if role == "assistant":
+        return [
+            {
+                "type": "provider-output",
+                "sourceId": f"{run_id}:message:{ordinal}",
+                "sourceVersion": model_attempt_id,
+                "digest": digest,
+            }
+        ]
+    if role == "tool" and isinstance(message.get("tool_call_id"), str):
+        return [
+            {
+                "type": "tool-receipt",
+                "sourceId": message["tool_call_id"],
+                "sourceVersion": model_attempt_id,
+                "digest": digest,
+            }
+        ]
+    raise context_unavailable()
+
+
+def _recovery_content(
+    message: dict[str, JsonValue],
+    artifacts: tuple[PreparedArtifact, ...],
+) -> JsonValue:
+    content = message.get("content")
+    if not isinstance(content, list):
+        return content
+    known = {artifact.data_url: artifact for artifact in artifacts}
+    projected: list[JsonValue] = []
+    for part in content:
+        if not isinstance(part, dict):
+            raise context_unavailable()
+        if part.get("type") == "text" and isinstance(part.get("text"), str):
+            projected.append(part)
+            continue
+        image = part.get("image_url")
+        url = image.get("url") if isinstance(image, dict) else None
+        artifact = known.get(url) if isinstance(url, str) else None
+        if part.get("type") != "image_url" or artifact is None:
+            raise context_unavailable()
+        projected.append(
+            {
+                "type": "artifact_ref",
+                "sha256": artifact.sha256,
+                "mediaType": artifact.media_type,
+                "byteSize": artifact.byte_size,
+            }
+        )
+    return projected
+
+
+def _provider_payload(
+    raw: bytes,
+    messages: list[dict[str, JsonValue]],
+    model: str,
+) -> dict[str, JsonValue]:
+    try:
+        value = json.loads(raw)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        raise context_unavailable() from None
+    if (
+        not isinstance(value, dict)
+        or value.get("messages") != messages
+        or value.get("model") != model
+    ):
+        raise context_unavailable()
+    return cast(dict[str, JsonValue], value)
+
+
+def _message_digest(message: dict[str, JsonValue]) -> str:
+    role = message.get("role")
+    if role not in {"system", "user", "assistant", "tool"} or "content" not in message:
+        raise context_unavailable()
+    return canonical_json_digest(cast(JsonValue, message))

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

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import Field, model_validator
+
+from .contracts import CanonicalModel, JsonValue, ProviderDataPolicy
+
+
+class NamedFunction(CanonicalModel):
+    name: str = Field(pattern=r"^[A-Za-z0-9_-]{1,64}$")
+
+
+class NamedToolChoice(CanonicalModel):
+    type: Literal["function"]
+    function: NamedFunction
+
+
+class ClientCompletionRequest(CanonicalModel):
+    client_run_id: str = Field(min_length=1, max_length=80)
+    operation_key: str = Field(min_length=1, max_length=200)
+    deployment_key: str = Field(min_length=1, max_length=200)
+    model_alias: str = Field(pattern=r"^[A-Za-z0-9._-]{1,80}$")
+    attempt: int = Field(ge=1, le=128)
+    messages: list[dict[str, JsonValue]] = Field(min_length=1, max_length=128)
+    tools: list[dict[str, JsonValue]] = Field(default_factory=list, max_length=64)
+    tool_choice: Literal["auto", "none"] | NamedToolChoice | None = None
+    parallel_tool_calls: Literal[False] = False
+    provider_data_policy: ProviderDataPolicy
+    max_response_bytes: int = Field(ge=1_024, le=16_777_216)
+
+    @model_validator(mode="after")
+    def validate_openai_envelope(self) -> Self:
+        for message in self.messages:
+            if message.get("role") not in {"system", "user", "assistant", "tool"}:
+                raise ValueError("消息角色无效")
+            content = message.get("content")
+            if content is not None and not isinstance(content, str):
+                raise ValueError("消息 content 无效")
+        names: set[str] = set()
+        for tool in self.tools:
+            function = tool.get("function")
+            if tool.get("type") != "function" or not isinstance(function, dict):
+                raise ValueError("Tool 定义无效")
+            name = function.get("name")
+            parameters = function.get("parameters")
+            if (
+                not isinstance(name, str)
+                or not name
+                or name in names
+                or not isinstance(parameters, dict)
+                or parameters.get("type") != "object"
+            ):
+                raise ValueError("Tool Function 定义无效")
+            names.add(name)
+        if (
+            isinstance(self.tool_choice, NamedToolChoice)
+            and self.tool_choice.function.name not in names
+        ):
+            raise ValueError("命名 Tool Choice 不存在")
+        return self

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

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import json
+from typing import cast
+
+from .contracts import JsonValue, ProviderDataPolicy
+from .engine import SafeEngineError
+from .provider_governance import (
+    GovernanceDenied,
+    ProviderRequestGovernance,
+    field_for_message,
+    govern_message,
+    govern_value,
+)
+
+
+def govern_client_completion(
+    governance: ProviderRequestGovernance,
+    *,
+    deployment_key: str,
+    operation_key: str,
+    run_id: str,
+    attempt: int,
+    messages: list[dict[str, JsonValue]],
+    tools: list[dict[str, JsonValue]],
+    policy: ProviderDataPolicy,
+) -> tuple[list[dict[str, JsonValue]], list[dict[str, JsonValue]]]:
+    rules = {rule.field: rule for rule in policy.envelope_fields}
+    classified: set[str] = set()
+    redacted = False
+    try:
+        governed_messages: list[dict[str, JsonValue]] = []
+        for message in messages:
+            field = field_for_message(message)
+            rule = rules.get(field)
+            if rule is None:
+                raise GovernanceDenied(f"Provider 未授权发送字段：{field}")
+            classified.add(rule.classification)
+            value, changed = govern_message(message, rule.dlp_action)
+            redacted = redacted or changed
+            governed_messages.append(cast(dict[str, JsonValue], value))
+        governed_tools = tools
+        if tools:
+            rule = rules.get("tool-definitions")
+            if rule is None:
+                raise GovernanceDenied("Provider 未授权发送字段：tool-definitions")
+            classified.add(rule.classification)
+            value, changed = govern_value(tools, rule.dlp_action)
+            redacted = redacted or changed
+            governed_tools = cast(list[dict[str, JsonValue]], value)
+        sent_bytes = len(
+            json.dumps(
+                {"messages": governed_messages, "tools": governed_tools},
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ).encode()
+        )
+        governance.record_client(
+            deployment_key=deployment_key,
+            operation_key=operation_key,
+            run_id=run_id,
+            attempt=attempt,
+            classified=classified,
+            sent_bytes=sent_bytes,
+            decision="redact" if redacted else "allow",
+        )
+        return governed_messages, governed_tools
+    except GovernanceDenied:
+        governance.record_client(
+            deployment_key=deployment_key,
+            operation_key=operation_key,
+            run_id=run_id,
+            attempt=attempt,
+            classified=classified,
+            sent_bytes=0,
+            decision="reject",
+        )
+        raise SafeEngineError(
+            "FORBIDDEN",
+            "Provider 请求被字段治理策略拒绝",
+            retryable=False,
+        ) from None

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

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Callable
+from typing import TYPE_CHECKING, Annotated, cast
+
+from fastapi import FastAPI, Header, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+
+from .client_completion_contracts import ClientCompletionRequest
+from .client_completion_runtime import ClientCompletionRuntime
+from .engine import AgentEngineAdapter, SafeEngineError
+from .http_helpers import authorized, safe_error
+
+if TYPE_CHECKING:
+    from .client_completion_runtime import PreparedClientCompletion
+
+
+def install_client_completion_routes(
+    application: FastAPI,
+    engine: AgentEngineAdapter,
+    internal_token: str | None,
+) -> None:
+    @application.get("/api/internal/client-agent/health", response_model=None)
+    async def client_completion_health(
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> dict[str, str] | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        factory = runtime_factory(engine)
+        if factory is None:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Client Agent Provider 尚未配置",
+                True,
+            )
+        try:
+            factory().deployment_digest()
+        except SafeEngineError as error:
+            return safe_error(503, error.code, error.safe_message, error.retryable)
+        return {"status": "ready"}
+
+    @application.post(
+        "/api/internal/client-agent/chat/completions",
+        response_model=None,
+    )
+    async def client_completion(
+        body: ClientCompletionRequest,
+        request: Request,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> StreamingResponse | JSONResponse:
+        if not authorized(authorization, internal_token):
+            return safe_error(403, "FORBIDDEN", "内部调用认证失败", False)
+        factory = runtime_factory(engine)
+        if factory is None:
+            return safe_error(
+                503,
+                "RUNTIME_UNAVAILABLE",
+                "Client Agent Provider 尚未配置",
+                True,
+            )
+        try:
+            runtime = factory()
+            prepared = runtime.prepare(body)
+        except SafeEngineError as error:
+            return safe_error(
+                403 if error.code == "FORBIDDEN" else 503,
+                error.code,
+                error.safe_message,
+                error.retryable,
+            )
+        return StreamingResponse(
+            completion_events(runtime, prepared, request),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-store, no-transform",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+
+async def completion_events(
+    runtime: ClientCompletionRuntime,
+    prepared: object,
+    request: Request,
+) -> AsyncIterator[str]:
+    typed = cast("PreparedClientCompletion", prepared)
+    yield event(
+        "windy.meta",
+        {"deploymentDigest": typed.deployment_digest},
+    )
+    try:
+        async for chunk in runtime.stream(typed):
+            if await request.is_disconnected():
+                return
+            yield event(None, chunk)
+        yield "data: [DONE]\n\n"
+    except SafeEngineError as error:
+        yield event(
+            "windy.error",
+            {
+                "code": error.code,
+                "message": error.safe_message,
+                "retryable": error.retryable,
+            },
+        )
+
+
+def event(name: str | None, value: object) -> str:
+    prefix = f"event: {name}\n" if name else ""
+    return f"{prefix}data: {json.dumps(value, ensure_ascii=False)}\n\n"
+
+
+def runtime_factory(
+    engine: AgentEngineAdapter,
+) -> Callable[[], ClientCompletionRuntime] | None:
+    return cast(
+        Callable[[], ClientCompletionRuntime] | None,
+        getattr(engine, "client_completion_runtime", None),
+    )

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

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from typing import cast
+
+import httpx
+
+from .client_completion_contracts import ClientCompletionRequest, NamedToolChoice
+from .client_completion_governance import govern_client_completion
+from .contracts import JsonValue
+from .engine import SafeEngineError
+from .openai_provider import OpenAiCompatibleProvider, ProviderTurn, consume_chunk
+from .provider_governance import ProviderRequestGovernance
+
+
+@dataclass(frozen=True)
+class PreparedClientCompletion:
+    deployment_digest: str
+    model_alias: str
+    body: bytes
+    max_response_bytes: int
+
+
+class ClientCompletionRuntime:
+    def __init__(
+        self,
+        provider: OpenAiCompatibleProvider,
+        governance: ProviderRequestGovernance,
+    ) -> None:
+        self._provider = provider
+        self._governance = governance
+
+    def prepare(self, request: ClientCompletionRequest) -> PreparedClientCompletion:
+        config = self._provider.config
+        if request.deployment_key != config.deployment_key:
+            raise SafeEngineError(
+                "MODEL_ROUTE_UNAVAILABLE",
+                "Client Agent Deployment 不可用",
+                retryable=False,
+            )
+        governed_messages, governed_tools = govern_client_completion(
+            self._governance,
+            deployment_key=config.deployment_key,
+            operation_key=request.operation_key,
+            run_id=request.client_run_id,
+            attempt=request.attempt,
+            messages=request.messages,
+            tools=request.tools,
+            policy=request.provider_data_policy,
+        )
+        payload: dict[str, JsonValue] = {
+            "model": config.model,
+            "messages": cast(JsonValue, governed_messages),
+            "stream": True,
+            "stream_options": {"include_usage": True},
+            "parallel_tool_calls": False,
+        }
+        if governed_tools:
+            payload["tools"] = cast(JsonValue, governed_tools)
+        if request.tool_choice is not None:
+            payload["tool_choice"] = cast(
+                JsonValue,
+                request.tool_choice.model_dump(by_alias=True)
+                if isinstance(request.tool_choice, NamedToolChoice)
+                else request.tool_choice,
+            )
+        body = json.dumps(
+            payload,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        ).encode()
+        return PreparedClientCompletion(
+            deployment_digest=self.deployment_digest(),
+            model_alias=request.model_alias,
+            body=body,
+            max_response_bytes=min(
+                request.max_response_bytes,
+                config.max_response_bytes,
+            ),
+        )
+
+    async def stream(
+        self,
+        prepared: PreparedClientCompletion,
+    ) -> AsyncGenerator[dict[str, JsonValue]]:
+        consumed = 0
+        turn = ProviderTurn()
+        async with self._provider._client() as client:
+            try:
+                async with client.stream(
+                    "POST",
+                    "/chat/completions",
+                    content=prepared.body,
+                    headers={"content-type": "application/json"},
+                ) as response:
+                    if not response.is_success:
+                        await self._provider._bounded_stream(response)
+                        raise SafeEngineError(
+                            "RATE_LIMITED"
+                            if response.status_code == 429
+                            else "PROVIDER_UNAVAILABLE",
+                            "模型服务限流"
+                            if response.status_code == 429
+                            else "模型服务暂不可用",
+                            retryable=response.status_code == 429
+                            or response.status_code >= 500,
+                        )
+                    async for line in response.aiter_lines():
+                        consumed += len(line.encode()) + 1
+                        if consumed > prepared.max_response_bytes:
+                            raise SafeEngineError(
+                                "BUDGET_EXCEEDED",
+                                "模型响应超过会话上限",
+                                retryable=False,
+                            )
+                        if not line.startswith("data:"):
+                            continue
+                        data = line.removeprefix("data:").strip()
+                        if not data or data == "[DONE]":
+                            continue
+                        chunk = json.loads(data)
+                        consume_chunk(chunk, turn)
+                        if not isinstance(chunk, dict):
+                            raise TypeError
+                        normalized = cast(dict[str, JsonValue], chunk)
+                        normalized["model"] = prepared.model_alias
+                        yield normalized
+            except SafeEngineError:
+                raise
+            except httpx.HTTPError:
+                raise SafeEngineError(
+                    "PROVIDER_UNAVAILABLE",
+                    "模型服务暂不可用",
+                    retryable=True,
+                ) from None
+            except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+                raise SafeEngineError(
+                    "PROVIDER_UNAVAILABLE",
+                    "模型返回协议无效",
+                    retryable=True,
+                ) from None
+
+    def deployment_digest(self) -> str:
+        config = self._provider.config
+        canonical = json.dumps(
+            {
+                "deploymentKey": config.deployment_key,
+                "model": config.model,
+                "deploymentIdentity": config.readiness_deployment_identity,
+                "releaseDigest": config.readiness_release_digest,
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+        return f"sha256:{hashlib.sha256(canonical).hexdigest()}"

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

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import hashlib
+import json
+
+from .contracts import JsonValue
+
+
+def bytes_digest(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def canonical_json_digest(value: JsonValue) -> str:
+    encoded = json.dumps(
+        value,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode()
+    return bytes_digest(encoded)
+
+
+def message_content_digest(role: str, content: JsonValue) -> str:
+    return canonical_json_digest({"role": role, "content": content})