@venturekit-pro/ai API

Functions

Embeddings

Function	Description
`createEmbedder(config)`	Create an embedder for generating vectors
`createEmbeddingConfig(options)`	Create embedding configuration

Embedder interface:

Method	Description
`embed(text: string)`	Generate a single vector
`embedBatch(texts: string[])`	Generate vectors for multiple texts

Vector Stores

Function	Description
`createVectorStore(config)`	Create a vector store instance
`createVectorStoreConfig(options)`	Create vector store configuration

VectorStore interface:

Method	Description
`upsert(items)`	Insert or update vectors
`query(vector, options)`	Query similar vectors

RAG Pipeline

Function	Description
`createRagPipeline(config)`	Create a RAG pipeline
`createRagConfig(options)`	Create RAG configuration
`chunkText(text, options)`	Split text into chunks

RagPipeline interface:

Method	Description
`ingest(chunks)`	Ingest document chunks
`retrieve(query, options)`	Retrieve relevant context

Agents

Function	Description
`createAgent(config)`	Create an AI agent
`createAgentConfig(options)`	Create agent configuration
`defineTool(definition)`	Define a tool for agent use

Agent interface:

Method	Description
`run(prompt)`	Run the agent with a user prompt

Chat completion

Provider-neutral single- or multi-turn completion without tool use, calling each vendor’s REST API directly with fetch() (no SDK peer dependency). One client per (provider, apiKey); the factory switches on provider once, at construction.

import { createChatClient } from '@venturekit-pro/ai';

const chat = createChatClient({ provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY!, timeoutMs: 30_000 });
const result = await chat.complete({
  model: 'claude-sonnet-4-5',
  messages: [{ role: 'system', content: 'Be terse.' }, { role: 'user', content: 'Summarise this…' }],
  maxTokens: 400,
  pricing: { costPer1kInputUsd: 0.003, costPer1kOutputUsd: 0.015 },   // optional — stamps `cost`
});
// result.output, result.usage { promptTokens, completionTokens }, result.cost?.costUsd, result.latencyMs, result.finishReason

Export	Description
`createChatClient(config)`	`ChatClientConfig` is a union discriminated by `provider: 'anthropic' \| 'openai' \| 'google'` (`AnthropicAdapterConfig` / `OpenAiAdapterConfig` / `GoogleAdapterConfig`: `apiKey`, `baseUrl?`, `apiVersion?`, `timeoutMs?`). Returns `ChatCompletionClient` `{ provider, complete(request) }`
`completeWithAnthropic(config, request)` / `completeWithOpenAi(config, request)` / `completeWithGoogle(config, request)`	The per-provider calls underneath
`stampCost(usage, pricing?)`	`CostStamp` `{ costUsd, costMicroUsd, pricing }` or `null` without pricing
`round8(n)`	Round to 8 decimals (USD micro-precision)

ChatCompletionRequest: model, messages (ChatMessage = { role: 'system' \| 'user' \| 'assistant', content }), maxTokens?, temperature?, topP?, stop?, pricing?, idempotencyKey? (forwarded to Anthropic and OpenAI; the retry layer sets one so a retried call is not double-charged). ChatCompletionResult: output, provider, model, usage (ChatTokenUsage), cost, latencyMs, finishReason.

Image generation

Export	Description
`createImageClient({ provider: 'google', … })`	`ImageGenerationClient` — `generate({ model, prompt, aspectRatio? })` → `{ images: [{ bytes, mimeType }], provider, model, latencyMs }`. `ImageAspectRatio` is `'1:1' \| '4:3' \| '16:9' \| '9:16'`; Google Imagen is the only provider today
`generateWithGoogleImagen(config, request)`	The raw Imagen call

Model catalog & cost estimation

Export	Description
`createModelCatalog(rows)`	In-memory `ModelCatalog` over `ModelDescriptor[]` (`key`, `provider`, `model`, `displayName`, `status`, pricing) — `list()`, `find(key)`, `resolve(key)` (throws), `available()`, `withStatus(status)`
`estimateTokens(text)`	~`length / 4`
`estimateCost({ promptText, expectedCompletionTokens?, pricing? })`	`CostEstimate` `{ promptTokens, completionTokens, costUsd }` (`costUsd` null without pricing)
`estimateCostForModel(promptText, expectedCompletionTokens, model)`	Same, reading pricing from a `ModelDescriptor`

