1import type * as aiplatform from "@distilled.cloud/gcp/aiplatform_v1";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { RuntimeContext } from "../../RuntimeContext.ts";
5import type { GcpProjectMissing } from "../Environment.ts";
6
7/**
8 * A Vertex AI publisher model, e.g. Gemini. Publisher models are not
9 * Alchemy resources — they are addressed by id under a location.
10 */
11export interface PublisherModel {
12 /**
13 * Model id, e.g. `gemini-2.5-flash`.
14 */
15 model: string;
16 /**
17 * Vertex AI location serving the model. `global` routes to any region
18 * with capacity; pin a region (e.g. `us-central1`) for data residency.
19 * @default "global"
20 */
21 location?: string;
22 /**
23 * Model publisher.
24 * @default "google"
25 */
26 publisher?: string;
27}
28
29export interface GenerateContentRequest
30 extends aiplatform.GoogleCloudAiplatformV1GenerateContentRequest {}
31
32export type GenerateContentError =
33 | aiplatform.GenerateContentProjectsLocationsPublishersModelsError
34 | GcpProjectMissing;
35
36/**
37 * Runtime client returned by {@link GenerateContent}.
38 */
39export interface GenerateContentClient {
40 /**
41 * Full `generateContent` call against the bound model.
42 */
43 generate(
44 request: GenerateContentRequest,
45 ): Effect.Effect<
46 aiplatform.GoogleCloudAiplatformV1GenerateContentResponse,
47 GenerateContentError,
48 RuntimeContext
49 >;
50 /**
51 * Single-turn text generation: sends `prompt` as one user turn and
52 * returns the concatenated text parts of the first candidate.
53 * `options` is merged into the request (generation config, system
54 * instruction, safety settings, ...).
55 */
56 text(
57 prompt: string,
58 options?: Omit<GenerateContentRequest, "contents">,
59 ): Effect.Effect<string, GenerateContentError, RuntimeContext>;
60}
61
62/**
63 * Runtime binding for Vertex AI `generateContent` on a publisher model
64 * (Gemini).
65 *
66 * Bind it in a Function/Job init phase with a model id or a
67 * {@link PublisherModel} descriptor and provide
68 * {@link GenerateContentHttp}. At deploy time it grants the host's
69 * runtime service account `roles/aiplatform.user` on the project —
70 * Vertex AI publisher models have no resource-level IAM policy.
71 *
72 * ### Generating Text
73 * **Example:** Ask Gemini a question
74 * ```typescript
75 * const gemini = yield* GCP.AIPlatform.GenerateContent("gemini-2.5-flash");
76 * const answer = yield* gemini.text("Name three primary colors.");
77 * ```
78 *
79 * **Example:** Pin a region and tune generation
80 * ```typescript
81 * const gemini = yield* GCP.AIPlatform.GenerateContent({
82 * model: "gemini-2.5-flash",
83 * location: "us-central1",
84 * });
85 * const answer = yield* gemini.text("Write a haiku about rain.", {
86 * generationConfig: { temperature: 0.2, maxOutputTokens: 256 },
87 * });
88 * ```
89 *
90 * ### Full Requests
91 * **Example:** Multi-turn chat with a system instruction
92 * ```typescript
93 * const response = yield* gemini.generate({
94 * systemInstruction: { parts: [{ text: "Answer in one sentence." }] },
95 * contents: [
96 * { role: "user", parts: [{ text: "What is Cloud Run?" }] },
97 * { role: "model", parts: [{ text: "A serverless container platform." }] },
98 * { role: "user", parts: [{ text: "How is it billed?" }] },
99 * ],
100 * });
101 * const usage = response.usageMetadata?.totalTokenCount;
102 * ```
103 *
104 * @binding
105 * @category AIPlatform
106 */
107export interface GenerateContent extends Binding.Service<
108 GenerateContent,
109 "GCP.AIPlatform.GenerateContent",
110 (model: string | PublisherModel) => Effect.Effect<GenerateContentClient>
111> {}
112
113export const GenerateContent = Binding.Service<GenerateContent>(
114 "GCP.AIPlatform.GenerateContent",
115);