@novahelm/ai

AI integration for NovaHelm — the first-party AI surface for the platform and consumer apps. Exposes createAIProvider, streamChat, AnthropicAdapter (default), OpenAIAdapter, and OllamaAdapter, plus RAG, content pipelines, caching, rate limiting, and usage tracking. Consumers should only import from @novahelm/ai — never ai / @ai-sdk/* directly (the provider SDKs are an internal implementation detail and may change).

Quick Start

pnpm add @novahelm/ai

import { createAIProvider, streamChat } from "@novahelm/ai";

const ai = createAIProvider({
  provider: "anthropic",
  apiKey: "sk-...",
  defaultModel: "claude-sonnet-4-20250514",
});

// Stream a chat response
const stream = await streamChat({
  ai,
  messages: [{ role: "user", content: "Summarize this article..." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

RAG (Retrieval-Augmented Generation)

Index documents and search by semantic similarity using pgvector:

import { indexDocument, semanticSearch, chunkText } from "@novahelm/ai";

// Index a document (chunks + embeds automatically)
await indexDocument({
  ai,
  db,
  content: articleBody,
  metadata: { type: "article", id: article.id },
});

// Search by meaning
const results = await semanticSearch({
  ai,
  db,
  query: "How do I deploy to production?",
  limit: 5,
});

Content Pipeline

Run AI-powered content processing (summarize, tag, generate SEO):

import { runContentPipeline } from "@novahelm/ai";

const result = await runContentPipeline({
  ai,
  content: post.body,
  steps: ["summarize", "extract-tags", "generate-meta"],
});
// result.summary, result.tags, result.meta

Prompt Templates

Define reusable, parameterized prompt templates:

import { definePromptTemplate, renderPrompt } from "@novahelm/ai";

definePromptTemplate({
  id: "blog-outline",
  template: "Write an outline for a blog post about {{topic}} targeting {{audience}}.",
  variables: [
    { name: "topic", required: true },
    { name: "audience", default: "developers" },
  ],
});

const prompt = renderPrompt("blog-outline", { topic: "WebSockets" });

Caching

Cache AI responses in Redis to reduce costs and latency:

import { createAICache, withCache } from "@novahelm/ai";

const cache = createAICache({ redis, ttlSeconds: 3600 });

const response = await withCache(cache, {
  messages: [{ role: "user", content: "What is NovaHelm?" }],
  generate: () => streamChat({ ai, messages }),
});

Fallback Providers

Automatic failover between AI providers:

import { createFallbackProvider } from "@novahelm/ai";

const resilientAi = createFallbackProvider({
  providers: [
    { provider: "anthropic", apiKey: "..." },
    { provider: "openai", apiKey: "..." },
  ],
});

Client Hook

import { useNovaChat } from "@novahelm/ai/client";

function ChatUI() {
  const { messages, send, isStreaming } = useNovaChat({
    endpoint: "/api/chat",
  });

  return <button onClick={() => send("Hello!")}>Ask</button>;
}

API Reference

| Export | Description | |--------|-------------| | createAIProvider(config) | Initialize AI provider (Anthropic, OpenAI, Ollama) | | streamChat(opts) | Stream a chat completion | | semanticSearch(opts) | Vector similarity search (pgvector) | | indexDocument(opts) | Chunk and embed a document | | chunkText(text, opts) | Split text into chunks | | runContentPipeline(opts) | Run multi-step AI content processing | | extractTags(opts) | AI-powered tag extraction | | extractTagsNLP(text) | NLP-based tag extraction (no AI call) | | createAICache(config) | Create Redis-backed response cache | | withCache(cache, opts) | Wrap generation with caching | | createFallbackProvider(config) | Multi-provider failover | | definePromptTemplate(config) | Register a reusable prompt template | | renderPrompt(id, vars) | Render a template with variables | | createResilientStream(opts) | Stream with automatic retry | | createAIRateLimiter(config) | Token/request rate limiter | | trackUsage(opts) | Record token usage for billing | | getUsageSummary(range) | Query usage stats | | useNovaChat(opts) | React hook for chat UI (from /client) |