@lantanios/agentic-server 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,397 @@
+# @lantanios/agentic-server
+
+Real-time Socket.IO server combining memory, audio, and event communication for AI agents.
+
+## Features
+
+- 🔌 **Socket.IO namespaces** — Separate channels for memory, audio, events
+- 🧠 **Memory namespace** — CRUD + vector search via WebSocket
+- 🎙️ **Audio namespace** — Real-time STT/TTS streaming
+- 📡 **Events namespace** — Pub/sub, broadcast, direct messaging between agents
+- 🔄 **Priority providers** — Local-first audio with cloud fallback
+
+## Installation
+
+```bash
+npm install @lantanios/agentic-server
+```
+
+## Configuration
+
+Create `.env`:
+
+```bash
+# Server
+PORT=3847
+CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# MongoDB (required)
+MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/Agentic
+
+# OpenAI (required for embeddings, optional for TTS)
+OPENAI_API_KEY=sk-...
+
+# Local audio server (optional, for local STT/TTS)
+LOCAL_STT_ENDPOINT=http://localhost:8001
+LOCAL_TTS_ENDPOINT=http://localhost:8001
+
+# Cloud fallbacks (optional)
+DEEPGRAM_API_KEY=...
+```
+
+## Quick Start
+
+### Run the Server
+
+```bash
+# Using npx
+npx @lantanios/agentic-server
+
+# Or in code
+import '@lantanios/agentic-server';
+```
+
+### Connect from Client
+
+```typescript
+import { io } from 'socket.io-client';
+
+// Connect to memory namespace
+const memory = io('http://localhost:3847/memory', {
+  auth: { agentId: 'pip' }  // Required: your agent ID
+});
+
+// Connect to audio namespace
+const audio = io('http://localhost:3847/audio', {
+  auth: { agentId: 'pip' }
+});
+
+// Connect to events namespace
+const events = io('http://localhost:3847/events', {
+  auth: { agentId: 'pip' }
+});
+```
+
+## Socket.IO Namespaces
+
+### `/memory` — Memory Operations
+
+All operations require `agentId` in auth. Agents can only access their own memories.
+
+#### Create Memory
+
+```typescript
+memory.emit('create', {
+  type: 'fact',
+  content: 'User prefers dark mode',
+  metadata: {
+    importance: 4,
+    tags: ['preferences', 'ui'],
+    project: 'settings',
+  }
+}, (response) => {
+  if (response.success) {
+    console.log('Created:', response.memory);
+  }
+});
+```
+
+#### List Memories
+
+```typescript
+memory.emit('list', {
+  type: 'fact',           // optional filter
+  project: 'settings',    // optional filter
+  minImportance: 3,       // optional filter
+  limit: 20,
+  offset: 0,
+}, (response) => {
+  console.log(response.memories);
+  console.log(`Total: ${response.total}`);
+});
+```
+
+#### Vector Search
+
+```typescript
+memory.emit('search', {
+  query: 'what are the user preferences?',
+  limit: 10,
+  minScore: 0.7,
+}, (response) => {
+  response.results.forEach(r => {
+    console.log(`${r.score.toFixed(2)}: ${r.content}`);
+  });
+});
+```
+
+#### Recall Context
+
+```typescript
+memory.emit('recall', {
+  context: 'Starting work on the Lantanios project',
+  limit: 30,
+}, (response) => {
+  console.log('Important:', response.breakdown.important);
+  console.log('Context-matched:', response.breakdown.contextMatched);
+  console.log('Recent:', response.breakdown.recent);
+  console.log('Memories:', response.memories);
+});
+```
+
+#### Other Operations
+
+```typescript
+// Get single memory
+memory.emit('get', memoryId, callback);
+
+// Update memory
+memory.emit('update', { id: memoryId, content: 'Updated content' }, callback);
+
+// Delete memory (soft delete)
+memory.emit('delete', memoryId, callback);
+
+// Get summary stats
+memory.emit('summary', (response) => {
+  console.log(response.summary);
+});
+```
+
+### `/audio` — Audio Streaming
+
+#### Stream Recording
+
+```typescript
+// Start recording
+audio.emit('stream:start', {}, (response) => {
+  console.log('Recording started');
+});
+
+// Send audio chunks (from microphone)
+mediaRecorder.ondataavailable = (e) => {
+  audio.emit('stream:chunk', e.data);
+};
+
+// Stop and get transcription
+audio.emit('stream:stop', { language: 'en' }, (response) => {
+  if (response.success) {
+    console.log('Transcript:', response.result.text);
+  }
+});
+
+// Also emitted as event
+audio.on('transcription', (result) => {
+  console.log('Transcript:', result.text);
+});
+```
+
+#### One-shot Transcription
+
+```typescript
+audio.emit('transcribe', {
+  audio: audioBuffer,  // Buffer or ArrayBuffer
+  language: 'en',
+  provider: 'local-whisper',  // optional: force provider
+}, (response) => {
+  console.log(response.result.text);
+});
+```
+
+#### Text to Speech
+
+```typescript
+// One-shot TTS
+audio.emit('speak', {
+  text: 'Hello, how can I help you?',
+  voice: 'nova',
+  speed: 1.0,
+  format: 'mp3',
+}, (response) => {
+  if (response.success) {
+    playAudio(response.audio);  // Buffer
+  }
+});
+
+// Streaming TTS
+audio.emit('speak:stream', {
+  text: 'This is a long response that will be streamed...',
+  voice: 'nova',
+});
+
+audio.on('speak:start', () => console.log('TTS started'));
+audio.on('speak:chunk', (chunk) => streamToSpeaker(chunk));
+audio.on('speak:end', () => console.log('TTS finished'));
+audio.on('speak:error', (err) => console.error(err));
+```
+
+#### Check Providers
+
+```typescript
+audio.emit('providers:status', (response) => {
+  console.log(response.status);
+  // { stt: { 'local-whisper': true }, tts: { 'local-piper': false, 'openai-tts': true } }
+});
+```
+
+### `/events` — Agent Communication
+
+#### Subscribe to Channels
+
+```typescript
+events.emit('subscribe', 'project-updates', (response) => {
+  console.log(`Subscribed to ${response.channel}`);
+});
+
+events.emit('unsubscribe', 'project-updates', callback);
+```
+
+#### Publish to Channel
+
+```typescript
+events.emit('publish', {
+  channel: 'project-updates',
+  event: 'task-completed',
+  payload: { taskId: '123', status: 'done' },
+}, (response) => {
+  console.log(`Delivered to ${response.delivered} subscribers`);
+});
+
+// Receive events
+events.on('event', (data) => {
+  console.log(`[${data.channel}] ${data.event} from ${data.from}:`, data.payload);
+});
+```
+
+#### Broadcast to All Agents
+
+```typescript
+events.emit('broadcast', {
+  event: 'system-alert',
+  payload: { message: 'Server restarting in 5 minutes' },
+}, (response) => {
+  console.log(`Broadcast to ${response.delivered} agents`);
+});
+
+events.on('broadcast', (data) => {
+  console.log(`Broadcast from ${data.from}:`, data.event, data.payload);
+});
+```
+
+#### Direct Message
+
+```typescript
+events.emit('dm', {
+  to: 'deep',  // Target agent ID
+  event: 'private-message',
+  payload: { text: 'Hey Deep, can you check the Lantanios logs?' },
+}, (response) => {
+  console.log(response.delivered ? 'Delivered' : 'Agent not online');
+});
+
+events.on('dm', (data) => {
+  console.log(`DM from ${data.from}:`, data.event, data.payload);
+});
+```
+
+#### List Online Agents
+
+```typescript
+events.emit('agents:list', (response) => {
+  console.log('Online agents:', response.agents);
+  // ['pip', 'deep']
+});
+```
+
+## REST Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Health check with MongoDB and socket status |
+| `GET` | `/providers` | Audio provider availability |
+
+```bash
+curl http://localhost:3847/health
+# { "status": "ok", "mongodb": "connected", "sockets": 2 }
+
+curl http://localhost:3847/providers
+# { "status": "ok", "providers": { "stt": {...}, "tts": {...} } }
+```
+
+## Architecture
+
+```
+Client (Browser/Node)
+    │
+    ├── Socket.IO ─────► /memory  ────► MongoDB + OpenAI Embeddings
+    │
+    ├── Socket.IO ─────► /audio   ────► Local Whisper/Piper
+    │                                   └──► Deepgram/OpenAI (fallback)
+    │
+    └── Socket.IO ─────► /events  ────► Pub/Sub (in-memory)
+```
+
+## Example: Full Agent Connection
+
+```typescript
+import { io } from 'socket.io-client';
+
+class AgentClient {
+  private memory;
+  private audio;
+  private events;
+
+  constructor(serverUrl: string, agentId: string) {
+    const auth = { agentId };
+
+    this.memory = io(`${serverUrl}/memory`, { auth });
+    this.audio = io(`${serverUrl}/audio`, { auth });
+    this.events = io(`${serverUrl}/events`, { auth });
+
+    // Subscribe to relevant channels
+    this.events.emit('subscribe', 'system');
+    this.events.on('event', this.handleEvent.bind(this));
+    this.events.on('dm', this.handleDM.bind(this));
+  }
+
+  async remember(content: string, type = 'fact', importance = 3) {
+    return new Promise((resolve) => {
+      this.memory.emit('create', { type, content, metadata: { importance } }, resolve);
+    });
+  }
+
+  async search(query: string) {
+    return new Promise((resolve) => {
+      this.memory.emit('search', { query, limit: 10 }, resolve);
+    });
+  }
+
+  async transcribe(audioBuffer: Buffer) {
+    return new Promise((resolve) => {
+      this.audio.emit('transcribe', { audio: audioBuffer }, resolve);
+    });
+  }
+
+  async speak(text: string) {
+    return new Promise((resolve) => {
+      this.audio.emit('speak', { text }, resolve);
+    });
+  }
+
+  private handleEvent(data) {
+    console.log(`Event from ${data.from}:`, data.event);
+  }
+
+  private handleDM(data) {
+    console.log(`DM from ${data.from}:`, data.payload);
+  }
+}
+
+// Usage
+const agent = new AgentClient('http://localhost:3847', 'pip');
+await agent.remember('User asked about weather', 'conversation', 2);
+const results = await agent.search('weather conversations');
+```
+
+## License
+
+Private - Lantanios

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lantanios/agentic-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Real-time server with Socket.IO for memory and audio streaming",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,13 @@
     "start": "node dist/index.js",
     "lint": "eslint src --ext .ts"
   },
-  "keywords": ["socket.io", "realtime", "audio", "memory", "ai"],
+  "keywords": [
+    "socket.io",
+    "realtime",
+    "audio",
+    "memory",
+    "ai"
+  ],
   "author": "Lantanios",
   "license": "UNLICENSED",
   "publishConfig": {