overai 1.4.0

package/dist/observability/adapters/memory.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Memory Observability Adapter
+ * In-memory storage for development and testing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryObservabilityAdapter = void 0;
+exports.createMemoryAdapter = createMemoryAdapter;
+/**
+ * Generate a random ID
+ */
+function generateId() {
+    return Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+}
+/**
+ * Memory Span Context
+ */
+class MemorySpanContext {
+    constructor(spanId, traceId, adapter) {
+        this.spanId = spanId;
+        this.traceId = traceId;
+        this.adapter = adapter;
+    }
+    addEvent(name, attributes) {
+        this.adapter.addEvent(this.spanId, name, attributes);
+    }
+    setAttributes(attributes) {
+        const span = this.adapter.getSpan(this.spanId);
+        if (span) {
+            span.attributes = { ...span.attributes, ...attributes };
+        }
+    }
+    setProviderMetadata(metadata) {
+        const span = this.adapter.getSpan(this.spanId);
+        if (span) {
+            span.providerMetadata = metadata;
+        }
+    }
+    recordError(error) {
+        this.adapter.recordError(this.spanId, error);
+    }
+    end(status = 'completed') {
+        this.adapter.endSpan(this.spanId, status);
+    }
+}
+/**
+ * Memory Trace Context
+ */
+class MemoryTraceContext {
+    constructor(traceId, adapter) {
+        this.traceId = traceId;
+        this.adapter = adapter;
+    }
+    startSpan(name, kind, parentId) {
+        return this.adapter.startSpan(this.traceId, name, kind, parentId);
+    }
+    end(status = 'completed') {
+        this.adapter.endTrace(this.traceId, status);
+    }
+}
+/**
+ * Memory Observability Adapter
+ * Stores all traces and spans in memory for development/testing
+ */
+class MemoryObservabilityAdapter {
+    constructor(options = {}) {
+        this.name = 'memory';
+        this.isEnabled = true;
+        this.traces = new Map();
+        this.spans = new Map();
+        this.maxTraces = options.maxTraces || 1000;
+    }
+    async initialize() { }
+    async shutdown() {
+        this.clear();
+    }
+    startTrace(name, metadata = {}, attribution) {
+        const traceId = generateId();
+        const trace = {
+            id: traceId,
+            name,
+            startTime: Date.now(),
+            status: 'running',
+            spans: [],
+            metadata,
+            attribution
+        };
+        // Enforce max traces limit
+        if (this.traces.size >= this.maxTraces) {
+            const oldestKey = this.traces.keys().next().value;
+            if (oldestKey) {
+                this.traces.delete(oldestKey);
+            }
+        }
+        this.traces.set(traceId, trace);
+        return new MemoryTraceContext(traceId, this);
+    }
+    endTrace(traceId, status = 'completed') {
+        const trace = this.traces.get(traceId);
+        if (trace) {
+            trace.endTime = Date.now();
+            trace.status = status;
+        }
+    }
+    startSpan(traceId, name, kind, parentId) {
+        const spanId = generateId();
+        const span = {
+            id: spanId,
+            traceId,
+            parentId,
+            name,
+            kind,
+            status: 'running',
+            startTime: Date.now(),
+            attributes: {},
+            events: []
+        };
+        this.spans.set(spanId, span);
+        const trace = this.traces.get(traceId);
+        if (trace) {
+            trace.spans.push(span);
+        }
+        return new MemorySpanContext(spanId, traceId, this);
+    }
+    endSpan(spanId, status = 'completed', attributes) {
+        const span = this.spans.get(spanId);
+        if (span) {
+            span.endTime = Date.now();
+            span.status = status;
+            if (attributes) {
+                span.attributes = { ...span.attributes, ...attributes };
+            }
+        }
+    }
+    addEvent(spanId, name, attributes) {
+        const span = this.spans.get(spanId);
+        if (span) {
+            const event = {
+                name,
+                timestamp: Date.now(),
+                attributes
+            };
+            span.events.push(event);
+        }
+    }
+    recordError(spanId, error) {
+        const span = this.spans.get(spanId);
+        if (span) {
+            span.error = {
+                message: error.message,
+                stack: error.stack,
+                code: error.code
+            };
+            span.status = 'failed';
+        }
+    }
+    async flush() {
+        // No-op for memory adapter
+    }
+    // Utility methods for testing/debugging
+    getTrace(traceId) {
+        return this.traces.get(traceId);
+    }
+    getSpan(spanId) {
+        return this.spans.get(spanId);
+    }
+    getAllTraces() {
+        return Array.from(this.traces.values());
+    }
+    getAllSpans() {
+        return Array.from(this.spans.values());
+    }
+    getTraceSpans(traceId) {
+        return Array.from(this.spans.values()).filter(s => s.traceId === traceId);
+    }
+    clear() {
+        this.traces.clear();
+        this.spans.clear();
+    }
+    getStats() {
+        return {
+            traces: this.traces.size,
+            spans: this.spans.size
+        };
+    }
+}
+exports.MemoryObservabilityAdapter = MemoryObservabilityAdapter;
+function createMemoryAdapter(options) {
+    return new MemoryObservabilityAdapter(options);
+}

