create-windy 0.4.0 → 0.5.0

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

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from typing import Any
+
+from psycopg import AsyncConnection
+from psycopg_pool import AsyncConnectionPool
+
+from .postgres_report_queries import (
+    attempt_filter_clause,
+    filter_clause,
+)
+from .report_types import ReportFilter, iso
+
+type DatabaseConnection = AsyncConnection[dict[str, Any]]
+type DatabasePool = AsyncConnectionPool[DatabaseConnection]
+
+
+async def summary(
+    pool: DatabasePool,
+    query: ReportFilter,
+    retention_days: int,
+    generated_at: float,
+) -> dict[str, object]:
+    run_clause, run_parameters = filter_clause(query, generated_at, "r")
+    attempt_clause, attempt_parameters = attempt_filter_clause(
+        query,
+        generated_at,
+    )
+    async with pool.connection() as connection:
+        run_row = await fetch_one(
+            connection,
+            f"""
+            select count(*) as total,
+              count(*) filter (where r.status = 'completed') as completed,
+              count(*) filter (where r.status = 'failed') as failed,
+              count(*) filter (where r.status = 'cancelled') as cancelled,
+              min(r.created_at) as available_from
+            from agent_runtime_report_runs r {run_clause}
+            """,
+            run_parameters,
+        )
+        attempt_row = await fetch_one(
+            connection,
+            f"""
+            select count(*) as attempts,
+              min(a.started_at) as available_from,
+              count(*) filter (where a.cache_status = 'hit') as cache_hit,
+              count(*) filter (where a.cache_status = 'miss') as cache_miss,
+              count(*) filter (where a.cache_status = 'unknown') as cache_unknown,
+              count(*) filter (
+                where a.total_tokens is not null
+              ) as known_total_tokens,
+              sum(a.input_tokens) as input_tokens,
+              sum(a.output_tokens) as output_tokens,
+              sum(a.cached_input_tokens) as cached_input_tokens,
+              sum(a.reasoning_tokens) as reasoning_tokens,
+              sum(a.total_tokens) as total_tokens,
+              coalesce(sum(a.input_tokens) filter (
+                where a.input_tokens is not null
+                  and a.cached_input_tokens is not null
+              ), 0) as paired_input_tokens,
+              coalesce(sum(a.cached_input_tokens) filter (
+                where a.input_tokens is not null
+                  and a.cached_input_tokens is not null
+              ), 0) as paired_cached_tokens
+            from agent_runtime_report_attempts a
+            join agent_runtime_report_runs r on r.run_id = a.run_id
+            {attempt_clause}
+            """,
+            attempt_parameters,
+        )
+        model_rows = await fetch_all(
+            connection,
+            f"""
+            select a.deployment_key,
+              coalesce(a.reported_model, a.requested_model) as model,
+              count(*) as attempts,
+              sum(a.input_tokens) as input_tokens,
+              sum(a.output_tokens) as output_tokens,
+              sum(a.cached_input_tokens) as cached_input_tokens,
+              sum(a.reasoning_tokens) as reasoning_tokens,
+              sum(a.total_tokens) as total_tokens,
+              count(*) filter (
+                where a.usage_source = 'unknown'
+              ) as unknown_usage_count
+            from agent_runtime_report_attempts a
+            join agent_runtime_report_runs r on r.run_id = a.run_id
+            {attempt_clause}
+            group by a.deployment_key,
+              coalesce(a.reported_model, a.requested_model)
+            order by a.deployment_key,
+              coalesce(a.reported_model, a.requested_model)
+            """,
+            attempt_parameters,
+        )
+        activity_rows = await fetch_all(
+            connection,
+            f"""
+            with run_activity as (
+              select to_char(
+                  to_timestamp(r.created_at) at time zone 'UTC',
+                  'YYYY-MM-DD'
+                ) as date,
+                count(*) as runs,
+                count(*) filter (
+                  where r.status = 'completed'
+                ) as completed,
+                count(*) filter (where r.status = 'failed') as failed
+              from agent_runtime_report_runs r
+              {run_clause}
+              group by 1
+            ),
+            attempt_activity as (
+              select to_char(
+                  to_timestamp(a.started_at) at time zone 'UTC',
+                  'YYYY-MM-DD'
+                ) as date,
+                count(*) as attempts,
+                count(a.total_tokens) as known_token_attempts,
+                sum(a.total_tokens) as total_tokens
+              from agent_runtime_report_attempts a
+              join agent_runtime_report_runs r on r.run_id = a.run_id
+              {attempt_clause}
+              group by 1
+            ),
+            activity_dates as (
+              select date from run_activity
+              union
+              select date from attempt_activity
+            )
+            select d.date,
+              coalesce(ra.runs, 0) as runs,
+              coalesce(ra.completed, 0) as completed,
+              coalesce(ra.failed, 0) as failed,
+              coalesce(aa.attempts, 0) as attempts,
+              aa.total_tokens
+            from activity_dates d
+            left join run_activity ra on ra.date = d.date
+            left join attempt_activity aa on aa.date = d.date
+            order by d.date
+            """,
+            (*run_parameters, *attempt_parameters),
+        )
+    return present_summary(
+        run_row,
+        attempt_row,
+        model_rows,
+        activity_rows,
+        retention_days,
+        generated_at,
+    )
+
+
+def present_summary(
+    run: dict[str, Any],
+    attempt: dict[str, Any],
+    models: list[dict[str, Any]],
+    activity: list[dict[str, Any]],
+    retention_days: int,
+    generated_at: float,
+) -> dict[str, object]:
+    total = integer(run, "total")
+    completed = integer(run, "completed")
+    failed = integer(run, "failed")
+    cancelled = integer(run, "cancelled")
+    attempts = integer(attempt, "attempts")
+    cache_hit = integer(attempt, "cache_hit")
+    cache_miss = integer(attempt, "cache_miss")
+    paired_input = integer(attempt, "paired_input_tokens")
+    available_values = [
+        value
+        for value in (
+            optional_float(run, "available_from"),
+            optional_float(attempt, "available_from"),
+        )
+        if value is not None
+    ]
+    return {
+        "generatedAt": iso(generated_at),
+        "reportingAvailableFrom": iso(
+            min(available_values) if available_values else None
+        ),
+        "retentionDays": retention_days,
+        "runs": {
+            "total": total,
+            "completed": completed,
+            "failed": failed,
+            "cancelled": cancelled,
+            "inProgress": total - completed - failed - cancelled,
+            "successRate": (
+                completed / (completed + failed) if completed + failed else None
+            ),
+        },
+        "cache": {
+            "hit": cache_hit,
+            "miss": cache_miss,
+            "unknown": integer(attempt, "cache_unknown"),
+            "hitRate": (
+                cache_hit / (cache_hit + cache_miss) if cache_hit + cache_miss else None
+            ),
+            "tokenRate": (
+                integer(attempt, "paired_cached_tokens") / paired_input
+                if paired_input > 0
+                else None
+            ),
+            "coverageRate": ((cache_hit + cache_miss) / attempts if attempts else 0),
+        },
+        "tokens": {
+            "input": aggregate_token(attempt, "input_tokens", attempts),
+            "output": aggregate_token(attempt, "output_tokens", attempts),
+            "cachedInput": aggregate_token(
+                attempt,
+                "cached_input_tokens",
+                attempts,
+            ),
+            "reasoning": aggregate_token(
+                attempt,
+                "reasoning_tokens",
+                attempts,
+            ),
+            "total": aggregate_token(attempt, "total_tokens", attempts),
+            "coverageRate": (
+                integer(attempt, "known_total_tokens") / attempts if attempts else 0
+            ),
+        },
+        "byModel": [present_model(row) for row in models],
+        "activity": [present_activity(row) for row in activity],
+    }
+
+
+def present_model(row: dict[str, Any]) -> dict[str, object]:
+    return {
+        "deploymentKey": text(row, "deployment_key"),
+        "model": text(row, "model"),
+        "attempts": integer(row, "attempts"),
+        "inputTokens": optional_integer(row, "input_tokens"),
+        "outputTokens": optional_integer(row, "output_tokens"),
+        "cachedInputTokens": optional_integer(row, "cached_input_tokens"),
+        "reasoningTokens": optional_integer(row, "reasoning_tokens"),
+        "totalTokens": optional_integer(row, "total_tokens"),
+        "unknownUsageCount": integer(row, "unknown_usage_count"),
+    }
+
+
+def present_activity(row: dict[str, Any]) -> dict[str, object]:
+    attempts = integer(row, "attempts")
+    known_attempts = integer(row, "known_token_attempts")
+    return {
+        "date": text(row, "date"),
+        "runs": integer(row, "runs"),
+        "completed": integer(row, "completed"),
+        "failed": integer(row, "failed"),
+        "totalTokens": (
+            optional_integer(row, "total_tokens")
+            if attempts and known_attempts == attempts
+            else None
+        ),
+    }
+
+
+async def fetch_one(
+    connection: DatabaseConnection,
+    query: str,
+    parameters: tuple[object, ...],
+) -> dict[str, Any]:
+    row = await (await connection.execute(query, parameters)).fetchone()
+    if row is None:
+        raise RuntimeError("AI Runtime 报表聚合查询未返回结果")
+    return row
+
+
+async def fetch_all(
+    connection: DatabaseConnection,
+    query: str,
+    parameters: tuple[object, ...],
+) -> list[dict[str, Any]]:
+    return list(await (await connection.execute(query, parameters)).fetchall())
+
+
+def integer(row: dict[str, Any], key: str) -> int:
+    return int(row[key])
+
+
+def optional_integer(row: dict[str, Any], key: str) -> int | None:
+    value = row[key]
+    return int(value) if value is not None else None
+
+
+def aggregate_token(
+    row: dict[str, Any],
+    key: str,
+    attempt_count: int,
+) -> int | None:
+    value = optional_integer(row, key)
+    return value if value is not None else (0 if attempt_count == 0 else None)
+
+
+def text(row: dict[str, Any], key: str) -> str:
+    return str(row[key])
+
+
+def optional_float(row: dict[str, Any], key: str) -> float | None:
+    value = row[key]
+    return float(value) if value is not None else None

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

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import Literal, cast
+
+from .contracts import StartRunRequest
+from .report_store import AgentRuntimeReportStore
+from .report_types import (
+    AttemptReport,
+    AttemptTerminalOutcome,
+    NonTerminalRunStatus,
+    UsageFacts,
+)
+from .store import CanonicalEvent, RunRecord, RunStore
+
+logger = logging.getLogger(__name__)
+
+
+async def ensure_run_report_safely(
+    store: AgentRuntimeReportStore,
+    run_id: str,
+    request: StartRunRequest,
+) -> None:
+    try:
+        await store.ensure_run(run_id, request, time.time())
+    except Exception:
+        reporting_failure(store, "run_ensure", run_id)
+
+
+async def start_run_report_safely(
+    store: AgentRuntimeReportStore,
+    run_id: str,
+) -> None:
+    try:
+        await store.start_run(run_id, time.time())
+    except Exception:
+        reporting_failure(store, "run_start", run_id)
+
+
+async def finish_run_report_safely(
+    store: AgentRuntimeReportStore,
+    run_id: str,
+    status: Literal["completed", "failed", "cancelled"],
+    safe_error_code: str | None = None,
+) -> None:
+    """Keep a reporting outage from changing the canonical Run terminal state."""
+    try:
+        await store.finish_run(
+            run_id,
+            status,
+            time.time(),
+            safe_error_code,
+        )
+    except Exception:
+        reporting_failure(
+            store,
+            "run_terminal",
+            run_id,
+            {"report_status": status},
+        )
+
+
+async def sync_terminal_from_canonical(
+    report_store: AgentRuntimeReportStore,
+    canonical_store: RunStore,
+    run_id: str,
+    fallback_safe_error_code: str | None = None,
+) -> RunRecord | None:
+    record = await canonical_store.get(run_id)
+    if record is None or not record.terminal:
+        return None
+    status = cast(Literal["completed", "failed", "cancelled"], record.status)
+    safe_error_code = None
+    if status == "failed":
+        safe_error_code = canonical_error_code(record) or fallback_safe_error_code
+    await finish_run_report_safely(
+        report_store,
+        run_id,
+        status,
+        safe_error_code,
+    )
+    return record
+
+
+async def sync_canonical_event(
+    report_store: AgentRuntimeReportStore,
+    canonical_store: RunStore,
+    run_id: str,
+    event: CanonicalEvent | None,
+    fallback_safe_error_code: str | None = None,
+) -> RunRecord | None:
+    event_type = event.get("type") if event else None
+    if event is None or event_type in {
+        "run.completed",
+        "run.failed",
+        "run.cancelled",
+    }:
+        return await sync_terminal_from_canonical(
+            report_store,
+            canonical_store,
+            run_id,
+            fallback_safe_error_code,
+        )
+    if isinstance(event_type, str):
+        await sync_status(report_store, run_id, event_type)
+    return None
+
+
+async def append_and_sync_canonical_event(
+    report_store: AgentRuntimeReportStore,
+    canonical_store: RunStore,
+    run_id: str,
+    event_type: str,
+    fields: dict[str, object] | None = None,
+    fallback_safe_error_code: str | None = None,
+) -> RunRecord | None:
+    event = await canonical_store.append(run_id, event_type, fields)
+    return await sync_canonical_event(
+        report_store,
+        canonical_store,
+        run_id,
+        event,
+        fallback_safe_error_code,
+    )
+
+
+async def sync_status(
+    store: AgentRuntimeReportStore,
+    run_id: str,
+    event_type: str,
+) -> None:
+    status: NonTerminalRunStatus
+    if event_type == "approval.required":
+        status = "awaiting-approval"
+    elif event_type == "approval.resolved":
+        status = "running"
+    else:
+        return
+    try:
+        await store.set_run_status(run_id, status, time.time())
+    except Exception:
+        reporting_failure(
+            store,
+            "run_status",
+            run_id,
+            {"report_status": status},
+        )
+
+
+def canonical_error_code(record: RunRecord) -> str | None:
+    for event in reversed(record.events):
+        if event.get("type") != "run.failed":
+            continue
+        error = event.get("error")
+        if isinstance(error, dict):
+            code = error.get("code")
+            if isinstance(code, str):
+                return code
+    return None
+
+
+async def start_attempt_report_safely(
+    store: AgentRuntimeReportStore,
+    run_id: str,
+    tool_round: int,
+    deployment_key: str,
+    requested_model: str,
+) -> AttemptReport | None:
+    try:
+        return await store.start_attempt(
+            run_id,
+            tool_round,
+            deployment_key,
+            requested_model,
+            time.time(),
+        )
+    except Exception:
+        reporting_failure(store, "attempt_start", run_id)
+        return None
+
+
+async def finish_attempt_report_safely(
+    store: AgentRuntimeReportStore,
+    attempt: AttemptReport | None,
+    outcome: AttemptTerminalOutcome,
+    usage: UsageFacts,
+    *,
+    reported_model: str | None = None,
+    safe_error_code: str | None = None,
+) -> None:
+    if attempt is None:
+        return
+    try:
+        await store.finish_attempt(
+            attempt.attempt_id,
+            outcome,
+            usage,
+            time.time(),
+            reported_model,
+            safe_error_code,
+        )
+    except Exception:
+        reporting_failure(store, "attempt_terminal", attempt.run_id)
+
+
+def reporting_failure(
+    store: AgentRuntimeReportStore,
+    stage: str,
+    run_id: str,
+    extra: dict[str, str] | None = None,
+) -> None:
+    store.metrics.observe_reporting_failure(stage)
+    logger.exception(
+        "Agent Runtime 报表写入失败",
+        extra={"run_id": run_id, "report_stage": stage, **(extra or {})},
+    )

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

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from threading import Lock
+
+from .report_types import AttemptTerminalOutcome, UsageFacts
+
+
+class AgentRuntimeMetrics:
+    """In-process Prometheus counters with deliberately low-cardinality labels."""
+
+    def __init__(self) -> None:
+        self._values: defaultdict[tuple[str, ...], int] = defaultdict(int)
+        self._lock = Lock()
+
+    def observe_run(self, outcome: str) -> None:
+        with self._lock:
+            self._values[("runs", outcome)] += 1
+
+    def observe_reporting_failure(self, stage: str) -> None:
+        with self._lock:
+            self._values[("reporting_failures", stage)] += 1
+
+    def observe_attempt(
+        self,
+        outcome: AttemptTerminalOutcome,
+        usage: UsageFacts,
+    ) -> None:
+        with self._lock:
+            self._values[("attempts", outcome)] += 1
+            self._values[("cache", usage.cache_status)] += 1
+            self._values[("usage", usage.source)] += 1
+            for kind, value in (
+                ("input", usage.input_tokens),
+                ("output", usage.output_tokens),
+                ("cached_input", usage.cached_input_tokens),
+                ("reasoning", usage.reasoning_tokens),
+                ("total", usage.total_tokens),
+            ):
+                if value is not None:
+                    self._values[("tokens", kind, usage.source)] += value
+
+    def render(self) -> str:
+        with self._lock:
+            values = dict(self._values)
+        lines = [
+            "# HELP southwind_agent_runtime_runs_total Terminal Agent runs.",
+            "# TYPE southwind_agent_runtime_runs_total counter",
+        ]
+        lines.extend(
+            metric(
+                "southwind_agent_runtime_runs_total",
+                {"outcome": outcome},
+                values.get(("runs", outcome), 0),
+            )
+            for outcome in ("completed", "failed", "cancelled")
+        )
+        lines.extend(
+            (
+                "# HELP southwind_agent_runtime_attempts_total Provider attempts.",
+                "# TYPE southwind_agent_runtime_attempts_total counter",
+            )
+        )
+        lines.extend(
+            metric(
+                "southwind_agent_runtime_attempts_total",
+                {"outcome": outcome},
+                values.get(("attempts", outcome), 0),
+            )
+            for outcome in (
+                "completed",
+                "failed",
+                "cancelled",
+                "blocked",
+                "abandoned",
+            )
+        )
+        lines.extend(
+            (
+                "# HELP southwind_agent_runtime_cache_attempts_total Cache facts.",
+                "# TYPE southwind_agent_runtime_cache_attempts_total counter",
+            )
+        )
+        lines.extend(
+            metric(
+                "southwind_agent_runtime_cache_attempts_total",
+                {"status": status},
+                values.get(("cache", status), 0),
+            )
+            for status in ("hit", "miss", "unknown")
+        )
+        lines.extend(
+            (
+                "# HELP southwind_agent_runtime_usage_attempts_total Usage coverage.",
+                "# TYPE southwind_agent_runtime_usage_attempts_total counter",
+            )
+        )
+        lines.extend(
+            metric(
+                "southwind_agent_runtime_usage_attempts_total",
+                {"source": source},
+                values.get(("usage", source), 0),
+            )
+            for source in ("provider-reported", "estimated", "unknown")
+        )
+        lines.extend(
+            (
+                "# HELP southwind_agent_runtime_reporting_failures_total "
+                "Internal reporting write failures.",
+                "# TYPE southwind_agent_runtime_reporting_failures_total counter",
+            )
+        )
+        lines.extend(
+            metric(
+                "southwind_agent_runtime_reporting_failures_total",
+                {"stage": stage},
+                values.get(("reporting_failures", stage), 0),
+            )
+            for stage in (
+                "run_ensure",
+                "run_start",
+                "run_status",
+                "run_terminal",
+                "attempt_start",
+                "attempt_terminal",
+            )
+        )
+        lines.extend(
+            (
+                "# HELP southwind_agent_runtime_tokens_total Reported token usage.",
+                "# TYPE southwind_agent_runtime_tokens_total counter",
+            )
+        )
+        for key, value in sorted(values.items()):
+            if len(key) == 3 and key[0] == "tokens":
+                _, kind, source = key
+                lines.append(
+                    metric(
+                        "southwind_agent_runtime_tokens_total",
+                        {"kind": kind, "source": source},
+                        value,
+                    )
+                )
+        return "\n".join(lines) + "\n"
+
+
+def metric(name: str, labels: dict[str, str], value: int) -> str:
+    encoded = ",".join(f'{key}="{item}"' for key, item in labels.items())
+    return f"{name}{{{encoded}}} {value}"