@nexus-cortex/core 4.26.0

package/dist/adapters/FormatAdapter.interface.js

@@ -0,0 +1,89 @@
+/**
+ * FormatAdapter Interface
+ *
+ * Defines the contract for bidirectional tool format conversion between
+ * canonical internal format and provider-specific formats.
+ *
+ * Phase 1.5: Multi-Provider Architecture
+ * Based on: CORTEX_V4_PHASE_1.5_ARCHITECTURE.md
+ */
+/**
+ * Naming Convention Utilities
+ *
+ * Convert between snake_case and PascalCase.
+ */
+export class NamingConvention {
+    /**
+     * Convert string to snake_case
+     *
+     * @param str - Input string
+     * @returns snake_case version
+     *
+     * @example
+     * toSnakeCase('ReadFile') → 'read_file'
+     * toSnakeCase('readFile') → 'read_file'
+     * toSnakeCase('read_file') → 'read_file'
+     */
+    static toSnakeCase(str) {
+        return str
+            .replace(/([A-Z])/g, '_$1')
+            .toLowerCase()
+            .replace(/^_/, '');
+    }
+    /**
+     * Convert string to PascalCase
+     *
+     * @param str - Input string
+     * @returns PascalCase version
+     *
+     * @example
+     * toPascalCase('read_file') → 'ReadFile'
+     * toPascalCase('ReadFile') → 'ReadFile'
+     * toPascalCase('readFile') → 'ReadFile'
+     */
+    static toPascalCase(str) {
+        return str
+            .split('_')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join('');
+    }
+    /**
+     * Convert tool name based on convention
+     *
+     * @param name - Tool name
+     * @param convention - Target convention
+     * @returns Converted name
+     */
+    static convertToolName(name, convention) {
+        return convention === 'snake_case'
+            ? this.toSnakeCase(name)
+            : this.toPascalCase(name);
+    }
+    /**
+     * Convert all tool names in schema
+     *
+     * @param tools - Canonical tools
+     * @param convention - Target convention
+     * @returns Tools with converted names
+     */
+    static convertToolNames(tools, convention) {
+        return tools.map(tool => ({
+            ...tool,
+            name: this.convertToolName(tool.name, convention),
+            metadata: {
+                ...tool.metadata,
+                originalNaming: this.detectConvention(tool.name)
+            }
+        }));
+    }
+    /**
+     * Detect naming convention used
+     *
+     * @param str - String to analyze
+     * @returns Detected convention
+     */
+    static detectConvention(str) {
+        return str.includes('_') ? 'snake_case' : 'PascalCase';
+    }
+}
+//# sourceMappingURL=FormatAdapter.interface.js.map

package/dist/adapters/FormatAdapter.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormatAdapter.interface.js","sourceRoot":"","sources":["../../src/adapters/FormatAdapter.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+BH;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAC3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,WAAW,CAAC,GAAW;QAC5B,OAAO,GAAG;aACP,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC;aAC1B,WAAW,EAAE;aACb,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACvB,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,YAAY,CAAC,GAAW;QAC7B,OAAO,GAAG;aACP,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;aACzD,IAAI,CAAC,EAAE,CAAC,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CACpB,IAAY,EACZ,UAAuC;QAEvC,OAAO,UAAU,KAAK,YAAY;YAChC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;YACxB,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,gBAAgB,CACrB,KAAsB,EACtB,UAAuC;QAEvC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxB,GAAG,IAAI;YACP,IAAI,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;YACjD,QAAQ,EAAE;gBACR,GAAG,IAAI,CAAC,QAAQ;gBAChB,cAAc,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;aACjD;SACF,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAW;QACjC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;IACzD,CAAC;CACF"}

