create-windy 0.2.34 → 0.3.1

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

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncGenerator
+
+from google.adk.models.base_llm import BaseLlm
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.genai import types
+from pydantic import PrivateAttr
+
+from .adk_failure import AdkFailureState
+from .contracts import JsonValue
+from .engine import EngineRunRequest, SafeEngineError
+from .openai_engine import cancelled, parse_arguments
+from .openai_provider import OpenAiCompatibleProvider, ProviderTurn
+from .provider_governance import ProviderRequestGovernance
+
+
+class GovernedOpenAiLlm(BaseLlm):
+    """ADK model bridge that preserves Southwind's provider governance."""
+
+    _request: EngineRunRequest = PrivateAttr()
+    _provider: OpenAiCompatibleProvider = PrivateAttr()
+    _governance: ProviderRequestGovernance = PrivateAttr()
+    _cancellation: asyncio.Event = PrivateAttr()
+    _failures: AdkFailureState = PrivateAttr()
+    _attempt: int = PrivateAttr(default=0)
+
+    def __init__(
+        self,
+        request: EngineRunRequest,
+        provider: OpenAiCompatibleProvider,
+        governance: ProviderRequestGovernance,
+        cancellation: asyncio.Event,
+        failures: AdkFailureState,
+    ) -> None:
+        super().__init__(model=provider.config.model)
+        self._request = request
+        self._provider = provider
+        self._governance = governance
+        self._cancellation = cancellation
+        self._failures = failures
+
+    async def generate_content_async(
+        self,
+        llm_request: LlmRequest,
+        stream: bool = False,
+    ) -> AsyncGenerator[LlmResponse, None]:
+        del stream
+        try:
+            cancelled(self._cancellation)
+            self._attempt += 1
+            if self._attempt > self._provider.config.max_tool_rounds:
+                raise SafeEngineError(
+                    "BUDGET_EXCEEDED",
+                    "Agent Tool 调用轮次超过上限",
+                    retryable=False,
+                )
+            messages = adk_messages(llm_request, self._request.instructions)
+            governed = self._governance.authorize(
+                deployment_key=self._provider.config.deployment_key,
+                operation_key=self._request.operation_key,
+                run_id=self._request.run_id,
+                attempt=self._attempt,
+                messages=messages,
+                tools=self._request.allowed_tools,
+                policy=self._request.provider_data_policy,
+                input_value=self._request.input,
+                measure=lambda values, tools: len(
+                    self._provider.request_body(values, tools)
+                ),
+            )
+            turn = await self._provider.complete_turn(
+                governed.messages,
+                governed.tools,
+            )
+            cancelled(self._cancellation)
+            validate_tool_calls(
+                turn,
+                {tool.key for tool in self._request.allowed_tools},
+            )
+            async for response in responses_for_turn(turn):
+                yield response
+        except SafeEngineError as error:
+            self._failures.capture(error)
+            raise
+
+
+def adk_messages(
+    request: LlmRequest,
+    instructions: str,
+) -> list[dict[str, JsonValue]]:
+    result: list[dict[str, JsonValue]] = [{"role": "system", "content": instructions}]
+    for content in request.contents:
+        parts = content.parts or []
+        calls = [part.function_call for part in parts if part.function_call]
+        responses = [part.function_response for part in parts if part.function_response]
+        text = "".join(
+            part.text or "" for part in parts if not part.thought and part.text
+        )
+        if calls:
+            result.append(
+                {
+                    "role": "assistant",
+                    "content": text or None,
+                    "tool_calls": [
+                        {
+                            "id": call.id or "",
+                            "type": "function",
+                            "function": {
+                                "name": call.name or "",
+                                "arguments": json.dumps(
+                                    call.args or {},
+                                    ensure_ascii=False,
+                                    separators=(",", ":"),
+                                ),
+                            },
+                        }
+                        for call in calls
+                    ],
+                }
+            )
+        elif responses:
+            result.extend(tool_response_messages(responses))
+        elif text:
+            result.append(
+                {
+                    "role": "assistant" if content.role == "model" else "user",
+                    "content": text,
+                }
+            )
+    return result
+
+
+def tool_response_messages(
+    responses: list[types.FunctionResponse],
+) -> list[dict[str, JsonValue]]:
+    return [
+        {
+            "role": "tool",
+            "tool_call_id": response.id or "",
+            "content": json.dumps(
+                response.response or {},
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ),
+        }
+        for response in responses
+    ]
+
+
+def validate_tool_calls(turn: ProviderTurn, allowed: set[str]) -> None:
+    for call in turn.tool_calls:
+        if not call.call_id or not call.name or call.name not in allowed:
+            raise SafeEngineError(
+                "TOOL_DENIED",
+                "模型请求了未授权 Tool",
+                retryable=False,
+            )
+        parse_arguments(call.arguments)
+
+
+async def responses_for_turn(
+    turn: ProviderTurn,
+) -> AsyncGenerator[LlmResponse, None]:
+    usage = turn.usage or {"source": "unknown"}
+    metadata = {"southwindUsage": usage}
+    if turn.tool_calls:
+        yield LlmResponse(
+            content=types.Content(
+                role="model",
+                parts=[
+                    types.Part(
+                        function_call=types.FunctionCall(
+                            id=call.call_id,
+                            name=call.name,
+                            args=parse_arguments(call.arguments),
+                        )
+                    )
+                    for call in turn.tool_calls
+                ],
+            ),
+            partial=False,
+            custom_metadata=metadata,
+            usage_metadata=adk_usage(usage),
+        )
+        return
+    for delta in turn.text_deltas:
+        yield LlmResponse(
+            content=types.Content(
+                role="model",
+                parts=[types.Part(text=delta)],
+            ),
+            partial=True,
+        )
+    yield LlmResponse(
+        content=types.Content(
+            role="model",
+            parts=[types.Part(text=turn.text)],
+        ),
+        partial=False,
+        custom_metadata=metadata,
+        usage_metadata=adk_usage(usage),
+    )
+
+
+def adk_usage(
+    usage: dict[str, JsonValue],
+) -> types.GenerateContentResponseUsageMetadata | None:
+    input_tokens = usage.get("inputTokens")
+    output_tokens = usage.get("outputTokens")
+    total_tokens = usage.get("totalTokens")
+    if not any(
+        isinstance(value, int) for value in (input_tokens, output_tokens, total_tokens)
+    ):
+        return None
+    return types.GenerateContentResponseUsageMetadata(
+        prompt_token_count=input_tokens if isinstance(input_tokens, int) else None,
+        candidates_token_count=(
+            output_tokens if isinstance(output_tokens, int) else None
+        ),
+        total_token_count=total_tokens if isinstance(total_tokens, int) else None,
+    )

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

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, cast
+
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+
+from .adk_failure import AdkFailureState
+from .contracts import JsonValue, RuntimeToolDefinition
+from .engine import EngineRunRequest, SafeEngineError
+from .openai_engine import cancelled
+from .tool_host import ToolHostClient, ToolInvocation
+
+
+class GovernedTool(BaseTool):
+    """ADK declaration whose only execution path is the governed Tool Host."""
+
+    def __init__(
+        self,
+        definition: RuntimeToolDefinition,
+        request: EngineRunRequest,
+        tool_host: ToolHostClient,
+        cancellation: asyncio.Event,
+        failures: AdkFailureState,
+    ) -> None:
+        super().__init__(
+            name=definition.key,
+            description=definition.description,
+        )
+        self._request = request
+        self._tool_host = tool_host
+        self._cancellation = cancellation
+        self._failures = failures
+
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters_json_schema={
+                "type": "object",
+                "additionalProperties": True,
+            },
+        )
+
+    async def run_async(
+        self,
+        *,
+        args: dict[str, Any],
+        tool_context: ToolContext,
+    ) -> JsonValue:
+        try:
+            cancelled(self._cancellation)
+            call_id = tool_context.function_call_id
+            if not call_id:
+                raise SafeEngineError(
+                    "TOOL_DENIED",
+                    "Agent Tool Call 缺少稳定标识",
+                    retryable=False,
+                )
+            result = await self._tool_host.execute(
+                self._request.tool_host_url,
+                ToolInvocation(
+                    self._request.run_id,
+                    call_id,
+                    self.name,
+                    cast(dict[str, JsonValue], args),
+                    self._request.execution_grant,
+                ),
+            )
+            cancelled(self._cancellation)
+            return result
+        except SafeEngineError as error:
+            self._failures.capture(error)
+            raise

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

