@lanonasis/ai-sdk 0.1.0 → 0.2.2

package/README.md

@@ -1,36 +1,279 @@
 # @lanonasis/ai-sdk
 
-Unified AI SDK facade for browser and Node, backed by `vortexai-l0` orchestrator.
+Drop-in AI SDK for browser and Node.js applications with persistent memory, chat completions, and vortexai-l0 orchestration.
+
+## Version
+
+**Current Release:** v0.2.1
+
+## Features
+
+- 🔑 **API Key Authentication** - Secure `lano_xxx...` format keys
+- 💾 **Persistent Memory** - Built-in integration with `@lanonasis/memory-sdk-standalone`
+- 🌊 **Streaming Support** - Real-time response streaming
+- 🎭 **Orchestration** - Complex multi-agent workflows via vortexai-l0
+- ⚛️ **React Hooks** - First-class React integration
+- 📦 **Tree-shakeable** - Only import what you need
+- 🔒 **Type-safe** - Full TypeScript support
 
 ## Installation
+
 ```bash
 npm install @lanonasis/ai-sdk
 # or
 bun add @lanonasis/ai-sdk
 ```
 
-## Usage (Browser / Frontend)
-The default export is browser-safe (ESM, no Node-only deps).
+## Environment Setup
+
+Add your API key to your environment:
+
+```bash
+# .env.local (Next.js) or .env
+LANONASIS_API_KEY=lano_your_api_key_here
+
+# For client-side usage in Next.js
+NEXT_PUBLIC_LANONASIS_API_KEY=lano_your_api_key_here
+```
+
+Once configured, the SDK works seamlessly with no additional setup required.
+
+## Quick Start
+
 ```ts
-import { AiSDK } from '@lanonasis/ai-sdk';
+import { LanonasisAI } from '@lanonasis/ai-sdk';
 
-const sdk = new AiSDK();
-const res = await sdk.orchestrate('create viral TikTok campaign');
-console.log(res.message);
+// Initialize with API key from environment
+const ai = new LanonasisAI({
+  apiKey: process.env.LANONASIS_API_KEY!,
+  // baseUrl defaults to https://api.lanonasis.com
+});
+
+// Simple message
+const response = await ai.send('Hello, who are you?');
+console.log(response);
+
+// Chat with full control
+const result = await ai.chat({
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What is 2+2?' },
+  ],
+  model: 'gpt-4o-mini',
+  temperature: 0.7,
+  maxTokens: 1000,
+});
+
+console.log(result.response);
+```
+
+## Detailed Examples
+
+### Basic Chat Completion
+
+```ts
+import { LanonasisAI } from '@lanonasis/ai-sdk';
+
+const ai = new LanonasisAI({
+  apiKey: process.env.LANONASIS_API_KEY!,
+});
+
+// Single turn conversation
+const response = await ai.chat({
+  messages: [
+    { role: 'user', content: 'Explain quantum computing in simple terms' }
+  ],
+  model: 'gpt-4o-mini',
+});
+
+console.log(response.response);
+// Output: "Quantum computing is like having a super-powered calculator..."
 ```
 
