ai-sage-client 0.0.1

package/README.md

@@ -0,0 +1,85 @@
+# ai-sage-client
+
+The official Node.js SDK for **AI Sage Agent APM**.
+Auto-instrument your AI agents to capture logs, LLM calls, tool usage, and execution traces with a single line of code.
+
+## Features
+
+- 🔍 **Auto-Instrumentation**: Automatically captures `console.log`, `OpenAI` calls, and outbound `fetch`/`http` requests.
+- 🧵 **Context Aware**: Uses `AsyncLocalStorage` to keep logs isolated across concurrent user sessions.
+- 🛡️ **Active Governance**: Validate inputs against policies before execution using `aisage.check()`.
+- ⚡ **Zero Config**: Just set your API Key and go.
+
+## Installation
+
+```bash
+npm install ai-sage-client
+```
+
+## Usage
+
+### 1. Initialize
+
+Call `init()` at the start of your application (e.g., inside `server.js` or `app.ts`).
+
+```typescript
+import aisage from 'ai-sage-client';
+
+aisage.init({
+  apiKey: process.env.AISAGE_API_KEY,
+  // baseUrl: 'https://your-sage-instance.com' // Optional
+});
+```
+
+### 2. Wrap Agent Execution
+
+Wrap your agent's entry point with `aisage.run()`. This establishes the session context.
+
+```typescript
+import aisage from 'ai-sage-client';
+
+async function handleUserRequest(userInput: string) {
+  return aisage.run('chat_flow', async () => {
+    
+    // 1. Governance Check (Optional)
+    const check = await aisage.check(userInput);
+    if (!check.allowed) {
+        throw new Error(`Blocked: ${check.reason}`);
+    }
+
+    // 2. Your Agent Logic (Auto-captured!)
+    console.log('Processing user input:', userInput);
+    
+    const response = await openai.chat.completions.create({
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: userInput }]
+    });
+
+    // 3. Outbound Calls (Auto-captured!)
+    await fetch('https://api.weather.com/...');
+
+    return response.choices[0].message.content;
+  });
+}
+```
+
+### 3. Auto-Instrumentation
+
+To enable OpenAI capture, pass the `openai` instance:
+
+```typescript
+import OpenAI from 'openai';
+const openai = new OpenAI();
+
+// Enable auto-capture
+aisage.instrument(openai);
+```
+
+## Environment Variables
+
+- `AISAGE_API_KEY`: Your Agent API Key from the AI Sage Dashboard.
+- `AISAGE_BASE_URL`: (Optional) URL of the AI Sage ingestion API.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+interface ClientConfig {
+    apiKey?: string;
+    projectId?: string;
+    baseUrl?: string;
+    autoInstrument?: {
+        console?: boolean;
+        openai?: boolean;
+        http?: boolean;
+        process?: boolean;
+    };
+}
+interface LogEntry {
+    conversation_id: string;
+    type: 'trigger' | 'step' | 'user_input' | 'model_response' | 'tool_call' | 'tool_result' | 'error' | 'final_output';
+    content: any;
+    timestamp?: string;
+    metadata?: any;
+    duration_ms?: number;
+}
+declare class AiSageClient {
+    private config;
+    private logs;
+    private storage;
+    private isActive;
+    private flushInterval;
+    constructor();
+    init(config: ClientConfig): void;
+    stop(): void;
+    private startFlushLoop;
+    run<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    private checkStatus;
+    /**
+     * Active Governance Check: Validate input against policies before execution.
+     * @param input The user input or prompt to check
+     * @returns { allowed: boolean, reason?: string }
+     */
+    check(input: string): Promise<{
+        allowed: boolean;
+        reason?: string;
+    }>;
+    log(type: LogEntry['type'], content: any, metadata?: any): void;
+    flush(): Promise<void>;
+    instrument(openaiModule: any): void;
+    private interceptConsole;
+    private interceptHttp;
+}
+export declare const aisage: AiSageClient;
+export default aisage;

