AI

VentureKit provides AI capabilities through @venturekit-pro/ai with embeddings, vector stores, RAG pipelines, and agents with tool use.

Setup

npm install @venturekit-pro/ai@dev

# Install provider(s) you need
npm install openai                          # OpenAI embeddings + agents
npm install @aws-sdk/client-bedrock-runtime # AWS Bedrock embeddings
npm install @pinecone-database/pinecone     # Pinecone vector store

Embeddings

Generate vector embeddings from text:

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

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

// embed() returns an EmbeddingResult — the vector lives at `.embedding`.
const { embedding } = await embedder.embed('What is VentureKit?');
const batch = await embedder.embedBatch(['Question 1', 'Question 2']);
// batch is a BatchEmbeddingResult — the vectors live at batch.embeddings (number[][])

Providers

Provider	Models	Setup
OpenAI	`text-embedding-3-small`, `text-embedding-3-large`	API key
AWS Bedrock	Titan, Cohere	AWS credentials

Vector Stores

Store and query vector embeddings:

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

// `dimensions` is required (no default). Provider-specific options live
// under the matching provider key (`pinecone`, `pgvector`, `qdrant`).
const store = createVectorStore({
  provider: 'pinecone',
  indexName: 'my-index',
  dimensions: 1536, // OpenAI text-embedding-3-small
  pinecone: { apiKey: process.env.PINECONE_API_KEY! },
});

// Upsert vectors — the field is `values` (a `number[]`), not `vector`.
await store.upsert([
  { id: 'doc-1', values: embedding, metadata: { title: 'Getting Started' } },
]);

// Search for similar vectors — pass a `VectorQuery` object.
const results = await store.search({ vector: embedding, topK: 5 });

Providers

Provider	Description
Pinecone	Managed vector database
pgvector	PostgreSQL extension (use with `@venturekit/data`)
In-memory	Development and testing

RAG Pipeline

Build retrieval-augmented generation pipelines:

import { createRagPipeline, chunkText } from '@venturekit-pro/ai';

// `RagConfig` is config-only (no live instances): provide nested embedding,
// vectorStore, and chunking configs plus the default `topK`.
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,
});

Ingesting Documents

rag.index() takes raw documents — it chunks each one internally using the pipeline’s chunking config, then embeds and upserts the chunks:

await rag.index([
  { id: 'doc-1', content: documentText, metadata: { title: 'Getting Started' } },
]);

If you need to chunk text yourself (for example to write to a VectorStore directly), chunkText(text, sourceId, ChunkingConfig) is exported separately — do not pass its output back into rag.index(), which would chunk it again:

const chunks = chunkText(documentText, 'doc-1', {
  strategy: 'fixed',
  chunkSize: 500,
  chunkOverlap: 50,
});

Retrieving Context

const context = await rag.retrieve('How do I deploy?', { topK: 3 });
// Returns the most relevant chunks for your query

Agents

Create AI agents with tool use:

import { createAgent, defineTool } from '@venturekit-pro/ai';

// Tool parameters use a JSON-Schema object shape: `{ type: 'object',
// properties, required }`. The callback is `execute`, not `handler`.
const searchTool = defineTool<{ query: string }>({
  name: 'search_docs',
  description: 'Search the documentation',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query' },
    },
    required: ['query'],
  },
  execute: async ({ query }) => {
    // retrieve() returns a RetrievedContext: { chunks, context, totalChunks }.
    const { chunks } = await rag.retrieve(query, { topK: 3 });
    return chunks.map(c => c.content).join('\n\n');
  },
});

// `provider` is required — 'openai' | 'anthropic' | 'bedrock'.
const agent = createAgent({
  provider: 'openai',
  model: 'gpt-4',
  apiKey: process.env.OPENAI_API_KEY!,
  tools: [searchTool],
  systemPrompt: 'You are a helpful assistant that answers questions about VentureKit.',
});

const response = await agent.run('How do I set up authentication?');

Using AI in Handlers

createRagPipeline() takes the same nested config object shown above. Build the pipeline once at module scope and reuse it across handler invocations so the underlying provider clients are not re-initialised on every request.

import { handler } from '@venturekit/runtime';
import { createRagPipeline } from '@venturekit-pro/ai';

// Module-scope — initialised once per Lambda container.
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,
});

export const main = handler(async (body, ctx, logger) => {
  // retrieve() returns { chunks, context, totalChunks }. `context` is a ready-to-use
  // prompt string; `chunks` is the array of matched passages.
  const { chunks, context } = await rag.retrieve(body.question, { topK: 3 });

  logger.info('RAG retrieval', { question: body.question, resultCount: chunks.length });
  return { answer: context };
}, { scopes: ['api.read'] });