package/dist/adapters/GatewayTranslationLayer.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Gateway Translation Layer
+ *
+ * Orchestrates bidirectional message and tool format conversion between
+ * canonical internal format and provider-specific formats.
+ *
+ * Phase 1.5: Multi-Provider Architecture
+ * Based on: CORTEX_V4_PHASE_1.5_ARCHITECTURE.md
+ */
+import { CanonicalTool, CanonicalMessage } from '../adapters/FormatAdapter.interface.js';
+import { ModelConfig } from '../models/ModelConfig.interface.js';
+import { AdapterRegistry } from '../adapters/AdapterRegistry.js';
+import { ToolNamingHandler } from '../adapters/ToolNamingHandler.js';
+/**
+ * Request preparation result
+ */
+export interface PreparedRequest {
+    /** Provider-specific messages */
+    messages: unknown[];
+    /** Provider-specific tools (if applicable) */
+    tools?: unknown[];
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request parameters */
+    parameters: Record<string, unknown>;
+    /** System message (handled separately for some providers) */
+    systemMessage?: string;
+    /** Model ID to use */
+    modelId: string;
+    /** Previous response ID for stateful Responses API chaining (XAI, OpenAI) */
+    previousResponseId?: string;
+    /**
+     * Conversation/session identifier for cache-routing.
+     * Used as `x-grok-conv-id` header (Chat Completions / Messages API) and
+     * `prompt_cache_key` body field (Responses API).
+     */
+    conversationId?: string;
+}
+/**
+ * Cache performance metrics
+ */
+export interface CacheMetrics {
+    /** Tokens written to cache (cache creation) */
+    cacheCreationTokens: number;
+    /** Tokens read from cache (cache hits) */
+    cacheReadTokens: number;
+    /** Uncached input tokens */
+    uncachedInputTokens: number;
+    /** Cache hit rate (0.0 to 1.0) */
+    cacheHitRate: number;
+    /** Estimated cost savings ratio (0.0 to 1.0) */
+    costSavingsRatio: number;
+}
+/**
+ * Token usage with optional cache breakdown
+ */
+export interface TokenUsageMetrics {
+    /** Total input tokens (cached + uncached) */
+    inputTokens: number;
+    /** Generated output tokens */
+    outputTokens: number;
+    /** Total tokens (input + output) */
+    totalTokens: number;
+    /** Cache-specific metrics (optional - provider-dependent) */
+    cache?: CacheMetrics;
+    /**
+     * Provider-authoritative billed cost for THIS request, in xAI "ticks"
+     * (1 USD = 1e10 ticks). xAI returns `usage.cost_in_usd_ticks` on chat
+     * completions, Responses API, and agentic loops — the actual amount
+     * billed after caching discounts, inclusive of all token AND server-side
+     * tool/reasoning costs (the otherwise-opaque server-side spend). Absent
+     * for providers that don't report it.
+     */
+    costUsdTicks?: number;
+    /** `costUsdTicks` converted to dollars (costUsdTicks / 1e10). */
+    costUsd?: number;
+    /** Number of server-side tool invocations xAI billed for this request. */
+    serverSideToolsUsed?: number;
+}
+/**
+ * Response conversion result
+ */
+export interface ConvertedResponse {
+    /** Canonical messages */
+    messages: CanonicalMessage[];
+    /** Token usage information with cache metrics */
+    usage?: TokenUsageMetrics;
+    /** Stop reason */
+    stopReason?: string;
+    /** Raw provider response (for debugging) */
+    rawResponse?: unknown;
+}
+/**
+ * Session Context
+ *
+ * Required for timeline tracking in canonical messages
+ */
+export interface SessionContext {
+    /** Session ID */
+    sessionId: string;
+    /** Conversation ID (for branching) */
+    conversationId: string;
+    /** Current turn number */
+    turnNumber: number;
+}
+/**
+ * Gateway Translation Layer
+ *
+ * Central orchestrator for format conversion between canonical and provider formats.
+ */
+export declare class GatewayTranslationLayer {
+    private adapterRegistry;
+    private toolNamingHandler;
+    constructor(adapterRegistry?: AdapterRegistry, toolNamingHandler?: ToolNamingHandler);
+    /**
+     * Prepare request for provider API
+     *
+     * Converts canonical messages and tools to provider-specific format,
+     * adds headers, authentication, and parameters.
+     *
+     * @param messages - Canonical messages
+     * @param tools - Canonical tools (optional)
+     * @param modelConfig - Model configuration
+     * @param options - Additional options
+     * @returns Prepared request ready for API call
+     */
+    prepareRequest(messages: CanonicalMessage[], tools: CanonicalTool[] | undefined, modelConfig: ModelConfig, options?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        topK?: number;
+        stream?: boolean;
+        disableThinking?: boolean;
+        reasoningEffort?: 'none' | 'low' | 'medium' | 'high';
+        /**
+         * R28: byte-stable static system prompt. When set, used as the system
+         * field instead of scanning for role:'system' messages — so the prompt
+         * lives in the provider `system` field (cacheable prefix) rather than
+         * riding the moving latest-user-message slot.
+         */
+        staticSystemPrompt?: string;
+        /**
+         * R28b: session/conversation id → `x-grok-conv-id` header. xAI's
+         * prompt-cache prefix lives on a specific backend instance; consistent
+         * routing via this id is required for cache hits even when the prefix
+         * is byte-stable. Without it the header is never sent and every request
+         * may hit a cold instance.
+         */
+        conversationId?: string;
+    }): PreparedRequest;
+    /**
+     * Prepare tools with PTC support.
+     * Essential tools sent normally, standard tools get defer_loading: true,
+     * PTC system tools (code_execution, tool_search) appended.
+     *
+     * @param tools - Canonical tools
+     * @param modelConfig - Model configuration
+     * @returns Array of provider-formatted tools with PTC system tools
+     */
+    prepareToolsWithPTC(tools: CanonicalTool[], modelConfig: ModelConfig): unknown[];
+    /**
+     * Convert provider response to canonical format
+     *
+     * @param providerResponse - Raw provider response
+     * @param modelConfig - Model configuration
+     * @param sessionContext - Session context for timeline tracking
+     * @returns Converted canonical messages with metadata
+     */
+    convertResponse(providerResponse: unknown, modelConfig: ModelConfig, sessionContext: SessionContext): ConvertedResponse;
+    /**
+     * Validate request before sending
+     *
+     * @param messages - Canonical messages
+     * @param tools - Canonical tools
+     * @param modelConfig - Model configuration
+     * @returns Validation result
+     */
+    validateRequest(messages: CanonicalMessage[], tools: CanonicalTool[] | undefined, modelConfig: ModelConfig): {
+        valid: boolean;
+        errors?: string[];
+        warnings?: string[];
+    };
+    /**
+     * Extract system message from messages
+     */
+    private extractSystemMessage;
+    /**
+     * Prepare HTTP headers for provider API
+     */
+    private prepareHeaders;
+    /**
+     * Prepare request parameters based on model config
+     */
+    private prepareParameters;
+    /**
+     * Set nested parameter using dot notation path
+     */
+    private setNestedParam;
+    /**
+     * Extract messages from provider response
+     */
+    private extractMessagesFromResponse;
+    /**
+     * Extract token usage from provider response with cache metrics
+     */
+    private extractUsage;
+    /**
+     * Extract stop reason from provider response
+     */
+    private extractStopReason;
+    /**
+     * Estimate token count for messages and tools
+     *
+     * Simple estimation: ~4 characters per token
+     */
+    private estimateTokenCount;
+}
+/**
+ * Default singleton instance
+ */
+export declare const gatewayTranslationLayer: GatewayTranslationLayer;
+//# sourceMappingURL=GatewayTranslationLayer.d.ts.map

package/dist/adapters/GatewayTranslationLayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayTranslationLayer.d.ts","sourceRoot":"","sources":["../../src/adapters/GatewayTranslationLayer.ts"],"names":[],"mappings":"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"}