Components

Add AI capabilities with gencow add — RAG, Memory, Tools, Guardrails, and more

The gencow add command installs pre-built AI components into your project. Each component adds files to gencow/ and installs required dependencies.

Usage

# Add a single component
npx gencow@latest add AI

# Add multiple at once
npx gencow@latest add AI RAG Reranker

# Dependencies auto-resolve (RAG requires AI → AI is added automatically)
npx gencow@latest add RAG   # → also installs AI

Available Components

# Component Description Requires
1 AI Vercel AI SDK wrapper (chat, embeddings, structured output; cloud proxy is non-streaming today) —
2 Tools AI Tool Calling with ctx integration AI
3 RAG Document ingestion + semantic search AI
4 Memory Agent memory (episodic/semantic/procedural) AI
5 Reranker LLM-powered search result reranking AI
6 Guardrails Input/output safety filters (PII, topic blocking) AI
7 Prompts Reusable prompt templates —
8 Parsers PDF/HTML/CSV file parsing —
9 Analytics LLM call tracking AI (coming soon)

Component Details

AI — Core Engine

npx gencow@latest add AI

Creates gencow/ai.ts and gencow/ai-image.ts. Provides:

ai.chat({ system, messages, model })    // Non-streaming response
ai.stream({ system, messages, model })  // Local/direct streaming; cloud proxy not yet supported
ai.embed(text)                          // Generate embeddings
ai.image.generate({ prompt, model })    // Generate images with GPT Image

Installed deps: ai, @ai-sdk/openai Env required: OPENAI_API_KEY (local only — auto in cloud)

Cloud model support is controlled by platform model_pricing active rows. The current seed includes GPT-5.5, GPT-5.4/mini/nano, GPT-5 mini/nano, GPT-4.1 family models, GPT-4o compatibility models, GPT Image models, and text-embedding-3-*.

gencow add RAG

Creates gencow/rag.ts + gencow/schema-rag.ts. Provides:

// Ingest documents
await rag.ingest(ctx, "source-name", "Document text content...");

// Search legacy local documents
const results = await rag.retrieve(ctx, "What is Gencow?");
// → [{ content, source, score }]

Important: Import schema-rag.ts in your main schema.ts to create the required DB tables.

rag.ingest() uses the local rag_documents table. Grounded helpers such as rag.askGrounded() and reranker.answerGrounded() read canonical Phase 2 rag_* corpora populated through documents.ingest.*.

For production grounded RAG, ingest files with documents.ingest.start and query canonical chunks with ctx.search("rag_chunks", ...) or ctx.grounding.answer(...).

Memory — Agent Memory

gencow add Memory

Creates gencow/memory.ts + gencow/schema-memory.ts. Three memory types:

// Build context from memory for AI conversations
const memCtx = await memory.buildContext(ctx, userId, sessionId, query);
// → { episodic, semantic, procedural }

// Extract and store memories from conversation
await memory.extract(ctx, userId, sessionId, messages);
Type Purpose Example
Episodic Conversation history "Last time we discussed…"
Semantic Facts and knowledge "User prefers dark mode"
Procedural Learned procedures "When user asks X, do Y"

Reranker — Result Quality

gencow add Reranker

Creates gencow/reranker.ts. Improves search result relevance:

// Rerank search results
const reranked = await reranker.rerank(query, searchResults, { topK: 5 });

// Combined RAG pipeline: search + rerank
const results = await reranker.searchAndRerank(ctx, rag, query);

// Phase 3 grounded answer: claim → citation mapping
const grounded = await reranker.answerGrounded(ctx, query, {
    corpus: "default",
    visibility: "shared",
});

Guardrails — Safety Filters

gencow add Guardrails

Creates gencow/guardrails.ts. Input/output validation:

// Validate input
const safe = await guardrails.validateInput(userText, {
    maskPII: true,           // Mask phone numbers, emails, etc.
    blockTopics: ["politics"], // Block specific topics
});

// Validate output
const cleanOutput = await guardrails.validateOutput(aiResponse, {
    removePII: true,
});

// Wrap a function with both input and output guards
const result = await guardrails.wrap(
    myFunction, input, inputOptions, outputOptions
);

Prompts — Reusable Templates

gencow add Prompts

Creates gencow/prompts.ts. Pre-built prompt templates:

import { ragQAPrompt, summarizePrompt, classifyPrompt } from "./prompts";

// RAG Q&A
const prompt = ragQAPrompt({
    question: "What is Gencow?",
    context: "Retrieved context here...",
});

// Summarization
const prompt = summarizePrompt({ text: "Long text to summarize..." });

// Classification
const prompt = classifyPrompt({
    text: "I love this product!",
    categories: ["positive", "negative", "neutral"],
});

Parsers — File Parsing

gencow add Parsers

Creates gencow/parsers.ts. Parse various file formats:

// PDF
const text = await parsers.pdf(buffer);

// HTML
const text = await parsers.html(htmlString);

// CSV
const rows = await parsers.csv(csvString);

// Auto-detect by filename
const text = await parsers.auto("document.pdf", buffer);

// RAG integration
await rag.ingest(ctx, "manual.pdf", await parsers.pdf(buffer));

Installed deps: pdf-parse

Dependency Resolution

Components automatically install their dependencies:

gencow add RAG
# → Also installs AI (because RAG requires AI)
gencow add RAG Reranker Memory
# → Installs AI first, then RAG, Reranker, Memory

After Installation

# README is auto-updated with new component docs
gencow dev

Each component's usage is added to the auto-generated gencow/README.md.

Next Steps

AI EngineRAG & Memory