API Reference

import { createOrka } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import { collector } from '@orka-js/collector';
    
// 1 - Initialize DevTools in local mode
const { tracer, stop } = await collector({ 
    source: 'local',
    port: 3001,
    open: true  // Automatically open the dashboard
});

// 2 - Configure Orka with the integrated tracer
const orka = createOrka({
    llm: new OpenAIAdapter({ 
        apiKey: process.env.OPENAI_API_KEY!,
        timeoutMs: 30000
    }),
    vectorDB: new MemoryVectorAdapter(),
    // Tracer injection for automatic tracing
    tracer,
    defaults: {
        chunkSize: 500,
        topK: 3,
    },
});

// 3 - Usage - automatic and transparent tracing
console.log('🚀 Starting the demo...');

// Create a knowledge base
await orka.knowledge.create({
    name: 'documentation',
    source: [
        'OrkaJS is a TypeScript framework for LLM systems.',
        'It supports OpenAI, Anthropic, Mistral and Ollama.',
        'Vector databases: Pinecone, Qdrant, Chroma, in-memory.',
    ],
});

// Question with automatic RAG tracing
const result = await orka.ask({
    knowledge: 'documentation',
    question: 'What LLM providers are supported?',
});

console.log('Result:', result);

// 4 - Cleanup
await orka.knowledge.delete('documentation');
await stop(); // Stop the DevTools server
 
//🎯 RESULT IN THE DASHBOARD:
//• Main trace: "ask-operation"
//• Sub-traces: knowledge retrieval, LLM call, response generation
//• Metrics: latency, tokens, cost
//• Hierarchical tree visualization

import { createOrka } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import { trace } from '@orka-js/collector';

const orka = createOrka({
    llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! })
});

// 1 - Start a tracing session (logical group of operations)
const sessionId = trace.session('Support Client - Ticket #TCK-1234');

console.log('Session started: ' + sessionId);

// 2 - Trace a complete RAG operation with detailed metadata
const ragRunId = trace.start('workflow', 'RAG Query Processing', {
    query: 'How to configure Redis cache in OrkaJS?',
    knowledge: 'documentation',
    userId: 'user-456',
    ticketId: 'TCK-1234',
    priority: 'high'
}, {
    category: 'technical-support',
    complexity: 'medium',
    estimatedTokens: 1500
});

try {
    // Step 1: Retrieval from knowledge base
    const retrievalRunId = trace.start('retrieval', 'Knowledge Search', {
        query: 'Redis cache configuration OrkaJS',
        topK: 5
    });
    
    // Simulation of search (replace with actual call)
    const retrievedDocs = [
        { content: 'Redis cache configuration...', score: 0.95 },
        { content: 'Cache best practices...', score: 0.87 }
    ];
    
    trace.end(retrievalRunId, {
        documents: retrievedDocs.length,
        avgScore: retrievedDocs.reduce((sum, doc) => sum + doc.score, 0) / retrievedDocs.length,
        searchTime: 45
    });

    // Step 2: Generate response with LLM
    const llmRunId = trace.start('llm', 'Generate Technical Response', {
        prompt: 'Based on the retrieved docs...',
        model: 'gpt-4',
        maxTokens: 500
    });
    
    const result = await orka.ask({
        knowledge: 'documentation',
        question: 'How to configure Redis cache in OrkaJS?'
    });
    
    trace.end(llmRunId, result, {
        responseLength: result.length,
        actualTokens: 342,
        model: 'gpt-4',
        temperature: 0.1
    });

    // 3 - Finalize the RAG tracing
    trace.end(ragRunId, {
        finalResponse: result,
        totalProcessingTime: 1250,
        customerSatisfaction: 'resolved'
    });
    
    console.log('Ticket processed successfully');
    
} catch (error) {
    // Error handling with tracing
    trace.error(ragRunId, error instanceof Error ? error: new Error(String(error)));
    console.error('Error during processing:', error);
}

// 4 - Finalize the session
trace.endSession(sessionId);

