infimal 0.2.1__py3-none-any.whl

infimal/__init__.py

@@ -0,0 +1,154 @@
+"""infimal: snapshot-native serverless GPU endpoints.
+
+```python
+from infimal import App, Latency, Scale
+
+app = App("voice", perf=Latency(p95_ms=300), scale=Scale(max_replicas=4))
+
+@app.setup
+def load():
+    return load_model()          # runs once, on a builder GPU, then frozen into a snapshot
+
+@app.handler
+def transcribe(model, request):
+    return model(request["audio"])
+```
+
+`infimal apps deploy` gives you an HTTPS endpoint that scales to zero and comes back from that
+snapshot instead of a cold load. You never name a GPU: declare a latency or throughput target, or a
+tier, and the platform picks the silicon.
+
+Calling a model that is already served is the client:
+
+```python
+from infimal import Client
+
+client = Client.from_env()
+print(client.model("qwen3-8b").chat("Explain this code.").max_tokens(128).run().text)
+```
+
+The client names (`Client`, `InfimalError`, `Job`, `Request`, `ChatResult` and the rest) are
+imported on first use, not by `import infimal`: an App module is imported inside the serving
+container by the harness, and that import must not pull in the HTTP stack.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from .app import App, SnapshotBoundaryError, discover
+from .gateway import Credential, Flat, Gateway, Model, PerToken, Provider, Source, Wire
+from .models import (
+    Batch,
+    Deployment,
+    Endpoint,
+    Engine,
+    Latency,
+    Reservation,
+    Scale,
+    Throughput,
+    Tier,
+    TrafficEnvelope,
+)
+from .ring import Frame, FrameKind, Ring, RingError, RingFull
+from .runtime import (
+    is_build,
+    production_vram_bytes,
+    snapshot_vram_bytes,
+    snapshot_vram_fraction,
+    target_vram_bytes,
+)
+
+if TYPE_CHECKING:
+    from .client import Client, InfimalError, InfimalUnreachable
+    from .request import (
+        Artifact,
+        Capabilities,
+        ChatResult,
+        Job,
+        JobResult,
+        LoraSpec,
+        ModelHandle,
+        Request,
+    )
+
+__version__ = "0.2.1"
+
+#: The client surface, by the module that defines it. Loaded lazily (PEP 562) so that
+#: `import infimal` inside a container never imports httpx. `GlowError` and `GlowUnreachable` are
+#: the pre-rename names of the two errors, resolvable in 0.2 only and left out of `__all__`.
+_LAZY = {
+    "Client": "client",
+    "InfimalError": "client",
+    "InfimalUnreachable": "client",
+    "GlowError": "client",
+    "GlowUnreachable": "client",
+    "ModelHandle": "request",
+    "Request": "request",
+    "ChatResult": "request",
+    "JobResult": "request",
+    "Job": "request",
+    "Artifact": "request",
+    "Capabilities": "request",
+    "LoraSpec": "request",
+}
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    value = getattr(import_module(f".{module}", __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY))
+
+
+__all__ = [
+    "App",
+    "Artifact",
+    "Batch",
+    "Capabilities",
+    "ChatResult",
+    "Client",
+    "Credential",
+    "Deployment",
+    "Endpoint",
+    "Engine",
+    "Flat",
+    "Frame",
+    "FrameKind",
+    "Gateway",
+    "InfimalError",
+    "InfimalUnreachable",
+    "Job",
+    "JobResult",
+    "Latency",
+    "LoraSpec",
+    "Model",
+    "ModelHandle",
+    "PerToken",
+    "Provider",
+    "Request",
+    "Reservation",
+    "Ring",
+    "RingError",
+    "RingFull",
+    "Scale",
+    "SnapshotBoundaryError",
+    "Source",
+    "Throughput",
+    "Tier",
+    "TrafficEnvelope",
+    "Wire",
+    "__version__",
+    "discover",
+    "is_build",
+    "production_vram_bytes",
+    "snapshot_vram_bytes",
+    "snapshot_vram_fraction",
+    "target_vram_bytes",
+]

infimal/_synth.py

@@ -0,0 +1,347 @@
+"""`python -m infimal._synth`: the SDK's half of `infimal apps plan`, `apply` and `deploy`.
+
+Private. The native `infimal` binary is the one customer CLI (D361); an App's topology is Python, and
+the only way to know what a module declares is to execute it. So the binary runs this module as a
+subprocess: one JSON request on stdin, one JSON reply on stdout. Nothing else calls it, and its shape
+is versioned by the `synth` field rather than promised to anyone else. The contract is written down
+in `docs/sdk.md`, "The synth contract".
+
+It never opens a connection and reads no credential. Everything that crosses the wire is the
+binary's: it fetches the live app between the two operations, sends the deploy or the configuration
+this module computed, and renders the answer. What stays here is what has to be Python — executing
+the customer's module — and what is Python today and is reused rather than ported: the diff engine
+(`infimal.plan`) and the deploy body (`infimal.client.deploy_body`).
+
+Two operations:
+
+    {"synth": 1, "op": "declare", "module": "main", "app": null}
+        executes the module (from the working directory) and returns the App's declaration, the
+        source digest, a description to print, and the deploy request.
+
+    {"synth": 1, "op": "diff", "app": "voice", "declaration": {…}, "source_digest": "sha256:…",
+     "live": null | <GET /v1/apps/{app}>}
+        diffs a declaration against the live app without executing anything, and returns the plan,
+        its lines, and the request `apply` sends (null when there is nothing to change).
+
+Two more, for `infimal gateway plan` and `apply` (`infimal.gateway`):
+
+    {"synth": 1, "op": "gateway.declare", "module": "gateway", "gateway": null}
+        executes the module and returns the Gateway's declaration, the credentials it names as
+        `{name, env}` (the binary reads the variables; this module never does), a summary, and the
+        `PUT /v1/gateway` request.
+    {"synth": 1, "op": "gateway.diff", "declaration": {…}, "live": null | <GET /v1/gateway>}
+        diffs the declaration against the live gateway and returns the plan, its lines, and the
+        request `apply` sends (null when nothing changed).
+
+Every reply carries `"synth": 1` and `"ok"`; a failure is `{"ok": false, "error", "message",
+"next"}`, the API's envelope, so the binary shows it the way it shows a refusal. The exit status
+is 0 with a reply that is ok, 1 with a failure reply, and 2 when the request itself could not be
+read. What the customer's module prints while it is imported goes to stderr: stdout is the reply
+and nothing else.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+from dataclasses import asdict
+from typing import Any
+from urllib.parse import quote
+
+#: The contract's version. The binary refuses a reply that does not carry the one it speaks.
+VERSION = 1
+
+
+class Refusal(Exception):
+    """A failure with the envelope the binary prints: a code, a sentence and the next step."""
+
+    def __init__(self, error: str, message: str, next: str):
+        super().__init__(message)
+        self.error = error
+        self.message = message
+        self.next = next
+
+
+def _path(*segments: str) -> str:
+    return "/" + "/".join(quote(str(s), safe="") for s in segments)
+
+
+def _summary(deployment: Any) -> list[str]:
+    """What the module declares, in the lines `infimal apps plan` prints above the diff."""
+    lines = [f"app: {deployment.name}", f"  tier          {deployment.tier.value}"]
+    if deployment.perf is not None:
+        target = deployment.perf.model_dump()
+        target.pop("kind", None)
+        shown = ", ".join(f"{k}={v}" for k, v in target.items())
+        lines.append(f"  perf          {deployment.perf.kind}({shown})")
+    scale = deployment.scale
+    lines.append(
+        f"  scale         {scale.min_replicas}..{scale.max_replicas}, "
+        f"target queue {scale.target_queue_ms} ms"
+    )
+    lines.append(
+        f"  residency     park after {scale.idle_park_ms / 1000:.0f}s idle, "
+        f"checkpoint after {scale.parked_checkpoint_ms / 1000:.0f}s parked"
+    )
+    if deployment.batch.enabled:
+        lines.append(
+            f"  batching      up to {deployment.batch.max_size} in {deployment.batch.window_ms} ms"
+        )
+    if deployment.reservation is not None:
+        lines.append(
+            f"  reservation   snapshot {deployment.reservation.snapshot_gb:.0f} GB, "
+            f"production {deployment.reservation.production_gb:.0f} GB"
+        )
+    return lines
+
+
+def _load(module: str, app_name: str | None) -> Any:
+    """Execute the customer's module from the working directory and return its App, validated."""
+    from .harness import load_app
+
+    sys.path.insert(0, os.getcwd())
+    try:
+        # The module's own output goes to stderr: stdout carries the reply and nothing else.
+        with contextlib.redirect_stdout(sys.stderr):
+            app = load_app(module, app_name)
+    except ModuleNotFoundError as exc:
+        if exc.name and (exc.name == module or module.startswith(exc.name + ".")):
+            raise Refusal(
+                "module_not_found",
+                f"no module named {module!r} in {os.getcwd()}",
+                "Run from the directory that contains it, and name it as an import path "
+                "(services.voice), not as a file (services/voice.py).",
+            ) from None
+        raise Refusal(
+            "module_failed",
+            f"importing {module!r} failed: ModuleNotFoundError: {exc}",
+            "Install the module's dependencies in the Python environment that runs the SDK.",
+        ) from None
+    except SystemExit as exc:
+        if not isinstance(exc.code, str):
+            raise Refusal(
+                "module_failed",
+                f"importing {module!r} exited with status {exc.code!r}",
+                "Remove the exit from the module's import path: planning executes it.",
+            ) from None
+        # `load_app` names what it did not find: no App at all, no App of that name, or several.
+        raise Refusal(
+            "app_not_found",
+            str(exc.code),
+            "Declare one infimal.App in the module, or pass --app NAME to choose one.",
+        ) from None
+    except Exception as exc:
+        raise Refusal(
+            "module_failed",
+            f"importing {module!r} failed: {type(exc).__name__}: {exc}",
+            "Fix the module: planning executes it, so its imports must be safe to run.",
+        ) from None
+    try:
+        app.validate()
+    except ValueError as exc:
+        raise Refusal("invalid_app", str(exc), "Fix the App declaration, then plan again.") from None
+    return app
+
+
+def declare(request: dict[str, Any]) -> dict[str, Any]:
+    from .client import deploy_body
+    from .plan import source_digest
+
+    module = request.get("module") or "main"
+    app = _load(str(module), request.get("app") or None)
+    wire = app.deployment.to_wire()
+    digest = source_digest(os.getcwd())
+    body = deploy_body(wire, tier=wire["tier"], region=wire.get("region"), source_digest=digest)
+    return {
+        "app": app.name,
+        "declaration": wire,
+        "source_digest": digest,
+        "summary": _summary(app.deployment),
+        "deploy": {"method": "POST", "path": _path("v1", "apps", app.name, "deploy"), "body": body},
+    }
+
+
+def plan_data(plan: Any) -> dict[str, Any]:
+    """The plan as JSON: the dataclass, and the three properties a script branches on."""
+    return {
+        **asdict(plan),
+        "kind": plan.kind.value,
+        "requires_rebuild": plan.requires_rebuild,
+        "keeps_snapshot": plan.keeps_snapshot,
+        "keeps_rate_lock": plan.keeps_rate_lock,
+    }
+
+
+def diff(request: dict[str, Any]) -> dict[str, Any]:
+    from .client import deploy_body
+    from .plan import ChangeKind, diff_wire, render
+
+    app = request.get("app")
+    wire = request.get("declaration")
+    if not isinstance(app, str) or not app or not isinstance(wire, dict):
+        raise Refusal(
+            "invalid_request",
+            "diff needs the app name and the declaration that declare returned",
+            "Upgrade the infimal binary and the SDK together.",
+        )
+    live = request.get("live")
+    digest = request.get("source_digest")
+    plan = diff_wire(app, wire, live if isinstance(live, dict) else None, local_source_digest=digest)
+    apply: dict[str, Any] | None = None
+    if plan.kind is not ChangeKind.NOOP:
+        if plan.requires_rebuild:
+            body = deploy_body(wire, tier=wire.get("tier"), region=wire.get("region"),
+                               source_digest=digest)
+            apply = {"method": "POST", "path": _path("v1", "apps", app, "deploy"), "body": body}
+        else:
+            # A configuration merges onto the saved row: provided fields replace, omitted ones are
+            # kept (D327). So a target or a region the module no longer declares is sent as an
+            # explicit null, which is the only way to clear it.
+            body = dict(wire)
+            for change in plan.changes:
+                if change.after is None and change.field in ("perf", "region"):
+                    body["slo" if change.field == "perf" else "region"] = None
+            apply = {"method": "PUT", "path": _path("v1", "apps", app, "config"), "body": body}
+    return {"plan": plan_data(plan), "lines": render(plan), "apply": apply}
+
+
+def _load_gateway(module: str, namespace: str | None) -> Any:
+    """Execute the customer's module and return the `Gateway` it declares, validated on construction."""
+    from importlib import import_module
+
+    from .gateway import discover
+
+    sys.path.insert(0, os.getcwd())
+    try:
+        with contextlib.redirect_stdout(sys.stderr):
+            loaded = import_module(module)
+    except ModuleNotFoundError as exc:
+        if exc.name and (exc.name == module or module.startswith(exc.name + ".")):
+            raise Refusal(
+                "module_not_found",
+                f"no module named {module!r} in {os.getcwd()}",
+                "Run from the directory that contains it, and name it as an import path "
+                "(gateway), not as a file (gateway.py).",
+            ) from None
+        raise Refusal(
+            "module_failed",
+            f"importing {module!r} failed: ModuleNotFoundError: {exc}",
+            "Install the module's dependencies in the Python environment that runs the SDK.",
+        ) from None
+    except Exception as exc:
+        # A pydantic refusal inside the module is the declaration being invalid, not the import.
+        name = type(exc).__name__
+        error = "invalid_gateway" if name == "ValidationError" else "module_failed"
+        raise Refusal(
+            error,
+            f"importing {module!r} failed: {name}: {exc}",
+            "Fix the Gateway declaration, then plan again." if error == "invalid_gateway"
+            else "Fix the module: planning executes it, so its imports must be safe to run.",
+        ) from None
+    try:
+        return discover(loaded, namespace)
+    except LookupError as exc:
+        raise Refusal(
+            "gateway_not_found",
+            str(exc),
+            "Declare one infimal.Gateway in the module, or pass --gateway NAMESPACE to choose one.",
+        ) from None
+
+
+def gateway_declare(request: dict[str, Any]) -> dict[str, Any]:
+    """Execute the module and return the declaration, its credentials by variable name, and the apply request.
+
+    The declaration carries no credential value. `credentials` lists `{name, env}`; the binary reads
+    each variable and sends `{"name", "key"}` under `credentials` in the body, refusing before any
+    request when one is unset.
+    """
+    module = request.get("module") or "gateway"
+    gateway = _load_gateway(str(module), request.get("gateway") or None)
+    wire = gateway.to_wire()
+    return {
+        "gateway": gateway.namespace,
+        "declaration": wire,
+        "credentials": wire["credentials"],
+        "summary": gateway.summary(),
+        "apply": {"method": "PUT", "path": _path("v1", "gateway"), "body": wire},
+    }
+
+
+def gateway_diff(request: dict[str, Any]) -> dict[str, Any]:
+    """Diff a declaration against `GET /v1/gateway` without executing anything."""
+    from .gateway import GatewayChangeKind, diff_wire, render
+
+    wire = request.get("declaration")
+    if not isinstance(wire, dict) or not isinstance(wire.get("namespace"), str):
+        raise Refusal(
+            "invalid_request",
+            "gateway.diff needs the declaration that gateway.declare returned",
+            "Upgrade the infimal binary and the SDK together.",
+        )
+    live = request.get("live")
+    plan = diff_wire(wire, live if isinstance(live, dict) else None)
+    apply: dict[str, Any] | None = None
+    if plan.kind is not GatewayChangeKind.NOOP:
+        apply = {"method": "PUT", "path": _path("v1", "gateway"), "body": wire}
+    return {
+        "plan": {
+            **asdict(plan),
+            "kind": plan.kind.value,
+            "changes": [asdict(c) for c in plan.changes],
+        },
+        "lines": render(plan),
+        "apply": apply,
+    }
+
+
+OPERATIONS = {
+    "declare": declare,
+    "diff": diff,
+    "gateway.declare": gateway_declare,
+    "gateway.diff": gateway_diff,
+}
+
+
+def run(raw: str) -> tuple[dict[str, Any], int]:
+    """One request in, one reply and an exit status out."""
+    try:
+        request = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return _failure("invalid_request", f"the request is not JSON: {exc}"), 2
+    if not isinstance(request, dict) or request.get("synth") != VERSION:
+        return _failure(
+            "version_mismatch",
+            f"this SDK speaks synth {VERSION}; the request asked for {request.get('synth') if isinstance(request, dict) else None!r}",
+        ), 2
+    operation = OPERATIONS.get(str(request.get("op")))
+    if operation is None:
+        return _failure("invalid_request", f"unknown operation {request.get('op')!r}"), 2
+    try:
+        reply = operation(request)
+    except Refusal as exc:
+        return {"synth": VERSION, "ok": False, "error": exc.error, "message": exc.message,
+                "next": exc.next}, 1
+    return {"synth": VERSION, "ok": True, "op": request["op"], **reply}, 0
+
+
+def _failure(error: str, message: str) -> dict[str, Any]:
+    return {
+        "synth": VERSION,
+        "ok": False,
+        "error": error,
+        "message": message,
+        "next": "Install the SDK that matches this infimal binary; they are released together.",
+    }
+
+
+def main() -> int:
+    reply, status = run(sys.stdin.read())
+    sys.stdout.write(json.dumps(reply, default=str) + "\n")
+    sys.stdout.flush()
+    return status
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())