create-windy 0.6.0 → 0.6.2

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

package/template/apps/embedding-server/src/southwind_embedding_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/embedding-server/src/southwind_embedding_server/run_service.py

@@ -3,25 +3,36 @@ from __future__ import annotations
 import asyncio
 import hashlib
 import json
+from collections.abc import Awaitable, Callable
+from typing import Protocol
 
-from .adapter import EmbeddingAdapter
 from .config import EmbeddingConfig
-from .contracts import EmbeddingRequest
+from .contracts import EmbeddingRequest, EmbeddingResponse
 from .error import SafeEmbeddingError
 from .run_store import EmbeddingRunRecord, EmbeddingRunStore, failure
 
 
+class EmbeddingExecutionPort(Protocol):
+    config: EmbeddingConfig
+
+    async def embed(
+        self, request: EmbeddingRequest, run_id: str | None = None
+    ) -> EmbeddingResponse: ...
+
+
 class EmbeddingRunService:
     def __init__(
         self,
-        adapter: EmbeddingAdapter,
+        adapter: EmbeddingExecutionPort,
         store: EmbeddingRunStore,
         max_concurrent_runs: int,
+        admit: Callable[[EmbeddingRequest], Awaitable[bool]] | None = None,
     ) -> None:
         self.adapter = adapter
         self.store = store
         self._tasks: dict[str, asyncio.Task[None]] = {}
         self._queue = asyncio.Semaphore(max_concurrent_runs)
+        self._admit = admit
 
     async def start(
         self, request: EmbeddingRequest, idempotency_key: str, run_id: str
@@ -76,6 +87,12 @@ class EmbeddingRunService:
                         "Embedding Deployment 已漂移",
                         False,
                     )
+                if self._admit and not await self._admit(request):
+                    raise SafeEmbeddingError(
+                        "CAPABILITY_UNAVAILABLE",
+                        "Embedding Runtime readiness 已漂移",
+                        True,
+                    )
                 await self.store.append(run_id, "run.started")
                 async with asyncio.timeout(request.limits.max_duration_seconds):
                     output = await self.adapter.embed(request, run_id)
@@ -127,4 +144,7 @@ def deployment_pin(config: EmbeddingConfig) -> dict[str, object]:
         "normalized": config.normalized,
         "maxUnits": config.max_units,
         "capabilities": list(config.capabilities),
+        "deploymentIdentity": config.deployment_identity,
+        "releaseDigest": config.release_digest,
+        "offersDigest": config.offers_digest,
     }

package/template/apps/embedding-server/tests/test_config.py

@@ -36,3 +36,16 @@ def test_rejects_ambiguous_normalization() -> None:
 
     with pytest.raises(ValueError, match="true 或 false"):
         EmbeddingConfig.from_environment(values)
+
+
+def test_rejects_invalid_readiness_identity_and_ttl() -> None:
+    values = environment()
+    values["EMBEDDING_DEPLOYMENT_IDENTITY"] = "embedding-server"
+    with pytest.raises(ValueError, match="EMBEDDING_DEPLOYMENT_IDENTITY"):
+        EmbeddingConfig.from_environment(values)
+
+    values = environment()
+    values["EMBEDDING_READINESS_TTL_SECONDS"] = "301"
+    values["EMBEDDING_RUN_ENCRYPTION_SECRET"] = "x" * 32
+    with pytest.raises(ValueError, match="不能超过 300"):
+        EmbeddingConfig.from_environment(values)

