create-windy 0.5.2 → 0.6.1

package/template/apps/embedding-server/src/southwind_embedding_server/contracts.py

@@ -66,6 +66,18 @@ class ProviderDataPolicy(CanonicalModel):
     envelope_fields: list[dict[str, JsonValue]]
 
 
+class ReadinessPinV1(CanonicalModel):
+    key: str = Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$")
+    identity: str = Field(
+        pattern=(
+            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}$"
+        )
+    )
+    release_digest: str = Field(pattern=r"^sha256:[a-f0-9]{64}$")
+    offers_digest: str = Field(pattern=r"^sha256:[a-f0-9]{64}$")
+
+
 class EmbeddingRequest(CanonicalModel):
     kind: Literal["embedding"]
     operation_key: str = Field(min_length=1)
@@ -77,6 +89,7 @@ class EmbeddingRequest(CanonicalModel):
     limits: RuntimeLimits
     provider_egress: ProviderEgress
     provider_data_policy: ProviderDataPolicy | None = None
+    readiness_pin: ReadinessPinV1 | None = None
 
 
 class EmbeddingVector(CanonicalModel):

package/template/apps/embedding-server/src/southwind_embedding_server/image_input.py

@@ -4,6 +4,7 @@ import asyncio
 import base64
 import hashlib
 from io import BytesIO
+from urllib.parse import quote
 
 import httpx
 from PIL import Image, UnidentifiedImageError
@@ -20,6 +21,8 @@ async def load_image(
     config: EmbeddingConfig,
     max_bytes: int,
     max_pixels: int,
+    run_id: str | None = None,
+    item_id: str | None = None,
 ) -> tuple[str, str]:
     if source.media_type.lower() not in _IMAGE_TYPES:
         raise invalid("Embedding 图片格式不受支持")
@@ -32,13 +35,21 @@ async def load_image(
                 connect=config.connect_timeout_seconds,
             )
         ) as client:
+            url = config.artifact_url
+            headers = {
+                "authorization": f"Bearer {config.internal_token}",
+                "x-ai-artifact-ref": source.value,
+            }
+            if run_id and item_id:
+                url = (
+                    f"{config.run_artifact_url}/{quote(run_id, safe='')}"
+                    f"/artifacts/{quote(item_id, safe='')}"
+                )
+                headers.pop("x-ai-artifact-ref")
             async with client.stream(
                 "GET",
-                config.artifact_url,
-                headers={
-                    "authorization": f"Bearer {config.internal_token}",
-                    "x-ai-artifact-ref": source.value,
-                },
+                url,
+                headers=headers,
             ) as response:
                 response.raise_for_status()
                 async for chunk in response.aiter_bytes():