package/dist/observability/adapters/noop.d.ts

@@ -0,0 +1,25 @@
+/**
+ * No-op Observability Adapter
+ * Default adapter that does nothing - zero overhead when observability is disabled
+ */
+import type { ObservabilityAdapter, TraceContext, SpanContext, SpanKind, SpanStatus, AttributionContext } from '../types';
+/**
+ * No-op Observability Adapter
+ *
+ * This adapter does nothing and has zero overhead.
+ * Used as the default when no observability is configured.
+ */
+export declare class NoopObservabilityAdapter implements ObservabilityAdapter {
+    readonly name = "noop";
+    readonly isEnabled = false;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    startTrace(_name: string, _metadata?: Record<string, unknown>, _attribution?: AttributionContext): TraceContext;
+    endTrace(_traceId: string, _status?: SpanStatus): void;
+    startSpan(_traceId: string, _name: string, _kind: SpanKind, _parentId?: string): SpanContext;
+    endSpan(_spanId: string, _status?: SpanStatus, _attributes?: Record<string, unknown>): void;
+    addEvent(_spanId: string, _name: string, _attributes?: Record<string, unknown>): void;
+    recordError(_spanId: string, _error: Error): void;
+    flush(): Promise<void>;
+}
+export declare const noopAdapter: NoopObservabilityAdapter;

package/dist/observability/adapters/noop.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * No-op Observability Adapter
+ * Default adapter that does nothing - zero overhead when observability is disabled
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopAdapter = exports.NoopObservabilityAdapter = void 0;
+/**
+ * No-op span context - all operations are no-ops
+ */
+class NoopSpanContext {
+    constructor() {
+        this.spanId = '';
+        this.traceId = '';
+    }
+    addEvent(_name, _attributes) { }
+    setAttributes(_attributes) { }
+    setProviderMetadata(_metadata) { }
+    recordError(_error) { }
+    end(_status) { }
+}
+/**
+ * No-op trace context - all operations are no-ops
+ */
+class NoopTraceContext {
+    constructor() {
+        this.traceId = '';
+    }
+    startSpan(_name, _kind, _parentId) {
+        return new NoopSpanContext();
+    }
+    end(_status) { }
+}
+// Singleton instances
+const noopSpanContext = new NoopSpanContext();
+const noopTraceContext = new NoopTraceContext();
+/**
+ * No-op Observability Adapter
+ *
+ * This adapter does nothing and has zero overhead.
+ * Used as the default when no observability is configured.
+ */
+class NoopObservabilityAdapter {
+    constructor() {
+        this.name = 'noop';
+        this.isEnabled = false;
+    }
+    async initialize() { }
+    async shutdown() { }
+    startTrace(_name, _metadata, _attribution) {
+        return noopTraceContext;
+    }
+    endTrace(_traceId, _status) { }
+    startSpan(_traceId, _name, _kind, _parentId) {
+        return noopSpanContext;
+    }
+    endSpan(_spanId, _status, _attributes) { }
+    addEvent(_spanId, _name, _attributes) { }
+    recordError(_spanId, _error) { }
+    async flush() { }
+}
+exports.NoopObservabilityAdapter = NoopObservabilityAdapter;
+// Export singleton instance
+exports.noopAdapter = new NoopObservabilityAdapter();

