@coalex-ai/sdk 0.4.1 → 0.5.1

package/dist/metrics.d.ts

@@ -1,101 +0,0 @@
-/**
- * Coalex metrics functionality for performance tracking and monitoring.
- */
-export interface MetricRequestData {
-    requestId: string;
-    metricId: string;
-    value: number;
-    metricType?: string;
-    metadata?: Record<string, any>;
-    agentId?: string;
-    reviewingAgentId?: string;
-    taskId?: string;
-}
-export interface MetricResponseData {
-    id: number;
-    agentId: string;
-    accountId: string;
-    requestId: string;
-    metricId: string;
-    metricType?: string;
-    value: number;
-    metadata: Record<string, any>;
-    reviewingAgentId?: string;
-    taskId?: string;
-    createdAt: Date;
-}
-/**
- * Request object for metric submission.
- */
-export declare class MetricRequest {
-    requestId: string;
-    metricId: string;
-    value: number;
-    metricType?: string;
-    metadata: Record<string, any>;
-    agentId?: string;
-    reviewingAgentId?: string;
-    taskId?: string;
-    constructor(data: MetricRequestData);
-}
-/**
- * Response object for metric submissions.
- */
-export declare class MetricResponse {
-    id: number;
-    agentId: string;
-    accountId: string;
-    requestId: string;
-    metricId: string;
-    metricType?: string;
-    value: number;
-    metadata: Record<string, any>;
-    reviewingAgentId?: string;
-    taskId?: string;
-    createdAt: Date;
-    constructor(data: MetricResponseData);
-}
-export interface SubmitMetricOptions {
-    requestId: string;
-    metricId: string;
-    value: number;
-    metricType?: string;
-    metadata?: Record<string, any>;
-    agentId?: string;
-    reviewingAgentId?: string;
-    taskId?: string;
-    endpoint?: string;
-}
-/**
- * Submit a metric for performance tracking and monitoring.
- *
- * This function sends a metric to the coalex-ai-creator service to be stored
- * and made available for analysis and reporting.
- *
- * @param options - Metric submission options
- * @returns Promise that resolves to MetricResponse
- * @throws Error if required parameters are missing or the request fails
- *
- * @example
- * ```typescript
- * import { register, submitMetric } from '@coalex/sdk';
- *
- * // Register coalex first
- * register({ agentId: 'your-agent-id' });
- *
- * // Submit a precision metric
- * const response = await submitMetric({
- *   requestId: 'req_12345',
- *   metricId: 'model_precision',
- *   value: 0.92,
- *   metricType: 'precision',
- *   metadata: {
- *     modelVersion: 'v2.1.0',
- *     dataset: 'test_set_v1'
- *   }
- * });
- *
- * console.log(`Metric stored with ID: ${response.id}`);
- * ```
- */
-export declare function submitMetric(options: SubmitMetricOptions): Promise<MetricResponse>;

package/dist/metrics.js

