@cilow/sdk 0.2.0 → 0.2.1

package/README.md

@@ -1,16 +1,6 @@
 # @cilow/sdk
 
-TypeScript/JavaScript SDK for the Cilow AI Agent Platform - Production-ready memory system for AI agents with unlimited context.
-
-## Features
-
-- **Semantic Memory Storage** - Store and retrieve memories using vector embeddings
-- **Multi-tier Storage** - Hot/Warm/Cold tiers with automatic optimization
-- **Tag-based Organization** - Organize memories with flexible tagging
-- **Full-text + Semantic Search** - Hybrid search combining BM25 and embeddings
-- **Knowledge Graph** - Entity extraction and relationship mapping
-- **Multi-tenant Support** - User isolation for secure multi-user apps
-- **TypeScript First** - Full type safety with comprehensive types
+Complete TypeScript SDK for Cilow - AI Memory Infrastructure with multi-framework support.
 
 ## Installation
 
@@ -25,297 +15,520 @@ pnpm add @cilow/sdk
 ## Quick Start
 
 ```typescript
-import { CilowClient } from '@cilow/sdk';
+import { Cilow } from '@cilow/sdk';
 
-// Initialize with API key
-const client = new CilowClient({
-  apiKey: 'cilow_your_api_key',
-  baseUrl: 'https://api.cilow.ai', // or your self-hosted URL
+const cilow = new Cilow({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'your-api-key'
 });
 
-// Add a memory
-const { memoryId } = await client.addMemory({
-  content: 'User prefers TypeScript over JavaScript for backend development',
-  tags: ['preference', 'programming', 'backend'],
-});
+// Store a memory
+await cilow.remember("User prefers dark mode", { tags: ["preference", "ui"] });
 
-// Search memories semantically
-const results = await client.searchMemories({
-  query: 'What programming languages does the user prefer?',
-  limit: 5,
-});
+// Search memories
+const memories = await cilow.recall("user preferences");
 
-console.log(results);
-// [
-//   {
-//     memoryId: 'mem_xxx',
-//     content: 'User prefers TypeScript over JavaScript...',
-//     similarity: 0.92,
-//     score: 0.18,
-//     tags: ['preference', 'programming', 'backend']
-//   }
-// ]
+// Delete memories
+await cilow.forget({ tags: ["temporary"] });
 ```
 
-## Authentication
+## Features
 
-### API Key Authentication (Recommended for backends)
+- **Simple API**: `remember`, `recall`, `forget` for easy memory management
+- **Full TypeScript Support**: Complete type definitions for all APIs
+- **Framework Integrations**: Vercel AI SDK, OpenAI, LangChain
+- **React Hooks**: `useMemory`, `useRecall`, `useMemoryContext`
+- **WebSocket Support**: Real-time memory updates and graph changes
+- **Multi-tier Memory**: Hot, warm, cold memory tiers for optimal performance
 
-```typescript
-const client = new CilowClient({
-  apiKey: 'cilow_your_api_key',
-});
-```
+## Core Client
 
-### JWT Authentication (For frontend apps)
+### Basic Operations
 
 ```typescript
-const client = new CilowClient({
-  baseUrl: 'https://api.cilow.ai',
+import { Cilow } from '@cilow/sdk';
+
+const cilow = new Cilow({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'your-api-key'
 });
 
-// Login to get access token
-const auth = await client.login('user@example.com', 'password');
-console.log(`Logged in as: ${auth.user.email}`);
+// Store a memory
+const memoryId = await cilow.remember("Important information", {
+  tags: ["important"],
+  userId: "user-123",
+  metadata: { source: "chat" }
+});
 
-// Token is automatically set for subsequent requests
-```
+// Search memories with semantic similarity
+const results = await cilow.recall("important information", {
+  limit: 10,
+  minRelevance: 0.5,
+  tags: ["important"]
+});
 