-## Usage (Node)
+### Multi-turn Conversation
+
 ```ts
-import { AiSDK } from '@lanonasis/ai-sdk';
+const ai = new LanonasisAI({ apiKey: process.env.LANONASIS_API_KEY! });
+
+// Build conversation history
+const messages = [
+  { role: 'system', content: 'You are a coding assistant specializing in TypeScript.' },
+  { role: 'user', content: 'How do I create a generic function?' },
+];
+
+const response1 = await ai.chat({ messages });
+console.log(response1.response);
+
+// Continue the conversation
+messages.push({ role: 'assistant', content: response1.response });
+messages.push({ role: 'user', content: 'Can you show me an example with arrays?' });
+
+const response2 = await ai.chat({ messages });
+console.log(response2.response);
+```
+
+### With Persistent Memory
+
+The SDK automatically integrates with `@lanonasis/memory-sdk-standalone`:
+
+```ts
+const ai = new LanonasisAI({
+  apiKey: process.env.LANONASIS_API_KEY!,
+  memory: {
+    enabled: true,
+    autoSave: true,
+    contextStrategy: 'relevance',
+  },
+});
+
+// Store important information
+await ai.memory.createMemory({
+  title: 'User Preferences',
+  content: 'User prefers dark mode and concise responses',
+  status: 'active',
+});
 
+// Search memories
+const memories = await ai.memory.searchMemories({
+  query: 'user preferences',
+  status: 'active',
+  threshold: 0.7,
+});
+
+// Chat with memory context
+const response = await ai.chat({
+  messages: [{ role: 'user', content: 'Remember my preferences?' }],
+  conversationId: 'user-123-session',
+});
+
+// Get context from memories
+const context = await ai.memory.searchWithContext('previous conversations');
+```
+
+## Streaming Responses
+
+```ts
+// Async iterator style
+for await (const chunk of ai.chatStream({
+  messages: [{ role: 'user', content: 'Tell me a story' }],
+})) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+
+// Callback style
+await ai.streamChat(
+  { messages: [{ role: 'user', content: 'Count to 10' }] },
+  (chunk) => console.log(chunk.choices[0]?.delta?.content)
+);
+```
+
+## Orchestration
+
+Use vortexai-l0 for complex workflows:
+
+```ts
+// Remote API orchestration (default)
+const result = await ai.orchestrate('Create a viral TikTok campaign');
+
+// Local orchestration (no API call)
+const ai = new LanonasisAI({
+  apiKey: 'lnss_xxx',
+  useLocalOrchestration: true,
+});
+const result = await ai.orchestrate('analyze trending hashtags');
+```
+
+## React Integration
+
+```tsx
+import { useLanonasis, useChat } from '@lanonasis/ai-sdk/react';
+
+function ChatComponent() {
+  const { client, isReady } = useLanonasis({
+    apiKey: process.env.NEXT_PUBLIC_LANONASIS_KEY!,
+  });
+
+  const { messages, send, isLoading, sendWithStream } = useChat({
+    client,
+    systemPrompt: 'You are a helpful assistant.',
+  });
+
+  return (
+    <div>
+      {messages.map((msg, i) => (
+        <div key={i} className={msg.role}>{msg.content}</div>
+      ))}
+      {isLoading && <div>Thinking...</div>}
+    </div>
+  );
+}
+```
+
+## Configuration
+
+```ts
+new LanonasisAI({
+  apiKey: string;              // Required: lano_xxx format
+  baseUrl?: string;            // Default: https://api.lanonasis.com
+  memoryUrl?: string;          // Default: same as baseUrl
+  timeout?: number;            // Default: 30000 (30s)
+  maxRetries?: number;         // Default: 3
+  debug?: boolean;             // Default: false
+  organizationId?: string;     // For multi-tenant setups
+  useLocalOrchestration?: bool // Use vortexai-l0 locally
+  memory?: {
+    enabled?: boolean;         // Default: true
+    autoSave?: boolean;        // Default: true
+    contextStrategy?: string;  // 'relevance' | 'temporal' | 'hybrid'
+    maxContextTokens?: number; // Default: 4000
+  };
+});
+```
+
+## API Endpoints
+
+The SDK connects to these endpoints by default:
+
+| Feature | Endpoint |
+|---------|----------|
+| Chat Completions | `POST /v1/chat/completions` |
+| Memory API | `GET/POST /api/v1/memory` |
+| Health Check | `GET /health` |
+
+All requests are authenticated via the `Authorization: Bearer lano_xxx` header.
+
+## Architecture
+
+This SDK integrates with existing Lanonasis infrastructure:
+
+- **@lanonasis/memory-sdk** - Persistent memory and context building
+- **vortexai-l0** - Local orchestration engine
+- **Backend API** - Chat completions and remote orchestration
+
+## Migration from v0.1.0
+
+```ts
+// Old (v0.1.0)
+import { AiSDK } from '@lanonasis/ai-sdk';
 const sdk = new AiSDK();
-const res = await sdk.orchestrate('analyze trending hashtags');
-console.log(res.workflow);
+await sdk.orchestrate('query');
+
+// New (v0.2.x)
+import { LanonasisAI } from '@lanonasis/ai-sdk';
+const ai = new LanonasisAI({ apiKey: process.env.LANONASIS_API_KEY! });
+await ai.orchestrate('query');
+// Or simple:
+const message = await ai.send('query');
 ```
 
+## License
+
+MIT
+
 ## Advanced (Plugins)