@@ -1,192 +0,0 @@
-"use strict";
-/**
- * Coalex metrics functionality for performance tracking and monitoring.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MetricResponse = exports.MetricRequest = void 0;
-exports.submitMetric = submitMetric;
-const api_1 = require("@opentelemetry/api");
-const DEFAULT_CREATOR_ENDPOINT = 'https://creator.coalex.ai';
-/**
- * Request object for metric submission.
- */
-class MetricRequest {
-    constructor(data) {
-        this.requestId = data.requestId;
-        this.metricId = data.metricId;
-        this.value = data.value;
-        this.metricType = data.metricType;
-        this.metadata = data.metadata || {};
-        this.agentId = data.agentId;
-        this.reviewingAgentId = data.reviewingAgentId;
-        this.taskId = data.taskId;
-    }
-}
-exports.MetricRequest = MetricRequest;
-/**
- * Response object for metric submissions.
- */
-class MetricResponse {
-    constructor(data) {
-        this.id = data.id;
-        this.agentId = data.agentId;
-        this.accountId = data.accountId;
-        this.requestId = data.requestId;
-        this.metricId = data.metricId;
-        this.metricType = data.metricType;
-        this.value = data.value;
-        this.metadata = data.metadata;
-        this.reviewingAgentId = data.reviewingAgentId;
-        this.taskId = data.taskId;
-        this.createdAt = data.createdAt;
-    }
-}
-exports.MetricResponse = MetricResponse;
-/**
- * Extract agent_id from the current tracer provider's resource.
- */
-function getAgentIdFromTracer() {
-    try {
-        const tracerProvider = api_1.trace.getTracerProvider();
-        if (tracerProvider && tracerProvider.resource) {
-            const attributes = tracerProvider.resource.attributes;
-            return attributes['coalex.agent_id'];
-        }
-    }
-    catch (error) {
-        console.warn('Failed to get agent_id from tracer:', error);
-    }
-    return undefined;
-}
-/**
- * Submit a metric for performance tracking and monitoring.
- *
- * This function sends a metric to the coalex-ai-creator service to be stored
- * and made available for analysis and reporting.
- *
- * @param options - Metric submission options
- * @returns Promise that resolves to MetricResponse
- * @throws Error if required parameters are missing or the request fails
- *
- * @example
- * ```typescript
- * import { register, submitMetric } from '@coalex/sdk';
- *
- * // Register coalex first
- * register({ agentId: 'your-agent-id' });
- *
- * // Submit a precision metric
- * const response = await submitMetric({
- *   requestId: 'req_12345',
- *   metricId: 'model_precision',
- *   value: 0.92,
- *   metricType: 'precision',
- *   metadata: {
- *     modelVersion: 'v2.1.0',
- *     dataset: 'test_set_v1'
- *   }
- * });
- *
- * console.log(`Metric stored with ID: ${response.id}`);
- * ```
- */
-async function submitMetric(options) {
-    const { requestId, metricId, value, metricType, metadata, reviewingAgentId, taskId, endpoint = DEFAULT_CREATOR_ENDPOINT } = options;
-    if (!requestId) {
-        throw new Error('requestId is required');
-    }
-    if (!metricId) {
-        throw new Error('metricId is required');
-    }
-    if (value === null || value === undefined) {
-        throw new Error('value is required');
-    }
-    // Ensure value is a number
-    const numericValue = Number(value);
-    if (isNaN(numericValue)) {
-        throw new Error('value must be a numeric type');
-    }
-    // Auto-detect agent_id from tracer if not provided
-    let agentId = options.agentId;
-    if (!agentId) {
-        agentId = getAgentIdFromTracer();
-        if (!agentId) {
-            throw new Error('agentId is required. Either pass it explicitly or ensure register() was called first.');
-        }
-    }
-    // Create metric request
-    const metricRequest = new MetricRequest({
-        requestId,
-        metricId,
-        value: numericValue,
-        metricType,
-        metadata,
-        agentId,
-        reviewingAgentId,
-        taskId
-    });
-    // Prepare request payload
-    const payload = {
-        request_id: metricRequest.requestId,
-        metric_id: metricRequest.metricId,
-        value: metricRequest.value,
-        agent_id: metricRequest.agentId
-    };
-    // Add optional fields if provided
-    if (metricRequest.metricType) {
-        payload.metric_type = metricRequest.metricType;
-    }
-    if (metricRequest.metadata && Object.keys(metricRequest.metadata).length > 0) {
-        payload.metadata = metricRequest.metadata;
-    }
-    if (metricRequest.reviewingAgentId) {
-        payload.reviewing_agent_id = metricRequest.reviewingAgentId;
-    }
-    if (metricRequest.taskId) {
-        payload.task_id = metricRequest.taskId;
-    }
-    // Prepare headers for authentication
-    const headers = {
-        'Authorization': `Bearer ${agentId}`,
-        'Content-Type': 'application/json'
-    };
-    // Build URL
-    const url = `${endpoint}/metrics`;
-    console.log(`Submitting metric ${metricId} for request ${requestId} (agent: ${agentId})`);
-    try {
-        // Make HTTP request
-        const response = await fetch(url, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(payload)
-        });
-        // Check response status
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`HTTP ${response.status}: ${errorText}`);
-        }
-        // Parse response
-        const responseData = await response.json();
-        // Parse created_at timestamp
-        const createdAt = new Date(responseData.created_at);
-        const metricResponse = new MetricResponse({
-            id: responseData.id,
-            agentId: responseData.agent_id,
-            accountId: responseData.account_id,
-            requestId: responseData.request_id,
-            metricId: responseData.metric_id,
-            metricType: responseData.metric_type,
-            value: responseData.value,
-            metadata: responseData.metadata || {},
-            reviewingAgentId: responseData.reviewing_agent_id,
-            taskId: responseData.task_id,
-            createdAt
-        });
-        console.log(`Metric ${metricId} submitted successfully. ID: ${metricResponse.id}`);
-        return metricResponse;
-    }
-    catch (error) {
-        console.error(`Failed to submit metric ${metricId} for request ${requestId}:`, error);
-        throw error;
-    }
-}

package/dist/otel/register.d.ts

