Skip to content
VentureKit

@venturekit-pro/ai

Installation

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


# 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,
});


// chunkText(text, sourceId, ChunkingConfig) — sourceId is required.
const chunks = chunkText(text, 'doc-1', { strategy: 'fixed', chunkSize: 500, chunkOverlap: 50 });
await rag.index(chunks);
const context = await rag.retrieve('query', { topK: 3 });

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?.roles ?? [],
};


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.

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)
Section titled “Related”