@nshiab/simple-data-analysis 5.21.1 → 6.0.1

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/embeddingOptions.d.ts

@@ -0,0 +1,186 @@
+/** The service family used to generate an embedding. */
+export type EmbeddingProvider = "gemini" | "ollama";
+/** The resolved service backend used to generate an embedding. */
+export type EmbeddingBackend = "gemini-api" | "vertex" | "ollama";
+/** Options shared by every embedding provider. */
+export interface EmbeddingCommonOptions {
+    /** The embedding model. Defaults to `AI_EMBEDDINGS_MODEL`. */
+    model?: string;
+    /** Whether to persist and reuse the embedding response. Defaults to `true`. */
+    cache?: boolean;
+    /** Whether to log request and timing information. */
+    verbose?: boolean;
+}
+/** Options that explicitly select the Gemini API. */
+export interface GeminiEmbeddingOptions extends EmbeddingCommonOptions {
+    /** Explicitly selects the Google embedding provider. */
+    provider: "gemini";
+    /** Keeps the request on the Gemini API rather than Vertex AI. */
+    vertex?: false;
+    /** Gemini API key. Defaults to `AI_KEY`. */
+    apiKey?: string;
+    /** Vertex projects are not valid for the Gemini API. */
+    project?: never;
+    /** Vertex locations are not valid for the Gemini API. */
+    location?: never;
+    /** Ollama clients are not valid for the Gemini API. */
+    ollama?: never;
+    /** Ollama context windows are not valid for the Gemini API. */
+    contextWindow?: never;
+}
+/** Options that explicitly select Vertex AI. */
+export interface VertexEmbeddingOptions extends EmbeddingCommonOptions {
+    /** Explicitly selects the Google embedding provider. */
+    provider: "gemini";
+    /** Selects the Vertex AI backend. */
+    vertex: true;
+    /** Vertex Express Mode API key. */
+    apiKey?: string;
+    /** Google Cloud project. Defaults to `AI_PROJECT`. */
+    project?: string;
+    /** Google Cloud location. Defaults to `AI_LOCATION`. */
+    location?: string;
+    /** Ollama clients are not valid for Vertex AI. */
+    ollama?: never;
+    /** Ollama context windows are not valid for Vertex AI. */
+    contextWindow?: never;
+}
+/** Minimal Ollama client contract used for embedding requests. */
+export interface OllamaEmbeddingClient {
+    /**
+     * Non-secret deployment endpoint for custom adapters that are not instances
+     * of the Ollama SDK client.
+     */
+    embeddingEndpoint?: string;
+    /** Sends an embedding request to Ollama. */
+    embed(request: {
+        model: string;
+        input: string;
+        options?: {
+            num_ctx?: number;
+        };
+    }): Promise<{
+        embeddings: number[][];
+    }>;
+}
+/** Options that explicitly select Ollama. */
+export interface OllamaEmbeddingOptions extends EmbeddingCommonOptions {
+    /** Explicitly selects Ollama. */
+    provider: "ollama";
+    /** A custom Ollama client. */
+    ollama?: OllamaEmbeddingClient;
+    /** The model context-window size sent to Ollama. */
+    contextWindow?: number;
+    /** Gemini and Vertex API keys are not valid for Ollama. */
+    apiKey?: never;
+    /** Vertex selection is not valid for Ollama. */
+    vertex?: never;
+    /** Vertex projects are not valid for Ollama. */
+    project?: never;
+    /** Vertex locations are not valid for Ollama. */
+    location?: never;
+}
+/**
+ * Provider-independent options. The provider, backend, and credentials are
+ * selected entirely from the environment.
+ */
+export interface EnvironmentEmbeddingOptions extends EmbeddingCommonOptions {
+    /** Omit the discriminator to select the provider from the environment. */
+    provider?: never;
+    /** Direct credentials require an explicit provider. */
+    apiKey?: never;
+    /** Direct backend selection requires an explicit provider. */
+    vertex?: never;
+    /** Direct deployment selection requires an explicit provider. */
+    project?: never;
+    /** Direct deployment selection requires an explicit provider. */
+    location?: never;
+    /** Custom clients require an explicit provider. */
+    ollama?: never;
+    /** Provider-specific semantic options require an explicit provider. */
+    contextWindow?: never;
+}
+/** Exact provider-aware options accepted by {@link getEmbedding}. */
+export type GetEmbeddingOptions = EnvironmentEmbeddingOptions | GeminiEmbeddingOptions | VertexEmbeddingOptions | OllamaEmbeddingOptions;
+/** Environment fields used when resolving an embedding request. */
+export type EmbeddingEnvironment = Record<string, string | undefined>;
+/** Fields shared by every canonical embedding identity. */
+export interface EmbeddingIdentityBase {
+    /** Cache-compatibility schema for the canonical identity. */
+    schemaVersion: 2;
+    /** Resolved embedding model. */
+    model: string;
+}
+/** Canonical identity for a Gemini API embedding vector space. */
+export interface GeminiEmbeddingIdentity extends EmbeddingIdentityBase {
+    /** Resolved provider. */
+    provider: "gemini";
+    /** Resolved Gemini API backend. */
+    backend: "gemini-api";
+}
+/** Canonical identity for a Vertex AI embedding vector space. */
+export interface VertexEmbeddingIdentity extends EmbeddingIdentityBase {
+    /** Resolved provider. */
+    provider: "gemini";
+    /** Resolved Vertex AI backend. */
+    backend: "vertex";
+    /** Resolved Google Cloud project, when configured. */
+    project?: string;
+    /** Resolved Google Cloud location, when configured. */
+    location?: string;
+}
+/** Canonical identity for an Ollama embedding vector space. */
+export interface OllamaEmbeddingIdentity extends EmbeddingIdentityBase {
+    /** Resolved provider. */
+    provider: "ollama";
+    /** Resolved Ollama backend. */
+    backend: "ollama";
+    /** Non-secret Ollama endpoint identity. */
+    endpoint: string;
+    /** Context-window size when explicitly configured. */
+    contextWindow?: number;
+}
+/**
+ * Non-secret fields that determine whether two embedding requests share a
+ * compatible vector space.
+ */
+export type EmbeddingIdentity = GeminiEmbeddingIdentity | VertexEmbeddingIdentity | OllamaEmbeddingIdentity;
+export interface ResolvedEmbeddingRequest {
+    /** Canonical non-secret identity. */
+    identity: EmbeddingIdentity;
+    /** Resolved Gemini or Vertex API key. */
+    apiKey?: string;
+    /** Resolved Vertex project. */
+    project?: string;
+    /** Resolved Vertex location. */
+    location?: string;
+    /** Custom Ollama client, when provided. */
+    ollama?: OllamaEmbeddingClient;
+}
+/**
+ * Resolves the provider, backend, model, deployment, and semantic options once.
+ * The returned identity never includes credentials or cache/logging controls.
+ */
+export declare function resolveEmbeddingRequest(typedOptions?: GetEmbeddingOptions, environment?: EmbeddingEnvironment): ResolvedEmbeddingRequest;
+/**
+ * Returns the canonical, non-secret identity for an embedding request.
+ * Downstream persisted data can compare this value to decide whether vectors
+ * are compatible with the current request.
+ *
+ * @param options Provider-aware embedding options.
+ * @param environment Environment used to resolve omitted values.
+ * @returns The canonical identity used by embedding caches.
+ *
+ * @example
+ * ```ts
+ * const identity = getEmbeddingIdentity({
+ *   provider: "ollama",
+ *   model: "nomic-embed-text",
+ *   contextWindow: 8192,
+ * });
+ * ```
+ *
+ * @category AI
+ */
+export declare function getEmbeddingIdentity(options?: GetEmbeddingOptions, environment?: EmbeddingEnvironment): EmbeddingIdentity;
+//# sourceMappingURL=embeddingOptions.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/embeddingOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddingOptions.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/embeddingOptions.ts"],"names":[],"mappings":"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"}

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/embeddingOptions.js

