@firebase/ai 0.0.1

package/dist/src/types/enums.d.ts

@@ -0,0 +1,263 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Role is the producer of the content.
+ * @public
+ */
+export type Role = (typeof POSSIBLE_ROLES)[number];
+/**
+ * Possible roles.
+ * @public
+ */
+export declare const POSSIBLE_ROLES: readonly ["user", "model", "function", "system"];
+/**
+ * Harm categories that would cause prompts or candidates to be blocked.
+ * @public
+ */
+export declare enum HarmCategory {
+    HARM_CATEGORY_HATE_SPEECH = "HARM_CATEGORY_HATE_SPEECH",
+    HARM_CATEGORY_SEXUALLY_EXPLICIT = "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+    HARM_CATEGORY_HARASSMENT = "HARM_CATEGORY_HARASSMENT",
+    HARM_CATEGORY_DANGEROUS_CONTENT = "HARM_CATEGORY_DANGEROUS_CONTENT"
+}
+/**
+ * Threshold above which a prompt or candidate will be blocked.
+ * @public
+ */
+export declare enum HarmBlockThreshold {
+    /**
+     * Content with `NEGLIGIBLE` will be allowed.
+     */
+    BLOCK_LOW_AND_ABOVE = "BLOCK_LOW_AND_ABOVE",
+    /**
+     * Content with `NEGLIGIBLE` and `LOW` will be allowed.
+     */
+    BLOCK_MEDIUM_AND_ABOVE = "BLOCK_MEDIUM_AND_ABOVE",
+    /**
+     * Content with `NEGLIGIBLE`, `LOW`, and `MEDIUM` will be allowed.
+     */
+    BLOCK_ONLY_HIGH = "BLOCK_ONLY_HIGH",
+    /**
+     * All content will be allowed.
+     */
+    BLOCK_NONE = "BLOCK_NONE"
+}
+/**
+ * This property is not supported in the Gemini Developer API ({@link GoogleAIBackend}).
+ *
+ * @public
+ */
+export declare enum HarmBlockMethod {
+    /**
+     * The harm block method uses both probability and severity scores.
+     */
+    SEVERITY = "SEVERITY",
+    /**
+     * The harm block method uses the probability score.
+     */
+    PROBABILITY = "PROBABILITY"
+}
+/**
+ * Probability that a prompt or candidate matches a harm category.
+ * @public
+ */
+export declare enum HarmProbability {
+    /**
+     * Content has a negligible chance of being unsafe.
+     */
+    NEGLIGIBLE = "NEGLIGIBLE",
+    /**
+     * Content has a low chance of being unsafe.
+     */
+    LOW = "LOW",
+    /**
+     * Content has a medium chance of being unsafe.
+     */
+    MEDIUM = "MEDIUM",
+    /**
+     * Content has a high chance of being unsafe.
+     */
+    HIGH = "HIGH"
+}
+/**
+ * Harm severity levels.
+ * @public
+ */
+export declare enum HarmSeverity {
+    /**
+     * Negligible level of harm severity.
+     */
+    HARM_SEVERITY_NEGLIGIBLE = "HARM_SEVERITY_NEGLIGIBLE",
+    /**
+     * Low level of harm severity.
+     */
+    HARM_SEVERITY_LOW = "HARM_SEVERITY_LOW",
+    /**
+     * Medium level of harm severity.
+     */
+    HARM_SEVERITY_MEDIUM = "HARM_SEVERITY_MEDIUM",
+    /**
+     * High level of harm severity.
+     */
+    HARM_SEVERITY_HIGH = "HARM_SEVERITY_HIGH",
+    /**
+     * Harm severity is not supported.
+     *
+     * @remarks
+     * The GoogleAI backend does not support `HarmSeverity`, so this value is used as a fallback.
+     */
+    HARM_SEVERITY_UNSUPPORTED = "HARM_SEVERITY_UNSUPPORTED"
+}
+/**
+ * Reason that a prompt was blocked.
+ * @public
+ */
+export declare enum BlockReason {
+    /**
+     * Content was blocked by safety settings.
+     */
+    SAFETY = "SAFETY",
+    /**
+     * Content was blocked, but the reason is uncategorized.
+     */
+    OTHER = "OTHER",
+    /**
+     * Content was blocked because it contained terms from the terminology blocklist.
+     */
+    BLOCKLIST = "BLOCKLIST",
+    /**
+     * Content was blocked due to prohibited content.
+     */
+    PROHIBITED_CONTENT = "PROHIBITED_CONTENT"
+}
+/**
+ * Reason that a candidate finished.
+ * @public
+ */
+export declare enum FinishReason {
+    /**
+     * Natural stop point of the model or provided stop sequence.
+     */
+    STOP = "STOP",
+    /**
+     * The maximum number of tokens as specified in the request was reached.
+     */
+    MAX_TOKENS = "MAX_TOKENS",
+    /**
+     * The candidate content was flagged for safety reasons.
+     */
+    SAFETY = "SAFETY",
+    /**
+     * The candidate content was flagged for recitation reasons.
+     */
+    RECITATION = "RECITATION",
+    /**
+     * Unknown reason.
+     */
+    OTHER = "OTHER",
+    /**
+     * The candidate content contained forbidden terms.
+     */
+    BLOCKLIST = "BLOCKLIST",
+    /**
+     * The candidate content potentially contained prohibited content.
+     */
+    PROHIBITED_CONTENT = "PROHIBITED_CONTENT",
+    /**
+     * The candidate content potentially contained Sensitive Personally Identifiable Information (SPII).
+     */
+    SPII = "SPII",
+    /**
+     * The function call generated by the model was invalid.
+     */
+    MALFORMED_FUNCTION_CALL = "MALFORMED_FUNCTION_CALL"
+}
+/**
+ * @public
+ */
+export declare enum FunctionCallingMode {
+    /**
+     * Default model behavior; model decides to predict either a function call
+     * or a natural language response.
+     */
+    AUTO = "AUTO",
+    /**
+     * Model is constrained to always predicting a function call only.
+     * If `allowed_function_names` is set, the predicted function call will be
+     * limited to any one of `allowed_function_names`, else the predicted
+     * function call will be any one of the provided `function_declarations`.
+     */
+    ANY = "ANY",
+    /**
+     * Model will not predict any function call. Model behavior is same as when
+     * not passing any function declarations.
+     */
+    NONE = "NONE"
+}
+/**
+ * Content part modality.
+ * @public
+ */
+export declare enum Modality {
+    /**
+     * Unspecified modality.
+     */
+    MODALITY_UNSPECIFIED = "MODALITY_UNSPECIFIED",
+    /**
+     * Plain text.
+     */
+    TEXT = "TEXT",
+    /**
+     * Image.
+     */
+    IMAGE = "IMAGE",
+    /**
+     * Video.
+     */
+    VIDEO = "VIDEO",
+    /**
+     * Audio.
+     */
+    AUDIO = "AUDIO",
+    /**
+     * Document (for example, PDF).
+     */
+    DOCUMENT = "DOCUMENT"
+}
+/**
+ * Generation modalities to be returned in generation responses.
+ *
+ * @beta
+ */
+export declare const ResponseModality: {
+    /**
+     * Text.
+     * @beta
+     */
+    readonly TEXT: "TEXT";
+    /**
+     * Image.
+     * @beta
+     */
+    readonly IMAGE: "IMAGE";
+};
+/**
+ * Generation modalities to be returned in generation responses.
+ *
+ * @beta
+ */
+export type ResponseModality = (typeof ResponseModality)[keyof typeof ResponseModality];

