@almadar/llm 2.33.0 → 2.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/llm",
-  "version": "2.33.0",
+  "version": "2.34.0",
   "description": "Multi-provider LLM client with rate limiting, token tracking, structured outputs, and continuation handling",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,10 @@
     "./providers": {
       "types": "./dist/providers/index.d.ts",
       "import": "./dist/providers/index.js"
+    },
+    "./vector": {
+      "types": "./dist/vector/index.d.ts",
+      "import": "./dist/vector/index.js"
     }
   },
   "files": [
@@ -36,6 +40,7 @@
     "@langchain/anthropic": "^1.3.23",
     "@langchain/core": "^1.1.32",
     "@langchain/openai": "^1.2.13",
+    "chromadb": "^3.1.0",
     "openai": "^6.18.0",
     "zod": "^3.22.0",
     "@almadar/logger": "^1.9.0"

package/src/client.ts

@@ -217,6 +217,49 @@ export interface LLMStreamChunk {
   done: boolean;
 }
 
+// ============================================================================
+// Vision (Anthropic image content-parts)
+// ============================================================================
+
+/** Media types the Anthropic base64 image source accepts. */
+export type VisionImageMediaType = Anthropic.Base64ImageSource['media_type'];
+
+/** A single image sent as a base64 content-part (no `data:` URI prefix). */
+export interface VisionImagePart {
+  base64: string;
+  mediaType: VisionImageMediaType;
+}
+
+export interface VisionCallOptions<T = string> {
+  systemPrompt?: string;
+  userText: string;
+  images: ReadonlyArray<VisionImagePart>;
+  /** Zod schema for structured JSON output — reuses the package's `parseJsonResponse` mechanism. */
+  schema?: z.ZodSchema<T>;
+  maxTokens?: number;
+  temperature?: number;
+  skipSchemaValidation?: boolean;
+  signal?: AbortSignal;
+}
+
+/**
+ * Build the Anthropic user-message content array for a vision call: one text
+ * block followed by one image block per screenshot, grounded entirely in the
+ * SDK's own typed shapes. Pure and side-effect-free so it can be unit-tested
+ * without any API call.
+ */
+export function buildVisionMessageContent(
+  userText: string,
+  images: ReadonlyArray<VisionImagePart>,
+): Anthropic.ContentBlockParam[] {
+  const textBlock: Anthropic.TextBlockParam = { type: 'text', text: userText };
+  const imageBlocks: Anthropic.ImageBlockParam[] = images.map((img) => ({
+    type: 'image',
+    source: { type: 'base64', media_type: img.mediaType, data: img.base64 },
+  }));
+  return [textBlock, ...imageBlocks];
+}
+
 // ============================================================================
 // Provider Configuration
 // ============================================================================
@@ -353,6 +396,7 @@ export const ANTHROPIC_MODELS = {
   CLAUDE_SONNET_4_5: 'claude-sonnet-4-5-20250929',
   CLAUDE_SONNET_4: 'claude-sonnet-4-20250514',
   CLAUDE_OPUS_4_5: 'claude-opus-4-5-20250929',
+  CLAUDE_HAIKU_4_5: 'claude-haiku-4-5',
   CLAUDE_3_5_HAIKU: 'claude-3-5-haiku-20241022',
 } as const;
 
@@ -1377,6 +1421,94 @@ export class LLMClient {
     throw lastError;
   }
 
+  /**
+   * Send one or more images (base64 content-parts) plus a text prompt to a
+   * vision-capable Anthropic model and return the response. When a `schema`
+   * is supplied the text output is parsed and validated through the package's
+   * `parseJsonResponse` mechanism; otherwise the raw text is returned as `T`.
+   *
+   * Anthropic-only — image content-parts use the native messages API. Other
+   * providers throw (mirrors `callWithTools`).
+   */
+  async callWithVision<T = string>(
+    options: VisionCallOptions<T>,
+  ): Promise<LLMResponse<T>> {
+    if (this.provider !== 'anthropic') {
+      throw new Error(
+        `LLMClient.callWithVision: vision is only supported on the anthropic provider (got ${this.provider})`,
+      );
+    }
+
+    const {
+      systemPrompt,
+      userText,
+      images,
+      schema,
+      maxTokens,
+      temperature,
+      skipSchemaValidation = false,
+      signal,
+    } = options;
+
+    if (images.length === 0) {
+      throw new Error('LLMClient.callWithVision: at least one image is required');
+    }
+
+    return this.rateLimiter.execute(async () => {
+      const anthropic = new Anthropic({ apiKey: this.providerConfig.apiKey });
+      const content = buildVisionMessageContent(userText, images);
+      const messages: Anthropic.MessageParam[] = [{ role: 'user', content }];
+
+      log.info(
+        `[LLMClient:callWithVision] Invoking ${this.provider}/${this.modelName} (images=${images.length})`,
+      );
+
+      const response = await anthropic.messages.create(
+        {
+          model: this.modelName,
+          max_tokens: maxTokens ?? 4096,
+          temperature: temperature ?? 0,
+          ...(systemPrompt ? { system: systemPrompt } : {}),
+          messages,
+        },
+        signal ? { signal } : {},
+      );
+
+      const textContent = response.content.find((c) => c.type === 'text');
+      const rawText =
+        textContent && 'text' in textContent ? textContent.text : '';
+
+      const apiUsage = response.usage;
+      const usage: LLMUsage = {
+        promptTokens: apiUsage.input_tokens,
+        completionTokens: apiUsage.output_tokens,
+        totalTokens: apiUsage.input_tokens + apiUsage.output_tokens,
+      };
+      if (this.tokenTracker) {
+        this.tokenTracker.addUsage(usage.promptTokens, usage.completionTokens, {
+          provider: this.provider,
+        });
+      }
+
+      const finishReason: LLMFinishReason =
+        response.stop_reason === 'end_turn'
+          ? 'stop'
+          : response.stop_reason === 'max_tokens'
+            ? 'length'
+            : response.stop_reason === 'tool_use'
+              ? 'tool_calls'
+              : null;
+
+      const data: T = skipSchemaValidation
+        ? parseJsonResponse<T>(rawText, undefined)
+        : schema
+          ? parseJsonResponse<T>(rawText, schema)
+          : asGeneric<T>(rawText);
+
+      return { data, raw: rawText, finishReason, usage };
+    });
+  }
+
   static cacheableBlock(text: string, cache = true): CacheableBlock {
     return cache
       ? { type: 'text', text, cache_control: { type: 'ephemeral' } }

package/src/index.ts

@@ -22,6 +22,7 @@ export {
   createZhipuClient,
   getAvailableProvider,
   isProviderAvailable,
+  buildVisionMessageContent,
   DEEPSEEK_MODELS,
   OPENAI_MODELS,
   ANTHROPIC_MODELS,
@@ -38,6 +39,9 @@ export {
   type CacheAwareLLMCallOptions,
   type LLMStreamOptions,
   type LLMStreamChunk,
+  type VisionImageMediaType,
+  type VisionImagePart,
+  type VisionCallOptions,
 } from './client.js';
 
 export {

package/src/vector/collection.ts

@@ -0,0 +1,161 @@
+/**
+ * VectorCollection — thin wrapper over a live chromadb `Collection`: batched
+ * writes, query shaping, and space/metadata read-through. Mechanics only —
+ * callers own retry/best-effort policy, so failures propagate as rejections
+ * here (unlike the connect/collection-resolution seams, which never throw).
+ */
+import type * as Chroma from 'chromadb';
+import { normalizeVectorTopK, shapeVectorHits, type VectorHit } from './shape.js';
+
+export interface VectorRecords {
+  ids: readonly string[];
+  embeddings: readonly (readonly number[])[];
+  documents?: readonly string[];
+  metadatas?: readonly Chroma.Metadata[];
+}
+
+export interface VectorQueryOptions {
+  embedding: readonly number[];
+  topK?: number;
+  where?: Chroma.Where;
+  includeDocuments?: boolean;
+  includeMetadatas?: boolean;
+}
+
+export interface VectorDeleteTarget {
+  ids?: readonly string[];
+  where?: Chroma.Where;
+}
+
+export interface VectorGetOptions {
+  where?: Chroma.Where;
+  /** Default true. */
+  includeMetadatas?: boolean;
+  /** Default false — privacy default: raw node text is never returned unless explicitly asked for. */
+  includeDocuments?: boolean;
+  limit?: number;
+}
+
+export interface VectorRecord {
+  id: string;
+  metadata?: Chroma.Metadata | undefined;
+  document?: string | undefined;
+}
+
+export interface VectorCollection {
+  upsert(records: VectorRecords): Promise<number>;
+  add(records: VectorRecords): Promise<number>;
+  query(opts: VectorQueryOptions): Promise<VectorHit[]>;
+  /** Fetch records by metadata filter (no embedding / no similarity). Defaults to metadatas-only. */
+  get(opts?: VectorGetOptions): Promise<VectorRecord[]>;
+  delete(target: VectorDeleteTarget): Promise<void>;
+  count(): Promise<number>;
+  /** Every id in the collection (paged get, vectors not fetched) — backs mirror-sync reconciliation. */
+  listIds(): Promise<string[]>;
+  readonly metadata: Chroma.CollectionMetadata | undefined;
+  readonly space: string | null;
+}
+
+const WRITE_BATCH_SIZE = 500;
+
+interface WriteBatch {
+  ids: string[];
+  embeddings: number[][];
+  documents?: string[];
+  metadatas?: Chroma.Metadata[];
+}
+
+async function writeInBatches(
+  write: (batch: WriteBatch) => Promise<void>,
+  records: VectorRecords,
+): Promise<number> {
+  const { ids, embeddings, documents, metadatas } = records;
+  let written = 0;
+  for (let start = 0; start < ids.length; start += WRITE_BATCH_SIZE) {
+    const end = Math.min(start + WRITE_BATCH_SIZE, ids.length);
+    await write({
+      ids: ids.slice(start, end),
+      embeddings: embeddings.slice(start, end).map((vec) => [...vec]),
+      ...(documents ? { documents: documents.slice(start, end) } : {}),
+      ...(metadatas ? { metadatas: metadatas.slice(start, end) } : {}),
+    });
+    written += end - start;
+  }
+  return written;
+}
+
+export function wrapVectorCollection(raw: Chroma.Collection): VectorCollection {
+  return {
+    upsert(records) {
+      return writeInBatches((batch) => raw.upsert(batch), records);
+    },
+    add(records) {
+      return writeInBatches((batch) => raw.add(batch), records);
+    },
+    async query(opts) {
+      const include: Array<'distances' | 'metadatas' | 'documents'> = ['distances'];
+      if (opts.includeMetadatas) include.push('metadatas');
+      if (opts.includeDocuments) include.push('documents');
+      const result = await raw.query({
+        queryEmbeddings: [[...opts.embedding]],
+        nResults: normalizeVectorTopK(opts.topK),
+        where: opts.where,
+        include,
+      });
+      return shapeVectorHits(result);
+    },
+    async delete(target) {
+      await raw.delete({
+        ...(target.ids ? { ids: [...target.ids] } : {}),
+        ...(target.where ? { where: target.where } : {}),
+      });
+    },
+    async get(opts = {}) {
+      const include: Array<'metadatas' | 'documents'> = [];
+      if (opts.includeMetadatas !== false) include.push('metadatas');
+      if (opts.includeDocuments) include.push('documents');
+      const records: VectorRecord[] = [];
+      const PAGE = 10_000;
+      const hardLimit = opts.limit ?? Number.MAX_SAFE_INTEGER;
+      for (let offset = 0; offset < hardLimit; offset += PAGE) {
+        const pageLimit = Math.min(PAGE, hardLimit - offset);
+        const page = await raw.get({
+          ...(opts.where ? { where: opts.where } : {}),
+          include,
+          limit: pageLimit,
+          offset,
+        });
+        const wantMeta = include.includes('metadatas');
+        const wantDoc = include.includes('documents');
+        for (let i = 0; i < page.ids.length; i++) {
+          records.push({
+            id: page.ids[i],
+            ...(wantMeta ? { metadata: page.metadatas?.[i] ?? undefined } : {}),
+            ...(wantDoc ? { document: page.documents?.[i] ?? undefined } : {}),
+          });
+        }
+        if (page.ids.length < pageLimit) break;
+      }
+      return records;
+    },
+    count() {
+      return raw.count();
+    },
+    async listIds() {
+      const ids: string[] = [];
+      const PAGE = 10_000;
+      for (let offset = 0; ; offset += PAGE) {
+        const page = await raw.get({ include: [], limit: PAGE, offset });
+        ids.push(...page.ids);
+        if (page.ids.length < PAGE) break;
+      }
+      return ids;
+    },
+    get metadata() {
+      return raw.metadata;
+    },
+    get space() {
+      return raw.configuration.hnsw?.space ?? null;
+    },
+  };
+}

package/src/vector/env.ts

@@ -0,0 +1,45 @@
+/**
+ * Vector-store env resolution + host parsing — pure seams, no chromadb import.
+ */
+
+export interface VectorStoreConfig {
+  host?: string;
+  apiKey?: string;
+  tenant?: string;
+  database?: string;
+}
+
+function cleanEnvValue(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function resolveVectorStoreEnv(): VectorStoreConfig {
+  const env = process.env;
+  return {
+    host: cleanEnvValue(env.ALMADAR_CHROMA_HOST),
+    apiKey: cleanEnvValue(env.ALMADAR_CHROMA_API_KEY),
+    tenant: cleanEnvValue(env.ALMADAR_CHROMA_TENANT),
+    database: cleanEnvValue(env.ALMADAR_CHROMA_DATABASE),
+  };
+}
+
+export interface VectorHostInit {
+  host?: string;
+  port?: number;
+  ssl?: boolean;
+}
+
+/** Parse a bare host or full URL into chromadb client args: bare host ⇒ port 8000, https default 443. */
+export function parseVectorHost(host: string): VectorHostInit {
+  const init: VectorHostInit = {};
+  try {
+    const url = new URL(host.includes('://') ? host : `http://${host}`);
+    init.host = url.hostname;
+    init.port = url.port ? parseInt(url.port, 10) : url.protocol === 'https:' ? 443 : 8000;
+    init.ssl = url.protocol === 'https:';
+  } catch {
+    init.host = host;
+  }
+  return init;
+}

package/src/vector/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @almadar/llm/vector
+ *
+ * Shared Chroma vector-store client seam: env resolution, connect + cache,
+ * collection resolution with a space-mismatch guard, and query-result
+ * shaping. Mechanics only — it never embeds (`EmbeddingClient` is its
+ * sibling in this package), never names collections, and applies no domain
+ * policy beyond what a call site's `VectorCollectionSpec` declares.
+ *
+ * @packageDocumentation
+ */
+
+export { resolveVectorStoreEnv, parseVectorHost, type VectorStoreConfig } from './env.js';
+
+export {
+  connectVectorStore,
+  resetVectorStoreCache,
+  type VectorStoreHandle,
+  type VectorCollectionSpec,
+} from './store.js';
+
+export { type VectorCollection, type VectorRecords, type VectorQueryOptions, type VectorGetOptions, type VectorRecord } from './collection.js';
+
+export { type VectorHit } from './shape.js';
+
+export type { Where, Metadata } from 'chromadb';

package/src/vector/shape.ts

@@ -0,0 +1,60 @@
+/**
+ * Query-result shaping — pure seams, no chromadb import (types only, erased).
+ */
+import type * as Chroma from 'chromadb';
+
+export interface VectorHit {
+  id: string;
+  distance: number;
+  score: number;
+  metadata?: Chroma.Metadata;
+  document?: string;
+}
+
+const DEFAULT_QUERY_TOP_K = 10;
+
+export function normalizeVectorTopK(topK: number | undefined): number {
+  if (typeof topK !== 'number' || !Number.isFinite(topK) || topK <= 0) return DEFAULT_QUERY_TOP_K;
+  return Math.floor(topK);
+}
+
+function clamp01(value: number): number {
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+/** Structural subset of chromadb's `QueryResult` this module reads (pure-shaping seam). */
+export interface VectorQueryResultLike {
+  readonly ids: ReadonlyArray<ReadonlyArray<string>>;
+  readonly distances: ReadonlyArray<ReadonlyArray<number | null>>;
+  readonly metadatas?: ReadonlyArray<ReadonlyArray<Chroma.Metadata | null>>;
+  readonly documents?: ReadonlyArray<ReadonlyArray<string | null>>;
+}
+
+export function shapeVectorHits(result: VectorQueryResultLike): VectorHit[] {
+  const ids = result.ids[0] ?? [];
+  const distances = result.distances[0] ?? [];
+  const metadatas = result.metadatas?.[0] ?? [];
+  const documents = result.documents?.[0] ?? [];
+  const hits: VectorHit[] = [];
+  for (let i = 0; i < ids.length; i++) {
+    const id = ids[i];
+    if (typeof id !== 'string') continue;
+    const rawDistance = distances[i];
+    // a missing/null distance is the worst case (no similarity signal) — treat as 1, same as rabit's shapeChromaMatches.
+    const distance = typeof rawDistance === 'number' ? rawDistance : 1;
+    const score = clamp01(1 - distance);
+    const metadata = metadatas[i];
+    const document = documents[i];
+    hits.push({
+      id,
+      distance,
+      score,
+      ...(metadata ? { metadata } : {}),
+      ...(typeof document === 'string' ? { document } : {}),
+    });
+  }
+  hits.sort((a, b) => b.score - a.score);
+  return hits;
+}

package/src/vector/store.ts

@@ -0,0 +1,193 @@
+/**
+ * Vector-store connection + collection resolution: env → chromadb client
+ * (cached per process, per distinct config), plus the space-mismatch policy
+ * that guards a `collection()` call from silently ranking/writing under the
+ * wrong index space.
+ */
+import type * as Chroma from 'chromadb';
+import { createLogger } from '@almadar/logger';
+import type { VectorStoreConfig } from './env.js';
+import { parseVectorHost } from './env.js';
+import { wrapVectorCollection, type VectorCollection } from './collection.js';
+
+const vectorLog = createLogger('almadar:llm:vector');
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export type VectorSpace = 'cosine' | 'l2' | 'ip';
+
+export interface VectorCollectionSpec {
+  name: string;
+  space?: VectorSpace;
+  metadata?: Chroma.CollectionMetadata;
+  /** 'recreate' drops + rebuilds a wrong-space collection (derived/rebuildable data only). Default 'reject' never auto-drops a consumer's data. */
+  onSpaceMismatch?: 'recreate' | 'reject';
+}
+
+export interface VectorStoreHandle {
+  /** Human-readable connection target, for logs. */
+  readonly target: string;
+  collection(spec: VectorCollectionSpec): Promise<VectorCollection | null>;
+  getCollection(name: string): Promise<VectorCollection | null>;
+  deleteCollection(name: string): Promise<boolean>;
+  heartbeat(): Promise<boolean>;
+}
+
+const stubEmbeddingFunction: Chroma.EmbeddingFunction = {
+  // Callers always supply pre-computed vectors; the stub stops chromadb from
+  // instantiating its own DefaultEmbeddingFunction.
+  generate: async () => [],
+};
+
+const DEFAULT_ON_SPACE_MISMATCH = 'reject';
+
+function isEmptyConfig(config: VectorStoreConfig): boolean {
+  return !config.host && !config.apiKey;
+}
+
+function configCacheKey(config: VectorStoreConfig): string {
+  return JSON.stringify([config.host ?? null, config.apiKey ?? null, config.tenant ?? null, config.database ?? null]);
+}
+
+async function loadChromaModule(): Promise<typeof import('chromadb') | null> {
+  try {
+    return await import('chromadb');
+  } catch (err) {
+    vectorLog.warn('store:module-missing', () => ({
+      error: errorMessage(err),
+      hint: 'add chromadb to dependencies and run pnpm install',
+    }));
+    return null;
+  }
+}
+
+async function resolveCollection(
+  client: Chroma.ChromaClient,
+  spec: VectorCollectionSpec,
+): Promise<VectorCollection | null> {
+  const create = (): Promise<Chroma.Collection> =>
+    client.getOrCreateCollection({
+      name: spec.name,
+      embeddingFunction: stubEmbeddingFunction,
+      ...(spec.space ? { configuration: { hnsw: { space: spec.space } } } : {}),
+      ...(spec.metadata ? { metadata: spec.metadata } : {}),
+    });
+
+  let raw: Chroma.Collection;
+  try {
+    raw = await create();
+  } catch (err) {
+    vectorLog.warn('collection:create-failed', () => ({ name: spec.name, error: errorMessage(err) }));
+    return null;
+  }
+
+  // spec.space omitted ⇒ no verification, server default on create.
+  if (!spec.space) return wrapVectorCollection(raw);
+
+  const foundSpace = raw.configuration.hnsw?.space ?? null;
+  if (foundSpace === spec.space) return wrapVectorCollection(raw);
+
+  const policy = spec.onSpaceMismatch ?? DEFAULT_ON_SPACE_MISMATCH;
+  if (policy === 'reject') {
+    vectorLog.warn('collection:space-mismatch', () => ({
+      name: spec.name,
+      declaredSpace: spec.space,
+      foundSpace,
+      policy,
+    }));
+    return null;
+  }
+
+  vectorLog.warn('collection:space-heal', () => ({ name: spec.name, declaredSpace: spec.space, foundSpace }));
+  await client.deleteCollection({ name: spec.name });
+  try {
+    raw = await create();
+  } catch (err) {
+    vectorLog.warn('collection:create-failed', () => ({ name: spec.name, error: errorMessage(err) }));
+    return null;
+  }
+  return wrapVectorCollection(raw);
+}
+
+function buildVectorStoreHandle(client: Chroma.ChromaClient, target: string): VectorStoreHandle {
+  return {
+    target,
+    collection(spec) {
+      return resolveCollection(client, spec);
+    },
+    async getCollection(name) {
+      try {
+        const raw = await client.getCollection({ name, embeddingFunction: stubEmbeddingFunction });
+        return wrapVectorCollection(raw);
+      } catch (err) {
+        vectorLog.debug('collection:get-missing', () => ({ name, error: errorMessage(err) }));
+        return null;
+      }
+    },
+    async deleteCollection(name) {
+      try {
+        await client.deleteCollection({ name });
+        return true;
+      } catch (err) {
+        vectorLog.warn('collection:delete-failed', () => ({ name, error: errorMessage(err) }));
+        return false;
+      }
+    },
+    async heartbeat() {
+      try {
+        await client.heartbeat();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+const vectorStoreCache = new Map<string, VectorStoreHandle>();
+
+/** Test-only reset — clears the per-process handle cache between cases. */
+export function resetVectorStoreCache(): void {
+  vectorStoreCache.clear();
+}
+
+export async function connectVectorStore(config: VectorStoreConfig): Promise<VectorStoreHandle | null> {
+  if (isEmptyConfig(config)) {
+    vectorLog.debug('store:skip', () => ({ reason: 'config-empty' }));
+    return null;
+  }
+
+  const key = configCacheKey(config);
+  const cached = vectorStoreCache.get(key);
+  if (cached) return cached;
+
+  const mod = await loadChromaModule();
+  if (!mod) return null;
+
+  let client: Chroma.ChromaClient;
+  let target: string;
+  if (config.apiKey) {
+    client = new mod.CloudClient({ apiKey: config.apiKey, tenant: config.tenant, database: config.database });
+    target = `cloud(tenant=${config.tenant ?? 'default'}, db=${config.database ?? 'default'})`;
+  } else if (config.host) {
+    client = new mod.ChromaClient(parseVectorHost(config.host));
+    target = config.host;
+  } else {
+    // unreachable: isEmptyConfig already guards host/apiKey both absent.
+    return null;
+  }
+
+  try {
+    await client.heartbeat();
+  } catch (err) {
+    vectorLog.warn('store:heartbeat-failed', () => ({ target, error: errorMessage(err) }));
+    return null;
+  }
+
+  const handle = buildVectorStoreHandle(client, target);
+  vectorStoreCache.set(key, handle);
+  vectorLog.info('store:ready', () => ({ target }));
+  return handle;
+}