create-windy 0.5.2 → 0.6.0

package/template/apps/speech-server/src/southwind_speech_server/errors.py

@@ -4,3 +4,11 @@ class SafeSpeechError(Exception):
         self.code = code
         self.safe_message = message
         self.retryable = retryable
+
+
+def safe_speech_status(error: SafeSpeechError) -> int:
+    if error.code == "FORBIDDEN":
+        return 403
+    if error.code in {"CAPABILITY_UNAVAILABLE", "RUNTIME_UNAVAILABLE"}:
+        return 503
+    return 400

package/template/apps/speech-server/src/southwind_speech_server/normalizer.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import math
 import shutil
 from dataclasses import dataclass
 from pathlib import Path
@@ -30,12 +31,18 @@ class AudioNormalizer:
         target: Path,
         max_duration_seconds: int,
         timeout_seconds: int,
+        max_output_bytes: int | None = None,
     ) -> NormalizedAudio:
         if not self.available:
             raise NormalizationError("CAPABILITY_UNAVAILABLE", "音频归一化工具不可用")
         duration_ms = await self._duration(source, timeout_seconds)
         if duration_ms > max_duration_seconds * 1000:
             raise NormalizationError("BUDGET_EXCEEDED", "音频时长超过 Operation 配额")
+        if (
+            max_output_bytes is not None
+            and estimated_pcm_bytes(duration_ms) > max_output_bytes
+        ):
+            raise NormalizationError("BUDGET_EXCEEDED", "归一化 PCM 预计超过输出上限")
         await run_process(
             [
                 "ffmpeg",
@@ -58,6 +65,9 @@ class AudioNormalizer:
         )
         if not await asyncio.to_thread(valid_output, target):
             raise NormalizationError("INVALID_INPUT", "音频归一化输出无效")
+        output_size = await asyncio.to_thread(lambda: target.stat().st_size)
+        if max_output_bytes is not None and output_size > max_output_bytes:
+            raise NormalizationError("BUDGET_EXCEEDED", "归一化 PCM 超过输出上限")
         return NormalizedAudio(target, duration_ms)
 
     async def _duration(self, source: Path, timeout_seconds: int) -> int:
@@ -106,3 +116,7 @@ async def run_process(arguments: list[str], timeout_seconds: int) -> str:
 
 def valid_output(target: Path) -> bool:
     return target.is_file() and target.stat().st_size > 44
+
+
+def estimated_pcm_bytes(duration_ms: int) -> int:
+    return 44 + math.ceil(duration_ms * 32)

package/template/apps/speech-server/src/southwind_speech_server/output_artifact.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from pathlib import Path
+
+import httpx
+
+from .config import SpeechRuntimeConfig
+from .contracts import JsonValue, OutputArtifactSink, StartSpeechRunRequest
+from .errors import SafeSpeechError
+
+
+class SpeechOutputArtifactClient:
+    part_bytes = 8 * 1024 * 1024
+
+    def __init__(self, config: SpeechRuntimeConfig) -> None:
+        self.config = config
+
+    async def accept_grant(
+        self, request: StartSpeechRunRequest, grant: str | None
+    ) -> None:
+        sink = request.output_artifact_sink
+        if request.effective_variant != "normalize":
+            return
+        if sink is None or not grant or not self._valid_sink(request, sink):
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE", "normalize Sink 无效", False
+            )
+        url = (
+            f"{self.config.output_artifact_url.rstrip('/')}/scopes/{sink.scope}"
+            f"/grants/{sink.grant_generation}/accept"
+        )
+        try:
+            async with httpx.AsyncClient(
+                timeout=self.config.connect_timeout_seconds
+            ) as client:
+                response = await client.post(url, headers=self._headers(grant))
+                response.raise_for_status()
+        except Exception as error:
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE", "normalize Sink 授权失败", True
+            ) from error
+
+    async def abort_open(
+        self, request: StartSpeechRunRequest, grant: str | None
+    ) -> None:
+        sink = request.output_artifact_sink
+        if sink is None or not grant:
+            return
+        try:
+            async with httpx.AsyncClient(
+                timeout=self.config.connect_timeout_seconds
+            ) as client:
+                response = await client.delete(
+                    f"{self.config.output_artifact_url.rstrip('/')}/scopes/"
+                    f"{sink.scope}/open",
+                    headers=self._headers(grant),
+                )
+                response.raise_for_status()
+        except Exception as error:
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE", "normalize Sink 清理失败", True
+            ) from error
+
+    async def publish(
+        self, sink: OutputArtifactSink, grant: str, path: Path
+    ) -> JsonValue:
+        byte_size, digest = await file_metadata(path)
+        if byte_size > min(
+            sink.limits.max_artifact_bytes,
+            sink.limits.max_total_bytes,
+            self.config.max_output_artifact_bytes,
+        ):
+            raise SafeSpeechError(
+                "BUDGET_EXCEEDED", "normalize 输出超过 Sink 上限", False
+            )
+        headers = self._headers(grant)
+        base = f"{self.config.output_artifact_url.rstrip('/')}/scopes/{sink.scope}"
+        try:
+            async with httpx.AsyncClient(
+                timeout=self.config.request_timeout_seconds
+            ) as client:
+                begun = await client.post(
+                    f"{base}/artifacts",
+                    headers=headers,
+                    json={
+                        "contractVersion": 1,
+                        "outputKey": "normalized-audio",
+                        "filename": "normalized.wav",
+                        "mediaType": "audio/wav",
+                        "byteSize": byte_size,
+                        "sha256": digest,
+                        "outputKind": "normalized-audio",
+                    },
+                )
+                begun.raise_for_status()
+                artifact_id = begun.json().get("artifactId")
+                if not isinstance(artifact_id, str):
+                    raise ValueError("missing artifact")
+                await self._upload_parts(
+                    client, base, artifact_id, headers, path, byte_size
+                )
+                completed = await client.post(
+                    f"{base}/artifacts/{artifact_id}/complete", headers=headers
+                )
+                completed.raise_for_status()
+                sealed = await client.post(f"{base}/seal", headers=headers)
+                sealed.raise_for_status()
+                refs = sealed.json().get("artifacts")
+                if not isinstance(refs, list) or len(refs) != 1:
+                    raise ValueError("missing sealed ref")
+                reference = refs[0]
+                if not isinstance(reference, dict):
+                    raise ValueError("invalid sealed ref")
+                return {
+                    "mediaType": reference.get("mediaType"),
+                    "byteSize": reference.get("byteSize"),
+                    "sha256": reference.get("sha256"),
+                }
+        except SafeSpeechError:
+            raise
+        except Exception as error:
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE", "normalize 输出 Artifact 写入失败", True
+            ) from error
+
+    async def _upload_parts(
+        self,
+        client: httpx.AsyncClient,
+        base: str,
+        artifact_id: str,
+        headers: dict[str, str],
+        path: Path,
+        expected_size: int,
+    ) -> None:
+        offset = 0
+        part_number = 0
+        with path.open("rb") as source:
+            while chunk := await asyncio.to_thread(source.read, self.part_bytes):
+                part_digest = hashlib.sha256(chunk).hexdigest()
+                response = await client.put(
+                    f"{base}/artifacts/{artifact_id}/parts/{part_number}",
+                    headers={
+                        **headers,
+                        "x-ai-output-part-sha256": part_digest,
+                        "x-ai-output-part-offset": str(offset),
+                    },
+                    content=chunk,
+                )
+                response.raise_for_status()
+                offset += len(chunk)
+                part_number += 1
+        if offset != expected_size:
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE", "normalize 输出在上传期间发生变化", True
+            )
+
+    def _valid_sink(
+        self, request: StartSpeechRunRequest, sink: OutputArtifactSink
+    ) -> bool:
+        return bool(
+            sink.deployment_identity == self.config.deployment_identity
+            and sink.release_digest == self.config.release_digest
+            and sink.offers_digest == self.config.offers_digest
+            and sink.allowed_media_types == ["audio/wav"]
+            and sink.limits.max_artifacts == 1
+            and sink.limits.max_total_bytes <= request.limits.max_output_bytes
+            and sink.limits.max_artifact_bytes <= request.limits.max_output_bytes
+            and sink.limits.max_total_bytes <= self.config.max_output_artifact_bytes
+            and sink.limits.max_artifact_bytes <= self.config.max_output_artifact_bytes
+        )
+
+    def _headers(self, grant: str) -> dict[str, str]:
+        return {
+            "authorization": f"Bearer {self.config.internal_token}",
+            "x-ai-output-artifact-grant": grant,
+        }
+
+
+async def file_metadata(path: Path) -> tuple[int, str]:
+    digest = hashlib.sha256()
+    size = 0
+    with path.open("rb") as source:
+        while chunk := await asyncio.to_thread(
+            source.read, SpeechOutputArtifactClient.part_bytes
+        ):
+            size += len(chunk)
+            digest.update(chunk)
+    return size, digest.hexdigest()

