Skip to content
VentureKit

@venturekit-pro/ai

Installation

Section titled “Installation”
Terminal window
npm install @venturekit-pro/ai


# Install providers you need
npm install openai                          # OpenAI
npm install @aws-sdk/client-bedrock-runtime # AWS Bedrock
npm install @pinecone-database/pinecone     # Pinecone

What It Provides

Section titled “What It Provides”

Embeddings

Section titled “Embeddings”
import { createEmbedder, createEmbeddingConfig, DEFAULT_EMBEDDING_CONFIG } from '@venturekit-pro/ai';


const embedder = createEmbedder({
  provider: 'openai',
  model: 'text-embedding-3-small',
  apiKey: process.env.OPENAI_API_KEY!,
});


// embed() returns { embedding, tokensUsed?, model } — destructure to get the vector.
const { embedding } = await embedder.embed('Hello world');

Vector Stores

Section titled “Vector Stores”
import { createVectorStore, createVectorStoreConfig, DEFAULT_VECTOR_STORE_CONFIG } from '@venturekit-pro/ai';


// Provider config is nested under the provider's key. `dimensions` is required
// (1536 for OpenAI text-embedding-3-small, 3072 for text-embedding-3-large).
const store = createVectorStore({
  provider: 'pinecone',
  indexName: 'my-index',
  dimensions: 1536,
  pinecone: { apiKey: process.env.PINECONE_API_KEY! },
});


// `Vector` is `{ id, values, metadata? }` — note the field is `values`, not `vector`.
await store.upsert([{ id: 'doc-1', values: embedding, metadata: {} }]);
// `search()` takes a `VectorQuery` object — `{ vector, topK, includeMetadata?, filter?, minScore? }`.
const results = await store.search({ vector: embedding, topK: 5 });

RAG Pipeline

Section titled “RAG Pipeline”
import { createRagPipeline, createRagConfig, DEFAULT_RAG_CONFIG, chunkText } from '@venturekit-pro/ai';


const rag = createRagPipeline({
  embedding: { provider: 'openai', model: 'text-embedding-3-small', apiKey: process.env.OPENAI_API_KEY! },
  vectorStore: { provider: 'pinecone', indexName: 'my-index', dimensions: 1536, pinecone: { apiKey: process.env.PINECONE_API_KEY! } },
  chunking: { strategy: 'fixed', chunkSize: 500, chunkOverlap: 50 },
  topK: 3,
});


// index() takes raw documents — it chunks each one internally using the
// pipeline's `chunking` config, then embeds and upserts them.
await rag.index([{ id: 'doc-1', content: text, metadata: { title: 'Intro' } }]);


// retrieve() returns a RetrievedContext: { chunks, context, totalChunks }.
const { context } = await rag.retrieve('query', { topK: 3 });


// chunkText(text, sourceId, ChunkingConfig) is also exported for manual chunking
// when writing to a VectorStore directly instead of through the pipeline.
const chunks = chunkText(text, 'doc-1', { strategy: 'fixed', chunkSize: 500, chunkOverlap: 50 });

Agents

Section titled “Agents”
import { createAgent, createAgentConfig, DEFAULT_AGENT_CONFIG, defineTool } from '@venturekit-pro/ai';


const tool = defineTool({
  name: 'search',
  description: 'Search the knowledge base',
  parameters: { type: 'object', properties: {}, required: [] },
  execute: async () => ({}),
});


const agent = createAgent({
  provider: 'openai',
  model: 'gpt-4',
  apiKey: process.env.OPENAI_API_KEY!,
  tools: [tool],
  systemPrompt: '...',
});


const response = await agent.run('question');

Tenant- & Permission-Aware AI

Section titled “Tenant- & Permission-Aware AI”

A thin layer on top of agents and RAG that scopes every operation to a tenant (plus optional per-action permission checks). The wrapper folds tenant + user + roles into the system prompt and into the metadata filter passed to the vector store on every retrieval — so multi-tenant SaaS apps cannot accidentally leak context across tenants.

