@lightcurve/sdk 0.1.0

package/dist/buffer.d.ts

@@ -0,0 +1,14 @@
+import { CognitionEvent } from './types';
+export declare class EventBuffer {
+    private queue;
+    private apiUrl;
+    private apiKey?;
+    private batchSize;
+    private flushInterval;
+    private intervalId?;
+    constructor(apiUrl: string, apiKey?: string, batchSize?: number, flushInterval?: number);
+    add(event: CognitionEvent): void;
+    private start;
+    flush(): Promise<void>;
+    stop(): void;
+}

package/dist/buffer.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBuffer = void 0;
+class EventBuffer {
+    constructor(apiUrl, apiKey, batchSize = 10, flushInterval = 2000) {
+        this.queue = [];
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        this.batchSize = batchSize;
+        this.flushInterval = flushInterval;
+        this.start();
+    }
+    add(event) {
+        this.queue.push(event);
+        if (this.queue.length >= this.batchSize) {
+            this.flush();
+        }
+    }
+    start() {
+        this.intervalId = setInterval(() => {
+            if (this.queue.length > 0) {
+                this.flush();
+            }
+        }, this.flushInterval);
+    }
+    async flush() {
+        if (this.queue.length === 0)
+            return;
+        const batch = [...this.queue];
+        this.queue = []; // Clear queue immediately
+        try {
+            const response = await fetch(`${this.apiUrl}/v1/ingest`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(this.apiKey ? { 'Authorization': `Bearer ${this.apiKey}` } : {}),
+                },
+                body: JSON.stringify({ events: batch }),
+            });
+            if (!response.ok) {
+                console.error(`[Lightcurve] Failed to flush events: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            console.error('[Lightcurve] Error flushing events:', error);
+        }
+    }
+    stop() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+        }
+        // Flush remaining
+        this.flush();
+    }
+}
+exports.EventBuffer = EventBuffer;

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { EventBuffer } from './buffer';
+export declare class Lightcurve {
+    private buffer;
+    constructor(apiUrl?: string, apiKey?: string);
+    startRun(agentId: string, runId?: string, orgId?: string): Run;
+    close(): void;
+}
+export declare class Run {
+    private buffer;
+    runId: string;
+    agentId: string;
+    orgId?: string | undefined;
+    constructor(buffer: EventBuffer, runId: string, agentId: string, orgId?: string | undefined);
+    private log;
+    logInput(userInput: string, interpretedGoal?: string, constraints?: string[]): void;
+    logKnowledge(summary: string, evidencePresent?: boolean, sources?: string[]): void;
+    logPlan(steps: string[], rationale?: string, alternatives?: string[]): void;
+    logTool(toolName: string, input: Record<string, any>, output?: Record<string, any>, success?: boolean, retries?: number, latencyMs?: number): void;
+    logValidation(result: boolean, method?: string, confidenceScore?: number): void;
+    logOutput(content: string, structuredData?: Record<string, any>, confidence?: number): void;
+    end(): void;
+}

package/dist/client.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Run = exports.Lightcurve = void 0;
+const uuid_1 = require("uuid");
+const buffer_1 = require("./buffer");
+class Lightcurve {
+    constructor(apiUrl = 'http://localhost:8000', apiKey) {
+        this.buffer = new buffer_1.EventBuffer(apiUrl, apiKey);
+    }
+    startRun(agentId, runId, orgId) {
+        const id = runId || (0, uuid_1.v4)();
+        return new Run(this.buffer, id, agentId, orgId);
+    }
+    close() {
+        this.buffer.stop();
+    }
+}
+exports.Lightcurve = Lightcurve;
+class Run {
+    constructor(buffer, runId, agentId, orgId) {
+        this.buffer = buffer;
+        this.runId = runId;
+        this.agentId = agentId;
+        this.orgId = orgId;
+    }
+    log(type, data, incidentFlags) {
+        const event = {
+            run_id: this.runId,
+            agent_id: this.agentId,
+            org_id: this.orgId,
+            timestamp: new Date().toISOString(),
+            type,
+            data,
+            incident_flags: incidentFlags,
+        };
+        this.buffer.add(event);
+    }
+    logInput(userInput, interpretedGoal, constraints = []) {
+        const data = { user_input: userInput, interpreted_goal: interpretedGoal, constraints };
+        this.log('input', data);
+    }
+    logKnowledge(summary, evidencePresent = false, sources = []) {
+        const data = { summary, evidence_present: evidencePresent, sources };
+        this.log('knowledge', data);
+    }
+    logPlan(steps, rationale, alternatives = []) {
+        const data = { steps, rationale, alternatives };
+        this.log('plan', data);
+    }
+    logTool(toolName, input, output, success = true, retries = 0, latencyMs) {
+        const data = {
+            tool_name: toolName, input, output, success, retries, latency_ms: latencyMs
+        };
+        this.log('tool', data);
+    }
+    logValidation(result, method = 'auto', confidenceScore) {
+        const data = { result, method, confidence_score: confidenceScore };
+        this.log('validation', data);
+    }
+    logOutput(content, structuredData, confidence) {
+        const data = { content, structured_data: structuredData, confidence };
+        this.log('output', data);
+    }
+    end() {
+        this.buffer.flush();
+    }
+}
+exports.Run = Run;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export { tracer, Tracer } from './tracer';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tracer = exports.tracer = void 0;
+__exportStar(require("./types"), exports);
+var tracer_1 = require("./tracer");
+Object.defineProperty(exports, "tracer", { enumerable: true, get: function () { return tracer_1.tracer; } });
+Object.defineProperty(exports, "Tracer", { enumerable: true, get: function () { return tracer_1.Tracer; } });

package/dist/tracer.d.ts

@@ -0,0 +1,21 @@
+export declare const COGNITIVE_PHASES: Set<string>;
+export interface TraceOptions {
+    name?: string;
+    project?: string;
+    tags?: Record<string, any>;
+}
+export declare class Tracer {
+    private transport?;
+    private storage;
+    private apiKey?;
+    private project?;
+    init(options?: {
+        apiKey?: string;
+        apiUrl?: string;
+        project?: string;
+    }): void;
+    trace(options?: TraceOptions): <T extends (...args: any[]) => any>(fn: T) => T;
+    step(name: string, metadata?: Record<string, any>): ((fn: Function) => any) | (<T>(fn: () => Promise<T> | T) => Promise<T>);
+    cognitive(phase: string, name?: string): ((fn: Function) => any) | (<T>(fn: () => Promise<T> | T) => Promise<T>);
+}
+export declare const tracer: Tracer;

package/dist/tracer.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tracer = exports.Tracer = exports.COGNITIVE_PHASES = void 0;
+const async_hooks_1 = require("async_hooks");
+const uuid_1 = require("uuid");
+const transport_1 = require("./transport");
+exports.COGNITIVE_PHASES = new Set([
+    "planning",
+    "goal_decomposition",
+    "reflection",
+    "self_critique",
+    "tool_selection",
+    "validation",
+    "synthesis"
+]);
+class Tracer {
+    constructor() {
+        this.storage = new async_hooks_1.AsyncLocalStorage();
+    }
+    init(options = {}) {
+        this.apiKey = options.apiKey || process.env.LIGHTCURVE_API_KEY;
+        this.project = options.project;
+        this.transport = new transport_1.BackgroundTransport(this.apiKey, options.apiUrl);
+    }
+    trace(options = {}) {
+        return (fn) => {
+            return ((...args) => {
+                const transport = this.transport;
+                if (!transport) {
+                    return fn(...args);
+                }
+                const runId = (0, uuid_1.v4)();
+                const start = Date.now();
+                const steps = [];
+                const runName = options.name || fn.name || "anonymous";
+                return this.storage.run(steps, async () => {
+                    let status = "success";
+                    let output = null;
+                    let errorMsg;
+                    try {
+                        const result = await fn(...args);
+                        output = { return_value: JSON.stringify(result) }; // Simplify
+                        return result;
+                    }
+                    catch (e) {
+                        status = "failure";
+                        errorMsg = e.message || String(e);
+                        output = { error: errorMsg };
+                        throw e;
+                    }
+                    finally {
+                        const duration = Date.now() - start;
+                        const payload = {
+                            run_id: runId,
+                            name: runName,
+                            project: options.project || this.project,
+                            started_at: new Date(start).toISOString(),
+                            duration_ms: duration,
+                            status,
+                            input: { args: args.map(a => String(a)) },
+                            output,
+                            steps: [...steps],
+                            metadata: options.tags,
+                            exception: errorMsg
+                        };
+                        transport.send(payload);
+                    }
+                });
+            });
+        };
+    }
+    step(name, metadata) {
+        const store = this.storage.getStore();
+        if (!store) {
+            // Not in a trace, return dummy
+            return (fn) => fn();
+        }
+        const start = Date.now();
+        // Return a wrapper that expects a function or promise? 
+        // Python `with tracer.step()` is synchronous block or context manager.
+        // Node.js:
+        // await tracer.step("name", async () => { ... })
+        return async (fn) => {
+            let status = "success";
+            let output = {};
+            try {
+                return await fn();
+            }
+            catch (e) {
+                status = "failure";
+                output = { error: e.message };
+                throw e;
+            }
+            finally {
+                const duration = Date.now() - start;
+                store.push({
+                    name,
+                    type: "custom",
+                    status,
+                    started_at: new Date(start).toISOString(),
+                    duration_ms: duration,
+                    metadata,
+                    output
+                });
+            }
+        };
+    }
+    cognitive(phase, name) {
+        if (!exports.COGNITIVE_PHASES.has(phase)) {
+            console.warn(`Warning: Unknown cognitive phase '${phase}'. Expected one of: ${Array.from(exports.COGNITIVE_PHASES).join(', ')}`);
+        }
+        const store = this.storage.getStore();
+        if (!store) {
+            return (fn) => fn();
+        }
+        const start = Date.now();
+        return async (fn) => {
+            let status = "success";
+            let output = {};
+            try {
+                return await fn();
+            }
+            catch (e) {
+                status = "failure";
+                output = { error: e.message };
+                throw e;
+            }
+            finally {
+                const duration = Date.now() - start;
+                // Map to backend stage
+                const stageMapCognitive = {
+                    "planning": "task_specification",
+                    "goal_decomposition": "task_specification",
+                    "reflection": "validation",
+                    "self_critique": "validation",
+                    "validation": "validation",
+                    "tool_selection": "tool_call",
+                    "synthesis": "output"
+                };
+                const stage = stageMapCognitive[phase] || "execution_strategy";
+                store.push({
+                    name: name || phase,
+                    type: "cognitive",
+                    stage: stage,
+                    cognitive_type: phase,
+                    status,
+                    started_at: new Date(start).toISOString(),
+                    duration_ms: duration,
+                    output
+                });
+            }
+        };
+    }
+}
+exports.Tracer = Tracer;
+exports.tracer = new Tracer();

package/dist/transport.d.ts

@@ -0,0 +1,11 @@
+import { RunPayload } from './types';
+export declare class BackgroundTransport {
+    private queue;
+    private processing;
+    private apiKey?;
+    private apiUrl;
+    constructor(apiKey?: string, apiUrl?: string);
+    send(payload: RunPayload): void;
+    private processQueue;
+    private postPayload;
+}

package/dist/transport.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BackgroundTransport = void 0;
+class BackgroundTransport {
+    constructor(apiKey, apiUrl = "http://localhost:8000") {
+        this.queue = [];
+        this.processing = false;
+        this.apiKey = apiKey;
+        this.apiUrl = apiUrl.replace(/\/$/, "");
+    }
+    send(payload) {
+        this.queue.push(payload);
+        this.processQueue();
+    }
+    async processQueue() {
+        if (this.processing || this.queue.length === 0)
+            return;
+        this.processing = true;
+        try {
+            while (this.queue.length > 0) {
+                const payload = this.queue.shift();
+                if (payload) {
+                    await this.postPayload(payload);
+                }
+            }
+        }
+        finally {
+            this.processing = false;
+        }
+    }
+    async postPayload(payload) {
+        const url = `${this.apiUrl}/v1/traces`;
+        const headers = {
+            "Content-Type": "application/json",
+            "X-Lightcurve-Key": this.apiKey || ""
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        try {
+            // Using global fetch (Node 18+)
+            await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload)
+            });
+        }
+        catch (e) {
+            // Silent retry/fail
+            // console.error("Failed to send trace", e);
+        }
+    }
+}
+exports.BackgroundTransport = BackgroundTransport;

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+export interface StepPayload {
+    name: string;
+    type: string;
+    stage?: string;
+    cognitive_type?: string;
+    status: string;
+    input?: Record<string, any>;
+    output?: Record<string, any>;
+    duration_ms?: number;
+    started_at?: string;
+    metadata?: Record<string, any>;
+}
+export interface RunPayload {
+    run_id: string;
+    name: string;
+    project?: string;
+    input?: Record<string, any>;
+    output?: Record<string, any>;
+    status: string;
+    duration_ms?: number;
+    started_at: string;
+    steps: StepPayload[];
+    metadata?: Record<string, any>;
+    exception?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@lightcurve/sdk",
+    "version": "0.1.0",
+    "description": "Observability and evaluation SDK for AI Agents",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/uselightcurve/lightcurve-sdk.git"
+    },
+    "keywords": [
+        "llm",
+        "agent",
+        "observability",
+        "ai"
+    ],
+    "author": "Lightcurve Team",
+    "license": "MIT",
+    "dependencies": {
+        "axios": "^1.6.0",
+        "uuid": "^9.0.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.0.0",
+        "@types/node": "^20.0.0",
+        "@types/uuid": "^9.0.0"
+    }
+}