@@ -21,7 +21,6 @@ from .contracts import (
     StartRunResponse,
 )
 from .engine import AgentEngineAdapter
-from .openai_engine import OpenAiCompatibleEngineAdapter
 from .openai_provider import OpenAiCompatibleProvider
 from .provider_audit import ProviderAuditStore
 from .provider_governance import ProviderRequestGovernance
@@ -229,7 +228,7 @@ def default_engine() -> AgentEngineAdapter:
     internal_token = os.environ.get("AGENT_SERVER_INTERNAL_TOKEN", "").strip()
     if not internal_token:
         raise ValueError("Agent Server Provider 已配置但内部 Token 缺失")
-    return OpenAiCompatibleEngineAdapter(
+    return AdkEngineAdapter(
         OpenAiCompatibleProvider(
             config,
             EnvironmentSecretResolver(os.environ),

package/template/apps/agent-server/tests/__init__.py

@@ -0,0 +1 @@
+"""Agent Server test package."""

package/template/apps/agent-server/tests/openai_provider_test_support.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import json
+import tempfile
+
+import httpx
+
+from southwind_agent_server.config import (
+    EnvironmentSecretResolver,
+    OpenAiCompatibleConfig,
+    SecretRef,
+)
+from southwind_agent_server.contracts import (
+    ProviderDataPolicy,
+    ProviderEgress,
+    ProviderFieldPolicy,
+    ProviderInputFieldPolicy,
+    RuntimeLimits,
+    RuntimeToolDefinition,
+    ToolNetworkPolicy,
+)
+from southwind_agent_server.engine import EngineRunRequest
+from southwind_agent_server.openai_provider import OpenAiCompatibleProvider
+from southwind_agent_server.provider_audit import ProviderAuditStore
+from southwind_agent_server.provider_governance import ProviderRequestGovernance
+
+
+def create_provider(
+    transport: httpx.AsyncBaseTransport,
+) -> OpenAiCompatibleProvider:
+    environment = {"QWEN_API_KEY": "server-secret"}
+    return OpenAiCompatibleProvider(
+        OpenAiCompatibleConfig(
+            base_url="https://provider.test/v1",
+            model="qwen-compatible",
+            api_key_ref=SecretRef("env", "QWEN_API_KEY"),
+            https_host_allowlist=("provider.test",),
+        ),
+        EnvironmentSecretResolver(environment),
+        transport=transport,
+    )
+
+
+def runtime_request(tool_key: str) -> EngineRunRequest:
+    return EngineRunRequest(
+        run_id="run_1",
+        operation_key="business.answer",
+        input={"question": "记录"},
+        instructions="回答业务问题。",
+        user_prompt="有多少记录？",
+        allowed_tools=(
+            RuntimeToolDefinition(
+                key=tool_key,
+                label="查询记录",
+                description="查询当前数据范围内的记录。",
+            ),
+        ),
+        limits=RuntimeLimits(
+            max_duration_seconds=60,
+            max_output_bytes=4096,
+        ),
+        provider_egress=ProviderEgress(
+            mode="configured-endpoint",
+            deployment_key="ai.openai-compatible",
+        ),
+        provider_data_policy=provider_data_policy(),
+        tool_network_policy=ToolNetworkPolicy(mode="forbidden"),
+        execution_grant="grant_1",
+        tool_host_url="http://server:9747",
+    )
+
+
+def provider_data_policy() -> ProviderDataPolicy:
+    return ProviderDataPolicy(
+        input_fields=[
+            ProviderInputFieldPolicy(
+                json_pointer="/question",
+                classification="internal",
+                dlp_action="redact",
+            )
+        ],
+        envelope_fields=[
+            ProviderFieldPolicy(
+                field="instructions",
+                classification="internal",
+                dlp_action="reject",
+            ),
+            ProviderFieldPolicy(
+                field="user-prompt",
+                classification="internal",
+                dlp_action="redact",
+            ),
+            ProviderFieldPolicy(
+                field="tool-definitions",
+                classification="internal",
+                dlp_action="reject",
+            ),
+            ProviderFieldPolicy(
+                field="provider-output",
+                classification="internal",
+                dlp_action="redact",
+            ),
+            ProviderFieldPolicy(
+                field="tool-results",
+                classification="sensitive",
+                dlp_action="redact",
+            ),
+        ],
+    )
+
+
+def governance(path: str | None = None) -> ProviderRequestGovernance:
+    path = (
+        path
+        or tempfile.NamedTemporaryFile(
+            suffix=".sqlite3",
+            delete=False,
+        ).name
+    )
+    return ProviderRequestGovernance(ProviderAuditStore(path, retention_days=90))
+
+
+def sse_response(chunks: list[object]) -> httpx.Response:
+    body = "".join(
+        f"data: {json.dumps(chunk, ensure_ascii=False)}\n\n" for chunk in chunks
+    )
+    return httpx.Response(
+        200,
+        headers={"content-type": "text/event-stream"},
+        content=f"{body}data: [DONE]\n\n",
+    )