create-windy 0.8.2 → 0.9.1

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

@@ -1,298 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import time
-import uuid
-from collections.abc import Callable
-from dataclasses import replace
-from typing import Literal
-
-from .contracts import StartRunRequest
-from .engine_identity import DIRECT_ENGINE_ID
-from .report_metrics import AgentRuntimeMetrics
-from .report_presenter import (
-    aggregate_summary,
-    attempt_value,
-    attempts_for,
-    filtered_attempts,
-    filtered_runs,
-    run_value,
-    scoped_runs,
-)
-from .report_store_protocol import AgentRuntimeReportStore
-from .report_types import (
-    AttemptReport,
-    AttemptTerminalOutcome,
-    NonTerminalRunStatus,
-    ReportFilter,
-    RunReport,
-    UsageFacts,
-    identity,
-    retention_seconds,
-    validate_retention,
-)
-
-__all__ = ["AgentRuntimeReportStore", "InMemoryAgentRuntimeReportStore"]
-
-
-class InMemoryAgentRuntimeReportStore:
-    def __init__(
-        self,
-        retention_days: int = 90,
-        *,
-        now: Callable[[], float] = time.time,
-        metrics: AgentRuntimeMetrics | None = None,
-    ) -> None:
-        validate_retention(retention_days)
-        self.retention_days = retention_days
-        self._now = now
-        self.metrics = metrics or AgentRuntimeMetrics()
-        self._runs: dict[str, RunReport] = {}
-        self._attempts: dict[str, AttemptReport] = {}
-        self._lock = asyncio.Lock()
-
-    async def ensure_run(
-        self,
-        run_id: str,
-        request: StartRunRequest,
-        created_at: float,
-        engine_id: str = DIRECT_ENGINE_ID,
-    ) -> None:
-        async with self._lock:
-            self._prune()
-            context = request.reporting
-            candidate = RunReport(
-                run_id=run_id,
-                engine_id=engine_id,
-                operation_key=request.operation_key,
-                release_id=request.release.release_id,
-                trace_id=request.trace_id,
-                actor_id=context.actor_id if context else None,
-                actor_type=context.actor_type if context else None,
-                department_id=context.department_id if context else None,
-                status="accepted",
-                safe_error_code=None,
-                started_at=None,
-                finished_at=None,
-                duration_ms=None,
-                created_at=created_at,
-                updated_at=created_at,
-                expires_at=created_at + retention_seconds(self.retention_days),
-            )
-            existing = self._runs.get(run_id)
-            if existing and identity(existing) != identity(candidate):
-                raise ValueError("Agent Runtime 报表 Run 身份冲突")
-            if existing is None:
-                self._runs[run_id] = candidate
-
-    async def start_run(self, run_id: str, started_at: float) -> None:
-        async with self._lock:
-            run = self._runs[run_id]
-            if run.status in {"completed", "failed", "cancelled"}:
-                return
-            for attempt_id, attempt in self._attempts.items():
-                if attempt.run_id != run_id or attempt.outcome != "running":
-                    continue
-                usage = UsageFacts()
-                self._attempts[attempt_id] = replace(
-                    attempt,
-                    outcome="abandoned",
-                    usage=usage,
-                    duration_ms=max(
-                        0,
-                        round((started_at - attempt.started_at) * 1_000),
-                    ),
-                    finished_at=started_at,
-                )
-                self.metrics.observe_attempt("abandoned", usage)
-            self._runs[run_id] = replace(
-                run,
-                status="running",
-                started_at=run.started_at or started_at,
-                updated_at=started_at,
-            )
-
-    async def set_run_status(
-        self,
-        run_id: str,
-        status: NonTerminalRunStatus,
-        updated_at: float,
-    ) -> None:
-        async with self._lock:
-            run = self._runs[run_id]
-            if run.status in {"completed", "failed", "cancelled"}:
-                return
-            if updated_at < run.updated_at:
-                return
-            self._runs[run_id] = replace(
-                run,
-                status=status,
-                updated_at=updated_at,
-            )
-
-    async def finish_run(
-        self,
-        run_id: str,
-        status: Literal["completed", "failed", "cancelled"],
-        finished_at: float,
-        safe_error_code: str | None = None,
-    ) -> None:
-        async with self._lock:
-            run = self._runs[run_id]
-            if run.status in {"completed", "failed", "cancelled"}:
-                if run.status != status:
-                    raise ValueError("Agent Runtime 报表终态冲突")
-                return
-            started = run.started_at or run.created_at
-            self._runs[run_id] = replace(
-                run,
-                status=status,
-                safe_error_code=safe_error_code,
-                finished_at=finished_at,
-                duration_ms=max(0, round((finished_at - started) * 1_000)),
-                updated_at=finished_at,
-                expires_at=finished_at + retention_seconds(self.retention_days),
-            )
-            self.metrics.observe_run(status)
-
-    async def start_attempt(
-        self,
-        run_id: str,
-        tool_round: int,
-        deployment_key: str,
-        requested_model: str,
-        started_at: float,
-    ) -> AttemptReport:
-        async with self._lock:
-            sequence = 1 + max(
-                (
-                    attempt.sequence
-                    for attempt in self._attempts.values()
-                    if attempt.run_id == run_id
-                ),
-                default=0,
-            )
-            attempt = AttemptReport(
-                attempt_id=f"attempt_{uuid.uuid4().hex}",
-                run_id=run_id,
-                sequence=sequence,
-                tool_round=tool_round,
-                deployment_key=deployment_key,
-                requested_model=requested_model,
-                reported_model=None,
-                outcome="running",
-                usage=UsageFacts(),
-                duration_ms=None,
-                safe_error_code=None,
-                started_at=started_at,
-                finished_at=None,
-            )
-            self._attempts[attempt.attempt_id] = attempt
-            return attempt
-
-    async def finish_attempt(
-        self,
-        attempt_id: str,
-        outcome: AttemptTerminalOutcome,
-        usage: UsageFacts,
-        finished_at: float,
-        reported_model: str | None = None,
-        safe_error_code: str | None = None,
-    ) -> None:
-        async with self._lock:
-            attempt = self._attempts[attempt_id]
-            if attempt.finished_at is not None:
-                if (
-                    attempt.outcome != outcome
-                    or attempt.usage != usage
-                    or attempt.reported_model != reported_model
-                    or attempt.safe_error_code != safe_error_code
-                ):
-                    raise ValueError("Agent Runtime 报表 Attempt 终态冲突")
-                return
-            self._attempts[attempt_id] = replace(
-                attempt,
-                outcome=outcome,
-                usage=usage,
-                reported_model=reported_model,
-                safe_error_code=safe_error_code,
-                duration_ms=max(0, round((finished_at - attempt.started_at) * 1_000)),
-                finished_at=finished_at,
-            )
-            self.metrics.observe_attempt(outcome, usage)
-
-    async def summary(self, query: ReportFilter) -> dict[str, object]:
-        async with self._lock:
-            self._prune()
-            visible_runs = scoped_runs(self._runs.values(), query)
-            runs = filtered_runs(visible_runs, query)
-            attempts = filtered_attempts(
-                self._attempts.values(),
-                visible_runs,
-                query,
-            )
-            return aggregate_summary(
-                runs,
-                attempts,
-                self.retention_days,
-                min(
-                    [run.created_at for run in runs]
-                    + [attempt.started_at for attempt in attempts],
-                    default=None,
-                ),
-                self._now(),
-            )
-
-    async def list_runs(
-        self, query: ReportFilter, page: int, page_size: int
-    ) -> dict[str, object]:
-        async with self._lock:
-            self._prune()
-            runs = sorted(
-                filtered_runs(self._runs.values(), query),
-                key=lambda run: run.created_at,
-                reverse=True,
-            )
-            start = (page - 1) * page_size
-            items = [
-                run_value(run, attempts_for(self._attempts.values(), [run]))
-                for run in runs[start : start + page_size]
-            ]
-            return {
-                "items": items,
-                "total": len(runs),
-                "page": page,
-                "pageSize": page_size,
-            }
-
-    async def get_run(self, run_id: str) -> dict[str, object] | None:
-        async with self._lock:
-            self._prune()
-            run = self._runs.get(run_id)
-            if run is None:
-                return None
-            attempts = attempts_for(self._attempts.values(), [run])
-            return {
-                **run_value(run, attempts),
-                "releaseId": run.release_id,
-                "traceId": run.trace_id,
-                "safeErrorCode": run.safe_error_code,
-                "attempts": [attempt_value(item) for item in attempts],
-            }
-
-    async def close(self) -> None:
-        return None
-
-    def _prune(self) -> None:
-        expired = {
-            run_id
-            for run_id, run in self._runs.items()
-            if run.expires_at <= self._now()
-        }
-        for run_id in expired:
-            self._runs.pop(run_id, None)
-        self._attempts = {
-            key: value
-            for key, value in self._attempts.items()
-            if value.run_id not in expired
-        }

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

