create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import tempfile
+from pathlib import Path
+
+import httpx
+
+from .config import SpeechRuntimeConfig
+from .contracts import JsonValue, StartSpeechRunRequest
+from .errors import SafeSpeechError
+from .normalizer import AudioNormalizer, NormalizationError
+from .output_validation import canonicalize_output
+
+SUPPORTED_MEDIA_TYPES = frozenset(
+    {
+        "audio/mpeg",
+        "audio/mp4",
+        "audio/ogg",
+        "audio/wav",
+        "audio/x-wav",
+        "audio/flac",
+        "audio/webm",
+        "video/mp4",
+        "video/webm",
+    }
+)
+
+
+class SpeechAdapter:
+    def __init__(
+        self,
+        config: SpeechRuntimeConfig,
+        normalizer: AudioNormalizer | None = None,
+    ) -> None:
+        self.config = config
+        self.normalizer = normalizer or AudioNormalizer()
+
+    @property
+    def available(self) -> bool:
+        return self.config.adapter_url is not None and self.normalizer.available
+
+    async def execute(self, request: StartSpeechRunRequest) -> JsonValue:
+        if not self.config.adapter_url:
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE",
+                "Speech Adapter 未配置",
+                True,
+            )
+        if request.source.media_type.lower() not in SUPPORTED_MEDIA_TYPES:
+            raise SafeSpeechError(
+                "INVALID_INPUT",
+                "音频或视频格式不受支持",
+                False,
+            )
+        missing = set(request.required_capabilities) - set(self.config.capabilities)
+        if missing:
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE",
+                "Speech Adapter 缺少所需能力",
+                True,
+            )
+        self._authorize_deployment(request)
+        enforce_runtime_quotas(request, self.config)
+        source = await self._download(request)
+        normalized = Path(f"{source}.wav")
+        try:
+            try:
+                audio = await self.normalizer.normalize(
+                    source,
+                    normalized,
+                    request.limits.max_media_duration_seconds,
+                    request.limits.max_duration_seconds,
+                )
+            except NormalizationError as error:
+                raise SafeSpeechError(
+                    error.code,
+                    str(error),
+                    error.code == "CAPABILITY_UNAVAILABLE",
+                ) from error
+            return await self._invoke(request, audio.path, audio.duration_ms)
+        finally:
+            await remove(source)
+            await remove(normalized)
+
+    async def _download(self, request: StartSpeechRunRequest) -> Path:
+        digest = hashlib.sha256()
+        total = 0
+        with tempfile.NamedTemporaryFile(delete=False) as target:
+            path = Path(target.name)
+            try:
+                async with httpx.AsyncClient(
+                    timeout=httpx.Timeout(
+                        self.config.request_timeout_seconds,
+                        connect=self.config.connect_timeout_seconds,
+                    )
+                ) as client:
+                    async with client.stream(
+                        "GET",
+                        self.config.artifact_url,
+                        headers={
+                            "authorization": f"Bearer {self.config.internal_token}",
+                            "x-ai-artifact-ref": request.source.value,
+                        },
+                    ) as response:
+                        response.raise_for_status()
+                        async for chunk in response.aiter_bytes():
+                            total += len(chunk)
+                            if total > min(
+                                request.source.byte_size,
+                                request.limits.max_input_bytes,
+                            ):
+                                raise SafeSpeechError(
+                                    "BUDGET_EXCEEDED",
+                                    "Speech 输入超过声明上限",
+                                    False,
+                                )
+                            digest.update(chunk)
+                            target.write(chunk)
+            except SafeSpeechError:
+                await remove(path)
+                raise
+            except Exception as error:
+                await remove(path)
+                raise SafeSpeechError(
+                    "ARTIFACT_UNAVAILABLE",
+                    "Speech Runtime 无法读取 Artifact",
+                    True,
+                ) from error
+        if (
+            total != request.source.byte_size
+            or digest.hexdigest() != request.source.sha256
+        ):
+            await remove(path)
+            raise SafeSpeechError(
+                "ARTIFACT_UNAVAILABLE",
+                "Artifact 完整性校验失败",
+                False,
+            )
+        return path
+
+    async def _invoke(
+        self,
+        request: StartSpeechRunRequest,
+        path: Path,
+        duration_ms: int,
+    ) -> JsonValue:
+        adapter_url = self.config.adapter_url
+        if not adapter_url:
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE", "Speech Adapter 未配置", True
+            )
+        headers = (
+            {"authorization": f"Bearer {self.config.adapter_token}"}
+            if self.config.adapter_token
+            else {}
+        )
+        try:
+            async with httpx.AsyncClient(
+                timeout=httpx.Timeout(
+                    self.config.request_timeout_seconds,
+                    connect=self.config.connect_timeout_seconds,
+                )
+            ) as client:
+                with path.open("rb") as source:
+                    response = await client.post(
+                        f"{adapter_url.rstrip('/')}/v1/speech/transcribe",
+                        headers=headers,
+                        files={"file": ("source.wav", source, "audio/wav")},
+                        data={
+                            "operationKey": request.operation_key,
+                            "durationMs": str(duration_ms),
+                            "dataClassification": request.data_classification,
+                            "options": encode(request.options),
+                            "providerEgress": request.provider_egress.model_dump_json(
+                                by_alias=True
+                            ),
+                            "providerDataPolicy": (
+                                request.provider_data_policy.model_dump_json(
+                                    by_alias=True
+                                )
+                                if request.provider_data_policy
+                                else "null"
+                            ),
+                            "limits": request.limits.model_dump_json(by_alias=True),
+                        },
+                    )
+            response.raise_for_status()
+            if len(response.content) > request.limits.max_output_bytes:
+                raise SafeSpeechError(
+                    "BUDGET_EXCEEDED",
+                    "Speech 输出超过上限",
+                    False,
+                )
+            value: JsonValue = response.json()
+            return canonicalize_output(
+                value,
+                duration_ms,
+                request.limits.max_units,
+            )
+        except SafeSpeechError:
+            raise
+        except Exception as error:
+            raise SafeSpeechError(
+                "RUNTIME_UNAVAILABLE",
+                "Speech Adapter 执行失败",
+                True,
+            ) from error
+
+    def _authorize_deployment(self, request: StartSpeechRunRequest) -> None:
+        if request.provider_egress.mode == "forbidden":
+            return
+        if not request.provider_data_policy:
+            raise SafeSpeechError(
+                "FORBIDDEN",
+                "Speech Operation 缺少 Provider 字段治理策略",
+                False,
+            )
+        if (
+            not self.config.deployment_key
+            or request.provider_egress.deployment_key != self.config.deployment_key
+        ):
+            raise SafeSpeechError(
+                "FORBIDDEN",
+                "Speech Operation 未授权当前 Deployment",
+                False,
+            )
+
+
+def enforce_runtime_quotas(
+    request: StartSpeechRunRequest,
+    config: SpeechRuntimeConfig,
+) -> None:
+    if request.source.byte_size > request.limits.max_input_bytes:
+        raise SafeSpeechError("BUDGET_EXCEEDED", "Speech Artifact 超过输入上限", False)
+    if request.limits.max_units > config.max_units:
+        raise SafeSpeechError("BUDGET_EXCEEDED", "转写分段上限超过 Runtime 配置", False)
+    if request.limits.max_media_duration_seconds > config.max_media_duration_seconds:
+        raise SafeSpeechError("BUDGET_EXCEEDED", "媒体时长上限超过 Runtime 配置", False)
+
+
+def encode(value: object) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+
+
+async def remove(path: Path) -> None:
+    await asyncio.to_thread(path.unlink, missing_ok=True)

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

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import asyncio
+import hmac
+import os
+import uuid
+from collections.abc import AsyncIterator
+
+from fastapi import Depends, FastAPI, Header, HTTPException, Query
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+from .adapter import SpeechAdapter
+from .config import SpeechRuntimeConfig
+from .contracts import ErrorResponse, StartRunResponse, StartSpeechRunRequest
+from .errors import SafeSpeechError
+from .service import SpeechRunService
+from .store import RunConflictError, SpeechRunStore
+
+
+def create_app(config: SpeechRuntimeConfig) -> FastAPI:
+    app = FastAPI(title="Southwind Speech Runtime", docs_url=None, redoc_url=None)
+    store = SpeechRunStore(config.store_path)
+    service = SpeechRunService(SpeechAdapter(config), store)
+
+    def authorize(authorization: str | None = Header(default=None)) -> None:
+        provided = (authorization or "").removeprefix("Bearer ")
+        if not provided or not hmac.compare_digest(provided, config.internal_token):
+            raise HTTPException(status_code=403, detail="FORBIDDEN")
+
+    @app.get("/health/ready")
+    async def ready(_: None = Depends(authorize)) -> JSONResponse:
+        if not service.adapter.available:
+            return JSONResponse(
+                {"status": "unavailable", "capabilities": []},
+                status_code=503,
+            )
+        return JSONResponse(
+            {
+                "status": "ready",
+                "capabilities": list(config.capabilities),
+                "limits": {
+                    "maxUnits": config.max_units,
+                    "maxMediaDurationSeconds": config.max_media_duration_seconds,
+                },
+            }
+        )
+
+    @app.post("/api/speech/runs", status_code=202)
+    async def start(
+        request: StartSpeechRunRequest,
+        idempotency_key: str = Header(alias="idempotency-key"),
+        _: None = Depends(authorize),
+    ) -> StartRunResponse:
+        if not idempotency_key.strip() or len(idempotency_key) > 160:
+            raise HTTPException(status_code=400, detail="INVALID_INPUT")
+        try:
+            record = await service.start(request, idempotency_key)
+        except RunConflictError:
+            raise HTTPException(status_code=409, detail="RUN_CONFLICT") from None
+        return StartRunResponse(
+            run_id=record.run_id,
+            status=record.status,
+            events_url=f"/api/speech/runs/{record.run_id}/events",
+        )
+
+    @app.get("/api/speech/runs/{run_id}/events")
+    async def events(
+        run_id: str,
+        after: int = Query(default=0, ge=0),
+        _: None = Depends(authorize),
+    ) -> StreamingResponse:
+        service.require(run_id)
+
+        async def stream() -> AsyncIterator[str]:
+            cursor = after
+            for _attempt in range(30):
+                current = service.require(run_id)
+                events = store.events_after(run_id, cursor)
+                for event in events:
+                    sequence = event.get("sequence")
+                    if not isinstance(sequence, int):
+                        raise RuntimeError("Speech Event sequence 无效")
+                    cursor = sequence
+                    yield f"data: {encode_event(event)}\n\n"
+                if current.terminal:
+                    return
+                if not events:
+                    yield ": heartbeat\n\n"
+                await asyncio.sleep(1)
+
+        return StreamingResponse(stream(), media_type="text/event-stream")
+
+    @app.get("/api/speech/runs/{run_id}/result")
+    async def result(run_id: str, _: None = Depends(authorize)) -> JSONResponse:
+        record = service.require(run_id)
+        if record.status != "completed" or not isinstance(record.output, dict):
+            return JSONResponse({"code": "RUN_NOT_READY"}, status_code=409)
+        artifact = store.artifact(run_id)
+        return JSONResponse(
+            {
+                "runId": run_id,
+                "status": "completed",
+                "output": {
+                    **record.output,
+                    "artifact": {
+                        "mediaType": artifact.media_type,
+                        "byteSize": artifact.byte_size,
+                        "sha256": artifact.sha256,
+                    },
+                },
+            }
+        )
+
+    @app.get("/api/speech/runs/{run_id}/artifact")
+    async def artifact(run_id: str, _: None = Depends(authorize)) -> Response:
+        record = service.require(run_id)
+        if record.status != "completed":
+            return JSONResponse(
+                encode_error("RUN_NOT_READY", "Speech 结果尚未就绪", False),
+                status_code=409,
+            )
+        result = store.artifact(run_id)
+        return Response(
+            content=result.body,
+            media_type=result.media_type,
+            headers={
+                "content-length": str(result.byte_size),
+                "x-content-sha256": result.sha256,
+                "cache-control": "private, no-store",
+            },
+        )
+
+    @app.post("/api/speech/runs/{run_id}/cancel")
+    async def cancel(run_id: str, _: None = Depends(authorize)) -> JSONResponse:
+        record = await service.cancel(run_id)
+        return JSONResponse({"runId": run_id, "status": record.status})
+
+    @app.exception_handler(KeyError)
+    async def missing(_request: object, _error: KeyError) -> JSONResponse:
+        return safe_error("RUN_NOT_FOUND", "Speech Run 不存在", 404, False)
+
+    @app.exception_handler(HTTPException)
+    async def http_error(_request: object, error: HTTPException) -> JSONResponse:
+        code = str(error.detail)
+        return safe_error(code, "Speech 请求被拒绝", error.status_code, False)
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_error(
+        _request: object, _error: RequestValidationError
+    ) -> JSONResponse:
+        return safe_error("INVALID_INPUT", "Speech 请求格式无效", 400, False)
+
+    @app.exception_handler(SafeSpeechError)
+    async def safe_speech_error(
+        _request: object, error: SafeSpeechError
+    ) -> JSONResponse:
+        status = 403 if error.code == "FORBIDDEN" else 400
+        return safe_error(error.code, error.safe_message, status, error.retryable)
+
+    return app
+
+
+def safe_error(code: str, message: str, status: int, retryable: bool) -> JSONResponse:
+    return JSONResponse(encode_error(code, message, retryable), status_code=status)
+
+
+def encode_error(code: str, message: str, retryable: bool) -> dict[str, object]:
+    return ErrorResponse(
+        code=code,
+        message=message,
+        request_id=f"speech_{uuid.uuid4().hex}",
+        retryable=retryable,
+    ).model_dump(by_alias=True)
+
+
+def encode_event(event: dict[str, object]) -> str:
+    import json
+
+    return json.dumps(event, ensure_ascii=False, separators=(",", ":"))
+
+
+app = create_app(SpeechRuntimeConfig.from_environment(dict(os.environ)))

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

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+
+@dataclass(frozen=True)
+class SpeechRuntimeConfig:
+    internal_token: str
+    store_path: str
+    artifact_url: str
+    adapter_url: str | None
+    adapter_token: str | None
+    deployment_key: str | None
+    capabilities: tuple[str, ...]
+    max_units: int = 100_000
+    max_media_duration_seconds: int = 24 * 60 * 60
+    connect_timeout_seconds: float = 5
+    request_timeout_seconds: float = 3600
+
+    @classmethod
+    def from_environment(cls, environment: dict[str, str]) -> SpeechRuntimeConfig:
+        artifact_url = environment.get(
+            "SPEECH_ARTIFACT_URL",
+            "http://server:9747/api/internal/ai/artifacts",
+        ).strip()
+        validate_intranet_url(artifact_url)
+        adapter_url = environment.get("SPEECH_ADAPTER_URL", "").strip() or None
+        if adapter_url:
+            validate_intranet_url(adapter_url)
+        capabilities = tuple(
+            sorted(
+                {
+                    item.strip()
+                    for item in environment.get(
+                        "SPEECH_ADAPTER_CAPABILITIES",
+                        (
+                            "speech.transcribe.batch,speech.normalize,"
+                            "speech.vad,speech.timestamps"
+                        ),
+                    ).split(",")
+                    if item.strip()
+                }
+            )
+        )
+        return cls(
+            internal_token=required(environment, "SPEECH_SERVER_INTERNAL_TOKEN"),
+            store_path=environment.get(
+                "SPEECH_RUN_STORE_PATH", "/app/data/speech/runs.sqlite3"
+            ).strip(),
+            artifact_url=artifact_url,
+            adapter_url=adapter_url,
+            adapter_token=environment.get("SPEECH_ADAPTER_TOKEN", "").strip() or None,
+            deployment_key=environment.get("SPEECH_DEPLOYMENT_KEY", "").strip() or None,
+            capabilities=capabilities,
+            max_units=positive_int(environment, "SPEECH_MAX_UNITS", 100_000),
+            max_media_duration_seconds=positive_int(
+                environment,
+                "SPEECH_MAX_MEDIA_DURATION_SECONDS",
+                24 * 60 * 60,
+            ),
+        )
+
+
+def required(environment: dict[str, str], key: str) -> str:
+    value = environment.get(key, "").strip()
+    if not value:
+        raise ValueError(f"缺少 {key}")
+    return value
+
+
+def positive_int(environment: dict[str, str], key: str, default: int) -> int:
+    raw = environment.get(key, str(default)).strip()
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ValueError(f"{key} 必须是正整数") from None
+    if value <= 0:
+        raise ValueError(f"{key} 必须是正整数")
+    return value
+
+
+def validate_intranet_url(raw: str) -> None:
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("Speech 内部 URL 无效")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("Speech 内部 URL 不允许凭据、查询串或片段")
+    host = parsed.hostname.lower()
+    if host == "localhost" or host.endswith(".internal") or "." not in host:
+        return
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        raise ValueError(
+            "Speech 内部 URL 必须使用 localhost、内部服务名、私网 IP 或 .internal"
+        ) from None
+    if not (address.is_private or address.is_loopback):
+        raise ValueError("Speech 内部 URL 禁止使用公网地址")

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

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+type JsonValue = (
+    str | int | float | bool | None | list[JsonValue] | dict[str, JsonValue]
+)
+type RunStatus = Literal["accepted", "running", "completed", "failed", "cancelled"]
+
+
+def to_camel(value: str) -> str:
+    first, *rest = value.split("_")
+    return first + "".join(part.capitalize() for part in rest)
+
+
+class CanonicalModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="forbid",
+    )
+
+
+class ArtifactInput(CanonicalModel):
+    value: str = Field(min_length=1, max_length=4096)
+    media_type: str = Field(min_length=1, max_length=160)
+    byte_size: int = Field(ge=1, le=2 * 1024 * 1024 * 1024)
+    sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+class RuntimeLimits(CanonicalModel):
+    max_duration_seconds: int = Field(ge=1, le=3600)
+    max_input_bytes: int = Field(ge=1, le=2 * 1024 * 1024 * 1024)
+    max_output_bytes: int = Field(ge=1024, le=64 * 1024 * 1024)
+    max_units: int = Field(ge=1, le=100_000)
+    max_media_duration_seconds: int = Field(ge=1, le=24 * 60 * 60)
+
+
+class ProviderEgress(CanonicalModel):
+    mode: Literal["forbidden", "configured-endpoint"]
+    deployment_key: str | None = None
+
+    @model_validator(mode="after")
+    def validate_deployment(self) -> Self:
+        if self.mode == "configured-endpoint":
+            if not self.deployment_key or not self.deployment_key.strip():
+                raise ValueError("Provider Deployment Key 缺失")
+        elif self.deployment_key is not None:
+            raise ValueError("禁止出网时不能指定 Provider Deployment")
+        return self
+
+
+class ProviderFieldPolicy(CanonicalModel):
+    field: Literal["artifact-content", "provider-output"]
+    classification: Literal["public", "internal", "sensitive"]
+    dlp_action: Literal["reject", "redact"]
+
+
+class ProviderInputFieldPolicy(CanonicalModel):
+    json_pointer: str = Field(pattern=r"^/[^/]+(?:/[^/]+)*$")
+    classification: Literal["public", "internal", "sensitive"]
+    dlp_action: Literal["reject", "redact"]
+
+
+class ProviderDataPolicy(CanonicalModel):
+    input_fields: list[ProviderInputFieldPolicy] = Field(min_length=1)
+    envelope_fields: list[ProviderFieldPolicy] = Field(min_length=2)
+
+    @model_validator(mode="after")
+    def validate_fields(self) -> Self:
+        fields = [rule.field for rule in self.envelope_fields]
+        if set(fields) != {"artifact-content", "provider-output"}:
+            raise ValueError("Speech Provider 字段治理策略不完整")
+        if len(fields) != len(set(fields)):
+            raise ValueError("Speech Provider 字段治理策略重复")
+        return self
+
+
+class StartSpeechRunRequest(CanonicalModel):
+    kind: Literal["speech"]
+    operation_key: str = Field(min_length=1, max_length=160)
+    options: JsonValue
+    source: ArtifactInput
+    required_capabilities: list[str] = Field(min_length=1, max_length=32)
+    data_classification: Literal["public", "internal", "sensitive"]
+    limits: RuntimeLimits
+    provider_egress: ProviderEgress
+    provider_data_policy: ProviderDataPolicy | None = None
+
+
+class StartRunResponse(CanonicalModel):
+    run_id: str
+    status: RunStatus
+    events_url: str
+
+
+class ErrorResponse(CanonicalModel):
+    code: str
+    message: str
+    request_id: str
+    retryable: bool

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

@@ -0,0 +1,6 @@
+class SafeSpeechError(Exception):
+    def __init__(self, code: str, message: str, retryable: bool) -> None:
+        super().__init__(message)
+        self.code = code
+        self.safe_message = message
+        self.retryable = retryable