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 EmbeddingResult[]; access vectors via batch.map(r => r.embedding)

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

// chunkText(text, sourceId, ChunkingConfig) — sourceId is required.
const chunks = chunkText(documentText, 'doc-1', {
  strategy: 'fixed',
  chunkSize: 500,
  chunkOverlap: 50,
});

// Index documents into the pipeline’s vector store.
await rag.index(chunks);

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 }) => {
    const results = await rag.retrieve(query, { topK: 3 });
    return results.map(r => r.text).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) => {
  const context = await rag.retrieve(body.question, { topK: 3 });

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