@coalex-ai/sdk 0.4.5 → 0.5.1

package/package.json

@@ -1,47 +1,59 @@
 {
   "name": "@coalex-ai/sdk",
-  "version": "0.4.5",
-  "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",
+  "version": "0.5.1",
+  "description": "Coalex TypeScript SDK for AI governance observability",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/carlosmlribeiro/coalex-ts.git"
+    "url": "git+https://github.com/Coalex-ai/coalex.git",
+    "directory": "packages/sdk-typescript"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./ext": {
+      "types": "./dist/ext/index.d.ts",
+      "import": "./dist/ext/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/ tests/",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-base": "^1.28.0",
     "@opentelemetry/sdk-trace-node": "^1.28.0",
+    "@opentelemetry/sdk-trace-base": "^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"
+    "typescript": "~5.7.0",
+    "vitest": "^2.0.0",
+    "eslint": "^9.0.0",
+    "@eslint/js": "^9.0.0",
+    "typescript-eslint": "^8.0.0"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ]
+  "peerDependencies": {
+    "@opentelemetry/instrumentation": ">=0.50.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/instrumentation": {
+      "optional": true
+    }
+  }
 }

package/LICENSE

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

@@ -1,263 +0,0 @@
-# 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

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

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