package/dist/observability/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Observability Module - Unified tracing, logging, and metrics
+ *
+ * Supports 14+ observability integrations:
+ * - Langfuse, LangSmith, LangWatch
+ * - Arize AX, Axiom, Braintrust
+ * - Helicone, Laminar, Maxim
+ * - Patronus, Scorecard, SigNoz
+ * - Traceloop, Weave
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createObservabilityAdapter, setObservabilityAdapter } from 'praisonai';
+ *
+ * // Enable observability
+ * const adapter = await createObservabilityAdapter('langfuse');
+ * setObservabilityAdapter(adapter);
+ *
+ * // Use with agents
+ * const agent = new Agent({
+ *   instructions: "You are helpful"
+ * });
+ * ```
+ */
+export type { SpanKind, SpanStatus, SpanData, SpanEvent, TraceData, TraceContext, SpanContext, ObservabilityAdapter, AttributionContext, ProviderMetadata, ObservabilityToolConfig, ObservabilityToolName, ObservabilityToolInfo } from './types';
+export { OBSERVABILITY_TOOLS, getObservabilityToolInfo, listObservabilityTools, hasObservabilityToolEnvVar } from './types';
+export { NoopObservabilityAdapter, noopAdapter, MemoryObservabilityAdapter, createMemoryAdapter, ConsoleObservabilityAdapter, createConsoleAdapter, createObservabilityAdapter, clearAdapterCache } from './adapters';
+import type { ObservabilityAdapter } from './types';
+/**
+ * Set the global observability adapter
+ */
+export declare function setObservabilityAdapter(adapter: ObservabilityAdapter): void;
+/**
+ * Get the global observability adapter (creates memory adapter if not set)
+ */
+export declare function getObservabilityAdapter(): ObservabilityAdapter;
+/**
+ * Reset the global observability adapter (for testing)
+ */
+export declare function resetObservabilityAdapter(): void;
+/**
+ * Create a trace helper function for easy integration
+ */
+export declare function trace(toolName?: string): {
+    tool: string;
+    getAdapter(): Promise<ObservabilityAdapter>;
+};

package/dist/observability/index.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Observability Module - Unified tracing, logging, and metrics
+ *
+ * Supports 14+ observability integrations:
+ * - Langfuse, LangSmith, LangWatch
+ * - Arize AX, Axiom, Braintrust
+ * - Helicone, Laminar, Maxim
+ * - Patronus, Scorecard, SigNoz
+ * - Traceloop, Weave
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createObservabilityAdapter, setObservabilityAdapter } from 'praisonai';
+ *
+ * // Enable observability
+ * const adapter = await createObservabilityAdapter('langfuse');
+ * setObservabilityAdapter(adapter);
+ *
+ * // Use with agents
+ * const agent = new Agent({
+ *   instructions: "You are helpful"
+ * });
+ * ```
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearAdapterCache = exports.createObservabilityAdapter = exports.createConsoleAdapter = exports.ConsoleObservabilityAdapter = exports.createMemoryAdapter = exports.MemoryObservabilityAdapter = exports.noopAdapter = exports.NoopObservabilityAdapter = exports.hasObservabilityToolEnvVar = exports.listObservabilityTools = exports.getObservabilityToolInfo = exports.OBSERVABILITY_TOOLS = void 0;
+exports.setObservabilityAdapter = setObservabilityAdapter;
+exports.getObservabilityAdapter = getObservabilityAdapter;
+exports.resetObservabilityAdapter = resetObservabilityAdapter;
+exports.trace = trace;
+var types_1 = require("./types");
+Object.defineProperty(exports, "OBSERVABILITY_TOOLS", { enumerable: true, get: function () { return types_1.OBSERVABILITY_TOOLS; } });
+Object.defineProperty(exports, "getObservabilityToolInfo", { enumerable: true, get: function () { return types_1.getObservabilityToolInfo; } });
+Object.defineProperty(exports, "listObservabilityTools", { enumerable: true, get: function () { return types_1.listObservabilityTools; } });
+Object.defineProperty(exports, "hasObservabilityToolEnvVar", { enumerable: true, get: function () { return types_1.hasObservabilityToolEnvVar; } });
+// Re-export adapters
+var adapters_1 = require("./adapters");
+Object.defineProperty(exports, "NoopObservabilityAdapter", { enumerable: true, get: function () { return adapters_1.NoopObservabilityAdapter; } });
+Object.defineProperty(exports, "noopAdapter", { enumerable: true, get: function () { return adapters_1.noopAdapter; } });
+Object.defineProperty(exports, "MemoryObservabilityAdapter", { enumerable: true, get: function () { return adapters_1.MemoryObservabilityAdapter; } });
+Object.defineProperty(exports, "createMemoryAdapter", { enumerable: true, get: function () { return adapters_1.createMemoryAdapter; } });
+Object.defineProperty(exports, "ConsoleObservabilityAdapter", { enumerable: true, get: function () { return adapters_1.ConsoleObservabilityAdapter; } });
+Object.defineProperty(exports, "createConsoleAdapter", { enumerable: true, get: function () { return adapters_1.createConsoleAdapter; } });
+Object.defineProperty(exports, "createObservabilityAdapter", { enumerable: true, get: function () { return adapters_1.createObservabilityAdapter; } });
+Object.defineProperty(exports, "clearAdapterCache", { enumerable: true, get: function () { return adapters_1.clearAdapterCache; } });
+const adapters_2 = require("./adapters");
+// Global observability instance
+let globalAdapter = null;
+/**
+ * Set the global observability adapter
+ */
+function setObservabilityAdapter(adapter) {
+    globalAdapter = adapter;
+}
+/**
+ * Get the global observability adapter (creates memory adapter if not set)
+ */
+function getObservabilityAdapter() {
+    if (!globalAdapter) {
+        globalAdapter = new adapters_2.MemoryObservabilityAdapter();
+    }
+    return globalAdapter;
+}
+/**
+ * Reset the global observability adapter (for testing)
+ */
+function resetObservabilityAdapter() {
+    globalAdapter = null;
+}
+/**
+ * Create a trace helper function for easy integration
+ */
+function trace(toolName = 'memory') {
+    return {
+        tool: toolName,
+        async getAdapter() {
+            const { createObservabilityAdapter } = await Promise.resolve().then(() => __importStar(require('./adapters')));
+            return createObservabilityAdapter(toolName);
+        }
+    };
+}