@@ -1,75 +0,0 @@
-from __future__ import annotations
-
-from typing import Literal, Protocol
-
-from .contracts import StartRunRequest
-from .engine_identity import DIRECT_ENGINE_ID
-from .report_metrics import AgentRuntimeMetrics
-from .report_types import (
-    AttemptReport,
-    AttemptTerminalOutcome,
-    NonTerminalRunStatus,
-    ReportFilter,
-    UsageFacts,
-)
-
-
-class AgentRuntimeReportStore(Protocol):
-    """Persistence boundary for operational reports and model attempts."""
-
-    retention_days: int
-    metrics: AgentRuntimeMetrics
-
-    async def ensure_run(
-        self,
-        run_id: str,
-        request: StartRunRequest,
-        created_at: float,
-        engine_id: str = DIRECT_ENGINE_ID,
-    ) -> None: ...
-
-    async def start_run(self, run_id: str, started_at: float) -> None: ...
-
-    async def set_run_status(
-        self,
-        run_id: str,
-        status: NonTerminalRunStatus,
-        updated_at: float,
-    ) -> None: ...
-
-    async def finish_run(
-        self,
-        run_id: str,
-        status: Literal["completed", "failed", "cancelled"],
-        finished_at: float,
-        safe_error_code: str | None = None,
-    ) -> None: ...
-
-    async def start_attempt(
-        self,
-        run_id: str,
-        tool_round: int,
-        deployment_key: str,
-        requested_model: str,
-        started_at: float,
-    ) -> AttemptReport: ...
-
-    async def finish_attempt(
-        self,
-        attempt_id: str,
-        outcome: AttemptTerminalOutcome,
-        usage: UsageFacts,
-        finished_at: float,
-        reported_model: str | None = None,
-        safe_error_code: str | None = None,
-    ) -> None: ...
-
-    async def summary(self, query: ReportFilter) -> dict[str, object]: ...
-
-    async def list_runs(
-        self, query: ReportFilter, page: int, page_size: int
-    ) -> dict[str, object]: ...
-
-    async def get_run(self, run_id: str) -> dict[str, object] | None: ...
-
-    async def close(self) -> None: ...

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

