@claude-flow/embeddings/dist/synthetic-corpus.d.ts

V3 Embedding Service - OpenAI, Transformers.js, Agentic-Flow (ONNX), Mock providers with hyperbolic embeddings, normalization, and chunking

/**
 * ADR-121 Phase 15 — Synthetic topic-clustered corpus builder.
 *
 * Generates a deterministic, reproducible vector corpus with known
 * topic structure + known relevance judgements. Used by the RAG
 * scale benchmark and available as a pure-function utility for
 * users who want to benchmark their own retrieval pipelines without
 * sourcing real corpora.
 *
 * Topology: N topics × D docs per topic. Each topic has a "centroid"
 * direction in vector space; its docs are noisy variants near that
 * centroid. A configurable fraction of each topic's docs are
 * "duplicate-heavy" (very close to the centroid) — useful for
 * stressing diversification primitives. The remaining docs spread
 * along secondary axes for diversity.
 *
 * Determinism: same options → same corpus, bit-for-bit. Uses a
 * deterministic PRNG seeded by `seed` (default 42).
 */
export interface SyntheticCorpusOptions {
    /** Number of distinct topics. Each topic gets its own axis in vector space. */
    readonly topics: number;
    /** Docs per topic. Total corpus size = topics × docsPerTopic. */
    readonly docsPerTopic: number;
    /** Embedding dimension. Must be >= topics. */
    readonly dim: number;
    /**
     * Fraction of each topic's docs that are near-duplicate (very close
     * to the topic centroid). The rest spread along secondary axes for
     * diversity. Default 0.4 (40% dup-heavy, 60% diverse).
     * Range: [0, 1].
     */
    readonly duplicateRatio?: number;
    /**
     * Noise scale added to each doc vector. Default 0.05. Larger noise
     * makes topics less separable.
     */
    readonly noiseLevel?: number;
    /** PRNG seed. Same seed → identical corpus. Default 42. */
    readonly seed?: number;
}
export interface SyntheticCorpusEntry {
    readonly id: string;
    /** Topic this doc belongs to. */
    readonly topic: number;
    /** True if this is a near-duplicate (vs a diverse member of the topic). */
    readonly isDuplicate: boolean;
    /** L2-normalized vector. */
    readonly vector: Float32Array;
}
export interface SyntheticCorpus {
    readonly entries: ReadonlyArray<SyntheticCorpusEntry>;
    /** topic index → set of doc ids belonging to that topic */
    readonly relevantByTopic: ReadonlyArray<ReadonlySet<string>>;
    /** Canonical query vector for each topic (the topic's centroid direction). */
    readonly topicQueryVectors: ReadonlyArray<Float32Array>;
    readonly options: Required<SyntheticCorpusOptions>;
}
/**
 * Build a synthetic topic-clustered corpus.
 *
 * Time complexity: O(topics · docsPerTopic · dim). Memory: same.
 *
 * For each topic t in [0, topics):
 *   - centroid = unit vector with axis t = 1
 *   - dup docs: centroid + small noise (within duplicateRatio of total)
 *   - diverse docs: centroid + larger secondary-axis components + noise
 *   - all L2-normalized
 *
 * Returns:
 *   - entries: flat list of docs (interleaved by topic for shuffle resistance)
 *   - relevantByTopic[t]: set of doc IDs belonging to topic t
 *   - topicQueryVectors[t]: canonical query vector for topic t
 */
export declare function buildSyntheticTopicCorpus(options: SyntheticCorpusOptions): SyntheticCorpus;
//# sourceMappingURL=synthetic-corpus.d.ts.map