package/template/apps/speech-server/src/southwind_speech_server/output_validation.py

@@ -8,7 +8,10 @@ def canonicalize_output(
     value: JsonValue,
     duration_ms: int,
     max_units: int,
+    variant: str = "transcribe",
 ) -> JsonValue:
+    if variant == "translate":
+        return canonicalize_translation(value, duration_ms, max_units)
     if not isinstance(value, dict):
         raise invalid_output("Speech 输出缺少分段")
     segments = value.get("segments")
@@ -71,6 +74,57 @@ def canonicalize_output(
     return result
 
 
+def canonicalize_translation(
+    value: JsonValue, duration_ms: int, max_units: int
+) -> JsonValue:
+    if not isinstance(value, dict):
+        raise invalid_output("Speech 翻译输出缺少分段")
+    original_segments = value.get("segments")
+    if not isinstance(original_segments, list):
+        raise invalid_output("Speech 翻译输出缺少分段")
+    source = canonicalize_output(
+        {
+            "language": value.get("sourceLanguage"),
+            "segments": [
+                {
+                    "text": item.get("source") if isinstance(item, dict) else None,
+                    "startMs": item.get("startMs") if isinstance(item, dict) else None,
+                    "endMs": item.get("endMs") if isinstance(item, dict) else None,
+                    "words": item.get("words") if isinstance(item, dict) else None,
+                }
+                for item in original_segments
+            ],
+            "metadata": value.get("metadata", {}),
+        },
+        duration_ms,
+        max_units,
+    )
+    assert isinstance(source, dict)
+    segments = source.get("segments")
+    assert isinstance(segments, list)
+    translated: list[JsonValue] = []
+    for original, normalized in zip(original_segments, segments, strict=True):
+        if not isinstance(original, dict) or not isinstance(normalized, dict):
+            raise invalid_output("Speech 翻译分段无效")
+        translation = original.get("translation")
+        if not isinstance(translation, str) or not translation.strip():
+            raise invalid_output("Speech 翻译文本无效")
+        translated.append(
+            {
+                **normalized,
+                "source": normalized.pop("text"),
+                "translation": translation,
+            }
+        )
+    return {
+        "durationMs": duration_ms,
+        "sourceLanguage": value.get("sourceLanguage"),
+        "targetLanguage": value.get("targetLanguage"),
+        "segments": translated,
+        "metadata": source.get("metadata", {}),
+    }
+
+
 def canonicalize_words(
     value: JsonValue, segment_start: int, segment_end: int
 ) -> JsonValue:

package/template/apps/speech-server/src/southwind_speech_server/pin_cli.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import Awaitable, Callable
+
+import httpx
+
+from .config import SpeechRuntimeConfig
+from .readiness_contracts import (
+    AdapterSpeechReadinessV1,
+    OutputArtifactSinkReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+)
+from .readiness_http import get_json
+from .readiness_local import SpeechLocalReadiness, probe_local_tools
+
+
+async def compute_pins(
+    config: SpeechRuntimeConfig,
+    adapter_transport: httpx.AsyncBaseTransport | None = None,
+    sink_transport: httpx.AsyncBaseTransport | None = None,
+    local_probe: Callable[[float], Awaitable[SpeechLocalReadiness]] = probe_local_tools,
+) -> dict[str, str]:
+    if not config.deployment_key or not config.deployment_identity:
+        raise ValueError("Speech deployment key/identity 缺失")
+    tools = await local_probe(config.readiness_timeout_seconds)
+    adapter = None
+    if config.adapter_url:
+        adapter = AdapterSpeechReadinessV1.model_validate(
+            await get_json(
+                f"{config.adapter_url.rstrip('/')}/v1/speech/readiness",
+                config.adapter_token,
+                config.readiness_timeout_seconds,
+                adapter_transport,
+            )
+        )
+    sink = OutputArtifactSinkReadinessV1.model_validate(
+        await get_json(
+            f"{config.output_artifact_url.rstrip('/')}/health/ready",
+            config.internal_token,
+            config.readiness_timeout_seconds,
+            sink_transport,
+        )
+    )
+    offers = final_offers(config, adapter, sink, tools)
+    configured = set(config.capabilities)
+    runtime_owned = {"speech.normalize", "speech.output-artifact.v1"}
+    if not offers or any(
+        not capabilities(offer).difference(runtime_owned).issubset(configured)
+        for offer in offers
+    ):
+        raise ValueError("Speech full offers 超出 Runtime 配置")
+    return {
+        "deploymentKey": config.deployment_key,
+        "deploymentIdentity": config.deployment_identity,
+        "releaseDigest": compute_release_digest(adapter, sink, tools),
+        "offersDigest": compute_offers_digest(offers),
+    }
+
+
+def capabilities(offer: dict[str, object]) -> set[str]:
+    value = offer.get("capabilities")
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ValueError("Speech full offer capabilities 无效")
+    return set(value)
+
+
+async def main() -> None:
+    try:
+        pins = await compute_pins(
+            SpeechRuntimeConfig.from_environment(dict(os.environ))
+        )
+    except Exception as error:
+        raise SystemExit("Speech readiness full probe 未通过，未写入 pins") from error
+    print(json.dumps(pins, separators=(",", ":"), sort_keys=True))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/template/apps/speech-server/src/southwind_speech_server/readiness.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+import httpx
+from pydantic import ValidationError
+
+from .config import SpeechRuntimeConfig
+from .contracts import StartSpeechRunRequest
+from .readiness_contracts import (
+    AdapterSpeechReadinessV1,
+    OutputArtifactSinkReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+)
+from .readiness_http import ProbeFailure, ProbeFailureCode, get_json
+from .readiness_local import SpeechLocalReadiness, probe_local_tools
+from .readiness_support import (
+    canonical_time,
+    latency_ms,
+    not_configured,
+    sink_matches_snapshot,
+    stale_snapshot,
+    string_list,
+    supports_offer,
+)
+
+type Snapshot = dict[str, object]
+type LocalProbe = Callable[[float], Awaitable[SpeechLocalReadiness]]
+
+
+@dataclass(frozen=True)
+class SpeechReadinessInspection:
+    snapshot: Snapshot
+    offers: tuple[dict[str, object], ...] = ()
+    valid_until: datetime | None = None
+
+    @property
+    def ready(self) -> bool:
+        return self.snapshot.get("status") == "ready" and bool(self.offers)
+
+
+class SpeechReadinessProbe:
+    def __init__(
+        self,
+        config: SpeechRuntimeConfig,
+        adapter_transport: httpx.AsyncBaseTransport | None = None,
+        sink_transport: httpx.AsyncBaseTransport | None = None,
+        local_probe: LocalProbe = probe_local_tools,
+        wall_clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+        monotonic_clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.config = config
+        self.adapter_transport = adapter_transport
+        self.sink_transport = sink_transport or adapter_transport
+        self.local_probe = local_probe
+        self.wall_clock = wall_clock
+        self.monotonic_clock = monotonic_clock
+        self._full_pin_attested = False
+        self._attested_tools: SpeechLocalReadiness | None = None
+        self._attested_adapter: AdapterSpeechReadinessV1 | None = None
+        self._attested_sink: OutputArtifactSinkReadinessV1 | None = None
+
+    async def inspect(self) -> SpeechReadinessInspection:
+        checked_at = self._now()
+        started = self.monotonic_clock()
+        if not self.config.readiness_configured:
+            return SpeechReadinessInspection(not_configured(canonical_time(checked_at)))
+        try:
+            async with asyncio.timeout(self.config.readiness_timeout_seconds):
+                tools = await self.local_probe(self.config.readiness_timeout_seconds)
+                adapter, sink = await asyncio.gather(
+                    self._optional_adapter(), self._optional_sink()
+                )
+                offers = final_offers(self.config, adapter, sink, tools)
+                self._validate_runtime_bounds(offers)
+                offers_digest = compute_offers_digest(offers)
+                release_digest = compute_release_digest(adapter, sink, tools)
+                full_probe = sink is not None and (
+                    self.config.adapter_url is None or adapter is not None
+                )
+                if full_probe:
+                    if (
+                        offers_digest != self.config.offers_digest
+                        or release_digest != self.config.release_digest
+                    ):
+                        raise ProbeFailure("INVALID_RESPONSE", False)
+                    self._full_pin_attested = True
+                    self._attested_tools = tools
+                    self._attested_adapter = adapter
+                    self._attested_sink = sink
+                elif not self._full_pin_attested:
+                    raise ProbeFailure("RESOURCE_UNAVAILABLE", True)
+                elif (
+                    tools != self._attested_tools
+                    or (adapter is not None and adapter != self._attested_adapter)
+                    or (sink is not None and sink != self._attested_sink)
+                ):
+                    raise ProbeFailure("INVALID_RESPONSE", False)
+        except TimeoutError:
+            return self._failed(checked_at, started, "TIMEOUT", True)
+        except httpx.TimeoutException:
+            return self._failed(checked_at, started, "TIMEOUT", True)
+        except httpx.ConnectError:
+            return self._failed(checked_at, started, "CONNECTION_FAILED", True)
+        except httpx.HTTPError:
+            return self._failed(checked_at, started, "CONNECTION_FAILED", True)
+        except ProbeFailure as failure:
+            return self._failed(checked_at, started, failure.code, failure.retryable)
+        except (ValidationError, ValueError, KeyError, TypeError, AssertionError):
+            return self._failed(checked_at, started, "INVALID_RESPONSE", False)
+
+        observed_at = self._now()
+        valid_until = checked_at + timedelta(seconds=self.config.readiness_ttl_seconds)
+        deployment = self._deployment(release_digest, offers_digest)
+        if observed_at >= valid_until:
+            return SpeechReadinessInspection(
+                stale_snapshot(checked_at, observed_at, valid_until, deployment)
+            )
+        checked = canonical_time(checked_at)
+        snapshot: Snapshot = {
+            "schemaVersion": 1,
+            "status": "ready",
+            "configured": True,
+            "runtimeKind": "speech",
+            "observedAt": canonical_time(observed_at),
+            "downstreamProbe": {
+                "status": "passed",
+                "checkedAt": checked,
+                "validUntil": canonical_time(valid_until),
+                "latencyMs": latency_ms(started, self.monotonic_clock()),
+                "deploymentIdentity": deployment["identity"],
+                "releaseDigest": deployment["releaseDigest"],
+                "offersDigest": deployment["offersDigest"],
+            },
+            "deployment": deployment,
+            "offers": offers,
+            "unavailableReasons": [],
+        }
+        return SpeechReadinessInspection(snapshot, tuple(offers), valid_until)
+
+    def supports(
+        self,
+        inspection: SpeechReadinessInspection,
+        request: StartSpeechRunRequest,
+    ) -> bool:
+        if (
+            not inspection.ready
+            or inspection.valid_until is None
+            or self._now() >= inspection.valid_until
+        ):
+            return False
+        sink = request.output_artifact_sink
+        if sink and not sink_matches_snapshot(sink, inspection.snapshot):
+            return False
+        inputs = {
+            "video" if request.source.media_type.startswith("video/") else "audio"
+        }
+        outputs = {"audio" if request.effective_variant == "normalize" else "text"}
+        for offer in inspection.offers:
+            if offer.get("variant") != request.effective_variant:
+                continue
+            if supports_offer(offer, request, inputs, outputs):
+                return not sink or (
+                    sink.limits.max_artifact_bytes
+                    <= self.config.max_output_artifact_bytes
+                    and sink.limits.max_total_bytes
+                    <= self.config.max_output_artifact_bytes
+                )
+        return False
+
+    async def _optional_adapter(self) -> AdapterSpeechReadinessV1 | None:
+        if not self.config.adapter_url:
+            return None
+        try:
+            value = await get_json(
+                f"{self.config.adapter_url.rstrip('/')}/v1/speech/readiness",
+                self.config.adapter_token,
+                self.config.readiness_timeout_seconds,
+                self.adapter_transport,
+            )
+            return AdapterSpeechReadinessV1.model_validate(value)
+        except (ProbeFailure, ValidationError, httpx.HTTPError):
+            return None
+
+    async def _optional_sink(self) -> OutputArtifactSinkReadinessV1 | None:
+        try:
+            value = await get_json(
+                f"{self.config.output_artifact_url.rstrip('/')}/health/ready",
+                self.config.internal_token,
+                self.config.readiness_timeout_seconds,
+                self.sink_transport,
+            )
+            return OutputArtifactSinkReadinessV1.model_validate(value)
+        except (ProbeFailure, ValidationError, httpx.HTTPError):
+            return None
+
+    def _validate_runtime_bounds(self, offers: list[dict[str, object]]) -> None:
+        configured = set(self.config.capabilities)
+        runtime_owned = {"speech.normalize", "speech.output-artifact.v1"}
+        for current in offers:
+            capabilities = set(string_list(current["capabilities"]))
+            if not (capabilities - runtime_owned).issubset(configured):
+                raise ProbeFailure("INVALID_RESPONSE", False)
+        if not offers:
+            raise ProbeFailure("RESOURCE_UNAVAILABLE", True)
+
+    def _deployment(self, release_digest: str, offers_digest: str) -> dict[str, str]:
+        values = (
+            self.config.deployment_key,
+            self.config.deployment_identity,
+            self.config.release_digest,
+            self.config.offers_digest,
+        )
+        if not all(values):
+            raise ValueError("Speech readiness 配置缺失")
+        return {
+            "key": str(values[0]),
+            "identity": str(values[1]),
+            "releaseDigest": release_digest,
+            "offersDigest": offers_digest,
+        }
+
+    def _failed(
+        self,
+        checked_at: datetime,
+        started: float,
+        code: ProbeFailureCode,
+        retryable: bool,
+    ) -> SpeechReadinessInspection:
+        return SpeechReadinessInspection(
+            {
+                "schemaVersion": 1,
+                "status": "unavailable",
+                "configured": True,
+                "runtimeKind": "speech",
+                "observedAt": canonical_time(self._now()),
+                "downstreamProbe": {
+                    "status": "failed",
+                    "checkedAt": canonical_time(checked_at),
+                    "latencyMs": latency_ms(started, self.monotonic_clock()),
+                    "failureCode": code,
+                    "retryable": retryable,
+                },
+                "deployment": None,
+                "offers": [],
+                "unavailableReasons": [
+                    {
+                        "code": "DOWNSTREAM_PROBE_FAILED",
+                        "retryable": retryable,
+                        "subject": code,
+                    }
+                ],
+            }
+        )
+
+    def _now(self) -> datetime:
+        value = self.wall_clock()
+        if value.tzinfo is None:
+            raise ValueError("Speech readiness wall clock 缺少时区")
+        return value.astimezone(UTC)