astro-content-vectors 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 h93xV2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# astro-content-vectors
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An Astro integration that ranks entries in a content collection by embedding similarity. It uses OpenAI when `OPENAI_API_KEY` is available and automatically falls back to a local LM Studio server when the key is missing or OpenAI is unreachable.
+
+Requires Astro 7 or later and Node.js 20 or later for the build process.
+
+## Install
+
+```sh
+npm install astro-content-vectors
+# or: pnpm add astro-content-vectors
+# or: bun add astro-content-vectors
+```
+
+Add the integration in `astro.config.mjs`:
+
+```js
+import { defineConfig } from "astro/config";
+import contentVectors from "astro-content-vectors";
+
+export default defineConfig({
+    integrations: [
+        contentVectors({
+            collections: ["blog"],
+            provider: {
+                type: "openai",
+                model: "text-embedding-3-small",
+            },
+            environments: {
+                development: {
+                    provider: {
+                        type: "lmstudio",
+                        // Match the model name loaded in LM Studio.
+                        baseUrl: "http://127.0.0.1:1234/v1",
+                        model: "text-embedding-nomic-embed-text-v1.5",
+                    },
+                },
+                production: {
+                    provider: { model: "text-embedding-3-small" },
+                },
+            },
+            fallback: {
+                baseUrl: "http://127.0.0.1:1234/v1",
+                model: "text-embedding-nomic-embed-text-v1.5",
+            },
+            threshold: 0.65,
+            limit: 3,
+            logLevel: "info",
+            // Set true to fail the Astro build if neither provider works.
+            failOnError: false,
+        }),
+    ],
+});
+```
+
+Set `OPENAI_API_KEY` in the environment where the Astro build runs. The integration detects it automatically and never puts the key into client bundles or injected configuration. Without the key, it tries the configured LM Studio fallback. If an OpenAI request fails, it tries the fallback once. If both providers fail, it logs a warning and returns no recommendations by default; set `failOnError: true` to fail the build instead. Start LM Studio's local server and load an embedding model for the fallback to work.
+
+Astro `dev` uses the `development` override; `astro build` uses `production`. The integration selects an override using Astro's `import.meta.env.MODE`, so custom modes such as `astro build --mode preview` work as environment keys too. Set `environment` to explicitly override the detected mode. Each environment may override the single default `provider`; any omitted settings inherit from the default. OpenAI environments use the default LM Studio fallback; configure it with the top-level `fallback` option or set `fallback: false` to disable it. An environment configured with LM Studio uses only that provider.
+
+### Provider configuration
+
+Both providers use the OpenAI embeddings API format. OpenAI uses `https://api.openai.com/v1` by default; LM Studio uses `http://127.0.0.1:1234/v1`. Set `baseUrl` when your server listens elsewhere, and set `model` to a model available to that provider. LM Studio defaults to `text-embedding-nomic-embed-text-v1.5`; OpenAI defaults to `text-embedding-3-small`.
+
+| Provider setting | Description                                                |
+| ---------------- | ---------------------------------------------------------- |
+| `type`           | `"openai"` or `"lmstudio"`. Defaults to `"openai"`.        |
+| `baseUrl`        | OpenAI-compatible API base URL. Defaults depend on `type`. |
+| `model`          | Embedding model name. Defaults depend on `type`.           |
+| `batchSize`      | Content entries per embedding request. Defaults to `32`.   |
+
+The OpenAI SDK sends one request per batch, does not retry failed requests, and times out a request after 60 seconds. A failed OpenAI request can then use the configured LM Studio fallback.
+
+### Integration options
+
+| Option                   | Default                                                           | Description                                                                   |
+| ------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `collections`            | all collections                                                   | Optional allowlist of Astro content collections to index.                     |
+| `provider`               | OpenAI                                                            | Default provider and its settings.                                            |
+| `environments`           | `{}`                                                              | Provider overrides keyed by environment name.                                 |
+| `environment`            | `"development"` for `astro dev`; `"production"` for `astro build` | Explicit environment key to select an override.                               |
+| `fallback`               | LM Studio                                                         | Fallback settings for an OpenAI provider. Set to `false` to disable fallback. |
+| `threshold`              | `0.65`                                                            | Minimum cosine similarity score for a recommendation.                         |
+| `limit`                  | `3`                                                               | Maximum recommendations returned per entry.                                   |
+| `logLevel`               | `"warn"`                                                          | One of `"silent"`, `"error"`, `"warn"`, `"info"`, or `"debug"`.               |
+| `failOnError`            | `false`                                                           | Throw if no configured provider can generate embeddings.                      |
+| `cache`                  | `true`                                                            | Store embeddings in SQLite during Astro builds.                               |
+| `cachePath`              | `.astro/embeddings.db`                                            | SQLite file path, relative to the project root.                               |
+| `outputSimilarityScores` | `false`                                                           | Write pairwise similarity score JSON files into the build output.             |
+
+```js
+contentVectors({
+    environment: process.env.DEPLOY_ENV ?? "preview",
+    provider: { type: "openai", model: "text-embedding-3-small" },
+    environments: {
+        preview: { provider: { model: "text-embedding-3-large" } },
+    },
+});
+```
+
+Import the Astro-aware helper from the package's `astro` entry point in an Astro component or page frontmatter. Its types are included automatically:
+
+```astro
+---
+import { getCollection } from "astro:content";
+import { getRelatedContent } from "astro-content-vectors/astro";
+
+const post = Astro.props.post;
+const recommendations = await getRelatedContent("blog", post.id);
+const posts = await getCollection("blog");
+const relatedPosts = recommendations
+  .map(({ id }) => posts.find((entry) => entry.id === id))
+  .filter(Boolean);
+---
+
+{relatedPosts.map((entry) => <a href={`/blog/${entry.id}/`}>{entry.data.title}</a>)}
+```
+
+Each collection is indexed once per server/build process. The integration embeds each entry's title, description (if any), and Markdown body. `getRelatedContent(collection, id)` returns an array of `{ id, score }` objects, ordered by descending cosine similarity. The current entry is excluded from its own recommendations. Entries scoring below `threshold` are omitted. Set `logLevel` to `silent` to disable logs.
+
+By default, generated vectors are cached in `.astro/embeddings.db` using SQLite. The cache is keyed by collection, entry ID, provider, and model, and refreshes an entry when its source text changes. Set `cache: false` to disable it or `cachePath` to choose another database file.
+
+The integration uses the OpenAI SDK for embedding requests. LM Studio works through its OpenAI-compatible API. The runtime API is also exported for custom content loaders:
+
+The runtime helper accepts documents with an `id` and optional `title`, `text`, and `body` fields. Its configuration requires a provider `baseUrl` and `model`; SQLite caching is disabled for direct runtime calls unless `cache: true` is passed.
+
+To inspect how your content compares while tuning `threshold`, enable the optional score report:
+
+```ts
+contentVectors({
+    outputSimilarityScores: true,
+    threshold: 0.7,
+});
+```
+
+During a static build, this writes one JSON file per accessed collection to `.astro/content-vector-similarities/`, alongside the default embeddings cache. Each file contains every unique pair of entry IDs and its cosine similarity score, including scores below the configured threshold. The option is off by default. The reports stay out of `dist` and are not included in the deployed site unless you copy them there yourself.
+
+```ts
+import { getRelatedContent } from "astro-content-vectors/runtime";
+
+const index = await getRelatedContent(documents, {
+    provider: {
+        baseUrl: "http://127.0.0.1:1234/v1",
+        model: "your-loaded-embedding-model",
+    },
+    cache: true,
+});
+```
+
+## Static builds on Cloudflare
+
+Cloudflare Secrets Store values cannot be retrieved through Cloudflare's management API or dashboard after they are stored. Its `get()` binding is available to a running Worker, so it cannot provide the OpenAI key to a regular static build. See [Secrets Store management](https://developers.cloudflare.com/secrets-store/manage-secrets/) and the [Workers binding guide](https://developers.cloudflare.com/secrets-store/integrations/workers/).
+
+For a static build, configure `OPENAI_API_KEY` as a protected build environment variable instead. For example, in GitHub Actions:
+
+```yaml
+- name: Build Astro site
+  run: bun run build
+  env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```
+
+The integration picks up this variable automatically. Keep it in the CI or hosting provider's secret settings; do not place its value in Astro config or commit it to the repository.
+
+## Development
+
+```sh
+bun install
+bun run check
+bun run typecheck
+bun run test
+bun run test:package
+bun run test:astro-install
+bun run build
+```
+
+`bun run test` runs the unit and integration suites. `bun run test:package` builds the package and checks its exports. `bun run test:astro-install` packs and installs the package into a temporary Astro 7 fixture, then runs a static build against a local mock embeddings server.