package/template/apps/embedding-server/src/southwind_embedding_server/pin_cli.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+
+import httpx
+
+from .config import EmbeddingConfig
+from .readiness_contracts import (
+    AdapterEmbeddingReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+)
+from .readiness_http import get_json
+
+
+async def compute_pins(
+    config: EmbeddingConfig,
+    transport: httpx.AsyncBaseTransport | None = None,
+) -> dict[str, str]:
+    if not config.deployment_key or not config.deployment_identity:
+        raise ValueError("Embedding deployment key/identity 缺失")
+    if not config.adapter_url:
+        raise ValueError("Embedding Adapter 未配置")
+    adapter = AdapterEmbeddingReadinessV1.model_validate(
+        await get_json(
+            f"{config.adapter_url.rstrip('/')}/v1/embedding/readiness",
+            config.adapter_token,
+            config.readiness_timeout_seconds,
+            transport,
+        )
+    )
+    deployment = adapter.deployment
+    if (
+        deployment.model != config.model
+        or deployment.version != config.version
+        or deployment.dimensions != config.dimensions
+        or deployment.normalized != config.normalized
+    ):
+        raise ValueError("Embedding Adapter deployment 漂移")
+    offers = final_offers(config, adapter)
+    return {
+        "deploymentKey": config.deployment_key,
+        "deploymentIdentity": config.deployment_identity,
+        "releaseDigest": compute_release_digest(adapter),
+        "offersDigest": compute_offers_digest(offers),
+    }
+
+
+async def main() -> None:
+    try:
+        pins = await compute_pins(EmbeddingConfig.from_environment(dict(os.environ)))
+    except Exception as error:
+        message = "Embedding readiness full probe 未通过，未写入 pins"
+        raise SystemExit(message) from error
+    print(json.dumps(pins, separators=(",", ":"), sort_keys=True))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/template/apps/embedding-server/src/southwind_embedding_server/readiness.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Protocol
+
+import httpx
+from pydantic import ValidationError
+
+from .config import EmbeddingConfig
+from .contracts import EmbeddingRequest
+from .readiness_contracts import (
+    AdapterEmbeddingReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+    supports_offer,
+)
+from .readiness_http import ProbeFailure, ProbeFailureCode, get_json
+
+type Snapshot = dict[str, object]
+
+
+@dataclass(frozen=True)
+class EmbeddingReadinessInspection:
+    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 EmbeddingReadinessPort(Protocol):
+    async def inspect(self) -> EmbeddingReadinessInspection: ...
+
+    def supports(
+        self,
+        inspection: EmbeddingReadinessInspection,
+        request: EmbeddingRequest,
+    ) -> bool: ...
+
+
+class EmbeddingReadinessProbe:
+    def __init__(
+        self,
+        config: EmbeddingConfig,
+        transport: httpx.AsyncBaseTransport | None = None,
+        wall_clock: Callable[[], datetime] = lambda: datetime.now(UTC),
+        monotonic_clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.config = config
+        self.transport = transport
+        self.wall_clock = wall_clock
+        self.monotonic_clock = monotonic_clock
+
+    async def inspect(self) -> EmbeddingReadinessInspection:
+        checked_at = self._now()
+        started = self.monotonic_clock()
+        adapter_url = self.config.adapter_url
+        if not self.config.readiness_configured or not adapter_url:
+            return EmbeddingReadinessInspection(self._not_configured(checked_at))
+        try:
+            async with asyncio.timeout(self.config.readiness_timeout_seconds):
+                adapter = AdapterEmbeddingReadinessV1.model_validate(
+                    await get_json(
+                        f"{adapter_url.rstrip('/')}/v1/embedding/readiness",
+                        self.config.adapter_token,
+                        self.config.readiness_timeout_seconds,
+                        self.transport,
+                    )
+                )
+                self._validate_adapter(adapter)
+                offers = final_offers(self.config, adapter)
+                offers_digest = compute_offers_digest(offers)
+                release_digest = compute_release_digest(adapter)
+                if (
+                    offers_digest != self.config.offers_digest
+                    or release_digest != self.config.release_digest
+                ):
+                    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 EmbeddingReadinessInspection(
+                self._stale(checked_at, observed_at, valid_until, deployment)
+            )
+        snapshot: Snapshot = {
+            "schemaVersion": 1,
+            "status": "ready",
+            "configured": True,
+            "runtimeKind": "embedding",
+            "observedAt": canonical_time(observed_at),
+            "downstreamProbe": {
+                "status": "passed",
+                "checkedAt": canonical_time(checked_at),
+                "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 EmbeddingReadinessInspection(snapshot, tuple(offers), valid_until)
+
+    def supports(
+        self,
+        inspection: EmbeddingReadinessInspection,
+        request: EmbeddingRequest,
+    ) -> bool:
+        pin = request.readiness_pin
+        deployment = inspection.snapshot.get("deployment")
+        if (
+            not inspection.ready
+            or inspection.valid_until is None
+            or self._now() >= inspection.valid_until
+            or not isinstance(deployment, dict)
+            or (pin is not None and pin.model_dump(by_alias=True) != deployment)
+        ):
+            return False
+        return any(supports_offer(offer, request) for offer in inspection.offers)
+
+    def _validate_adapter(self, adapter: AdapterEmbeddingReadinessV1) -> None:
+        deployment = adapter.deployment
+        if (
+            deployment.model != self.config.model
+            or deployment.version != self.config.version
+            or deployment.dimensions != self.config.dimensions
+            or deployment.normalized != self.config.normalized
+        ):
+            raise ProbeFailure("INVALID_RESPONSE", False)
+
+    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("Embedding readiness 配置缺失")
+        return {
+            "key": str(values[0]),
+            "identity": str(values[1]),
+            "releaseDigest": release_digest,
+            "offersDigest": offers_digest,
+        }
+
+    def _not_configured(self, observed_at: datetime) -> Snapshot:
+        return {
+            "schemaVersion": 1,
+            "status": "unavailable",
+            "configured": False,
+            "runtimeKind": "embedding",
+            "observedAt": canonical_time(observed_at),
+            "downstreamProbe": {"status": "not-run", "reason": "NOT_CONFIGURED"},
+            "deployment": None,
+            "offers": [],
+            "unavailableReasons": [
+                {"code": "RUNTIME_NOT_CONFIGURED", "retryable": True}
+            ],
+        }
+
+    def _failed(
+        self,
+        checked_at: datetime,
+        started: float,
+        code: ProbeFailureCode,
+        retryable: bool,
+    ) -> EmbeddingReadinessInspection:
+        return EmbeddingReadinessInspection(
+            {
+                "schemaVersion": 1,
+                "status": "unavailable",
+                "configured": True,
+                "runtimeKind": "embedding",
+                "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 _stale(
+        self,
+        checked_at: datetime,
+        observed_at: datetime,
+        valid_until: datetime,
+        deployment: dict[str, str],
+    ) -> Snapshot:
+        return {
+            "schemaVersion": 1,
+            "status": "unavailable",
+            "configured": True,
+            "runtimeKind": "embedding",
+            "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"],
+            },
+            "deployment": deployment,
+            "offers": [],
+            "unavailableReasons": [{"code": "PROBE_STALE", "retryable": True}],
+        }
+
+    def _now(self) -> datetime:
+        value = self.wall_clock()
+        if value.tzinfo is None:
+            raise ValueError("Embedding readiness wall clock 缺少时区")
+        return value.astimezone(UTC)
+
+
+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))