@@ -0,0 +1,124 @@
+import process from "node:process";
+const EMBEDDING_IDENTITY_SCHEMA_VERSION = 2;
+function isOllamaEmbeddingClient(value) {
+    return typeof value === "object" && value !== null && "embed" in value &&
+        typeof value.embed === "function";
+}
+function resolveProvider(options, environment) {
+    if (options.provider) {
+        return options.provider;
+    }
+    // Runtime support for the pre-provider API. The public option type requires
+    // an explicit provider whenever the Ollama-specific field is used.
+    if (options.ollama === true || isOllamaEmbeddingClient(options.ollama)) {
+        return "ollama";
+    }
+    if (options.ollama === false) {
+        return "gemini";
+    }
+    const environmentProvider = environment.AI_EMBEDDINGS_PROVIDER;
+    if (environmentProvider) {
+        if (environmentProvider !== "gemini" && environmentProvider !== "ollama") {
+            throw new Error('AI_EMBEDDINGS_PROVIDER must be either "gemini" or "ollama".');
+        }
+        return environmentProvider;
+    }
+    return environment.OLLAMA ? "ollama" : "gemini";
+}
+function sanitizeEndpoint(endpoint) {
+    const url = new URL(endpoint);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    const pathname = url.pathname === "/" ? "" : url.pathname.replace(/\/$/, "");
+    return `${url.origin}${pathname}`;
+}
+function getOllamaEndpoint(client) {
+    if (!client)
+        return "http://127.0.0.1:11434";
+    const sdkEndpoint = client.config?.host;
+    const endpoint = client.embeddingEndpoint ??
+        (typeof sdkEndpoint === "string" ? sdkEndpoint : undefined);
+    if (!endpoint) {
+        throw new Error("Custom Ollama embedding clients must provide a non-secret embeddingEndpoint for cache identity.");
+    }
+    return sanitizeEndpoint(endpoint);
+}
+/**
+ * Resolves the provider, backend, model, deployment, and semantic options once.
+ * The returned identity never includes credentials or cache/logging controls.
+ */
+export function resolveEmbeddingRequest(typedOptions = {}, environment = process.env) {
+    const options = typedOptions;
+    const provider = resolveProvider(options, environment);
+    const model = options.model ?? environment.AI_EMBEDDINGS_MODEL;
+    if (!model) {
+        throw new Error("Model not specified. Use the AI_EMBEDDINGS_MODEL environment variable or pass it as an option.");
+    }
+    if (provider === "ollama") {
+        const customClient = isOllamaEmbeddingClient(options.ollama)
+            ? options.ollama
+            : undefined;
+        const identity = {
+            schemaVersion: EMBEDDING_IDENTITY_SCHEMA_VERSION,
+            provider,
+            backend: "ollama",
+            model,
+            endpoint: getOllamaEndpoint(customClient),
+            ...(options.contextWindow === undefined
+                ? {}
+                : { contextWindow: options.contextWindow }),
+        };
+        return { identity, ollama: customClient };
+    }
+    const explicitlySelected = options.provider === "gemini";
+    const project = options.project ?? environment.AI_PROJECT;
+    const location = options.location ?? environment.AI_LOCATION;
+    const vertex = options.vertex === true ||
+        (!explicitlySelected && Boolean(project) && Boolean(location));
+    const apiKey = options.apiKey ?? environment.AI_KEY;
+    if (vertex) {
+        const identity = {
+            schemaVersion: EMBEDDING_IDENTITY_SCHEMA_VERSION,
+            provider,
+            backend: "vertex",
+            model,
+            ...(project === undefined ? {} : { project }),
+            ...(location === undefined ? {} : { location }),
+        };
+        return { identity, apiKey, project, location };
+    }
+    return {
+        identity: {
+            schemaVersion: EMBEDDING_IDENTITY_SCHEMA_VERSION,
+            provider,
+            backend: "gemini-api",
+            model,
+        },
+        apiKey,
+    };
+}
+/**
+ * Returns the canonical, non-secret identity for an embedding request.
+ * Downstream persisted data can compare this value to decide whether vectors
+ * are compatible with the current request.
+ *
+ * @param options Provider-aware embedding options.
+ * @param environment Environment used to resolve omitted values.
+ * @returns The canonical identity used by embedding caches.
+ *
+ * @example
+ * ```ts
+ * const identity = getEmbeddingIdentity({
+ *   provider: "ollama",
+ *   model: "nomic-embed-text",
+ *   contextWindow: 8192,
+ * });
+ * ```
+ *
+ * @category AI
+ */
+export function getEmbeddingIdentity(options = {}, environment = process.env) {
+    return resolveEmbeddingRequest(options, environment).identity;
+}

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/getEmbedding.d.ts