@@ -1,118 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from datetime import UTC, datetime
-from typing import Literal
-
-from .contracts import RunStatus
-
-type AttemptTerminalOutcome = Literal[
-    "completed", "failed", "cancelled", "blocked", "abandoned"
-]
-type AttemptOutcome = Literal["running"] | AttemptTerminalOutcome
-type NonTerminalRunStatus = Literal["running", "awaiting-approval"]
-type CacheStatus = Literal["hit", "miss", "unknown"]
-type UsageSource = Literal["provider-reported", "estimated", "unknown"]
-
-
-@dataclass(frozen=True)
-class UsageFacts:
-    source: UsageSource = "unknown"
-    input_tokens: int | None = None
-    output_tokens: int | None = None
-    cached_input_tokens: int | None = None
-    reasoning_tokens: int | None = None
-    total_tokens: int | None = None
-    first_token_latency_ms: int | None = None
-    cache_status: CacheStatus = "unknown"
-
-    def event_value(self) -> dict[str, str | int]:
-        result: dict[str, str | int] = {
-            "source": self.source,
-            "cacheStatus": self.cache_status,
-        }
-        for key, value in (
-            ("inputTokens", self.input_tokens),
-            ("outputTokens", self.output_tokens),
-            ("cachedInputTokens", self.cached_input_tokens),
-            ("reasoningTokens", self.reasoning_tokens),
-            ("totalTokens", self.total_tokens),
-            ("firstTokenLatencyMs", self.first_token_latency_ms),
-        ):
-            if value is not None:
-                result[key] = value
-        return result
-
-
-@dataclass(frozen=True)
-class RunReport:
-    run_id: str
-    engine_id: str
-    operation_key: str
-    release_id: str
-    trace_id: str
-    actor_id: str | None
-    actor_type: str | None
-    department_id: str | None
-    status: RunStatus
-    safe_error_code: str | None
-    started_at: float | None
-    finished_at: float | None
-    duration_ms: int | None
-    created_at: float
-    updated_at: float
-    expires_at: float
-
-
-@dataclass(frozen=True)
-class AttemptReport:
-    attempt_id: str
-    run_id: str
-    sequence: int
-    tool_round: int
-    deployment_key: str
-    requested_model: str
-    reported_model: str | None
-    outcome: AttemptOutcome
-    usage: UsageFacts
-    duration_ms: int | None
-    safe_error_code: str | None
-    started_at: float
-    finished_at: float | None
-
-
-@dataclass(frozen=True)
-class ReportFilter:
-    from_timestamp: float
-    to_timestamp: float
-    selected_actor_id: str | None = None
-    scope_restricted: bool = False
-    actor_ids: tuple[str, ...] = ()
-    department_ids: tuple[str, ...] = ()
-
-
-def validate_retention(value: int) -> None:
-    if not 1 <= value <= 3650:
-        raise ValueError("AI Runtime 报表留存天数超出范围")
-
-
-def retention_seconds(days: int) -> int:
-    return days * 24 * 60 * 60
-
-
-def iso(value: float | None) -> str | None:
-    return (
-        datetime.fromtimestamp(value, tz=UTC).isoformat().replace("+00:00", "Z")
-        if value is not None
-        else None
-    )
-
-
-def identity(run: RunReport) -> tuple[str, str, str, str, str | None]:
-    return (
-        run.engine_id,
-        run.operation_key,
-        run.release_id,
-        run.trace_id,
-        run.actor_id,
-    )

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