package/dist/astro.d.ts

@@ -0,0 +1,3 @@
+import type { RelatedContent } from "./runtime.js";
+/** Return ranked related entries from an Astro content collection. */
+export declare function getRelatedContent(collection: string, id: string): Promise<RelatedContent[]>;

package/dist/astro.js

@@ -0,0 +1,57 @@
+/// <reference types="astro/client" />
+import { getCollection } from "astro:content";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getRelatedContent as buildRelatedContent } from "./runtime.js";
+const { environments, environment, defaultEnvironment, outputSimilarityScores, outputDirectory, } = __ASTRO_CONTENT_VECTORS_CONFIG__;
+const viteEnvironment = import.meta.env?.MODE;
+const activeEnvironment = environment ?? viteEnvironment ?? defaultEnvironment;
+const selectedConfig = environments[activeEnvironment] ?? environments[defaultEnvironment];
+if (!selectedConfig?.provider) {
+    throw new Error(`astro-content-vectors has no providers configured for environment: ${activeEnvironment}`);
+}
+const config = selectedConfig;
+const indexes = new Map();
+const optionalString = (value) => typeof value === "string" ? value : undefined;
+/** Return ranked related entries from an Astro content collection. */
+export async function getRelatedContent(collection, id) {
+    if (config.collections && !config.collections.includes(collection)) {
+        throw new Error(`Collection is not enabled in astro-content-vectors: ${collection}`);
+    }
+    let pending = indexes.get(collection);
+    if (!pending) {
+        const created = getCollection(collection).then((entries) => {
+            const documents = entries.map((entry) => ({
+                id: entry.id,
+                title: optionalString(entry.data.title),
+                text: optionalString(entry.data.description),
+                body: entry.body ?? "",
+            }));
+            const reportConfig = {
+                ...config,
+                cacheNamespace: collection,
+            };
+            if (outputSimilarityScores) {
+                reportConfig.onSimilarityScores = async (pairs) => {
+                    await mkdir(outputDirectory, { recursive: true });
+                    const file = join(outputDirectory, `${encodeURIComponent(collection)}.json`);
+                    const report = {
+                        collection,
+                        threshold: config.threshold ?? 0.65,
+                        pairs,
+                    };
+                    await writeFile(file, `${JSON.stringify(report, null, 2)}\n`);
+                };
+            }
+            return buildRelatedContent(documents, reportConfig);
+        });
+        indexes.set(collection, created);
+        void created.catch(() => indexes.delete(collection));
+        pending = created;
+    }
+    if (!pending) {
+        throw new Error("Failed to create the content-vector index.");
+    }
+    const index = await pending;
+    return index.get(id) ?? [];
+}

