@cilow/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cilow AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# @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
+
+## Installation
+
+```bash
+npm install @cilow/sdk
+# or
+yarn add @cilow/sdk
+# or
+pnpm add @cilow/sdk
+```
+
+## Quick Start
+
+```typescript
+import { CilowClient } 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
+});
+
+// Add a memory
+const { memoryId } = await client.addMemory({
+  content: 'User prefers TypeScript over JavaScript for backend development',
+  tags: ['preference', 'programming', 'backend'],
+});
+
+// Search memories semantically
+const results = await client.searchMemories({
+  query: 'What programming languages does the user prefer?',
+  limit: 5,
+});
+
+console.log(results);
+// [
+//   {
+//     memoryId: 'mem_xxx',
+//     content: 'User prefers TypeScript over JavaScript...',
+//     similarity: 0.92,
+//     score: 0.18,
+//     tags: ['preference', 'programming', 'backend']
+//   }
+// ]
+```
+
+## Authentication
+
+### API Key Authentication (Recommended for backends)
+
+```typescript
+const client = new CilowClient({
+  apiKey: 'cilow_your_api_key',
+});
+```
+
+### JWT Authentication (For frontend apps)
+
+```typescript
+const client = new CilowClient({
+  baseUrl: 'https://api.cilow.ai',
+});
+
+// Login to get access token
+const auth = await client.login('user@example.com', 'password');
+console.log(`Logged in as: ${auth.user.email}`);
+
+// Token is automatically set for subsequent requests
+```
+
+## Memory Operations
+
+### Add Memory
+
+```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',
+  },
+});
+```
+
+### Search Memories
+
+```typescript
+// Semantic search
+const results = await client.searchMemories({
+  query: 'What were the Q4 priorities?',
+  limit: 10,
+  minScore: 0.5,
+});
+
+// Search with tag filtering
+const taggedResults = await client.searchMemories({
+  query: 'planning discussions',
+  tags: ['meeting', 'planning'],
+  tagMode: 'all', // 'all' = AND, 'any' = OR
+});
+```
+
+### Update Memory
+
+```typescript
+await client.updateMemory(memoryId, {
+  content: 'Updated content with new information',
+  tags: ['updated', 'important'],
+});
+```
+
+### Delete Memory
+
+```typescript
+await client.deleteMemory(memoryId);
+```
+
+### List Memories
+
+```typescript
+// List all memories
+const memories = await client.listMemories();
+
+// Filter by tier
+const hotMemories = await client.listMemories({
+  tier: 'hot',
+  limit: 50,
+  offset: 0,
+});
+```
+
+### Get Statistics
+
+```typescript
+const stats = await client.getMemoryStats();
+console.log(stats);
+// {
+//   totalMemories: 1500,
+//   hotTier: 200,
+//   warmTier: 800,
+//   coldTier: 500,
+//   totalTokens: 45000,
+//   avgSalience: 0.65
+// }
+```
+
+## Tag Management
+
+```typescript
+// Add tags to a memory
+await client.addTags(memoryId, ['important', 'follow-up']);
+
+// Remove tags
+await client.removeTags(memoryId, ['follow-up']);
+
+// Replace all tags
+await client.setTags(memoryId, ['new-tag-set']);
+
+// Filter memories by tags
+const tagged = await client.filterByTags(['important'], 'any');
+
+// List all tags with counts
+const allTags = await client.listAllTags();
+
+// Get tag statistics
+const tagStats = await client.getTagStats();
+```
+
+## Agent Operations
+
+```typescript
+// Create an agent
+const agentId = await client.createAgent({
+  name: 'research-assistant',
+  model: 'gpt-4',
+  systemPrompt: 'You are a helpful research assistant.',
+});
+
+// Execute a task
+const result = await client.executeTask(agentId, {
+  task: 'Summarize the key points from recent meetings',
+  context: 'User is preparing for Q1 planning',
+});
+
+// Get agent status
+const agent = await client.getAgent(agentId);
+
+// List all agents
+const agents = await client.listAgents();
+
+// Delete agent
+await client.deleteAgent(agentId);
+```
+
+## API Key Management
+
+```typescript
+// Create a new API key
+const apiKey = await client.createApiKey({
+  name: 'Production API Key',
+  expiresAt: new Date('2025-01-01'),
+});
+
+// List API keys
+const keys = await client.listApiKeys();
+
+// Revoke an API key
+await client.revokeApiKey(keyId);
+
+// Delete an API key
+await client.deleteApiKey(keyId);
+```
+
+## Session Management
+
+```typescript
+// List active sessions
+const sessions = await client.listSessions();
+
+// Revoke a specific session
+await client.revokeSession(sessionId);
+
+// Revoke all other sessions
+await client.revokeOtherSessions();
+
+// Revoke all sessions (logout everywhere)
+await client.revokeAllSessions();
+```
+
+## Error Handling
+
+```typescript
+import {
+  CilowError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError
+} from '@cilow/sdk';
+
+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}`);
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+const client = new CilowClient({
+  // API base URL (default: http://localhost:8080)
+  baseUrl: 'https://api.cilow.ai',
+
+  // API key for authentication
+  apiKey: 'cilow_your_api_key',
+
+  // JWT access token (alternative to API key)
+  accessToken: 'eyJhbGc...',
+
+  // Request timeout in milliseconds (default: 30000)
+  timeout: 60000,
+});
+```
+
+## Types
+
+All types are fully exported for TypeScript users:
+
+```typescript
+import type {
+  Memory,
+  MemoryStats,
+  SearchResult,
+  Agent,
+  User,
+  ApiKey,
+  AddMemoryOptions,
+  SearchMemoriesOptions,
+} from '@cilow/sdk';
+```
+
+## Self-Hosting
+
+Cilow can be self-hosted. Point the SDK to your instance:
+
+```typescript
+const client = new CilowClient({
+  baseUrl: 'http://localhost:8080',
+  apiKey: 'your-local-api-key',
+});
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- ES2020+ or modern browser with fetch support
+
+## License
+
+MIT