package/template/apps/embedding-server/src/southwind_embedding_server/readiness_contracts.py

@@ -0,0 +1,221 @@
+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 EmbeddingConfig
+from .contracts import CanonicalModel, EmbeddingRequest
+
+MAX_SAFE_INTEGER_V1 = 2**53 - 1
+EMBEDDING_RUNTIME_RELEASE_V1 = "southwind-embedding-runtime/readiness-v1"
+_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",
+    "maxArtifacts",
+    "maxPixelsPerArtifact",
+    "maxConcurrentRuns",
+    "maxQueueDepth",
+)
+type Modality = Literal["text", "image", "audio", "video", "document", "embedding"]
+
+
+class EmbeddingReadinessLimitsV1(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_artifacts: int | None = Field(default=None, ge=1, le=MAX_SAFE_INTEGER_V1)
+    max_pixels_per_artifact: int | None = Field(
+        default=None, 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 AdapterEmbeddingOfferV1(CanonicalModel):
+    variant: str = Field(pattern=_STABLE_KEY.pattern)
+    capability_version: str = Field(pattern=_STABLE_KEY.pattern)
+    capabilities: list[str] = Field(min_length=1, max_length=32)
+    input_modalities: list[Modality] = Field(min_length=1, max_length=2)
+    output_modalities: list[Modality] = Field(min_length=1, max_length=1)
+    limits: EmbeddingReadinessLimitsV1
+
+    @model_validator(mode="after")
+    def validate_atomic_offer(self) -> Self:
+        if any(not _STABLE_KEY.fullmatch(value) for value in self.capabilities):
+            raise ValueError("Embedding Adapter capability key 无效")
+        if len(self.capabilities) != len(set(self.capabilities)):
+            raise ValueError("Embedding Adapter capability 重复")
+        if len(self.input_modalities) != len(set(self.input_modalities)):
+            raise ValueError("Embedding Adapter 输入模态重复")
+        if len(self.output_modalities) != len(set(self.output_modalities)):
+            raise ValueError("Embedding Adapter 输出模态重复")
+        if not set(self.input_modalities).issubset({"text", "image"}):
+            raise ValueError("Embedding Adapter 输入模态无效")
+        if set(self.output_modalities) != {"embedding"}:
+            raise ValueError("Embedding Adapter 输出必须是 embedding")
+        return self
+
+
+class AdapterEmbeddingDeploymentV1(CanonicalModel):
+    identity: str = Field(pattern=_IDENTITY.pattern)
+    release_digest: str = Field(pattern=_DIGEST.pattern)
+    model: str = Field(min_length=1, max_length=200)
+    version: str = Field(min_length=1, max_length=200)
+    dimensions: int = Field(ge=1, le=65_536)
+    normalized: bool
+
+
+class AdapterEmbeddingReadinessV1(CanonicalModel):
+    contract_version: Literal[1]
+    status: Literal["ready"]
+    runtime_kind: Literal["embedding-adapter"]
+    deployment: AdapterEmbeddingDeploymentV1
+    offers: list[AdapterEmbeddingOfferV1] = Field(min_length=1, max_length=16)
+
+    @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("Embedding Adapter variant 重复")
+        return self
+
+
+def final_offers(
+    config: EmbeddingConfig, adapter: AdapterEmbeddingReadinessV1
+) -> list[dict[str, object]]:
+    configured = set(config.capabilities)
+    offers: list[dict[str, object]] = []
+    for downstream in adapter.offers:
+        if not set(downstream.capabilities).issubset(configured):
+            raise ValueError("Embedding Adapter capabilities 超出配置")
+        limits = downstream.limits
+        current: dict[str, object] = {
+            "variant": downstream.variant,
+            "capabilities": list(downstream.capabilities),
+            "inputModalities": list(downstream.input_modalities),
+            "outputModalities": ["embedding"],
+            "limits": {
+                "maxDurationSeconds": min(
+                    config.max_duration_seconds, limits.max_duration_seconds
+                ),
+                "maxInputBytes": min(config.max_input_bytes, limits.max_input_bytes),
+                "maxOutputBytes": min(config.max_output_bytes, limits.max_output_bytes),
+                "maxUnits": min(config.max_units, limits.max_units),
+                "maxConcurrentRuns": min(
+                    config.max_concurrent_runs, limits.max_concurrent_runs
+                ),
+                "maxQueueDepth": min(config.max_queue_depth, limits.max_queue_depth),
+            },
+        }
+        bounded = current["limits"]
+        assert isinstance(bounded, dict)
+        if "image" in downstream.input_modalities:
+            bounded["maxArtifacts"] = min(
+                config.max_artifacts, limits.max_artifacts or config.max_artifacts
+            )
+            bounded["maxPixelsPerArtifact"] = min(
+                config.max_pixels_per_artifact,
+                limits.max_pixels_per_artifact or config.max_pixels_per_artifact,
+            )
+        offers.append(current)
+    return offers
+
+
+def supports_offer(offer: dict[str, object], request: EmbeddingRequest) -> bool:
+    limits = offer.get("limits")
+    if not isinstance(limits, dict):
+        return False
+    artifacts = any(item.source is not None for item in request.items)
+    return bool(
+        set(request.required_capabilities).issubset(strings(offer["capabilities"]))
+        and set(request.input_modalities).issubset(strings(offer["inputModalities"]))
+        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 (
+            not artifacts
+            or (
+                request.limits.max_artifacts is not None
+                and request.limits.max_pixels_per_artifact is not None
+                and number(limits, "maxArtifacts") >= request.limits.max_artifacts
+                and number(limits, "maxPixelsPerArtifact")
+                >= request.limits.max_pixels_per_artifact
+            )
+        )
+    )
+
+
+def compute_offers_digest(offers: list[dict[str, object]]) -> str:
+    if not 0 < len(offers) <= 16:
+        raise ValueError("Embedding 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("Embedding readiness variant 重复")
+    encoded = json.dumps(canonical, ensure_ascii=False, separators=(",", ":")).encode()
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
+
+
+def compute_release_digest(adapter: AdapterEmbeddingReadinessV1) -> str:
+    payload = {
+        "adapter": adapter.deployment.model_dump(by_alias=True),
+        "capabilityVersions": sorted(
+            [
+                {"variant": item.variant, "capabilityVersion": item.capability_version}
+                for item in adapter.offers
+            ],
+            key=lambda item: item["variant"],
+        ),
+        "runtimeRelease": EMBEDDING_RUNTIME_RELEASE_V1,
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
+
+
+def canonical_offer(value: dict[str, object]) -> dict[str, object]:
+    limits = value.get("limits")
+    if not isinstance(limits, dict):
+        raise ValueError("Embedding readiness offer 无效")
+    return {
+        "variant": value.get("variant"),
+        "capabilities": sorted(strings(value.get("capabilities"))),
+        "inputModalities": sorted(strings(value.get("inputModalities"))),
+        "outputModalities": sorted(strings(value.get("outputModalities"))),
+        "limits": {key: limits[key] for key in _LIMIT_KEYS if key in limits},
+    }
+
+
+def strings(value: object) -> set[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ValueError("Embedding readiness list 无效")
+    return set(value)
+
+
+def number(value: dict[str, object], key: str) -> int:
+    current = value.get(key)
+    return current if isinstance(current, int) and not isinstance(current, bool) else -1