Database-backed catalog (vk_llm_models, migration shipped with the package): listModels(q), getModelByKey(q, key), createModel(q, input), patchModel(q, key, patch), isLlmModelUniqueViolation(err), isLlmModelForeignKeyViolation(err). LlmModelRow carries key, provider, model, displayName, description, status (LlmModelStatus), replacementKey, contextWindow, maxOutputTokens, supportsJsonMode, supportsImageInput, pricing and a default timeout.

Prompt templates

Operator-editable prompts as data, with {{variable}} interpolation:

Export	Description
`renderTemplate(template, ctx)`	`RenderResult` `{ output, referenced, unresolved }`
`renderPromptTemplate(tpl, ctx, { strict? })`	Render a `PromptTemplate` (`id`, `version`, `name`, `template`, `variables: PromptVariable[]`) — applies `defaultValue`s, and with `strict` throws on unresolved required variables
`promptContentHash(tpl)`	Stable hash of template + variables, for audit rows and cache keys

Retry & fallback

Export	Description
`retryWithBackoff(fn, { maxAttempts?, initialDelayMs?, backoffFactor?, maxDelayMs?, shouldRetry? })`	Exponential backoff around `fn(attempt)`
`isRetryableError(err)`	Rate limits, 5xx, timeouts, network errors
`withFallback({ primary, backup, shouldFallback? })`	Run `primary()`, fall back to `backup()` on retryable errors — e.g. an Anthropic client with an OpenAI backup

LLM cost ledger

llm_cost_events — token usage and USD cost per LLM call, distinct from @venturekit-pro/audit’s audit_events; apps using both link the tables via correlationId. Migrations (vk_ai_cost_000N_*.sql) ship in the package’s vk.migrations directory and are auto-applied by vk migrate; getAiCostMigrationsDir() is the explicit escape hatch.

import { recordLlmCost, rollupCostWindow } from '@venturekit-pro/ai';

await recordLlmCost(query, {
  tenantId, source: 'persona.reply', target: { type: 'conversation', id: conv.id },
  provider: result.provider, model: result.model,
  tokensIn: result.usage.promptTokens, tokensOut: result.usage.completionTokens,
  costUsd: result.cost?.costUsd ?? null, costMicroUsd: result.cost?.costMicroUsd ?? null,
  latencyMs: result.latencyMs, correlationId: runId, idempotencyKey: `${runId}/reply`,
});

const rollup = await rollupCostWindow(query, { tenantId, windowKey: '30d' });
// rollup.totals { costUsd, calls, tokensIn, tokensOut }, rollup.prevTotals, rollup.byModel, rollup.bySource

Export	Description
`recordLlmCost(q, input)`	Append one `LlmCostEvent` (`LlmCostInput` above; `idempotencyKey` makes retries safe)
`listLlmCosts(q, args)`	Filtered list (`ListLlmCostsArgs`)
`llmCostByTarget(q, args)` / `llmCostByCorrelation(q, args)` / `llmCostByTenant(q, args)`	Totals per target, per operation, per tenant
`llmCostByMonth(q, args)`	`LlmMonthlyCostBucket[]`
`computeWindows(key, now?)`	`CostWindowKey` (`'7d' \| '30d' \| '90d' \| 'ytd'`) → current + previous `CostWindowRange`
`rollupCostWindow(q, { tenantId, windowKey, now? })`	`CostRollupResult` — `window`, `prevWindow`, `totals`, `prevTotals`, `byModel`, `bySource`

Types

AI-related types are exported from ./types/index.js, including embedding configs, vector store configs, RAG configs, agent configs, and tool definitions. Chat, image, catalog, prompt, fallback and ledger types are listed with their sections above.

Constants

Constant	Description
`DEFAULT_EMBEDDING_CONFIG`	Default embedding configuration
`DEFAULT_VECTOR_STORE_CONFIG`	Default vector store configuration
`DEFAULT_RAG_CONFIG`	Default RAG configuration
`DEFAULT_AGENT_CONFIG`	Default agent configuration