overai 1.4.0

package/dist/integrations/observability/base.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Base Observability - Abstract class for observability integrations
+ * Supports tracing, logging, and metrics
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryObservabilityProvider = exports.ConsoleObservabilityProvider = exports.BaseObservabilityProvider = void 0;
+exports.createConsoleObservability = createConsoleObservability;
+exports.createMemoryObservability = createMemoryObservability;
+/**
+ * Abstract base class for observability providers
+ */
+class BaseObservabilityProvider {
+    constructor(name) {
+        this.name = name;
+    }
+    /**
+     * Helper to create trace context
+     */
+    createTraceContext(span) {
+        return {
+            traceId: span.traceId,
+            spanId: span.id,
+            parentSpanId: span.parentId
+        };
+    }
+    /**
+     * Generate unique ID
+     */
+    generateId() {
+        return crypto.randomUUID().replace(/-/g, '');
+    }
+}
+exports.BaseObservabilityProvider = BaseObservabilityProvider;
+/**
+ * Console-based observability provider for development
+ */
+class ConsoleObservabilityProvider extends BaseObservabilityProvider {
+    constructor(config = {}) {
+        super('ConsoleObservability');
+        this.spans = new Map();
+        this.verbose = config.verbose ?? false;
+    }
+    startSpan(name, attributes, parentContext) {
+        const span = {
+            id: this.generateId(),
+            traceId: parentContext?.traceId || this.generateId(),
+            parentId: parentContext?.spanId,
+            name,
+            startTime: Date.now(),
+            status: 'unset',
+            attributes: attributes || {},
+            events: []
+        };
+        this.spans.set(span.id, span);
+        if (this.verbose) {
+            console.log(`[SPAN START] ${name}`, { traceId: span.traceId, spanId: span.id });
+        }
+        return span;
+    }
+    endSpan(span, status = 'ok', error) {
+        span.endTime = Date.now();
+        span.status = status;
+        if (error) {
+            span.attributes.error = error.message;
+            span.attributes.errorStack = error.stack;
+        }
+        const duration = span.endTime - span.startTime;
+        if (this.verbose) {
+            console.log(`[SPAN END] ${span.name}`, {
+                duration: `${duration}ms`,
+                status,
+                ...(error && { error: error.message })
+            });
+        }
+        this.spans.delete(span.id);
+    }
+    addSpanEvent(span, name, attributes) {
+        span.events.push({
+            name,
+            timestamp: Date.now(),
+            attributes
+        });
+        if (this.verbose) {
+            console.log(`[SPAN EVENT] ${span.name} -> ${name}`, attributes);
+        }
+    }
+    log(entry) {
+        const prefix = `[${entry.level.toUpperCase()}]`;
+        const context = entry.traceId ? ` [trace:${entry.traceId.slice(0, 8)}]` : '';
+        switch (entry.level) {
+            case 'debug':
+                console.debug(`${prefix}${context} ${entry.message}`, entry.attributes);
+                break;
+            case 'info':
+                console.info(`${prefix}${context} ${entry.message}`, entry.attributes);
+                break;
+            case 'warn':
+                console.warn(`${prefix}${context} ${entry.message}`, entry.attributes);
+                break;
+            case 'error':
+                console.error(`${prefix}${context} ${entry.message}`, entry.attributes);
+                break;
+        }
+    }
+    recordMetric(metric) {
+        if (this.verbose) {
+            console.log(`[METRIC] ${metric.name}: ${metric.value} (${metric.type})`, metric.tags);
+        }
+    }
+    async flush() {
+        // Console provider doesn't need flushing
+    }
+    async shutdown() {
+        this.spans.clear();
+    }
+}
+exports.ConsoleObservabilityProvider = ConsoleObservabilityProvider;
+/**
+ * Memory-based observability provider for testing
+ */
+class MemoryObservabilityProvider extends BaseObservabilityProvider {
+    constructor() {
+        super('MemoryObservability');
+        this.spans = [];
+        this.logs = [];
+        this.metrics = [];
+    }
+    startSpan(name, attributes, parentContext) {
+        const span = {
+            id: this.generateId(),
+            traceId: parentContext?.traceId || this.generateId(),
+            parentId: parentContext?.spanId,
+            name,
+            startTime: Date.now(),
+            status: 'unset',
+            attributes: attributes || {},
+            events: []
+        };
+        this.spans.push(span);
+        return span;
+    }
+    endSpan(span, status = 'ok', error) {
+        span.endTime = Date.now();
+        span.status = status;
+        if (error) {
+            span.attributes.error = error.message;
+        }
+    }
+    addSpanEvent(span, name, attributes) {
+        span.events.push({ name, timestamp: Date.now(), attributes });
+    }
+    log(entry) {
+        this.logs.push(entry);
+    }
+    recordMetric(metric) {
+        this.metrics.push(metric);
+    }
+    async flush() { }
+    async shutdown() {
+        this.spans = [];
+        this.logs = [];
+        this.metrics = [];
+    }
+    // Helper methods for testing
+    getSpansByName(name) {
+        return this.spans.filter(s => s.name === name);
+    }
+    getLogsByLevel(level) {
+        return this.logs.filter(l => l.level === level);
+    }
+    getMetricsByName(name) {
+        return this.metrics.filter(m => m.name === name);
+    }
+}
+exports.MemoryObservabilityProvider = MemoryObservabilityProvider;
+// Factory functions
+function createConsoleObservability(config) {
+    return new ConsoleObservabilityProvider(config);
+}
+function createMemoryObservability() {
+    return new MemoryObservabilityProvider();
+}