// 5 - Retrieve session metrics
const collector = getCollector();
const sessionMetrics = collector.getMetrics(sessionId);

console.log('Metrics of the session:', {
    totalRuns: sessionMetrics.totalRuns,
    avgLatency: `${sessionMetrics.avgLatencyMs.toFixed(2)}ms`,
    totalTokens: sessionMetrics.totalTokens,
    errorRate: `${(sessionMetrics.errorRate * 100).toFixed(1)}%`
});

//🎯 RESULT:
//• Session structured with business context
//• Hierarchical runs with rich metadata
//• Error handling with preserved context
//• Metrics per session for analysis

import { createOrka } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import { withTrace } from '@orka-js/collector';
    
const orka = createOrka({
    llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! })
});

// 1 - Existing function (without modification)
async function processUserQuery(query: string, options?: {
    maxResults?: number;
    includeSources?: boolean;
}) {
    console.log('Processing query: ' + query);
    
    // Complex business logic
    const result = await orka.ask({
        question: query,
        knowledge: 'documentation',
        topK: options?.maxResults ?? 3
    });
    
    if (options?.includeSources) {
        return {
            answer: result,
            sources: ['doc-1', 'doc-2', 'doc-3'], // Simulation
            metadata: {
            processedAt: new Date().toISOString(),
            queryLength: query.length
            }
        };
    }
    
    return result;
}

// 2 - Automatic wrapping with tracing
const tracedProcessQuery = withTrace(
    processUserQuery,
    { 
        name: 'Query Processing Pipeline',
        type: 'workflow' as const,
        // Automatic metadata for each call
        metadata: {
            version: '2.1.0',
            service: 'user-support',
            environment: 'production'
        }
    }
);

// 3 - Usage - automatic tracing
async function handleCustomerRequests() {
    const queries = [
        'Comment installer OrkaJS ?',
        'Quels sont les providers LLM supportés ?',
        'Comment configurer le cache ?'
    ];
    
    for (const query of queries) {
        try {
            console.log('Processing:' + query);
        
            // Normal call - automatic tracing in background
            const result = await tracedProcessQuery(query, {
                maxResults: 5,
                includeSources: true
            });
        
            console.log('Result:', result);
        
        } catch (error) {
            console.error('Error for "' + query + '":', error);
        }
    }
}

// 4 - Wrapper for utility functions
const tracedLogger = withTrace(
    async (level: 'info' | 'warn' | 'error', message: string, data?: any) => {
        // Existing logging logic
        const timestamp = new Date().toISOString();
        console.log('[' + timestamp + '] [' + level.toUpperCase() + '] ' + message, data || '');
    
        // Simulation of sending to external service
        await new Promise(resolve => setTimeout(resolve, 10));
    },
    {
        name: 'External Logging',
        type: 'tool' as const,
        metadata: {
            provider: 'datadog',
            retention: '30d'
        }
    }
);

// 5 - Execution of the demo
await handleCustomerRequests();

// Logging with tracing
await tracedLogger('info', 'Demo completed successfully', {
    totalQueries: 3,
    avgLatency: 850
});

//🎯 ADVANTAGES:
//• No modification of the original code
//• Automatic and consistent tracing
//• Automatically enriched metadata
//• Error handling preserved
//• Reusable for any function

import { createOrka } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import { MemoryVectorAdapter } from '@orka-js/memory';
import { Trace } from '@orka-js/collector';

// 1- Initial configuration
const orka = createOrka({
    llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
    vectorDB: new MemoryVectorAdapter()
});

// 2- Service class with decorators
class CustomerSupportAgent {
    private readonly agentId: string;
    private readonly version: string = '1.2.0';

    constructor(agentId: string) {
        this.agentId = agentId;
    }