package/dist/index.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aisage = void 0;
+const uuid_1 = require("uuid");
+const async_hooks_1 = require("async_hooks");
+class AiSageClient {
+    constructor() {
+        this.config = {};
+        this.logs = [];
+        this.storage = new async_hooks_1.AsyncLocalStorage();
+        this.isActive = false;
+        this.flushInterval = null;
+    }
+    init(config) {
+        this.config = {
+            apiKey: config.apiKey || process.env.AISAGE_API_KEY,
+            baseUrl: config.baseUrl || "http://localhost:3000",
+            autoInstrument: {
+                console: true,
+                openai: true,
+                http: true,
+                ...config.autoInstrument
+            }
+        };
+        if (!this.config.apiKey) {
+            console.warn('[AiSage] No API Key provided. SDK disabled.');
+            return;
+        }
+        if (this.config.autoInstrument?.console) {
+            this.interceptConsole();
+        }
+        if (this.config.autoInstrument?.http) {
+            this.interceptHttp();
+        }
+        this.isActive = true;
+        this.startFlushLoop();
+        console.log('[AiSage] Initialized');
+    }
+    stop() {
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+            this.flushInterval = null;
+        }
+        this.isActive = false;
+    }
+    startFlushLoop() {
+        if (this.flushInterval)
+            clearInterval(this.flushInterval);
+        this.flushInterval = setInterval(() => this.flush(), 2000);
+    }
+    async run(name, fn) {
+        if (!this.isActive)
+            return fn();
+        const sessionId = (0, uuid_1.v4)();
+        const context = { sessionId };
+        return this.storage.run(context, async () => {
+            const start = Date.now();
+            try {
+                await this.checkStatus();
+            }
+            catch (e) {
+                console.error(`[AiSage] Blocked: ${e.message}`);
+                throw e;
+            }
+            this.log('trigger', { name, type: 'manual_run' });
+            try {
+                const result = await fn();
+                this.log('final_output', result, { duration_ms: Date.now() - start });
+                return result;
+            }
+            catch (e) {
+                this.log('error', { error: e.message, stack: e.stack }, { duration_ms: Date.now() - start });
+                throw e;
+            }
+        });
+    }
+    async checkStatus() {
+        return new Promise((resolve, reject) => {
+            // @ts-ignore
+            const fetchFn = fetch; // Use global fetch
+            fetchFn(`${this.config.baseUrl}/api/ingest`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'x-agent-key': this.config.apiKey },
+                body: JSON.stringify({ conversation_id: 'ping', logs: [] })
+            })
+                .then((res) => res.json())
+                .then((data) => {
+                if (data.agent_status === 'paused' || data.agent_status === 'disabled') {
+                    reject(new Error(`Agent is ${data.agent_status}`));
+                }
+                else {
+                    resolve();
+                }
+            })
+                .catch((err) => {
+                console.warn('[AiSage] Status check failed, proceeding anyway:', err.message);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Active Governance Check: Validate input against policies before execution.
+     * @param input The user input or prompt to check
+     * @returns { allowed: boolean, reason?: string }
+     */
+    async check(input) {
+        if (!this.isActive || !this.config.apiKey)
+            return { allowed: true };
+        try {
+            // Extract Agent ID from API Key (if encoded) or just use endpoint that resolves key
+            // Ideally we assume the endpoint handles key validation.
+            // But wait, the route is /api/agents/[agent_id]/check. We might not know agent_id in SDK if not passed.
+            // Let's use a generic /api/check endpoint that uses x-agent-key to resolve agent.
+            // Or assume baseUrl points to the right place. 
+            // Better: use /api/check or /api/govern and let backend resolve agent from key.
+            // For MVP, since I created /api/agents/[agent_id]/check, I need agent_id.
+            // The ClientConfig has propery `projectId` but not `agentId`.
+            // Let's change the route I created to be generic or update SDK to support generic check.
+            // I'll assume for now I can reach it via a generic path or update the backend path.
+            // Actually, I'll update the backend path to be `/api/govern` which is cleaner.
+            // Re-using baseUrl/api/ingest style -> baseUrl/api/govern
+            // @ts-ignore
+            const res = await fetch(`${this.config.baseUrl}/api/govern`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'x-agent-key': this.config.apiKey },
+                body: JSON.stringify({ input })
+            });
+            const data = await res.json();
+            return data;
+        }
+        catch (e) {
+            console.error('[AiSage] Governance check failed', e);
+            return { allowed: true }; // Fail open
+        }
+    }
+    log(type, content, metadata = {}) {
+        const store = this.storage.getStore();
+        if (!store) {
+            return;
+        }
+        this.logs.push({
+            conversation_id: store.sessionId,
+            type,
+            content,
+            timestamp: new Date().toISOString(),
+            metadata,
+            ...metadata
+        });
+    }
+    async flush() {
+        if (this.logs.length === 0)
+            return;
+        const batch = [...this.logs];
+        this.logs = [];
+        try {
+            // @ts-ignore
+            await fetch(`${this.config.baseUrl}/api/ingest`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-agent-key': this.config.apiKey
+                },
+                body: JSON.stringify({
+                    conversation_id: batch[0].conversation_id, // Group by session ID ideally, or send mixed batch
+                    logs: batch
+                })
+            });
+        }
+        catch (e) {
+            console.error('[AiSage] Flush failed', e);
+        }
+    }
+    instrument(openaiModule) {
+        if (!openaiModule?.chat?.completions?.create) {
+            return;
+        }
+        const originalCreate = openaiModule.chat.completions.create.bind(openaiModule.chat.completions);
+        openaiModule.chat.completions.create = async (body, options) => {
+            const start = Date.now();
+            try {
+                const result = await originalCreate(body, options);
+                this.log('model_response', {
+                    model: body.model,
+                    input: body.messages,
+                    output: result.choices?.[0]?.message,
+                    usage: result.usage,
+                    duration_ms: Date.now() - start
+                }, { duration_ms: Date.now() - start });
+                return result;
+            }
+            catch (e) {
+                this.log('error', {
+                    model: body.model,
+                    error: e.message
+                }, { duration_ms: Date.now() - start });
+                throw e;
+            }
+        };
+        console.log('[AiSage] OpenAI Instrumented');
+    }
+    interceptConsole() {
+        const originalLog = console.log;
+        const originalError = console.error;
+        console.log = (...args) => {
+            if (args[0] && typeof args[0] === 'string' && args[0].startsWith('[AiSage]')) {
+                originalLog.apply(console, args);
+                return;
+            }
+            this.log('step', { type: 'console_log', content: args.map(String).join(' ') });
+            originalLog.apply(console, args);
+        };
+        console.error = (...args) => {
+            if (args[0] && typeof args[0] === 'string' && args[0].startsWith('[AiSage]')) {
+                originalError.apply(console, args);
+                return;
+            }
+            this.log('error', { type: 'console_error', content: args.map(String).join(' ') });
+            originalError.apply(console, args);
+        };
+    }
+    interceptHttp() {
+        const self = this;
+        // Helper to patch request methods
+        function patchRequest(module, protocol) {
+            const originalRequest = module.request;
+            module.request = function (...args) {
+                let options;
+                let url;
+                if (typeof args[0] === 'string' || args[0] instanceof URL) {
+                    url = args[0];
+                    options = args[1] || {};
+                }
+                else {
+                    options = args[0];
+                    url = `${protocol}//${options.hostname || options.host || 'localhost'}${options.path || '/'}`;
+                }
+                const targetHost = (options.hostname || options.host || '').toString();
+                // @ts-ignore
+                const configHost = new URL(self.config.baseUrl || 'http://localhost').hostname;
+                if (targetHost === configHost) {
+                    return originalRequest.apply(this, args);
+                }
+                const start = Date.now();
+                const method = options.method || 'GET';
+                const logName = `http.${method.toLowerCase()}`;
+                self.log('tool_call', {
+                    name: logName,
+                    args: { url: url.toString(), method }
+                });
+                const req = originalRequest.apply(this, args);
+                req.on('response', (res) => {
+                    res.on('end', () => {
+                        self.log('tool_result', {
+                            name: logName,
+                            output: { status: res.statusCode, statusText: res.statusMessage },
+                            duration_ms: Date.now() - start
+                        }, { duration_ms: Date.now() - start });
+                    });
+                });
+                req.on('error', (e) => {
+                    self.log('error', {
+                        name: logName,
+                        error: e.message
+                    }, { duration_ms: Date.now() - start });
+                });
+                return req;
+            };
+        }
+        // Use require to get the mutable CommonJS module, avoiding "only a getter" on ES namespaces
+        // @ts-ignore
+        const httpModule = require('http');
+        // @ts-ignore
+        const httpsModule = require('https');
+        patchRequest(httpModule, 'http:');
+        patchRequest(httpsModule, 'https:');
+        console.log('[AiSage] HTTP Instrumented');
+    }
+}
+exports.aisage = new AiSageClient();
+exports.default = exports.aisage;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "ai-sage-client",
+  "version": "0.0.1",
+  "description": "AI Sage Auto-Instrumentation SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "ts-node test/usage.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "observability",
+    "apm",
+    "llm",
+    "agent",
+    "monitoring"
+  ],
+  "author": "AI Sage",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/medeepak/ai-sage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/medeepak/ai-sage/issues"
+  },
+  "homepage": "https://github.com/medeepak/ai-sage#readme",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "ts-node": "^10.9.1",
+    "@types/node": "^20.0.0"
+  },
+  "dependencies": {
+    "uuid": "^9.0.0"
+  }
+}