@nhtio/adk 1.20260607.2 → 1.20260609.1

package/batteries/vector/builder.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"builder.mjs","names":["#pushOrBranch","#sink","#collection","#topK","#near","#selectCalled","#projection","#offset","#consistency","#run","#validateRawFilters"],"sources":["../../../src/batteries/vector/builder.ts"],"sourcesContent":["/**\n * Knex-style chainable query builder for the vector storage battery.\n *\n * @module @nhtio/adk/batteries/vector/builder\n */\n\nimport { isRawFilter, isFilterCondition } from './filters'\nimport {\n  E_VECTOR_STORE_QUERY_CONFLICT,\n  E_VECTOR_STORE_PROJECTION_REQUIRED,\n  E_VECTOR_STORE_RAW_BINDING_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR,\n} from './exceptions'\nimport type { VectorRecord, VectorMatch, VectorConsistency } from './types'\nimport type { SearchPlan, UpsertPlan, DeletePlan, Projection } from './plan'\nimport type { VectorFilter, FilterCondition, FilterOperator } from './filters'\n\nconst OP_ALIASES: Record<string, FilterOperator> = {\n  '=': 'eq',\n  '==': 'eq',\n  '===': 'eq',\n  '!=': 'ne',\n  '<>': 'ne',\n  '!==': 'ne',\n  '>': 'gt',\n  '>=': 'gte',\n  '<': 'lt',\n  '<=': 'lte',\n  'eq': 'eq',\n  'ne': 'ne',\n  'gt': 'gt',\n  'gte': 'gte',\n  'lt': 'lt',\n  'lte': 'lte',\n  'in': 'in',\n  'nin': 'nin',\n  'exists': 'exists',\n  'contains': 'contains',\n}\nconst normalizeOp = (op: string): FilterOperator => {\n  const norm = OP_ALIASES[op]\n  if (!norm) throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['builder', op])\n  return norm\n}\n\nexport interface PlanSink {\n  executeSearch(plan: SearchPlan): Promise<VectorMatch[]>\n  executeUpsert(plan: UpsertPlan): Promise<void>\n  executeDelete(plan: DeletePlan): Promise<void>\n}\n\nexport type SelectArg =\n  | string\n  | [string, Record<string, unknown>]\n  | Record<string, Record<string, unknown> | true>\n\n/**\n * A callback that receives a fresh filter-only builder, used to express a parenthesized group of\n * conditions — `A AND (B OR C)`, `NOT (…)`, and arbitrary nesting. The callback mutates the builder\n * in place (knex-style); its accumulated conditions become a single nested `VectorFilter`.\n *\n * @see {@link FilterBuilder.where}\n */\nexport type FilterCallback = (qb: FilterBuilder) => void\n\n/**\n * The where-clause surface of the query builder, factored out so a grouping callback can be handed\n * a builder that only exposes filter methods (not `near*`/`select`/`limit` or the terminals).\n *\n * Chained `.where()` ANDs; the first `.orWhere()` snapshots the accumulated AND-list into the first\n * branch of an OR (knex semantics). Any of the where-methods also accepts a {@link FilterCallback}\n * to open a nested group, letting AND and OR mix to any depth.\n */\nclass FilterBuilder {\n  protected andConditions: VectorFilter[] = []\n  protected orBranches: VectorFilter[][] = []\n\n  /** Build a nested group by running `cb` against a fresh {@link FilterBuilder}. */\n  protected runGroup(cb: FilterCallback): VectorFilter | undefined {\n    const fb = new FilterBuilder()\n    cb(fb)\n    return fb.buildFilter()\n  }\n\n  where(cb: FilterCallback): this\n  where(a: string, b?: unknown, c?: unknown): this\n  where(obj: Record<string, unknown>): this\n  where(a: string | Record<string, unknown> | FilterCallback, b?: unknown, c?: unknown): this {\n    if (typeof a === 'function') {\n      const group = this.runGroup(a)\n      if (group !== undefined) {\n        this.andConditions.push(group)\n      }\n      return this\n    }\n    if (typeof a === 'object' && !Array.isArray(a)) {\n      for (const key of Object.keys(a)) {\n        this.andConditions.push({\n          field: key,\n          op: 'eq',\n          value: a[key] as FilterCondition['value'],\n        })\n      }\n      return this\n    }\n    const field = a as string\n    const value = b !== undefined ? (c !== undefined ? c : b) : b\n    const op = c !== undefined ? normalizeOp(b as string) : 'eq'\n    this.andConditions.push({ field, op, value: value as FilterCondition['value'] })\n    return this\n  }\n\n  andWhere(cb: FilterCallback): this\n  andWhere(a: string, b?: unknown, c?: unknown): this\n  andWhere(obj: Record<string, unknown>): this\n  andWhere(a: string | Record<string, unknown> | FilterCallback, b?: unknown, c?: unknown): this {\n    return this.where(a as any, b, c)\n  }\n\n  /**\n   * Open a new OR branch holding a single filter. The accumulated AND-list is contributed as the\n   * first OR-group by {@link buildFilter}, so each branch carries only its own condition(s) — that\n   * is what makes `where(A).where(B).orWhere(C)` resolve to `(A AND B) OR C`.\n   */\n  #pushOrBranch(filter: VectorFilter): void {\n    this.orBranches.push([filter])\n  }\n\n  orWhere(cb: FilterCallback): this\n  orWhere(field: string, value: unknown): this\n  orWhere(field: string, op: FilterOperator, value: unknown): this\n  orWhere(field: string | FilterCallback, b?: unknown, c?: unknown): this {\n    if (typeof field === 'function') {\n      const group = this.runGroup(field)\n      if (group !== undefined) {\n        this.#pushOrBranch(group)\n      }\n      return this\n    }\n    const value = c !== undefined ? c : b\n    const op = c !== undefined ? normalizeOp(b as string) : 'eq'\n    this.#pushOrBranch({ field, op, value: value as FilterCondition['value'] })\n    return this\n  }\n\n  whereNot(cb: FilterCallback): this\n  whereNot(field: string, value: unknown): this\n  whereNot(field: string | FilterCallback, value?: unknown): this {\n    if (typeof field === 'function') {\n      const group = this.runGroup(field)\n      if (group !== undefined) {\n        this.andConditions.push({ not: group })\n      }\n      return this\n    }\n    return this.where(field, 'ne', value as FilterCondition['value'])\n  }\n\n  orWhereNot(cb: FilterCallback): this\n  orWhereNot(field: string, value: unknown): this\n  orWhereNot(field: string | FilterCallback, value?: unknown): this {\n    if (typeof field === 'function') {\n      const group = this.runGroup(field)\n      if (group !== undefined) {\n        this.#pushOrBranch({ not: group })\n      }\n      return this\n    }\n    return this.orWhere(field, 'ne', value)\n  }\n\n  whereIn(field: string, values: unknown[]): this {\n    return this.where(field, 'in', values as FilterCondition['value'])\n  }\n\n  whereNotIn(field: string, values: unknown[]): this {\n    return this.where(field, 'nin', values as FilterCondition['value'])\n  }\n\n  whereNull(field: string): this {\n    return this.where(field, 'exists', false as FilterCondition['value'])\n  }\n\n  whereExists(field: string): this {\n    return this.where(field, 'exists', true as FilterCondition['value'])\n  }\n\n  whereRaw(sql: string, bindings?: unknown[]): this\n  whereRaw(rawObj: { $dialect: string; $raw: unknown; $bindings?: unknown[] }): this\n  whereRaw(\n    sqlOrObj: string | { $dialect: string; $raw: unknown; $bindings?: unknown[] },\n    bindings?: unknown[]\n  ): this {\n    if (typeof sqlOrObj === 'object') {\n      this.andConditions.push({\n        $dialect: sqlOrObj.$dialect,\n        $raw: sqlOrObj.$raw,\n        $bindings: sqlOrObj.$bindings ?? [],\n      })\n    } else {\n      this.andConditions.push({ $dialect: 'sql', $raw: sqlOrObj, $bindings: bindings ?? [] })\n    }\n    return this\n  }\n\n  protected buildFilter(): VectorFilter | undefined {\n    if (this.andConditions.length === 0 && this.orBranches.length === 0) {\n      return undefined\n    }\n\n    if (this.orBranches.length > 0) {\n      const orGroups: VectorFilter[][] = []\n      if (this.andConditions.length > 0) {\n        orGroups.push(this.andConditions)\n      }\n      for (const branch of this.orBranches) {\n        if (branch.length > 0) {\n          orGroups.push(branch)\n        }\n      }\n      if (orGroups.length === 1) {\n        return { and: orGroups[0] }\n      }\n      return { or: orGroups.map((conds) => ({ and: conds })) }\n    }\n\n    return { and: this.andConditions }\n  }\n\n  protected extractIdsFromFilter(): string[] {\n    const ids: string[] = []\n    const only = this.andConditions.length === 1 ? this.andConditions[0] : undefined\n    if (\n      only &&\n      isFilterCondition(only) &&\n      only.field === 'id' &&\n      only.op === 'in' &&\n      Array.isArray(only.value)\n    ) {\n      ids.push(...(only.value as string[]))\n    }\n    return ids\n  }\n}\n\nclass VectorQueryBuilder extends FilterBuilder implements PromiseLike<VectorMatch[]> {\n  #sink: PlanSink\n  #collection: string\n  #near: { vector: number[] } | { serverText: string } | { id: string } | undefined\n  #projection: Projection = { id: false, vector: false, document: false, metadata: false }\n  #topK: number\n  #offset: number = 0\n  #selectCalled: boolean = false\n  #consistency: VectorConsistency | undefined\n\n  constructor(sink: PlanSink, collection: string, defaultTopK: number) {\n    super()\n    this.#sink = sink\n    this.#collection = collection\n    this.#topK = defaultTopK\n  }\n\n  nearVector(vector: number[]): this {\n    if (this.#near !== undefined) {\n      throw new E_VECTOR_STORE_QUERY_CONFLICT(['a near* clause was already set'])\n    }\n    this.#near = { vector }\n    return this\n  }\n\n  nearText(text: string): this {\n    if (this.#near !== undefined) {\n      throw new E_VECTOR_STORE_QUERY_CONFLICT(['a near* clause was already set'])\n    }\n    this.#near = { serverText: text }\n    return this\n  }\n\n  nearId(id: string): this {\n    if (this.#near !== undefined) {\n      throw new E_VECTOR_STORE_QUERY_CONFLICT(['a near* clause was already set'])\n    }\n    this.#near = { id }\n    return this\n  }\n\n  select(...args: SelectArg[]): this {\n    this.#selectCalled = true\n    for (const arg of args) {\n      if (typeof arg === 'string') {\n        if (arg === '*') {\n          this.#projection = { id: true, vector: {}, document: {}, metadata: {} }\n        } else {\n          if (arg === 'id') {\n            this.#projection.id = true\n          } else if (arg === 'vector') {\n            this.#projection.vector = {}\n          } else if (arg === 'document') {\n            this.#projection.document = {}\n          } else if (arg === 'metadata') {\n            this.#projection.metadata = {}\n          }\n        }\n      } else if (Array.isArray(arg)) {\n        const [field, config] = arg\n        if (field === 'vector') {\n          this.#projection.vector = config as { name?: string }\n        } else if (field === 'document') {\n          this.#projection.document = config as { field?: string }\n        } else if (field === 'metadata') {\n          this.#projection.metadata = config as { fields?: string[] }\n        } else if (field === 'id') {\n          this.#projection.id = true\n        }\n      } else if (typeof arg === 'object') {\n        for (const key of Object.keys(arg)) {\n          if (key === 'vector') {\n            this.#projection.vector = arg[key] as { name?: string }\n          } else if (key === 'document') {\n            this.#projection.document = arg[key] as { field?: string }\n          } else if (key === 'metadata') {\n            this.#projection.metadata = arg[key] as { fields?: string[] }\n          } else if (key === 'id') {\n            this.#projection.id = true\n          }\n        }\n      }\n    }\n    return this\n  }\n\n  limit(n: number): this {\n    this.#topK = n\n    return this\n  }\n\n  offset(n: number): this {\n    this.#offset = n\n    return this\n  }\n\n  /**\n   * Per-operation read-after-write override for the terminal `.upsert()` / `.delete()`.\n   * Universal across adapters: strongly-consistent backends ignore it (no-op), so a chain\n   * written for an eventually-consistent backend keeps working verbatim when the adapter is\n   * swapped. Precedence: this > the store's `consistency` option > the adapter's declared\n   * `capabilities.consistency.default`. See {@link VectorConsistency}.\n   */\n  consistency(mode: VectorConsistency): this {\n    this.#consistency = mode\n    return this\n  }\n\n  then<TR1 = VectorMatch[], TR2 = never>(\n    onfulfilled?: ((value: VectorMatch[]) => TR1 | PromiseLike<TR1>) | null,\n    onrejected?: ((reason: unknown) => TR2 | PromiseLike<TR2>) | null\n  ): PromiseLike<TR1 | TR2> {\n    return this.#run().then(onfulfilled as any, onrejected as any)\n  }\n\n  async #run(): Promise<VectorMatch[]> {\n    if (!this.#selectCalled) {\n      throw new E_VECTOR_STORE_PROJECTION_REQUIRED()\n    }\n\n    const filter = this.buildFilter()\n\n    const plan: SearchPlan = {\n      collection: this.#collection,\n      near: this.#near,\n      filter,\n      topK: this.#topK,\n      offset: this.#offset,\n      projection: this.#projection,\n    }\n\n    this.#validateRawFilters(plan.filter)\n\n    return await this.#sink.executeSearch(plan)\n  }\n\n  async upsert(records: VectorRecord[]): Promise<void> {\n    const plan: UpsertPlan = {\n      collection: this.#collection,\n      records,\n      consistency: this.#consistency,\n    }\n    await this.#sink.executeUpsert(plan)\n  }\n\n  async delete(): Promise<void> {\n    const ids = this.extractIdsFromFilter()\n    const filter = this.buildFilter()\n\n    const plan: DeletePlan = {\n      collection: this.#collection,\n      ids: ids.length > 0 ? ids : undefined,\n      filter: filter && Object.keys(filter).length > 0 ? filter : undefined,\n      consistency: this.#consistency,\n    }\n\n    await this.#sink.executeDelete(plan)\n  }\n\n  #validateRawFilters(filter: VectorFilter | undefined): void {\n    if (!filter) {\n      return\n    }\n\n    if (isRawFilter(filter)) {\n      const raw = filter.$raw as string\n      const placeholders = (raw.match(/\\?/g) || []).length\n      if (placeholders !== filter.$bindings?.length) {\n        throw new E_VECTOR_STORE_RAW_BINDING_MISMATCH([placeholders, filter.$bindings?.length ?? 0])\n      }\n      return\n    }\n\n    if ('and' in filter && filter.and) {\n      for (const f of filter.and) {\n        this.#validateRawFilters(f)\n      }\n    }\n\n    if ('or' in filter && filter.or) {\n      for (const f of filter.or) {\n        this.#validateRawFilters(f)\n      }\n    }\n\n    if ('not' in filter && filter.not) {\n      this.#validateRawFilters(filter.not)\n    }\n  }\n}\n\nexport { VectorQueryBuilder, FilterBuilder }\n"],"mappings":"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"}
+{"version":3,"file":"builder.mjs","names":["#pushOrBranch","#sink","#collection","#topK","#near","#selectCalled","#projection","#offset","#consistency","#run","#validateRawFilters"],"sources":["../../../src/batteries/vector/builder.ts"],"sourcesContent":["/**\n * Knex-style chainable query builder for the vector storage battery.\n *\n * @module @nhtio/adk/batteries/vector/builder\n */\n\nimport { isRawFilter, isFilterCondition } from './filters'\nimport {\n  E_VECTOR_STORE_QUERY_CONFLICT,\n  E_VECTOR_STORE_PROJECTION_REQUIRED,\n  E_VECTOR_STORE_RAW_BINDING_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR,\n} from './exceptions'\nimport type { VectorRecord, VectorMatch, VectorConsistency } from './types'\nimport type { SearchPlan, UpsertPlan, DeletePlan, Projection } from './plan'\nimport type { VectorFilter, FilterCondition, FilterOperator } from './filters'\n\nconst OP_ALIASES: Record<string, FilterOperator> = {\n  '=': 'eq',\n  '==': 'eq',\n  '===': 'eq',\n  '!=': 'ne',\n  '<>': 'ne',\n  '!==': 'ne',\n  '>': 'gt',\n  '>=': 'gte',\n  '<': 'lt',\n  '<=': 'lte',\n  'eq': 'eq',\n  'ne': 'ne',\n  'gt': 'gt',\n  'gte': 'gte',\n  'lt': 'lt',\n  'lte': 'lte',\n  'in': 'in',\n  'nin': 'nin',\n  'exists': 'exists',\n  'contains': 'contains',\n}\nconst normalizeOp = (op: string): FilterOperator => {\n  const norm = OP_ALIASES[op]\n  if (!norm) throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['builder', op])\n  return norm\n}\n\n/**\n * The execution backend a {@link VectorQueryBuilder} drains its assembled plans into. Implemented\n * by the vector store; the builder produces {@link SearchPlan}/{@link UpsertPlan}/{@link DeletePlan}\n * objects and hands them here rather than touching the adapter directly.\n */\nexport interface PlanSink {\n  /** Executes an assembled search plan and resolves the matching records. */\n  executeSearch(plan: SearchPlan): Promise<VectorMatch[]>\n  /** Executes an assembled upsert plan. */\n  executeUpsert(plan: UpsertPlan): Promise<void>\n  /** Executes an assembled delete plan. */\n  executeDelete(plan: DeletePlan): Promise<void>\n}\n\n/**\n * An argument accepted by {@link VectorQueryBuilder.select} — a field name (or `'*'`), a\n * `[field, config]` tuple, or a `{ field: config }` map selecting and configuring projected fields.\n */\nexport type SelectArg =\n  | string\n  | [string, Record<string, unknown>]\n  | Record<string, Record<string, unknown> | true>\n\n/**\n * A callback that receives a fresh filter-only builder, used to express a parenthesized group of\n * conditions — `A AND (B OR C)`, `NOT (…)`, and arbitrary nesting. The callback mutates the builder\n * in place (knex-style); its accumulated conditions become a single nested `VectorFilter`.\n *\n * @see {@link FilterBuilder.where}\n */\nexport type FilterCallback = (qb: FilterBuilder) => void\n\n/**\n * The where-clause surface of the query builder, factored out so a grouping callback can be handed\n * a builder that only exposes filter methods (not `near*`/`select`/`limit` or the terminals).\n *\n * Chained `.where()` ANDs; the first `.orWhere()` snapshots the accumulated AND-list into the first\n * branch of an OR (knex semantics). Any of the where-methods also accepts a {@link FilterCallback}\n * to open a nested group, letting AND and OR mix to any depth.\n */\nclass FilterBuilder {\n  protected andConditions: VectorFilter[] = []\n  protected orBranches: VectorFilter[][] = []\n\n  /** Build a nested group by running `cb` against a fresh {@link FilterBuilder}. */\n  protected runGroup(cb: FilterCallback): VectorFilter | undefined {\n    const fb = new FilterBuilder()\n    cb(fb)\n    return fb.buildFilter()\n  }\n\n  /** Add a parenthesized condition group via a {@link FilterCallback}; ANDed with prior conditions. */\n  where(cb: FilterCallback): this\n  /** Add a condition `field op value` (or `field = value` when `c` is omitted); ANDed with prior conditions. */\n  where(a: string, b?: unknown, c?: unknown): this\n  /** Add equality conditions for each key of `obj`; ANDed with prior conditions. */\n  where(obj: Record<string, unknown>): this\n  where(a: string | Record<string, unknown> | FilterCallback, b?: unknown, c?: unknown): this {\n    if (typeof a === 'function') {\n      const group = this.runGroup(a)\n      if (group !== undefined) {\n        this.andConditions.push(group)\n      }\n      return this\n    }\n    if (typeof a === 'object' && !Array.isArray(a)) {\n      for (const key of Object.keys(a)) {\n        this.andConditions.push({\n          field: key,\n          op: 'eq',\n          value: a[key] as FilterCondition['value'],\n        })\n      }\n      return this\n    }\n    const field = a as string\n    const value = b !== undefined ? (c !== undefined ? c : b) : b\n    const op = c !== undefined ? normalizeOp(b as string) : 'eq'\n    this.andConditions.push({ field, op, value: value as FilterCondition['value'] })\n    return this\n  }\n\n  /** Alias of {@link FilterBuilder.where} (callback group form) for readability in a chain. */\n  andWhere(cb: FilterCallback): this\n  /** Alias of {@link FilterBuilder.where} (`field op value` form) for readability in a chain. */\n  andWhere(a: string, b?: unknown, c?: unknown): this\n  /** Alias of {@link FilterBuilder.where} (object form) for readability in a chain. */\n  andWhere(obj: Record<string, unknown>): this\n  andWhere(a: string | Record<string, unknown> | FilterCallback, b?: unknown, c?: unknown): this {\n    return this.where(a as any, b, c)\n  }\n\n  /**\n   * Open a new OR branch holding a single filter. The accumulated AND-list is contributed as the\n   * first OR-group by {@link buildFilter}, so each branch carries only its own condition(s) — that\n   * is what makes `where(A).where(B).orWhere(C)` resolve to `(A AND B) OR C`.\n   */\n  #pushOrBranch(filter: VectorFilter): void {\n    this.orBranches.push([filter])\n  }\n\n  /** Open a new OR branch holding a parenthesized condition group via a {@link FilterCallback}. */\n  orWhere(cb: FilterCallback): this\n  /** Open a new OR branch holding the equality condition `field = value`. */\n  orWhere(field: string, value: unknown): this\n  /** Open a new OR branch holding the condition `field op value`. */\n  orWhere(field: string, op: FilterOperator, value: unknown): this\n  orWhere(field: string | FilterCallback, b?: unknown, c?: unknown): this {\n    if (typeof field === 'function') {\n      const group = this.runGroup(field)\n      if (group !== undefined) {\n        this.#pushOrBranch(group)\n      }\n      return this\n    }\n    const value = c !== undefined ? c : b\n    const op = c !== undefined ? normalizeOp(b as string) : 'eq'\n    this.#pushOrBranch({ field, op, value: value as FilterCondition['value'] })\n    return this\n  }\n\n  /** AND a negated parenthesized condition group via a {@link FilterCallback}. */\n  whereNot(cb: FilterCallback): this\n  /** AND the negated equality condition `field != value`. */\n  whereNot(field: string, value: unknown): this\n  whereNot(field: string | FilterCallback, value?: unknown): this {\n    if (typeof field === 'function') {\n      const group = this.runGroup(field)\n      if (group !== undefined) {\n        this.andConditions.push({ not: group })\n      }\n      return this\n    }\n    return this.where(field, 'ne', value as FilterCondition['value'])\n  }\n\n  /** Open a new OR branch holding a negated parenthesized condition group via a {@link FilterCallback}. */\n  orWhereNot(cb: FilterCallback): this\n  /** Open a new OR branch holding the negated equality condition `field != value`. */\n  orWhereNot(field: string, value: unknown): this\n  orWhereNot(field: string | FilterCallback, value?: unknown): this {\n    if (typeof field === 'function') {\n      const group = this.runGroup(field)\n      if (group !== undefined) {\n        this.#pushOrBranch({ not: group })\n      }\n      return this\n    }\n    return this.orWhere(field, 'ne', value)\n  }\n\n  /** AND the condition that `field`'s value is one of `values`. */\n  whereIn(field: string, values: unknown[]): this {\n    return this.where(field, 'in', values as FilterCondition['value'])\n  }\n\n  /** AND the condition that `field`'s value is none of `values`. */\n  whereNotIn(field: string, values: unknown[]): this {\n    return this.where(field, 'nin', values as FilterCondition['value'])\n  }\n\n  /** AND the condition that `field` is absent (does not exist). */\n  whereNull(field: string): this {\n    return this.where(field, 'exists', false as FilterCondition['value'])\n  }\n\n  /** AND the condition that `field` is present (exists). */\n  whereExists(field: string): this {\n    return this.where(field, 'exists', true as FilterCondition['value'])\n  }\n\n  /** AND a raw, adapter-dialect filter expressed as SQL text plus positional `bindings`. */\n  whereRaw(sql: string, bindings?: unknown[]): this\n  /** AND a raw, adapter-dialect filter expressed as a `{ $dialect, $raw, $bindings }` object. */\n  whereRaw(rawObj: { $dialect: string; $raw: unknown; $bindings?: unknown[] }): this\n  whereRaw(\n    sqlOrObj: string | { $dialect: string; $raw: unknown; $bindings?: unknown[] },\n    bindings?: unknown[]\n  ): this {\n    if (typeof sqlOrObj === 'object') {\n      this.andConditions.push({\n        $dialect: sqlOrObj.$dialect,\n        $raw: sqlOrObj.$raw,\n        $bindings: sqlOrObj.$bindings ?? [],\n      })\n    } else {\n      this.andConditions.push({ $dialect: 'sql', $raw: sqlOrObj, $bindings: bindings ?? [] })\n    }\n    return this\n  }\n\n  protected buildFilter(): VectorFilter | undefined {\n    if (this.andConditions.length === 0 && this.orBranches.length === 0) {\n      return undefined\n    }\n\n    if (this.orBranches.length > 0) {\n      const orGroups: VectorFilter[][] = []\n      if (this.andConditions.length > 0) {\n        orGroups.push(this.andConditions)\n      }\n      for (const branch of this.orBranches) {\n        if (branch.length > 0) {\n          orGroups.push(branch)\n        }\n      }\n      if (orGroups.length === 1) {\n        return { and: orGroups[0] }\n      }\n      return { or: orGroups.map((conds) => ({ and: conds })) }\n    }\n\n    return { and: this.andConditions }\n  }\n\n  protected extractIdsFromFilter(): string[] {\n    const ids: string[] = []\n    const only = this.andConditions.length === 1 ? this.andConditions[0] : undefined\n    if (\n      only &&\n      isFilterCondition(only) &&\n      only.field === 'id' &&\n      only.op === 'in' &&\n      Array.isArray(only.value)\n    ) {\n      ids.push(...(only.value as string[]))\n    }\n    return ids\n  }\n}\n\nclass VectorQueryBuilder extends FilterBuilder implements PromiseLike<VectorMatch[]> {\n  #sink: PlanSink\n  #collection: string\n  #near: { vector: number[] } | { serverText: string } | { id: string } | undefined\n  #projection: Projection = { id: false, vector: false, document: false, metadata: false }\n  #topK: number\n  #offset: number = 0\n  #selectCalled: boolean = false\n  #consistency: VectorConsistency | undefined\n\n  constructor(sink: PlanSink, collection: string, defaultTopK: number) {\n    super()\n    this.#sink = sink\n    this.#collection = collection\n    this.#topK = defaultTopK\n  }\n\n  /**\n   * Search by nearest neighbours to a client-supplied query `vector`. Mutually exclusive with the\n   * other `near*` clauses.\n   *\n   * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_QUERY_CONFLICT} when a `near*` clause is already set.\n   */\n  nearVector(vector: number[]): this {\n    if (this.#near !== undefined) {\n      throw new E_VECTOR_STORE_QUERY_CONFLICT(['a near* clause was already set'])\n    }\n    this.#near = { vector }\n    return this\n  }\n\n  /**\n   * Search by nearest neighbours to `text`, embedded server-side by the backend. Mutually exclusive\n   * with the other `near*` clauses.\n   *\n   * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_QUERY_CONFLICT} when a `near*` clause is already set.\n   */\n  nearText(text: string): this {\n    if (this.#near !== undefined) {\n      throw new E_VECTOR_STORE_QUERY_CONFLICT(['a near* clause was already set'])\n    }\n    this.#near = { serverText: text }\n    return this\n  }\n\n  /**\n   * Search by nearest neighbours to the stored vector of the record with the given `id`. Mutually\n   * exclusive with the other `near*` clauses.\n   *\n   * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_QUERY_CONFLICT} when a `near*` clause is already set.\n   */\n  nearId(id: string): this {\n    if (this.#near !== undefined) {\n      throw new E_VECTOR_STORE_QUERY_CONFLICT(['a near* clause was already set'])\n    }\n    this.#near = { id }\n    return this\n  }\n\n  /**\n   * Declare which fields each match projects (id / vector / document / metadata). Required before a\n   * search terminal runs. Accepts {@link SelectArg}s: `'*'`, field names, `[field, config]` tuples,\n   * or `{ field: config }` maps.\n   */\n  select(...args: SelectArg[]): this {\n    this.#selectCalled = true\n    for (const arg of args) {\n      if (typeof arg === 'string') {\n        if (arg === '*') {\n          this.#projection = { id: true, vector: {}, document: {}, metadata: {} }\n        } else {\n          if (arg === 'id') {\n            this.#projection.id = true\n          } else if (arg === 'vector') {\n            this.#projection.vector = {}\n          } else if (arg === 'document') {\n            this.#projection.document = {}\n          } else if (arg === 'metadata') {\n            this.#projection.metadata = {}\n          }\n        }\n      } else if (Array.isArray(arg)) {\n        const [field, config] = arg\n        if (field === 'vector') {\n          this.#projection.vector = config as { name?: string }\n        } else if (field === 'document') {\n          this.#projection.document = config as { field?: string }\n        } else if (field === 'metadata') {\n          this.#projection.metadata = config as { fields?: string[] }\n        } else if (field === 'id') {\n          this.#projection.id = true\n        }\n      } else if (typeof arg === 'object') {\n        for (const key of Object.keys(arg)) {\n          if (key === 'vector') {\n            this.#projection.vector = arg[key] as { name?: string }\n          } else if (key === 'document') {\n            this.#projection.document = arg[key] as { field?: string }\n          } else if (key === 'metadata') {\n            this.#projection.metadata = arg[key] as { fields?: string[] }\n          } else if (key === 'id') {\n            this.#projection.id = true\n          }\n        }\n      }\n    }\n    return this\n  }\n\n  /** Cap the number of matches returned (the search `topK`). */\n  limit(n: number): this {\n    this.#topK = n\n    return this\n  }\n\n  /** Skip the first `n` matches before returning results. */\n  offset(n: number): this {\n    this.#offset = n\n    return this\n  }\n\n  /**\n   * Per-operation read-after-write override for the terminal `.upsert()` / `.delete()`.\n   * Universal across adapters: strongly-consistent backends ignore it (no-op), so a chain\n   * written for an eventually-consistent backend keeps working verbatim when the adapter is\n   * swapped. Precedence: this > the store's `consistency` option > the adapter's declared\n   * `capabilities.consistency.default`. See {@link VectorConsistency}.\n   */\n  consistency(mode: VectorConsistency): this {\n    this.#consistency = mode\n    return this\n  }\n\n  then<TR1 = VectorMatch[], TR2 = never>(\n    onfulfilled?: ((value: VectorMatch[]) => TR1 | PromiseLike<TR1>) | null,\n    onrejected?: ((reason: unknown) => TR2 | PromiseLike<TR2>) | null\n  ): PromiseLike<TR1 | TR2> {\n    return this.#run().then(onfulfilled as any, onrejected as any)\n  }\n\n  async #run(): Promise<VectorMatch[]> {\n    if (!this.#selectCalled) {\n      throw new E_VECTOR_STORE_PROJECTION_REQUIRED()\n    }\n\n    const filter = this.buildFilter()\n\n    const plan: SearchPlan = {\n      collection: this.#collection,\n      near: this.#near,\n      filter,\n      topK: this.#topK,\n      offset: this.#offset,\n      projection: this.#projection,\n    }\n\n    this.#validateRawFilters(plan.filter)\n\n    return await this.#sink.executeSearch(plan)\n  }\n\n  /** Terminal: insert or replace `records` in the collection. */\n  async upsert(records: VectorRecord[]): Promise<void> {\n    const plan: UpsertPlan = {\n      collection: this.#collection,\n      records,\n      consistency: this.#consistency,\n    }\n    await this.#sink.executeUpsert(plan)\n  }\n\n  /** Terminal: delete records matching the accumulated filter (or the `id IN [...]` fast path). */\n  async delete(): Promise<void> {\n    const ids = this.extractIdsFromFilter()\n    const filter = this.buildFilter()\n\n    const plan: DeletePlan = {\n      collection: this.#collection,\n      ids: ids.length > 0 ? ids : undefined,\n      filter: filter && Object.keys(filter).length > 0 ? filter : undefined,\n      consistency: this.#consistency,\n    }\n\n    await this.#sink.executeDelete(plan)\n  }\n\n  #validateRawFilters(filter: VectorFilter | undefined): void {\n    if (!filter) {\n      return\n    }\n\n    if (isRawFilter(filter)) {\n      const raw = filter.$raw as string\n      const placeholders = (raw.match(/\\?/g) || []).length\n      if (placeholders !== filter.$bindings?.length) {\n        throw new E_VECTOR_STORE_RAW_BINDING_MISMATCH([placeholders, filter.$bindings?.length ?? 0])\n      }\n      return\n    }\n\n    if ('and' in filter && filter.and) {\n      for (const f of filter.and) {\n        this.#validateRawFilters(f)\n      }\n    }\n\n    if ('or' in filter && filter.or) {\n      for (const f of filter.or) {\n        this.#validateRawFilters(f)\n      }\n    }\n\n    if ('not' in filter && filter.not) {\n      this.#validateRawFilters(filter.not)\n    }\n  }\n}\n\nexport { VectorQueryBuilder, FilterBuilder }\n"],"mappings":";;;;;;;;AAiBA,IAAM,aAA6C;CACjD,KAAK;CACL,MAAM;CACN,OAAO;CACP,MAAM;CACN,MAAM;CACN,OAAO;CACP,KAAK;CACL,MAAM;CACN,KAAK;CACL,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,OAAO;CACP,MAAM;CACN,OAAO;CACP,MAAM;CACN,OAAO;CACP,UAAU;CACV,YAAY;AACd;AACA,IAAM,eAAe,OAA+B;CAClD,MAAM,OAAO,WAAW;CACxB,IAAI,CAAC,MAAM,MAAM,IAAI,2CAA2C,CAAC,WAAW,EAAE,CAAC;CAC/E,OAAO;AACT;;;;;;;;;AA0CA,IAAM,gBAAN,MAAM,cAAc;CAClB,gBAA0C,CAAC;CAC3C,aAAyC,CAAC;;CAG1C,SAAmB,IAA8C;EAC/D,MAAM,KAAK,IAAI,cAAc;EAC7B,GAAG,EAAE;EACL,OAAO,GAAG,YAAY;CACxB;CAQA,MAAM,GAAsD,GAAa,GAAmB;EAC1F,IAAI,OAAO,MAAM,YAAY;GAC3B,MAAM,QAAQ,KAAK,SAAS,CAAC;GAC7B,IAAI,UAAU,KAAA,GACZ,KAAK,cAAc,KAAK,KAAK;GAE/B,OAAO;EACT;EACA,IAAI,OAAO,MAAM,YAAY,CAAC,MAAM,QAAQ,CAAC,GAAG;GAC9C,KAAK,MAAM,OAAO,OAAO,KAAK,CAAC,GAC7B,KAAK,cAAc,KAAK;IACtB,OAAO;IACP,IAAI;IACJ,OAAO,EAAE;GACX,CAAC;GAEH,OAAO;EACT;EACA,MAAM,QAAQ;EACd,MAAM,QAAQ,MAAM,KAAA,IAAa,MAAM,KAAA,IAAY,IAAI,IAAK;EAC5D,MAAM,KAAK,MAAM,KAAA,IAAY,YAAY,CAAW,IAAI;EACxD,KAAK,cAAc,KAAK;GAAE;GAAO;GAAW;EAAkC,CAAC;EAC/E,OAAO;CACT;CAQA,SAAS,GAAsD,GAAa,GAAmB;EAC7F,OAAO,KAAK,MAAM,GAAU,GAAG,CAAC;CAClC;;;;;;CAOA,cAAc,QAA4B;EACxC,KAAK,WAAW,KAAK,CAAC,MAAM,CAAC;CAC/B;CAQA,QAAQ,OAAgC,GAAa,GAAmB;EACtE,IAAI,OAAO,UAAU,YAAY;GAC/B,MAAM,QAAQ,KAAK,SAAS,KAAK;GACjC,IAAI,UAAU,KAAA,GACZ,KAAKA,cAAc,KAAK;GAE1B,OAAO;EACT;EACA,MAAM,QAAQ,MAAM,KAAA,IAAY,IAAI;EACpC,MAAM,KAAK,MAAM,KAAA,IAAY,YAAY,CAAW,IAAI;EACxD,KAAKA,cAAc;GAAE;GAAO;GAAW;EAAkC,CAAC;EAC1E,OAAO;CACT;CAMA,SAAS,OAAgC,OAAuB;EAC9D,IAAI,OAAO,UAAU,YAAY;GAC/B,MAAM,QAAQ,KAAK,SAAS,KAAK;GACjC,IAAI,UAAU,KAAA,GACZ,KAAK,cAAc,KAAK,EAAE,KAAK,MAAM,CAAC;GAExC,OAAO;EACT;EACA,OAAO,KAAK,MAAM,OAAO,MAAM,KAAiC;CAClE;CAMA,WAAW,OAAgC,OAAuB;EAChE,IAAI,OAAO,UAAU,YAAY;GAC/B,MAAM,QAAQ,KAAK,SAAS,KAAK;GACjC,IAAI,UAAU,KAAA,GACZ,KAAKA,cAAc,EAAE,KAAK,MAAM,CAAC;GAEnC,OAAO;EACT;EACA,OAAO,KAAK,QAAQ,OAAO,MAAM,KAAK;CACxC;;CAGA,QAAQ,OAAe,QAAyB;EAC9C,OAAO,KAAK,MAAM,OAAO,MAAM,MAAkC;CACnE;;CAGA,WAAW,OAAe,QAAyB;EACjD,OAAO,KAAK,MAAM,OAAO,OAAO,MAAkC;CACpE;;CAGA,UAAU,OAAqB;EAC7B,OAAO,KAAK,MAAM,OAAO,UAAU,KAAiC;CACtE;;CAGA,YAAY,OAAqB;EAC/B,OAAO,KAAK,MAAM,OAAO,UAAU,IAAgC;CACrE;CAMA,SACE,UACA,UACM;EACN,IAAI,OAAO,aAAa,UACtB,KAAK,cAAc,KAAK;GACtB,UAAU,SAAS;GACnB,MAAM,SAAS;GACf,WAAW,SAAS,aAAa,CAAC;EACpC,CAAC;OAED,KAAK,cAAc,KAAK;GAAE,UAAU;GAAO,MAAM;GAAU,WAAW,YAAY,CAAC;EAAE,CAAC;EAExF,OAAO;CACT;CAEA,cAAkD;EAChD,IAAI,KAAK,cAAc,WAAW,KAAK,KAAK,WAAW,WAAW,GAChE;EAGF,IAAI,KAAK,WAAW,SAAS,GAAG;GAC9B,MAAM,WAA6B,CAAC;GACpC,IAAI,KAAK,cAAc,SAAS,GAC9B,SAAS,KAAK,KAAK,aAAa;GAElC,KAAK,MAAM,UAAU,KAAK,YACxB,IAAI,OAAO,SAAS,GAClB,SAAS,KAAK,MAAM;GAGxB,IAAI,SAAS,WAAW,GACtB,OAAO,EAAE,KAAK,SAAS,GAAG;GAE5B,OAAO,EAAE,IAAI,SAAS,KAAK,WAAW,EAAE,KAAK,MAAM,EAAE,EAAE;EACzD;EAEA,OAAO,EAAE,KAAK,KAAK,cAAc;CACnC;CAEA,uBAA2C;EACzC,MAAM,MAAgB,CAAC;EACvB,MAAM,OAAO,KAAK,cAAc,WAAW,IAAI,KAAK,cAAc,KAAK,KAAA;EACvE,IACE,QACA,kBAAkB,IAAI,KACtB,KAAK,UAAU,QACf,KAAK,OAAO,QACZ,MAAM,QAAQ,KAAK,KAAK,GAExB,IAAI,KAAK,GAAI,KAAK,KAAkB;EAEtC,OAAO;CACT;AACF;AAEA,IAAM,qBAAN,cAAiC,cAAoD;CACnF;CACA;CACA;CACA,cAA0B;EAAE,IAAI;EAAO,QAAQ;EAAO,UAAU;EAAO,UAAU;CAAM;CACvF;CACA,UAAkB;CAClB,gBAAyB;CACzB;CAEA,YAAY,MAAgB,YAAoB,aAAqB;EACnE,MAAM;EACN,KAAKC,QAAQ;EACb,KAAKC,cAAc;EACnB,KAAKC,QAAQ;CACf;;;;;;;CAQA,WAAW,QAAwB;EACjC,IAAI,KAAKC,UAAU,KAAA,GACjB,MAAM,IAAI,8BAA8B,CAAC,gCAAgC,CAAC;EAE5E,KAAKA,QAAQ,EAAE,OAAO;EACtB,OAAO;CACT;;;;;;;CAQA,SAAS,MAAoB;EAC3B,IAAI,KAAKA,UAAU,KAAA,GACjB,MAAM,IAAI,8BAA8B,CAAC,gCAAgC,CAAC;EAE5E,KAAKA,QAAQ,EAAE,YAAY,KAAK;EAChC,OAAO;CACT;;;;;;;CAQA,OAAO,IAAkB;EACvB,IAAI,KAAKA,UAAU,KAAA,GACjB,MAAM,IAAI,8BAA8B,CAAC,gCAAgC,CAAC;EAE5E,KAAKA,QAAQ,EAAE,GAAG;EAClB,OAAO;CACT;;;;;;CAOA,OAAO,GAAG,MAAyB;EACjC,KAAKC,gBAAgB;EACrB,KAAK,MAAM,OAAO,MAChB,IAAI,OAAO,QAAQ;OACb,QAAQ,KACV,KAAKC,cAAc;IAAE,IAAI;IAAM,QAAQ,CAAC;IAAG,UAAU,CAAC;IAAG,UAAU,CAAC;GAAE;QAEtE,IAAI,QAAQ,MACV,KAAKA,YAAY,KAAK;QACjB,IAAI,QAAQ,UACjB,KAAKA,YAAY,SAAS,CAAC;QACtB,IAAI,QAAQ,YACjB,KAAKA,YAAY,WAAW,CAAC;QACxB,IAAI,QAAQ,YACjB,KAAKA,YAAY,WAAW,CAAC;EAAA,OAG5B,IAAI,MAAM,QAAQ,GAAG,GAAG;GAC7B,MAAM,CAAC,OAAO,UAAU;GACxB,IAAI,UAAU,UACZ,KAAKA,YAAY,SAAS;QACrB,IAAI,UAAU,YACnB,KAAKA,YAAY,WAAW;QACvB,IAAI,UAAU,YACnB,KAAKA,YAAY,WAAW;QACvB,IAAI,UAAU,MACnB,KAAKA,YAAY,KAAK;EAE1B,OAAO,IAAI,OAAO,QAAQ;QACnB,MAAM,OAAO,OAAO,KAAK,GAAG,GAC/B,IAAI,QAAQ,UACV,KAAKA,YAAY,SAAS,IAAI;QACzB,IAAI,QAAQ,YACjB,KAAKA,YAAY,WAAW,IAAI;QAC3B,IAAI,QAAQ,YACjB,KAAKA,YAAY,WAAW,IAAI;QAC3B,IAAI,QAAQ,MACjB,KAAKA,YAAY,KAAK;EAAA;EAK9B,OAAO;CACT;;CAGA,MAAM,GAAiB;EACrB,KAAKH,QAAQ;EACb,OAAO;CACT;;CAGA,OAAO,GAAiB;EACtB,KAAKI,UAAU;EACf,OAAO;CACT;;;;;;;;CASA,YAAY,MAA+B;EACzC,KAAKC,eAAe;EACpB,OAAO;CACT;CAEA,KACE,aACA,YACwB;EACxB,OAAO,KAAKC,KAAK,EAAE,KAAK,aAAoB,UAAiB;CAC/D;CAEA,MAAMA,OAA+B;EACnC,IAAI,CAAC,KAAKJ,eACR,MAAM,IAAI,mCAAmC;EAG/C,MAAM,SAAS,KAAK,YAAY;EAEhC,MAAM,OAAmB;GACvB,YAAY,KAAKH;GACjB,MAAM,KAAKE;GACX;GACA,MAAM,KAAKD;GACX,QAAQ,KAAKI;GACb,YAAY,KAAKD;EACnB;EAEA,KAAKI,oBAAoB,KAAK,MAAM;EAEpC,OAAO,MAAM,KAAKT,MAAM,cAAc,IAAI;CAC5C;;CAGA,MAAM,OAAO,SAAwC;EACnD,MAAM,OAAmB;GACvB,YAAY,KAAKC;GACjB;GACA,aAAa,KAAKM;EACpB;EACA,MAAM,KAAKP,MAAM,cAAc,IAAI;CACrC;;CAGA,MAAM,SAAwB;EAC5B,MAAM,MAAM,KAAK,qBAAqB;EACtC,MAAM,SAAS,KAAK,YAAY;EAEhC,MAAM,OAAmB;GACvB,YAAY,KAAKC;GACjB,KAAK,IAAI,SAAS,IAAI,MAAM,KAAA;GAC5B,QAAQ,UAAU,OAAO,KAAK,MAAM,EAAE,SAAS,IAAI,SAAS,KAAA;GAC5D,aAAa,KAAKM;EACpB;EAEA,MAAM,KAAKP,MAAM,cAAc,IAAI;CACrC;CAEA,oBAAoB,QAAwC;EAC1D,IAAI,CAAC,QACH;EAGF,IAAI,YAAY,MAAM,GAAG;GAEvB,MAAM,gBADM,OAAO,KACO,MAAM,KAAK,KAAK,CAAC,GAAG;GAC9C,IAAI,iBAAiB,OAAO,WAAW,QACrC,MAAM,IAAI,oCAAoC,CAAC,cAAc,OAAO,WAAW,UAAU,CAAC,CAAC;GAE7F;EACF;EAEA,IAAI,SAAS,UAAU,OAAO,KAC5B,KAAK,MAAM,KAAK,OAAO,KACrB,KAAKS,oBAAoB,CAAC;EAI9B,IAAI,QAAQ,UAAU,OAAO,IAC3B,KAAK,MAAM,KAAK,OAAO,IACrB,KAAKA,oBAAoB,CAAC;EAI9B,IAAI,SAAS,UAAU,OAAO,KAC5B,KAAKA,oBAAoB,OAAO,GAAG;CAEvC;AACF"}