    @Trace({  name: 'Generate Technical Response', type: 'agent' as const,
        metadata: {
            category: 'customer-support',
            criticality: 'high'
        }
    })
    async generateResponse(query: string, context?: {
        userId?: string;
        sessionId?: string;
        priority?: 'low' | 'medium' | 'high';
    }): Promise<{
        response: string;
        confidence: number;
        sources: string[];
        processingTime: number;
    }> {
        const startTime = Date.now();
    
        try {
            // Business logic
            const result = await orka.ask({
                question: query,
                knowledge: 'support-docs',
                system: `You are a technical support agent (ID: ${this.agentId}). Respond with precision and empathy.`
            });

            const processingTime = Date.now() - startTime;
            
            return {
                response: result,
                confidence: 0.92,
                sources: ['kb-123', 'kb-456'],
                processingTime
            };
            
        } catch (error) {
            // Errors are automatically traced by the decorator
            throw new Error(`Failed to generate response: ${error instanceof Error ? error.message : String(error)}`);
        }
    }


    @Trace({ name: 'Create Knowledge Base', type: 'retrieval' as const,
        metadata: {
            operation: 'knowledge-ingestion',
            batch: true
        }
    })
    async createKnowledgeBase(docs: {
        title: string;
        content: string;
        category: string;
        tags: string[];
    }[]): Promise<void> {
    console.log(`📚 Ingesting ${docs.length} documents...`);
    
    // Document preparation
    const processedDocs = docs.map(doc => ({
        ...doc,
        processedAt: new Date().toISOString(),
        agentVersion: this.version
    }));

    // Creation in Orka
    await orka.knowledge.create({
        name: 'support-docs',
        source: processedDocs.map(doc => doc.content)
    });

        console.log('Knowledge base created successfully');
    }

    @Trace({ name: 'Update Agent Configuration', type: 'custom' as const })
    updateConfiguration(config: {
        temperature?: number;
        maxTokens?: number;
        model?: string;
    }): void {
    // Configuration logic
    console.log(' Configuration updated:', config);
    
        // Simulation of validation
        if (config.temperature && (config.temperature < 0 || config.temperature > 2)) {
            throw new Error('Temperature must be between 0 and 2');
        }
    }

    // Method without decorator (not traced)
    private internalHelper(data: any): void {
        // Internal logic - no automatic tracing
        console.log('🔧 Internal processing:', data);
    }
}

// 3 - Inherited class with tracing
class AdvancedSupportAgent extends CustomerSupportAgent {
    
    @Trace({ name: 'Multi-step Problem Resolution', type: 'workflow' as const })
    async resolveComplexIssue(issue: {
        description: string;
        severity: 'low' | 'medium' | 'high' | 'critical';
        category: string;
    }): Promise<{
        resolution: string;
        steps: string[];
        escalation: boolean;
    }> {
        const steps: string[] = [];
    
        try {
            // Step 1: Problem analysis
            steps.push('Problem analysis');
            const analysis = await this.generateResponse(
                `Analyze this problem: ${issue.description}`,
                { priority: issue.severity }
            );

            // Step 2: Solution search
            steps.push('Solution search');
            const solutions = await this.generateResponse(
                `Find solutions for: ${issue.description}`,
                { priority: issue.severity }
            );

            // Step 3: Resolution generation
            steps.push('Resolution generation');
            const resolution = await this.generateResponse(
                `Generate a complete resolution based on the analysis and solutions`,
                { priority: issue.severity }
            );

            return {
                resolution: resolution.response,
                steps,
                escalation: issue.severity === 'critical'
            };

        } catch (error) {
            steps.push('Resolution failed');
            throw error;
        }
    }
}