import {
  createContextAwareAgent,
  createContextAwareRag,
  buildContextPrompt,
  tenantFilter,
} from '@venturekit-pro/ai';
import type { VentureKitAIContext, PermissionCheck } from '@venturekit-pro/ai';


const aiCtx: VentureKitAIContext = {
  tenantId: ctx.tenant!.id,
  userId: ctx.user?.id,
  roles: (ctx.user?.claims?.roles as string[] | undefined) ?? [],
};


const checkPermission: PermissionCheck = async (c, action) =>
  c.roles.includes('admin') || action === 'read';


// Agent scoped to this tenant — system prompt is auto-suffixed with
// `[Context: tenant=<id>, user=<id>, roles=<a,b,c>]`.
const agent = createContextAwareAgent(aiCtx, {
  provider: 'openai',
  model: 'gpt-4o-mini',
  apiKey: process.env.OPENAI_API_KEY!,
  systemPrompt: 'You are a helpful assistant.',
  permissionCheck: checkPermission,
});


// RAG that auto-applies `tenantFilter(aiCtx.tenantId)` to every search.
const rag = createContextAwareRag(aiCtx, {
  embedding: { provider: 'openai', model: 'text-embedding-3-small', apiKey: process.env.OPENAI_API_KEY! },
  vectorStore: { provider: 'pinecone', indexName: 'docs', dimensions: 1536, pinecone: { apiKey: process.env.PINECONE_API_KEY! } },
  chunking: { strategy: 'fixed', chunkSize: 500, chunkOverlap: 50 },
  topK: 3,
});

The exported helpers buildContextPrompt(ctx) and tenantFilter(tenantId, extra?) are also available directly if you need to attach VentureKit context to a plain createAgent / createRagPipeline call instead of using the wrappers.

Chat Completion & Fallback

Section titled “Chat Completion & Fallback”

Provider-neutral completion (Anthropic, OpenAI, Google) without tool use — implemented over each vendor’s REST API with fetch(), so no SDK peer is needed — with a retry/backup layer:

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


const anthropic = createChatClient({ provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY! });
const openai = createChatClient({ provider: 'openai', apiKey: process.env.OPENAI_API_KEY! });


const request = { model: 'claude-sonnet-4-5', messages: [{ role: 'user' as const, content: prompt }], maxTokens: 500 };
const result = await withFallback({
  primary: () => retryWithBackoff(() => anthropic.complete(request), { maxAttempts: 3 }),
  backup: () => openai.complete({ ...request, model: 'gpt-4o-mini' }),
});
// result.output, result.usage, result.cost (when `pricing` was passed), result.latencyMs

Images, Prompts & Cost

Section titled “Images, Prompts & Cost”
  • Images — createImageClient({ provider: 'google', … }).generate({ model, prompt, aspectRatio }) returns raw bytes (Imagen).
  • Prompt templates — renderPromptTemplate(tpl, ctx) renders operator-editable {{variable}} templates with typed variables; promptContentHash(tpl) pins the version used in audit rows.
  • Cost estimation — estimateCost({ promptText, expectedCompletionTokens, pricing }) before a call; createModelCatalog(rows) for an in-memory model registry, or the vk_llm_models table via listModels / createModel / patchModel.
  • Cost ledger — recordLlmCost(query, { tenantId, source, provider, model, tokensIn, tokensOut, costUsd, … }) writes to llm_cost_events; rollupCostWindow(query, { tenantId, windowKey: '30d' }) gives totals, previous-window comparison, and per-model / per-source breakdowns. Migrations ship with the package and are auto-applied by vk migrate.

See the API reference for every signature.

Dependencies

Section titled “Dependencies”
  • @venturekit/core — required
  • openai — optional peer (embeddings, agents)
  • @aws-sdk/client-bedrock-runtime — optional peer (Bedrock embeddings)
  • @pinecone-database/pinecone — optional peer (Pinecone vector store)
  • @venturekit/data — optional (query for the cost ledger and model catalog)
Section titled “Related”