@almadar/llm 2.33.0 → 2.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/llm",
-  "version": "2.33.0",
+  "version": "2.35.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,15 +40,16 @@
     "@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"
   },
   "peerDependencies": {
-    "@almadar/core": "^10.29.0"
+    "@almadar/core": "^10.31.0"
   },
   "devDependencies": {
-    "@almadar/core": "^10.29.0",
+    "@almadar/core": "^10.31.0",
     "@almadar/eslint-plugin": "^2.14.0",
     "@types/node": "^22.0.0",
     "@typescript-eslint/parser": "8.56.0",

package/src/client.ts

@@ -189,6 +189,10 @@ export interface LLMUsage {
   promptTokens: number;
   completionTokens: number;
   totalTokens: number;
+  /** Prompt tokens served from the provider's prefix cache (OpenAI-style
+   *  `prompt_tokens_details.cached_tokens`, deepseek-native
+   *  `prompt_cache_hit_tokens`). Absent when the provider reports neither. */
+  cachedPromptTokens?: number;
 }
 
 export type LLMFinishReason =
@@ -217,6 +221,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 +400,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;
 
@@ -1123,20 +1171,23 @@ export class LLMClient {
 
         let usage: LLMUsage | null = null;
         if (parsed.usage) {
+          const rawUsage = parsed.usage as {
+            prompt_tokens_details?: { cached_tokens?: number };
+            prompt_cache_hit_tokens?: number;
+            cost?: number;
+          };
+          const cachedTokens =
+            rawUsage.prompt_tokens_details?.cached_tokens ?? rawUsage.prompt_cache_hit_tokens;
           usage = {
             promptTokens: parsed.usage.prompt_tokens,
             completionTokens: parsed.usage.completion_tokens,
             totalTokens: parsed.usage.total_tokens,
+            ...(cachedTokens !== undefined ? { cachedPromptTokens: cachedTokens } : {}),
           };
           if (this.tokenTracker) {
-            const rawUsage = parsed.usage as {
-              prompt_tokens_details?: { cached_tokens?: number };
-              cost?: number;
-            };
-            const cachedTokens = rawUsage.prompt_tokens_details?.cached_tokens ?? 0;
             this.tokenTracker.addUsage(usage.promptTokens, usage.completionTokens, {
               provider: this.provider,
-              cachedPromptTokens: cachedTokens,
+              cachedPromptTokens: cachedTokens ?? 0,
               // OpenRouter returns the real, routing+cache-adjusted charge here.
               ...(typeof rawUsage.cost === 'number' ? { costUSD: rawUsage.cost } : {}),
             });
@@ -1377,6 +1428,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;
+}