@coalex-ai/sdk 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Coalex.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# Coalex SDK for TypeScript
+
+A TypeScript package for OpenTelemetry integration with Coalex.ai observability platform.
+
+## Installation
+
+```bash
+npm install @coalex-ai/sdk
+```
+
+## Quick Start
+
+```typescript
+import { register, coalexContext } from '@coalex-ai/sdk';
+
+// Register Coalex tracing
+const tracerProvider = register({
+  agentId: 'YOUR_AGENT_ID'
+});
+
+// Use coalexContext for proper span management and attribute propagation
+await coalexContext(
+  {
+    requestId: 'req_001',
+    promptVersion: 'v1.0.0'
+  },
+  async () => {
+    // Your instrumented code here
+    // Any OpenTelemetry instrumented calls will be traced with proper context
+    const result = await someApiCall();
+    return result;
+  }
+);
+```
+
+## Features
+
+- **Simple Setup**: One-line registration with `register()`
+- **Coalex Integration**: Default endpoint for Coalex observability platform
+- **Context Management**: Use `coalexContext()` for proper span hierarchy and attribute propagation
+- **OpenTelemetry Compatible**: Works with all OpenTelemetry instrumentations
+- **Authentication**: Automatic authentication using agent_id
+- **Human-in-the-Loop**: Approval workflow for human review
+- **Metrics Tracking**: Submit and track performance metrics
+
+## Configuration
+
+### Register
+
+```typescript
+import { register } from '@coalex/sdk';
+
+const tracerProvider = register({
+  agentId: 'YOUR_AGENT_ID',              // Required: Your unique agent identifier
+  endpoint: 'https://custom-endpoint',    // Optional: Custom OTLP endpoint
+  serviceName: 'my-service',              // Optional: Service name (default: 'coalex-service')
+  serviceVersion: '1.0.0',                // Optional: Service version
+  additionalAttributes: {                 // Optional: Additional resource attributes
+    environment: 'production'
+  }
+});
+```
+
+## API Reference
+
+### Tracing
+
+#### `register(options: RegisterOptions)`
+
+Register Coalex OpenTelemetry tracing with the Coalex platform.
+
+**Parameters:**
+- `agentId` (required): Your unique agent identifier for authentication
+- `endpoint` (optional): OTLP endpoint URL (defaults to `https://traces.coalex.ai/v1/traces`)
+- `serviceName` (optional): Name of your service (defaults to `'coalex-service'`)
+- `serviceVersion` (optional): Version of your service (defaults to `'0.1.0'`)
+- `additionalAttributes` (optional): Additional resource attributes to include
+
+**Returns:** `NodeTracerProvider` - The configured tracer provider
+
+#### `coalexContext(options, fn)`
+
+Execute a function within a Coalex context that ensures attributes are propagated to child spans.
+
+**Parameters:**
+- `options.requestId` (required): Unique request identifier
+- `options.promptVersion` (required): Version of the prompt being used
+- `options.spanName` (optional): Name for the context span (defaults to `'coalex_operation'`)
+- `fn`: The async function to execute within the context
+
+**Returns:** `Promise<T>` - Promise that resolves with the function result
+
+**Example:**
+```typescript
+await coalexContext(
+  {
+    requestId: 'req_12345',
+    promptVersion: 'v2.0.0'
+  },
+  async () => {
+    // Your code here
+    return await someOperation();
+  }
+);
+```
+
+#### `coalexContextSync(options, fn)`
+
+Synchronous version of `coalexContext` for non-async operations.
+
+**Example:**
+```typescript
+const result = coalexContextSync(
+  {
+    requestId: 'req_12345',
+    promptVersion: 'v2.0.0'
+  },
+  () => {
+    // Your synchronous code here
+    return someValue;
+  }
+);
+```
+
+#### `addRequestContext(requestId, promptVersion)`
+
+Add request context to the current active span. For better attribute propagation, consider using `coalexContext()` instead.
+
+### Approval
+
+#### `approve(options: ApproveOptions)`
+
+Submit an approval request for human-in-the-loop review.
+
+**Parameters:**
+- `requestId` (required): Unique identifier for this approval request
+- `inputData` (optional): Input data provided to your AI system
+- `outputData` (optional): Output data generated by your AI system
+- `version` (optional): Version of your prompt/model (defaults to `'1.0.0'`)
+- `slaSeconds` (optional): SLA in seconds for human review (defaults to 3600)
+- `agentId` (optional): Agent ID for authentication (auto-detected if not provided)
+- `urlParams` (optional): Additional URL parameters for the review interface
+- `eval` (optional): Evaluation control - string (use provided eval_id), true (generate eval_id), false/null (skip eval)
+- `endpoint` (optional): Creator service endpoint
+
+**Returns:** `Promise<ApprovalResponse>` - The approval response
+
+**Example:**
+```typescript
+import { approve } from '@coalex/sdk';
+
+const response = await approve({
+  requestId: 'req_12345',
+  inputData: { userQuery: 'What is the weather?' },
+  outputData: { response: "It's sunny today" },
+  version: 'v1.2.0'
+});
+
+console.log(`Approval task created: ${response.taskId}`);
+console.log(`Status: ${response.status}`);
+
+if (response.isAutoApproved) {
+  console.log('Request was auto-approved');
+} else if (response.needsHumanReview) {
+  console.log('Request needs human review');
+}
+```
+
+### Metrics
+
+#### `submitMetric(options: SubmitMetricOptions)`
+
+Submit a metric for performance tracking and monitoring.
+
+**Parameters:**
+- `requestId` (required): Unique identifier for the request that generated this metric
+- `metricId` (required): Identifier for the type/name of metric
+- `value` (required): Numeric value for the metric
+- `metricType` (optional): Type category of the metric (e.g., "precision", "recall")
+- `metadata` (optional): Additional contextual data for the metric
+- `agentId` (optional): Agent ID for authentication (auto-detected if not provided)
+- `reviewingAgentId` (optional): ID of agent that reviewed/validated this metric
+- `taskId` (optional): Associated task identifier if applicable
+- `endpoint` (optional): Creator service endpoint
+
+**Returns:** `Promise<MetricResponse>` - The metric response
+
+**Example:**
+```typescript
+import { submitMetric } from '@coalex/sdk';
+
+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}`);
+```
+
+## Complete Example
+
+```typescript
+import { register, coalexContext, approve, submitMetric } from '@coalex-ai/sdk';
+
+// 1. Register tracing
+register({
+  agentId: 'YOUR_AGENT_ID',
+  serviceName: 'my-ai-service'
+});
+
+// 2. Use context for traced operations
+await coalexContext(
+  {
+    requestId: 'req_001',
+    promptVersion: 'v1.0.0'
+  },
+  async () => {
+    // Your AI/LLM operations here
+    const result = await generateResponse('What is AI?');
+
+    // 3. Submit for approval
+    const approval = await approve({
+      requestId: 'req_001',
+      inputData: { query: 'What is AI?' },
+      outputData: { response: result },
+      version: 'v1.0.0'
+    });
+
+    // 4. Submit metrics
+    if (approval.isAutoApproved) {
+      await submitMetric({
+        requestId: 'req_001',
+        metricId: 'auto_approval_rate',
+        value: 1.0,
+        metricType: 'rate'
+      });
+    }
+
+    return result;
+  }
+);
+```
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions. All functions and classes are fully typed for an excellent development experience.
+
+## License
+
+MIT
+
+## Links
+
+- [Homepage](https://coalex.ai)
+- [Documentation](https://docs.coalex.ai)
+- [GitHub](https://github.com/coalex-ai/coalex-ts)
+- [PyPI (Python version)](https://pypi.org/project/coalex/)

package/dist/approve.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Coalex approval functionality for human-in-the-loop workflows.
+ */
+export interface ApprovalRequestData {
+    requestId: string;
+    inputData?: Record<string, any>;
+    outputData?: Record<string, any>;
+    version?: string;
+    slaSeconds?: number;
+    agentId?: string;
+    urlParams?: Record<string, any>;
+    eval?: string | boolean;
+}
+export interface ApprovalResponseData {
+    taskId: string;
+    requestId: string;
+    status: string;
+    slaTimestamp: Date;
+    evalId?: string;
+    tunedOutputData?: Record<string, any>;
+}
+/**
+ * Request object for approval tasks.
+ */
+export declare class ApprovalRequest {
+    requestId: string;
+    inputData: Record<string, any>;
+    outputData: Record<string, any>;
+    version: string;
+    slaSeconds: number;
+    agentId?: string;
+    urlParams: Record<string, any>;
+    eval?: string | boolean;
+    constructor(data: ApprovalRequestData);
+}
+/**
+ * Response object for approval requests.
+ */
+export declare class ApprovalResponse {
+    taskId: string;
+    requestId: string;
+    status: string;
+    slaTimestamp: Date;
+    evalId?: string;
+    tunedOutputData?: Record<string, any>;
+    constructor(data: ApprovalResponseData);
+    /**
+     * Check if this request was auto-approved.
+     */
+    get isAutoApproved(): boolean;
+    /**
+     * Check if this request needs human review.
+     */
+    get needsHumanReview(): boolean;
+}
+export interface ApproveOptions {
+    requestId: string;
+    inputData?: Record<string, any>;
+    outputData?: Record<string, any>;
+    version?: string;
+    slaSeconds?: number;
+    agentId?: string;
+    urlParams?: Record<string, any>;
+    eval?: string | boolean;
+    endpoint?: string;
+}
+/**
+ * Submit an approval request for human-in-the-loop review.
+ *
+ * This function sends a request to the coalex-ai-creator service to create
+ * an approval task that will be handled by a human reviewer.
+ *
+ * @param options - Approval request options
+ * @returns Promise that resolves to ApprovalResponse
+ * @throws Error if required parameters are missing or the request fails
+ *
+ * @example
+ * ```typescript
+ * import { register, approve } from '@coalex/sdk';
+ *
+ * // Register coalex first
+ * register({ agentId: 'your-agent-id' });
+ *
+ * // Submit approval request
+ * const response = await approve({
+ *   requestId: 'req_12345',
+ *   inputData: { userQuery: 'What is the weather?' },
+ *   outputData: { response: "It's sunny today" },
+ *   version: 'v1.2.0'
+ * });
+ *
+ * console.log(`Approval task created: ${response.taskId}`);
+ * ```
+ */
+export declare function approve(options: ApproveOptions): Promise<ApprovalResponse>;

package/dist/approve.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Coalex approval functionality for human-in-the-loop workflows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalResponse = exports.ApprovalRequest = void 0;
+exports.approve = approve;
+const api_1 = require("@opentelemetry/api");
+const DEFAULT_CREATOR_ENDPOINT = 'https://creator.coalex.ai';
+/**
+ * Request object for approval tasks.
+ */
+class ApprovalRequest {
+    constructor(data) {
+        this.requestId = data.requestId;
+        this.inputData = data.inputData || {};
+        this.outputData = data.outputData || {};
+        this.version = data.version || '1.0.0';
+        this.slaSeconds = data.slaSeconds || 3600;
+        this.agentId = data.agentId;
+        this.urlParams = data.urlParams || {};
+        this.eval = data.eval;
+    }
+}
+exports.ApprovalRequest = ApprovalRequest;
+/**
+ * Response object for approval requests.
+ */
+class ApprovalResponse {
+    constructor(data) {
+        this.taskId = data.taskId;
+        this.requestId = data.requestId;
+        this.status = data.status;
+        this.slaTimestamp = data.slaTimestamp;
+        this.evalId = data.evalId;
+        this.tunedOutputData = data.tunedOutputData;
+    }
+    /**
+     * Check if this request was auto-approved.
+     */
+    get isAutoApproved() {
+        return this.status === 'auto_approved';
+    }
+    /**
+     * Check if this request needs human review.
+     */
+    get needsHumanReview() {
+        return this.status === 'pending';
+    }
+}
+exports.ApprovalResponse = ApprovalResponse;
+/**
+ * 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 an approval request for human-in-the-loop review.
+ *
+ * This function sends a request to the coalex-ai-creator service to create
+ * an approval task that will be handled by a human reviewer.
+ *
+ * @param options - Approval request options
+ * @returns Promise that resolves to ApprovalResponse
+ * @throws Error if required parameters are missing or the request fails
+ *
+ * @example
+ * ```typescript
+ * import { register, approve } from '@coalex/sdk';
+ *
+ * // Register coalex first
+ * register({ agentId: 'your-agent-id' });
+ *
+ * // Submit approval request
+ * const response = await approve({
+ *   requestId: 'req_12345',
+ *   inputData: { userQuery: 'What is the weather?' },
+ *   outputData: { response: "It's sunny today" },
+ *   version: 'v1.2.0'
+ * });
+ *
+ * console.log(`Approval task created: ${response.taskId}`);
+ * ```
+ */
+async function approve(options) {
+    const { requestId, inputData, outputData, version = '1.0.0', slaSeconds = 3600, urlParams, eval: evalOption, endpoint = DEFAULT_CREATOR_ENDPOINT } = options;
+    if (!requestId) {
+        throw new Error('requestId is required');
+    }
+    // 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 approval request
+    const approvalRequest = new ApprovalRequest({
+        requestId,
+        inputData,
+        outputData,
+        version,
+        slaSeconds,
+        agentId,
+        urlParams,
+        eval: evalOption
+    });
+    // Prepare request payload
+    const payload = {
+        request_id: approvalRequest.requestId,
+        input_data: approvalRequest.inputData,
+        output_data: approvalRequest.outputData,
+        version: approvalRequest.version,
+        sla_seconds: approvalRequest.slaSeconds,
+        agent_id: approvalRequest.agentId,
+        url_params: approvalRequest.urlParams,
+        eval: approvalRequest.eval
+    };
+    // Prepare headers for authentication
+    const headers = {
+        'Authorization': `Bearer ${agentId}`,
+        'Content-Type': 'application/json'
+    };
+    // Build URL
+    const url = `${endpoint}/approve`;
+    console.log(`Submitting approval request ${requestId} for 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();
+        // Convert sla_timestamp string to Date
+        const slaTimestamp = new Date(responseData.sla_timestamp);
+        const approvalResponse = new ApprovalResponse({
+            taskId: responseData.task_id,
+            requestId: responseData.request_id,
+            status: responseData.status,
+            slaTimestamp,
+            evalId: responseData.eval_id,
+            tunedOutputData: responseData.tuned_output_data
+        });
+        console.log(`Approval request ${requestId} submitted successfully. Task ID: ${approvalResponse.taskId}`);
+        return approvalResponse;
+    }
+    catch (error) {
+        console.error(`Failed to submit approval request ${requestId}:`, error);
+        throw error;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Coalex SDK for observability and monitoring.
+ *
+ * @packageDocumentation
+ */
+export { register, addRequestContext, coalexContext, coalexContextSync, RegisterOptions, CoalexContextOptions } from './otel/register';
+export { approve, ApprovalRequest, ApprovalResponse, ApprovalRequestData, ApprovalResponseData, ApproveOptions } from './approve';
+export { submitMetric, MetricRequest, MetricResponse, MetricRequestData, MetricResponseData, SubmitMetricOptions } from './metrics';
+export declare const VERSION = "0.4.1";

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Coalex SDK for observability and monitoring.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.MetricResponse = exports.MetricRequest = exports.submitMetric = exports.ApprovalResponse = exports.ApprovalRequest = exports.approve = exports.coalexContextSync = exports.coalexContext = exports.addRequestContext = exports.register = void 0;
+// OpenTelemetry registration and context
+var register_1 = require("./otel/register");
+Object.defineProperty(exports, "register", { enumerable: true, get: function () { return register_1.register; } });
+Object.defineProperty(exports, "addRequestContext", { enumerable: true, get: function () { return register_1.addRequestContext; } });
+Object.defineProperty(exports, "coalexContext", { enumerable: true, get: function () { return register_1.coalexContext; } });
+Object.defineProperty(exports, "coalexContextSync", { enumerable: true, get: function () { return register_1.coalexContextSync; } });
+// Approval functionality
+var approve_1 = require("./approve");
+Object.defineProperty(exports, "approve", { enumerable: true, get: function () { return approve_1.approve; } });
+Object.defineProperty(exports, "ApprovalRequest", { enumerable: true, get: function () { return approve_1.ApprovalRequest; } });
+Object.defineProperty(exports, "ApprovalResponse", { enumerable: true, get: function () { return approve_1.ApprovalResponse; } });
+// Metrics functionality
+var metrics_1 = require("./metrics");
+Object.defineProperty(exports, "submitMetric", { enumerable: true, get: function () { return metrics_1.submitMetric; } });
+Object.defineProperty(exports, "MetricRequest", { enumerable: true, get: function () { return metrics_1.MetricRequest; } });
+Object.defineProperty(exports, "MetricResponse", { enumerable: true, get: function () { return metrics_1.MetricResponse; } });
+// Version
+exports.VERSION = '0.4.1';

package/dist/metrics.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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

@@ -0,0 +1,192 @@
+"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

@@ -0,0 +1,98 @@
+/**
+ * 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

@@ -0,0 +1,200 @@
+"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;
+        }
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@coalex-ai/sdk",
+  "version": "0.4.1",
+  "description": "TypeScript SDK for Coalex.ai observability platform with OpenTelemetry integration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "keywords": [
+    "coalex",
+    "opentelemetry",
+    "tracing",
+    "observability",
+    "monitoring",
+    "metrics"
+  ],
+  "author": "Coalex.ai <support@coalex.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coalex-ai/coalex-ts"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^1.28.0",
+    "@opentelemetry/sdk-trace-node": "^1.28.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.55.0",
+    "@opentelemetry/resources": "^1.28.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.14",
+    "ts-jest": "^29.2.5"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}