package/dist/integrations/observability/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Observability Integrations
+ * Provides adapters for various observability platforms
+ */
+export * from './base';
+export * from './langfuse';
+export { createConsoleObservability, createMemoryObservability } from './base';
+export { createLangfuseObservability } from './langfuse';

package/dist/integrations/observability/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Observability Integrations
+ * Provides adapters for various observability platforms
+ */
+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.createLangfuseObservability = exports.createMemoryObservability = exports.createConsoleObservability = void 0;
+__exportStar(require("./base"), exports);
+__exportStar(require("./langfuse"), exports);
+// Re-export factory functions
+var base_1 = require("./base");
+Object.defineProperty(exports, "createConsoleObservability", { enumerable: true, get: function () { return base_1.createConsoleObservability; } });
+Object.defineProperty(exports, "createMemoryObservability", { enumerable: true, get: function () { return base_1.createMemoryObservability; } });
+var langfuse_1 = require("./langfuse");
+Object.defineProperty(exports, "createLangfuseObservability", { enumerable: true, get: function () { return langfuse_1.createLangfuseObservability; } });

package/dist/integrations/observability/langfuse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Langfuse Observability Integration
+ */
+import { BaseObservabilityProvider, Span, TraceContext, LogEntry, Metric } from './base';
+export interface LangfuseConfig {
+    publicKey: string;
+    secretKey: string;
+    baseUrl?: string;
+    flushAt?: number;
+    flushInterval?: number;
+}
+export declare class LangfuseObservabilityProvider extends BaseObservabilityProvider {
+    private publicKey;
+    private secretKey;
+    private baseUrl;
+    private queue;
+    private flushAt;
+    private flushInterval;
+    private flushTimer?;
+    constructor(config: LangfuseConfig);
+    private startFlushTimer;
+    private request;
+    private enqueue;
+    startSpan(name: string, attributes?: Record<string, any>, parentContext?: TraceContext): Span;
+    endSpan(span: Span, status?: 'ok' | 'error', error?: Error): void;
+    addSpanEvent(span: Span, name: string, attributes?: Record<string, any>): void;
+    log(entry: LogEntry): void;
+    recordMetric(metric: Metric): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export declare function createLangfuseObservability(config: LangfuseConfig): LangfuseObservabilityProvider;

package/dist/integrations/observability/langfuse.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * Langfuse Observability Integration
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LangfuseObservabilityProvider = void 0;
+exports.createLangfuseObservability = createLangfuseObservability;
+const base_1 = require("./base");
+class LangfuseObservabilityProvider extends base_1.BaseObservabilityProvider {
+    constructor(config) {
+        super('LangfuseObservability');
+        this.queue = [];
+        this.publicKey = config.publicKey;
+        this.secretKey = config.secretKey;
+        this.baseUrl = config.baseUrl || 'https://cloud.langfuse.com';
+        this.flushAt = config.flushAt || 20;
+        this.flushInterval = config.flushInterval || 10000;
+        this.startFlushTimer();
+    }
+    startFlushTimer() {
+        this.flushTimer = setInterval(() => {
+            if (this.queue.length > 0) {
+                this.flush();
+            }
+        }, this.flushInterval);
+    }
+    async request(path, body) {
+        const auth = Buffer.from(`${this.publicKey}:${this.secretKey}`).toString('base64');
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Basic ${auth}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(body)
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Langfuse API error: ${response.status} - ${error}`);
+        }
+        return response.json();
+    }
+    enqueue(event) {
+        this.queue.push(event);
+        if (this.queue.length >= this.flushAt) {
+            this.flush();
+        }
+    }
+    startSpan(name, attributes, parentContext) {
+        const span = {
+            id: this.generateId(),
+            traceId: parentContext?.traceId || this.generateId(),
+            parentId: parentContext?.spanId,
+            name,
+            startTime: Date.now(),
+            status: 'unset',
+            attributes: attributes || {},
+            events: []
+        };
+        // Create trace if this is root span
+        if (!parentContext) {
+            this.enqueue({
+                type: 'trace-create',
+                body: {
+                    id: span.traceId,
+                    name,
+                    metadata: attributes,
+                    timestamp: new Date(span.startTime).toISOString()
+                }
+            });
+        }
+        // Create span/generation
+        this.enqueue({
+            type: 'span-create',
+            body: {
+                id: span.id,
+                traceId: span.traceId,
+                parentObservationId: span.parentId,
+                name,
+                startTime: new Date(span.startTime).toISOString(),
+                metadata: attributes
+            }
+        });
+        return span;
+    }
+    endSpan(span, status = 'ok', error) {
+        span.endTime = Date.now();
+        span.status = status;
+        const updateBody = {
+            spanId: span.id,
+            endTime: new Date(span.endTime).toISOString(),
+            level: status === 'error' ? 'ERROR' : 'DEFAULT'
+        };
+        if (error) {
+            updateBody.statusMessage = error.message;
+        }
+        this.enqueue({
+            type: 'span-update',
+            body: updateBody
+        });
+    }
+    addSpanEvent(span, name, attributes) {
+        span.events.push({
+            name,
+            timestamp: Date.now(),
+            attributes
+        });
+        this.enqueue({
+            type: 'event-create',
+            body: {
+                traceId: span.traceId,
+                observationId: span.id,
+                name,
+                metadata: attributes,
+                timestamp: new Date().toISOString()
+            }
+        });
+    }
+    log(entry) {
+        // Langfuse doesn't have direct log support, use events instead
+        if (entry.traceId) {
+            this.enqueue({
+                type: 'event-create',
+                body: {
+                    traceId: entry.traceId,
+                    observationId: entry.spanId,
+                    name: `log:${entry.level}`,
+                    metadata: {
+                        message: entry.message,
+                        ...entry.attributes
+                    },
+                    timestamp: new Date(entry.timestamp).toISOString()
+                }
+            });
+        }
+    }
+    recordMetric(metric) {
+        // Langfuse uses scores for metrics
+        this.enqueue({
+            type: 'score-create',
+            body: {
+                name: metric.name,
+                value: metric.value,
+                timestamp: new Date(metric.timestamp).toISOString(),
+                comment: JSON.stringify(metric.tags)
+            }
+        });
+    }
+    async flush() {
+        if (this.queue.length === 0)
+            return;
+        const batch = this.queue.splice(0, this.queue.length);
+        try {
+            await this.request('/api/public/ingestion', {
+                batch
+            });
+        }
+        catch (error) {
+            // Re-add failed items to queue
+            this.queue.unshift(...batch);
+            console.error('Langfuse flush error:', error);
+        }
+    }
+    async shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        await this.flush();
+    }
+}
+exports.LangfuseObservabilityProvider = LangfuseObservabilityProvider;
+function createLangfuseObservability(config) {
+    return new LangfuseObservabilityProvider(config);
+}

package/dist/integrations/postgres.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Natural Language Postgres
+ *
+ * Provides NL->SQL capabilities for querying PostgreSQL databases.
+ */
+export interface PostgresConfig {
+    /** Database connection URL */
+    connectionUrl: string;
+    /** Schema to use (default: public) */
+    schema?: string;
+    /** Read-only mode (default: true for safety) */
+    readOnly?: boolean;
+    /** Allowed tables (whitelist) */
+    allowedTables?: string[];
+    /** Blocked tables (blacklist) */
+    blockedTables?: string[];
+    /** Maximum rows to return (default: 100) */
+    maxRows?: number;
+    /** Query timeout in ms (default: 30000) */
+    timeout?: number;
+}
+export interface TableSchema {
+    name: string;
+    columns: ColumnSchema[];
+    primaryKey?: string[];
+    foreignKeys?: ForeignKey[];
+}
+export interface ColumnSchema {
+    name: string;
+    type: string;
+    nullable: boolean;
+    defaultValue?: string;
+    description?: string;
+}
+export interface ForeignKey {
+    columns: string[];
+    referencedTable: string;
+    referencedColumns: string[];
+}
+export interface QueryResult {
+    rows: any[];
+    rowCount: number;
+    fields: {
+        name: string;
+        type: string;
+    }[];
+    executionTime: number;
+}
+export interface NLQueryResult {
+    /** Natural language query */
+    query: string;
+    /** Generated SQL */
+    sql: string;
+    /** Query result */
+    result: QueryResult;
+    /** Explanation of the query */
+    explanation?: string;
+}
+/**
+ * Create a Natural Language Postgres client.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createNLPostgres } from 'praisonai/integrations/postgres';
+ *
+ * const db = await createNLPostgres({
+ *   connectionUrl: process.env.DATABASE_URL!,
+ *   readOnly: true
+ * });
+ *
+ * // Query with natural language
+ * const result = await db.query('Show me all users who signed up last month');
+ * console.log(result.rows);
+ * ```
+ *
+ * @example With schema introspection
+ * ```typescript
+ * const db = await createNLPostgres({ connectionUrl: '...' });
+ *
+ * // Get schema information
+ * const schema = await db.getSchema();
+ * console.log('Tables:', schema.map(t => t.name));
+ *
+ * // Query with context
+ * const result = await db.query('How many orders were placed today?');
+ * ```
+ */
+export declare function createNLPostgres(config: PostgresConfig): Promise<NLPostgresClient>;
+export declare class NLPostgresClient {
+    private config;
+    private pool;
+    private schema;
+    private connected;
+    constructor(config: PostgresConfig);
+    /**
+     * Connect to the database.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the database.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Load database schema.
+     */
+    private loadSchema;
+    /**
+     * Get the database schema.
+     */
+    getSchema(): TableSchema[];
+    /**
+     * Get schema as a string for LLM context.
+     */
+    getSchemaContext(): string;
+    /**
+     * Execute a raw SQL query.
+     */
+    executeSQL(sql: string): Promise<QueryResult>;
+    /**
+     * Query the database using natural language.
+     */
+    query(naturalLanguageQuery: string, options?: {
+        model?: string;
+    }): Promise<NLQueryResult>;
+    /**
+     * Chat with the database (conversational interface).
+     */
+    chat(message: string, options?: {
+        model?: string;
+        history?: Array<{
+            role: string;
+            content: string;
+        }>;
+    }): Promise<string>;
+    /**
+     * Inspect the database structure.
+     */
+    inspect(): Promise<{
+        tables: number;
+        schema: TableSchema[];
+        sampleData: Record<string, any[]>;
+    }>;
+}
+/**
+ * Create a tool for querying Postgres with natural language.
+ *
+ * @example Use with an agent
+ * ```typescript
+ * import { Agent } from 'praisonai';
+ * import { createPostgresTool } from 'praisonai/integrations/postgres';
+ *
+ * const dbTool = await createPostgresTool({
+ *   connectionUrl: process.env.DATABASE_URL!
+ * });
+ *
+ * const agent = new Agent({
+ *   instructions: 'You can query the database',
+ *   tools: [dbTool]
+ * });
+ * ```
+ */
+export declare function createPostgresTool(config: PostgresConfig): Promise<any>;