+
 ```ts
-import { AiSDK, createPluginManager } from '@lanonasis/ai-sdk';
+import { LanonasisAI, createPluginManager } from '@lanonasis/ai-sdk';
 
 const plugins = createPluginManager();
 plugins.register({

package/dist/client.d.ts

@@ -0,0 +1,79 @@
+/**
+ * LanonasisAI - Main SDK Client
+ *
+ * Drop-in AI SDK that integrates with existing Lanonasis infrastructure:
+ * - @lanonasis/memory-sdk for persistent memory and context
+ * - vortexai-l0 for local orchestration
+ * - Backend API for chat completions
+ */
+import MemoryClient from '@lanonasis/memory-sdk-standalone';
+import type { LanonasisConfig, ChatRequest, ChatResponse, ChatStreamChunk, OrchestrateRequest, OrchestrateResponse, ApiKeyInfo, StreamCallback, EventType, EventHandler } from './types/index.js';
+export declare class LanonasisAI {
+    private http;
+    private localOrchestrator;
+    private eventHandlers;
+    /** Memory client from @lanonasis/memory-sdk */
+    readonly memory: MemoryClient;
+    /** SDK configuration */
+    readonly config: Required<Omit<LanonasisConfig, 'memory'>> & {
+        memory: LanonasisConfig['memory'];
+    };
+    constructor(config: LanonasisConfig);
+    on(event: EventType, handler: EventHandler): () => void;
+    off(event: EventType, handler: EventHandler): void;
+    private emit;
+    /**
+     * Send a chat message with optional memory context
+     */
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Simple message send (convenience method)
+     */
+    send(message: string, options?: Partial<ChatRequest>): Promise<string>;
+    /**
+     * Stream chat response
+     */
+    chatStream(request: ChatRequest): AsyncGenerator<ChatStreamChunk, void, unknown>;
+    /**
+     * Stream with callback (alternative API)
+     */
+    streamChat(request: ChatRequest, onChunk: StreamCallback): Promise<ChatResponse>;
+    /**
+     * Orchestrate a complex request
+     * Uses local vortexai-l0 or remote API based on config
+     */
+    orchestrate(request: OrchestrateRequest | string): Promise<OrchestrateResponse>;
+    /**
+     * Convert L0Orchestrator response to OrchestrateResponse format
+     */
+    private convertL0Response;
+    /**
+     * Build context from memory using memory-sdk's searchWithContext
+     */
+    private buildMemoryContext;
+    /**
+     * Inject context into messages
+     */
+    private injectContext;
+    /**
+     * Save conversation to memory
+     */
+    private saveToMemory;
+    validateKey(): Promise<ApiKeyInfo>;
+    getUsage(): Promise<ApiKeyInfo['usage']>;
+    getRateLimitStatus(): {
+        remaining: number;
+        reset: number;
+    };
+    healthCheck(): Promise<{
+        status: 'ok' | 'error';
+        latency: number;
+    }>;
+    memoryHealth(): Promise<{
+        status: 'ok' | 'error';
+    }>;
+    withConfig(overrides: Partial<LanonasisConfig>): LanonasisAI;
+    private debug;
+}
+export declare function createClient(config: LanonasisConfig): LanonasisAI;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,YAAyD,MAAM,kCAAkC,CAAC;AAGzG,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAEnB,UAAU,EACV,cAAc,EACd,SAAS,EACT,YAAY,EAGb,MAAM,kBAAkB,CAAC;AAM1B,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,aAAa,CAAgD;IAErE,+CAA+C;IAC/C,SAAgB,MAAM,EAAE,YAAY,CAAC;IAErC,wBAAwB;IACxB,SAAgB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,GAAG;QAAE,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;gBAE9F,MAAM,EAAE,eAAe;IA2CnC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI;IAQvD,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAIlD,OAAO,CAAC,IAAI;IAeZ;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAiDvD;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAa5E;;OAEG;IACI,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC;IAwDvF;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAuCtF;;;OAGG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAwCrF;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;YACW,kBAAkB;IAyBhC;;OAEG;IACH,OAAO,CAAC,aAAa;IAkBrB;;OAEG;YACW,YAAY;IA8BpB,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC;IAKlC,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAK9C,kBAAkB;;;;IAIZ,WAAW,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAUnE,YAAY,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,GAAG,OAAO,CAAA;KAAE,CAAC;IAKzD,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,WAAW;IAO5D,OAAO,CAAC,KAAK;CAKd;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,WAAW,CAEjE"}