@sovant/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sovant 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,370 @@
+# Sovant JavaScript/TypeScript SDK
+
+Official JavaScript/TypeScript SDK for the Sovant Memory API. Build AI applications with persistent memory, semantic search, and intelligent context management.
+
+> **Note: Coming Soon!** This SDK is currently in development and will be available on npm soon. In the meantime, you can use our REST API directly.
+
+## Installation
+
+```bash
+# Coming soon
+npm install @sovant/sdk
+# or
+yarn add @sovant/sdk
+# or
+pnpm add @sovant/sdk
+```
+
+## Quick Start
+
+```javascript
+import { SovantClient } from "@sovant/sdk";
+
+// Initialize the client
+const client = new SovantClient("YOUR_API_KEY");
+
+// Create a memory
+const memory = await client.memories.create({
+  content: "User prefers dark mode interfaces",
+  type: "preference",
+  metadata: {
+    category: "ui_preferences",
+    confidence: 0.95,
+  },
+});
+
+console.log("Created memory:", memory.id);
+
+// Search memories
+const results = await client.memories.search({
+  query: "What are the user's UI preferences?",
+  limit: 5,
+});
+
+results.forEach((result) => {
+  console.log(`- ${result.content} (relevance: ${result.relevance_score})`);
+});
+```
+
+## Features
+
+- 🚀 **Full TypeScript Support** - Complete type definitions for all methods
+- 🔄 **Async/Await** - Modern promise-based API
+- 🔁 **Automatic Retries** - Built-in retry logic for network failures
+- 📦 **Batch Operations** - Efficient bulk create/delete operations
+- 🎯 **Smart Search** - Semantic, keyword, and hybrid search modes
+- 🧵 **Thread Management** - Organize memories into contextual threads
+- 📊 **Analytics** - Built-in insights and statistics
+- ⚡ **Tree-Shakeable** - Only import what you need
+
+## Configuration
+
+```javascript
+const client = new SovantClient({
+  apiKey: "YOUR_API_KEY",
+  baseUrl: "https://api.sovant.ai/v1", // Optional
+  timeout: 30000, // Request timeout in ms
+  maxRetries: 3, // Number of retries for failed requests
+  retryDelay: 1000, // Delay between retries in ms
+});
+```
+
+You can also use environment variables:
+
+```bash
+export SOVANT_API_KEY="YOUR_API_KEY"
+```
+
+```javascript
+const client = new SovantClient(process.env.SOVANT_API_KEY);
+```
+
+## Memory Operations
+
+### Create a Memory
+
+```javascript
+const memory = await client.memories.create({
+  content: "The user completed the onboarding tutorial",
+  type: "event",
+  importance: 0.8,
+  metadata: {
+    step_completed: "tutorial",
+    duration_seconds: 180,
+  },
+  tags: ["onboarding", "milestone"],
+  emotion: {
+    type: "positive",
+    intensity: 0.7,
+  },
+  action_items: ["Send welcome email", "Unlock advanced features"],
+});
+```
+
+### Update a Memory
+
+```javascript
+const updated = await client.memories.update(memory.id, {
+  importance: 0.9,
+  follow_up_required: true,
+  follow_up_due: "2024-12-31T23:59:59Z",
+});
+```
+
+### Search Memories
+
+```javascript
+// Semantic search
+const semanticResults = await client.memories.search({
+  query: "user achievements and milestones",
+  search_type: "semantic",
+  limit: 10,
+});
+
+// Filtered search
+const filteredResults = await client.memories.search({
+  query: "preferences",
+  type: ["preference", "decision"],
+  tags: ["important"],
+  created_after: "2024-01-01",
+  sort_by: "importance",
+  sort_order: "desc",
+});
+```
+
+### Batch Operations
+
+```javascript
+// Batch create
+const batchResult = await client.memories.createBatch([
+  { content: "Memory 1", type: "observation" },
+  { content: "Memory 2", type: "reflection" },
+  { content: "Memory 3", type: "learning" },
+]);
+
+console.log(`Created ${batchResult.success_count} memories`);
+console.log(`Failed ${batchResult.failed_count} memories`);
+
+// Batch delete
+const deleteResult = await client.memories.deleteBatch([
+  "mem_123",
+  "mem_456",
+  "mem_789",
+]);
+```
+
+## Thread Management
+
+### Create a Thread
+
+```javascript
+const thread = await client.threads.create({
+  name: "Project Planning Discussion",
+  description: "Capturing all decisions and ideas for Q1 project",
+  tags: ["project", "planning", "q1-2024"],
+});
+```
+
+### Add Memories to Thread
+
+```javascript
+// Add existing memories
+await client.threads.addMemories(thread.id, [memory1.id, memory2.id]);
+
+// Create and add in one operation
+const newMemory = await client.memories.create({
+  content: "Decided to use TypeScript for the project",
+  type: "decision",
+  thread_ids: [thread.id],
+});
+```
+
+### Get Thread with Memories
+
+```javascript
+const threadWithMemories = await client.threads.get(thread.id, true);
+
+console.log(`Thread: ${threadWithMemories.name}`);
+console.log(`Memories: ${threadWithMemories.memories.length}`);
+
+threadWithMemories.memories.forEach((memory) => {
+  console.log(`- ${memory.content}`);
+});
+```
+
+### Thread Analytics
+
+```javascript
+const stats = await client.threads.getStats(thread.id);
+
+console.log(`Total memories: ${stats.memory_count}`);
+console.log(`Average importance: ${stats.avg_importance}`);
+console.log(`Decisions made: ${stats.total_decisions}`);
+console.log(`Open questions: ${stats.total_questions}`);
+```
+
+## Error Handling
+
+The SDK provides typed error classes for different scenarios:
+
+```javascript
+import {
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NotFoundError,
+} from "@sovant/sdk";
+
+try {
+  const memory = await client.memories.get("invalid_id");
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.error("Memory not found");
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof ValidationError) {
+    console.error("Validation errors:", error.errors);
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides comprehensive type definitions:
+
+```typescript
+import {
+  Memory,
+  Thread,
+  SearchResult,
+  MemoryType,
+  EmotionType,
+} from "@sovant/sdk";
+
+// All methods are fully typed
+const createMemory = async (
+  content: string,
+  type: MemoryType,
+): Promise<Memory> => {
+  return client.memories.create({ content, type });
+};
+
+// Type-safe emotion handling
+const emotions: EmotionType[] = ["happy", "excited", "calm"];
+```
+
+## Advanced Usage
+
+### Memory Insights
+
+```javascript
+const insights = await client.memories.getInsights({
+  time_range: "last_30_days",
+  group_by: "type",
+});
+
+console.log("Memory distribution:", insights.type_distribution);
+console.log("Emotion distribution:", insights.emotion_distribution);
+console.log("Growth rate:", `${insights.growth_rate}%`);
+```
+
+### Related Memories
+
+```javascript
+const related = await client.memories.getRelated(memory.id, {
+  limit: 5,
+  threshold: 0.7,
+});
+
+console.log("Related memories:");
+related.forEach((r) => {
+  console.log(`- ${r.content} (similarity: ${r.relevance_score})`);
+});
+```
+
+### Thread Merging
+
+```javascript
+// Merge multiple threads into one
+const mergedThread = await client.threads.merge(mainThread.id, [
+  thread2.id,
+  thread3.id,
+]);
+```
+
+## React Hooks (Coming Soon)
+
+```javascript
+import { useMemory, useThread, useSearch } from "@sovant/sdk/react";
+
+function MyComponent() {
+  const { memories, loading, error } = useMemory({
+    type: "preference",
+    limit: 10,
+  });
+
+  const { results, search } = useSearch();
+
+  // Component logic...
+}
+```
+
+## API Reference
+
+### Client Methods
+
+- `new SovantClient(apiKey)` - Create a new client instance
+- `client.ping()` - Test API connection
+- `client.getUsage()` - Get current API usage and quota
+
+### Memory Methods
+
+- `client.memories.create(data)` - Create a new memory
+- `client.memories.get(id)` - Get a memory by ID
+- `client.memories.update(id, data)` - Update a memory
+- `client.memories.delete(id)` - Delete a memory
+- `client.memories.list(options)` - List memories with pagination
+- `client.memories.search(options)` - Search memories
+- `client.memories.createBatch(memories)` - Batch create memories
+- `client.memories.deleteBatch(ids)` - Batch delete memories
+- `client.memories.getInsights(options)` - Get memory analytics
+- `client.memories.archive(id)` - Archive a memory
+- `client.memories.pin(id)` - Pin a memory
+- `client.memories.getRelated(id, options)` - Get related memories
+
+### Thread Methods
+
+- `client.threads.create(data)` - Create a new thread
+- `client.threads.get(id, includeMemories)` - Get a thread
+- `client.threads.update(id, data)` - Update a thread
+- `client.threads.delete(id, deleteMemories)` - Delete a thread
+- `client.threads.list(options)` - List threads with pagination
+- `client.threads.addMemories(id, memoryIds)` - Add memories to thread
+- `client.threads.removeMemories(id, memoryIds)` - Remove memories from thread
+- `client.threads.getMemories(id, options)` - Get memories in thread
+- `client.threads.getStats(id)` - Get thread statistics
+- `client.threads.search(options)` - Search threads
+- `client.threads.merge(targetId, sourceIds)` - Merge threads
+- `client.threads.clone(id, options)` - Clone a thread
+
+## Examples
+
+Check out the [examples directory](https://github.com/sovant-ai/javascript-sdk/tree/main/examples) for complete working examples:
+
+- Basic CRUD operations
+- Advanced search techniques
+- Thread management workflows
+- Error handling patterns
+- TypeScript usage
+- React integration
+
+## Support
+
+- 📚 [Documentation](https://docs.sovant.ai)
+- 💬 [Discord Community](https://discord.gg/sovant)
+- 🐛 [Issue Tracker](https://github.com/sovant-ai/javascript-sdk/issues)
+- 📧 [Email Support](mailto:support@sovant.ai)
+
+## License
+
+MIT © Sovant AI