@@ -0,0 +1,83 @@
+import { type GetEmbeddingOptions } from "./embeddingOptions.js";
+/**
+ * Generates a numerical embedding (vector representation) for a given text string. Embeddings are crucial for various natural language processing (NLP) tasks, including semantic search, text classification, clustering, and anomaly detection, as they allow text to be processed and compared mathematically.
+ *
+ * This function supports both Google's Gemini AI models and local models running with Ollama. It provides options for authentication, model selection, and caching to optimize performance and cost.
+ *
+ * **Authentication**:
+ * With no explicit provider, credentials, model information, and provider selection come from environment variables (`AI_KEY`, `AI_PROJECT`, `AI_LOCATION`, `AI_EMBEDDINGS_MODEL`, `AI_EMBEDDINGS_PROVIDER`). Providerless options intentionally contain only fields shared by every provider.
+ *
+ * **Local Models**:
+ * To use a local model with Ollama, pass `provider: "ollama"`, or set `AI_EMBEDDINGS_PROVIDER=ollama` (the legacy `OLLAMA` environment variable is also supported), and ensure Ollama is running. A custom `Ollama` client can be passed in the provider-specific `ollama` option.
+ *
+ * **Caching**:
+ * Responses are cached by default in a local `.journalism-cache` directory. If the same request is made again, the cached response will be returned, avoiding redundant API calls. Set `cache` to `false` to disable caching. Remember to add `.journalism-cache` to your `.gitignore` file.
+ *
+ * @param text The input text string for which to generate the embedding.
+ * @param options Configuration options for the embedding generation.
+ * @param options.provider Explicitly selects Gemini/Vertex or Ollama. When omitted, `AI_EMBEDDINGS_PROVIDER` is used, then the legacy `OLLAMA` fallback, then Gemini.
+ * @param options.model The specific embedding model to use (e.g., 'text-embedding-004'). Defaults to the `AI_EMBEDDINGS_MODEL` environment variable.
+ * @param options.apiKey Your Gemini API or Vertex Express Mode API key. Defaults to the `AI_KEY` environment variable.
+ * @param options.vertex If `true`, explicitly selects the Vertex AI backend for the Google provider.
+ * @param options.project Your Google Cloud project ID for Vertex AI. Defaults to the `AI_PROJECT` environment variable.
+ * @param options.location The Google Cloud location for your Vertex AI project. Defaults to the `AI_LOCATION` environment variable.
+ * @param options.cache If `true`, enables caching of the embedding response. Defaults to `true`.
+ * @param options.ollama A custom Ollama client. Boolean selection remains supported at runtime for compatibility but is deprecated; use `provider: "ollama"` instead.
+ * @param options.verbose If `true`, logs additional information such as execution time and the truncated input text. Defaults to `false`.
+ *   @param options.contextWindow - An option to specify the context window size for Ollama models. By default, Ollama sets this depending on the model, which can be lower than the actual maximum context window size of the model.
+ *
+ * @returns A promise that resolves to an array of numbers representing the generated embedding.
+ *
+ * @example
+ * ```ts
+ * // Environment-selected usage. Configure AI_EMBEDDINGS_PROVIDER,
+ * // AI_EMBEDDINGS_MODEL, and the matching credentials first.
+ * const embedding = await getEmbedding("The quick brown fox jumps over the lazy dog.");
+ * console.log(embedding); // [0.012, -0.034, ..., 0.056] (example output)
+ * ```
+ * @example
+ * ```ts
+ * // Embeddings are cached by default.
+ * const cachedEmbedding = await getEmbedding("Artificial intelligence is transforming industries.");
+ * console.log(cachedEmbedding);
+ * ```
+ * @example
+ * ```ts
+ * // Generate an embedding using a specific model and API key.
+ * const customEmbedding = await getEmbedding("Machine learning is a subset of AI.", {
+ *   provider: "gemini",
+ *   model: "another-embedding-model",
+ *   apiKey: "your_custom_api_key"
+ * });
+ * console.log(customEmbedding);
+ * ```
+ * @example
+ * ```ts
+ * // Explicit Vertex AI usage.
+ * const vertexEmbedding = await getEmbedding("Local reporting matters.", {
+ *   provider: "gemini",
+ *   vertex: true,
+ *   model: "text-embedding-004",
+ *   project: "your-project",
+ *   location: "northamerica-northeast1",
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Explicit Ollama usage.
+ * const ollamaEmbedding = await getEmbedding("Local reporting matters.", {
+ *   provider: "ollama",
+ *   model: "nomic-embed-text",
+ *   contextWindow: 8192,
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Generate an embedding with verbose logging.
+ * const verboseEmbedding = await getEmbedding("The quick brown fox jumps over the lazy dog.", { verbose: true });
+ * console.log(verboseEmbedding);
+ * ```
+ * @category AI
+ */
+export default function getEmbedding(text: string, options?: GetEmbeddingOptions): Promise<number[]>;
+//# sourceMappingURL=getEmbedding.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/getEmbedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getEmbedding.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/getEmbedding.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,uBAAuB,CAAC;AAG/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,wBAA8B,YAAY,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAiHnB"}

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/getEmbedding.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { GoogleGenAI } from "@google/genai";
+import ollama from "ollama";
+import crypto from "node:crypto";
+import { resolveEmbeddingRequest, } from "./embeddingOptions.js";
+import formatDuration from "./helpers/formatDuration.js";
+/**
+ * Generates a numerical embedding (vector representation) for a given text string. Embeddings are crucial for various natural language processing (NLP) tasks, including semantic search, text classification, clustering, and anomaly detection, as they allow text to be processed and compared mathematically.
+ *
+ * This function supports both Google's Gemini AI models and local models running with Ollama. It provides options for authentication, model selection, and caching to optimize performance and cost.
+ *
+ * **Authentication**:
+ * With no explicit provider, credentials, model information, and provider selection come from environment variables (`AI_KEY`, `AI_PROJECT`, `AI_LOCATION`, `AI_EMBEDDINGS_MODEL`, `AI_EMBEDDINGS_PROVIDER`). Providerless options intentionally contain only fields shared by every provider.
+ *
+ * **Local Models**:
+ * To use a local model with Ollama, pass `provider: "ollama"`, or set `AI_EMBEDDINGS_PROVIDER=ollama` (the legacy `OLLAMA` environment variable is also supported), and ensure Ollama is running. A custom `Ollama` client can be passed in the provider-specific `ollama` option.
+ *
+ * **Caching**:
+ * Responses are cached by default in a local `.journalism-cache` directory. If the same request is made again, the cached response will be returned, avoiding redundant API calls. Set `cache` to `false` to disable caching. Remember to add `.journalism-cache` to your `.gitignore` file.
+ *
+ * @param text The input text string for which to generate the embedding.
+ * @param options Configuration options for the embedding generation.
+ * @param options.provider Explicitly selects Gemini/Vertex or Ollama. When omitted, `AI_EMBEDDINGS_PROVIDER` is used, then the legacy `OLLAMA` fallback, then Gemini.
+ * @param options.model The specific embedding model to use (e.g., 'text-embedding-004'). Defaults to the `AI_EMBEDDINGS_MODEL` environment variable.
+ * @param options.apiKey Your Gemini API or Vertex Express Mode API key. Defaults to the `AI_KEY` environment variable.
+ * @param options.vertex If `true`, explicitly selects the Vertex AI backend for the Google provider.
+ * @param options.project Your Google Cloud project ID for Vertex AI. Defaults to the `AI_PROJECT` environment variable.
+ * @param options.location The Google Cloud location for your Vertex AI project. Defaults to the `AI_LOCATION` environment variable.
+ * @param options.cache If `true`, enables caching of the embedding response. Defaults to `true`.
+ * @param options.ollama A custom Ollama client. Boolean selection remains supported at runtime for compatibility but is deprecated; use `provider: "ollama"` instead.
+ * @param options.verbose If `true`, logs additional information such as execution time and the truncated input text. Defaults to `false`.
+ *   @param options.contextWindow - An option to specify the context window size for Ollama models. By default, Ollama sets this depending on the model, which can be lower than the actual maximum context window size of the model.
+ *
+ * @returns A promise that resolves to an array of numbers representing the generated embedding.
+ *
+ * @example
+ * ```ts
+ * // Environment-selected usage. Configure AI_EMBEDDINGS_PROVIDER,
+ * // AI_EMBEDDINGS_MODEL, and the matching credentials first.
+ * const embedding = await getEmbedding("The quick brown fox jumps over the lazy dog.");
+ * console.log(embedding); // [0.012, -0.034, ..., 0.056] (example output)
+ * ```
+ * @example
+ * ```ts
+ * // Embeddings are cached by default.
+ * const cachedEmbedding = await getEmbedding("Artificial intelligence is transforming industries.");
+ * console.log(cachedEmbedding);
+ * ```
+ * @example
+ * ```ts
+ * // Generate an embedding using a specific model and API key.
+ * const customEmbedding = await getEmbedding("Machine learning is a subset of AI.", {
+ *   provider: "gemini",
+ *   model: "another-embedding-model",
+ *   apiKey: "your_custom_api_key"
+ * });
+ * console.log(customEmbedding);
+ * ```
+ * @example
+ * ```ts
+ * // Explicit Vertex AI usage.
+ * const vertexEmbedding = await getEmbedding("Local reporting matters.", {
+ *   provider: "gemini",
+ *   vertex: true,
+ *   model: "text-embedding-004",
+ *   project: "your-project",
+ *   location: "northamerica-northeast1",
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Explicit Ollama usage.
+ * const ollamaEmbedding = await getEmbedding("Local reporting matters.", {
+ *   provider: "ollama",
+ *   model: "nomic-embed-text",
+ *   contextWindow: 8192,
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Generate an embedding with verbose logging.
+ * const verboseEmbedding = await getEmbedding("The quick brown fox jumps over the lazy dog.", { verbose: true });
+ * console.log(verboseEmbedding);
+ * ```
+ * @category AI
+ */
+export default async function getEmbedding(text, options = {}) {
+    const start = Date.now();
+    const resolved = resolveEmbeddingRequest(options);
+    const { identity } = resolved;
+    const model = identity.model;
+    const cache = options.cache ?? true;
+    if (options.verbose) {
+        console.log(`\nText for ${model}:`);
+        console.log(text.length > 50 ? `${text.slice(0, 50)}...` : text);
+    }
+    const cacheKeyInput = { identity, text };
+    let cacheFileJSON;
+    if (cache) {
+        const cachePath = "./.journalism-cache";
+        if (!existsSync(cachePath)) {
+            mkdirSync(cachePath);
+        }
+        const hash = crypto
+            .createHash("sha256")
+            .update(JSON.stringify(cacheKeyInput))
+            .digest("hex");
+        cacheFileJSON =
+            `${cachePath}/getEmbedding-v${identity.schemaVersion}-${hash}.json`;
+        if (existsSync(cacheFileJSON)) {
+            const cachedResponse = JSON.parse(readFileSync(cacheFileJSON, "utf-8"));
+            if (options.verbose) {
+                console.log("\nReturning cached JSON response.");
+            }
+            return cachedResponse;
+        }
+        else {
+            if (options.verbose) {
+                console.log("\nCache missed. Generating new response...");
+            }
+        }
+    }
+    let rawResponse;
+    if (identity.backend === "ollama") {
+        const client = resolved.ollama ?? ollama;
+        const response = await client.embed({
+            model,
+            input: text,
+            options: {
+                num_ctx: identity.contextWindow,
+            },
+        });
+        rawResponse = response.embeddings;
+    }
+    else {
+        if (identity.backend === "gemini-api" && !resolved.apiKey) {
+            throw new Error('No Gemini API key found. Set AI_KEY or pass apiKey with provider: "gemini".');
+        }
+        if (identity.backend === "vertex" && !resolved.apiKey &&
+            !(resolved.project && resolved.location)) {
+            throw new Error("No Vertex credentials found. Set AI_PROJECT and AI_LOCATION, or pass an API key for Vertex Express Mode.");
+        }
+        const client = new GoogleGenAI({
+            apiKey: resolved.apiKey,
+            vertexai: identity.backend === "vertex",
+            project: resolved.project,
+            location: resolved.location,
+        });
+        const response = await client.models.embedContent({
+            model,
+            contents: text,
+        });
+        rawResponse = response.embeddings;
+    }
+    if (!Array.isArray(rawResponse) || rawResponse.length === 0) {
+        throw new Error("Invalid response from the API. Please check your model and input.");
+    }
+    const firstEmbedding = rawResponse[0];
+    const returnedResponse = Array.isArray(firstEmbedding)
+        ? firstEmbedding
+        : typeof firstEmbedding === "object" && firstEmbedding !== null &&
+            "values" in firstEmbedding && Array.isArray(firstEmbedding.values)
+            ? firstEmbedding.values
+            : undefined;
+    if (!Array.isArray(returnedResponse) || typeof returnedResponse[0] !== "number") {
+        throw new Error("Invalid response from the API. Please check your model and input.");
+    }
+    if (cache && cacheFileJSON) {
+        if (returnedResponse && Array.isArray(returnedResponse)) {
+            writeFileSync(cacheFileJSON, JSON.stringify(returnedResponse));
+            if (options.verbose) {
+                console.log("Response cached as JSON.");
+            }
+        }
+    }
+    if (options.verbose) {
+        console.log("Execution time:", formatDuration(Date.now() - start));
+    }
+    return returnedResponse;
+}

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/helpers/cache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Initialises the cache directory and returns a deterministic file path
+ * derived from a SHA-256 hash of the request parameters.
+ */
+export declare function initCache(hashInput: unknown): {
+    cacheFile: string;
+};
+/**
+ * Checks for a cache hit. Returns the cached value or `null` on a miss.
+ */
+export declare function readCache(cacheFile: string): unknown | null;
+/**
+ * Writes a response to the cache.
+ */
+export declare function writeCache(cacheFile: string, response: unknown): void;
+/**
+ * Reads a cached object and optionally transforms its `response`. If the
+ * transform rejects the cached value, the cache entry is removed so a retry
+ * can generate a fresh response.
+ */
+export declare function readAndProcessCache<TCached extends {
+    response: unknown;
+}, TResponse = TCached["response"]>(cacheFile: string, processResponse?: (response: unknown) => TResponse | Promise<TResponse>): Promise<(Omit<TCached, "response"> & {
+    response: TResponse;
+}) | null>;
+//# sourceMappingURL=cache.d.ts.map

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/helpers/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/helpers/cache.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,OAAO,GACjB;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CASvB;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,MAAM,GAChB,OAAO,GAAG,IAAI,CAKhB;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,GAChB,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,SAAS;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,EACrC,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,EAE/B,SAAS,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,GACtE,OAAO,CACN,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,GACrD,IAAI,CACP,CAkBA"}