package/dist/observability/types.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Observability Types - Unified tracing interface for all observability integrations
+ */
+export type SpanKind = 'llm' | 'tool' | 'agent' | 'workflow' | 'embedding' | 'retrieval' | 'custom';
+export type SpanStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Attribution context for multi-agent safety
+ */
+export interface AttributionContext {
+    agentId?: string;
+    runId?: string;
+    traceId?: string;
+    sessionId?: string;
+    parentSpanId?: string;
+    userId?: string;
+    teamId?: string;
+}
+/**
+ * Provider call metadata
+ */
+export interface ProviderMetadata {
+    provider: string;
+    model: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    latencyMs?: number;
+    retryCount?: number;
+    region?: string;
+    cost?: number;
+    finishReason?: string;
+}
+/**
+ * Span event
+ */
+export interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Span data
+ */
+export interface SpanData {
+    id: string;
+    traceId: string;
+    parentId?: string;
+    name: string;
+    kind: SpanKind;
+    status: SpanStatus;
+    startTime: number;
+    endTime?: number;
+    attributes: Record<string, unknown>;
+    events: SpanEvent[];
+    attribution?: AttributionContext;
+    providerMetadata?: ProviderMetadata;
+    error?: {
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+}
+/**
+ * Trace data
+ */
+export interface TraceData {
+    id: string;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    status: SpanStatus;
+    spans: SpanData[];
+    metadata: Record<string, unknown>;
+    attribution?: AttributionContext;
+}
+/**
+ * Span context for active spans
+ */
+export interface SpanContext {
+    spanId: string;
+    traceId: string;
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    setAttributes(attributes: Record<string, unknown>): void;
+    setProviderMetadata(metadata: ProviderMetadata): void;
+    recordError(error: Error): void;
+    end(status?: SpanStatus): void;
+}
+/**
+ * Trace context for active traces
+ */
+export interface TraceContext {
+    traceId: string;
+    startSpan(name: string, kind: SpanKind, parentId?: string): SpanContext;
+    end(status?: SpanStatus): void;
+}
+/**
+ * Unified Observability Adapter Protocol
+ * All observability integrations must implement this interface
+ */
+export interface ObservabilityAdapter {
+    readonly name: string;
+    readonly isEnabled: boolean;
+    initialize?(): Promise<void>;
+    shutdown?(): Promise<void>;
+    startTrace(name: string, metadata?: Record<string, unknown>, attribution?: AttributionContext): TraceContext;
+    endTrace(traceId: string, status?: SpanStatus): void;
+    startSpan(traceId: string, name: string, kind: SpanKind, parentId?: string): SpanContext;
+    endSpan(spanId: string, status?: SpanStatus, attributes?: Record<string, unknown>): void;
+    addEvent(spanId: string, name: string, attributes?: Record<string, unknown>): void;
+    recordError(spanId: string, error: Error): void;
+    flush(): Promise<void>;
+}
+/**
+ * Observability tool configuration
+ */
+export interface ObservabilityToolConfig {
+    name: string;
+    apiKey?: string;
+    baseUrl?: string;
+    projectId?: string;
+    environment?: string;
+    enabled?: boolean;
+    batchSize?: number;
+    flushInterval?: number;
+    debug?: boolean;
+    headers?: Record<string, string>;
+}
+/**
+ * Supported observability tools
+ */
+export type ObservabilityToolName = 'langfuse' | 'langsmith' | 'langwatch' | 'arize' | 'axiom' | 'braintrust' | 'helicone' | 'laminar' | 'maxim' | 'patronus' | 'scorecard' | 'signoz' | 'traceloop' | 'weave' | 'console' | 'memory' | 'noop';
+/**
+ * Observability tool info
+ */
+export interface ObservabilityToolInfo {
+    name: ObservabilityToolName;
+    package?: string;
+    envKey: string;
+    description: string;
+    features: {
+        traces: boolean;
+        spans: boolean;
+        events: boolean;
+        errors: boolean;
+        metrics: boolean;
+        export: boolean;
+    };
+    docsUrl?: string;
+}
+/**
+ * All supported observability tools with their configurations
+ */
+export declare const OBSERVABILITY_TOOLS: Record<ObservabilityToolName, ObservabilityToolInfo>;
+/**
+ * Get observability tool info
+ */
+export declare function getObservabilityToolInfo(name: ObservabilityToolName): ObservabilityToolInfo | undefined;
+/**
+ * List all observability tools
+ */
+export declare function listObservabilityTools(): ObservabilityToolInfo[];
+/**
+ * Check if observability tool has required env var
+ */
+export declare function hasObservabilityToolEnvVar(name: ObservabilityToolName): boolean;