@@ -1,64 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-from dataclasses import dataclass
-
-from .contracts import JsonValue
-from .engine import SafeEngineError
-from .run_capacity import (
-    RunCapacity,
-    RunCapacityReservation,
-    RunCapacityUnavailable,
-)
-from .store import IdempotencyConflictError, RunRecord, RunStore
-
-
-@dataclass(frozen=True)
-class RunAdmissionResult:
-    record: RunRecord
-    reservation: RunCapacityReservation | None
-
-
-class RunAdmission:
-    def __init__(self, store: RunStore, capacity: RunCapacity) -> None:
-        self._store = store
-        self._capacity = capacity
-        self._lock = asyncio.Lock()
-
-    async def admit(
-        self,
-        candidate: RunRecord,
-        invocation: JsonValue,
-    ) -> RunAdmissionResult:
-        async with self._lock:
-            current = await self._store.get_by_idempotency(candidate.idempotency_key)
-            if current:
-                if current.fingerprint != candidate.fingerprint:
-                    raise IdempotencyConflictError
-                return RunAdmissionResult(current, None)
-            try:
-                reservation = await self._capacity.reserve()
-            except RunCapacityUnavailable:
-                raise SafeEngineError(
-                    "RUNTIME_UNAVAILABLE",
-                    "VLM Runtime 容量已满",
-                    retryable=True,
-                ) from None
-            try:
-                record, created = await self._store.create_or_get(
-                    candidate,
-                    invocation,
-                )
-            except Exception:
-                await reservation.release()
-                raise
-            if not created:
-                await reservation.release()
-                return RunAdmissionResult(record, None)
-            return RunAdmissionResult(record, reservation)
-
-    async def reserve_recovery(self) -> RunCapacityReservation | None:
-        try:
-            return await self._capacity.reserve()
-        except RunCapacityUnavailable:
-            return None

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