package/dist/src/types/error.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { GenerateContentResponse } from './responses';
+/**
+ * Details object that may be included in an error response.
+ *
+ * @public
+ */
+export interface ErrorDetails {
+    '@type'?: string;
+    /** The reason for the error. */
+    reason?: string;
+    /** The domain where the error occurred. */
+    domain?: string;
+    /** Additional metadata about the error. */
+    metadata?: Record<string, unknown>;
+    /** Any other relevant information about the error. */
+    [key: string]: unknown;
+}
+/**
+ * Details object that contains data originating from a bad HTTP response.
+ *
+ * @public
+ */
+export interface CustomErrorData {
+    /** HTTP status code of the error response. */
+    status?: number;
+    /** HTTP status text of the error response. */
+    statusText?: string;
+    /** Response from a {@link GenerateContentRequest} */
+    response?: GenerateContentResponse;
+    /** Optional additional details about the error. */
+    errorDetails?: ErrorDetails[];
+}
+/**
+ * Standardized error codes that {@link AIError} can have.
+ *
+ * @public
+ */
+export declare const enum AIErrorCode {
+    /** A generic error occurred. */
+    ERROR = "error",
+    /** An error occurred in a request. */
+    REQUEST_ERROR = "request-error",
+    /** An error occurred in a response. */
+    RESPONSE_ERROR = "response-error",
+    /** An error occurred while performing a fetch. */
+    FETCH_ERROR = "fetch-error",
+    /** An error associated with a Content object.  */
+    INVALID_CONTENT = "invalid-content",
+    /** An error due to the Firebase API not being enabled in the Console. */
+    API_NOT_ENABLED = "api-not-enabled",
+    /** An error due to invalid Schema input.  */
+    INVALID_SCHEMA = "invalid-schema",
+    /** An error occurred due to a missing Firebase API key. */
+    NO_API_KEY = "no-api-key",
+    /** An error occured due to a missing Firebase app ID. */
+    NO_APP_ID = "no-app-id",
+    /** An error occurred due to a model name not being specified during initialization. */
+    NO_MODEL = "no-model",
+    /** An error occurred due to a missing project ID. */
+    NO_PROJECT_ID = "no-project-id",
+    /** An error occurred while parsing. */
+    PARSE_FAILED = "parse-failed",
+    /** An error occured due an attempt to use an unsupported feature. */
+    UNSUPPORTED = "unsupported"
+}