package/esm/deps/jsr.io/@nshiab/journalism-ai/2.0.6/src/ai/helpers/cache.js

@@ -0,0 +1,56 @@
+import crypto from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+const CACHE_PATH = "./.journalism-cache";
+/**
+ * Initialises the cache directory and returns a deterministic file path
+ * derived from a SHA-256 hash of the request parameters.
+ */
+export function initCache(hashInput) {
+    if (!existsSync(CACHE_PATH)) {
+        mkdirSync(CACHE_PATH);
+    }
+    const hash = crypto
+        .createHash("sha256")
+        .update(JSON.stringify(hashInput))
+        .digest("hex");
+    return { cacheFile: `${CACHE_PATH}/askAI-${hash}.json` };
+}
+/**
+ * Checks for a cache hit. Returns the cached value or `null` on a miss.
+ */
+export function readCache(cacheFile) {
+    if (existsSync(cacheFile)) {
+        return JSON.parse(readFileSync(cacheFile, "utf-8"));
+    }
+    return null;
+}
+/**
+ * Writes a response to the cache.
+ */
+export function writeCache(cacheFile, response) {
+    writeFileSync(cacheFile, JSON.stringify(response));
+}
+/**
+ * Reads a cached object and optionally transforms its `response`. If the
+ * transform rejects the cached value, the cache entry is removed so a retry
+ * can generate a fresh response.
+ */
+export async function readAndProcessCache(cacheFile, processResponse) {
+    const cached = readCache(cacheFile);
+    if (cached === null) {
+        return null;
+    }
+    if (!processResponse) {
+        return cached;
+    }
+    try {
+        return {
+            ...cached,
+            response: await processResponse(cached.response),
+        };
+    }
+    catch (error) {
+        rmSync(cacheFile);
+        throw error;
+    }
+}