// 4 - Usage
async function demoSupportAgent() {
    console.log('🚀 Starting support agent...');
    
    // Create agent
    const agent = new CustomerSupportAgent('agent-007');
    
    // Configuration (automatically traced)
    agent.updateConfiguration({
        temperature: 0.1,
        maxTokens: 1000,
        model: 'gpt-4'
    });

    // Create knowledge base (automatically traced)
    await agent.createKnowledgeBase([
        {
            title: 'Installation Guide',
            content: 'OrkaJS is installed with npm install orajs...',
            category: 'installation',
            tags: ['setup', 'npm', 'installation']
        },
        {
            title: 'Redis configuration',
            content: 'To configure Redis cache...',
            category: 'configuration',
            tags: ['redis', 'cache', 'configuration']
        }
    ]);

    // Generate response (automatically traced)
    const response = await agent.generateResponse(
        'How to configure Redis cache?',
        {
            userId: 'user-123',
            sessionId: 'session-456',
            priority: 'high'
        }
    );

    console.log('Response generated:', response);

    // Advanced agent
    const advancedAgent = new AdvancedSupportAgent('agent-elite');
    
    const resolution = await advancedAgent.resolveComplexIssue({
        description: 'The application does not start after update',
        severity: 'critical',
        category: 'technical'
    });

    console.log('Complex resolution:', resolution);
}

// 5 - Execution
await demoSupportAgent();

//🎯 ADVANTAGES OF DECORATORS:
//• Declarative and elegant syntax
//• No pollution of business code
//• Inheritance preserved
//• Centralized configuration
//• Errors traced automatically
//• Ideal for object-oriented architecture

import { createOrka } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import { devtools } from '@orka-js/collector';

// 1 - Configuration Production - Mode Agent (send traces)
const { tracer, stop } = await devtools({
    source: 'remote',
    mode: 'agent',
    remote: {
        endpoint: 'https://traces.company.com',
        apiKey: process.env.COLLECTOR_API_KEY!,
        projectId: 'customer-support-ai',
        environment: 'production',
        sampling: 0.1, // 10% of traces to control costs
        batchSize: 50, // Send in batches of 50 traces
        flushInterval: 5000 // Force send every 5s
    },
    verbose: true,
    // Local fallback configuration
    fallback: {
        enableLocalCache: true,
        maxCacheSize: 1000,
        retryAttempts: 3,
        retryDelay: 1000
    }
});

// 2 - Configuration Orka for production
const orka = createOrka({
    llm: new OpenAIAdapter({ 
        apiKey: process.env.OPENAI_API_KEY!,
        timeoutMs: 30000,
        maxRetries: 3
    }),
    tracer,
    // Resilience configuration
    resilience: {
    retry: { attempts: 3, backoff: 'exponential' },
            fallback: { 
                primary: 'gpt-4',
                fallback: 'gpt-3.5-turbo' 
            }
    }
});

// 3 - Production service with tracing
class ProductionSupportService {
    private readonly serviceVersion = '2.3.1';
    private readonly region = process.env.AWS_REGION || 'us-east-1';

    async handleCustomerRequest(request: {
        userId: string;
        query: string;
        sessionId: string;
        priority: 'low' | 'medium' | 'high' | 'urgent';
    }): Promise<{
        response: string;
        confidence: number;
        processingTime: number;
        traceId?: string;
    }> {
        const startTime = Date.now();
        
            try {
                // Automatic tracing via injected tracer
                const result = await orka.ask({
                    question: request.query,
                    knowledge: 'production-docs',
                    system: `Service de support (v${this.serviceVersion}) - Priorité: ${request.priority}`,
                    metadata: {
                        userId: request.userId,
                        sessionId: request.sessionId,
                        region: this.region,
                        priority: request.priority,
                        serviceVersion: this.serviceVersion
                    }
                });

                const processingTime = Date.now() - startTime;

                return {
                    response: result,
                    confidence: 0.89,
                    processingTime
                };

            } catch (error) {
                // Errors are automatically tracked.
                console.error(`Request processing error ${request.userId}:`, error);
                throw error;
            }
        }

