sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ AIPlatform/ GenerateContent.ts

import type * as aiplatform from "@distilled.cloud/gcp/aiplatform_v1";
import * as Binding from "alchemy/Binding";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import type * as Effect from "effect/Effect";
import type { GcpProjectMissing } from "../Environment.ts";

/**
 * A Vertex AI publisher model, e.g. Gemini. Publisher models are not
 * Alchemy resources — they are addressed by id under a location.
 */
export interface PublisherModel {
  /**
   * Model id, e.g. `gemini-2.5-flash`.
   */
  model: string;
  /**
   * Vertex AI location serving the model. `global` routes to any region
   * with capacity; pin a region (e.g. `us-central1`) for data residency.
   * @default "global"
   */
  location?: string;
  /**
   * Model publisher.
   * @default "google"
   */
  publisher?: string;
}

export interface GenerateContentRequest
  extends aiplatform.GoogleCloudAiplatformV1GenerateContentRequest {}

export type GenerateContentError =
  | aiplatform.GenerateContentProjectsLocationsPublishersModelsError
  | GcpProjectMissing;

/**
 * Runtime client returned by {@link GenerateContent}.
 */
export interface GenerateContentClient {
  /**
   * Full `generateContent` call against the bound model.
   */
  generate(
    request: GenerateContentRequest,
  ): Effect.Effect<
    aiplatform.GoogleCloudAiplatformV1GenerateContentResponse,
    GenerateContentError,
    RuntimeContext
  >;
  /**
   * Single-turn text generation: sends `prompt` as one user turn and
   * returns the concatenated text parts of the first candidate.
   * `options` is merged into the request (generation config, system
   * instruction, safety settings, ...).
   */
  text(
    prompt: string,
    options?: Omit<GenerateContentRequest, "contents">,
  ): Effect.Effect<string, GenerateContentError, RuntimeContext>;
}

/**
 * Runtime binding for Vertex AI `generateContent` on a publisher model
 * (Gemini).
 *
 * Bind it in a Function/Job init phase with a model id or a
 * {@link PublisherModel} descriptor and provide
 * {@link GenerateContentHttp}. At deploy time it grants the host's
 * runtime service account `roles/aiplatform.user` on the project —
 * Vertex AI publisher models have no resource-level IAM policy.
 *
 * ### Generating Text
 * **Example:** Ask Gemini a question
 * ```typescript
 * const gemini = yield* GCP.AIPlatform.GenerateContent("gemini-2.5-flash");
 * const answer = yield* gemini.text("Name three primary colors.");
 * ```
 *
 * **Example:** Pin a region and tune generation
 * ```typescript
 * const gemini = yield* GCP.AIPlatform.GenerateContent({
 *   model: "gemini-2.5-flash",
 *   location: "us-central1",
 * });
 * const answer = yield* gemini.text("Write a haiku about rain.", {
 *   generationConfig: { temperature: 0.2, maxOutputTokens: 256 },
 * });
 * ```
 *
 * ### Full Requests
 * **Example:** Multi-turn chat with a system instruction
 * ```typescript
 * const response = yield* gemini.generate({
 *   systemInstruction: { parts: [{ text: "Answer in one sentence." }] },
 *   contents: [
 *     { role: "user", parts: [{ text: "What is Cloud Run?" }] },
 *     { role: "model", parts: [{ text: "A serverless container platform." }] },
 *     { role: "user", parts: [{ text: "How is it billed?" }] },
 *   ],
 * });
 * const usage = response.usageMetadata?.totalTokenCount;
 * ```
 *
 * @binding
 * @category AIPlatform
 */
export interface GenerateContent extends Binding.Service<
  GenerateContent,
  "GCP.AIPlatform.GenerateContent",
  (model: string | PublisherModel) => Effect.Effect<GenerateContentClient>
> {}

export const GenerateContent = Binding.Service<GenerateContent>("GCP.AIPlatform.GenerateContent");