@sovant/sdk 1.1.2 → 1.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Sovant AI
+Copyright (c) 2025 Sovant
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,9 +1,26 @@
-# Sovant JavaScript/TypeScript SDK
+# @sovant/sdk
 
-Sovant is Memory-as-a-Service: a durable, queryable memory layer for AI apps with cross-model recall, hybrid (semantic + deterministic) retrieval, and simple SDKs.
+**Sovant is a governed AI memory layer for LLM applications.**
+It gives your apps hybrid recall, profile-aware context, and a structured memory store you can audit, inspect, and control.
 
-[![npm version](https://img.shields.io/npm/v/@sovant/sdk.svg)](https://www.npmjs.com/package/@sovant/sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+The official **JavaScript and TypeScript** SDK for the Sovant Memory API.
+
+[![npm version](https://img.shields.io/npm/v/@sovant/sdk)](https://www.npmjs.com/package/@sovant/sdk)
+[![Documentation](https://img.shields.io/badge/docs-sovant.ai-blue)](https://sovant.ai/docs)
+[![GitHub](https://img.shields.io/badge/github-sovant-lightgrey)](https://github.com/sovant-ai/sovant)
+
+---
+
+## What is Sovant?
+
+Sovant is an **AI infrastructure company** providing the **memory layer for AI systems**.  
+Our platform makes it simple to persist, search, and manage conversational and contextual data securely across sessions, channels, and applications.
+
+- **Problem:** Most AI systems forget everything once a session ends. This causes compliance risks, knowledge loss, and poor user experience.  
+- **Solution:** Sovant provides a **Memory-as-a-Service API** — a single SDK and API key that lets you store, retrieve, and search memories with audit-ready controls.  
+- **Target audience:** Developers, startups, and enterprises building AI agents, copilots, or compliance-driven apps who need context persistence.
+
+---
 
 ## Installation
 
@@ -15,450 +32,143 @@ yarn add @sovant/sdk
 pnpm add @sovant/sdk
 ```
 
-## Quick Start
+## 60-Second Quickstart
+
+### TypeScript
 
 ```typescript
-import { Sovant } from '@sovant/sdk';
+import { Sovant } from "@sovant/sdk";
 
-// Initialize the client
-const sovant = new Sovant({
-  apiKey: 'sk_live_your_api_key_here',
-  baseUrl: 'https://sovant.ai', // Optional, defaults to https://sovant.ai
-});
+const sv = new Sovant({ apiKey: process.env.SOVANT_API_KEY! });
 
 // Create a memory
-const memory = await sovant.memory.create({
-  content: 'User prefers dark mode interfaces',
-  type: 'preference',
-  tags: ['ui', 'settings'],
+await sv.memory.create({
+  data: { note: "User prefers morning meetings" },
+  type: "preference"
 });
 
 // Search memories
-const results = await sovant.memory.search({
-  query: 'user preferences',
-  limit: 10,
-});
-
-// Update a memory
-const updated = await sovant.memory.update(memory.id, {
-  tags: ['ui', 'settings', 'theme'],
-});
-
-// Delete a memory
-await sovant.memory.delete(memory.id);
-```
-
-## Chat in 60 Seconds
-
-Stream real-time chat responses with memory context:
-
-```typescript
-import { Sovant } from '@sovant/sdk';
-
-const client = new Sovant({ apiKey: process.env.SOVANT_API_KEY, baseUrl: 'https://sovant.ai' });
-
-// Create a chat session
-const session = await client.chat.createSession({ title: 'Demo' });
-
-// Stream a response
-const stream = await client.chat.sendMessage(session.id, {
-  message: 'hello',
-  provider: 'openai',
-  model: 'gpt-4o-mini',
-  stream: true,
-  useMemory: true,
-});
-
-for await (const ev of stream) {
-  if (ev.type === 'delta') process.stdout.write(ev.data || '');
-}
-
-// Get chat history
-const messages = await client.chat.getMessages(session.id);
-```
-
-## Profile Recall Helpers
-
-Save and recall user profile facts with canonical patterns:
-
-```typescript
-// Extract profile entity from text
-const fact = await client.recall.extractProfile("i'm from kuching");
-// -> { entity: 'location', value: 'kuching' } | null
-
-if (fact) {
-  await client.recall.saveProfileFact(fact); // canonicalizes and persists
-}
-
-// Get all profile facts
-const profile = await client.recall.getProfileFacts();
-// -> { name?: string, age?: string|number, location?: string, preferences?: string[] }
-```
-
-## Configuration
-
-```typescript
-const sovant = new Sovant({
-  apiKey: 'sk_live_your_api_key_here',  // Required
-  baseUrl: 'https://sovant.ai',          // Optional, API endpoint
-  timeout: 30000,                        // Optional, request timeout in ms (default: 30000)
-  maxRetries: 3,                         // Optional, max retry attempts (default: 3)
-  debug: false,                          // Optional, enable debug logging (default: false)
-});
-```
-
-## API Reference
-
-### Memory Operations
-
-#### Create Memory
-
-```typescript
-const memory = await sovant.memory.create({
-  content: 'Customer contacted support about billing',
-  type: 'observation',              // 'journal' | 'insight' | 'observation' | 'task' | 'preference'
-  tags: ['support', 'billing'],
-  metadata: { ticketId: '12345' },
-  thread_id: 'thread_abc123',       // Optional thread association
-  importance_score: 0.8,            // 0-1 importance rating
-  emotional_tone: 'frustrated',
-  source: 'zendesk',
-});
-```
-
-#### List Memories
-
-```typescript
-const list = await sovant.memory.list({
-  limit: 20,                        // Max items per page (default: 20)
-  offset: 0,                        // Pagination offset
-  tags: ['billing'],                // Filter by tags
-  type: 'observation',              // Filter by type
-  is_archived: false,               // Filter archived status
-});
-
-console.log(list.memories);         // Array of memories
-console.log(list.total);           // Total count
-console.log(list.has_more);        // More pages available
-```
-
-#### Get Memory by ID
-
-```typescript
-const memory = await sovant.memory.get('mem_123abc');
-```
-
-#### Update Memory (Partial)
-
-```typescript
-const updated = await sovant.memory.update('mem_123abc', {
-  tags: ['support', 'billing', 'resolved'],
-  metadata: { 
-    ...memory.metadata,
-    resolved: true,
-  },
-  is_archived: true,
-});
-```
-
-#### Replace Memory (Full)
-
-```typescript
-const replaced = await sovant.memory.put('mem_123abc', {
-  content: 'Updated content here',  // Required for PUT
-  type: 'observation',
-  tags: ['updated'],
+const results = await sv.memory.search({
+  query: "meeting preferences",
+  limit: 3
 });
-```
-
-#### Delete Memory
 
-```typescript
-await sovant.memory.delete('mem_123abc');
+console.log(results);
 ```
 
-#### Search Memories
+### JavaScript (ESM)
 
-```typescript
-// Semantic search
-const semanticResults = await sovant.memory.search({
-  query: 'customer preferences about notifications',
-  limit: 10,
-  type: 'preference',
-});
-
-// Filter-based search
-const filterResults = await sovant.memory.search({
-  tags: ['settings', 'notifications'],
-  from_date: '2024-01-01',
-  to_date: '2024-12-31',
-  emotional_tone: 'positive',
-  limit: 20,
-});
-```
+```javascript
+import { Sovant } from "@sovant/sdk";
 
-#### Batch Operations
-
-```typescript
-const batch = await sovant.memory.batch({
-  operations: [
-    {
-      op: 'create',
-      data: {
-        content: 'First memory',
-        type: 'journal',
-      },
-    },
-    {
-      op: 'update',
-      id: 'mem_123abc',
-      data: {
-        tags: ['updated'],
-      },
-    },
-    {
-      op: 'delete',
-      id: 'mem_456def',
-    },
-  ],
-});
+const sv = new Sovant({ apiKey: process.env.SOVANT_API_KEY });
 
-console.log(batch.ok);              // All operations succeeded
-console.log(batch.results);         // Individual operation results
-console.log(batch.summary);         // Summary statistics
-```
-
-## Memory Types
-
-- **journal** - Chronological entries and logs
-- **insight** - Derived patterns and conclusions
-- **observation** - Factual, observed information
-- **task** - Action items and todos
-- **preference** - User preferences and settings
-
-## Error Handling
-
-The SDK provides typed errors for better error handling:
-
-```typescript
-import { Sovant, SovantError, NetworkError, TimeoutError } from '@sovant/sdk';
-
-try {
-  const memory = await sovant.memory.get('invalid_id');
-} catch (error) {
-  if (error instanceof SovantError) {
-    console.error('API Error:', error.message);
-    console.error('Error Code:', error.code);
-    console.error('Status:', error.status);
-    console.error('Request ID:', error.requestId);
-    
-    switch (error.status) {
-      case 401:
-        // Handle authentication error
-        break;
-      case 404:
-        // Handle not found
-        break;
-      case 429:
-        // Handle rate limiting
-        break;
-    }
-  } else if (error instanceof TimeoutError) {
-    console.error('Request timed out');
-  } else if (error instanceof NetworkError) {
-    console.error('Network error:', error.message);
-  }
-}
-```
-
-## Thread Management
-
-Associate memories with conversation threads:
-
-```typescript
-// Create memories within a thread
-const memory1 = await sovant.memory.create({
-  content: 'User asked about pricing',
-  thread_id: 'thread_conversation_123',
+// Create a memory
+await sv.memory.create({
+  data: "User prefers morning meetings",
+  type: "preference"
 });
 
-const memory2 = await sovant.memory.create({
-  content: 'User selected enterprise plan',
-  thread_id: 'thread_conversation_123',
+// Search memories
+const results = await sv.memory.search({
+  query: "meeting preferences",
+  limit: 3
 });
 
-// List memories in a thread
-const threadMemories = await sovant.memory.list({
-  thread_id: 'thread_conversation_123',
-});
+console.log(results);
 ```
 
-## API Key Management
-
-Manage API keys programmatically:
-
-```typescript
-// List all API keys
-const keys = await client.keys.list();
-console.log(keys); // Array of key objects
+### JavaScript (CommonJS)
 
-// Create a new API key
-const newKey = await client.keys.create({ name: 'CI key' });
-console.log(newKey.key); // The actual secret key (only shown once!)
+```javascript
+const { Sovant } = require("@sovant/sdk");
 
-// Update key metadata
-await client.keys.update(newKey.id, { name: 'Production key' });
+const sv = new Sovant({ apiKey: process.env.SOVANT_API_KEY });
 
-// Revoke a key
-await client.keys.revoke(newKey.id);
+// Works the same as ESM
+sv.memory.create({ data: "User likes coffee", type: "preference" })
+  .then(() => console.log("Memory saved!"));
 ```
 
-## Advanced Features
+## Recall vs Search
 
-### Retry Configuration
-
-The SDK automatically retries failed requests with exponential backoff:
-
-```typescript
-const sovant = new Sovant({
-  apiKey: 'sk_live_...',
-  maxRetries: 5,           // Increase retry attempts
-  timeout: 60000,          // Increase timeout for slow connections
-});
-```
+Sovant provides two ways to query memories:
 
-### Debug Mode
+- **`memory.recall()`** – Hybrid recall, profile-aware
+  Best for conversational AI queries like "What do you know about me?" or "What happened on Project X?".
+  Uses Sovant's hybrid pipeline (profile fast-path + thread-scoped lexical + vector semantic search) and prioritizes profile facts (name/age/location) when available.
 
-Enable debug logging to see detailed request/response information:
+- **`memory.search()`** – Semantic search
+  Best for topic-based lookup and discovery, e.g., "hiking", "Q1 marketing plan".
+  Pure vector similarity search without profile logic. Behavior unchanged from previous versions.
 
 ```typescript
-const sovant = new Sovant({
-  apiKey: 'sk_live_...',
-  debug: true,             // Enable debug output
+// Recall for conversational queries
+const context = await sv.memory.recall({
+  query: "what do you know about me?",
+  limit: 10
 });
-```
-
-### Custom Base URL
 
-Connect to different environments:
-
-```typescript
-const client = new Sovant({
-  apiKey: 'sk_live_...',
-  baseUrl: 'https://staging.sovant.ai',
+// Search for topic discovery
+const topics = await sv.memory.search({
+  query: "project updates",
+  limit: 5
 });
 ```
 
-## TypeScript Support
-
-The SDK is written in TypeScript and provides full type definitions:
-
-```typescript
-import type {
-  Memory,
-  MemoryType,
-  CreateMemoryInput,
-  SearchParams,
-  SearchResults,
-  BatchRequest,
-  BatchResponse,
-} from '@sovant/sdk';
-
-// All types are fully typed
-const createInput: CreateMemoryInput = {
-  content: 'Typed content',
-  type: 'journal',
-  tags: ['typed'],
-};
-
-const memory: Memory = await sovant.memory.create(createInput);
-```
-
-## Best Practices
+## Features
 
-1. **Use appropriate memory types** - Choose the correct type for your use case
-2. **Add meaningful tags** - Tags improve searchability and organization
-3. **Set importance scores** - Help prioritize critical memories
-4. **Use threads** - Group related memories together
-5. **Handle errors gracefully** - Implement proper error handling
-6. **Batch operations** - Use batch API for multiple operations
-7. **Archive don't delete** - Consider archiving instead of deleting
+- **Memory CRUD** — create, retrieve, update, delete memories
+- **Semantic Search** — query memories with filters and topK ranking
+- **Threads** — link related memories via thread_id (REST API)
+- **Batch Operations (Beta)** — atomic multi-operation support
+- **Compliance-ready** — audit trails, PDPA/GDPR-friendly by design
+- **SDKs** — official TypeScript and Python SDKs, with REST API reference
 
-## Examples
-
-### Customer Support Integration
-
-```typescript
-// Track customer interaction
-const interaction = await sovant.memory.create({
-  content: 'Customer reported slow dashboard loading',
-  type: 'observation',
-  thread_id: `ticket_${ticketId}`,
-  tags: ['support', 'performance', 'dashboard'],
-  metadata: {
-    ticketId,
-    customerId,
-    priority: 'high',
-  },
-  emotional_tone: 'frustrated',
-  source: 'zendesk',
-});
+## SDKs and Documentation
 
-// Record resolution
-const resolution = await sovant.memory.create({
-  content: 'Resolved by clearing cache and upgrading plan',
-  type: 'insight',
-  thread_id: `ticket_${ticketId}`,
-  tags: ['support', 'resolved'],
-  metadata: {
-    ticketId,
-    resolutionTime: '2h',
-  },
-});
-```
+- [TypeScript SDK Documentation](https://sovant.ai/docs/sdk/typescript)
+- [Python SDK on PyPI](https://pypi.org/project/sovant/)
+- [REST API Reference](https://sovant.ai/docs/api)
+- [Full Documentation](https://sovant.ai/docs)
 
-### User Preference Tracking
+## API Overview
 
-```typescript
-// Store preference
-const preference = await sovant.memory.create({
-  content: 'User prefers email notifications over SMS',
-  type: 'preference',
-  tags: ['notifications', 'email', 'settings'],
-  metadata: {
-    userId,
-    setting: 'notification_channel',
-    value: 'email',
-  },
-  importance_score: 0.9,
-});
+### Endpoints Summary
+- `POST /api/v1/memory` — Create memory
+- `GET /api/v1/memory` — List memories
+- `GET /api/v1/memories/{id}` — Get memory by ID
+- `PATCH|PUT /api/v1/memories/{id}` — Update memory
+- `DELETE /api/v1/memories/{id}` — Delete memory
+- `GET /api/v1/memory/search` — Search memories
+- `POST /api/v1/memory/batch` — Batch operations (Beta)
 
-// Query preferences
-const preferences = await sovant.memory.search({
-  type: 'preference',
-  tags: ['notifications'],
-});
-```
+## Field Mapping Note
 
-## Rate Limiting
+- **SDK level:** accepts `data`
+- **API level:** expects `content`
+- SDK automatically converts `data` → `content`.
+- `subject` is deprecated (ignored by API). Use `thread_id`, `tags`, or `metadata` for grouping.
 
-The API implements rate limiting. The SDK automatically handles rate limit responses with retries. Rate limit headers are included in responses:
+## Status of Advanced Features
 
-- `X-RateLimit-Limit` - Request limit per window
-- `X-RateLimit-Remaining` - Remaining requests
-- `X-RateLimit-Reset` - Reset timestamp
+- **Batch API:** Available, marked Beta.
+- **Threads:** Fully supported via REST API.
+- **Webhooks, personalization, multi-channel sync:** Coming soon.
 
-## Support
+## Versioning & Changelog
 
-- Documentation: [https://sovant.ai/docs](https://sovant.ai/docs)
-- API/Auth docs: [https://sovant.ai/docs/security/auth](https://sovant.ai/docs/security/auth)
-- Issues: [GitHub Issues](https://github.com/sovant-ai/javascript-sdk/issues)
-- Support: support@sovant.ai
+- **Current release:** 1.3.0
+- Version 1.3.0 adds hybrid recall with profile awareness
+- See [CHANGELOG.md](./CHANGELOG.md) for details.
 
-## Changelog
+## License & Use
 
-See [CHANGELOG.md](./CHANGELOG.md) for a detailed history of changes.
+- This SDK is MIT-licensed for integration convenience.
+- The Sovant API and platform are proprietary to Sovant Technologies Sdn. Bhd.
+- You may use this SDK to integrate with Sovant's hosted API.
+- Hosting/redistributing the Sovant backend or any proprietary components is not permitted.
 
 ## License
 
-MIT - See [LICENSE](LICENSE) file for details.
+MIT © Sovant AI