Skip to content

README.md

Latest commit

 

History

History
286 lines (221 loc) · 8.31 KB

README.md

File metadata and controls

286 lines (221 loc) · 8.31 KB
Raw

@ainative/ai-kit-core API Reference

Framework-agnostic core for AI Kit - streaming, agents, state management

Installation

npm install @ainative/ai-kit-core
# or
pnpm add @ainative/ai-kit-core
# or
yarn add @ainative/ai-kit-core

Overview

The core package provides the fundamental building blocks for building AI-powered applications. It includes:

  • Streaming: Real-time streaming from LLM providers (OpenAI, Anthropic)
  • Agents: AI agent creation, execution, and orchestration
  • Security: PII detection, prompt injection prevention, content moderation
  • Memory: Long-term memory management and fact extraction
  • Context: Context window management and token counting
  • Summarization: Automatic conversation summarization
  • Authentication: AINative authentication provider
  • Session Management: User session tracking and storage
  • ZeroDB Integration: Database operations and query building
  • Usage Tracking: Token counting and cost monitoring
  • Instrumentation: Auto-instrumentation and observability
  • RLHF: Reinforcement learning logging and feedback
  • Search: Semantic search capabilities
  • Store: Conversation and state persistence
  • Monitoring: Query monitoring and alerting
  • Reporting: Usage reports and analytics

Modules

Streaming

Agents

Security

Memory

Context Management

Summarization

Authentication

Session Management

ZeroDB

Usage Tracking

Instrumentation

RLHF

Search

Store

Monitoring

Alerts

Reporting

Quick Start Examples

Streaming

import { AIStream } from '@ainative/ai-kit-core/streaming';
import { OpenAI } from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }],
  stream: true
});

const stream = AIStream(response);

// Use in your framework (Next.js, Express, etc.)
return new Response(stream);

Agents

import { Agent, AgentExecutor } from '@ainative/ai-kit-core/agents';
import { Calculator, WebSearch } from '@ainative/ai-kit-tools';

const agent = new Agent({
  name: 'ResearchAssistant',
  description: 'Helps with research and calculations',
  tools: [Calculator, WebSearch],
  llm: {
    provider: 'openai',
    model: 'gpt-4',
    apiKey: process.env.OPENAI_API_KEY
  }
});

const executor = new AgentExecutor({ agent });
const result = await executor.execute('What is 15% of the GDP of France?');
console.log(result.output);

Security

import { PIIDetector } from '@ainative/ai-kit-core/security';

const detector = new PIIDetector({
  enabledTypes: ['email', 'phone', 'ssn', 'credit_card']
});

const result = detector.detect('My email is john@example.com');
console.log(result.containsPII); // true
console.log(result.detectedTypes); // ['email']
console.log(result.redacted); // 'My email is [REDACTED_EMAIL]'

Memory

import { UserMemory } from '@ainative/ai-kit-core/memory';
import { ZeroDBMemoryStore } from '@ainative/ai-kit-core/memory';

const store = new ZeroDBMemoryStore({
  projectId: process.env.ZERODB_PROJECT_ID,
  apiKey: process.env.ZERODB_API_KEY
});

const memory = new UserMemory({
  userId: 'user-123',
  store
});

// Store facts
await memory.addFact('User prefers dark mode');
await memory.addFact('User is interested in machine learning');

// Retrieve relevant memories
const relevant = await memory.getRelevantMemories('What are my preferences?');
console.log(relevant);

Usage Tracking

import { UsageTracker } from '@ainative/ai-kit-core/tracking';

const tracker = new UsageTracker();

await tracker.trackSuccess({
  model: 'gpt-4',
  promptTokens: 100,
  completionTokens: 50,
  durationMs: 1000,
  userId: 'user-123'
});

const stats = await tracker.getAggregated();
console.log(`Total cost: $${stats.totalCost}`);
console.log(`Total tokens: ${stats.totalTokens}`);

TypeScript Support

All modules include complete TypeScript definitions:

import type {
  AIStreamConfig,
  AgentConfig,
  ToolDefinition,
  SecurityConfig,
  MemoryRecord,
  UsageRecord
} from '@ainative/ai-kit-core';

Configuration

Most modules support configuration via environment variables or config objects:

// Environment variables
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
ZERODB_PROJECT_ID=proj_...
ZERODB_API_KEY=zdb_...

// Config objects
const config = {
  llm: {
    provider: 'openai',
    model: 'gpt-4',
    apiKey: process.env.OPENAI_API_KEY
  },
  security: {
    enablePIIDetection: true,
    enablePromptInjection: true
  },
  memory: {
    enabled: true,
    maxRecords: 1000
  }
};

Best Practices

  1. Always handle errors: Wrap API calls in try-catch blocks
  2. Use streaming for real-time UX: Stream responses when possible
  3. Enable security by default: Use PII detection and prompt injection prevention
  4. Track usage: Monitor costs with UsageTracker
  5. Implement memory: Use UserMemory for context-aware conversations
  6. Validate inputs: Always validate user inputs before processing
  7. Use TypeScript: Leverage type safety for better development experience

License

MIT

Links

See Also