package/batteries/vector/chroma/index.d.ts

@@ -6,6 +6,7 @@ import type { VectorFilter } from "../filters";
 import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
 import type { VectorMatch, BaseVectorStoreOptions, VectorStoreCapabilities } from "../types";
 export interface ChromaVectorStoreOptions extends BaseVectorStoreOptions {
+    /** Connection and authentication parameters for the backend. */
     connection?: {
         url?: string;
         host?: string;
@@ -13,14 +14,17 @@ export interface ChromaVectorStoreOptions extends BaseVectorStoreOptions {
         ssl?: boolean;
     };
 }
+/** Translate a neutral {@link VectorFilter} into Chroma's `where` filter object. */
 export declare const translateChromaWhere: (filter?: VectorFilter) => Record<string, unknown> | undefined;
 export declare class ChromaVectorStore extends BaseVectorStore {
     #private;
     readonly capabilities: VectorStoreCapabilities;
+    /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
     static isAvailable(): boolean;
     isAvailable(): boolean;
     connect(): Promise<void>;
     close(): Promise<void>;
+    /** Resolve (and cache) the underlying Chroma collection handle for `name`. */
     getCollection(name: string): Promise<any>;
     createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void>;
     dropCollection(collection: string, ifExists: boolean): Promise<void>;

package/batteries/vector/chroma.cjs

@@ -22,6 +22,7 @@ var getSpace = (metric) => {
 	if (metric === "dot") return "ip";
 	return "cosine";
 };
+/** Translate a neutral {@link VectorFilter} into Chroma's `where` filter object. */
 var translateChromaWhere = (filter) => {
 	if (!filter) return void 0;
 	if (require_batteries_vector_filters.isRawFilter(filter)) {
@@ -78,6 +79,7 @@ var ChromaVectorStore = class extends require_batteries_vector_contract.BaseVect
 	get #opts() {
 		return this.options;
 	}
+	/** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
 	static isAvailable() {
 		return typeof process !== "undefined";
 	}
@@ -112,6 +114,7 @@ var ChromaVectorStore = class extends require_batteries_vector_contract.BaseVect
 		this.#client = null;
 		this.#collectionCache.clear();
 	}
+	/** Resolve (and cache) the underlying Chroma collection handle for `name`. */
 	async getCollection(name) {
 		let collection = this.#collectionCache.get(name);
 		if (collection) return collection;

package/batteries/vector/chroma.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"chroma.cjs","names":["#opts","#client","#collectionCache"],"sources":["../../../src/batteries/vector/chroma/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/chroma\n */\n\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isFilterCondition, isRawFilter, isFilterGroup } from '../filters'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR,\n} from '../exceptions'\nimport type { VectorFilter } from '../filters'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorMetadata,\n  BaseVectorStoreOptions,\n  VectorStoreCapabilities,\n} from '../types'\n\nexport interface ChromaVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { url?: string; host?: string; port?: number; ssl?: boolean }\n}\n\nconst getChromaClient = async () => {\n  try {\n    const mod = await import('chromadb')\n    return mod.ChromaClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['chromadb'])\n  }\n}\n\nconst getSpace = (metric: string): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'l2'\n  if (metric === 'dot') return 'ip'\n  return 'cosine'\n}\n\nexport const translateChromaWhere = (\n  filter?: VectorFilter\n): Record<string, unknown> | undefined => {\n  if (!filter) return undefined\n  if (isRawFilter(filter)) {\n    if (filter.$dialect === 'chroma') {\n      return filter.$raw as Record<string, unknown>\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', String(filter.$dialect)])\n  }\n  if (isFilterCondition(filter)) {\n    const { field, op, value } = filter\n    if (value === undefined) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    if (op === 'eq') {\n      return { [field]: { $eq: value } }\n    }\n    if (op === 'ne') {\n      return { [field]: { $ne: value } }\n    }\n    if (op === 'gt') {\n      return { [field]: { $gt: value } }\n    }\n    if (op === 'gte') {\n      return { [field]: { $gte: value } }\n    }\n    if (op === 'lt') {\n      return { [field]: { $lt: value } }\n    }\n    if (op === 'lte') {\n      return { [field]: { $lte: value } }\n    }\n    if (op === 'in') {\n      return { [field]: { $in: value } }\n    }\n    if (op === 'nin') {\n      return { [field]: { $nin: value } }\n    }\n    if (op === 'exists' || op === 'contains') {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n  }\n  if (isFilterGroup(filter)) {\n    const { and, or, not } = filter\n    if (and) {\n      const children = and\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $and: children }\n    }\n    if (or) {\n      const children = or\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $or: children }\n    }\n    if (not) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', 'not'])\n    }\n    return undefined\n  }\n  return undefined\n}\n\nexport class ChromaVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // Strongly consistent on resolve; the option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n  #client: any | null = null\n  #collectionCache: Map<string, any> = new Map()\n  get #opts() {\n    return this.options as ChromaVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const ChromaClient = await getChromaClient()\n    const c = this.#opts.connection || {}\n    let host: string | undefined\n    let port: number | undefined\n    let ssl: boolean = false\n\n    if (c.url) {\n      const url = new URL(c.url)\n      host = url.hostname\n      port = url.port ? Number.parseInt(url.port, 10) : url.protocol === 'https:' ? 443 : 80\n      ssl = url.protocol === 'https:'\n    } else {\n      host = c.host\n      port = c.port\n      ssl = c.ssl || false\n    }\n\n    const path =\n      host && port !== undefined\n        ? `${ssl ? 'https://' : 'http://'}${host}${port === 80 || port === 443 ? '' : ':' + port}`\n        : undefined\n\n    try {\n      this.#client = new ChromaClient({ path })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n    this.#collectionCache.clear()\n  }\n\n  async getCollection(name: string): Promise<any> {\n    let collection = this.#collectionCache.get(name)\n    if (collection) return collection\n    if (!this.#client) await this.connect()\n    const metric = this.#opts.metric ?? 'cosine'\n    collection = await this.#client.getOrCreateCollection({\n      name,\n      metadata: { 'hnsw:space': getSpace(metric) },\n    })\n    this.#collectionCache.set(name, collection)\n    return collection\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const name = spec.collection\n    if (ifNotExists && (await this.hasCollection(name))) return\n    if (await this.hasCollection(name)) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['create', 'exists'])\n    }\n    try {\n      await this.connect()\n      const metric = spec.vector.metric ?? 'cosine'\n      await this.#client!.getOrCreateCollection({\n        name,\n        metadata: { 'hnsw:space': getSpace(metric) },\n      })\n      this.#collectionCache.set(name, null)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.connect()\n      await this.#client!.deleteCollection({ name: collection })\n      this.#collectionCache.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    if (!this.#client) await this.connect()\n    try {\n      const collections = await this.#client!.listCollections()\n      for (const c of collections) {\n        if (typeof c === 'object' ? c.name === collection : c === collection) {\n          return true\n        }\n      }\n      return false\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    try {\n      const collection = await this.getCollection(from)\n      await collection.modify({ name: to })\n      const cached = this.#collectionCache.get(from)\n      this.#collectionCache.delete(from)\n      if (cached) {\n        this.#collectionCache.set(to, cached)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const collection = await this.getCollection(plan.collection)\n    const expected = this.#opts.dimensions\n    const ids: string[] = []\n    const embeddings: number[][] = []\n    const documents: string[] = []\n    const metadatas: VectorMetadata[] = []\n\n    for (const r of plan.records) {\n      let vector = r.vector\n      if (!vector && r.document) {\n        const [v] = await this.encode([r.document], 'document')\n        vector = v\n      }\n      if (!vector) {\n        throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n      }\n      if (expected !== undefined && vector.length !== expected) {\n        throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n      }\n      ids.push(r.id)\n      embeddings.push(vector)\n      documents.push(r.document ?? '')\n      const md = { ...(r.metadata ?? {}), internalId: r.id }\n      metadatas.push(md)\n    }\n\n    try {\n      await collection.upsert({ ids, embeddings, documents, metadatas })\n    } catch (err) {\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const collection = await this.getCollection(plan.collection)\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const res = await collection.get({ ids: [plan.near.id], include: ['embeddings'] })\n        if (!res.ids || res.ids.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        const embeddings = res.embeddings || []\n        if (!embeddings || embeddings.length === 0 || !embeddings[0]) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id has no vector: ' + plan.near.id])\n        }\n        queryVector = embeddings[0]\n      }\n    }\n\n    const where = translateChromaWhere(plan.filter)\n\n    let results: any\n    if (queryVector) {\n      try {\n        results = await collection.query({\n          queryEmbeddings: [queryVector],\n          nResults: plan.topK,\n          where,\n          include: ['documents', 'metadatas', 'distances', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    } else {\n      try {\n        results = await collection.get({\n          where,\n          limit: plan.topK,\n          include: ['documents', 'metadatas', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    }\n\n    const proj = plan.projection\n    const out: VectorMatch[] = []\n    // `query()` returns per-query nested arrays (`ids: [[...]]`); `get()` (the filter-scan path)\n    // returns flat arrays (`ids: [...]`). Unwrap one level only for the query path.\n    const unwrap = (col: any): any[] => {\n      if (!col) return []\n      return queryVector ? (col[0] ?? []) : col\n    }\n    const ids = unwrap(results.ids)\n    const documents = unwrap(results.documents)\n    const metadatas = unwrap(results.metadatas)\n    const embeddings = unwrap(results.embeddings)\n    const distances = unwrap(results.distances)\n\n    const start = plan.offset || 0\n    const limit = plan.topK\n\n    for (let i = start; i < Math.min(ids.length, start + limit); i++) {\n      const match: VectorMatch = {}\n      if (proj.id) {\n        match.id = ids[i]\n      }\n      if (proj.vector && embeddings[i]) {\n        match.vector = embeddings[i]\n      }\n      if (proj.document) {\n        match.document = documents[i] ?? undefined\n      }\n      if (proj.metadata && metadatas[i]) {\n        const rawMeta = metadatas[i] as VectorMetadata\n        const { internalId, ...rest } = rawMeta\n        match.metadata = rest\n      }\n      if (queryVector && distances && distances[i] !== undefined) {\n        match.score = normalizeScore(distances[i], metric, 'distance')\n      }\n      out.push(match)\n    }\n\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = await this.getCollection(plan.collection)\n    try {\n      if (plan.ids) {\n        await collection.delete({ ids: plan.ids })\n      } else if (plan.filter) {\n        const where = translateChromaWhere(plan.filter)\n        if (where) {\n          await collection.delete({ where })\n        } else {\n          await collection.delete({ where: {} })\n        }\n      } else {\n        await collection.delete({ where: {} })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"chroma.cjs","names":["#opts","#client","#collectionCache"],"sources":["../../../src/batteries/vector/chroma/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/chroma\n */\n\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isFilterCondition, isRawFilter, isFilterGroup } from '../filters'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR,\n} from '../exceptions'\nimport type { VectorFilter } from '../filters'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorMetadata,\n  BaseVectorStoreOptions,\n  VectorStoreCapabilities,\n} from '../types'\n\nexport interface ChromaVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection?: { url?: string; host?: string; port?: number; ssl?: boolean }\n}\n\nconst getChromaClient = async () => {\n  try {\n    const mod = await import('chromadb')\n    return mod.ChromaClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['chromadb'])\n  }\n}\n\nconst getSpace = (metric: string): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'l2'\n  if (metric === 'dot') return 'ip'\n  return 'cosine'\n}\n\n/** Translate a neutral {@link VectorFilter} into Chroma's `where` filter object. */\nexport const translateChromaWhere = (\n  filter?: VectorFilter\n): Record<string, unknown> | undefined => {\n  if (!filter) return undefined\n  if (isRawFilter(filter)) {\n    if (filter.$dialect === 'chroma') {\n      return filter.$raw as Record<string, unknown>\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', String(filter.$dialect)])\n  }\n  if (isFilterCondition(filter)) {\n    const { field, op, value } = filter\n    if (value === undefined) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    if (op === 'eq') {\n      return { [field]: { $eq: value } }\n    }\n    if (op === 'ne') {\n      return { [field]: { $ne: value } }\n    }\n    if (op === 'gt') {\n      return { [field]: { $gt: value } }\n    }\n    if (op === 'gte') {\n      return { [field]: { $gte: value } }\n    }\n    if (op === 'lt') {\n      return { [field]: { $lt: value } }\n    }\n    if (op === 'lte') {\n      return { [field]: { $lte: value } }\n    }\n    if (op === 'in') {\n      return { [field]: { $in: value } }\n    }\n    if (op === 'nin') {\n      return { [field]: { $nin: value } }\n    }\n    if (op === 'exists' || op === 'contains') {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n  }\n  if (isFilterGroup(filter)) {\n    const { and, or, not } = filter\n    if (and) {\n      const children = and\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $and: children }\n    }\n    if (or) {\n      const children = or\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $or: children }\n    }\n    if (not) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', 'not'])\n    }\n    return undefined\n  }\n  return undefined\n}\n\nexport class ChromaVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // Strongly consistent on resolve; the option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n  #client: any | null = null\n  #collectionCache: Map<string, any> = new Map()\n  get #opts() {\n    return this.options as ChromaVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const ChromaClient = await getChromaClient()\n    const c = this.#opts.connection || {}\n    let host: string | undefined\n    let port: number | undefined\n    let ssl: boolean = false\n\n    if (c.url) {\n      const url = new URL(c.url)\n      host = url.hostname\n      port = url.port ? Number.parseInt(url.port, 10) : url.protocol === 'https:' ? 443 : 80\n      ssl = url.protocol === 'https:'\n    } else {\n      host = c.host\n      port = c.port\n      ssl = c.ssl || false\n    }\n\n    const path =\n      host && port !== undefined\n        ? `${ssl ? 'https://' : 'http://'}${host}${port === 80 || port === 443 ? '' : ':' + port}`\n        : undefined\n\n    try {\n      this.#client = new ChromaClient({ path })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n    this.#collectionCache.clear()\n  }\n\n  /** Resolve (and cache) the underlying Chroma collection handle for `name`. */\n  async getCollection(name: string): Promise<any> {\n    let collection = this.#collectionCache.get(name)\n    if (collection) return collection\n    if (!this.#client) await this.connect()\n    const metric = this.#opts.metric ?? 'cosine'\n    collection = await this.#client.getOrCreateCollection({\n      name,\n      metadata: { 'hnsw:space': getSpace(metric) },\n    })\n    this.#collectionCache.set(name, collection)\n    return collection\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const name = spec.collection\n    if (ifNotExists && (await this.hasCollection(name))) return\n    if (await this.hasCollection(name)) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['create', 'exists'])\n    }\n    try {\n      await this.connect()\n      const metric = spec.vector.metric ?? 'cosine'\n      await this.#client!.getOrCreateCollection({\n        name,\n        metadata: { 'hnsw:space': getSpace(metric) },\n      })\n      this.#collectionCache.set(name, null)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.connect()\n      await this.#client!.deleteCollection({ name: collection })\n      this.#collectionCache.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    if (!this.#client) await this.connect()\n    try {\n      const collections = await this.#client!.listCollections()\n      for (const c of collections) {\n        if (typeof c === 'object' ? c.name === collection : c === collection) {\n          return true\n        }\n      }\n      return false\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    try {\n      const collection = await this.getCollection(from)\n      await collection.modify({ name: to })\n      const cached = this.#collectionCache.get(from)\n      this.#collectionCache.delete(from)\n      if (cached) {\n        this.#collectionCache.set(to, cached)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const collection = await this.getCollection(plan.collection)\n    const expected = this.#opts.dimensions\n    const ids: string[] = []\n    const embeddings: number[][] = []\n    const documents: string[] = []\n    const metadatas: VectorMetadata[] = []\n\n    for (const r of plan.records) {\n      let vector = r.vector\n      if (!vector && r.document) {\n        const [v] = await this.encode([r.document], 'document')\n        vector = v\n      }\n      if (!vector) {\n        throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n      }\n      if (expected !== undefined && vector.length !== expected) {\n        throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n      }\n      ids.push(r.id)\n      embeddings.push(vector)\n      documents.push(r.document ?? '')\n      const md = { ...(r.metadata ?? {}), internalId: r.id }\n      metadatas.push(md)\n    }\n\n    try {\n      await collection.upsert({ ids, embeddings, documents, metadatas })\n    } catch (err) {\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const collection = await this.getCollection(plan.collection)\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const res = await collection.get({ ids: [plan.near.id], include: ['embeddings'] })\n        if (!res.ids || res.ids.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        const embeddings = res.embeddings || []\n        if (!embeddings || embeddings.length === 0 || !embeddings[0]) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id has no vector: ' + plan.near.id])\n        }\n        queryVector = embeddings[0]\n      }\n    }\n\n    const where = translateChromaWhere(plan.filter)\n\n    let results: any\n    if (queryVector) {\n      try {\n        results = await collection.query({\n          queryEmbeddings: [queryVector],\n          nResults: plan.topK,\n          where,\n          include: ['documents', 'metadatas', 'distances', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    } else {\n      try {\n        results = await collection.get({\n          where,\n          limit: plan.topK,\n          include: ['documents', 'metadatas', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    }\n\n    const proj = plan.projection\n    const out: VectorMatch[] = []\n    // `query()` returns per-query nested arrays (`ids: [[...]]`); `get()` (the filter-scan path)\n    // returns flat arrays (`ids: [...]`). Unwrap one level only for the query path.\n    const unwrap = (col: any): any[] => {\n      if (!col) return []\n      return queryVector ? (col[0] ?? []) : col\n    }\n    const ids = unwrap(results.ids)\n    const documents = unwrap(results.documents)\n    const metadatas = unwrap(results.metadatas)\n    const embeddings = unwrap(results.embeddings)\n    const distances = unwrap(results.distances)\n\n    const start = plan.offset || 0\n    const limit = plan.topK\n\n    for (let i = start; i < Math.min(ids.length, start + limit); i++) {\n      const match: VectorMatch = {}\n      if (proj.id) {\n        match.id = ids[i]\n      }\n      if (proj.vector && embeddings[i]) {\n        match.vector = embeddings[i]\n      }\n      if (proj.document) {\n        match.document = documents[i] ?? undefined\n      }\n      if (proj.metadata && metadatas[i]) {\n        const rawMeta = metadatas[i] as VectorMetadata\n        const { internalId, ...rest } = rawMeta\n        match.metadata = rest\n      }\n      if (queryVector && distances && distances[i] !== undefined) {\n        match.score = normalizeScore(distances[i], metric, 'distance')\n      }\n      out.push(match)\n    }\n\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = await this.getCollection(plan.collection)\n    try {\n      if (plan.ids) {\n        await collection.delete({ ids: plan.ids })\n      } else if (plan.filter) {\n        const where = translateChromaWhere(plan.filter)\n        if (where) {\n          await collection.delete({ where })\n        } else {\n          await collection.delete({ where: {} })\n        }\n      } else {\n        await collection.delete({ where: {} })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/chroma.mjs

@@ -20,6 +20,7 @@ var getSpace = (metric) => {
 	if (metric === "dot") return "ip";
 	return "cosine";
 };
+/** Translate a neutral {@link VectorFilter} into Chroma's `where` filter object. */
 var translateChromaWhere = (filter) => {
 	if (!filter) return void 0;
 	if (isRawFilter(filter)) {
@@ -76,6 +77,7 @@ var ChromaVectorStore = class extends BaseVectorStore {
 	get #opts() {
 		return this.options;
 	}
+	/** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
 	static isAvailable() {
 		return typeof process !== "undefined";
 	}
@@ -110,6 +112,7 @@ var ChromaVectorStore = class extends BaseVectorStore {
 		this.#client = null;
 		this.#collectionCache.clear();
 	}
+	/** Resolve (and cache) the underlying Chroma collection handle for `name`. */
 	async getCollection(name) {
 		let collection = this.#collectionCache.get(name);
 		if (collection) return collection;

package/batteries/vector/chroma.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"chroma.mjs","names":["#opts","#client","#collectionCache"],"sources":["../../../src/batteries/vector/chroma/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/chroma\n */\n\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isFilterCondition, isRawFilter, isFilterGroup } from '../filters'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR,\n} from '../exceptions'\nimport type { VectorFilter } from '../filters'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorMetadata,\n  BaseVectorStoreOptions,\n  VectorStoreCapabilities,\n} from '../types'\n\nexport interface ChromaVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { url?: string; host?: string; port?: number; ssl?: boolean }\n}\n\nconst getChromaClient = async () => {\n  try {\n    const mod = await import('chromadb')\n    return mod.ChromaClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['chromadb'])\n  }\n}\n\nconst getSpace = (metric: string): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'l2'\n  if (metric === 'dot') return 'ip'\n  return 'cosine'\n}\n\nexport const translateChromaWhere = (\n  filter?: VectorFilter\n): Record<string, unknown> | undefined => {\n  if (!filter) return undefined\n  if (isRawFilter(filter)) {\n    if (filter.$dialect === 'chroma') {\n      return filter.$raw as Record<string, unknown>\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', String(filter.$dialect)])\n  }\n  if (isFilterCondition(filter)) {\n    const { field, op, value } = filter\n    if (value === undefined) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    if (op === 'eq') {\n      return { [field]: { $eq: value } }\n    }\n    if (op === 'ne') {\n      return { [field]: { $ne: value } }\n    }\n    if (op === 'gt') {\n      return { [field]: { $gt: value } }\n    }\n    if (op === 'gte') {\n      return { [field]: { $gte: value } }\n    }\n    if (op === 'lt') {\n      return { [field]: { $lt: value } }\n    }\n    if (op === 'lte') {\n      return { [field]: { $lte: value } }\n    }\n    if (op === 'in') {\n      return { [field]: { $in: value } }\n    }\n    if (op === 'nin') {\n      return { [field]: { $nin: value } }\n    }\n    if (op === 'exists' || op === 'contains') {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n  }\n  if (isFilterGroup(filter)) {\n    const { and, or, not } = filter\n    if (and) {\n      const children = and\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $and: children }\n    }\n    if (or) {\n      const children = or\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $or: children }\n    }\n    if (not) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', 'not'])\n    }\n    return undefined\n  }\n  return undefined\n}\n\nexport class ChromaVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // Strongly consistent on resolve; the option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n  #client: any | null = null\n  #collectionCache: Map<string, any> = new Map()\n  get #opts() {\n    return this.options as ChromaVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const ChromaClient = await getChromaClient()\n    const c = this.#opts.connection || {}\n    let host: string | undefined\n    let port: number | undefined\n    let ssl: boolean = false\n\n    if (c.url) {\n      const url = new URL(c.url)\n      host = url.hostname\n      port = url.port ? Number.parseInt(url.port, 10) : url.protocol === 'https:' ? 443 : 80\n      ssl = url.protocol === 'https:'\n    } else {\n      host = c.host\n      port = c.port\n      ssl = c.ssl || false\n    }\n\n    const path =\n      host && port !== undefined\n        ? `${ssl ? 'https://' : 'http://'}${host}${port === 80 || port === 443 ? '' : ':' + port}`\n        : undefined\n\n    try {\n      this.#client = new ChromaClient({ path })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n    this.#collectionCache.clear()\n  }\n\n  async getCollection(name: string): Promise<any> {\n    let collection = this.#collectionCache.get(name)\n    if (collection) return collection\n    if (!this.#client) await this.connect()\n    const metric = this.#opts.metric ?? 'cosine'\n    collection = await this.#client.getOrCreateCollection({\n      name,\n      metadata: { 'hnsw:space': getSpace(metric) },\n    })\n    this.#collectionCache.set(name, collection)\n    return collection\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const name = spec.collection\n    if (ifNotExists && (await this.hasCollection(name))) return\n    if (await this.hasCollection(name)) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['create', 'exists'])\n    }\n    try {\n      await this.connect()\n      const metric = spec.vector.metric ?? 'cosine'\n      await this.#client!.getOrCreateCollection({\n        name,\n        metadata: { 'hnsw:space': getSpace(metric) },\n      })\n      this.#collectionCache.set(name, null)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.connect()\n      await this.#client!.deleteCollection({ name: collection })\n      this.#collectionCache.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    if (!this.#client) await this.connect()\n    try {\n      const collections = await this.#client!.listCollections()\n      for (const c of collections) {\n        if (typeof c === 'object' ? c.name === collection : c === collection) {\n          return true\n        }\n      }\n      return false\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    try {\n      const collection = await this.getCollection(from)\n      await collection.modify({ name: to })\n      const cached = this.#collectionCache.get(from)\n      this.#collectionCache.delete(from)\n      if (cached) {\n        this.#collectionCache.set(to, cached)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const collection = await this.getCollection(plan.collection)\n    const expected = this.#opts.dimensions\n    const ids: string[] = []\n    const embeddings: number[][] = []\n    const documents: string[] = []\n    const metadatas: VectorMetadata[] = []\n\n    for (const r of plan.records) {\n      let vector = r.vector\n      if (!vector && r.document) {\n        const [v] = await this.encode([r.document], 'document')\n        vector = v\n      }\n      if (!vector) {\n        throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n      }\n      if (expected !== undefined && vector.length !== expected) {\n        throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n      }\n      ids.push(r.id)\n      embeddings.push(vector)\n      documents.push(r.document ?? '')\n      const md = { ...(r.metadata ?? {}), internalId: r.id }\n      metadatas.push(md)\n    }\n\n    try {\n      await collection.upsert({ ids, embeddings, documents, metadatas })\n    } catch (err) {\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const collection = await this.getCollection(plan.collection)\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const res = await collection.get({ ids: [plan.near.id], include: ['embeddings'] })\n        if (!res.ids || res.ids.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        const embeddings = res.embeddings || []\n        if (!embeddings || embeddings.length === 0 || !embeddings[0]) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id has no vector: ' + plan.near.id])\n        }\n        queryVector = embeddings[0]\n      }\n    }\n\n    const where = translateChromaWhere(plan.filter)\n\n    let results: any\n    if (queryVector) {\n      try {\n        results = await collection.query({\n          queryEmbeddings: [queryVector],\n          nResults: plan.topK,\n          where,\n          include: ['documents', 'metadatas', 'distances', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    } else {\n      try {\n        results = await collection.get({\n          where,\n          limit: plan.topK,\n          include: ['documents', 'metadatas', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    }\n\n    const proj = plan.projection\n    const out: VectorMatch[] = []\n    // `query()` returns per-query nested arrays (`ids: [[...]]`); `get()` (the filter-scan path)\n    // returns flat arrays (`ids: [...]`). Unwrap one level only for the query path.\n    const unwrap = (col: any): any[] => {\n      if (!col) return []\n      return queryVector ? (col[0] ?? []) : col\n    }\n    const ids = unwrap(results.ids)\n    const documents = unwrap(results.documents)\n    const metadatas = unwrap(results.metadatas)\n    const embeddings = unwrap(results.embeddings)\n    const distances = unwrap(results.distances)\n\n    const start = plan.offset || 0\n    const limit = plan.topK\n\n    for (let i = start; i < Math.min(ids.length, start + limit); i++) {\n      const match: VectorMatch = {}\n      if (proj.id) {\n        match.id = ids[i]\n      }\n      if (proj.vector && embeddings[i]) {\n        match.vector = embeddings[i]\n      }\n      if (proj.document) {\n        match.document = documents[i] ?? undefined\n      }\n      if (proj.metadata && metadatas[i]) {\n        const rawMeta = metadatas[i] as VectorMetadata\n        const { internalId, ...rest } = rawMeta\n        match.metadata = rest\n      }\n      if (queryVector && distances && distances[i] !== undefined) {\n        match.score = normalizeScore(distances[i], metric, 'distance')\n      }\n      out.push(match)\n    }\n\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = await this.getCollection(plan.collection)\n    try {\n      if (plan.ids) {\n        await collection.delete({ ids: plan.ids })\n      } else if (plan.filter) {\n        const where = translateChromaWhere(plan.filter)\n        if (where) {\n          await collection.delete({ where })\n        } else {\n          await collection.delete({ where: {} })\n        }\n      } else {\n        await collection.delete({ where: {} })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"chroma.mjs","names":["#opts","#client","#collectionCache"],"sources":["../../../src/batteries/vector/chroma/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/chroma\n */\n\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isFilterCondition, isRawFilter, isFilterGroup } from '../filters'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR,\n} from '../exceptions'\nimport type { VectorFilter } from '../filters'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorMetadata,\n  BaseVectorStoreOptions,\n  VectorStoreCapabilities,\n} from '../types'\n\nexport interface ChromaVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection?: { url?: string; host?: string; port?: number; ssl?: boolean }\n}\n\nconst getChromaClient = async () => {\n  try {\n    const mod = await import('chromadb')\n    return mod.ChromaClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['chromadb'])\n  }\n}\n\nconst getSpace = (metric: string): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'l2'\n  if (metric === 'dot') return 'ip'\n  return 'cosine'\n}\n\n/** Translate a neutral {@link VectorFilter} into Chroma's `where` filter object. */\nexport const translateChromaWhere = (\n  filter?: VectorFilter\n): Record<string, unknown> | undefined => {\n  if (!filter) return undefined\n  if (isRawFilter(filter)) {\n    if (filter.$dialect === 'chroma') {\n      return filter.$raw as Record<string, unknown>\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', String(filter.$dialect)])\n  }\n  if (isFilterCondition(filter)) {\n    const { field, op, value } = filter\n    if (value === undefined) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    if (op === 'eq') {\n      return { [field]: { $eq: value } }\n    }\n    if (op === 'ne') {\n      return { [field]: { $ne: value } }\n    }\n    if (op === 'gt') {\n      return { [field]: { $gt: value } }\n    }\n    if (op === 'gte') {\n      return { [field]: { $gte: value } }\n    }\n    if (op === 'lt') {\n      return { [field]: { $lt: value } }\n    }\n    if (op === 'lte') {\n      return { [field]: { $lte: value } }\n    }\n    if (op === 'in') {\n      return { [field]: { $in: value } }\n    }\n    if (op === 'nin') {\n      return { [field]: { $nin: value } }\n    }\n    if (op === 'exists' || op === 'contains') {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', op])\n  }\n  if (isFilterGroup(filter)) {\n    const { and, or, not } = filter\n    if (and) {\n      const children = and\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $and: children }\n    }\n    if (or) {\n      const children = or\n        .map((f) => translateChromaWhere(f) as Record<string, unknown>)\n        .filter((c) => c !== undefined)\n      if (children.length === 0) return undefined\n      if (children.length === 1) return children[0]\n      return { $or: children }\n    }\n    if (not) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['chroma', 'not'])\n    }\n    return undefined\n  }\n  return undefined\n}\n\nexport class ChromaVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // Strongly consistent on resolve; the option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n  #client: any | null = null\n  #collectionCache: Map<string, any> = new Map()\n  get #opts() {\n    return this.options as ChromaVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const ChromaClient = await getChromaClient()\n    const c = this.#opts.connection || {}\n    let host: string | undefined\n    let port: number | undefined\n    let ssl: boolean = false\n\n    if (c.url) {\n      const url = new URL(c.url)\n      host = url.hostname\n      port = url.port ? Number.parseInt(url.port, 10) : url.protocol === 'https:' ? 443 : 80\n      ssl = url.protocol === 'https:'\n    } else {\n      host = c.host\n      port = c.port\n      ssl = c.ssl || false\n    }\n\n    const path =\n      host && port !== undefined\n        ? `${ssl ? 'https://' : 'http://'}${host}${port === 80 || port === 443 ? '' : ':' + port}`\n        : undefined\n\n    try {\n      this.#client = new ChromaClient({ path })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n    this.#collectionCache.clear()\n  }\n\n  /** Resolve (and cache) the underlying Chroma collection handle for `name`. */\n  async getCollection(name: string): Promise<any> {\n    let collection = this.#collectionCache.get(name)\n    if (collection) return collection\n    if (!this.#client) await this.connect()\n    const metric = this.#opts.metric ?? 'cosine'\n    collection = await this.#client.getOrCreateCollection({\n      name,\n      metadata: { 'hnsw:space': getSpace(metric) },\n    })\n    this.#collectionCache.set(name, collection)\n    return collection\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const name = spec.collection\n    if (ifNotExists && (await this.hasCollection(name))) return\n    if (await this.hasCollection(name)) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['create', 'exists'])\n    }\n    try {\n      await this.connect()\n      const metric = spec.vector.metric ?? 'cosine'\n      await this.#client!.getOrCreateCollection({\n        name,\n        metadata: { 'hnsw:space': getSpace(metric) },\n      })\n      this.#collectionCache.set(name, null)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.connect()\n      await this.#client!.deleteCollection({ name: collection })\n      this.#collectionCache.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    if (!this.#client) await this.connect()\n    try {\n      const collections = await this.#client!.listCollections()\n      for (const c of collections) {\n        if (typeof c === 'object' ? c.name === collection : c === collection) {\n          return true\n        }\n      }\n      return false\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    try {\n      const collection = await this.getCollection(from)\n      await collection.modify({ name: to })\n      const cached = this.#collectionCache.get(from)\n      this.#collectionCache.delete(from)\n      if (cached) {\n        this.#collectionCache.set(to, cached)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const collection = await this.getCollection(plan.collection)\n    const expected = this.#opts.dimensions\n    const ids: string[] = []\n    const embeddings: number[][] = []\n    const documents: string[] = []\n    const metadatas: VectorMetadata[] = []\n\n    for (const r of plan.records) {\n      let vector = r.vector\n      if (!vector && r.document) {\n        const [v] = await this.encode([r.document], 'document')\n        vector = v\n      }\n      if (!vector) {\n        throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n      }\n      if (expected !== undefined && vector.length !== expected) {\n        throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n      }\n      ids.push(r.id)\n      embeddings.push(vector)\n      documents.push(r.document ?? '')\n      const md = { ...(r.metadata ?? {}), internalId: r.id }\n      metadatas.push(md)\n    }\n\n    try {\n      await collection.upsert({ ids, embeddings, documents, metadatas })\n    } catch (err) {\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const collection = await this.getCollection(plan.collection)\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const res = await collection.get({ ids: [plan.near.id], include: ['embeddings'] })\n        if (!res.ids || res.ids.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        const embeddings = res.embeddings || []\n        if (!embeddings || embeddings.length === 0 || !embeddings[0]) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id has no vector: ' + plan.near.id])\n        }\n        queryVector = embeddings[0]\n      }\n    }\n\n    const where = translateChromaWhere(plan.filter)\n\n    let results: any\n    if (queryVector) {\n      try {\n        results = await collection.query({\n          queryEmbeddings: [queryVector],\n          nResults: plan.topK,\n          where,\n          include: ['documents', 'metadatas', 'distances', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    } else {\n      try {\n        results = await collection.get({\n          where,\n          limit: plan.topK,\n          include: ['documents', 'metadatas', 'embeddings'],\n        })\n      } catch (err) {\n        throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n      }\n    }\n\n    const proj = plan.projection\n    const out: VectorMatch[] = []\n    // `query()` returns per-query nested arrays (`ids: [[...]]`); `get()` (the filter-scan path)\n    // returns flat arrays (`ids: [...]`). Unwrap one level only for the query path.\n    const unwrap = (col: any): any[] => {\n      if (!col) return []\n      return queryVector ? (col[0] ?? []) : col\n    }\n    const ids = unwrap(results.ids)\n    const documents = unwrap(results.documents)\n    const metadatas = unwrap(results.metadatas)\n    const embeddings = unwrap(results.embeddings)\n    const distances = unwrap(results.distances)\n\n    const start = plan.offset || 0\n    const limit = plan.topK\n\n    for (let i = start; i < Math.min(ids.length, start + limit); i++) {\n      const match: VectorMatch = {}\n      if (proj.id) {\n        match.id = ids[i]\n      }\n      if (proj.vector && embeddings[i]) {\n        match.vector = embeddings[i]\n      }\n      if (proj.document) {\n        match.document = documents[i] ?? undefined\n      }\n      if (proj.metadata && metadatas[i]) {\n        const rawMeta = metadatas[i] as VectorMetadata\n        const { internalId, ...rest } = rawMeta\n        match.metadata = rest\n      }\n      if (queryVector && distances && distances[i] !== undefined) {\n        match.score = normalizeScore(distances[i], metric, 'distance')\n      }\n      out.push(match)\n    }\n\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = await this.getCollection(plan.collection)\n    try {\n      if (plan.ids) {\n        await collection.delete({ ids: plan.ids })\n      } else if (plan.filter) {\n        const where = translateChromaWhere(plan.filter)\n        if (where) {\n          await collection.delete({ where })\n        } else {\n          await collection.delete({ where: {} })\n        }\n      } else {\n        await collection.delete({ where: {} })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/clickhouse/index.d.ts

@@ -15,6 +15,7 @@ import { BaseVectorStore } from "../contract";
 import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
 import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
 export interface ClickHouseVectorStoreOptions extends BaseVectorStoreOptions {
+    /** Connection and authentication parameters for the backend. */
     connection?: {
         url?: string;
         username?: string;
@@ -25,6 +26,7 @@ export interface ClickHouseVectorStoreOptions extends BaseVectorStoreOptions {
 export declare class ClickHouseVectorStore extends BaseVectorStore {
     #private;
     readonly capabilities: VectorStoreCapabilities;
+    /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
     static isAvailable(): boolean;
     isAvailable(): boolean;
     connect(): Promise<void>;

package/batteries/vector/clickhouse.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
 require("../../guards.cjs");
 const require_batteries_vector_filters = require("./filters.cjs");
 const require_batteries_vector_helpers = require("./helpers.cjs");
@@ -50,6 +50,7 @@ var ClickHouseVectorStore = class extends require_batteries_vector_contract.Base
 	get #opts() {
 		return this.options;
 	}
+	/** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
 	static isAvailable() {
 		return typeof process !== "undefined";
 	}

package/batteries/vector/clickhouse.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"clickhouse.cjs","names":["#opts","#client","#ensure","#json","#dims","#parseMeta","#project"],"sources":["../../../src/batteries/vector/clickhouse/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/clickhouse\n *\n * ClickHouse adapter. Vectors live in an `Array(Float32)` column; KNN uses ClickHouse's\n * `cosineDistance` / `L2Distance` / negative-inner-product expressions ordered ascending.\n * Metadata is a JSON `String` column, filtered with the neutral filter tree's JS reference\n * evaluator for exact cross-adapter parity. Each collection is a MergeTree table.\n *\n * MergeTree allows duplicate keys, so upsert is delete-then-insert; writes are made\n * read-after-write consistent with `mutations_sync = 2` on deletes.\n *\n * Driver: `@clickhouse/client` (HTTP).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface ClickHouseVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { url?: string; username?: string; password?: string; database?: string }\n}\n\nconst getClickHouseClient = async () => {\n  try {\n    const mod = await import('@clickhouse/client')\n    return mod.createClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@clickhouse/client'])\n  }\n}\n\n// ClickHouse distance expression per metric (all \"lower is closer\" once negated for dot).\nconst distanceExpr = (metric: DistanceMetric, vecLit: string): string =>\n  metric === 'euclidean'\n    ? `L2Distance(vec, ${vecLit})`\n    : metric === 'dot'\n      ? `-arraySum(arrayMap((a, b) -> a * b, vec, ${vecLit}))`\n      : `cosineDistance(vec, ${vecLit})`\n\n// Backtick-quote an identifier, escaping embedded backticks.\nconst ident = (name: string): string => '`' + name.replace(/`/g, '``') + '`'\n\n// Single-quoted ClickHouse string literal.\nconst lit = (value: string): string => `'${value.replace(/\\\\/g, '\\\\\\\\').replace(/'/g, \"\\\\'\")}'`\n\n// number[] → ClickHouse array literal [1, 2, 3].\nconst vectorLiteral = (vector: number[]): string =>\n  `[${vector.map((n) => (Number.isFinite(n) ? String(n) : '0')).join(', ')}]`\n\nexport class ClickHouseVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: true,\n    builtInEncoding: false,\n    // Made strongly consistent via mutations_sync=2 on deletes; writes visible on resolve.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #client: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): ClickHouseVectorStoreOptions {\n    return this.options as ClickHouseVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const createClient = await getClickHouseClient()\n    const c = this.#opts.connection || {}\n    try {\n      this.#client = createClient({\n        url: c.url ?? 'http://localhost:8123',\n        username: c.username ?? 'default',\n        password: c.password ?? '',\n        database: c.database ?? 'default',\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    if (this.#client) {\n      await this.#client.close()\n      this.#client = null\n    }\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#client) await this.connect()\n    return this.#client!\n  }\n\n  async #json(sql: string): Promise<any[]> {\n    const client = await this.#ensure()\n    const rs = await client.query({ query: sql, format: 'JSONEachRow' })\n    return (await rs.json()) as any[]\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await client.command({\n        query:\n          `CREATE TABLE ${ine}${ident(spec.collection)} (` +\n          `id String, vec Array(Float32), document String, metadata String` +\n          `) ENGINE = MergeTree() ORDER BY id`,\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    const ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await client.command({ query: `DROP TABLE ${ie}${ident(collection)}` })\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const rows = await this.#json(`EXISTS TABLE ${ident(collection)}`)\n    return rows.length > 0 && (rows[0].result === 1 || rows[0].result === '1')\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    const client = await this.#ensure()\n    try {\n      await client.command({ query: `RENAME TABLE ${ident(from)} TO ${ident(to)}` })\n      const d = this.#dims.get(from)\n      if (d !== undefined) {\n        this.#dims.set(to, d)\n        this.#dims.delete(from)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const client = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    const values: any[] = []\n    const ids: string[] = []\n    try {\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        ids.push(r.id)\n        values.push({\n          id: r.id,\n          vec: vector,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n        })\n      }\n      // MergeTree allows dupes — delete the ids first (synchronously) so upsert replaces.\n      const idList = ids.map((id) => lit(id)).join(', ')\n      await client.command({\n        query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${idList})`,\n        clickhouse_settings: { mutations_sync: '2' },\n      })\n      await client.insert({\n        table: plan.collection,\n        values,\n        format: 'JSONEachRow',\n      })\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await this.#json(\n          `SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)} LIMIT 1`\n        )\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = rows[0].vec as number[]\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        const distExpr = distanceExpr(metric, vectorLiteral(queryVector))\n        const rows = await this.#json(\n          `SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        filtered.sort((a, b) => Number(a.__dist) - Number(b.__dist))\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await this.#json(\n          `SELECT id, vec, document, metadata FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector) out.vector = (row.vec as number[]).map((n) => Number(n))\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row.__dist !== undefined && row.__dist !== null) {\n      out.score = normalizeScore(Number(row.__dist), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const client = await this.#ensure()\n    const sync = { mutations_sync: '2' as const }\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await client.command({\n          query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,\n          clickhouse_settings: sync,\n        })\n      } else if (plan.filter) {\n        const rows = await this.#json(`SELECT id, metadata FROM ${ident(plan.collection)}`)\n        const targets = rows\n          .filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row) => row.id as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await client.command({\n            query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,\n            clickhouse_settings: sync,\n          })\n        }\n      } else {\n        await client.command({\n          query: `DELETE FROM ${ident(plan.collection)} WHERE 1 = 1`,\n          clickhouse_settings: sync,\n        })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"clickhouse.cjs","names":["#opts","#client","#ensure","#json","#dims","#parseMeta","#project"],"sources":["../../../src/batteries/vector/clickhouse/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/clickhouse\n *\n * ClickHouse adapter. Vectors live in an `Array(Float32)` column; KNN uses ClickHouse's\n * `cosineDistance` / `L2Distance` / negative-inner-product expressions ordered ascending.\n * Metadata is a JSON `String` column, filtered with the neutral filter tree's JS reference\n * evaluator for exact cross-adapter parity. Each collection is a MergeTree table.\n *\n * MergeTree allows duplicate keys, so upsert is delete-then-insert; writes are made\n * read-after-write consistent with `mutations_sync = 2` on deletes.\n *\n * Driver: `@clickhouse/client` (HTTP).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface ClickHouseVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection?: { url?: string; username?: string; password?: string; database?: string }\n}\n\nconst getClickHouseClient = async () => {\n  try {\n    const mod = await import('@clickhouse/client')\n    return mod.createClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@clickhouse/client'])\n  }\n}\n\n// ClickHouse distance expression per metric (all \"lower is closer\" once negated for dot).\nconst distanceExpr = (metric: DistanceMetric, vecLit: string): string =>\n  metric === 'euclidean'\n    ? `L2Distance(vec, ${vecLit})`\n    : metric === 'dot'\n      ? `-arraySum(arrayMap((a, b) -> a * b, vec, ${vecLit}))`\n      : `cosineDistance(vec, ${vecLit})`\n\n// Backtick-quote an identifier, escaping embedded backticks.\nconst ident = (name: string): string => '`' + name.replace(/`/g, '``') + '`'\n\n// Single-quoted ClickHouse string literal.\nconst lit = (value: string): string => `'${value.replace(/\\\\/g, '\\\\\\\\').replace(/'/g, \"\\\\'\")}'`\n\n// number[] → ClickHouse array literal [1, 2, 3].\nconst vectorLiteral = (vector: number[]): string =>\n  `[${vector.map((n) => (Number.isFinite(n) ? String(n) : '0')).join(', ')}]`\n\nexport class ClickHouseVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: true,\n    builtInEncoding: false,\n    // Made strongly consistent via mutations_sync=2 on deletes; writes visible on resolve.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #client: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): ClickHouseVectorStoreOptions {\n    return this.options as ClickHouseVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const createClient = await getClickHouseClient()\n    const c = this.#opts.connection || {}\n    try {\n      this.#client = createClient({\n        url: c.url ?? 'http://localhost:8123',\n        username: c.username ?? 'default',\n        password: c.password ?? '',\n        database: c.database ?? 'default',\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    if (this.#client) {\n      await this.#client.close()\n      this.#client = null\n    }\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#client) await this.connect()\n    return this.#client!\n  }\n\n  async #json(sql: string): Promise<any[]> {\n    const client = await this.#ensure()\n    const rs = await client.query({ query: sql, format: 'JSONEachRow' })\n    return (await rs.json()) as any[]\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await client.command({\n        query:\n          `CREATE TABLE ${ine}${ident(spec.collection)} (` +\n          `id String, vec Array(Float32), document String, metadata String` +\n          `) ENGINE = MergeTree() ORDER BY id`,\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    const ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await client.command({ query: `DROP TABLE ${ie}${ident(collection)}` })\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const rows = await this.#json(`EXISTS TABLE ${ident(collection)}`)\n    return rows.length > 0 && (rows[0].result === 1 || rows[0].result === '1')\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    const client = await this.#ensure()\n    try {\n      await client.command({ query: `RENAME TABLE ${ident(from)} TO ${ident(to)}` })\n      const d = this.#dims.get(from)\n      if (d !== undefined) {\n        this.#dims.set(to, d)\n        this.#dims.delete(from)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const client = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    const values: any[] = []\n    const ids: string[] = []\n    try {\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        ids.push(r.id)\n        values.push({\n          id: r.id,\n          vec: vector,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n        })\n      }\n      // MergeTree allows dupes — delete the ids first (synchronously) so upsert replaces.\n      const idList = ids.map((id) => lit(id)).join(', ')\n      await client.command({\n        query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${idList})`,\n        clickhouse_settings: { mutations_sync: '2' },\n      })\n      await client.insert({\n        table: plan.collection,\n        values,\n        format: 'JSONEachRow',\n      })\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await this.#json(\n          `SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)} LIMIT 1`\n        )\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = rows[0].vec as number[]\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        const distExpr = distanceExpr(metric, vectorLiteral(queryVector))\n        const rows = await this.#json(\n          `SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        filtered.sort((a, b) => Number(a.__dist) - Number(b.__dist))\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await this.#json(\n          `SELECT id, vec, document, metadata FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector) out.vector = (row.vec as number[]).map((n) => Number(n))\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row.__dist !== undefined && row.__dist !== null) {\n      out.score = normalizeScore(Number(row.__dist), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const client = await this.#ensure()\n    const sync = { mutations_sync: '2' as const }\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await client.command({\n          query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,\n          clickhouse_settings: sync,\n        })\n      } else if (plan.filter) {\n        const rows = await this.#json(`SELECT id, metadata FROM ${ident(plan.collection)}`)\n        const targets = rows\n          .filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row) => row.id as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await client.command({\n            query: `DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`,\n            clickhouse_settings: sync,\n          })\n        }\n      } else {\n        await client.command({\n          query: `DELETE FROM ${ident(plan.collection)} WHERE 1 = 1`,\n          clickhouse_settings: sync,\n        })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/clickhouse.mjs

@@ -1,4 +1,4 @@
-import { s as isInstanceOf } from "../../tool_registry-D1pSSlsd.mjs";
+import { s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 import { evaluateFilter } from "./filters.mjs";
 import { normalizeScore } from "./helpers.mjs";
@@ -48,6 +48,7 @@ var ClickHouseVectorStore = class extends BaseVectorStore {
 	get #opts() {
 		return this.options;
 	}
+	/** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
 	static isAvailable() {
 		return typeof process !== "undefined";
 	}