@pattern-js/mod-vectors 0.4.0-main.c8eb671

package/dist/ops.js

@@ -0,0 +1,138 @@
+/**
+ * @pattern-js/mod-vectors — the `vectors.*` op catalog.
+ *
+ * Pure domain ops over the VectorsService: declare a collection, chunk text,
+ * upsert (text is embedded through the collection's declared alias), query
+ * (vector / keyword / hybrid, filterable), delete — plus `vectors.index`,
+ * the chunk→embed→upsert convenience that makes on-canvas RAG ingestion a
+ * single node.
+ */
+import { value, z } from "@pattern-js/core";
+import { chunkDoc } from "./chunk.js";
+import { VECTORS_SERVICE } from "./service.js";
+import { collectionSpecSchema, filterSchema, queryModeSchema, vectorItemSchema } from "./types.js";
+function service(ctx) {
+    const svc = ctx.services[VECTORS_SERVICE];
+    if (!svc)
+        throw new Error("vectors: service not available — is @pattern-js/mod-vectors listed in pattern.config.json mods?");
+    return svc;
+}
+const chunkConfig = {
+    maxChars: z.number().int().positive().default(1200),
+    overlap: z.number().int().min(0).default(150),
+    separators: z.array(z.string()).default(["\n\n", "\n", ". "]),
+};
+const docSchema = z.object({
+    id: z.string().optional(),
+    text: z.string(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+const collectionEnsure = {
+    type: "vectors.collection.ensure",
+    title: "vectors.collection.ensure",
+    description: "Declare (idempotently) an embedding collection: name + embedding alias + filterable meta fields. " +
+        "Dims lock on first write; only declared filterables can be filtered on.",
+    config: collectionSpecSchema,
+    inputs: {},
+    outputs: { collection: value(z.string()) },
+    execute: async (ctx) => {
+        const spec = collectionSpecSchema.parse(ctx.config);
+        await service(ctx).ensureCollection(spec);
+        return { collection: spec.name };
+    },
+};
+const upsert = {
+    type: "vectors.upsert",
+    title: "vectors.upsert",
+    description: "Write items into a collection: { items: [{ id?, text, meta? } | { id, vector, meta? }] } → { count, embedded }. " +
+        "Text embeds through the collection's declared alias; unchanged items (same id + content hash) are skipped.",
+    config: z.object({ collection: z.string().min(1) }),
+    inputs: { items: value(z.array(vectorItemSchema)) },
+    outputs: { count: value(z.number()), embedded: value(z.number()) },
+    execute: async (ctx) => {
+        const { collection } = ctx.config;
+        const items = z.array(vectorItemSchema).parse((await ctx.input.value("items")) ?? []);
+        const res = await service(ctx).upsert(collection, items, ctx);
+        return { count: res.count, embedded: res.embedded };
+    },
+};
+const query = {
+    type: "vectors.query",
+    title: "vectors.query",
+    description: "Search a collection: text (embedded via the collection's alias) or a raw vector → { matches: [{ id, score, text, meta }] }. " +
+        "mode: vector | keyword | hybrid (RRF fusion); filter: { field: value | values[] } over DECLARED filterables, pruned before scoring.",
+    config: z.object({
+        collection: z.string().min(1),
+        k: z.number().int().positive().max(100).default(8),
+        mode: queryModeSchema.default("vector"),
+        filter: filterSchema.optional(),
+    }),
+    inputs: {
+        text: value(z.string().optional()),
+        vector: value(z.array(z.number()).optional()),
+        filter: value(filterSchema.optional()),
+    },
+    outputs: { matches: value() },
+    execute: async (ctx) => {
+        const cfg = ctx.config;
+        const [text, vector, filterIn] = await Promise.all([
+            ctx.input.has("text") ? ctx.input.value("text") : undefined,
+            ctx.input.has("vector") ? ctx.input.value("vector") : undefined,
+            ctx.input.has("filter") ? ctx.input.value("filter") : undefined,
+        ]);
+        const matches = await service(ctx).query(cfg.collection, { text: text ?? undefined, vector: vector ?? undefined, k: cfg.k, mode: cfg.mode, filter: filterIn ?? cfg.filter }, ctx);
+        return { matches };
+    },
+};
+const del = {
+    type: "vectors.delete",
+    title: "vectors.delete",
+    description: "Delete rows by id from a collection: { ids } → { count }.",
+    config: z.object({ collection: z.string().min(1) }),
+    inputs: { ids: value(z.array(z.string())) },
+    outputs: { count: value(z.number()) },
+    execute: async (ctx) => {
+        const { collection } = ctx.config;
+        const ids = (await ctx.input.value("ids")) ?? [];
+        return { count: await service(ctx).delete(collection, ids) };
+    },
+};
+const chunk = {
+    type: "vectors.chunk",
+    title: "vectors.chunk",
+    description: "Split text for indexing (recursive character splitter, overlap carried across boundaries). " +
+        "Input `text` (one string) or `docs` ([{ id?, text, meta? }]) → { chunks: [{ id, text, meta? }] } with ids `${docId}#${i}`.",
+    config: z.object(chunkConfig),
+    inputs: { text: value(z.string().optional()), docs: value(z.array(docSchema).optional()) },
+    outputs: { chunks: value() },
+    execute: async (ctx) => {
+        const cfg = ctx.config;
+        const [text, docs] = await Promise.all([
+            ctx.input.has("text") ? ctx.input.value("text") : undefined,
+            ctx.input.has("docs") ? ctx.input.value("docs") : undefined,
+        ]);
+        const inputDocs = docs?.length ? docs : text !== undefined && text !== null ? [{ text }] : [];
+        if (!inputDocs.length)
+            throw new Error("vectors.chunk: wire `text` (one string) or `docs` (an array of { id?, text, meta? })");
+        const chunks = inputDocs.flatMap((d) => chunkDoc(d, cfg));
+        return { chunks };
+    },
+};
+const index = {
+    type: "vectors.index",
+    title: "vectors.index",
+    description: "Chunk → embed → upsert in one node (the RAG ingestion convenience). Input `docs` ([{ id?, text, meta? }]); " +
+        "chunk ids are `${docId}#${i}`, each chunk carries its doc's meta. Unchanged chunks are skipped (content hash).",
+    config: z.object({ collection: z.string().min(1), ...chunkConfig }),
+    inputs: { docs: value(z.array(docSchema)) },
+    outputs: { count: value(z.number()), chunks: value(z.number()) },
+    execute: async (ctx) => {
+        const cfg = ctx.config;
+        const docs = z.array(docSchema).parse((await ctx.input.value("docs")) ?? []);
+        const chunks = docs.flatMap((d) => chunkDoc(d, cfg));
+        const res = await service(ctx).upsert(cfg.collection, chunks.map((c) => ({ id: c.id, text: c.text, meta: c.meta })), ctx);
+        return { count: res.count, chunks: chunks.length };
+    },
+};
+export const vectorsOps = [collectionEnsure, upsert, query, del, chunk, index];
+//# sourceMappingURL=ops.js.map

package/dist/ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.js","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"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"}

package/dist/service.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @pattern-js/mod-vectors — the VectorsService (key "vectorsService").
+ *
+ * The contract surface between ops/sibling mods and whichever engine is
+ * registered (mod-email's driver pattern: the default "local" engine ships
+ * here; sqlite-vec/pgvector drivers register in their `ready`). Embedding
+ * happens HERE, always through the collection's declared alias, via the
+ * duck-typed "aiProviderService" — mod-ai is never imported.
+ */
+import type { OpContext } from "@pattern-js/core";
+import type { CollectionInfo, CollectionSpec, Filter, ListedRow, Match, QueryMode, VectorItem, VectorsEngine } from "./types.js";
+export declare const VECTORS_SERVICE = "vectorsService";
+export interface VectorsService {
+    registerEngine(engine: VectorsEngine): void;
+    /** The active engine's id ("local" unless a driver replaced it). */
+    engineId(): string;
+    ensureCollection(spec: CollectionSpec): Promise<void>;
+    listCollections(): Promise<CollectionInfo[]>;
+    /** Embed-and-write. Items may carry raw vectors (embedding skipped) or text. */
+    upsert(collection: string, items: VectorItem[], ctx: OpContext): Promise<{
+        count: number;
+        embedded: number;
+    }>;
+    query(collection: string, input: {
+        text?: string;
+        vector?: number[];
+        k?: number;
+        filter?: Filter;
+        mode?: QueryMode;
+    }, ctx: OpContext): Promise<Match[]>;
+    /** Enumerate rows newest-first (admin browsers, memory managers) — no scoring, that's `query`. */
+    list(collection: string, q?: {
+        filter?: Filter;
+        limit?: number;
+        offset?: number;
+    }): Promise<ListedRow[]>;
+    delete(collection: string, ids: string[]): Promise<number>;
+}
+export declare class DefaultVectorsService implements VectorsService {
+    private readonly engines;
+    private active;
+    constructor(local: VectorsEngine);
+    registerEngine(engine: VectorsEngine): void;
+    engineId(): string;
+    private engine;
+    ensureCollection(spec: CollectionSpec): Promise<void>;
+    listCollections(): Promise<CollectionInfo[]>;
+    private spec;
+    /** The collection's embedding model, via its declared alias — the ONE path to a vector. */
+    private model;
+    private embed;
+    upsert(collection: string, items: VectorItem[], ctx: OpContext): Promise<{
+        count: number;
+        embedded: number;
+    }>;
+    query(collection: string, input: {
+        text?: string;
+        vector?: number[];
+        k?: number;
+        filter?: Filter;
+        mode?: QueryMode;
+    }, ctx: OpContext): Promise<Match[]>;
+    list(collection: string, q?: {
+        filter?: Filter;
+        limit?: number;
+        offset?: number;
+    }): Promise<ListedRow[]>;
+    delete(collection: string, ids: string[]): Promise<number>;
+    /** Undeclared filter field = a located error naming the field AND the fix. */
+    private assertFilterable;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/service.js

@@ -0,0 +1,166 @@
+/**
+ * @pattern-js/mod-vectors — the VectorsService (key "vectorsService").
+ *
+ * The contract surface between ops/sibling mods and whichever engine is
+ * registered (mod-email's driver pattern: the default "local" engine ships
+ * here; sqlite-vec/pgvector drivers register in their `ready`). Embedding
+ * happens HERE, always through the collection's declared alias, via the
+ * duck-typed "aiProviderService" — mod-ai is never imported.
+ */
+import { createHash } from "node:crypto";
+import { normalize } from "./engine-local.js";
+export const VECTORS_SERVICE = "vectorsService";
+/* ── duck-typed views of mod-ai (never imported) ─────────────────────────── */
+const AI_PROVIDER_SERVICE = "aiProviderService";
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+/** Meta values for the DECLARED filterable fields (arrays flatten to any-of). */
+function extractFilterables(meta, declared) {
+    const out = {};
+    if (!meta)
+        return out;
+    for (const field of declared) {
+        const raw = meta[field];
+        if (raw === undefined || raw === null)
+            continue;
+        const values = (Array.isArray(raw) ? raw : [raw]).filter((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean");
+        if (values.length)
+            out[field] = values;
+    }
+    return out;
+}
+export class DefaultVectorsService {
+    engines = new Map();
+    active;
+    constructor(local) {
+        this.engines.set(local.id, local);
+        this.active = local.id;
+    }
+    registerEngine(engine) {
+        this.engines.set(engine.id, engine);
+        // Last registered driver wins (there is at most one real driver installed);
+        // the local engine stays available as "local".
+        this.active = engine.id;
+    }
+    engineId() {
+        return this.active;
+    }
+    engine() {
+        return this.engines.get(this.active);
+    }
+    async ensureCollection(spec) {
+        if (!spec.alias) {
+            throw new Error(`vectors: collection "${spec.name}" must declare its embedding alias — that declaration is what makes ` +
+                "index-with-one-model-query-with-another unrepresentable.");
+        }
+        await this.engine().ensureCollection(spec);
+    }
+    listCollections() {
+        return this.engine().listCollections();
+    }
+    async spec(collection) {
+        const spec = await this.engine().getCollection(collection);
+        if (!spec) {
+            throw new Error(`vectors: unknown collection "${collection}" — declare it first with vectors.collection.ensure`);
+        }
+        return spec;
+    }
+    /** The collection's embedding model, via its declared alias — the ONE path to a vector. */
+    async model(spec, ctx) {
+        const provider = ctx.services[AI_PROVIDER_SERVICE];
+        if (!provider || typeof provider.textEmbeddingModel !== "function") {
+            throw new Error(`vectors: embedding text for collection "${spec.name}" needs @pattern-js/mod-ai installed ` +
+                `(it provides the "${spec.alias}" embedding alias). Raw-vector upsert/query works without it.`);
+        }
+        return provider.textEmbeddingModel({ alias: spec.alias }, ctx);
+    }
+    async embed(spec, values, ctx) {
+        if (!values.length)
+            return [];
+        const model = await this.model(spec, ctx);
+        const perCallRaw = typeof model.maxEmbeddingsPerCall === "function" ? await model.maxEmbeddingsPerCall() : model.maxEmbeddingsPerCall;
+        const perCall = Math.max(1, Math.min(Number(perCallRaw) || 64, 64));
+        const out = [];
+        for (let i = 0; i < values.length; i += perCall) {
+            const batch = values.slice(i, i + perCall);
+            const { embeddings } = await model.doEmbed({ values: batch, abortSignal: ctx.signal });
+            for (const e of embeddings)
+                out.push(normalize(e));
+        }
+        return out;
+    }
+    async upsert(collection, items, ctx) {
+        const spec = await this.spec(collection);
+        const rows = [];
+        const toEmbed = [];
+        for (const item of items) {
+            if (item.vector === undefined && !item.text?.trim()) {
+                throw new Error(`vectors: an upsert item needs \`text\` (embedded via alias "${spec.alias}") or a raw \`vector\``);
+            }
+            const id = item.id ?? sha256(item.text ?? JSON.stringify(item.vector)).slice(0, 24);
+            const hash = sha256(JSON.stringify({ t: item.text ?? null, v: item.vector ?? null, m: item.meta ?? null }));
+            rows.push({
+                id,
+                vector: item.vector ? normalize(item.vector) : null,
+                text: item.text ?? null,
+                meta: item.meta ?? null,
+                filterValues: extractFilterables(item.meta, spec.filterables),
+                hash,
+            });
+            if (item.vector === undefined)
+                toEmbed.push({ index: rows.length - 1, text: item.text });
+        }
+        // Content-hash diffing: unchanged rows (same id + hash) skip re-embedding
+        // AND re-writing — the boot indexer leans on this after every upgrade.
+        const existing = await this.engine().hashes(collection, rows.map((r) => r.id));
+        const changed = new Set(rows.filter((r) => existing.get(r.id) !== r.hash).map((r) => r.id));
+        const pendingEmbeds = toEmbed.filter(({ index }) => changed.has(rows[index].id));
+        const embeddings = await this.embed(spec, pendingEmbeds.map((p) => p.text), ctx);
+        pendingEmbeds.forEach(({ index }, i) => {
+            rows[index].vector = embeddings[i];
+        });
+        const writes = rows.filter((r) => changed.has(r.id));
+        await this.engine().upsert(collection, writes);
+        return { count: writes.length, embedded: embeddings.length };
+    }
+    async query(collection, input, ctx) {
+        const spec = await this.spec(collection);
+        const mode = input.mode ?? "vector";
+        const k = Math.max(1, Math.min(input.k ?? 8, 100));
+        if (input.filter)
+            this.assertFilterable(spec, input.filter, collection);
+        if (!input.text?.trim() && input.vector === undefined) {
+            throw new Error("vectors: query needs `text` (embedded via the collection's alias) or a raw `vector`");
+        }
+        if (mode !== "vector" && !input.text?.trim()) {
+            throw new Error(`vectors: mode "${mode}" ranks by keywords — it needs a \`text\` query`);
+        }
+        let vector;
+        if (mode !== "keyword") {
+            vector = input.vector ? normalize(input.vector) : (await this.embed(spec, [input.text], ctx))[0];
+        }
+        return this.engine().query(collection, { vector, text: input.text, k, filter: input.filter, mode });
+    }
+    async list(collection, q = {}) {
+        const spec = await this.spec(collection);
+        if (q.filter)
+            this.assertFilterable(spec, q.filter, collection);
+        const eng = this.engine();
+        if (!eng.list)
+            throw new Error(`vectors: engine "${eng.id}" does not support listing rows`);
+        return eng.list(collection, q);
+    }
+    delete(collection, ids) {
+        return this.engine().delete(collection, ids);
+    }
+    /** Undeclared filter field = a located error naming the field AND the fix. */
+    assertFilterable(spec, filter, collection) {
+        const declared = new Set(spec.filterables);
+        for (const field of Object.keys(filter)) {
+            if (!declared.has(field)) {
+                throw new Error(`vectors: "${field}" is not a filterable field of collection "${collection}" — declared: ` +
+                    `[${spec.filterables.join(", ") || "none"}]. Add it to \`filterables\` in vectors.collection.ensure and re-upsert.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @pattern-js/mod-vectors — value shapes + the engine SPI.
+ *
+ * The load-bearing idea: a collection DECLARES its embedding alias (and, once
+ * written, its dimensions), so "indexed with one model, queried with another"
+ * — the classic silent RAG bug — is unrepresentable. Filterable metadata is
+ * declared the same way (mod-store's declared-index philosophy): only
+ * declared fields are indexed and only declared fields may be filtered on,
+ * so a typo'd filter is a located error, not an empty result.
+ */
+import { z } from "@pattern-js/core";
+export declare const filterValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+/** AND of equality/any-of — deliberately minimal so every driver can push it down. */
+export declare const filterSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>>;
+export type Filter = z.infer<typeof filterSchema>;
+export type FilterValue = z.infer<typeof filterValueSchema>;
+export declare const queryModeSchema: z.ZodEnum<{
+    vector: "vector";
+    keyword: "keyword";
+    hybrid: "hybrid";
+}>;
+export type QueryMode = z.infer<typeof queryModeSchema>;
+export declare const collectionSpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    alias: z.ZodString;
+    dims: z.ZodOptional<z.ZodNumber>;
+    metric: z.ZodDefault<z.ZodLiteral<"cosine">>;
+    filterables: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type CollectionSpec = z.infer<typeof collectionSpecSchema>;
+/** One upsert item: text to embed (id defaults to a hash) or a raw vector. */
+export declare const vectorItemSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    vector: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type VectorItem = z.infer<typeof vectorItemSchema>;
+export interface Match {
+    id: string;
+    score: number;
+    text: string | null;
+    meta: Record<string, unknown> | null;
+}
+export interface CollectionInfo extends CollectionSpec {
+    rows: number;
+}
+/** A fully-prepared row the service hands the engine (embedding already done). */
+export interface EngineRow {
+    id: string;
+    /** L2-normalized (cosine = dot); null for keyword-only rows. */
+    vector: Float32Array | null;
+    text: string | null;
+    meta: Record<string, unknown> | null;
+    /** Values for the DECLARED filterable fields, pre-extracted from meta. */
+    filterValues: Record<string, FilterValue[]>;
+    /** Content hash — lets indexers skip re-embedding unchanged text. */
+    hash: string;
+}
+export interface EngineQuery {
+    /** L2-normalized query vector (vector/hybrid modes). */
+    vector?: Float32Array;
+    /** The raw text query (keyword/hybrid modes). */
+    text?: string;
+    k: number;
+    filter?: Filter;
+    mode: QueryMode;
+}
+/**
+ * The driver SPI (mod-email's registerDriver pattern). The default "local"
+ * engine is sqlite-backed brute force; sqlite-vec / pgvector drivers register
+ * the same shape and receive `{ filter, mode }` to push down.
+ */
+/** One stored row, as enumeration (no scores — that's `query`'s job). */
+export interface ListedRow {
+    id: string;
+    text: string | null;
+    meta: Record<string, unknown> | null;
+    updatedAt: number;
+}
+export interface VectorsEngine {
+    id: string;
+    ensureCollection(spec: CollectionSpec): Promise<void>;
+    getCollection(name: string): Promise<CollectionSpec | null>;
+    listCollections(): Promise<CollectionInfo[]>;
+    /** Existing content hashes for these ids (indexers diff against this). */
+    hashes(collection: string, ids: string[]): Promise<Map<string, string>>;
+    upsert(collection: string, rows: EngineRow[]): Promise<void>;
+    query(collection: string, q: EngineQuery): Promise<Match[]>;
+    delete(collection: string, ids: string[]): Promise<number>;
+    /**
+     * Enumerate rows, newest-first, optionally pruned by a declared-filterable
+     * filter (admin browsers, memory managers). OPTIONAL — a driver that can't
+     * scan cheaply may omit it; the service reports that honestly.
+     */
+    list?(collection: string, q: {
+        filter?: Filter;
+        limit?: number;
+        offset?: number;
+    }): Promise<ListedRow[]>;
+    /** Lock dims on first write; throws (naming the alias) on mismatch. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,33 @@
+/**
+ * @pattern-js/mod-vectors — value shapes + the engine SPI.
+ *
+ * The load-bearing idea: a collection DECLARES its embedding alias (and, once
+ * written, its dimensions), so "indexed with one model, queried with another"
+ * — the classic silent RAG bug — is unrepresentable. Filterable metadata is
+ * declared the same way (mod-store's declared-index philosophy): only
+ * declared fields are indexed and only declared fields may be filtered on,
+ * so a typo'd filter is a located error, not an empty result.
+ */
+import { z } from "@pattern-js/core";
+export const filterValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+/** AND of equality/any-of — deliberately minimal so every driver can push it down. */
+export const filterSchema = z.record(z.string(), z.union([filterValueSchema, z.array(filterValueSchema)]));
+export const queryModeSchema = z.enum(["vector", "keyword", "hybrid"]);
+export const collectionSpecSchema = z.object({
+    name: z.string().min(1),
+    /** The embedding alias this collection indexes AND queries with. */
+    alias: z.string().min(1),
+    /** Locked on first write when omitted; a later mismatch is a hard, located error. */
+    dims: z.number().int().positive().optional(),
+    metric: z.literal("cosine").default("cosine"),
+    /** Meta fields extracted into the indexed side table — the ONLY filterable fields. */
+    filterables: z.array(z.string()).default([]),
+});
+/** One upsert item: text to embed (id defaults to a hash) or a raw vector. */
+export const vectorItemSchema = z.object({
+    id: z.string().optional(),
+    text: z.string().optional(),
+    vector: z.array(z.number()).optional(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAC;AAErC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAChF,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;AAI3G,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,oEAAoE;IACpE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,qFAAqF;IACrF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5C,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC7C,sFAAsF;IACtF,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC7C,CAAC,CAAC;AAGH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACzB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACnD,CAAC,CAAC"}