package/dist/cache.d.ts

@@ -0,0 +1,20 @@
+import Database from "better-sqlite3";
+type EmbeddingsRow = {
+    post_id: string;
+    post_hash: string;
+    embedding: string;
+};
+export type PostEmbeddingCacheEntry = {
+    hashedContent: string;
+    row: EmbeddingsRow | undefined;
+    vector: number[] | undefined;
+};
+/** Open the Astro project's persistent embedding database. */
+export declare const getEmbeddingDatabase: (dbPath?: string) => Database.Database;
+export declare const closeEmbeddingDatabase: (dbPath?: string) => void;
+export declare const initializeEmbeddingTable: (db: Database.Database) => void;
+/** Look up an embedding and compare its stored content hash. */
+export declare const getPostEmbeddingCacheEntry: (db: Database.Database, slug: string, content: string) => PostEmbeddingCacheEntry;
+/** Insert a new vector or replace the vector when its source text changed. */
+export declare const savePostEmbedding: (db: Database.Database, slug: string, hashedContent: string, vector: number[], row: EmbeddingsRow | undefined) => void;
+export {};

package/dist/cache.js

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import Database from "better-sqlite3";
+const databases = new Map();
+/** Open the Astro project's persistent embedding database. */
+export const getEmbeddingDatabase = (dbPath = resolve(process.cwd(), ".astro", "embeddings.db")) => {
+    const resolvedPath = resolve(dbPath);
+    const existing = databases.get(resolvedPath);
+    if (existing)
+        return existing;
+    const astroDir = dirname(resolvedPath);
+    if (!existsSync(astroDir)) {
+        mkdirSync(astroDir, { recursive: true });
+    }
+    const db = new Database(resolvedPath);
+    initializeEmbeddingTable(db);
+    databases.set(resolvedPath, db);
+    return db;
+};
+export const closeEmbeddingDatabase = (dbPath = resolve(process.cwd(), ".astro", "embeddings.db")) => {
+    const resolvedPath = resolve(dbPath);
+    const db = databases.get(resolvedPath);
+    if (db) {
+        db.close();
+        databases.delete(resolvedPath);
+    }
+};
+export const initializeEmbeddingTable = (db) => {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS embeddings (
+      post_id TEXT PRIMARY KEY,
+      post_hash TEXT,
+      embedding TEXT
+    );
+  `);
+};
+/** Look up an embedding and compare its stored content hash. */
+export const getPostEmbeddingCacheEntry = (db, slug, content) => {
+    const hash = createHash("sha256");
+    hash.update(content);
+    const hashedContent = hash.digest("hex");
+    const row = db
+        .prepare("SELECT * FROM embeddings WHERE post_id = ?")
+        .get(slug);
+    return {
+        hashedContent,
+        row,
+        vector: row && row.post_hash === hashedContent
+            ? JSON.parse(row.embedding)
+            : undefined,
+    };
+};
+/** Insert a new vector or replace the vector when its source text changed. */
+export const savePostEmbedding = (db, slug, hashedContent, vector, row) => {
+    if (!row) {
+        const insert = db.prepare("INSERT INTO embeddings (post_id, post_hash, embedding) VALUES (?, ?, ?)");
+        insert.run(slug, hashedContent, JSON.stringify(vector));
+    }
+    else if (row.post_hash !== hashedContent) {
+        const update = db.prepare("UPDATE embeddings SET post_hash = ?, embedding = ? WHERE post_id = ?");
+        update.run(hashedContent, JSON.stringify(vector), slug);
+    }
+};

package/dist/embedder.d.ts

@@ -0,0 +1,2 @@
+import type { ContentDocument, ContentVectorsConfig, EmbeddingProviderConfig } from "./types.js";
+export declare const embedAll: (documents: ContentDocument[], provider: EmbeddingProviderConfig, config: ContentVectorsConfig) => Promise<number[][]>;

package/dist/embedder.js

@@ -0,0 +1,86 @@
+import { getEmbeddingDatabase, getPostEmbeddingCacheEntry, savePostEmbedding, } from "./cache.js";
+import { requestEmbeddings } from "./provider.js";
+const contentText = (document) => [document.title, document.text, document.body].filter(Boolean).join("\n\n");
+const embeddingCacheId = (id, provider, namespace) => JSON.stringify([
+    provider.providerName ?? provider.baseUrl,
+    provider.baseUrl,
+    provider.model,
+    namespace ?? "",
+    id,
+]);
+export const embedAll = async (documents, provider, config) => {
+    const texts = documents.map(contentText);
+    const ids = documents.map(({ id }) => id);
+    const batchSize = Math.max(1, provider.batchSize ?? 32);
+    const database = config.cache === true
+        ? getEmbeddingDatabase(config.cachePath)
+        : undefined;
+    const vectors = new Array(texts.length);
+    const cacheEntries = new Array(texts.length);
+    const missing = [];
+    for (let index = 0; index < texts.length; index++) {
+        const id = ids[index];
+        const text = texts[index];
+        if (id === undefined || text === undefined) {
+            throw new Error("Content IDs and text must have matching lengths.");
+        }
+        const cacheId = embeddingCacheId(id, provider, config.cacheNamespace);
+        const entry = database
+            ? getPostEmbeddingCacheEntry(database, cacheId, text)
+            : undefined;
+        if (entry?.vector) {
+            vectors[index] = entry.vector;
+        }
+        else {
+            missing.push(index);
+            cacheEntries[index] = entry;
+        }
+    }
+    const updates = [];
+    for (let start = 0; start < missing.length; start += batchSize) {
+        const indices = missing.slice(start, start + batchSize);
+        const batch = indices.map((index) => {
+            const text = texts[index];
+            if (text === undefined) {
+                throw new Error("Missing content text for embedding.");
+            }
+            return text;
+        });
+        const batchVectors = await requestEmbeddings(batch, provider, config);
+        indices.forEach((index, batchIndex) => {
+            const vector = batchVectors[batchIndex];
+            if (!vector) {
+                throw new Error("Embedding provider returned fewer vectors than requested.");
+            }
+            vectors[index] = vector;
+            const entry = cacheEntries[index];
+            if (database && entry) {
+                const id = ids[index];
+                if (id === undefined) {
+                    throw new Error("Missing content ID for embedding.");
+                }
+                updates.push({
+                    cacheId: embeddingCacheId(id, provider, config.cacheNamespace),
+                    vector,
+                    entry,
+                });
+            }
+        });
+    }
+    const completeVectors = vectors.map((vector) => {
+        if (!vector) {
+            throw new Error("Embedding provider returned fewer vectors than documents.");
+        }
+        return vector;
+    });
+    const dimensions = completeVectors[0]?.length;
+    if (completeVectors.some((vector) => vector.length === 0 || vector.length !== dimensions)) {
+        throw new Error("Embedding provider returned vectors with incompatible dimensions.");
+    }
+    if (database) {
+        for (const { cacheId, vector, entry } of updates) {
+            savePostEmbedding(database, cacheId, entry.hashedContent, vector, entry.row);
+        }
+    }
+    return completeVectors;
+};

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import type { AstroIntegration } from "astro";
+export type AstroContentVectorsOptions = {
+    /** Optional collection allowlist. Calls for other collections return no results. */
+    collections?: string[];
+    /** Default provider configuration, used unless an environment overrides it. */
+    provider?: ProviderSelection;
+    /** Select a custom environment key. Defaults to Astro's dev/build command. */
+    environment?: string;
+    environments?: Record<string, {
+        provider?: ProviderOverride;
+    }>;
+    /** LM Studio fallback used when an OpenAI provider has no key or fails. */
+    fallback?: false | ProviderOverride;
+    threshold?: number;
+    limit?: number;
+    logLevel?: "silent" | "error" | "warn" | "info" | "debug";
+    /** Throw when both OpenAI and the local fallback fail. Defaults to false. */
+    failOnError?: boolean;
+    /** Write all pairwise scores to `.astro/content-vector-similarities/`. */
+    outputSimilarityScores?: boolean;
+    /** Persist generated vectors in SQLite. Defaults to true. */
+    cache?: boolean;
+    /** SQLite file path, relative to the Astro project root. */
+    cachePath?: string;
+};
+export type ProviderSelection = {
+    type: "lmstudio" | "openai";
+    baseUrl?: string;
+    model?: string;
+    batchSize?: number;
+    headers?: Record<string, string>;
+    apiKey?: string;
+};
+export type ProviderOverride = Partial<ProviderSelection>;
+/**
+ * Adds the Astro content-vector helper to a site. It uses OpenAI when
+ * OPENAI_API_KEY is available and falls back to the local LM Studio endpoint.
+ */
+export default function astroContentVectors(options?: AstroContentVectorsOptions): AstroIntegration;
+export type { ContentDocument, ContentVectorsConfig, EmbeddingProviderConfig, RelatedContent, SimilarityScore, } from "./runtime.js";
+export { cosineSimilarity, getPairWiseSimilarityScores, getSlugToMostRelatedPostsMap, } from "./runtime.js";

package/dist/index.js

@@ -0,0 +1,85 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const VECTORS_CONFIG_DEFINE = "__ASTRO_CONTENT_VECTORS_CONFIG__";
+const defineProvider = (name, configured) => {
+    // API keys are resolved in the server runtime; never serialize secrets into
+    // the settings injected into Astro's Vite build.
+    const { apiKey: _apiKey, headers: _headers, ...safeOptions } = configured;
+    if (name === "lmstudio") {
+        return {
+            ...safeOptions,
+            providerName: name,
+            baseUrl: safeOptions.baseUrl ?? "http://127.0.0.1:1234/v1",
+            model: safeOptions.model ?? "text-embedding-nomic-embed-text-v1.5",
+        };
+    }
+    return {
+        ...safeOptions,
+        providerName: name,
+        baseUrl: safeOptions.baseUrl ?? "https://api.openai.com/v1",
+        model: safeOptions.model ?? "text-embedding-3-small",
+    };
+};
+const defineEnvironment = (name, options, projectRoot) => {
+    const selected = {
+        type: "openai",
+        ...options.provider,
+        ...options.environments?.[name]?.provider,
+    };
+    const { type: providerName, ...providerOptions } = selected;
+    const primaryProvider = defineProvider(providerName, providerOptions);
+    const fallbackProvider = providerName === "openai" && options.fallback !== false
+        ? defineProvider("lmstudio", options.fallback ?? {})
+        : undefined;
+    return {
+        provider: primaryProvider,
+        fallbackProvider,
+        threshold: options.threshold,
+        limit: options.limit,
+        logLevel: options.logLevel,
+        failOnError: options.failOnError ?? false,
+        collections: options.collections ?? null,
+        cache: options.cache ?? true,
+        cachePath: resolve(projectRoot, options.cachePath ?? ".astro/embeddings.db"),
+    };
+};
+/**
+ * Adds the Astro content-vector helper to a site. It uses OpenAI when
+ * OPENAI_API_KEY is available and falls back to the local LM Studio endpoint.
+ */
+export default function astroContentVectors(options = {}) {
+    return {
+        name: "astro-content-vectors",
+        hooks: {
+            "astro:config:setup": ({ command, updateConfig, config }) => {
+                const defaultEnvironment = command === "dev" ? "development" : "production";
+                const environmentNames = new Set([
+                    "development",
+                    "production",
+                    ...Object.keys(options.environments ?? {}),
+                    ...(options.environment ? [options.environment] : []),
+                ]);
+                const projectRoot = fileURLToPath(config.root);
+                const environments = Object.fromEntries([...environmentNames].map((name) => [
+                    name,
+                    defineEnvironment(name, options, projectRoot),
+                ]));
+                const runtimeConfig = {
+                    environments,
+                    environment: options.environment,
+                    defaultEnvironment,
+                    outputSimilarityScores: options.outputSimilarityScores ?? false,
+                    outputDirectory: resolve(projectRoot, ".astro", "content-vector-similarities"),
+                };
+                updateConfig({
+                    vite: {
+                        define: {
+                            [VECTORS_CONFIG_DEFINE]: JSON.stringify(runtimeConfig),
+                        },
+                    },
+                });
+            },
+        },
+    };
+}
+export { cosineSimilarity, getPairWiseSimilarityScores, getSlugToMostRelatedPostsMap, } from "./runtime.js";

package/dist/logging.d.ts

@@ -0,0 +1,2 @@
+import type { ContentVectorsConfig } from "./types.js";
+export declare const log: (config: ContentVectorsConfig, level: "error" | "warn" | "info" | "debug", message: string) => void;

package/dist/logging.js

@@ -0,0 +1,10 @@
+const levels = { silent: 0, error: 1, warn: 2, info: 3, debug: 4 };
+const defaultLogger = (level, message) => {
+    const method = level === "debug" ? "log" : level;
+    console[method](`[astro-content-vectors] ${message}`);
+};
+export const log = (config, level, message) => {
+    if (levels[config.logLevel ?? "warn"] >= levels[level]) {
+        (config.logger ?? defaultLogger)(level, message);
+    }
+};

package/dist/provider.d.ts

@@ -0,0 +1,4 @@
+import type { ContentVectorsConfig, EmbeddingProviderConfig } from "./types.js";
+export declare const usesOpenAI: (provider: EmbeddingProviderConfig) => boolean;
+export declare const providerApiKey: (provider: EmbeddingProviderConfig) => any;
+export declare const requestEmbeddings: (texts: string[], provider: EmbeddingProviderConfig, config: ContentVectorsConfig) => Promise<number[][]>;

package/dist/provider.js

@@ -0,0 +1,51 @@
+import OpenAI from "openai";
+const environment = () => {
+    const vite = import.meta.env;
+    const node = globalThis.process?.env;
+    return { ...node, ...vite };
+};
+export const usesOpenAI = (provider) => provider.providerName === "openai" ||
+    provider.baseUrl.includes("api.openai.com");
+export const providerApiKey = (provider) => {
+    if (provider.apiKey)
+        return provider.apiKey;
+    if (!usesOpenAI(provider))
+        return undefined;
+    return environment().OPENAI_API_KEY;
+};
+export const requestEmbeddings = async (texts, provider, config) => {
+    const apiKey = providerApiKey(provider);
+    if (usesOpenAI(provider) && !apiKey) {
+        throw new Error("OPENAI_API_KEY is required when using the OpenAI embeddings provider.");
+    }
+    const client = new OpenAI({
+        apiKey: apiKey ?? "lm-studio",
+        baseURL: provider.baseUrl,
+        defaultHeaders: provider.headers,
+        fetch: config.fetch,
+        maxRetries: 0,
+        timeout: 60_000,
+    });
+    let payload;
+    try {
+        payload = await client.embeddings.create({
+            model: provider.model,
+            input: texts,
+        });
+    }
+    catch (error) {
+        if (error instanceof OpenAI.APIConnectionError &&
+            error.cause instanceof Error) {
+            throw new Error(`${error.message}: ${error.cause.message}`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    if (payload.data.length !== texts.length) {
+        throw new Error("Embedding provider returned an unexpected response.");
+    }
+    return [...payload.data]
+        .sort((a, b) => a.index - b.index)
+        .map(({ embedding }) => embedding);
+};

package/dist/related-posts.d.ts

@@ -0,0 +1,16 @@
+type Embedding = {
+    slug: string;
+    vector: number[];
+};
+declare const getCosineSimilarity: (vectorA: number[], vectorB: number[]) => number;
+type ScoredPost = {
+    slug: string;
+    score: number;
+};
+declare const COSINE_THRESHOLD = 0.65;
+declare const getSlugToMostRelatedPostsMap: (embeddings: Embedding[], options?: {
+    threshold?: number;
+    limit?: number;
+}) => Map<string, ScoredPost[]>;
+declare const getPairWiseSimilarityScores: (embeddings: Embedding[]) => number[];
+export { COSINE_THRESHOLD, type Embedding, getCosineSimilarity, getPairWiseSimilarityScores, getSlugToMostRelatedPostsMap, type ScoredPost, };

package/dist/related-posts.js

@@ -0,0 +1,38 @@
+const getCosineSimilarity = (vectorA, vectorB) => {
+    // See https://stackoverflow.com/a/64816824 for dot product calculation explained.
+    const dot = vectorA.reduce((sum, val, i) => sum + val * vectorB[i], 0.0);
+    const magnitudeA = Math.sqrt(vectorA.reduce((sum, val) => sum + val * val, 0.0));
+    const magnitudeB = Math.sqrt(vectorB.reduce((sum, val) => sum + val * val, 0.0));
+    const denominator = magnitudeA * magnitudeB;
+    return denominator === 0 ? 0 : dot / denominator;
+};
+const COSINE_THRESHOLD = 0.65;
+const getSlugToMostRelatedPostsMap = (embeddings, options = {}) => {
+    const threshold = options.threshold ?? COSINE_THRESHOLD;
+    const limit = options.limit ?? 3;
+    const slugToMostRelatedPosts = new Map();
+    for (const a of embeddings) {
+        const sims = embeddings
+            .filter((b) => b.slug !== a.slug)
+            .map((b) => ({
+            slug: b.slug,
+            score: getCosineSimilarity(a.vector, b.vector),
+        }))
+            .filter((c) => threshold <= c.score)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        slugToMostRelatedPosts.set(a.slug, sims);
+    }
+    return slugToMostRelatedPosts;
+};
+const getPairWiseSimilarityScores = (embeddings) => {
+    const pairs = [];
+    for (let i = 0; i < embeddings.length; i++) {
+        for (let j = i + 1; j < embeddings.length; j++) {
+            const sim = getCosineSimilarity(embeddings[i].vector, embeddings[j].vector);
+            pairs.push(sim);
+        }
+    }
+    return pairs;
+};
+export { COSINE_THRESHOLD, getCosineSimilarity, getPairWiseSimilarityScores, getSlugToMostRelatedPostsMap, };

package/dist/runtime.d.ts

@@ -0,0 +1,7 @@
+import { getCosineSimilarity, getPairWiseSimilarityScores, getSlugToMostRelatedPostsMap } from "./related-posts.js";
+import type { ContentDocument, ContentVectorsConfig, RelatedContent } from "./types.js";
+/** Generate vectors and return ranked recommendations for every document. */
+export declare function getRelatedContent(documents: ContentDocument[], config: ContentVectorsConfig): Promise<Map<string, RelatedContent[]>>;
+export type { Embedding, ScoredPost } from "./related-posts.js";
+export type { ContentDocument, ContentVectorsConfig, EmbeddingProviderConfig, FetchLike, RelatedContent, SimilarityScore, } from "./types.js";
+export { getCosineSimilarity as cosineSimilarity, getPairWiseSimilarityScores, getSlugToMostRelatedPostsMap, };

package/dist/runtime.js

@@ -0,0 +1,104 @@
+import { embedAll } from "./embedder.js";
+import { log } from "./logging.js";
+import { providerApiKey, usesOpenAI } from "./provider.js";
+import { getCosineSimilarity, getPairWiseSimilarityScores, getSlugToMostRelatedPostsMap, } from "./related-posts.js";
+/** Generate vectors and return ranked recommendations for every document. */
+export async function getRelatedContent(documents, config) {
+    const ids = new Set();
+    for (const document of documents) {
+        if (ids.has(document.id))
+            throw new Error(`Duplicate content id: ${document.id}`);
+        ids.add(document.id);
+    }
+    let vectors;
+    let primaryError;
+    const primaryApiKey = providerApiKey(config.provider);
+    const primaryHasKey = !usesOpenAI(config.provider) || Boolean(primaryApiKey);
+    if (!primaryHasKey) {
+        log(config, "info", "OPENAI_API_KEY is not set; using the local fallback provider.");
+        primaryError = new Error("OPENAI_API_KEY is required when using the OpenAI embeddings provider.");
+        if (!config.fallbackProvider)
+            log(config, "warn", String(primaryError));
+    }
+    else {
+        log(config, "info", `Generating embeddings for ${documents.length} content entries with ${config.provider.model}.`);
+        try {
+            const primaryProvider = primaryApiKey
+                ? { ...config.provider, apiKey: primaryApiKey }
+                : config.provider;
+            vectors = await embedAll(documents, primaryProvider, config);
+        }
+        catch (error) {
+            primaryError = error;
+            if (config.fallbackProvider) {
+                log(config, "warn", `Primary embedding provider failed; trying the fallback provider. ${error instanceof Error ? error.message : String(error)}`);
+            }
+            else {
+                log(config, "warn", `Embedding provider failed. ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    if (!vectors && config.fallbackProvider) {
+        log(config, "info", `Generating embeddings with fallback model ${config.fallbackProvider.model}.`);
+        try {
+            vectors = await embedAll(documents, config.fallbackProvider, config);
+        }
+        catch (fallbackError) {
+            const message = `Fallback embedding provider failed. ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`;
+            log(config, "warn", message);
+            if (config.failOnError) {
+                throw new AggregateError([primaryError, fallbackError], message);
+            }
+        }
+    }
+    if (!vectors) {
+        const message = "No embedding provider could generate vectors; returning an empty related-content index.";
+        log(config, "warn", message);
+        if (config.failOnError) {
+            throw primaryError instanceof Error
+                ? primaryError
+                : new Error(message);
+        }
+        return new Map(documents.map(({ id }) => [id, []]));
+    }
+    const embeddings = documents.map((document, index) => {
+        const vector = vectors[index];
+        if (!vector) {
+            throw new Error("Embedding provider returned fewer vectors than documents.");
+        }
+        return { slug: document.id, vector };
+    });
+    if (config.onSimilarityScores) {
+        const scores = [];
+        for (let i = 0; i < embeddings.length; i++) {
+            for (let j = i + 1; j < embeddings.length; j++) {
+                const source = embeddings[i];
+                const target = embeddings[j];
+                if (!source || !target)
+                    continue;
+                scores.push({
+                    sourceId: source.slug,
+                    targetId: target.slug,
+                    score: getCosineSimilarity(source.vector, target.vector),
+                });
+            }
+        }
+        await config.onSimilarityScores(scores);
+    }
+    const limit = Math.max(0, config.limit ?? 3);
+    const rankedBySlug = getSlugToMostRelatedPostsMap(embeddings, {
+        threshold: config.threshold,
+        limit,
+    });
+    const related = new Map();
+    for (const document of documents) {
+        const ranked = rankedBySlug.get(document.id) ?? [];
+        related.set(document.id, ranked.slice(0, limit).map(({ slug, score }) => ({
+            id: slug,
+            score,
+        })));
+    }
+    log(config, "info", `Built recommendations for ${documents.length} entries.`);
+    return related;
+}
+export { getCosineSimilarity as cosineSimilarity, getPairWiseSimilarityScores, getSlugToMostRelatedPostsMap, };

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export type ContentDocument = {
+    id: string;
+    title?: string;
+    body?: string;
+    /** Optional extra text such as tags or a description. */
+    text?: string;
+};
+export type EmbeddingProviderConfig = {
+    /** Provider identifier set by the Astro integration. */
+    providerName?: "openai" | "lmstudio";
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    /** Number of documents sent in one request. Defaults to 32. */
+    batchSize?: number;
+    headers?: Record<string, string>;
+};
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type RelatedContent = {
+    id: string;
+    score: number;
+};
+export type SimilarityScore = {
+    sourceId: string;
+    targetId: string;
+    score: number;
+};
+export type ContentVectorsConfig = {
+    provider: EmbeddingProviderConfig;
+    /** Used if the primary provider cannot be reached or has no API key. */
+    fallbackProvider?: EmbeddingProviderConfig;
+    /** Throw if no configured provider can generate vectors. Defaults to false. */
+    failOnError?: boolean;
+    logLevel?: "silent" | "error" | "warn" | "info" | "debug";
+    threshold?: number;
+    limit?: number;
+    /** Persist vectors in SQLite. Direct runtime use defaults to false. */
+    cache?: boolean;
+    /** SQLite database file. Relative paths resolve from the Astro project root. */
+    cachePath?: string;
+    /** Prevent ID collisions between independently processed collections. */
+    cacheNamespace?: string;
+    /** Inject fetch in tests or non-standard runtimes. */
+    fetch?: FetchLike;
+    onSimilarityScores?: (scores: SimilarityScore[]) => void | Promise<void>;
+    logger?: (level: "error" | "warn" | "info" | "debug", message: string) => void;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,111 @@
 {
-  "name": "astro-content-vectors",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "astro-content-vectors",
+    "description": "An Astro integration for vector-based related content using local or hosted embeddings.",
+    "version": "0.1.0",
+    "author": "h93xV2",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/h93xV2/astro-content-vectors.git"
+    },
+    "homepage": "https://github.com/h93xV2/astro-content-vectors#readme",
+    "bugs": {
+        "url": "https://github.com/h93xV2/astro-content-vectors/issues"
+    },
+    "type": "module",
+    "files": [
+        "dist"
+    ],
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./runtime": {
+            "types": "./dist/runtime.d.ts",
+            "import": "./dist/runtime.js"
+        },
+        "./astro": {
+            "types": "./dist/astro.d.ts",
+            "import": "./dist/astro.js"
+        }
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "peerDependencies": {
+        "astro": ">=7.0.0"
+    },
+    "scripts": {
+        "build": "npm run clean && tsc -p tsconfig.build.json",
+        "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+        "prepack": "npm run build",
+        "setup": "husky",
+        "test": "bun run test:unit && bun run test:integration",
+        "test:integration": "bun test test/integration",
+        "test:astro-install": "bun run build && bun test test/e2e/astro-install.test.ts",
+        "test:package": "bun run build && bun test test/package",
+        "test:unit": "bun test test/unit",
+        "typecheck": "tsc --noEmit",
+        "format": "biome format --write .",
+        "format:check": "biome format .",
+        "lint": "biome lint .",
+        "check": "biome check ."
+    },
+    "release": {
+        "branches": [
+            "main"
+        ],
+        "plugins": [
+            "@semantic-release/commit-analyzer",
+            "@semantic-release/release-notes-generator",
+            [
+                "@semantic-release/npm",
+                {
+                    "npmPublish": false
+                }
+            ],
+            [
+                "@semantic-release/exec",
+                {
+                    "publishCmd": "npm stage publish"
+                }
+            ],
+            [
+                "@semantic-release/git",
+                {
+                    "assets": [
+                        "package.json",
+                        "bun.lock"
+                    ],
+                    "message": "chore(release): ${nextRelease.version} [skip ci]"
+                }
+            ],
+            "@semantic-release/github"
+        ]
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.6.3",
+        "@commitlint/cli": "21.2.4",
+        "@commitlint/config-conventional": "21.2.4",
+        "@semantic-release/commit-analyzer": "13.0.1",
+        "@semantic-release/exec": "7.1.0",
+        "@semantic-release/git": "11.0.1",
+        "@semantic-release/github": "12.0.10",
+        "@semantic-release/npm": "13.2.0",
+        "@semantic-release/release-notes-generator": "14.1.1",
+        "@types/better-sqlite3": "9.6.0",
+        "@types/bun": "1.4.4",
+        "astro": "7.0.0",
+        "husky": "9.1.7",
+        "lint-staged": "17.6.0",
+        "semantic-release": "25.0.9",
+        "typescript": "7.0.2"
+    },
+    "dependencies": {
+        "better-sqlite3": "13.0.3",
+        "openai": "7.47.0"
+    }
+}