create-windy 0.5.2 → 0.6.1

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

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from typing import Literal, Self
+
+from pydantic import Field, field_validator, model_validator
+
+from .config import SpeechRuntimeConfig
+from .contracts import CanonicalModel
+from .readiness_local import SpeechLocalReadiness
+
+SPEECH_NORMALIZE_CAPABILITY_V1 = "speech.normalize"
+SPEECH_OUTPUT_ARTIFACT_CAPABILITY_V1 = "speech.output-artifact.v1"
+SPEECH_RUNTIME_RELEASE_COMPONENT_V1 = "southwind-speech-runtime/readiness-v1"
+MAX_SAFE_INTEGER_V1 = 2**53 - 1
+_STABLE_KEY = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$")
+_IDENTITY = re.compile(
+    r"^windy-deployment-v1_[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-"
+    r"[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
+)
+_DIGEST = re.compile(r"^sha256:[a-f0-9]{64}$")
+_LIMIT_KEYS = (
+    "maxDurationSeconds",
+    "maxInputBytes",
+    "maxOutputBytes",
+    "maxUnits",
+    "maxMediaDurationSeconds",
+    "maxArtifacts",
+    "maxPixelsPerArtifact",
+    "maxConcurrentRuns",
+    "maxQueueDepth",
+)
+type Modality = Literal["text", "image", "audio", "video", "document", "embedding"]
+
+
+class SpeechReadinessLimitsV1(CanonicalModel):
+    max_duration_seconds: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_input_bytes: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_output_bytes: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_units: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_media_duration_seconds: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_artifacts: int = Field(default=1, ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_concurrent_runs: int = Field(ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_queue_depth: int = Field(ge=0, le=MAX_SAFE_INTEGER_V1)
+
+    @field_validator("*", mode="before")
+    @classmethod
+    def normalize_integer_numbers(cls, value: object) -> object:
+        if isinstance(value, float) and math.isfinite(value) and value.is_integer():
+            return int(value)
+        return value
+
+
+class AdapterSpeechOfferV1(CanonicalModel):
+    variant: Literal["transcribe", "translate"]
+    capability_version: str = Field(pattern=_STABLE_KEY.pattern)
+    capabilities: list[str] = Field(min_length=1, max_length=30)
+    input_modalities: list[Modality] = Field(min_length=1, max_length=6)
+    output_modalities: list[Modality] = Field(min_length=1, max_length=6)
+    limits: SpeechReadinessLimitsV1
+
+    @model_validator(mode="after")
+    def validate_atomic_offer(self) -> Self:
+        if any(not _STABLE_KEY.fullmatch(value) for value in self.capabilities):
+            raise ValueError("Speech Adapter capability key 无效")
+        forbidden = {
+            SPEECH_NORMALIZE_CAPABILITY_V1,
+            SPEECH_OUTPUT_ARTIFACT_CAPABILITY_V1,
+        }
+        if forbidden.intersection(self.capabilities):
+            raise ValueError("Speech Adapter 不得声明 Runtime capability")
+        if len(self.capabilities) != len(set(self.capabilities)):
+            raise ValueError("Speech Adapter capability 重复")
+        if set(self.input_modalities) != {"audio"}:
+            raise ValueError("Speech Adapter 只接受归一化音频")
+        if set(self.output_modalities) != {"text"}:
+            raise ValueError("Speech Adapter 输出必须是文本")
+        return self
+
+
+class AdapterSpeechDeploymentV1(CanonicalModel):
+    identity: str = Field(pattern=_IDENTITY.pattern)
+    release_digest: str = Field(pattern=_DIGEST.pattern)
+
+
+class AdapterSpeechReadinessV1(CanonicalModel):
+    contract_version: Literal[1]
+    status: Literal["ready"]
+    runtime_kind: Literal["speech-adapter"]
+    deployment: AdapterSpeechDeploymentV1
+    offers: list[AdapterSpeechOfferV1] = Field(min_length=1, max_length=2)
+
+    @model_validator(mode="after")
+    def validate_variants(self) -> Self:
+        variants = [offer.variant for offer in self.offers]
+        if len(variants) != len(set(variants)):
+            raise ValueError("Speech Adapter variant 重复")
+        return self
+
+
+class OutputArtifactSinkDeploymentV1(CanonicalModel):
+    identity: str = Field(pattern=_IDENTITY.pattern)
+    release_digest: str = Field(pattern=_DIGEST.pattern)
+    protocol_version: Literal[1]
+
+
+class OutputArtifactSinkReadinessV1(CanonicalModel):
+    contract_version: Literal[1]
+    status: Literal["ready"]
+    capability: Literal["document.output-artifact.v1"]
+    sink: OutputArtifactSinkDeploymentV1
+
+
+def final_offers(
+    config: SpeechRuntimeConfig,
+    adapter: AdapterSpeechReadinessV1 | None,
+    sink: OutputArtifactSinkReadinessV1 | None,
+    tools: SpeechLocalReadiness,
+) -> list[dict[str, object]]:
+    # Callers may only construct offers after a successful executable probe.
+    del tools
+    offers: list[dict[str, object]] = []
+    if sink:
+        offers.append(
+            offer(
+                config,
+                "normalize",
+                [SPEECH_NORMALIZE_CAPABILITY_V1, SPEECH_OUTPUT_ARTIFACT_CAPABILITY_V1],
+                ["audio", "video"],
+                ["audio"],
+                config.max_output_artifact_bytes,
+            )
+        )
+    if adapter:
+        for downstream in adapter.offers:
+            limits = downstream.limits
+            current = offer(
+                config,
+                downstream.variant,
+                [SPEECH_NORMALIZE_CAPABILITY_V1, *downstream.capabilities],
+                ["audio", "video"],
+                ["text"],
+                min(config.max_inline_output_bytes, limits.max_output_bytes),
+            )
+            bounded = current["limits"]
+            assert isinstance(bounded, dict)
+            bounded.update(
+                {
+                    "maxDurationSeconds": min(
+                        int(config.request_timeout_seconds),
+                        limits.max_duration_seconds,
+                    ),
+                    "maxInputBytes": min(
+                        config.max_input_artifact_bytes, limits.max_input_bytes
+                    ),
+                    "maxUnits": min(config.max_units, limits.max_units),
+                    "maxMediaDurationSeconds": min(
+                        config.max_media_duration_seconds,
+                        limits.max_media_duration_seconds,
+                    ),
+                    "maxConcurrentRuns": min(
+                        config.max_concurrent_runs, limits.max_concurrent_runs
+                    ),
+                    "maxQueueDepth": min(
+                        config.max_queue_depth, limits.max_queue_depth
+                    ),
+                }
+            )
+            offers.append(current)
+    return offers
+
+
+def offer(
+    config: SpeechRuntimeConfig,
+    variant: str,
+    capabilities: list[str],
+    inputs: list[str],
+    outputs: list[str],
+    max_output_bytes: int,
+) -> dict[str, object]:
+    return {
+        "variant": variant,
+        "capabilities": capabilities,
+        "inputModalities": inputs,
+        "outputModalities": outputs,
+        "limits": {
+            "maxDurationSeconds": int(config.request_timeout_seconds),
+            "maxInputBytes": config.max_input_artifact_bytes,
+            "maxOutputBytes": max_output_bytes,
+            "maxUnits": config.max_units,
+            "maxMediaDurationSeconds": config.max_media_duration_seconds,
+            "maxArtifacts": 1,
+            "maxConcurrentRuns": config.max_concurrent_runs,
+            "maxQueueDepth": config.max_queue_depth,
+        },
+    }
+
+
+def compute_offers_digest(offers: list[dict[str, object]]) -> str:
+    if not 0 < len(offers) <= 3:
+        raise ValueError("Speech readiness offer 数量无效")
+    canonical = sorted(
+        (canonical_offer(item) for item in offers),
+        key=lambda item: str(item.get("variant")),
+    )
+    variants = [item.get("variant") for item in canonical]
+    if len(variants) != len(set(variants)):
+        raise ValueError("Speech readiness variant 重复")
+    encoded = json.dumps(canonical, ensure_ascii=False, separators=(",", ":")).encode()
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
+
+
+def canonical_offer(value: dict[str, object]) -> dict[str, object]:
+    limits = value.get("limits")
+    capabilities = value.get("capabilities")
+    inputs = value.get("inputModalities")
+    outputs = value.get("outputModalities")
+    if (
+        not isinstance(limits, dict)
+        or not isinstance(capabilities, list)
+        or not isinstance(inputs, list)
+        or not isinstance(outputs, list)
+    ):
+        raise ValueError("Speech readiness offer 无效")
+    return {
+        "variant": value.get("variant"),
+        "capabilities": sorted(capabilities),
+        "inputModalities": sorted(inputs),
+        "outputModalities": sorted(outputs),
+        "limits": {key: limits[key] for key in _LIMIT_KEYS if key in limits},
+    }
+
+
+def compute_release_digest(
+    adapter: AdapterSpeechReadinessV1 | None,
+    sink: OutputArtifactSinkReadinessV1 | None,
+    tools: SpeechLocalReadiness,
+) -> str:
+    capability_versions: list[dict[str, str]] = []
+    if adapter:
+        capability_versions = sorted(
+            [
+                {
+                    "variant": item.variant,
+                    "capabilityVersion": item.capability_version,
+                }
+                for item in adapter.offers
+            ],
+            key=lambda item: item["variant"],
+        )
+    payload = {
+        "adapter": (
+            {
+                "deployment": adapter.deployment.model_dump(by_alias=True),
+                "capabilityVersions": capability_versions,
+            }
+            if adapter
+            else None
+        ),
+        "outputArtifactSink": sink.sink.model_dump(by_alias=True) if sink else None,
+        "runtimeRelease": SPEECH_RUNTIME_RELEASE_COMPONENT_V1,
+        "tools": [tools.ffmpeg.__dict__, tools.ffprobe.__dict__],
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"

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

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from typing import Literal, cast
+
+import httpx
+
+MAX_READINESS_BODY_BYTES = 64 * 1024
+type ProbeFailureCode = Literal[
+    "AUTHENTICATION_FAILED",
+    "CONNECTION_FAILED",
+    "INVALID_RESPONSE",
+    "RESOURCE_UNAVAILABLE",
+    "TIMEOUT",
+    "UNHEALTHY",
+]
+
+
+class ProbeFailure(Exception):
+    def __init__(self, code: ProbeFailureCode, retryable: bool) -> None:
+        super().__init__(code)
+        self.code = code
+        self.retryable = retryable
+
+
+async def get_json(
+    url: str,
+    token: str | None,
+    timeout_seconds: float,
+    transport: httpx.AsyncBaseTransport | None,
+) -> object:
+    headers = {"authorization": f"Bearer {token}"} if token else {}
+    async with httpx.AsyncClient(
+        timeout=httpx.Timeout(timeout_seconds),
+        transport=transport,
+        follow_redirects=False,
+    ) as client:
+        async with client.stream("GET", url, headers=headers) as response:
+            if response.status_code != 200:
+                raise response_failure(response.status_code)
+            media_type = response.headers.get("content-type", "").split(";", 1)[0]
+            if media_type.strip().lower() != "application/json":
+                raise ProbeFailure("INVALID_RESPONSE", False)
+            if response.headers.get("content-encoding"):
+                raise ProbeFailure("INVALID_RESPONSE", False)
+            declared = response.headers.get("content-length")
+            if declared and (
+                not declared.isdigit() or int(declared) > MAX_READINESS_BODY_BYTES
+            ):
+                raise ProbeFailure("INVALID_RESPONSE", False)
+            body = bytearray()
+            async for chunk in response.aiter_bytes():
+                if len(chunk) > MAX_READINESS_BODY_BYTES - len(body):
+                    raise ProbeFailure("INVALID_RESPONSE", False)
+                body.extend(chunk)
+            if declared and int(declared) != len(body):
+                raise ProbeFailure("INVALID_RESPONSE", False)
+    try:
+        return cast(
+            object,
+            json.loads(
+                body.decode("utf-8"),
+                object_pairs_hook=unique_object,
+                parse_constant=reject_constant,
+            ),
+        )
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError, RecursionError):
+        raise ProbeFailure("INVALID_RESPONSE", False) from None
+
+
+def response_failure(status: int) -> ProbeFailure:
+    if status in {401, 403}:
+        return ProbeFailure("AUTHENTICATION_FAILED", False)
+    if status in {408, 504}:
+        return ProbeFailure("TIMEOUT", True)
+    if status == 429 or status >= 500:
+        return ProbeFailure("RESOURCE_UNAVAILABLE", True)
+    return ProbeFailure("UNHEALTHY", False)
+
+
+def unique_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate key")
+        result[key] = value
+    return result
+
+
+def reject_constant(_value: str) -> object:
+    raise ValueError("non-finite number")

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

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from .readiness_http import ProbeFailure
+
+MAX_SYNTHETIC_WAV_BYTES = 64 * 1024
+MAX_PROBE_OUTPUT_BYTES = 16 * 1024
+MAX_PROBE_STDERR_BYTES = 16 * 1024
+type ToolRunner = Callable[[list[str], bytes, float, int], Awaitable[bytes]]
+
+
+@dataclass(frozen=True)
+class LocalToolFact:
+    name: str
+    probe_fact: str
+    output_digest: str
+
+
+@dataclass(frozen=True)
+class SpeechLocalReadiness:
+    ffmpeg: LocalToolFact
+    ffprobe: LocalToolFact
+
+
+async def probe_local_tools(
+    timeout_seconds: float,
+    runner: ToolRunner | None = None,
+) -> SpeechLocalReadiness:
+    execute = runner or run_bounded
+    wav = await execute(
+        [
+            "ffmpeg",
+            "-nostdin",
+            "-v",
+            "error",
+            "-f",
+            "lavfi",
+            "-i",
+            "sine=frequency=1000:duration=0.05",
+            "-ac",
+            "1",
+            "-ar",
+            "16000",
+            "-c:a",
+            "pcm_s16le",
+            "-f",
+            "wav",
+            "pipe:1",
+        ],
+        b"",
+        timeout_seconds,
+        MAX_SYNTHETIC_WAV_BYTES,
+    )
+    if len(wav) <= 44 or not wav.startswith(b"RIFF") or wav[8:12] != b"WAVE":
+        raise ProbeFailure("INVALID_RESPONSE", False)
+    probe = await execute(
+        [
+            "ffprobe",
+            "-v",
+            "error",
+            "-show_entries",
+            "stream=codec_name,sample_rate,channels",
+            "-of",
+            "json",
+            "-i",
+            "pipe:0",
+        ],
+        wav,
+        timeout_seconds,
+        MAX_PROBE_OUTPUT_BYTES,
+    )
+    fact = parse_probe_fact(probe)
+    return SpeechLocalReadiness(
+        ffmpeg=LocalToolFact("ffmpeg", "synthetic-wav/pcm_s16le/16000/1", digest(wav)),
+        ffprobe=LocalToolFact("ffprobe", fact, digest(probe)),
+    )
+
+
+async def run_bounded(
+    arguments: list[str],
+    stdin: bytes,
+    timeout_seconds: float,
+    max_stdout_bytes: int,
+) -> bytes:
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *arguments,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+    except OSError:
+        raise ProbeFailure("RESOURCE_UNAVAILABLE", True) from None
+    try:
+        async with asyncio.timeout(max(0.1, timeout_seconds)):
+            if process.stdin:
+                process.stdin.write(stdin)
+                await process.stdin.drain()
+                process.stdin.close()
+            if not process.stdout or not process.stderr:
+                raise ProbeFailure("RESOURCE_UNAVAILABLE", True)
+            stdout, _stderr, returncode = await asyncio.gather(
+                read_limited(process.stdout, max_stdout_bytes),
+                read_limited(process.stderr, MAX_PROBE_STDERR_BYTES),
+                process.wait(),
+            )
+    except TimeoutError:
+        await terminate(process)
+        raise ProbeFailure("TIMEOUT", True) from None
+    except asyncio.CancelledError:
+        await terminate(process)
+        raise
+    except ProbeFailure:
+        await terminate(process)
+        raise
+    if returncode != 0 or not stdout:
+        raise ProbeFailure("RESOURCE_UNAVAILABLE", True)
+    return stdout
+
+
+async def read_limited(
+    stream: asyncio.StreamReader,
+    maximum: int,
+) -> bytes:
+    body = bytearray()
+    while chunk := await stream.read(min(4096, maximum + 1)):
+        if len(chunk) > maximum - len(body):
+            raise ProbeFailure("INVALID_RESPONSE", False)
+        body.extend(chunk)
+    return bytes(body)
+
+
+async def terminate(process: asyncio.subprocess.Process) -> None:
+    if process.returncode is None:
+        process.kill()
+    try:
+        await asyncio.wait_for(process.wait(), timeout=0.25)
+    except TimeoutError:
+        pass
+
+
+def parse_probe_fact(output: bytes) -> str:
+    try:
+        value = json.loads(output.decode("utf-8"))
+        streams = value["streams"]
+        stream = streams[0]
+        fact = f"{stream['codec_name']}/{stream['sample_rate']}/{stream['channels']}"
+    except (UnicodeDecodeError, json.JSONDecodeError, KeyError, IndexError, TypeError):
+        raise ProbeFailure("INVALID_RESPONSE", False) from None
+    if fact != "pcm_s16le/16000/1":
+        raise ProbeFailure("INVALID_RESPONSE", False)
+    return fact
+
+
+def digest(value: bytes) -> str:
+    return f"sha256:{hashlib.sha256(value).hexdigest()}"

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

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from .contracts import StartSpeechRunRequest
+
+type Snapshot = dict[str, object]
+
+
+def supports_offer(
+    offer: dict[str, object],
+    request: StartSpeechRunRequest,
+    inputs: set[str],
+    outputs: set[str],
+) -> bool:
+    limits = offer.get("limits")
+    return bool(
+        isinstance(limits, dict)
+        and set(request.required_capabilities).issubset(
+            set(string_list(offer["capabilities"]))
+        )
+        and inputs.issubset(set(string_list(offer["inputModalities"])))
+        and outputs.issubset(set(string_list(offer["outputModalities"])))
+        and number(limits, "maxDurationSeconds") >= request.limits.max_duration_seconds
+        and number(limits, "maxInputBytes") >= request.limits.max_input_bytes
+        and number(limits, "maxOutputBytes") >= request.limits.max_output_bytes
+        and number(limits, "maxUnits") >= request.limits.max_units
+        and number(limits, "maxMediaDurationSeconds")
+        >= request.limits.max_media_duration_seconds
+    )
+
+
+def sink_matches_snapshot(sink: object, snapshot: Snapshot) -> bool:
+    deployment = snapshot.get("deployment")
+    return bool(
+        isinstance(deployment, dict)
+        and getattr(sink, "deployment_identity", None) == deployment.get("identity")
+        and getattr(sink, "release_digest", None)
+        == deployment.get("pinnedReleaseDigest", deployment.get("releaseDigest"))
+        and getattr(sink, "offers_digest", None)
+        == deployment.get("pinnedOffersDigest", deployment.get("offersDigest"))
+    )
+
+
+def not_configured(observed_at: str) -> Snapshot:
+    return {
+        "schemaVersion": 1,
+        "status": "unavailable",
+        "configured": False,
+        "runtimeKind": "speech",
+        "observedAt": observed_at,
+        "downstreamProbe": {"status": "not-run", "reason": "NOT_CONFIGURED"},
+        "deployment": None,
+        "offers": [],
+        "unavailableReasons": [{"code": "RUNTIME_NOT_CONFIGURED", "retryable": True}],
+    }
+
+
+def stale_snapshot(
+    checked_at: datetime,
+    observed_at: datetime,
+    valid_until: datetime,
+    deployment: dict[str, str],
+) -> Snapshot:
+    return {
+        "schemaVersion": 1,
+        "status": "unavailable",
+        "configured": True,
+        "runtimeKind": "speech",
+        "observedAt": canonical_time(observed_at),
+        "downstreamProbe": {
+            "status": "passed",
+            "checkedAt": canonical_time(checked_at),
+            "validUntil": canonical_time(valid_until),
+            "latencyMs": 0,
+            "deploymentIdentity": deployment["identity"],
+            "releaseDigest": deployment["releaseDigest"],
+            "offersDigest": deployment["offersDigest"],
+            "pinnedReleaseDigest": deployment["pinnedReleaseDigest"],
+            "pinnedOffersDigest": deployment["pinnedOffersDigest"],
+        },
+        "deployment": deployment,
+        "offers": [],
+        "unavailableReasons": [{"code": "PROBE_STALE", "retryable": True}],
+    }
+
+
+def canonical_time(value: datetime) -> str:
+    return (
+        value.astimezone(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+    )
+
+
+def latency_ms(started: float, finished: float) -> int:
+    return max(0, round((finished - started) * 1000))
+
+
+def string_list(value: object) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ValueError("Speech readiness list 无效")
+    return value
+
+
+def number(value: dict[str, object], key: str) -> int:
+    item = value.get(key)
+    return item if isinstance(item, int) and not isinstance(item, bool) else -1