package/dist/src/types/googleai.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Tool, GenerationConfig, Citation, FinishReason, GroundingMetadata, PromptFeedback, SafetyRating, UsageMetadata } from '../public-types';
+import { Content, Part } from './content';
+/**
+ * @internal
+ */
+export interface GoogleAICountTokensRequest {
+    generateContentRequest: {
+        model: string;
+        contents: Content[];
+        systemInstruction?: string | Part | Content;
+        tools?: Tool[];
+        generationConfig?: GenerationConfig;
+    };
+}
+/**
+ * @internal
+ */
+export interface GoogleAIGenerateContentResponse {
+    candidates?: GoogleAIGenerateContentCandidate[];
+    promptFeedback?: PromptFeedback;
+    usageMetadata?: UsageMetadata;
+}
+/**
+ * @internal
+ */
+export interface GoogleAIGenerateContentCandidate {
+    index: number;
+    content: Content;
+    finishReason?: FinishReason;
+    finishMessage?: string;
+    safetyRatings?: SafetyRating[];
+    citationMetadata?: GoogleAICitationMetadata;
+    groundingMetadata?: GroundingMetadata;
+}
+/**
+ * @internal
+ */
+export interface GoogleAICitationMetadata {
+    citationSources: Citation[];
+}

package/dist/src/types/imagen/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './requests';
+export * from './responses';

package/dist/src/types/imagen/internal.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ImagenGenerationConfig, ImagenSafetySettings } from './requests';
+/**
+ * A response from the REST API is expected to look like this in the success case:
+ * {
+ *   "predictions": [
+ *     {
+ *       "mimeType": "image/png",
+ *       "bytesBase64Encoded": "iVBORw0KG..."
+ *     },
+ *     {
+ *       "mimeType": "image/png",
+ *       "bytesBase64Encoded": "i4BOtw0KG..."
+ *     }
+ *   ]
+ * }
+ *
+ * And like this in the failure case:
+ * {
+ *   "predictions": [
+ *     {
+ *       "raiFilteredReason": "..."
+ *     }
+ *   ]
+ * }
+ *
+ * @internal
+ */
+export interface ImagenResponseInternal {
+    predictions?: Array<{
+        /**
+         * The MIME type of the generated image.
+         */
+        mimeType?: string;
+        /**
+         * The image data encoded as a base64 string.
+         */
+        bytesBase64Encoded?: string;
+        /**
+         * The GCS URI where the image was stored.
+         */
+        gcsUri?: string;
+        /**
+         * The reason why the image was filtered.
+         */
+        raiFilteredReason?: string;
+    }>;
+}
+/**
+ * The parameters to be sent in the request body of the HTTP call
+ * to the Vertex AI backend.
+ *
+ * We need a seperate internal-only interface for this because the REST
+ * API expects different parameter names than what we show to our users.
+ *
+ * Sample request body JSON:
+ * {
+ *   "instances": [
+ *     {
+ *       "prompt": "Portrait of a golden retriever on a beach."
+ *     }
+ *   ],
+ *   "parameters": {
+ *     "mimeType": "image/png",
+ *     "safetyFilterLevel": "block_low_and_above",
+ *     "personGeneration": "allow_all",
+ *     "sampleCount": 2,
+ *     "includeRaiReason": true,
+ *     "aspectRatio": "9:16"
+ *   }
+ * }
+ *
+ * See the Google Cloud docs: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/imagen-api#-drest
+ *
+ * @internal
+ */
+export interface PredictRequestBody {
+    instances: [
+        {
+            prompt: string;
+        }
+    ];
+    parameters: {
+        sampleCount: number;
+        aspectRatio?: string;
+        outputOptions?: {
+            mimeType: string;
+            compressionQuality?: number;
+        };
+        negativePrompt?: string;
+        storageUri?: string;
+        addWatermark?: boolean;
+        safetyFilterLevel?: string;
+        personGeneration?: string;
+        includeRaiReason: boolean;
+    };
+}
+/**
+ * Contains all possible REST API paramaters that are provided by the caller.
+ *
+ * @internal
+ */
+export type ImagenGenerationParams = {
+    /**
+     * The Cloud Storage for Firebase bucket URI where the images should be stored
+     * (for GCS requests only).
+     */
+    gcsURI?: string;
+} & ImagenGenerationConfig & ImagenSafetySettings;