-## Memory Operations
+// Delete memories
+await cilow.forget({ memoryId: "mem-123" });
+await cilow.forget({ tags: ["old"], userId: "user-123" });
+```
 
-### Add Memory
+### Advanced Operations
 
 ```typescript
-const { memoryId } = await client.addMemory({
-  content: 'Meeting notes: Q4 planning discussed roadmap priorities',
-  tags: ['meeting', 'planning', 'q4'],
-  metadata: {
-    source: 'meeting-notes',
-    date: '2024-01-15',
-  },
+// Get a specific memory
+const memory = await cilow.getMemory("mem-123");
+
+// Update a memory
+const updated = await cilow.updateMemory("mem-123", {
+  content: "Updated content",
+  tags: ["updated"]
 });
-```
 
-### Search Memories
+// List memories with pagination
+const list = await cilow.listMemories({
+  limit: 20,
+  offset: 0,
+  userId: "user-123",
+  tags: ["preference"]
+});
 
-```typescript
-// Semantic search
-const results = await client.searchMemories({
-  query: 'What were the Q4 priorities?',
-  limit: 10,
-  minScore: 0.5,
+// Get context for AI prompts
+const context = await cilow.getContext("recent discussions", {
+  maxTokens: 2000,
+  userId: "user-123"
 });
 
-// Search with tag filtering
-const taggedResults = await client.searchMemories({
-  query: 'planning discussions',
-  tags: ['meeting', 'planning'],
-  tagMode: 'all', // 'all' = AND, 'any' = OR
+// Store conversation turns
+await cilow.storeConversation({
+  userMessage: "What's the weather?",
+  assistantResponse: "The weather is sunny today.",
+  userId: "user-123",
+  sessionId: "session-abc"
 });
+
+// Get statistics
+const stats = await cilow.getStats();
+console.log(`Total memories: ${stats.totalMemories}`);
 ```
 
-### Update Memory
+### Graph Operations
 
 ```typescript
-await client.updateMemory(memoryId, {
-  content: 'Updated content with new information',
-  tags: ['updated', 'important'],
+// Create graph nodes
+const node = await cilow.createGraphNode("Person", "John Doe", {
+  email: "john@example.com"
+});
+
+// Create relationships
+const edge = await cilow.createGraphEdge(
+  node.id,
+  "other-node-id",
+  "KNOWS",
+  { since: "2024" }
+);
+
+// Traverse the graph
+const subgraph = await cilow.traverseGraph({
+  startNodeId: node.id,
+  maxDepth: 3,
+  relationshipTypes: ["KNOWS", "WORKS_WITH"]
 });
 ```
 
-### Delete Memory
+## Vercel AI SDK Integration
 
 ```typescript
-await client.deleteMemory(memoryId);
-```
+import { createCilowTools, createCilowContext } from '@cilow/sdk/providers/vercel';
+import { streamText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+
+// Create tools for AI to use
+const tools = createCilowTools({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'your-key',
+  defaultUserId: 'user-123'
+});
 
-### List Memories
+// Use with streamText
+const result = await streamText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  tools,
+  messages: [
+    { role: 'user', content: 'What do you remember about me?' }
+  ]
+});
 
-```typescript
-// List all memories
-const memories = await client.listMemories();
+// Or use context injection
+const getContext = createCilowContext({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'your-key',
+  maxTokens: 2000
+});
 
-// Filter by tier
-const hotMemories = await client.listMemories({
-  tier: 'hot',
-  limit: 50,
-  offset: 0,
+const context = await getContext('previous discussions');
+
+const response = await streamText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  system: `You are a helpful assistant.\n\nContext:\n${context.context}`,
+  prompt: 'Continue our discussion'
 });
 ```
 
-### Get Statistics
+### Context Middleware
 
 ```typescript
-const stats = await client.getMemoryStats();
-console.log(stats);
-// {
-//   totalMemories: 1500,
-//   hotTier: 200,
-//   warmTier: 800,
-//   coldTier: 500,
-//   totalTokens: 45000,
-//   avgSalience: 0.65
-// }
+import { createContextMiddleware } from '@cilow/sdk/providers/vercel';
+
+const withMemory = createContextMiddleware({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'your-key'
+});
+
+// Automatically inject memory context
+const messagesWithContext = await withMemory(originalMessages, {
+  userId: 'user-123',
+  maxTokens: 2000
+});
 ```
 
-## Tag Management
+## OpenAI SDK Integration
 
 ```typescript
-// Add tags to a memory
-await client.addTags(memoryId, ['important', 'follow-up']);
+import OpenAI from 'openai';
+import { createCilowOpenAI } from '@cilow/sdk/providers/openai';
 
-// Remove tags
-await client.removeTags(memoryId, ['follow-up']);
+const openai = new OpenAI();
 
-// Replace all tags
-await client.setTags(memoryId, ['new-tag-set']);
+const cilowAI = createCilowOpenAI(openai, {
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'cilow-key',
+  autoStore: true // Automatically store conversations
+});
 
-// Filter memories by tags
-const tagged = await client.filterByTags(['important'], 'any');
+// Memory context is automatically injected
+const { completion, memoriesUsed } = await cilowAI.chat.completions.create({
+  model: 'gpt-4',
+  messages: [
+    { role: 'user', content: 'Based on our previous discussions, what should I focus on?' }
+  ]
+});
 
-// List all tags with counts
-const allTags = await client.listAllTags();
+console.log(`Used ${memoriesUsed} memories for context`);
+console.log(completion.choices[0].message.content);
 
-// Get tag statistics
-const tagStats = await client.getTagStats();
+// Direct memory access
+await cilowAI.remember("Important insight", { tags: ["insight"] });
+const memories = await cilowAI.recall("insights");
 ```
 
-## Agent Operations
+## LangChain Integration
+
+### Memory Class
 
 ```typescript
-// Create an agent
-const agentId = await client.createAgent({
-  name: 'research-assistant',
-  model: 'gpt-4',
-  systemPrompt: 'You are a helpful research assistant.',
+import { CilowMemory } from '@cilow/sdk/providers/langchain';
+import { ConversationChain } from 'langchain/chains';
+import { ChatOpenAI } from '@langchain/openai';
+
+const memory = new CilowMemory({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'cilow-key',
+  userId: 'user-123',
+  sessionId: 'session-abc'
 });
 
-// Execute a task
-const result = await client.executeTask(agentId, {
-  task: 'Summarize the key points from recent meetings',
-  context: 'User is preparing for Q1 planning',
+const chain = new ConversationChain({
+  llm: new ChatOpenAI(),
+  memory
 });
 
-// Get agent status
-const agent = await client.getAgent(agentId);
-
-// List all agents
-const agents = await client.listAgents();
-
-// Delete agent
-await client.deleteAgent(agentId);
+const response = await chain.call({
+  input: 'What did we discuss last time?'
+});
 ```
 
-## API Key Management
+### Retriever for RAG
 
 ```typescript
-// Create a new API key
-const apiKey = await client.createApiKey({
-  name: 'Production API Key',
-  expiresAt: new Date('2025-01-01'),
-});
+import { CilowRetriever } from '@cilow/sdk/providers/langchain';
+import { RetrievalQAChain } from 'langchain/chains';
 
-// List API keys
-const keys = await client.listApiKeys();
+const retriever = new CilowRetriever({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'cilow-key',
+  topK: 5
+});
 
-// Revoke an API key
-await client.revokeApiKey(keyId);
+const chain = RetrievalQAChain.fromLLM(
+  new ChatOpenAI(),
+  retriever
+);
 
-// Delete an API key
-await client.deleteApiKey(keyId);
+const answer = await chain.call({
+  query: 'What are the key points from our meetings?'
+});
 ```
 
-## Session Management
+### Vector Store
 
 ```typescript
-// List active sessions
-const sessions = await client.listSessions();
+import { CilowVectorStore } from '@cilow/sdk/providers/langchain';
 
-// Revoke a specific session
-await client.revokeSession(sessionId);
+const vectorStore = new CilowVectorStore({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'cilow-key'
+});
+
+// Add documents
+await vectorStore.addDocuments([
+  { pageContent: 'Meeting notes from Monday', metadata: { topic: 'standup' } },
+  { pageContent: 'Product requirements document', metadata: { topic: 'product' } }
+]);
 
-// Revoke all other sessions
-await client.revokeOtherSessions();
+// Similarity search
+const results = await vectorStore.similaritySearch('standup notes', 5);
 
-// Revoke all sessions (logout everywhere)
-await client.revokeAllSessions();
+// With scores
+const resultsWithScores = await vectorStore.similaritySearchWithScore('standup notes');
 ```
 
-## Error Handling
+## React Hooks
 
-```typescript
+```tsx
 import {
-  CilowError,
-  AuthenticationError,
-  NotFoundError,
-  RateLimitError
-} from '@cilow/sdk';
+  CilowProvider,
+  useMemory,
+  useRecall,
+  useMemoryContext,
+  useMemorySubscription,
+  useDebouncedSearch
+} from '@cilow/sdk/react';
+
+// Wrap your app with the provider
+function App() {
+  return (
+    <CilowProvider
+      apiUrl="https://api.cilow.ai"
+      apiKey="your-key"
+      userId="user-123"
+      enableWebSocket={true}
+    >
+      <YourApp />
+    </CilowProvider>
+  );
+}
 
-try {
-  await client.searchMemories({ query: 'test' });
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.error('Invalid API key');
-  } else if (error instanceof NotFoundError) {
-    console.error('Resource not found');
-  } else if (error instanceof RateLimitError) {
-    console.error('Rate limited, retry later');
-  } else if (error instanceof CilowError) {
-    console.error(`API error: ${error.message}`);
-  }
+// Use memory operations
+function MemoryManager() {
+  const { remember, forget, isLoading, error } = useMemory();
+
+  const handleSave = async () => {
+    await remember("Important note", { tags: ["note"] });
+  };
+
+  return (
+    <button onClick={handleSave} disabled={isLoading}>
+      Save Memory
+    </button>
+  );
+}
+
+// Search memories
+function SearchComponent() {
+  const { data, search, isLoading } = useRecall();
+
+  const handleSearch = () => {
+    search("user preferences", { limit: 10 });
+  };
+
+  return (
+    <div>
+      <button onClick={handleSearch}>Search</button>
+      {data.map(result => (
+        <div key={result.memory.id}>
+          <p>{result.memory.content}</p>
+          <span>Score: {(result.score * 100).toFixed(0)}%</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// Debounced search
+function LiveSearch() {
+  const { query, setQuery, results, isLoading } = useDebouncedSearch({
+    delay: 300,
+    minLength: 2
+  });
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={e => setQuery(e.target.value)}
+        placeholder="Search memories..."
+      />
+      {isLoading && <p>Searching...</p>}
+      {results.map(r => (
+        <div key={r.memory.id}>{r.memory.content}</div>
+      ))}
+    </div>
+  );
+}
+
+// Get context for AI
+function ChatWithContext() {
+  const { getContext, isLoading } = useMemoryContext();
+
+  const sendMessage = async (message: string) => {
+    const { context, memoriesUsed } = await getContext(message);
+
+    // Use context with your AI provider
+    const response = await callAI({
+      system: `Context:\n${context}`,
+      message
+    });
+  };
+
+  return <ChatUI onSend={sendMessage} />;
+}
+
+// Real-time updates
+function LiveMemoryFeed() {
+  const { latestEvent, events, isConnected } = useMemorySubscription({
+    userId: 'user-123',
+    eventTypes: ['memory.created', 'memory.updated']
+  });
+
+  useEffect(() => {
+    if (latestEvent?.type === 'memory.created') {
+      console.log('New memory:', latestEvent.memory);
+    }
+  }, [latestEvent]);
+
+  return (
+    <div>
+      <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
+      <p>Events: {events.length}</p>
+    </div>
+  );
 }
 ```
 
-## Configuration Options
+## WebSocket Support
 
 ```typescript
-const client = new CilowClient({
-  // API base URL (default: http://localhost:8080)
-  baseUrl: 'https://api.cilow.ai',
+import { CilowWebSocket } from '@cilow/sdk/websocket';
+
+const ws = new CilowWebSocket({
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'your-key',
+  reconnectAttempts: 5,
+  heartbeatInterval: 30000
+});
 
-  // API key for authentication
-  apiKey: 'cilow_your_api_key',
+// Connect
+await ws.connect();
 
-  // JWT access token (alternative to API key)
-  accessToken: 'eyJhbGc...',
+// Subscribe to events
+ws.subscribe({ userId: 'user-123' });
 
-  // Request timeout in milliseconds (default: 30000)
-  timeout: 60000,
+// Listen for memory events
+ws.onMemoryCreated((event) => {
+  console.log('New memory:', event.memory);
 });
+
+ws.onMemoryUpdated((event) => {
+  console.log('Updated memory:', event.memory);
+});
+
+ws.onMemoryDeleted((event) => {
+  console.log('Deleted memory ID:', event.memoryId);
+});
+
+// Listen for graph events
+ws.onGraphNodeCreated((event) => {
+  console.log('New node:', event.node);
+});
+
+// Connection status
+ws.onConnectionStatus((event) => {
+  console.log('Connection:', event.status, event.reason);
+});
+
+// Wait for specific event
+const event = await ws.once('memory.created', 5000);
+
+// Disconnect
+ws.disconnect();
 ```
 
-## Types
+## TypeScript Types
 
-All types are fully exported for TypeScript users:
+The SDK exports comprehensive TypeScript types:
 
 ```typescript
 import type {
+  // Core types
   Memory,
-  MemoryStats,
+  MemorySummary,
+  MemoryTier,
   SearchResult,
-  Agent,
-  User,
-  ApiKey,
-  AddMemoryOptions,
-  SearchMemoriesOptions,
+
+  // Graph types
+  GraphNode,
+  GraphEdge,
+  GraphSubgraph,
+
+  // Event types
+  CilowEvent,
+  MemoryCreatedEvent,
+  MemoryUpdatedEvent,
+
+  // Configuration
+  CilowConfig,
+  WebSocketConfig,
+
+  // API types
+  PaginatedResponse,
+  ContextResult,
 } from '@cilow/sdk';
 ```
 
-## Self-Hosting
-
-Cilow can be self-hosted. Point the SDK to your instance:
+## Error Handling
 
 ```typescript
-const client = new CilowClient({
-  baseUrl: 'http://localhost:8080',
-  apiKey: 'your-local-api-key',
-});
+import { CilowApiError, isApiError } from '@cilow/sdk';
+
+try {
+  await cilow.getMemory('invalid-id');
+} catch (error) {
+  if (error instanceof CilowApiError) {
+    console.log('API Error:', error.message);
+    console.log('Code:', error.code);
+    console.log('Status:', error.statusCode);
+    console.log('Details:', error.details);
+  }
+}
 ```
 
-## Requirements
+## Configuration Options
 
-- Node.js >= 18.0.0
-- ES2020+ or modern browser with fetch support
+```typescript
+const cilow = new Cilow({
+  // Required
+  apiUrl: 'https://api.cilow.ai',
+  apiKey: 'your-api-key',
+
+  // Optional
+  timeout: 30000,        // Request timeout (ms)
+  retries: 3,            // Retry attempts
+  debug: false,          // Enable debug logging
+  headers: {             // Custom headers
+    'X-Custom-Header': 'value'
+  }
+});
+```
 
 ## License