@@ -1,98 +0,0 @@
-/**
- * Coalex OpenTelemetry registration and setup.
- */
-import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
-export interface RegisterOptions {
-    agentId: string;
-    endpoint?: string;
-    serviceName?: string;
-    serviceVersion?: string;
-    additionalAttributes?: Record<string, string | number | boolean>;
-}
-export interface CoalexContextOptions {
-    requestId: string;
-    promptVersion: string;
-    spanName?: string;
-}
-/**
- * Register Coalex OpenTelemetry tracing with Coalex OTLP endpoint.
- *
- * @param options - Configuration options for tracing
- * @returns Configured TracerProvider instance
- *
- * @example
- * ```typescript
- * import { register } from '@coalex/sdk';
- *
- * const tracerProvider = register({
- *   agentId: 'YOUR_AGENT_ID'
- * });
- * ```
- */
-export declare function register(options: RegisterOptions): NodeTracerProvider;
-/**
- * Add request context to the current span.
- *
- * This function adds attributes to the current active span if one exists.
- * For better attribute propagation, consider using coalexContext() instead.
- *
- * @param requestId - Unique request identifier
- * @param promptVersion - Version of the prompt being used
- *
- * @example
- * ```typescript
- * import { addRequestContext } from '@coalex/sdk';
- *
- * addRequestContext('req_001', 'v1.0.0');
- * ```
- */
-export declare function addRequestContext(requestId: string, promptVersion: string): void;
-/**
- * Execute a function within a Coalex context that ensures attributes are propagated to child spans.
- *
- * @param options - Context options including requestId and promptVersion
- * @param fn - The function to execute within the context
- * @returns Promise that resolves with the function result
- *
- * @example
- * ```typescript
- * import { coalexContext } from '@coalex/sdk';
- *
- * await coalexContext(
- *   {
- *     requestId: 'req_001',
- *     promptVersion: 'v1.0.0'
- *   },
- *   async () => {
- *     // Any OpenTelemetry instrumented calls here will inherit the attributes
- *     const response = await someApiCall();
- *     return response;
- *   }
- * );
- * ```
- */
-export declare function coalexContext<T>(options: CoalexContextOptions, fn: () => Promise<T> | T): Promise<T>;
-/**
- * Synchronous version of coalexContext for non-async operations.
- *
- * @param options - Context options including requestId and promptVersion
- * @param fn - The function to execute within the context
- * @returns The function result
- *
- * @example
- * ```typescript
- * import { coalexContextSync } from '@coalex/sdk';
- *
- * const result = coalexContextSync(
- *   {
- *     requestId: 'req_001',
- *     promptVersion: 'v1.0.0'
- *   },
- *   () => {
- *     // Synchronous operations here
- *     return someValue;
- *   }
- * );
- * ```
- */
-export declare function coalexContextSync<T>(options: CoalexContextOptions, fn: () => T): T;

package/dist/otel/register.js