        // Health metrics of the service
        async getHealthMetrics(): Promise<{
            status: 'healthy' | 'degraded' | 'unhealthy';
            avgLatency: number;
            errorRate: number;
            totalRequests: number;
            uptime: number;
        }> {
            const collector = getCollector();
            const metrics = collector.getMetrics();
            
            const avgLatency = metrics.avgLatencyMs;
            const errorRate = metrics.errorRate;
            const totalRequests = metrics.totalRuns;
            
            // Determine health status
            let status: 'healthy' | 'degraded' | 'unhealthy';
            if (errorRate > 0.1 || avgLatency > 5000) {
                status = 'unhealthy';
            } else if (errorRate > 0.05 || avgLatency > 3000) {
                status = 'degraded';
            } else {
                status = 'healthy';
            }

            return {
                status,
                avgLatency,
                errorRate,
                totalRequests,
                uptime: process.uptime()
            };
        }
}

// 4 - Monitoring and alerts
class ProductionMonitor {
    private alertThresholds = {
        maxLatency: 3000, // 3s
        maxErrorRate: 0.05, // 5%
        minSuccessRate: 0.95 // 95%
    };

    async startMonitoring(): Promise<void> {
        const collector = getCollector();
    
        // Subscription to tracing events
        collector.subscribe((event) => {
            if (event.type === 'run:end') {
                const { run } = event;
                
                // Alertes de latence
                if (run.latencyMs && run.latencyMs > this.alertThresholds.maxLatency) {
                    this.sendAlert('HIGH_LATENCY', {
                    operation: run.name,
                    latency: run.latencyMs,
                    threshold: this.alertThresholds.maxLatency
                    });
                }
            }
            
            if (event.type === 'run:error') {
                this.sendAlert('OPERATION_ERROR', {
                    operation: event.run.name,
                    error: event.error,
                    severity: this.getSeverity(event.run.type)
                });
            }
        });

        // Periodic monitoring
        setInterval(async () => {
            const metrics = collector.getMetrics();
            await this.checkHealth(metrics);
        }, 30000); // Every 30s
    }

    private async sendAlert(type: string, data: any): Promise<void> {
        // Sending alerts to your monitoring system
        console.log(`🚨 ALERT [${type}]:`, data);
        
        // Integration with PagerDuty, Slack, etc.
        await this.pagerDuty.trigger(type, data);
        await this.slack.sendAlert(type, data);
    }

    private getSeverity(operationType: string): 'low' | 'medium' | 'high' | 'critical' {
        const severityMap = {
            'llm': 'critical',
            'agent': 'high',
            'retrieval': 'medium',
            'tool': 'low'
        };
        return severityMap[operationType as keyof typeof severityMap] || 'medium';
    }

    private async checkHealth(metrics: any): Promise<void> {
        if (metrics.errorRate > this.alertThresholds.maxErrorRate) {
                await this.sendAlert('HIGH_ERROR_RATE', {
                currentRate: metrics.errorRate,
                threshold: this.alertThresholds.maxErrorRate
            });
        }
    }
}

// 5 - Deployment and usage
async function deployProductionService() {
    console.log('Deployment of the production service...');
    
    const supportService = new ProductionSupportService();
    const monitor = new ProductionMonitor();
    
    // Starting monitoring
    await monitor.startMonitoring();
    
    // Simulation of production requests
    const requests = [
        { userId: 'user-001', query: 'How to reset my password?', sessionId: 'sess-001', priority: 'urgent' },
        { userId: 'user-002', query: 'API key configuration', sessionId: 'sess-002', priority: 'high' },
        { userId: 'user-003', query: 'Installation guide', sessionId: 'sess-003', priority: 'low' }
    ];
    
    for (const req of requests) {
        try {
            const result = await supportService.handleCustomerRequest(req);
            console.log(`${req.userId} request traited in ${result.processingTime}ms`);
        } catch (error) {
            console.error(`Failure request ${req.userId}:`, error);
        }
    }
    
    // Checking health
    const health = await supportService.getHealthMetrics();
    console.log('Service health:', health);
    
    // Proper shutdown
    await stop();
}

// 6 - Execution
await deployProductionService();

//🎯 AVANTAGES PRODUCTION:
//• Centralized traces for analysis
//• Sampling for cost control
//• Real-time monitoring with alerts
//• Built-in fallback and resilience
//• Automatic health metrics
//• Compatible with cloud infrastructure