@alchemy.run/modal 0.0.0 → 2.0.0-beta.87

package/lib/Endpoint.js

@@ -0,0 +1,283 @@
+import * as endpoint from "@distilled.cloud/modal/endpoint";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { deepEqual, isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Schedule from "effect/Schedule";
+import { environmentNames, envNameOf, environmentOf, isGeneratedName, listAll, objectName, } from "./internal.js";
+import { declarable } from "./internal/Declared.js";
+/** Provisioning failed, was cancelled, or didn't finish in time. */
+export class EndpointProvisioningFailed extends Data.TaggedError("Modal.EndpointProvisioningFailed") {
+}
+/**
+ * A Modal Endpoint: a managed model server that speaks the OpenAI Chat
+ * Completions, OpenAI Responses or Anthropic Messages API, from a catalog
+ * model, a Hugging Face repo, or weights on a Modal Volume.
+ *
+ * Reconcile waits until the endpoint is live, which takes minutes while the
+ * model loads. Modal can't change an endpoint in place, so any change
+ * replaces it.
+ *
+ * :::caution
+ * A dedicated endpoint reserves GPUs and is billed while it runs. Destroy it
+ * (or use `servingMode: "shared"`) when you're done.
+ * :::
+ *
+ * ### Serving a model
+ * **Example:** A catalog model behind the OpenAI API
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Qwen = Modal.Endpoint("Qwen", {
+ *   model: { repoId: "Qwen/Qwen3-8B" },
+ *   apis: ["openai-chat-completions", "anthropic-messages"],
+ * });
+ * ```
+ *
+ * **Example:** Fine-tuned weights from a Volume
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Weights = Modal.Volume("Weights", {});
+ * export const Tuned = Modal.Endpoint("Tuned", {
+ *   model: { volume: Weights, path: "/checkpoints/final", baseModel: "Qwen/Qwen3-8B" },
+ * });
+ * ```
+ *
+ * ### Calling it
+ * **Example:** From a Cloudflare Worker with `Modal.FetchServer`
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpClientRequest from "effect/http/HttpClientRequest";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Qwen } from "./Qwen.ts";
+ *
+ * export default class Chat extends Cloudflare.Worker<Chat>()(
+ *   "Chat",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     // Creates a webhook token for the Worker and sends it as Modal's proxy auth.
+ *     const qwen = yield* Modal.FetchServer(Qwen);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const response = yield* qwen.fetch(
+ *           HttpClientRequest.post("/v1/chat/completions").pipe(
+ *             HttpClientRequest.bodyJsonUnsafe({
+ *               model: "Qwen/Qwen3-8B",
+ *               messages: [{ role: "user", content: "hi" }],
+ *             }),
+ *           ),
+ *         );
+ *         return HttpServerResponse.json(yield* response.json);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.FetchServerHttp)),
+ * ) {}
+ * ```
+ *
+ * @resource
+ * @product Endpoint
+ */
+export const Endpoint = declarable()(Resource("Modal.Endpoint"));
+const API = {
+    "openai-chat-completions": "ENDPOINT_API_SURFACE_OPENAI_CHAT_COMPLETIONS",
+    "openai-responses": "ENDPOINT_API_SURFACE_OPENAI_RESPONSES",
+    "anthropic-messages": "ENDPOINT_API_SURFACE_ANTHROPIC_MESSAGES",
+};
+const INPUT = {
+    text: "ENDPOINT_INPUT_MODALITY_TEXT",
+    image: "ENDPOINT_INPUT_MODALITY_IMAGE",
+    audio: "ENDPOINT_INPUT_MODALITY_AUDIO",
+};
+const modelSource = (model) => {
+    if ("repoId" in model)
+        return { baseModelRepoId: model.repoId };
+    if ("huggingface" in model) {
+        return {
+            custom: {
+                baseModelRepoId: model.baseModel,
+                huggingface: {
+                    repoId: model.huggingface,
+                    revision: model.revision,
+                    huggingfaceToken: model.token,
+                },
+            },
+        };
+    }
+    const volume = model.volume;
+    return {
+        custom: {
+            baseModelRepoId: model.baseModel,
+            modalVolume: { volumeId: volume.volumeId ?? "", modelPath: model.path },
+        },
+    };
+};
+/** Modal's default routing region (`modal endpoint create`'s). */
+const DEFAULT_ROUTING_REGION = "us-west";
+/** Props compared for replacement (credentials and references by value). */
+const identity = (news) => ({
+    environment: envNameOf(news.environment),
+    model: modelSource(news.model),
+    apis: news.apis ?? ["openai-chat-completions"],
+    inputs: news.inputs ?? ["text"],
+    servingMode: news.servingMode ?? "dedicated",
+    regions: news.regions,
+    routingRegion: news.routingRegion ?? DEFAULT_ROUTING_REGION,
+    unauthenticated: news.unauthenticated ?? false,
+    description: news.description,
+});
+export const EndpointProvider = () => Provider.effect(Endpoint, Effect.gen(function* () {
+    const info = Effect.fn(function* (endpointId) {
+        return yield* endpoint
+            .endpointGetInfo({ endpointId })
+            .pipe(Effect.catchTag("EndpointNotFound", () => Effect.undefined));
+    });
+    const lookup = Effect.fn(function* (name, env) {
+        const found = yield* endpoint
+            .endpointGetByName({ name, environmentName: environmentOf(env) })
+            .pipe(Effect.catchTag("EndpointNotFound", () => Effect.undefined));
+        if (!found?.endpointId)
+            return undefined;
+        const details = yield* info(found.endpointId);
+        if (!details?.info ||
+            details.info.lifecycle?.status === "ENDPOINT_LIFECYCLE_STATUS_STOPPED") {
+            return undefined;
+        }
+        return {
+            endpointId: found.endpointId,
+            name,
+            environment: env,
+            url: details.info.serviceUrl ?? "",
+            requiresAuth: details.info.requiresProxyAuth ?? true,
+        };
+    });
+    /** Wait until live: model loads take minutes. */
+    const waitLive = Effect.fn(function* (endpointId) {
+        for (let attempt = 0; attempt < 120; attempt++) {
+            const details = yield* info(endpointId);
+            const status = details?.info?.status;
+            if (status === "ENDPOINT_STATUS_LIVE")
+                return details;
+            if (status === "ENDPOINT_STATUS_FAILED" ||
+                status === "ENDPOINT_STATUS_CANCELLED" ||
+                status === "ENDPOINT_STATUS_STOPPED") {
+                return yield* new EndpointProvisioningFailed({
+                    endpointId,
+                    status,
+                    message: `Modal endpoint ${endpointId} ended provisioning as ${status}`,
+                });
+            }
+            yield* Effect.sleep("15 seconds");
+        }
+        return yield* new EndpointProvisioningFailed({
+            endpointId,
+            status: "ENDPOINT_STATUS_PROVISIONING",
+            message: `Modal endpoint ${endpointId} wasn't live after 30 minutes`,
+        });
+    });
+    return {
+        stables: ["endpointId", "name", "environment"],
+        diff: Effect.fn(function* ({ id, news, olds, output }) {
+            if (!isResolved(news))
+                return undefined;
+            const name = yield* objectName(id, news.name);
+            if (output !== undefined && name !== output.name)
+                return { action: "replace" };
+            // Modal has no endpoint update: every change is a new endpoint.
+            if (olds !== undefined && !deepEqual(identity(news), identity(olds))) {
+                return { action: "replace" };
+            }
+            return undefined;
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+            const name = output?.name ?? (yield* objectName(id, olds?.name));
+            const found = yield* lookup(name, output?.environment ?? envNameOf(olds?.environment));
+            if (!found)
+                return undefined;
+            return output !== undefined || olds?.name === undefined ? found : Unowned(found);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+            const name = output?.name ?? (yield* objectName(id, news.name));
+            const env = envNameOf(news.environment);
+            // Observe
+            const existing = yield* lookup(name, env);
+            let endpointId = existing?.endpointId;
+            // Ensure
+            if (endpointId === undefined) {
+                yield* session.note(`Creating endpoint ${name}...`);
+                const created = yield* endpoint
+                    .createEndpoint({
+                    name,
+                    description: news.description,
+                    environmentName: environmentOf(env),
+                    model: modelSource(news.model),
+                    apiSurfaces: (news.apis ?? ["openai-chat-completions"]).map((api) => API[api]),
+                    inputModalities: (news.inputs ?? ["text"]).map((input) => INPUT[input]),
+                    servingMode: (news.servingMode ?? "dedicated") === "shared"
+                        ? "ENDPOINT_SERVING_MODE_SHARED"
+                        : "ENDPOINT_SERVING_MODE_DEDICATED",
+                    computeRegion: news.regions
+                        ? { explicit: { regions: news.regions } }
+                        : { auto: {} },
+                    // Modal routes an endpoint through exactly one region.
+                    proxyRegions: [news.routingRegion ?? DEFAULT_ROUTING_REGION],
+                    unauthenticated: news.unauthenticated ?? false,
+                    sharedEndpointNoticeAcknowledged: news.servingMode === "shared" ? true : undefined,
+                })
+                    .pipe(
+                // An endpoint creates an App, and Modal rate-limits App
+                // creation per workspace; wait it out, as `Modal.App` does.
+                Effect.retry({
+                    while: (e) => e._tag === "TooManyRequests",
+                    schedule: Schedule.spaced("5 seconds"),
+                    times: 12,
+                }), Effect.catchTag("EndpointAlreadyExists", () => lookup(name, env).pipe(Effect.map((found) => ({ endpointId: found?.endpointId })))));
+                endpointId = created.endpointId;
+            }
+            if (!endpointId) {
+                return yield* new EndpointProvisioningFailed({
+                    endpointId: "",
+                    status: "ENDPOINT_STATUS_UNSPECIFIED",
+                    message: `Modal returned no endpoint for ${name}`,
+                });
+            }
+            yield* session.note(`Waiting for endpoint ${name} to go live...`);
+            const live = yield* waitLive(endpointId);
+            return {
+                endpointId,
+                name,
+                environment: env,
+                url: live.info?.serviceUrl ?? "",
+                requiresAuth: live.info?.requiresProxyAuth ?? true,
+            };
+        }),
+        list: Effect.fn(function* () {
+            const envs = yield* environmentNames;
+            const all = [];
+            for (const env of envs) {
+                const items = yield* listAll((pagination) => endpoint
+                    .listEndpoint({ environmentName: env, pagination })
+                    .pipe(Effect.map((response) => response.items ?? [])), (item) => item.updatedAt);
+                for (const item of items) {
+                    if (!item.endpointId || !isGeneratedName(item.name))
+                        continue;
+                    const found = yield* lookup(item.name ?? "", env);
+                    if (found)
+                        all.push(found);
+                }
+            }
+            return all;
+        }),
+        delete: Effect.fn(function* ({ output }) {
+            yield* endpoint
+                .stopEndpoint({ endpointId: output.endpointId, source: "ENDPOINT_STOP_SOURCE_CLI" })
+                .pipe(Effect.catchTag("EndpointNotFound", () => Effect.void));
+        }),
+    };
+}));
+//# sourceMappingURL=Endpoint.js.map

package/lib/Endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Endpoint.js","sources":["../src/Endpoint.ts"],"names":[],"mappings":"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"}

package/lib/Environment.d.ts

@@ -0,0 +1,174 @@
+import * as environment from "@distilled.cloud/modal/environment";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import type { Providers } from "./Providers.ts";
+declare const EnvironmentUnexpectedResponse_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Modal.EnvironmentUnexpectedResponse";
+} & Readonly<A>;
+export declare class EnvironmentUnexpectedResponse extends EnvironmentUnexpectedResponse_base<{
+    readonly message: string;
+}> {
+}
+/** A member's access to an environment. */
+export type EnvironmentRole = "viewer" | "contributor" | "no-access";
+/** One role assignment: a workspace member or service user, and its role. */
+export type EnvironmentRoleAssignment = {
+    readonly userId: string;
+    readonly role: EnvironmentRole;
+} | {
+    readonly serviceUserId: string;
+    readonly role: EnvironmentRole;
+};
+export interface EnvironmentProps {
+    /**
+     * Environment name, unique in the workspace. If omitted, a unique name is
+     * generated from the stack, stage and logical ID. Changing it renames the
+     * environment in place.
+     */
+    name?: string;
+    /**
+     * Suffix of web endpoint URLs in this environment
+     * (`<workspace>-<suffix>--<app>.modal.run`).
+     * @default the environment name
+     */
+    webhookSuffix?: string;
+    /** Most tasks (containers) running at once in this environment. */
+    maxConcurrentTasks?: number;
+    /** Most GPUs in use at once in this environment. */
+    maxConcurrentGpus?: number;
+    /**
+     * Monthly spend limit in US dollars for this environment. Removing it
+     * clears the limit. Budgets need a Modal plan that includes them;
+     * elsewhere the deploy fails with `EnvironmentBudgetsNotEnabled`.
+     */
+    budget?: number;
+    /**
+     * Require authentication for web endpoints and tunnels in this
+     * environment: `true` blocks unauthenticated traffic, `false` allows it,
+     * and `undefined` inherits the workspace default.
+     */
+    blockUnauthenticatedResources?: boolean;
+    /**
+     * Restrict the environment to explicit members (a managed environment).
+     * Members without an assignment in {@link roles} get
+     * {@link defaultMemberRole}.
+     * @default false
+     */
+    managed?: boolean;
+    /**
+     * Role every workspace member gets in a managed environment unless
+     * {@link roles} assigns one.
+     */
+    defaultMemberRole?: EnvironmentRole;
+    /**
+     * Explicit role assignments. Each listed principal gets its role; a
+     * principal that was assigned before and is no longer listed falls back
+     * to {@link defaultMemberRole}.
+     */
+    roles?: EnvironmentRoleAssignment[];
+}
+export interface EnvironmentAttributes {
+    /** Environment ID (`en-…`). */
+    environmentId: string;
+    /** Environment name. */
+    name: string;
+    /** Suffix of web endpoint URLs in this environment. */
+    webhookSuffix: string | undefined;
+    /** Whether this is the workspace's default environment. */
+    isDefault: boolean;
+    /** Whether membership is restricted (a managed environment). */
+    managed: boolean;
+}
+/**
+ * A Modal Environment: an isolated namespace inside a workspace for Apps,
+ * Volumes, Dicts, Queues, Secrets and Sandboxes, with its own concurrency
+ * limits, spend budget and member roles. Objects with the same name in two
+ * environments are different objects, so one environment per stage keeps
+ * stages apart.
+ *
+ * Modal environments have no tags. Ownership is inferred from Alchemy
+ * state: an environment found under an explicit `name` without prior state
+ * is reported as unowned.
+ *
+ * ### Creating an Environment
+ * **Example:** One environment per stage
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Agents = Modal.Environment("Agents", {});
+ * ```
+ *
+ * **Example:** Limits and a monthly budget
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Agents = Modal.Environment("Agents", {
+ *   maxConcurrentTasks: 50,
+ *   maxConcurrentGpus: 4,
+ *   budget: 200,
+ * });
+ * ```
+ *
+ * ### Access control
+ * **Example:** A managed environment with explicit roles
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Production = Modal.Environment("Production", {
+ *   name: "production",
+ *   managed: true,
+ *   defaultMemberRole: "viewer",
+ *   roles: [{ userId: "us-1234", role: "contributor" }],
+ *   blockUnauthenticatedResources: true,
+ * });
+ * ```
+ *
+ * ### Using the environment
+ * **Example:** Put objects in it
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Agents = Modal.Environment("Agents", {});
+ * export const Coder = Modal.App("Coder", { environment: Agents });
+ * export const Workspace = Modal.Volume("Workspace", { environment: Agents });
+ * ```
+ *
+ * ### Looking up an existing environment
+ * `Environment.lookup` references an environment Alchemy doesn't manage (created with
+ * the Modal CLI or by another stack). It is read during plan/deploy, never
+ * created, updated or deleted.
+ *
+ * **Example:** Reference an existing environment
+ * ```typescript
+ * const staging = Modal.Environment.lookup({ name: "staging" });
+ * ```
+ *
+ * @resource
+ * @product Environment
+ */
+export declare const Environment: import("alchemy/Resource").ResourceConstructor<Environment, Providers> & Effect.Effect<import("alchemy/Resource").ResourceConstructor<Environment, never>, never, never> & {
+    Self: import("alchemy/Self").Self<Environment>;
+    Provider: Provider.Provider<Environment>;
+    Aliases: readonly string[] | undefined;
+    ref(id: string, options?: {
+        stage?: string;
+        stack?: string;
+    }): Effect.Effect<Environment, never, never>;
+} & {
+    lookup(props: {
+        name: import("alchemy/Input").Input<string>;
+    }): Environment;
+} & ((id: string, props: import("./internal/Declared.ts").DeclaredProps<EnvironmentProps>) => Effect.Effect<Environment, never, Providers>);
+export type Environment = Resource<"Modal.Environment", EnvironmentProps, EnvironmentAttributes, never, Providers, EnvironmentLookup>;
+/**
+ * Props for {@link Environment.lookup}: find an environment this
+ * stack doesn't manage by its name.
+ */
+export interface EnvironmentLookup {
+    /** Environment name. */
+    name: string;
+}
+export declare const EnvironmentProvider: () => import("effect/Layer").Layer<Provider.Provider<Environment>, never, import("alchemy/Stack").Stack | import("alchemy/Stage").Stage | environment.ModalOpContext>;
+export {};
+//# sourceMappingURL=Environment.d.ts.map

package/lib/Environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Environment.d.ts","sources":["../src/Environment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,oCAAoC,CAAC;AAElE,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;;;;AAEhD,qBAAa,6BAA8B,SAAQ,mCAEjD;IACA,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;CAAG;AAEL,2CAA2C;AAC3C,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAC;AAWrE,6EAA6E;AAC7E,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,eAAe,CAAC;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,yBAAyB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;2IAAwE,CAAC;AAEjG,MAAM,MAAM,WAAW,GAAG,QAAQ,CAChC,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,EACL,SAAS,EACT,iBAAiB,CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAcD,eAAO,MAAM,mBAAmB,uKAkL7B,CAAC"}