@@ -1,200 +0,0 @@
-"use strict";
-/**
- * Coalex OpenTelemetry registration and setup.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.register = register;
-exports.addRequestContext = addRequestContext;
-exports.coalexContext = coalexContext;
-exports.coalexContextSync = coalexContextSync;
-const api_1 = require("@opentelemetry/api");
-const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
-const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
-const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
-const resources_1 = require("@opentelemetry/resources");
-const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
-const DEFAULT_COALEX_ENDPOINT = 'https://traces.coalex.ai/v1/traces';
-/**
- * Register Coalex OpenTelemetry tracing with Coalex OTLP endpoint.
- *
- * @param options - Configuration options for tracing
- * @returns Configured TracerProvider instance
- *
- * @example
- * ```typescript
- * import { register } from '@coalex/sdk';
- *
- * const tracerProvider = register({
- *   agentId: 'YOUR_AGENT_ID'
- * });
- * ```
- */
-function register(options) {
-    const { agentId, endpoint = DEFAULT_COALEX_ENDPOINT, serviceName = 'coalex-service', serviceVersion = '0.1.0', additionalAttributes = {} } = options;
-    if (!agentId) {
-        throw new Error('agentId is required');
-    }
-    // Create resource with service information
-    const resourceAttributes = {
-        [semantic_conventions_1.ATTR_SERVICE_NAME]: serviceName,
-        [semantic_conventions_1.ATTR_SERVICE_VERSION]: serviceVersion,
-        'coalex.agent_id': agentId,
-        ...additionalAttributes
-    };
-    const resource = new resources_1.Resource(resourceAttributes);
-    // Create tracer provider
-    const tracerProvider = new sdk_trace_node_1.NodeTracerProvider({
-        resource
-    });
-    // Create OTLP exporter with agent_id in headers for auth
-    const exporter = new exporter_trace_otlp_http_1.OTLPTraceExporter({
-        url: endpoint,
-        headers: {
-            'Authorization': `Bearer ${agentId}`,
-            'X-Agent-ID': agentId
-        }
-    });
-    // Create batch span processor
-    const spanProcessor = new sdk_trace_base_1.BatchSpanProcessor(exporter);
-    tracerProvider.addSpanProcessor(spanProcessor);
-    // Set as global tracer provider
-    tracerProvider.register();
-    console.log(`Coalex tracing registered for agent ${agentId} -> ${endpoint}`);
-    return tracerProvider;
-}
-/**
- * Add request context to the current span.
- *
- * This function adds attributes to the current active span if one exists.
- * For better attribute propagation, consider using coalexContext() instead.
- *
- * @param requestId - Unique request identifier
- * @param promptVersion - Version of the prompt being used
- *
- * @example
- * ```typescript
- * import { addRequestContext } from '@coalex/sdk';
- *
- * addRequestContext('req_001', 'v1.0.0');
- * ```
- */
-function addRequestContext(requestId, promptVersion) {
-    const span = api_1.trace.getActiveSpan();
-    if (span && span.isRecording()) {
-        span.setAttribute('session.id', requestId);
-        span.setAttribute('prompt.version', promptVersion);
-    }
-    else {
-        console.warn('addRequestContext called without an active span. ' +
-            'Consider using coalexContext() for better attribute propagation.');
-    }
-}
-/**
- * Execute a function within a Coalex context that ensures attributes are propagated to child spans.
- *
- * @param options - Context options including requestId and promptVersion
- * @param fn - The function to execute within the context
- * @returns Promise that resolves with the function result
- *
- * @example
- * ```typescript
- * import { coalexContext } from '@coalex/sdk';
- *
- * await coalexContext(
- *   {
- *     requestId: 'req_001',
- *     promptVersion: 'v1.0.0'
- *   },
- *   async () => {
- *     // Any OpenTelemetry instrumented calls here will inherit the attributes
- *     const response = await someApiCall();
- *     return response;
- *   }
- * );
- * ```
- */
-async function coalexContext(options, fn) {
-    const { requestId, promptVersion, spanName = 'coalex_operation' } = options;
-    const tracer = api_1.trace.getTracer('coalex');
-    // Get agent_id from the current tracer provider's resource
-    let agentId;
-    const tracerProvider = api_1.trace.getTracerProvider();
-    if (tracerProvider && tracerProvider.resource) {
-        const attributes = tracerProvider.resource.attributes;
-        agentId = attributes['coalex.agent_id'];
-    }
-    return tracer.startActiveSpan(spanName, async (span) => {
-        try {
-            // Set Coalex attributes
-            if (agentId) {
-                span.setAttribute('account_id', agentId);
-            }
-            span.setAttribute('session.id', requestId);
-            span.setAttribute('prompt.version', promptVersion);
-            // Execute the function
-            const result = await fn();
-            span.end();
-            return result;
-        }
-        catch (error) {
-            // Record the error and re-throw
-            span.recordException(error);
-            span.end();
-            throw error;
-        }
-    });
-}
-/**
- * Synchronous version of coalexContext for non-async operations.
- *
- * @param options - Context options including requestId and promptVersion
- * @param fn - The function to execute within the context
- * @returns The function result
- *
- * @example
- * ```typescript
- * import { coalexContextSync } from '@coalex/sdk';
- *
- * const result = coalexContextSync(
- *   {
- *     requestId: 'req_001',
- *     promptVersion: 'v1.0.0'
- *   },
- *   () => {
- *     // Synchronous operations here
- *     return someValue;
- *   }
- * );
- * ```
- */
-function coalexContextSync(options, fn) {
-    const { requestId, promptVersion, spanName = 'coalex_operation' } = options;
-    const tracer = api_1.trace.getTracer('coalex');
-    // Get agent_id from the current tracer provider's resource
-    let agentId;
-    const tracerProvider = api_1.trace.getTracerProvider();
-    if (tracerProvider && tracerProvider.resource) {
-        const attributes = tracerProvider.resource.attributes;
-        agentId = attributes['coalex.agent_id'];
-    }
-    return tracer.startActiveSpan(spanName, (span) => {
-        try {
-            // Set Coalex attributes
-            if (agentId) {
-                span.setAttribute('account_id', agentId);
-            }
-            span.setAttribute('session.id', requestId);
-            span.setAttribute('prompt.version', promptVersion);
-            // Execute the function
-            const result = fn();
-            span.end();
-            return result;
-        }
-        catch (error) {
-            // Record the error and re-throw
-            span.recordException(error);
-            span.end();
-            throw error;
-        }
-    });
-}