@@ -1,59 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-
-
-class RunCapacityUnavailable(Exception):
-    pass
-
-
-class RunCapacity:
-    def __init__(self, max_concurrent_runs: int, max_queue_depth: int) -> None:
-        if max_concurrent_runs < 1 or max_queue_depth < 0:
-            raise ValueError("Agent Run 容量配置无效")
-        self._maximum = max_concurrent_runs
-        self._queue_maximum = max_queue_depth
-        self._active = 0
-        self._queued = 0
-        self._condition = asyncio.Condition()
-
-    async def reserve(self) -> RunCapacityReservation:
-        async with self._condition:
-            if self._active + self._queued >= self._maximum + self._queue_maximum:
-                raise RunCapacityUnavailable
-            self._queued += 1
-            return RunCapacityReservation(self)
-
-    async def enter(self, reservation: RunCapacityReservation) -> None:
-        async with self._condition:
-            while self._active >= self._maximum:
-                await self._condition.wait()
-            if reservation.released or reservation.entered:
-                raise RuntimeError("Agent Run 容量票据状态无效")
-            self._queued -= 1
-            self._active += 1
-            reservation.entered = True
-
-    async def release(self, reservation: RunCapacityReservation) -> None:
-        async with self._condition:
-            if reservation.released:
-                return
-            if reservation.entered:
-                self._active -= 1
-            else:
-                self._queued -= 1
-            reservation.released = True
-            self._condition.notify_all()
-
-
-class RunCapacityReservation:
-    def __init__(self, capacity: RunCapacity) -> None:
-        self._capacity = capacity
-        self.entered = False
-        self.released = False
-
-    async def enter(self) -> None:
-        await self._capacity.enter(self)
-
-    async def release(self) -> None:
-        await self._capacity.release(self)

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

@@ -1,74 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from .contracts import RuntimeLimits
-from .engine import SafeEngineError
-from .report_types import UsageFacts
-
-
-@dataclass
-class RuntimeBudgetAdmission:
-    limits: RuntimeLimits
-    input_tokens: int = 0
-    output_tokens: int = 0
-    tool_calls: int = 0
-
-    def before_attempt(self, attempt: int) -> int | None:
-        if (
-            self.limits.max_model_attempts is not None
-            and attempt > self.limits.max_model_attempts
-        ):
-            self._denied("Agent 模型调用次数超过 Workflow 上限")
-        if self.limits.max_input_tokens is not None:
-            if self.input_tokens >= self.limits.max_input_tokens:
-                self._denied("Agent 输入 Token 已耗尽")
-        if self.limits.max_output_tokens is None:
-            return None
-        remaining = self.limits.max_output_tokens - self.output_tokens
-        if remaining <= 0:
-            self._denied("Agent 输出 Token 已耗尽")
-        return remaining
-
-    def record_usage(self, usage: UsageFacts) -> None:
-        if usage.input_tokens is None or usage.output_tokens is None:
-            if (
-                self.limits.max_input_tokens is not None
-                or self.limits.max_output_tokens is not None
-            ):
-                self._denied("Provider 未返回 Workflow Token 计量")
-            return
-        self.input_tokens += usage.input_tokens
-        self.output_tokens += usage.output_tokens
-        if (
-            self.limits.max_input_tokens is not None
-            and self.input_tokens > self.limits.max_input_tokens
-        ):
-            self._denied("Agent 输入 Token 超过 Workflow 上限")
-        if (
-            self.limits.max_output_tokens is not None
-            and self.output_tokens > self.limits.max_output_tokens
-        ):
-            self._denied("Agent 输出 Token 超过 Workflow 上限")
-
-    def before_provider(self, conservative_input_tokens: int) -> None:
-        if conservative_input_tokens < 0:
-            self._denied("Agent 输入 Token 上界无效")
-        if (
-            self.limits.max_input_tokens is not None
-            and self.input_tokens + conservative_input_tokens
-            > self.limits.max_input_tokens
-        ):
-            self._denied("Agent 本次输入可能超过 Workflow Token 上限")
-
-    def reserve_tools(self, count: int) -> None:
-        self.tool_calls += count
-        if (
-            self.limits.max_tool_calls is not None
-            and self.tool_calls > self.limits.max_tool_calls
-        ):
-            self._denied("Agent Tool 调用次数超过 Workflow 上限")
-
-    @staticmethod
-    def _denied(message: str) -> None:
-        raise SafeEngineError("BUDGET_EXCEEDED", message, retryable=False)