{ "name": "@forge-sdk/embed", "language": "typescript", "version": "0.1.0", "description": "Embedding, reranking, vector store, and document chunking for the Forge SDK", "manifest": "forge-ts/packages/forge-embed/package.json", "manifestSha256": "edabb7540370afd3209e18fb51df977e5e33cffc738399f7f6bdbb2217ece289", "status": "source-reference", "registryPublicationVerified": false, "route": "/libraries/typescript/embed", "features": {}, "files": [ { "path": "forge-ts/packages/forge-embed/src/chunking.ts", "sha256": "c78ef30a78111bcfeb5c5ed82e48a59c3144035d43a0961485dcaded4acb2e93", "artifactSha256": "f6e612fce831207c30b367b5556b83b8011d51e0cf982f0d69d04c53ccf28660", "url": "/reference/source/forge-ts/packages/forge-embed/src/chunking.ts.txt", "declarations": [ { "name": "TextSplitter", "line": 26, "signature": "export interface TextSplitter {\n /**\n * Splits text into chunks.\n *\n * @param text - The text to split.\n * @returns An array of text chunks.\n */\n split(text: string): string[];\n}", "documentation": "Interface for splitting text into chunks.\n\nText splitters break long documents into smaller pieces suitable for\nembedding. Different strategies optimize for different use cases\n(semantic boundaries, token counts, etc.)." }, { "name": "RecursiveCharacterSplitterOptions", "line": 39, "signature": "export interface RecursiveCharacterSplitterOptions {\n /** Maximum number of characters per chunk. Defaults to 1000. */\n readonly chunkSize?: number;\n /** Number of overlapping characters between consecutive chunks. Defaults to 200. */\n readonly chunkOverlap?: number;\n /**\n * Separator hierarchy from coarsest to finest. Defaults to\n * `['\\n\\n', '\\n', '. ', ' ', '']` (paragraphs, lines, sentences, words, chars).\n */\n readonly separators?: readonly string[];\n}", "documentation": "" }, { "name": "RecursiveCharacterSplitter", "line": 70, "signature": "export class RecursiveCharacterSplitter implements TextSplitter {\n constructor(options: RecursiveCharacterSplitterOptions = {});\n split(text: string): string[];\n}", "documentation": "Splits text recursively using a hierarchy of separators.\n\nThe splitter tries the coarsest separator first (e.g., paragraph breaks),\nand falls back to finer separators when chunks exceed the target size.\nConsecutive chunks overlap by `chunkOverlap` characters to preserve context.\n\nANVIL Spec section 9.3 -- Document chunking for RAG pipelines." }, { "name": "TokenSplitterOptions", "line": 232, "signature": "export interface TokenSplitterOptions {\n /** Maximum number of tokens per chunk. Defaults to 256. */\n readonly tokensPerChunk?: number;\n /** Number of overlapping tokens between consecutive chunks. Defaults to 0. */\n readonly tokenOverlap?: number;\n}", "documentation": "" }, { "name": "TokenSplitter", "line": 252, "signature": "export class TokenSplitter implements TextSplitter {\n constructor(options: TokenSplitterOptions = {});\n split(text: string): string[];\n}", "documentation": "Splits text by approximate token count using whitespace tokenization.\n\nThis is a simple, zero-dependency token splitter that approximates token\nboundaries by splitting on whitespace. For precise token counts matching\na specific model's tokenizer, use a model-specific tokenizer." } ] }, { "path": "forge-ts/packages/forge-embed/src/document.ts", "sha256": "3d878445022e2b7a05ab30c9e2a5c85910adb9fae3cc3d5b58ec366a8bf474cb", "artifactSha256": "69aee9bd6f60be5de140f8c08292e4d15923c6db3b0399f0fd191fb77443cb98", "url": "/reference/source/forge-ts/packages/forge-embed/src/document.ts.txt", "declarations": [ { "name": "Document", "line": 27, "signature": "export interface Document {\n /** The text content of the document. */\n readonly content: string;\n /** Optional key-value metadata for filtering and context. */\n readonly metadata: Record;\n}", "documentation": "A document with content and metadata.\n\nDocuments are the input to embedding pipelines. The content is the text\nto be embedded, and metadata provides additional context for filtering\nand retrieval." }, { "name": "DocumentLoader", "line": 45, "signature": "export interface DocumentLoader {\n /**\n * Loads documents from the given source.\n *\n * @param source - The source content (text, JSON string, URL, etc.).\n * @returns An array of loaded documents.\n * @throws {ForgeEmbedError} If loading fails.\n */\n load(source: string): Promise;\n}", "documentation": "Interface for loading documents from various sources.\n\nImplementors provide document loading from files, APIs, databases, etc." }, { "name": "TextLoader", "line": 69, "signature": "export class TextLoader implements DocumentLoader {\n async load(source: string): Promise;\n}", "documentation": "Loads raw text as a single document.\n\nThe entire input text becomes the document content. No parsing or\ntransformation is applied." }, { "name": "JsonLoader", "line": 101, "signature": "export class JsonLoader implements DocumentLoader {\n constructor(contentField?: string);\n async load(source: string): Promise;\n}", "documentation": "Loads documents from a JSON string.\n\nSupports both JSON arrays (each element becomes a document) and single\nJSON objects. When a `contentField` is specified, only that field is\nextracted as the document content; otherwise the entire JSON is used." } ] }, { "path": "forge-ts/packages/forge-embed/src/embed.ts", "sha256": "f975e97d95f3f1309109f31e8d0265b0ccdabb868ca717949e22baa490b5673a", "artifactSha256": "fae5899fd8a68a053b57ac05415ea4661ff6b905707d619c41289c252c47a5e3", "url": "/reference/source/forge-ts/packages/forge-embed/src/embed.ts.txt", "declarations": [ { "name": "EmbeddingResult", "line": 22, "signature": "export interface EmbeddingResult {\n /** The embedding vector as an array of floating-point numbers. */\n readonly vector: readonly number[];\n /** The model identifier that produced this embedding. */\n readonly model: string;\n /** The dimensionality of the embedding vector. */\n readonly dimensions: number;\n}", "documentation": "The result of embedding a single text string." }, { "name": "EmbeddingProvider", "line": 47, "signature": "export interface EmbeddingProvider {\n /** Returns the model identifier (e.g., 'text-embedding-3-small'). */\n modelId(): string;\n\n /**\n * Embeds one or more text strings into vectors.\n *\n * @param texts - The text strings to embed.\n * @returns An array of EmbeddingResult, one per input text.\n * @throws {ForgeEmbedError} If the model fails or input is invalid.\n */\n embed(texts: string[]): Promise;\n}", "documentation": "Interface for embedding text into vector representations.\n\nImplementors connect to an embedding model (e.g., OpenAI text-embedding-3-small,\nCohere embed-english-v3, local ONNX models) and produce dense vectors." }, { "name": "embed", "line": 78, "signature": "export async function embed(\n provider: EmbeddingProvider,\n text: string\n): Promise;", "documentation": "" }, { "name": "embedMany", "line": 120, "signature": "export async function embedMany(\n provider: EmbeddingProvider,\n texts: string[]\n): Promise;", "documentation": "Embeds multiple text strings using the given provider." } ] }, { "path": "forge-ts/packages/forge-embed/src/error.ts", "sha256": "bfad05cc472b9ebce441fd8235b6620d7206e60fa5a11be814364e9ef6ad199d", "artifactSha256": "96a88a1b3185740aff7d207e12c8dd87d6f78d52d3ae3439502849c7bf02e8ee", "url": "/reference/source/forge-ts/packages/forge-embed/src/error.ts.txt", "declarations": [ { "name": "export const ForgeEmbedErrorCode = {", "line": 13, "signature": "export const ForgeEmbedErrorCode /* type inferred in source */;", "documentation": "Error types for the `@forge-sdk/embed` package.\n\nAll errors are typed and actionable. Error messages include enough context\nfor the developer to diagnose the issue without reading source code.\nError code enumeration for `@forge-sdk/embed`." }, { "name": "ForgeEmbedErrorCodeType", "line": 23, "signature": "export type ForgeEmbedErrorCodeType = (typeof ForgeEmbedErrorCode)[keyof typeof ForgeEmbedErrorCode];", "documentation": "Error code type." }, { "name": "ForgeEmbedError", "line": 42, "signature": "export class ForgeEmbedError extends Error {\n public readonly code: ForgeEmbedErrorCodeType;\n static modelError(model: string, reason: string): ForgeEmbedError;\n static dimensionMismatch(expected: number, actual: number): ForgeEmbedError;\n static emptyInput(operation: string): ForgeEmbedError;\n static storeError(operation: string, reason: string): ForgeEmbedError;\n static chunkingError(reason: string): ForgeEmbedError;\n static core(reason: string): ForgeEmbedError;\n}", "documentation": "Error class for embedding operations.\n\nCovers embedding model errors, dimension mismatches, empty inputs,\nvector store failures, and chunking errors." } ] }, { "path": "forge-ts/packages/forge-embed/src/index.ts", "sha256": "0fa5f724b4e93768ad0d20d4dc1080c2004cb9e1803be041bdf163a00c8c89bf", "artifactSha256": "ca728e1ea7dc4c7bb20b51e220a600ae6db7446937dc45e40f85d5ab488aec30", "url": "/reference/source/forge-ts/packages/forge-embed/src/index.ts.txt", "declarations": [ { "name": "export { ForgeEmbedError, ForgeEmbedErrorCode, type ForgeEmbedErrorCodeType } from './error.js';", "line": 29, "signature": "export { ForgeEmbedError, ForgeEmbedErrorCode, type ForgeEmbedErrorCodeType } from './error.js';", "documentation": "" }, { "name": "export { type EmbeddingProvider, type EmbeddingResult, embed, embedMany } from './embed.js';", "line": 32, "signature": "export { type EmbeddingProvider, type EmbeddingResult, embed, embedMany } from './embed.js';", "documentation": "" }, { "name": "export { cosineSimilarity, euclideanDistance, dotProduct } from './similarity.js';", "line": 35, "signature": "export { cosineSimilarity, euclideanDistance, dotProduct } from './similarity.js';", "documentation": "" }, { "name": "export { type Reranker, type RerankResult, rerank } from './rerank.js';", "line": 38, "signature": "export { type Reranker, type RerankResult, rerank } from './rerank.js';", "documentation": "" }, { "name": "export {", "line": 41, "signature": "export {\n type VectorStore,\n type VectorEntry,\n type SearchResult,\n InMemoryVectorStore,\n} from './vector-store.js';", "documentation": "" }, { "name": "export {", "line": 49, "signature": "export {\n type TextSplitter,\n RecursiveCharacterSplitter,\n type RecursiveCharacterSplitterOptions,\n TokenSplitter,\n type TokenSplitterOptions,\n} from './chunking.js';", "documentation": "" }, { "name": "export {", "line": 58, "signature": "export {\n type Document,\n type DocumentLoader,\n TextLoader,\n JsonLoader,\n} from './document.js';", "documentation": "" } ] }, { "path": "forge-ts/packages/forge-embed/src/rerank.ts", "sha256": "a3d8d10790b25cf564329f5b6f0b3c6000edd2e3f6dc0f9e9d7a8e5170c8c3a2", "artifactSha256": "1055d227b8ecff4700b0ffd15d024247ff26011762d69f28a04fade8f9c0abc4", "url": "/reference/source/forge-ts/packages/forge-embed/src/rerank.ts.txt", "declarations": [ { "name": "RerankResult", "line": 20, "signature": "export interface RerankResult {\n /** The original index of this document in the input array. */\n readonly index: number;\n /** The relevance score (higher is more relevant). */\n readonly score: number;\n /** The document text. */\n readonly document: string;\n}", "documentation": "The result of reranking a single document.\n\nContains the original index, relevance score, and document text." }, { "name": "Reranker", "line": 42, "signature": "export interface Reranker {\n /**\n * Reranks documents by relevance to a query.\n *\n * @param query - The search query.\n * @param documents - The documents to rerank.\n * @param topK - Maximum number of results to return.\n * @returns Reranked documents sorted by score descending.\n */\n rerank(query: string, documents: string[], topK: number): Promise;\n}", "documentation": "Interface for document reranking implementations.\n\nRerankers score and sort documents by relevance to a query. The default\nimplementation uses embedding cosine similarity, but dedicated reranker\nmodels (e.g., Cohere Rerank, cross-encoders) can provide higher quality." }, { "name": "rerank", "line": 76, "signature": "export async function rerank(\n provider: EmbeddingProvider,\n query: string,\n documents: string[],\n topK: number\n): Promise;", "documentation": "Reranks documents by cosine similarity to a query using an embedding provider.\n\nThis function embeds the query and all documents, computes cosine similarity\nbetween the query embedding and each document embedding, and returns the\ntop K results sorted by score descending." } ] }, { "path": "forge-ts/packages/forge-embed/src/similarity.ts", "sha256": "9bbc850743288983d64be5750a058959457d621179b03492c5cd52b4c4c4bb25", "artifactSha256": "b45e225885facc8dcac256149f83adedddbbeb98565b417e18e577d7118f7576", "url": "/reference/source/forge-ts/packages/forge-embed/src/similarity.ts.txt", "declarations": [ { "name": "cosineSimilarity", "line": 33, "signature": "export function cosineSimilarity(a: readonly number[], b: readonly number[]): number;", "documentation": "Computes the cosine similarity between two vectors.\n\nCosine similarity measures the cosine of the angle between two vectors,\nproducing a value in the range [-1, 1] where 1 means identical direction,\n0 means orthogonal, and -1 means opposite direction." }, { "name": "euclideanDistance", "line": 73, "signature": "export function euclideanDistance(a: readonly number[], b: readonly number[]): number;", "documentation": "Computes the Euclidean distance between two vectors.\n\nEuclidean distance is the L2 norm of the difference vector. Lower values\nindicate more similar vectors." }, { "name": "dotProduct", "line": 102, "signature": "export function dotProduct(a: readonly number[], b: readonly number[]): number;", "documentation": "Computes the dot product of two vectors.\n\nThe dot product is the sum of element-wise products. For normalized vectors,\nthe dot product equals the cosine similarity." } ] }, { "path": "forge-ts/packages/forge-embed/src/vector-store.ts", "sha256": "891f3d1715a5a8ebcf481ff1c2d9588650e0a82b2972c0c0470c3eb37e41dbe1", "artifactSha256": "c7c8ceb1c960a28b493000df8a7492ce969f3f2b27aa374e8c59225a0ba3767d", "url": "/reference/source/forge-ts/packages/forge-embed/src/vector-store.ts.txt", "declarations": [ { "name": "VectorEntry", "line": 20, "signature": "export interface VectorEntry {\n /** The unique identifier for this entry. */\n readonly id: string;\n /** The embedding vector. */\n readonly vector: readonly number[];\n /** Optional key-value metadata for filtering and retrieval. */\n readonly metadata: Record;\n}", "documentation": "A single entry in a vector store.\n\nEach entry has a unique identifier, a dense vector, and optional\nmetadata for filtering." }, { "name": "SearchResult", "line": 34, "signature": "export interface SearchResult {\n /** The matching vector entry. */\n readonly entry: VectorEntry;\n /** The similarity score (higher is more similar). */\n readonly score: number;\n}", "documentation": "A search result from a vector store query.\n\nContains the matching entry and its similarity score." }, { "name": "VectorStore", "line": 54, "signature": "export interface VectorStore {\n /**\n * Inserts a vector entry into the store.\n *\n * If an entry with the same ID already exists, it is overwritten.\n *\n * @param entry - The vector entry to insert.\n * @throws {ForgeEmbedError} If the insert fails.\n */\n insert(entry: VectorEntry): Promise;\n\n /**\n * Searches for the top K most similar vectors to the query.\n *\n * @param queryVector - The query vector.\n * @param topK - Maximum number of results to return.\n * @returns An array of SearchResult sorted by score descending.\n * @throws {ForgeEmbedError} If the search fails.\n */\n search(queryVector: readonly number[], topK: number): Promise;\n\n /**\n * Deletes a vector entry by its identifier.\n *\n * @param id - The identifier of the entry to delete.\n * @returns `true` if the entry was found and deleted, `false` otherwise.\n * @throws {ForgeEmbedError} If the delete fails.\n */\n delete(id: string): Promise;\n}", "documentation": "Interface for vector storage and similarity search.\n\nImplementations may use various indexing strategies (brute force,\nHNSW, IVF, etc.) and storage backends (in-memory, SQLite, Pinecone, etc.)." }, { "name": "InMemoryVectorStore", "line": 99, "signature": "export class InMemoryVectorStore implements VectorStore {\n async insert(entry: VectorEntry): Promise;\n async search(queryVector: readonly number[], topK: number): Promise;\n async delete(id: string): Promise;\n get size(): number;\n}", "documentation": "An in-memory vector store using brute-force cosine similarity.\n\nSuitable for development, testing, and small-scale use cases.\nFor production with large vector collections, use a dedicated\nvector database (Pinecone, Qdrant, Weaviate, etc.)." } ] } ] }