package/template/apps/embedding-server/tests/test_readiness.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import UTC, datetime
+
+import httpx
+
+from southwind_embedding_server.config import EmbeddingConfig
+from southwind_embedding_server.contracts import EmbeddingRequest
+from southwind_embedding_server.pin_cli import compute_pins
+from southwind_embedding_server.readiness import EmbeddingReadinessProbe
+from southwind_embedding_server.readiness_contracts import (
+    AdapterEmbeddingReadinessV1,
+    compute_offers_digest,
+    compute_release_digest,
+    final_offers,
+)
+
+IDENTITY = "windy-deployment-v1_0f26eb34-f384-4ec9-98f3-caf8d582291f"
+ADAPTER_IDENTITY = "windy-deployment-v1_11c93162-e5f0-40af-93ce-9771a4bf12ed"
+DIGEST_A = f"sha256:{'a' * 64}"
+DIGEST_B = f"sha256:{'b' * 64}"
+
+
+def adapter_payload() -> dict[str, object]:
+    return {
+        "contractVersion": 1,
+        "status": "ready",
+        "runtimeKind": "embedding-adapter",
+        "deployment": {
+            "identity": ADAPTER_IDENTITY,
+            "releaseDigest": DIGEST_A,
+            "model": "embedding-model",
+            "version": "2026-08",
+            "dimensions": 3,
+            "normalized": True,
+        },
+        "offers": [
+            {
+                "variant": "text",
+                "capabilityVersion": "embedding.text/v1",
+                "capabilities": ["embedding.text"],
+                "inputModalities": ["text"],
+                "outputModalities": ["embedding"],
+                "limits": limits(),
+            },
+            {
+                "variant": "image",
+                "capabilityVersion": "embedding.image/v1",
+                "capabilities": ["embedding.image"],
+                "inputModalities": ["image"],
+                "outputModalities": ["embedding"],
+                "limits": {
+                    **limits(),
+                    "maxArtifacts": 8,
+                    "maxPixelsPerArtifact": 20_000_000,
+                },
+            },
+        ],
+    }
+
+
+def limits() -> dict[str, int]:
+    return {
+        "maxDurationSeconds": 120,
+        "maxInputBytes": 64 * 1024 * 1024,
+        "maxOutputBytes": 64 * 1024 * 1024,
+        "maxUnits": 64,
+        "maxConcurrentRuns": 2,
+        "maxQueueDepth": 0,
+    }
+
+
+def base_config() -> EmbeddingConfig:
+    return EmbeddingConfig(
+        internal_token="internal",
+        artifact_url="http://server.internal/api/internal/ai/artifacts",
+        run_artifact_url="http://server.internal/api/internal/embeddings/runs",
+        adapter_url="http://adapter.internal",
+        adapter_token="adapter-token",
+        deployment_key="embedding.primary",
+        deployment_identity=IDENTITY,
+        release_digest=DIGEST_A,
+        offers_digest=DIGEST_B,
+        deployment_alias="intranet-v1",
+        model="embedding-model",
+        version="2026-08",
+        dimensions=3,
+        normalized=True,
+        capabilities=("embedding.text", "embedding.image"),
+        max_concurrent_runs=1,
+        max_queue_depth=0,
+    )
+
+
+def pinned_config() -> EmbeddingConfig:
+    config = base_config()
+    adapter = AdapterEmbeddingReadinessV1.model_validate(adapter_payload())
+    return replace(
+        config,
+        release_digest=compute_release_digest(adapter),
+        offers_digest=compute_offers_digest(final_offers(config, adapter)),
+    )
+
+
+def transport(status: int = 200) -> httpx.MockTransport:
+    return httpx.MockTransport(
+        lambda _request: httpx.Response(status, json=adapter_payload())
+    )
+
+
+def probe(config: EmbeddingConfig, status: int = 200) -> EmbeddingReadinessProbe:
+    return EmbeddingReadinessProbe(
+        config,
+        transport(status),
+        wall_clock=lambda: datetime(2026, 8, 6, 1, 2, 3, 4000, tzinfo=UTC),
+        monotonic_clock=lambda: 10.0,
+    )
+
+
+async def test_readiness_attests_bounded_atomic_offers_and_pins() -> None:
+    config = pinned_config()
+    inspection = await probe(config).inspect()
+
+    assert inspection.ready
+    assert inspection.snapshot["runtimeKind"] == "embedding"
+    assert [offer["variant"] for offer in inspection.offers] == ["text", "image"]
+    deployment = inspection.snapshot["deployment"]
+    assert isinstance(deployment, dict)
+    assert deployment == {
+        "key": config.deployment_key,
+        "identity": config.deployment_identity,
+        "releaseDigest": config.release_digest,
+        "offersDigest": config.offers_digest,
+    }
+
+
+async def test_unconfigured_or_failed_downstream_never_becomes_ready() -> None:
+    missing = await probe(replace(base_config(), adapter_url=None)).inspect()
+    assert not missing.ready
+    assert missing.snapshot["configured"] is False
+
+    failed = await probe(pinned_config(), 503).inspect()
+    assert not failed.ready
+    downstream = failed.snapshot["downstreamProbe"]
+    assert isinstance(downstream, dict)
+    assert downstream["failureCode"] == "RESOURCE_UNAVAILABLE"
+
+
+async def test_request_requires_exact_deployment_pin_and_matching_offer() -> None:
+    readiness = probe(pinned_config())
+    inspection = await readiness.inspect()
+    request = embedding_request(inspection.snapshot["deployment"])
+
+    assert readiness.supports(inspection, request)
+    assert request.readiness_pin is not None
+    drifted = request.model_copy(
+        update={
+            "readiness_pin": request.readiness_pin.model_copy(
+                update={"offers_digest": DIGEST_A}
+            )
+        }
+    )
+    assert not readiness.supports(inspection, drifted)
+    assert readiness.supports(
+        inspection, request.model_copy(update={"readiness_pin": None})
+    )
+
+
+async def test_pin_cli_uses_the_same_real_probe_facts() -> None:
+    config = base_config()
+    pins = await compute_pins(config, transport())
+    expected = pinned_config()
+    assert pins == {
+        "deploymentKey": config.deployment_key,
+        "deploymentIdentity": config.deployment_identity,
+        "releaseDigest": expected.release_digest,
+        "offersDigest": expected.offers_digest,
+    }
+
+
+def embedding_request(deployment: object) -> EmbeddingRequest:
+    assert isinstance(deployment, dict)
+    return EmbeddingRequest.model_validate(
+        {
+            "kind": "embedding",
+            "operationKey": "analysis.embedding.text",
+            "items": [{"id": "one", "text": "安全文本"}],
+            "options": {},
+            "inputModalities": ["text"],
+            "requiredCapabilities": ["embedding.text"],
+            "dataClassification": "sensitive",
+            "limits": {
+                "maxDurationSeconds": 30,
+                "maxInputBytes": 1024,
+                "maxOutputBytes": 1024,
+                "maxUnits": 10,
+            },
+            "providerEgress": {"mode": "forbidden"},
+            "readinessPin": deployment,
+        }
+    )