@backtest-kit/ollama 0.0.1 → 0.0.2

package/build/index.mjs

@@ -18,20 +18,69 @@ import { Ollama } from 'ollama';
 import { zodResponseFormat } from 'openai/helpers/zod';
 import { z } from 'zod';
 
+/**
+ * Enumeration of completion strategy types.
+ *
+ * Defines unique identifiers for different completion execution modes.
+ * Used internally for routing completion requests to appropriate handlers.
+ *
+ * @example
+ * ```typescript
+ * import { CompletionName } from '@backtest-kit/ollama';
+ *
+ * const completionType = CompletionName.RunnerCompletion;
+ * ```
+ */
 var CompletionName;
 (function (CompletionName) {
+    /** Standard completion mode (full response at once) */
     CompletionName["RunnerCompletion"] = "runner_completion";
+    /** Streaming completion mode (progressive response chunks) */
     CompletionName["RunnerStreamCompletion"] = "runner_stream_completion";
+    /** Outline completion mode (structured JSON with schema validation) */
     CompletionName["RunnerOutlineCompletion"] = "runner_outline_completion";
 })(CompletionName || (CompletionName = {}));
 var CompletionName$1 = CompletionName;
 
+/**
+ * Scoped context service for isolated execution contexts.
+ *
+ * Provides context isolation using async local storage through the di-scoped library.
+ * Each operation runs with its own context containing provider, model, and API key configuration.
+ * This enables multi-tenant scenarios where different requests use different AI providers or keys.
+ *
+ * Key features:
+ * - Scoped context isolation per execution
+ * - Support for single or multiple API keys (token rotation)
+ * - Thread-safe context propagation
+ * - Automatic cleanup after execution
+ *
+ * @example
+ * ```typescript
+ * import ContextService from "./services/base/ContextService";
+ *
+ * // Execute operation within scoped context
+ * const result = await ContextService.runInContext(async () => {
+ *   // Code here has access to the context
+ *   const model = contextService.context.model;
+ *   return await someAiOperation();
+ * }, {
+ *   inference: InferenceName.GPT5Inference,
+ *   model: "gpt-5o-mini",
+ *   apiKey: "sk-..."
+ * });
+ * ```
+ */
 const ContextService = scoped(class {
     constructor(context) {
         this.context = context;
     }
 });
 
+/**
+ * No-operation logger that silently discards all log messages.
+ * Used as default logger before a real logger is configured.
+ */
 const NOOP_LOGGER = {
     log() {
     },
@@ -42,43 +91,181 @@ const NOOP_LOGGER = {
     warn() {
     },
 };
+/**
+ * Centralized logging service for the Ollama package.
+ *
+ * Provides a unified interface for logging operations across the application.
+ * Uses a delegate pattern to forward log calls to a configured logger implementation.
+ * Defaults to a no-op logger if no logger is set.
+ *
+ * Key features:
+ * - Supports multiple log levels: log, debug, info, warn
+ * - Configurable logger backend via setLogger
+ * - Async logging support
+ * - Safe default (no-op) when unconfigured
+ *
+ * @example
+ * ```typescript
+ * import { LoggerService } from "./services/common/LoggerService";
+ * import { setLogger } from "./function/setup.function";
+ *
+ * // Configure custom logger
+ * setLogger({
+ *   log: async (topic, ...args) => console.log(topic, ...args),
+ *   debug: async (topic, ...args) => console.debug(topic, ...args),
+ *   info: async (topic, ...args) => console.info(topic, ...args),
+ *   warn: async (topic, ...args) => console.warn(topic, ...args),
+ * });
+ *
+ * const loggerService = inject<LoggerService>(TYPES.loggerService);
+ * await loggerService.info("Operation completed", { status: "success" });
+ * ```
+ */
 class LoggerService {
     constructor() {
+        /** Internal logger instance, defaults to NOOP_LOGGER */
         this._commonLogger = NOOP_LOGGER;
+        /**
+         * Logs a general message with optional arguments.
+         *
+         * @param topic - Message topic or category
+         * @param args - Additional arguments to log
+         */
         this.log = async (topic, ...args) => {
             await this._commonLogger.log(topic, ...args);
         };
+        /**
+         * Logs a debug message with optional arguments.
+         * Used for detailed diagnostic information.
+         *
+         * @param topic - Message topic or category
+         * @param args - Additional arguments to log
+         */
         this.debug = async (topic, ...args) => {
             await this._commonLogger.debug(topic, ...args);
         };
+        /**
+         * Logs an informational message with optional arguments.
+         * Used for general operational information.
+         *
+         * @param topic - Message topic or category
+         * @param args - Additional arguments to log
+         */
         this.info = async (topic, ...args) => {
             await this._commonLogger.info(topic, ...args);
         };
+        /**
+         * Logs a warning message with optional arguments.
+         * Used for potentially problematic situations.
+         *
+         * @param topic - Message topic or category
+         * @param args - Additional arguments to log
+         */
         this.warn = async (topic, ...args) => {
             await this._commonLogger.warn(topic, ...args);
         };
+        /**
+         * Sets the logger implementation to use for all logging operations.
+         *
+         * @param logger - Logger implementation conforming to ILogger interface
+         *
+         * @example
+         * ```typescript
+         * const logger = new LoggerService();
+         * logger.setLogger({
+         *   log: async (topic, ...args) => console.log(topic, ...args),
+         *   debug: async (topic, ...args) => console.debug(topic, ...args),
+         *   info: async (topic, ...args) => console.info(topic, ...args),
+         *   warn: async (topic, ...args) => console.warn(topic, ...args),
+         * });
+         * ```
+         */
         this.setLogger = (logger) => {
             this._commonLogger = logger;
         };
     }
 }
 
+/**
+ * Dependency injection activator for the Ollama package.
+ *
+ * Creates a scoped DI container using di-kit with the namespace "ollama".
+ * Provides functions for service registration, injection, initialization, and overriding.
+ *
+ * Exported functions:
+ * - provide: Register a service implementation in the container
+ * - inject: Retrieve a service instance from the container
+ * - init: Initialize the DI container (must be called before using services)
+ * - override: Replace an existing service registration with a new implementation
+ *
+ * @example
+ * ```typescript
+ * import { provide, inject, init } from "./core/di";
+ * import { TYPES } from "./core/types";
+ *
+ * // Register service
+ * provide(TYPES.loggerService, () => new LoggerService());
+ *
+ * // Initialize container
+ * init();
+ *
+ * // Inject service
+ * const logger = inject<LoggerService>(TYPES.loggerService);
+ * ```
+ */
 const { provide, inject, init, override } = createActivator("ollama");
 
+/**
+ * Common service type identifiers.
+ * Services used across the entire application.
+ */
 const commonServices$1 = {
+    /** Logger service for application-wide logging */
     loggerService: Symbol("loggerService"),
 };
+/**
+ * Base service type identifiers.
+ * Core foundational services.
+ */
 const baseServices$1 = {
+    /** Context service for scoped execution contexts */
     contextService: Symbol('contextService'),
 };
+/**
+ * Private service type identifiers.
+ * Internal services not exposed in public API.
+ */
 const privateServices$1 = {
+    /** Runner private service for AI provider operations */
     runnerPrivateService: Symbol('runnerPrivateService'),
+    /** Outline private service for structured completions */
     outlinePrivateService: Symbol('outlinePrivateService'),
 };
+/**
+ * Public service type identifiers.
+ * Services exposed in the public API.
+ */
 const publicServices$1 = {
+    /** Runner public service for context-managed AI operations */
     runnerPublicService: Symbol('runnerPublicService'),
+    /** Outline public service for simplified structured completions */
     outlinePublicService: Symbol('outlinePublicService'),
 };
+/**
+ * Service type identifier registry for dependency injection.
+ *
+ * Centralizes all Symbol-based type identifiers used for DI container registration.
+ * Organized by service layer: common, base, private, and public services.
+ *
+ * @example
+ * ```typescript
+ * import { inject } from "./di";
+ * import { TYPES } from "./types";
+ * import LoggerService from "../services/common/LoggerService";
+ *
+ * const logger = inject<LoggerService>(TYPES.loggerService);
+ * ```
+ */
 const TYPES = {
     ...commonServices$1,
     ...baseServices$1,
@@ -86,12 +273,44 @@ const TYPES = {
     ...publicServices$1,
 };
 
+/**
+ * Enumeration of supported JSON schema outlines.
+ *
+ * Defines unique identifiers for structured output schemas used with
+ * LLM providers. Outlines enforce JSON schema validation for critical
+ * data structures like trading signals.
+ *
+ * @example
+ * ```typescript
+ * import { OutlineName } from '@backtest-kit/ollama';
+ *
+ * const outlineName = OutlineName.SignalOutline;
+ * ```
+ */
 var OutlineName;
 (function (OutlineName) {
+    /** Trading signal JSON schema for position, TP/SL, and risk parameters */
     OutlineName["SignalOutline"] = "signal_outline";
 })(OutlineName || (OutlineName = {}));
 var OutlineName$1 = OutlineName;
 
+/**
+ * Lints and auto-fixes markdown content using markdownlint rules.
+ *
+ * Validates markdown syntax and applies automatic fixes for common issues
+ * like inconsistent list markers, trailing spaces, and heading styles.
+ * Returns the original content if no errors found or fixes cannot be applied.
+ *
+ * @param content - Raw markdown content to lint
+ * @returns Promise resolving to linted markdown content
+ *
+ * @example
+ * ```typescript
+ * const markdown = "# Title\n\n\n## Subtitle"; // Multiple blank lines
+ * const linted = await toLintMarkdown(markdown);
+ * // Returns: "# Title\n\n## Subtitle" (extra blank line removed)
+ * ```
+ */
 const toLintMarkdown = async (content) => {
     if (!content) {
         return "";
@@ -103,8 +322,28 @@ const toLintMarkdown = async (content) => {
     const value = applyFixes(content, errors);
     return value ? value : content;
 };
-globalThis.toLintMarkdown = toLintMarkdown;
 
+/**
+ * Converts markdown content to plain text with Telegram-compatible HTML formatting.
+ *
+ * Processes markdown through three stages:
+ * 1. Lints and fixes markdown using markdownlint
+ * 2. Renders markdown to HTML using markdown-it
+ * 3. Sanitizes HTML to Telegram-compatible subset
+ *
+ * Supported tags: b, i, a, code, pre, s, u, tg-spoiler, blockquote, br
+ * Transforms: headings removed, lists to bullets, multiple newlines collapsed
+ *
+ * @param content - Raw markdown content
+ * @returns Promise resolving to sanitized plain text with HTML formatting
+ *
+ * @example
+ * ```typescript
+ * const markdown = "# Title\n**Bold** and *italic*\n- Item 1\n- Item 2";
+ * const plain = await toPlainString(markdown);
+ * // Returns: "Bold and italic\n• Item 1\n• Item 2"
+ * ```
+ */
 const toPlainString = async (content) => {
     if (!content) {
         return "";
@@ -155,9 +394,58 @@ const toPlainString = async (content) => {
     return telegramHtml.replaceAll(/\n[\s\n]*\n/g, "\n").trim();
 };
 
+/**
+ * Private service for processing structured outline completions.
+ *
+ * Handles the core logic for executing outline-based AI completions with schema validation.
+ * Processes AI responses through the agent-swarm-kit json function to extract and validate
+ * structured trading signal data.
+ *
+ * Key features:
+ * - JSON schema validation using agent-swarm-kit
+ * - Trading signal extraction and transformation
+ * - Type conversion for numeric fields
+ * - Markdown formatting cleanup for notes
+ * - Error handling for validation failures
+ *
+ * @example
+ * ```typescript
+ * const outlinePrivate = inject<OutlinePrivateService>(TYPES.outlinePrivateService);
+ * const signal = await outlinePrivate.getCompletion([
+ *   { role: "user", content: "Analyze market" }
+ * ]);
+ * ```
+ */
 class OutlinePrivateService {
     constructor() {
+        /** Logger service for operation tracking */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes outline completion messages and extracts structured signal data.
+         *
+         * Sends messages to the AI provider, validates the response against the signal schema,
+         * and transforms the data into a structured format. Returns null if the AI decides
+         * to wait (no position).
+         *
+         * @param messages - Array of conversation messages for the AI
+         * @returns Promise resolving to structured signal data or null if position is "wait"
+         * @throws Error if validation fails or AI returns an error
+         *
+         * @example
+         * ```typescript
+         * const signal = await outlinePrivateService.getCompletion([
+         *   { role: "system", content: "Trading analyst role" },
+         *   { role: "user", content: "Market analysis data..." }
+         * ]);
+         *
+         * if (signal) {
+         *   console.log(`Position: ${signal.position}`);
+         *   console.log(`Entry: ${signal.priceOpen}`);
+         *   console.log(`SL: ${signal.priceStopLoss}`);
+         *   console.log(`TP: ${signal.priceTakeProfit}`);
+         * }
+         * ```
+         */
         this.getCompletion = async (messages) => {
             this.loggerService.log("outlinePrivateService getCompletion", {
                 messages,
@@ -182,40 +470,194 @@ class OutlinePrivateService {
     }
 }
 
+/**
+ * Private service managing AI inference provider registry and execution.
+ *
+ * Coordinates AI operations across multiple inference providers (OpenAI, Claude, Ollama, etc.).
+ * Maintains a registry of provider implementations and instantiates them on-demand.
+ * Uses memoization to cache provider instances for better performance.
+ *
+ * Key features:
+ * - Dynamic provider registration for multiple AI services
+ * - Lazy instantiation with memoization for performance
+ * - Context-aware provider selection based on inference type
+ * - Support for standard, streaming, and structured completions
+ * - Type-safe provider interface
+ *
+ * @example
+ * ```typescript
+ * // Provider registration (typically done at startup)
+ * const runnerPrivate = inject<RunnerPrivateService>(TYPES.runnerPrivateService);
+ * runnerPrivate.registerRunner(InferenceName.ClaudeInference, ClaudeProvider);
+ * runnerPrivate.registerRunner(InferenceName.GPT5Inference, GPT5Provider);
+ *
+ * // Provider usage (automatically selected based on context)
+ * const result = await runnerPrivate.getCompletion({
+ *   messages: [{ role: "user", content: "Analyze trade" }]
+ * });
+ * ```
+ */
 class RunnerPrivateService {
     constructor() {
+        /** Context service providing execution context (model, API key, provider) */
         this.contextService = inject(TYPES.contextService);
+        /** Logger service for operation tracking */
         this.loggerService = inject(TYPES.loggerService);
+        /** Registry storing provider class constructors by inference name */
         this._registry = new ToolRegistry("runner_registry");
+        /**
+         * Memoized provider instance getter.
+         * Creates and caches provider instances per inference type.
+         */
         this.getRunner = memoize(([inference]) => `${inference}`, (inference) => {
             const Runner = this._registry.get(inference);
             return new Runner(this.contextService, this.loggerService);
         });
+        /**
+         * Executes a standard AI completion using the provider specified in context.
+         *
+         * @param params - Completion parameters including messages and options
+         * @returns Promise resolving to AI response message
+         *
+         * @example
+         * ```typescript
+         * const result = await runnerPrivateService.getCompletion({
+         *   messages: [
+         *     { role: "system", content: "You are a trading assistant" },
+         *     { role: "user", content: "Analyze BTC market" }
+         *   ]
+         * });
+         * ```
+         */
         this.getCompletion = async (params) => {
             this.loggerService.log("runnerPrivateService getCompletion");
             const runner = this.getRunner(this.contextService.context.inference);
             return await runner.getCompletion(params);
         };
+        /**
+         * Executes a streaming AI completion using the provider specified in context.
+         *
+         * @param params - Completion parameters including messages and options
+         * @returns Promise resolving to accumulated AI response message
+         *
+         * @example
+         * ```typescript
+         * const result = await runnerPrivateService.getStreamCompletion({
+         *   messages: [{ role: "user", content: "Generate signal" }]
+         * });
+         * ```
+         */
         this.getStreamCompletion = async (params) => {
             this.loggerService.log("runnerPrivateService getStreamCompletion");
             const runner = this.getRunner(this.contextService.context.inference);
             return await runner.getStreamCompletion(params);
         };
+        /**
+         * Executes a structured outline completion using the provider specified in context.
+         *
+         * @param params - Outline completion parameters including messages and schema
+         * @returns Promise resolving to structured AI response
+         *
+         * @example
+         * ```typescript
+         * const signal = await runnerPrivateService.getOutlineCompletion({
+         *   messages: [{ role: "user", content: "Trading decision for ETH" }]
+         * });
+         * ```
+         */
         this.getOutlineCompletion = async (params) => {
             this.loggerService.log("runnerPrivateService getOutlineCompletion");
             const runner = this.getRunner(this.contextService.context.inference);
             return await runner.getOutlineCompletion(params);
         };
+        /**
+         * Registers a new AI provider implementation in the registry.
+         *
+         * @param name - Inference provider identifier
+         * @param runner - Provider class constructor
+         *
+         * @example
+         * ```typescript
+         * runnerPrivateService.registerRunner(
+         *   InferenceName.ClaudeInference,
+         *   ClaudeProvider
+         * );
+         * ```
+         */
         this.registerRunner = (name, runner) => {
             this._registry = this._registry.register(name, runner);
         };
     }
 }
 
+/**
+ * Public-facing service for structured AI outline completions.
+ *
+ * Provides a simplified interface for executing structured AI completions with schema validation.
+ * Handles context creation and isolation for outline-based operations.
+ * Used for extracting structured data from AI responses (e.g., trading signals).
+ *
+ * Key features:
+ * - Simplified API with automatic context management
+ * - JSON schema validation for structured outputs
+ * - Support for multiple AI providers
+ * - Optional API key parameter with fallback
+ * - Logging integration
+ *
+ * @example
+ * ```typescript
+ * import { engine } from "./lib";
+ * import { InferenceName } from "./enum/InferenceName";
+ *
+ * const signal = await engine.outlinePublicService.getCompletion(
+ *   [{ role: "user", content: "Analyze BTC/USDT and decide position" }],
+ *   InferenceName.ClaudeInference,
+ *   "claude-3-5-sonnet-20240620",
+ *   "sk-ant-..."
+ * );
+ *
+ * // Returns structured signal:
+ * // {
+ * //   position: "long",
+ * //   priceOpen: 50000,
+ * //   priceStopLoss: 48000,
+ * //   priceTakeProfit: 52000,
+ * //   minuteEstimatedTime: 120,
+ * //   note: "Strong bullish momentum..."
+ * // }
+ * ```
+ */
 class OutlinePublicService {
     constructor() {
+        /** Logger service for operation tracking */
         this.loggerService = inject(TYPES.loggerService);
+        /** Private service handling outline completion logic */
         this.outlinePrivateService = inject(TYPES.outlinePrivateService);
+        /**
+         * Executes a structured outline completion with schema validation.
+         *
+         * Creates an isolated execution context and processes messages through the AI provider
+         * to generate a structured response conforming to a predefined schema.
+         *
+         * @param messages - Array of conversation messages for the AI
+         * @param inference - AI provider identifier
+         * @param model - Model name/identifier
+         * @param apiKey - Optional API key(s), required for most providers
+         * @returns Promise resolving to structured signal data or null if position is "wait"
+         *
+         * @example
+         * ```typescript
+         * const result = await outlinePublicService.getCompletion(
+         *   [
+         *     { role: "system", content: "You are a trading analyst" },
+         *     { role: "user", content: "Analyze current BTC market" }
+         *   ],
+         *   InferenceName.DeepseekInference,
+         *   "deepseek-chat",
+         *   "sk-..."
+         * );
+         * ```
+         */
         this.getCompletion = async (messages, inference, model, apiKey) => {
             this.loggerService.log("outlinePublicService getCompletion", {
                 messages,
@@ -234,22 +676,134 @@ class OutlinePublicService {
     }
 }
 
+/**
+ * Public-facing service for AI inference operations with context management.
+ *
+ * Provides context-scoped access to AI completion operations.
+ * Acts as a facade that wraps RunnerPrivateService methods with context isolation.
+ * Each operation runs within a dedicated execution context to ensure proper API key
+ * and model configuration isolation.
+ *
+ * Key features:
+ * - Context-isolated execution for multi-tenant scenarios
+ * - Support for standard, streaming, and structured (outline) completions
+ * - Automatic context propagation to private service layer
+ * - Logging integration for operation tracking
+ *
+ * @example
+ * ```typescript
+ * import { engine } from "./lib";
+ * import { InferenceName } from "./enum/InferenceName";
+ *
+ * const context = {
+ *   inference: InferenceName.ClaudeInference,
+ *   model: "claude-3-5-sonnet-20240620",
+ *   apiKey: "sk-ant-..."
+ * };
+ *
+ * // Standard completion
+ * const result = await engine.runnerPublicService.getCompletion({
+ *   messages: [{ role: "user", content: "Analyze this trade..." }]
+ * }, context);
+ *
+ * // Streaming completion
+ * const stream = await engine.runnerPublicService.getStreamCompletion({
+ *   messages: [{ role: "user", content: "Generate signal..." }]
+ * }, context);
+ *
+ * // Structured outline completion
+ * const outline = await engine.runnerPublicService.getOutlineCompletion({
+ *   messages: [{ role: "user", content: "Trading decision..." }]
+ * }, context);
+ * ```
+ */
 class RunnerPublicService {
     constructor() {
+        /** Private service handling AI provider operations */
         this.runnerPrivateService = inject(TYPES.runnerPrivateService);
+        /** Logger service for operation tracking */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Executes a standard AI completion within the specified context.
+         *
+         * @param params - Completion parameters including messages and options
+         * @param context - Execution context with inference provider, model, and API key
+         * @returns Promise resolving to AI response message
+         *
+         * @example
+         * ```typescript
+         * const result = await runnerPublicService.getCompletion({
+         *   messages: [
+         *     { role: "system", content: "You are a trading analyst" },
+         *     { role: "user", content: "Analyze BTC/USDT" }
+         *   ]
+         * }, {
+         *   inference: InferenceName.ClaudeInference,
+         *   model: "claude-3-5-sonnet-20240620",
+         *   apiKey: "sk-ant-..."
+         * });
+         * ```
+         */
         this.getCompletion = async (params, context) => {
             this.loggerService.log("runnerPublicService getCompletion");
             return await ContextService.runInContext(async () => {
                 return await this.runnerPrivateService.getCompletion(params);
             }, context);
         };
+        /**
+         * Executes a streaming AI completion within the specified context.
+         *
+         * Similar to getCompletion but enables streaming mode where supported by the provider.
+         * The response is accumulated and returned as a complete message once streaming finishes.
+         *
+         * @param params - Completion parameters including messages and options
+         * @param context - Execution context with inference provider, model, and API key
+         * @returns Promise resolving to accumulated AI response message
+         *
+         * @example
+         * ```typescript
+         * const result = await runnerPublicService.getStreamCompletion({
+         *   messages: [
+         *     { role: "user", content: "Generate trading signal for ETH/USDT" }
+         *   ]
+         * }, {
+         *   inference: InferenceName.GPT5Inference,
+         *   model: "gpt-5o-mini",
+         *   apiKey: "sk-..."
+         * });
+         * ```
+         */
         this.getStreamCompletion = async (params, context) => {
             this.loggerService.log("runnerPublicService getStreamCompletion");
             return await ContextService.runInContext(async () => {
                 return await this.runnerPrivateService.getStreamCompletion(params);
             }, context);
         };
+        /**
+         * Executes a structured outline completion within the specified context.
+         *
+         * Uses structured output (JSON schema validation) to ensure the AI response
+         * conforms to a predefined format. Ideal for extracting structured data
+         * from AI responses (e.g., trading signals with specific fields).
+         *
+         * @param params - Outline completion parameters including messages and schema
+         * @param context - Execution context with inference provider, model, and API key
+         * @returns Promise resolving to structured AI response
+         *
+         * @example
+         * ```typescript
+         * const signal = await runnerPublicService.getOutlineCompletion({
+         *   messages: [
+         *     { role: "user", content: "Decide position for BTC/USDT" }
+         *   ]
+         * }, {
+         *   inference: InferenceName.DeepseekInference,
+         *   model: "deepseek-chat",
+         *   apiKey: "sk-..."
+         * });
+         * // Returns: { position: "long", price_open: 50000, ... }
+         * ```
+         */
         this.getOutlineCompletion = async (params, context) => {
             this.loggerService.log("runnerPublicService getOutlineCompletion");
             return await ContextService.runInContext(async () => {
@@ -259,36 +813,116 @@ class RunnerPublicService {
     }
 }
 
+/**
+ * Service registration module for dependency injection.
+ *
+ * Registers all service implementations in the DI container during application startup.
+ * Services are organized by layer: common, base, private, and public services.
+ * Each service is registered with a factory function that creates new instances.
+ *
+ * Registration order:
+ * 1. Common services (LoggerService)
+ * 2. Base services (ContextService)
+ * 3. Private services (RunnerPrivateService, OutlinePrivateService)
+ * 4. Public services (RunnerPublicService, OutlinePublicService)
+ *
+ * This file is imported by lib/index.ts to ensure services are registered
+ * before the DI container is initialized.
+ */
+/**
+ * Register common services.
+ */
 {
     provide(TYPES.loggerService, () => new LoggerService());
 }
+/**
+ * Register base services.
+ */
 {
     provide(TYPES.contextService, () => new ContextService());
 }
+/**
+ * Register private services.
+ */
 {
     provide(TYPES.runnerPrivateService, () => new RunnerPrivateService());
     provide(TYPES.outlinePrivateService, () => new OutlinePrivateService());
 }
+/**
+ * Register public services.
+ */
 {
     provide(TYPES.runnerPublicService, () => new RunnerPublicService());
     provide(TYPES.outlinePublicService, () => new OutlinePublicService());
 }
 
+/**
+ * Enumeration of supported LLM inference providers.
+ *
+ * Defines unique identifiers for each LLM provider supported by the library.
+ * Used internally for dependency injection and provider resolution.
+ *
+ * @example
+ * ```typescript
+ * import { InferenceName } from '@backtest-kit/ollama';
+ *
+ * const providerName = InferenceName.GPT5Inference;
+ * ```
+ */
 var InferenceName;
 (function (InferenceName) {
+    /** Ollama provider for local/cloud LLM inference */
     InferenceName["OllamaInference"] = "ollama_inference";
+    /** Grok provider by X.AI (api.x.ai) */
     InferenceName["GrokInference"] = "grok_inference";
+    /** Hugging Face Inference API provider */
     InferenceName["HfInference"] = "hf_inference";
+    /** Claude provider by Anthropic (api.anthropic.com) */
     InferenceName["ClaudeInference"] = "claude_inference";
+    /** OpenAI GPT provider (api.openai.com) */
     InferenceName["GPT5Inference"] = "gpt5_inference";
+    /** Z.ai GPT Provider (api.z.ai/api/paas/v4) */
+    InferenceName["GLM4Inference"] = "glm4_inference";
+    /** DeepSeek provider (api.deepseek.com) */
     InferenceName["DeepseekInference"] = "deepseek_inference";
+    /** Mistral AI provider (api.mistral.ai) */
     InferenceName["MistralInference"] = "mistral_inference";
+    /** Perplexity AI provider (api.perplexity.ai) */
     InferenceName["PerplexityInference"] = "perplexity_inference";
+    /** Cohere provider (api.cohere.ai) */
     InferenceName["CohereInference"] = "cohere_inference";
+    /** Alibaba Cloud provider (dashscope-intl.aliyuncs.com) */
     InferenceName["AlibabaInference"] = "alibaba_inference";
 })(InferenceName || (InferenceName = {}));
 var InferenceName$1 = InferenceName;
 
+/**
+ * Creates and caches an OpenAI-compatible client for Grok (xAI) API.
+ *
+ * Uses OpenAI SDK with Grok's API endpoint.
+ * The client instance is cached using singleshot memoization for performance.
+ * Token rotation is not supported - throws error if array of keys is provided.
+ *
+ * Key features:
+ * - OpenAI SDK compatibility layer
+ * - Single API key support only
+ * - Instance caching with singleshot
+ * - Automatic cache clearing on error
+ *
+ * @returns OpenAI client configured for Grok API
+ * @throws Error if API key array is provided (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { getGrok } from "./config/grok";
+ *
+ * const client = getGrok();
+ * const completion = await client.chat.completions.create({
+ *   model: "grok-beta",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ */
 const getGrok = singleshot(() => {
     const apiKey = lib.contextService.context.apiKey;
     if (Array.isArray(apiKey)) {
@@ -301,8 +935,54 @@ const getGrok = singleshot(() => {
     });
 });
 
-const CC_ENABLE_DEBUG = "CC_ENABLE_DEBUG" in process.env ? !!parseInt(process.env.CC_ENABLE_DEBUG) : false;
+/**
+ * Global configuration parameters for the Ollama package.
+ *
+ * Provides runtime configuration via environment variables with sensible defaults.
+ * All configuration values are immutable once initialized.
+ *
+ * Available configurations:
+ * - CC_ENABLE_DEBUG: Enable detailed debug logging
+ * - CC_ENABLE_THINKING: Enable AI extended reasoning mode
+ *
+ * @example
+ * ```typescript
+ * import { GLOBAL_CONFIG } from "./config/params";
+ *
+ * if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
+ *   console.log("Debug mode enabled");
+ * }
+ *
+ * if (GLOBAL_CONFIG.CC_ENABLE_THINKING) {
+ *   // AI will provide reasoning before responses
+ * }
+ * ```
+ */
+/**
+ * Mutable global configuration object.
+ * Values are read from environment variables at initialization.
+ */
+const GLOBAL_CONFIG = {
+    /**
+     * Enable debug mode for detailed logging.
+     * When enabled, additional debug information will be logged.
+     * Can be set via CC_ENABLE_DEBUG environment variable.
+     * Default: false
+     */
+    CC_ENABLE_DEBUG: "CC_ENABLE_DEBUG" in process.env ? !!parseInt(process.env.CC_ENABLE_DEBUG) : false,
+    /**
+     * Enable thinking mode for AI responses.
+     * When enabled, the AI will provide extended reasoning before answering.
+     * Can be set via CC_ENABLE_THINKING environment variable.
+     * Default: false
+     */
+    CC_ENABLE_THINKING: "CC_ENABLE_THINKING" in process.env ? !!parseInt(process.env.CC_ENABLE_THINKING) : false,
+};
 
+/**
+ * Custom ChatXAI implementation with simplified token counting.
+ * Estimates tokens as content.length / 4 for compatibility.
+ */
 class CustomChat extends ChatXAI {
     async getNumTokens(content) {
         if (typeof content !== "string") {
@@ -311,16 +991,54 @@ class CustomChat extends ChatXAI {
         return Math.ceil(content.length / 4);
     }
 }
+/**
+ * Creates configured ChatXAI instance for Grok streaming.
+ */
 const getChat$1 = (model, apiKey) => new CustomChat({
     apiKey,
     model,
     streaming: true,
 });
-let GrokProvider$1 = class GrokProvider {
+/**
+ * Provider for xAI Grok models via LangChain ChatXAI.
+ *
+ * Uses LangChain's ChatXAI integration for xAI Grok models.
+ * Provides true token-by-token streaming via LangChain callbacks and OpenAI SDK for standard requests.
+ *
+ * Key features:
+ * - LangChain ChatXAI for true streaming
+ * - OpenAI SDK via getGrok() for standard completion
+ * - Direct xAI API access for outline completion
+ * - Tool calling via bindTools (streaming) or tools parameter (standard)
+ * - Real-time token emission via stream callbacks
+ * - No token rotation support (single API key only)
+ *
+ * @example
+ * ```typescript
+ * const provider = new GrokProvider(contextService, logger);
+ * const response = await provider.getStreamCompletion({
+ *   agentName: "grok",
+ *   messages: [{ role: "user", content: "Latest AI news?" }],
+ *   mode: "direct",
+ *   tools: [searchTool],
+ *   clientId: "client-888"
+ * });
+ * ```
+ */
+class GrokProvider {
+    /**
+     * Creates a new GrokProvider instance.
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs standard completion request via OpenAI SDK.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to assistant's response
+     */
     async getCompletion(params) {
         const grok = getGrok();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -364,11 +1082,19 @@ let GrokProvider$1 = class GrokProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_grok_provider.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs true streaming completion via LangChain ChatXAI.
+     * Emits tokens in real-time as they are generated.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to complete response after streaming
+     * @throws Error if token rotation attempted
+     */
     async getStreamCompletion(params) {
         if (Array.isArray(this.contextService.context.apiKey)) {
             throw new Error("Grok provider does not support token rotation");
@@ -463,11 +1189,19 @@ let GrokProvider$1 = class GrokProvider {
             tool_calls: formattedToolCalls,
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_grok_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs structured output completion via direct xAI API.
+     * Uses response_format parameter for schema enforcement.
+     *
+     * @param params - Outline completion parameters
+     * @returns Promise resolving to validated JSON string
+     * @throws Error if model returns refusal or token rotation attempted
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         this.logger.log("grokProvider getOutlineCompletion", {
@@ -510,14 +1244,21 @@ let GrokProvider$1 = class GrokProvider {
             content: json,
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_grok_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
-};
+}
 
+/**
+ * Maximum number of retry attempts for outline completion.
+ */
 const MAX_ATTEMPTS$5 = 5;
+/**
+ * Custom ChatOpenAI implementation for HuggingFace with simplified token counting.
+ * Routes requests to HuggingFace Router endpoint.
+ */
 class HuggingFaceChat extends ChatOpenAI {
     async getNumTokens(content) {
         if (typeof content !== "string") {
@@ -526,6 +1267,9 @@ class HuggingFaceChat extends ChatOpenAI {
         return Math.ceil(content.length / 4);
     }
 }
+/**
+ * Creates configured HuggingFaceChat instance for streaming.
+ */
 const getChat = (model, apiKey) => new HuggingFaceChat({
     configuration: {
         baseURL: "https://router.huggingface.co/v1",
@@ -534,12 +1278,52 @@ const getChat = (model, apiKey) => new HuggingFaceChat({
     model,
     streaming: true,
 });
+/**
+ * Creates HuggingFace InferenceClient for standard completion.
+ */
 const getInference = (apiKey) => new InferenceClient(apiKey);
+/**
+ * Provider for HuggingFace models via HuggingFace Router API.
+ *
+ * Implements HuggingFace API access using both InferenceClient (standard completion)
+ * and LangChain ChatOpenAI (streaming). Supports thinking mode via reasoning_content.
+ * Does NOT support token rotation (single API key only).
+ *
+ * Key features:
+ * - HuggingFace InferenceClient for standard completion
+ * - LangChain ChatOpenAI for true streaming
+ * - Tool calling support with proper message conversion
+ * - Reasoning/thinking content capture (_thinking field)
+ * - Direct API access for outline completion
+ * - No token rotation support
+ *
+ * @example
+ * ```typescript
+ * const provider = new HfProvider(contextService, logger);
+ * const response = await provider.getStreamCompletion({
+ *   agentName: "hf-assistant",
+ *   messages: [{ role: "user", content: "Explain attention mechanism" }],
+ *   mode: "direct",
+ *   tools: [codeTool],
+ *   clientId: "client-777"
+ * });
+ * ```
+ */
 class HfProvider {
+    /**
+     * Creates a new HfProvider instance.
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs standard completion using HuggingFace InferenceClient.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to assistant's response
+     * @throws Error if token rotation attempted
+     */
     async getCompletion(params) {
         if (Array.isArray(this.contextService.context.apiKey)) {
             throw new Error("Hf provider does not support token rotation");
@@ -614,7 +1398,7 @@ class HfProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_hf_provider.txt", JSON.stringify({
                 params,
                 answer: result,
@@ -622,6 +1406,14 @@ class HfProvider {
         }
         return result;
     }
+    /**
+     * Performs true streaming completion using LangChain ChatOpenAI.
+     * Emits tokens in real-time via callbacks.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to complete response after streaming
+     * @throws Error if token rotation attempted
+     */
     async getStreamCompletion(params) {
         if (Array.isArray(this.contextService.context.apiKey)) {
             throw new Error("Hf provider does not support token rotation");
@@ -709,7 +1501,7 @@ class HfProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_hf_provider_stream.txt", JSON.stringify({
                 params,
                 answer: result,
@@ -717,6 +1509,14 @@ class HfProvider {
         }
         return result;
     }
+    /**
+     * Performs structured output completion using tool calling with extended retry logic.
+     * Captures reasoning_content as _thinking field in response.
+     *
+     * @param params - Outline completion parameters
+     * @returns Promise resolving to validated JSON string with thinking
+     * @throws Error if model fails after 5 attempts or token rotation attempted
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         this.logger.log("hfProvider getOutlineCompletion", {
@@ -822,7 +1622,7 @@ class HfProvider {
                         content: JSON.stringify(validation.data),
                     };
                     // Debug logging
-                    if (CC_ENABLE_DEBUG) {
+                    if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
                         await fs.appendFile("./debug_hf_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
                     }
                     return result;
@@ -835,9 +1635,25 @@ class HfProvider {
     }
 }
 
+/**
+ * Wrapper class for Ollama client with token rotation support.
+ *
+ * Implements round-robin API key rotation for high-volume Ollama usage.
+ * Each request automatically rotates through the provided API keys to
+ * distribute load and avoid rate limiting.
+ *
+ * Key features:
+ * - Round-robin token rotation using RoundRobin from agent-swarm-kit
+ * - Streaming and non-streaming support
+ * - Type-safe method overloads
+ * - Automatic Ollama client creation per token
+ *
+ * @throws Error if no API keys are provided in context
+ */
 class OllamaWrapper {
     constructor(_config) {
         this._config = _config;
+        /** Round-robin chat function factory */
         this._chatFn = RoundRobin.create(lib.contextService.context.apiKey, (token) => {
             const ollama = new Ollama({
                 ...this._config,
@@ -858,14 +1674,86 @@ class OllamaWrapper {
             throw new Error("OllamaRotate required apiKey[] to process token rotation");
         }
     }
+    /**
+     * Executes a chat request with automatic token rotation.
+     *
+     * @param request - Chat request configuration
+     * @returns Chat response or async iterable (for streaming)
+     */
     async chat(request) {
         return await this._chatFn(request);
     }
 }
+/**
+ * Creates and caches an Ollama wrapper with token rotation enabled.
+ *
+ * Requires an array of API keys in the execution context.
+ * The wrapper automatically rotates through keys using round-robin strategy.
+ *
+ * @returns OllamaWrapper instance with token rotation
+ *
+ * @example
+ * ```typescript
+ * import { getOllamaRotate } from "./config/ollama.rotate";
+ *
+ * // Context must have array of API keys
+ * const client = getOllamaRotate();
+ * const response = await client.chat({
+ *   model: "llama2",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * // Next request will use a different API key
+ * ```
+ */
 const getOllamaRotate = singleshot(() => new OllamaWrapper({
     host: "https://ollama.com",
 }));
 
+/**
+ * Creates and caches an Ollama client with flexible configuration.
+ *
+ * Supports three modes of operation:
+ * 1. Token rotation mode: Array of API keys enables automatic rotation
+ * 2. Cloud mode: Single API key connects to ollama.com
+ * 3. Local mode: No API key connects to local Ollama instance
+ *
+ * The client instance is cached using singleshot memoization for performance.
+ * Automatically selects the appropriate client based on API key configuration.
+ *
+ * Key features:
+ * - Token rotation support for high-volume usage
+ * - Cloud and local Ollama support
+ * - Instance caching with singleshot
+ * - Automatic mode detection
+ *
+ * @returns Ollama client or OllamaWrapper (for token rotation)
+ *
+ * @example
+ * ```typescript
+ * import { getOllama } from "./config/ollama";
+ *
+ * // Local mode (no API key)
+ * const localClient = getOllama();
+ * const response = await localClient.chat({
+ *   model: "llama2",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ *
+ * // Cloud mode (single API key)
+ * const cloudClient = getOllama();
+ * const response = await cloudClient.chat({
+ *   model: "llama2",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ *
+ * // Token rotation mode (array of API keys)
+ * const rotateClient = getOllama();
+ * const response = await rotateClient.chat({
+ *   model: "llama2",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ */
 const getOllama = singleshot(() => {
     const apiKey = lib.contextService.context.apiKey;
     if (Array.isArray(apiKey)) {
@@ -882,12 +1770,98 @@ const getOllama = singleshot(() => {
     });
 });
 
+/**
+ * Maximum number of retry attempts for outline completion when model fails to use tools correctly.
+ */
 const MAX_ATTEMPTS$4 = 3;
+/**
+ * Provider for Ollama LLM completions.
+ *
+ * Supports local and remote Ollama models with full tool calling capabilities.
+ * Provides both standard and streaming completion modes, as well as structured
+ * output through the outline completion method.
+ *
+ * Key features:
+ * - Native Ollama protocol support
+ * - Real-time streaming with token-by-token delivery
+ * - Tool calling with automatic retry logic
+ * - JSON schema validation for structured outputs
+ * - Optional thinking mode support (via CC_ENABLE_THINKING)
+ * - Debug logging when CC_ENABLE_DEBUG is enabled
+ *
+ * @example
+ * ```typescript
+ * const provider = new OllamaProvider(contextService, logger);
+ *
+ * // Standard completion
+ * const response = await provider.getCompletion({
+ *   agentName: "assistant",
+ *   messages: [{ role: "user", content: "Hello!" }],
+ *   mode: "direct",
+ *   tools: [],
+ *   clientId: "client-123"
+ * });
+ *
+ * // Streaming completion
+ * const streamResponse = await provider.getStreamCompletion({
+ *   agentName: "assistant",
+ *   messages: [{ role: "user", content: "Explain AI" }],
+ *   mode: "direct",
+ *   tools: [],
+ *   clientId: "client-123"
+ * });
+ *
+ * // Structured output with schema enforcement
+ * const outlineResponse = await provider.getOutlineCompletion({
+ *   messages: [{ role: "user", content: "Analyze sentiment" }],
+ *   format: {
+ *     type: "object",
+ *     properties: {
+ *       sentiment: { type: "string" },
+ *       confidence: { type: "number" }
+ *     }
+ *   }
+ * });
+ * ```
+ */
 class OllamaProvider {
+    /**
+     * Creates a new OllamaProvider instance.
+     *
+     * @param contextService - Context service managing model configuration and API settings
+     * @param logger - Logger instance for tracking provider operations
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs a standard (non-streaming) completion request to Ollama.
+     *
+     * Sends messages and tools to the Ollama model and returns the complete response.
+     * Supports tool calling with automatic ID generation for tool calls.
+     *
+     * @param params - Completion parameters including messages, tools, and agent configuration
+     * @param params.agentName - Name of the agent making the request
+     * @param params.messages - Conversation history with roles and content
+     * @param params.mode - Completion mode (e.g., "direct", "delegated")
+     * @param params.tools - Available tools for the model to call
+     * @param params.clientId - Client identifier for tracking requests
+     * @returns Promise resolving to the assistant's response message with optional tool calls
+     *
+     * @example
+     * ```typescript
+     * const response = await provider.getCompletion({
+     *   agentName: "assistant",
+     *   messages: [
+     *     { role: "user", content: "What's the weather in Tokyo?" }
+     *   ],
+     *   mode: "direct",
+     *   tools: [weatherTool],
+     *   clientId: "client-123"
+     * });
+     * ```
+     */
     async getCompletion(params) {
         const { agentName, messages: rawMessages, mode, tools, clientId } = params;
         const ollama = getOllama();
@@ -908,6 +1882,7 @@ class OllamaProvider {
                 })),
             })),
             tools,
+            think: GLOBAL_CONFIG.CC_ENABLE_THINKING,
         });
         const message = response.message;
         const result = {
@@ -922,11 +1897,40 @@ class OllamaProvider {
             role: response.message.role,
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_ollama_provider.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs a streaming completion request to Ollama.
+     *
+     * Sends messages and tools to the Ollama model and streams the response token by token.
+     * Emits "llm-new-token" events for each token and "llm-completion" when finished.
+     * Accumulates tool calls and content chunks from the stream.
+     *
+     * @param params - Completion parameters including messages, tools, and agent configuration
+     * @param params.agentName - Name of the agent making the request
+     * @param params.messages - Conversation history with roles and content
+     * @param params.mode - Completion mode (e.g., "direct", "delegated")
+     * @param params.tools - Available tools for the model to call
+     * @param params.clientId - Client identifier for event emission
+     * @returns Promise resolving to the complete assistant's response after streaming finishes
+     *
+     * @example
+     * ```typescript
+     * const response = await provider.getStreamCompletion({
+     *   agentName: "assistant",
+     *   messages: [
+     *     { role: "user", content: "Explain quantum computing" }
+     *   ],
+     *   mode: "direct",
+     *   tools: [],
+     *   clientId: "client-123"
+     * });
+     * // Client receives "llm-new-token" events during generation
+     * ```
+     */
     async getStreamCompletion(params) {
         const { agentName, messages: rawMessages, mode, tools, clientId } = params;
         const ollama = getOllama();
@@ -951,6 +1955,7 @@ class OllamaProvider {
             messages,
             tools,
             stream: true,
+            think: GLOBAL_CONFIG.CC_ENABLE_THINKING,
         });
         for await (const chunk of stream) {
             if (chunk.message.tool_calls) {
@@ -982,11 +1987,45 @@ class OllamaProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_ollama_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs structured output completion using JSON schema enforcement via tool calling.
+     *
+     * Forces the model to use a specific tool ("provide_answer") to ensure response
+     * conforms to the provided JSON schema. Implements retry logic with up to MAX_ATTEMPTS
+     * attempts if the model fails to use the tool correctly or returns invalid JSON.
+     *
+     * Uses jsonrepair to fix malformed JSON and validates the output against the schema.
+     * Adds context information to the returned data structure.
+     *
+     * @param params - Outline completion parameters
+     * @param params.messages - Conversation history for context
+     * @param params.format - JSON schema or response format definition
+     * @returns Promise resolving to validated JSON string conforming to the schema
+     * @throws Error if model fails to use tool after MAX_ATTEMPTS attempts
+     *
+     * @example
+     * ```typescript
+     * const response = await provider.getOutlineCompletion({
+     *   messages: [
+     *     { role: "user", content: "Analyze: 'Great product!'" }
+     *   ],
+     *   format: {
+     *     type: "object",
+     *     properties: {
+     *       sentiment: { type: "string", enum: ["positive", "negative", "neutral"] },
+     *       confidence: { type: "number", minimum: 0, maximum: 1 }
+     *     },
+     *     required: ["sentiment", "confidence"]
+     *   }
+     * });
+     * // response.content = '{"sentiment":"positive","confidence":0.95,"_context":{...}}'
+     * ```
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         const ollama = getOllama();
@@ -1029,6 +2068,7 @@ class OllamaProvider {
                 model: this.contextService.context.model,
                 messages,
                 tools: [toolDefinition],
+                think: GLOBAL_CONFIG.CC_ENABLE_THINKING,
             });
             const { tool_calls } = response.message;
             if (!tool_calls?.length) {
@@ -1068,7 +2108,7 @@ class OllamaProvider {
                         content: JSON.stringify(validation.data),
                     };
                     // Debug logging
-                    if (CC_ENABLE_DEBUG) {
+                    if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
                         await fs.appendFile("./debug_ollama_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
                     }
                     return result;
@@ -1081,6 +2121,33 @@ class OllamaProvider {
     }
 }
 
+/**
+ * Creates and caches an OpenAI-compatible client for Claude (Anthropic) API.
+ *
+ * Uses OpenAI SDK with Claude's API endpoint for compatibility.
+ * The client instance is cached using singleshot memoization for performance.
+ * Token rotation is not supported - throws error if array of keys is provided.
+ *
+ * Key features:
+ * - OpenAI SDK compatibility layer
+ * - Single API key support only
+ * - Instance caching with singleshot
+ * - Automatic cache clearing on error
+ *
+ * @returns OpenAI client configured for Claude API
+ * @throws Error if API key array is provided (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { getClaude } from "./config/claude";
+ *
+ * const client = getClaude();
+ * const completion = await client.chat.completions.create({
+ *   model: "claude-3-5-sonnet-20240620",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ */
 const getClaude = singleshot(() => {
     const apiKey = lib.contextService.context.apiKey;
     if (Array.isArray(apiKey)) {
@@ -1093,12 +2160,72 @@ const getClaude = singleshot(() => {
     });
 });
 
+/**
+ * Maximum number of retry attempts for outline completion when model fails to use tools correctly.
+ */
 const MAX_ATTEMPTS$3 = 5;
-class GrokProvider {
+/**
+ * Provider for Anthropic Claude models via OpenAI-compatible API.
+ *
+ * Note: This file exports ClaudeProvider class name but implements Claude functionality.
+ * This appears to be a naming inconsistency that should be addressed.
+ *
+ * Implements Claude API access through OpenAI-compatible endpoint with full tool calling support.
+ * Supports both standard and simulated streaming modes, as well as structured output
+ * through tool-based schema enforcement.
+ *
+ * Key features:
+ * - Claude API via OpenAI-compatible endpoint
+ * - Tool calling with retry logic and validation
+ * - Simulated streaming (returns complete response)
+ * - JSON schema enforcement via tool calling
+ * - Conditional tool parameter (only adds if tools present)
+ * - Debug logging when CC_ENABLE_DEBUG is enabled
+ *
+ * @example
+ * ```typescript
+ * const provider = new ClaudeProvider(contextService, logger); // Note: Should be ClaudeProvider
+ *
+ * // Standard completion
+ * const response = await provider.getCompletion({
+ *   agentName: "claude-assistant",
+ *   messages: [{ role: "user", content: "Explain neural networks" }],
+ *   mode: "direct",
+ *   tools: [searchTool],
+ *   clientId: "client-789"
+ * });
+ *
+ * // Structured output with schema validation
+ * const structured = await provider.getOutlineCompletion({
+ *   messages: [{ role: "user", content: "Classify: 'Best purchase ever!'" }],
+ *   format: {
+ *     type: "object",
+ *     properties: {
+ *       category: { type: "string" },
+ *       confidence: { type: "number" }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+class ClaudeProvider {
+    /**
+     * Creates a new ClaudeProvider instance (implements Claude functionality).
+     *
+     * @param contextService - Context service managing model configuration and API key
+     * @param logger - Logger instance for tracking provider operations
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs a standard completion request to Claude via OpenAI-compatible API.
+     * Only adds tools parameter if tools array is non-empty.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to assistant's response message
+     */
     async getCompletion(params) {
         const claude = getClaude();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -1147,11 +2274,17 @@ class GrokProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_claude_provider.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs simulated streaming completion (returns complete response, emits completion event).
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to complete assistant's response
+     */
     async getStreamCompletion(params) {
         const openai = getClaude();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -1208,11 +2341,19 @@ class GrokProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_gpt5_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs structured output completion using tool calling with retry logic.
+     * Uses tool_choice to force model to use the provide_answer tool.
+     *
+     * @param params - Outline completion parameters
+     * @returns Promise resolving to validated JSON string
+     * @throws Error if model fails after MAX_ATTEMPTS attempts
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         const claude = getClaude();
@@ -1310,7 +2451,7 @@ class GrokProvider {
                         content: JSON.stringify(validation.data),
                     };
                     // Debug logging
-                    if (CC_ENABLE_DEBUG) {
+                    if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
                         await fs.appendFile("./debug_claude_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
                     }
                     return result;
@@ -1323,6 +2464,33 @@ class GrokProvider {
     }
 }
 
+/**
+ * Creates and caches an OpenAI client for OpenAI API.
+ *
+ * Uses the official OpenAI SDK with default settings.
+ * The client instance is cached using singleshot memoization for performance.
+ * Token rotation is not supported - throws error if array of keys is provided.
+ *
+ * Key features:
+ * - Official OpenAI SDK
+ * - Single API key support only
+ * - Instance caching with singleshot
+ * - Automatic cache clearing on error
+ *
+ * @returns OpenAI client configured for OpenAI API
+ * @throws Error if API key array is provided (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { getOpenAi } from "./config/openai";
+ *
+ * const client = getOpenAi();
+ * const completion = await client.chat.completions.create({
+ *   model: "gpt-5o-mini",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ */
 const getOpenAi = singleshot(() => {
     const apiKey = lib.contextService.context.apiKey;
     if (Array.isArray(apiKey)) {
@@ -1334,11 +2502,93 @@ const getOpenAi = singleshot(() => {
     });
 });
 
+/**
+ * Provider for OpenAI GPT models (GPT-4, GPT-4 Turbo, GPT-3.5, etc.).
+ *
+ * Implements the OpenAI Chat Completions API with full tool calling support.
+ * Uses the official OpenAI SDK for reliable communication with OpenAI's API.
+ * Supports both standard and simulated streaming modes.
+ *
+ * Key features:
+ * - OpenAI Chat Completions API via official SDK
+ * - Tool calling with automatic argument serialization
+ * - Simulated streaming (returns complete response, emits completion event)
+ * - JSON schema enforcement for structured outputs
+ * - Debug logging when CC_ENABLE_DEBUG is enabled
+ *
+ * Note: This provider does not implement true token-by-token streaming.
+ * The getStreamCompletion method returns the complete response and emits
+ * a single completion event to maintain interface compatibility.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GPT5Provider(contextService, logger);
+ *
+ * // Standard completion with GPT-4
+ * const response = await provider.getCompletion({
+ *   agentName: "assistant",
+ *   messages: [{ role: "user", content: "Explain relativity" }],
+ *   mode: "direct",
+ *   tools: [],
+ *   clientId: "client-123"
+ * });
+ *
+ * // Structured output with JSON schema
+ * const analysis = await provider.getOutlineCompletion({
+ *   messages: [{ role: "user", content: "Analyze sentiment" }],
+ *   format: {
+ *     type: "json_schema",
+ *     json_schema: {
+ *       schema: {
+ *         type: "object",
+ *         properties: {
+ *           sentiment: { type: "string" },
+ *           score: { type: "number" }
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
 class GPT5Provider {
+    /**
+     * Creates a new GPT5Provider instance.
+     *
+     * @param contextService - Context service managing model configuration and API key
+     * @param logger - Logger instance for tracking provider operations
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs a standard completion request to OpenAI.
+     *
+     * Sends messages and tools to the OpenAI API and returns the complete response.
+     * Automatically serializes tool call arguments to JSON strings for API compatibility.
+     *
+     * @param params - Completion parameters including messages, tools, and agent configuration
+     * @param params.agentName - Name of the agent making the request
+     * @param params.messages - Conversation history with roles and content
+     * @param params.mode - Completion mode (e.g., "direct", "delegated")
+     * @param params.tools - Available tools for the model to call
+     * @param params.clientId - Client identifier for tracking requests
+     * @returns Promise resolving to the assistant's response message with optional tool calls
+     *
+     * @example
+     * ```typescript
+     * const response = await provider.getCompletion({
+     *   agentName: "gpt-assistant",
+     *   messages: [
+     *     { role: "user", content: "Calculate 15% tip on $85" }
+     *   ],
+     *   mode: "direct",
+     *   tools: [calculatorTool],
+     *   clientId: "client-456"
+     * });
+     * ```
+     */
     async getCompletion(params) {
         const openai = getOpenAi();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -1380,11 +2630,43 @@ class GPT5Provider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_gpt5_provider.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs a simulated streaming completion request to OpenAI.
+     *
+     * Note: This method does NOT implement true token-by-token streaming.
+     * It performs a standard completion and emits a single "llm-completion"
+     * event with the full response to maintain interface compatibility.
+     *
+     * For true streaming, the OpenAI SDK streaming API would need to be used
+     * with "stream: true" parameter.
+     *
+     * @param params - Completion parameters including messages, tools, and agent configuration
+     * @param params.agentName - Name of the agent making the request
+     * @param params.messages - Conversation history with roles and content
+     * @param params.mode - Completion mode (e.g., "direct", "delegated")
+     * @param params.tools - Available tools for the model to call
+     * @param params.clientId - Client identifier for event emission
+     * @returns Promise resolving to the complete assistant's response
+     *
+     * @example
+     * ```typescript
+     * const response = await provider.getStreamCompletion({
+     *   agentName: "gpt-assistant",
+     *   messages: [
+     *     { role: "user", content: "Write a haiku about coding" }
+     *   ],
+     *   mode: "direct",
+     *   tools: [],
+     *   clientId: "client-456"
+     * });
+     * // Client receives single "llm-completion" event with full response
+     * ```
+     */
     async getStreamCompletion(params) {
         const openai = getOpenAi();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -1441,11 +2723,53 @@ class GPT5Provider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_gpt5_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs structured output completion using OpenAI's response_format parameter.
+     *
+     * Uses OpenAI's native JSON schema mode to enforce structured output.
+     * The model is instructed to respond in a specific JSON format matching
+     * the provided schema. Uses jsonrepair to handle any JSON formatting issues.
+     *
+     * @param params - Outline completion parameters
+     * @param params.messages - Conversation history for context
+     * @param params.format - JSON schema or response format definition (supports both formats)
+     * @returns Promise resolving to validated JSON string conforming to the schema
+     * @throws Error if model returns a refusal message
+     *
+     * @example
+     * ```typescript
+     * const response = await provider.getOutlineCompletion({
+     *   messages: [
+     *     { role: "user", content: "Extract entities from: 'Apple released iPhone in Cupertino'" }
+     *   ],
+     *   format: {
+     *     type: "json_schema",
+     *     json_schema: {
+     *       schema: {
+     *         type: "object",
+     *         properties: {
+     *           entities: {
+     *             type: "array",
+     *             items: {
+     *               type: "object",
+     *               properties: {
+     *                 text: { type: "string" },
+     *                 type: { type: "string" }
+     *               }
+     *             }
+     *           }
+     *         }
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         const openai = getOpenAi();
@@ -1484,13 +2808,40 @@ class GPT5Provider {
             content: json,
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_gpt5_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
 }
 
+/**
+ * Creates and caches an OpenAI-compatible client for Deepseek API.
+ *
+ * Uses OpenAI SDK with Deepseek's API endpoint.
+ * The client instance is cached using singleshot memoization for performance.
+ * Token rotation is not supported - throws error if array of keys is provided.
+ *
+ * Key features:
+ * - OpenAI SDK compatibility layer
+ * - Single API key support only
+ * - Instance caching with singleshot
+ * - Automatic cache clearing on error
+ *
+ * @returns OpenAI client configured for Deepseek API
+ * @throws Error if API key array is provided (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { getDeepseek } from "./config/deepseek";
+ *
+ * const client = getDeepseek();
+ * const completion = await client.chat.completions.create({
+ *   model: "deepseek-chat",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ */
 const getDeepseek = singleshot(() => {
     const apiKey = lib.contextService.context.apiKey;
     if (Array.isArray(apiKey)) {
@@ -1503,12 +2854,52 @@ const getDeepseek = singleshot(() => {
     });
 });
 
+/**
+ * Maximum number of retry attempts for outline completion.
+ */
 const MAX_ATTEMPTS$2 = 3;
+/**
+ * Provider for Deepseek AI models via OpenAI-compatible API.
+ *
+ * Supports Deepseek models through OpenAI-compatible endpoint with tool calling.
+ * Features simulated streaming and structured output via tool-based schema enforcement.
+ *
+ * Key features:
+ * - OpenAI-compatible API endpoint
+ * - Tool calling with conditional inclusion (only if tools present)
+ * - Simulated streaming (returns complete response)
+ * - Schema enforcement via tool calling with retry logic
+ * - Debug logging support
+ *
+ * @example
+ * ```typescript
+ * const provider = new DeepseekProvider(contextService, logger);
+ * const response = await provider.getCompletion({
+ *   agentName: "deepseek-assistant",
+ *   messages: [{ role: "user", content: "Explain transformers" }],
+ *   mode: "direct",
+ *   tools: [],
+ *   clientId: "client-001"
+ * });
+ * ```
+ */
 class DeepseekProvider {
+    /**
+     * Creates a new DeepseekProvider instance.
+     *
+     * @param contextService - Context service with model configuration
+     * @param logger - Logger for operation tracking
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs standard completion request to Deepseek.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to assistant's response
+     */
     async getCompletion(params) {
         const deepseek = getDeepseek();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -1557,11 +2948,17 @@ class DeepseekProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_deepseek_provider.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs simulated streaming completion.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to complete response
+     */
     async getStreamCompletion(params) {
         const deepseek = getDeepseek();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -1618,11 +3015,18 @@ class DeepseekProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_deepseek_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs structured output completion with schema validation.
+     *
+     * @param params - Outline completion parameters
+     * @returns Promise resolving to validated JSON string
+     * @throws Error if model fails after MAX_ATTEMPTS
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         const deepseek = getDeepseek();
@@ -1720,7 +3124,7 @@ class DeepseekProvider {
                         content: JSON.stringify(validation.data),
                     };
                     // Debug logging
-                    if (CC_ENABLE_DEBUG) {
+                    if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
                         await fs.appendFile("./debug_deepseek_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
                     }
                     return result;
@@ -1733,6 +3137,33 @@ class DeepseekProvider {
     }
 }
 
+/**
+ * Creates and caches an OpenAI-compatible client for Mistral API.
+ *
+ * Uses OpenAI SDK with Mistral's API endpoint.
+ * The client instance is cached using singleshot memoization for performance.
+ * Token rotation is not supported - throws error if array of keys is provided.
+ *
+ * Key features:
+ * - OpenAI SDK compatibility layer
+ * - Single API key support only
+ * - Instance caching with singleshot
+ * - Automatic cache clearing on error
+ *
+ * @returns OpenAI client configured for Mistral API
+ * @throws Error if API key array is provided (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { getMistral } from "./config/mistral";
+ *
+ * const client = getMistral();
+ * const completion = await client.chat.completions.create({
+ *   model: "mistral-large-latest",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ */
 const getMistral = singleshot(() => {
     const apiKey = lib.contextService.context.apiKey;
     if (Array.isArray(apiKey)) {
@@ -1745,12 +3176,52 @@ const getMistral = singleshot(() => {
     });
 });
 
+/**
+ * Maximum number of retry attempts for outline completion.
+ */
 const MAX_ATTEMPTS$1 = 3;
+/**
+ * Provider for Mistral AI models via OpenAI-compatible API.
+ *
+ * Implements Mistral API access through OpenAI-compatible endpoint.
+ * Supports tool calling, simulated streaming, and structured output.
+ *
+ * Key features:
+ * - Mistral AI API via OpenAI-compatible endpoint
+ * - Tool calling with conditional inclusion
+ * - Simulated streaming (complete response)
+ * - Schema enforcement via tool calling with retry
+ * - Debug logging support
+ *
+ * @example
+ * ```typescript
+ * const provider = new MistralProvider(contextService, logger);
+ * const response = await provider.getCompletion({
+ *   agentName: "mistral-assistant",
+ *   messages: [{ role: "user", content: "Summarize quantum physics" }],
+ *   mode: "direct",
+ *   tools: [],
+ *   clientId: "client-555"
+ * });
+ * ```
+ */
 class MistralProvider {
+    /**
+     * Creates a new MistralProvider instance.
+     *
+     * @param contextService - Context service with model configuration
+     * @param logger - Logger for operation tracking
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs standard completion request to Mistral.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to assistant's response
+     */
     async getCompletion(params) {
         const mistral = getMistral();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -1799,11 +3270,17 @@ class MistralProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_mistral_provider.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs simulated streaming completion.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to complete response
+     */
     async getStreamCompletion(params) {
         const mistral = getMistral();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -1860,11 +3337,18 @@ class MistralProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_mistral_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs structured output completion with schema validation.
+     *
+     * @param params - Outline completion parameters
+     * @returns Promise resolving to validated JSON string
+     * @throws Error if model fails after MAX_ATTEMPTS
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         const mistral = getMistral();
@@ -1962,7 +3446,7 @@ class MistralProvider {
                         content: JSON.stringify(validation.data),
                     };
                     // Debug logging
-                    if (CC_ENABLE_DEBUG) {
+                    if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
                         await fs.appendFile("./debug_mistral_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
                     }
                     return result;
@@ -1975,6 +3459,33 @@ class MistralProvider {
     }
 }
 
+/**
+ * Creates and caches an OpenAI-compatible client for Perplexity API.
+ *
+ * Uses OpenAI SDK with Perplexity's API endpoint.
+ * The client instance is cached using singleshot memoization for performance.
+ * Token rotation is not supported - throws error if array of keys is provided.
+ *
+ * Key features:
+ * - OpenAI SDK compatibility layer
+ * - Single API key support only
+ * - Instance caching with singleshot
+ * - Automatic cache clearing on error
+ *
+ * @returns OpenAI client configured for Perplexity API
+ * @throws Error if API key array is provided (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { getPerplexity } from "./config/perplexity";
+ *
+ * const client = getPerplexity();
+ * const completion = await client.chat.completions.create({
+ *   model: "llama-3.1-sonar-large-128k-online",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ */
 const getPerplexity = singleshot(() => {
     const apiKey = lib.contextService.context.apiKey;
     if (Array.isArray(apiKey)) {
@@ -1987,11 +3498,49 @@ const getPerplexity = singleshot(() => {
     });
 });
 
+/**
+ * Provider for Perplexity AI models via OpenAI-compatible API.
+ *
+ * Implements Perplexity API access with specialized message handling.
+ * Filters and merges consecutive messages to comply with API requirements.
+ * Note: getStreamCompletion returns error message as streaming is not supported.
+ *
+ * Key features:
+ * - OpenAI-compatible API endpoint
+ * - Message filtering (user/assistant/tool only)
+ * - System message aggregation
+ * - Consecutive message merging (prevents API errors)
+ * - Tool calling support (requires description field)
+ * - Outline completion via response_format
+ * - Streaming not supported (returns error message)
+ *
+ * @example
+ * ```typescript
+ * const provider = new PerplexityProvider(contextService, logger);
+ * const response = await provider.getCompletion({
+ *   agentName: "perplexity-assistant",
+ *   messages: [{ role: "user", content: "Latest AI research?" }],
+ *   mode: "direct",
+ *   tools: [searchTool],
+ *   clientId: "client-333"
+ * });
+ * ```
+ */
 class PerplexityProvider {
+    /**
+     * Creates a new PerplexityProvider instance.
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs standard completion with message filtering and merging.
+     * Filters messages to user/assistant/tool only and merges consecutive messages.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to assistant's response
+     */
     async getCompletion(params) {
         const perplexity = getPerplexity();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -2076,11 +3625,18 @@ class PerplexityProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_perplexity_provider.txt", JSON.stringify({ params, answer: finalResult }, null, 2) + "\n\n");
         }
         return finalResult;
     }
+    /**
+     * Returns error message indicating streaming not supported.
+     * Perplexity provider does not implement token-by-token streaming.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to error message
+     */
     async getStreamCompletion(params) {
         const { clientId, agentName, mode } = params;
         this.logger.log("perplexityProvider getStreamCompletion", {
@@ -2097,6 +3653,14 @@ class PerplexityProvider {
         };
         return result;
     }
+    /**
+     * Performs structured output completion using response_format.
+     * Filters and merges messages before sending.
+     *
+     * @param params - Outline completion parameters
+     * @returns Promise resolving to validated JSON string
+     * @throws Error if model returns refusal
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         const perplexity = getPerplexity();
@@ -2168,13 +3732,40 @@ class PerplexityProvider {
             content: json,
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_perplexity_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
 }
 
+/**
+ * Creates and caches an OpenAI-compatible client for Cohere API.
+ *
+ * Uses OpenAI SDK with Cohere's compatibility endpoint.
+ * The client instance is cached using singleshot memoization for performance.
+ * Token rotation is not supported - throws error if array of keys is provided.
+ *
+ * Key features:
+ * - OpenAI SDK compatibility layer
+ * - Single API key support only
+ * - Instance caching with singleshot
+ * - Automatic cache clearing on error
+ *
+ * @returns OpenAI client configured for Cohere API
+ * @throws Error if API key array is provided (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { getCohere } from "./config/cohere";
+ *
+ * const client = getCohere();
+ * const completion = await client.chat.completions.create({
+ *   model: "command-r-plus",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ */
 const getCohere = singleshot(() => {
     const apiKey = lib.contextService.context.apiKey;
     if (Array.isArray(apiKey)) {
@@ -2187,11 +3778,56 @@ const getCohere = singleshot(() => {
     });
 });
 
+/**
+ * Provider for Cohere AI models via OpenAI-compatible API.
+ *
+ * Implements Cohere API access with specialized message handling for tool calling.
+ * Unlike other providers, includes tool messages in conversation and does NOT merge
+ * consecutive assistant messages (required for proper tool calling flow).
+ *
+ * Key features:
+ * - OpenAI-compatible API endpoint
+ * - Message filtering (user/assistant/tool - includes tool messages)
+ * - System message aggregation
+ * - NO consecutive assistant message merging (breaks tool calling)
+ * - Tool calling support (requires description field)
+ * - Outline completion via response_format
+ * - Simulated streaming
+ *
+ * Important: Cohere requires strict tool_calls -> tool_responses sequence.
+ * Merging assistant messages breaks this flow.
+ *
+ * @example
+ * ```typescript
+ * const provider = new CohereProvider(contextService, logger);
+ * const response = await provider.getCompletion({
+ *   agentName: "cohere-assistant",
+ *   messages: [
+ *     { role: "user", content: "Search for AI papers" },
+ *     { role: "assistant", content: "", tool_calls: [searchCall] },
+ *     { role: "tool", content: "Results...", tool_call_id: "123" }
+ *   ],
+ *   mode: "direct",
+ *   tools: [searchTool],
+ *   clientId: "client-222"
+ * });
+ * ```
+ */
 class CohereProvider {
+    /**
+     * Creates a new CohereProvider instance.
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs standard completion with Cohere-specific message handling.
+     * Includes tool messages and preserves assistant message sequence.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to assistant's response
+     */
     async getCompletion(params) {
         const cohere = getCohere();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -2263,11 +3899,17 @@ class CohereProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_cohere_provider.txt", JSON.stringify({ params, answer: finalResult }, null, 2) + "\n\n");
         }
         return finalResult;
     }
+    /**
+     * Performs simulated streaming completion with Cohere-specific message handling.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to complete response
+     */
     async getStreamCompletion(params) {
         const cohere = getCohere();
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
@@ -2347,11 +3989,19 @@ class CohereProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_cohere_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs structured output completion using response_format.
+     * Filters and merges user messages only (preserves assistant sequence).
+     *
+     * @param params - Outline completion parameters
+     * @returns Promise resolving to validated JSON string
+     * @throws Error if model returns refusal
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         const cohere = getCohere();
@@ -2410,20 +4060,63 @@ class CohereProvider {
             content: json,
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_cohere_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
 }
 
+/**
+ * Maximum number of retry attempts for outline completion.
+ */
 const MAX_ATTEMPTS = 3;
+/**
+ * Alibaba Cloud DashScope API base URL.
+ */
 const BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
+/**
+ * Provider for Alibaba Cloud Qwen models via DashScope API.
+ *
+ * Implements Alibaba Cloud DashScope API access using fetchApi for HTTP requests.
+ * Supports thinking mode control via enable_thinking parameter.
+ * Does NOT support token rotation (single API key only).
+ *
+ * Key features:
+ * - DashScope OpenAI-compatible endpoint
+ * - Direct fetchApi HTTP requests (no SDK)
+ * - Thinking mode control (enable_thinking parameter)
+ * - Tool calling with conditional inclusion
+ * - Simulated streaming
+ * - No token rotation support
+ *
+ * @example
+ * ```typescript
+ * const provider = new AlibabaProvider(contextService, logger);
+ * const response = await provider.getCompletion({
+ *   agentName: "qwen-assistant",
+ *   messages: [{ role: "user", content: "Explain blockchain" }],
+ *   mode: "direct",
+ *   tools: [],
+ *   clientId: "client-111"
+ * });
+ * ```
+ */
 class AlibabaProvider {
+    /**
+     * Creates a new AlibabaProvider instance.
+     */
     constructor(contextService, logger) {
         this.contextService = contextService;
         this.logger = logger;
     }
+    /**
+     * Performs standard completion request to Alibaba DashScope.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to assistant's response
+     * @throws Error if token rotation attempted
+     */
     async getCompletion(params) {
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
         this.logger.log("alibabaProvider getCompletion", {
@@ -2486,11 +4179,18 @@ class AlibabaProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_alibaba_provider.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs simulated streaming completion.
+     *
+     * @param params - Completion parameters
+     * @returns Promise resolving to complete response
+     * @throws Error if token rotation attempted
+     */
     async getStreamCompletion(params) {
         const { clientId, agentName, messages: rawMessages, mode, tools } = params;
         this.logger.log("alibabaProvider getStreamCompletion", {
@@ -2560,11 +4260,18 @@ class AlibabaProvider {
             })),
         };
         // Debug logging
-        if (CC_ENABLE_DEBUG) {
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
             await fs.appendFile("./debug_alibaba_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
         }
         return result;
     }
+    /**
+     * Performs structured output completion using tool calling with retry logic.
+     *
+     * @param params - Outline completion parameters
+     * @returns Promise resolving to validated JSON string
+     * @throws Error if model fails after MAX_ATTEMPTS or token rotation attempted
+     */
     async getOutlineCompletion(params) {
         const { messages: rawMessages, format } = params;
         this.logger.log("alibabaProvider getOutlineCompletion", {
@@ -2674,7 +4381,7 @@ class AlibabaProvider {
                         content: JSON.stringify(validation.data),
                     };
                     // Debug logging
-                    if (CC_ENABLE_DEBUG) {
+                    if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
                         await fs.appendFile("./debug_alibaba_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
                     }
                     return result;
@@ -2687,42 +4394,527 @@ class AlibabaProvider {
     }
 }
 
+/**
+ * Creates and caches an OpenAI-compatible client for Z.ai GLM-4 API.
+ *
+ * Uses OpenAI SDK with Z.ai's API endpoint for accessing Zhipu AI's GLM-4 models.
+ * The client instance is cached using singleshot memoization for performance.
+ * Token rotation is not supported - throws error if array of keys is provided.
+ *
+ * Key features:
+ * - OpenAI SDK compatibility layer
+ * - Single API key support only
+ * - Instance caching with singleshot
+ * - Automatic cache clearing on error
+ * - Context-based API key retrieval
+ *
+ * @returns OpenAI client configured for Z.ai API
+ * @throws Error if API key array is provided (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { getZAi } from "./config/zai";
+ *
+ * const client = getZAi();
+ * const completion = await client.chat.completions.create({
+ *   model: "glm-4-plus",
+ *   messages: [{ role: "user", content: "Hello" }]
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With structured output
+ * const client = getZAi();
+ * const completion = await client.chat.completions.create({
+ *   model: "glm-4-plus",
+ *   messages: [{ role: "user", content: "Generate trading signal" }],
+ *   response_format: {
+ *     type: "json_schema",
+ *     json_schema: { schema: { type: "object", properties: {...} } }
+ *   }
+ * });
+ * ```
+ */
+const getZAi = singleshot(() => {
+    const apiKey = lib.contextService.context.apiKey;
+    if (Array.isArray(apiKey)) {
+        getZAi.clear();
+        throw new Error("Z.ai provider does not support token rotation");
+    }
+    return new OpenAI({
+        apiKey,
+        baseURL: "https://api.z.ai/api/paas/v4/"
+    });
+});
+
+/**
+ * GLM-4 provider implementation for Z.ai API integration.
+ *
+ * Provides access to Zhipu AI's GLM-4 models through OpenAI-compatible API.
+ * Supports standard completions, streaming, and structured (outline) outputs.
+ * Uses the Z.ai API endpoint for model inference.
+ *
+ * Key features:
+ * - OpenAI SDK compatibility layer
+ * - Tool calling support (function calls)
+ * - Streaming completion with event emission
+ * - Structured JSON output with schema validation
+ * - Debug logging to file when enabled
+ * - Message format transformation between agent-swarm-kit and OpenAI formats
+ *
+ * @example
+ * ```typescript
+ * import { GLM4Provider } from "./client/GLM4Provider.client";
+ * import { ContextService } from "./services/base/ContextService";
+ *
+ * const provider = new GLM4Provider(contextService, logger);
+ *
+ * // Standard completion
+ * const result = await provider.getCompletion({
+ *   messages: [{ role: "user", content: "Hello" }],
+ *   agentName: "test-agent",
+ *   clientId: "client-123",
+ *   mode: "default"
+ * });
+ *
+ * // Streaming completion
+ * const stream = await provider.getStreamCompletion({
+ *   messages: [{ role: "user", content: "Analyze market" }],
+ *   agentName: "trader-agent",
+ *   clientId: "client-456",
+ *   mode: "stream"
+ * });
+ *
+ * // Structured output
+ * const outline = await provider.getOutlineCompletion({
+ *   messages: [{ role: "user", content: "Trading decision" }],
+ *   format: { type: "object", properties: {...} }
+ * });
+ * ```
+ */
+class GLM4Provider {
+    /**
+     * Creates a new GLM4Provider instance.
+     *
+     * @param contextService - Context service providing execution context (model, API key)
+     * @param logger - Logger service for operation tracking
+     */
+    constructor(contextService, logger) {
+        this.contextService = contextService;
+        this.logger = logger;
+    }
+    /**
+     * Executes a standard GLM-4 completion request.
+     *
+     * Sends messages to the GLM-4 model and returns the completion response.
+     * Supports tool calling (function calls) and automatically transforms message formats
+     * between agent-swarm-kit and OpenAI formats.
+     *
+     * Key operations:
+     * - Maps agent-swarm-kit messages to OpenAI format
+     * - Handles tool calls with JSON serialization/deserialization
+     * - Logs operation details for debugging
+     * - Optionally writes debug output to file
+     *
+     * @param params - Completion parameters including messages, tools, and context
+     * @param params.messages - Array of conversation messages
+     * @param params.tools - Optional array of function tools available to the model
+     * @param params.agentName - Name of the requesting agent
+     * @param params.clientId - Client session identifier
+     * @param params.mode - Completion mode (e.g., "default", "stream")
+     * @returns Promise resolving to completion message with optional tool calls
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.getCompletion({
+     *   messages: [
+     *     { role: "system", content: "You are a trading assistant" },
+     *     { role: "user", content: "Analyze BTC market" }
+     *   ],
+     *   tools: [
+     *     {
+     *       type: "function",
+     *       function: {
+     *         name: "get_market_data",
+     *         parameters: { type: "object", properties: {...} }
+     *       }
+     *     }
+     *   ],
+     *   agentName: "trader",
+     *   clientId: "session-123",
+     *   mode: "default"
+     * });
+     *
+     * console.log(result.content); // Model's text response
+     * console.log(result.tool_calls); // Any function calls requested
+     * ```
+     */
+    async getCompletion(params) {
+        const openai = getZAi();
+        const { clientId, agentName, messages: rawMessages, mode, tools } = params;
+        this.logger.log("glm4Provider getCompletion", {
+            agentName,
+            mode,
+            clientId,
+            context: this.contextService.context,
+        });
+        // Map raw messages to OpenAI format
+        const messages = rawMessages.map(({ role, tool_call_id, tool_calls, content }) => ({
+            role,
+            tool_call_id,
+            content,
+            tool_calls: tool_calls?.map(({ function: f, ...rest }) => ({
+                ...rest,
+                function: {
+                    name: f.name,
+                    arguments: JSON.stringify(f.arguments),
+                },
+            })),
+        }));
+        const { choices: [{ message: { content, role, tool_calls }, },], } = await openai.chat.completions.create({
+            model: this.contextService.context.model,
+            messages: messages,
+            tools: tools,
+        });
+        const result = {
+            content: content,
+            mode,
+            agentName,
+            role,
+            tool_calls: tool_calls?.map(({ function: f, ...rest }) => ({
+                ...rest,
+                function: {
+                    name: f.name,
+                    arguments: JSON.parse(f.arguments),
+                },
+            })),
+        };
+        // Debug logging
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
+            await fs.appendFile("./debug_glm4_provider.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
+        }
+        return result;
+    }
+    /**
+     * Executes a streaming GLM-4 completion request with event emission.
+     *
+     * Similar to getCompletion but emits "llm-completion" events during processing
+     * to enable real-time updates. The full response is accumulated and returned
+     * once streaming completes.
+     *
+     * Key operations:
+     * - Maps agent-swarm-kit messages to OpenAI format
+     * - Formats tools for OpenAI API
+     * - Emits events to client for real-time updates
+     * - Handles tool calls with JSON parsing
+     * - Logs operation details for debugging
+     * - Optionally writes debug output to file
+     *
+     * @param params - Completion parameters including messages, tools, and context
+     * @param params.messages - Array of conversation messages
+     * @param params.tools - Optional array of function tools available to the model
+     * @param params.agentName - Name of the requesting agent
+     * @param params.clientId - Client session identifier for event emission
+     * @param params.mode - Completion mode (typically "stream")
+     * @returns Promise resolving to accumulated completion message
+     *
+     * @example
+     * ```typescript
+     * // Listen for streaming events
+     * listen("llm-completion", (event) => {
+     *   console.log("Received chunk:", event.content);
+     * });
+     *
+     * const result = await provider.getStreamCompletion({
+     *   messages: [
+     *     { role: "user", content: "Generate trading signal for ETH" }
+     *   ],
+     *   tools: [...],
+     *   agentName: "signal-agent",
+     *   clientId: "client-789",
+     *   mode: "stream"
+     * });
+     *
+     * console.log("Final result:", result.content);
+     * ```
+     */
+    async getStreamCompletion(params) {
+        const openai = getZAi();
+        const { clientId, agentName, messages: rawMessages, mode, tools } = params;
+        this.logger.log("glm4Provider getStreamCompletion", {
+            agentName,
+            mode,
+            clientId,
+            context: this.contextService.context,
+        });
+        // Map raw messages to OpenAI format
+        const messages = rawMessages.map(({ role, tool_call_id, tool_calls, content }) => ({
+            role,
+            tool_call_id,
+            content,
+            tool_calls: tool_calls?.map(({ function: f, ...rest }) => ({
+                ...rest,
+                function: {
+                    name: f.name,
+                    arguments: JSON.stringify(f.arguments),
+                },
+            })),
+        }));
+        // Map tools to OpenAI format
+        const formattedTools = tools?.map(({ type, function: f }) => ({
+            type: type,
+            function: {
+                name: f.name,
+                parameters: f.parameters,
+            },
+        }));
+        const { choices: [{ message: { content, role, tool_calls }, },], } = await openai.chat.completions.create({
+            model: this.contextService.context.model,
+            messages: messages,
+            tools: formattedTools,
+        });
+        // Emit events to mimic streaming behavior
+        if (content) {
+            await event(clientId, "llm-completion", {
+                content: content.trim(),
+                agentName,
+            });
+        }
+        const result = {
+            content: content || "",
+            mode,
+            agentName,
+            role,
+            tool_calls: tool_calls?.map(({ function: f, ...rest }) => ({
+                ...rest,
+                function: {
+                    name: f.name,
+                    arguments: JSON.parse(f.arguments),
+                },
+            })),
+        };
+        // Debug logging
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
+            await fs.appendFile("./debug_glm4_provider_stream.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
+        }
+        return result;
+    }
+    /**
+     * Executes a structured outline completion with JSON schema validation.
+     *
+     * Generates a structured JSON response from GLM-4 that conforms to a provided schema.
+     * Uses OpenAI's response_format parameter to enforce JSON structure.
+     * The response is automatically repaired using jsonrepair if needed.
+     *
+     * Key operations:
+     * - Maps agent-swarm-kit messages to OpenAI format
+     * - Configures JSON schema response format
+     * - Sends request to GLM-4 model
+     * - Validates and repairs JSON response
+     * - Handles refusal messages
+     * - Logs operation details for debugging
+     * - Optionally writes debug output to file
+     *
+     * @param params - Outline completion parameters
+     * @param params.messages - Array of conversation messages
+     * @param params.format - JSON schema format definition or response_format object
+     * @returns Promise resolving to structured JSON message
+     * @throws Error if model refuses to generate response
+     *
+     * @example
+     * ```typescript
+     * const signal = await provider.getOutlineCompletion({
+     *   messages: [
+     *     { role: "system", content: "Generate trading signals" },
+     *     { role: "user", content: "Analyze BTC/USDT" }
+     *   ],
+     *   format: {
+     *     type: "object",
+     *     properties: {
+     *       position: { type: "string", enum: ["long", "short", "wait"] },
+     *       price_open: { type: "number" },
+     *       price_stop_loss: { type: "number" },
+     *       price_take_profit: { type: "number" }
+     *     },
+     *     required: ["position", "price_open", "price_stop_loss", "price_take_profit"]
+     *   }
+     * });
+     *
+     * const data = JSON.parse(signal.content);
+     * console.log(`Position: ${data.position}`);
+     * console.log(`Entry: ${data.price_open}`);
+     * ```
+     */
+    async getOutlineCompletion(params) {
+        const { messages: rawMessages, format } = params;
+        const openai = getZAi();
+        this.logger.log("glm4Provider getOutlineCompletion", {
+            context: this.contextService.context,
+        });
+        // Map raw messages to OpenAI format
+        const messages = rawMessages.map(({ role, tool_call_id, tool_calls, content }) => ({
+            role,
+            tool_call_id,
+            content,
+            tool_calls: tool_calls?.map(({ function: f, ...rest }) => ({
+                ...rest,
+                function: {
+                    name: f.name,
+                    arguments: JSON.stringify(f.arguments),
+                },
+            })),
+        }));
+        // Extract response format
+        const response_format = "json_schema" in format
+            ? format
+            : { type: "json_schema", json_schema: { schema: format } };
+        const completion = await openai.chat.completions.create({
+            messages: messages,
+            model: this.contextService.context.model,
+            response_format: response_format,
+        });
+        const choice = completion.choices[0];
+        if (choice.message.refusal) {
+            throw new Error(choice.message.refusal);
+        }
+        const json = jsonrepair(choice.message.content || "");
+        const result = {
+            role: "assistant",
+            content: json,
+        };
+        // Debug logging
+        if (GLOBAL_CONFIG.CC_ENABLE_DEBUG) {
+            await fs.appendFile("./debug_glm4_provider_outline.txt", JSON.stringify({ params, answer: result }, null, 2) + "\n\n");
+        }
+        return result;
+    }
+}
+
+/**
+ * Main library entry point for the Ollama package.
+ *
+ * Initializes the dependency injection container, registers all AI providers,
+ * and exports the engine object containing all services.
+ *
+ * The engine provides access to:
+ * - Common services (logger)
+ * - Base services (context)
+ * - Private services (runner and outline private services)
+ * - Public services (runner and outline public services)
+ *
+ * Registered AI providers:
+ * - Ollama (local and cloud)
+ * - OpenAI (GPT-5)
+ * - Claude (Anthropic)
+ * - Deepseek
+ * - Mistral
+ * - Perplexity
+ * - Cohere
+ * - Grok (xAI)
+ * - Alibaba
+ * - Hugging Face
+ *
+ * @example
+ * ```typescript
+ * import { engine } from "./lib";
+ *
+ * // Access logger
+ * engine.loggerService.info("Application started");
+ *
+ * // Use public service for AI completion
+ * const result = await engine.runnerPublicService.getCompletion(
+ *   { messages: [...] },
+ *   { inference: "claude", model: "claude-3-5-sonnet", apiKey: "..." }
+ * );
+ * ```
+ */
+/**
+ * Common service instances.
+ */
 const commonServices = {
     loggerService: inject(TYPES.loggerService),
 };
+/**
+ * Base service instances.
+ */
 const baseServices = {
     contextService: inject(TYPES.contextService),
 };
+/**
+ * Private service instances.
+ */
 const privateServices = {
     runnerPrivateService: inject(TYPES.runnerPrivateService),
     outlinePrivateService: inject(TYPES.outlinePrivateService),
 };
+/**
+ * Public service instances.
+ */
 const publicServices = {
     runnerPublicService: inject(TYPES.runnerPublicService),
     outlinePublicService: inject(TYPES.outlinePublicService),
 };
+/**
+ * Main engine object containing all services.
+ * Provides unified access to the entire service layer.
+ */
 const engine = {
     ...commonServices,
     ...baseServices,
     ...privateServices,
     ...publicServices,
 };
+// Initialize DI container
 init();
+/**
+ * Register all AI provider implementations.
+ */
 {
     engine.runnerPrivateService.registerRunner(InferenceName.OllamaInference, OllamaProvider);
-    engine.runnerPrivateService.registerRunner(InferenceName.GrokInference, GrokProvider$1);
+    engine.runnerPrivateService.registerRunner(InferenceName.GrokInference, GrokProvider);
     engine.runnerPrivateService.registerRunner(InferenceName.HfInference, HfProvider);
-    engine.runnerPrivateService.registerRunner(InferenceName.ClaudeInference, GrokProvider);
+    engine.runnerPrivateService.registerRunner(InferenceName.ClaudeInference, ClaudeProvider);
     engine.runnerPrivateService.registerRunner(InferenceName.GPT5Inference, GPT5Provider);
     engine.runnerPrivateService.registerRunner(InferenceName.DeepseekInference, DeepseekProvider);
     engine.runnerPrivateService.registerRunner(InferenceName.MistralInference, MistralProvider);
     engine.runnerPrivateService.registerRunner(InferenceName.PerplexityInference, PerplexityProvider);
     engine.runnerPrivateService.registerRunner(InferenceName.CohereInference, CohereProvider);
     engine.runnerPrivateService.registerRunner(InferenceName.AlibabaInference, AlibabaProvider);
+    engine.runnerPrivateService.registerRunner(InferenceName.GLM4Inference, GLM4Provider);
 }
+// Make engine globally accessible for debugging
 Object.assign(globalThis, { engine });
 var lib = engine;
 
+/**
+ * Outline runner completion handler registration.
+ *
+ * Registers a structured outline completion handler with agent-swarm-kit.
+ * This completion type enforces JSON schema validation on AI responses,
+ * ensuring they conform to a predefined structure. Essential for extracting
+ * structured data from AI responses (e.g., trading signals with specific fields).
+ *
+ * Key features:
+ * - JSON schema validation enabled (json: true)
+ * - Structured output enforcement
+ * - Type-safe response parsing
+ * - Automatic validation with retry on failure
+ * - Delegates to RunnerPrivateService
+ *
+ * @example
+ * ```typescript
+ * import { completion } from "agent-swarm-kit";
+ * import { CompletionName } from "./enum/CompletionName";
+ *
+ * const result = await completion(CompletionName.RunnerOutlineCompletion, {
+ *   messages: [
+ *     { role: "user", content: "Decide trading position" }
+ *   ]
+ * });
+ * // Returns structured data validated against schema
+ * ```
+ */
 addCompletion({
     completionName: CompletionName.RunnerOutlineCompletion,
     getCompletion: async (params) => {
@@ -2731,6 +4923,33 @@ addCompletion({
     json: true,
 });
 
+/**
+ * Streaming runner completion handler registration.
+ *
+ * Registers a streaming AI completion handler with agent-swarm-kit.
+ * This completion type enables real-time token streaming from AI providers
+ * that support it (OpenAI, Claude, etc.), with automatic accumulation into
+ * a complete response.
+ *
+ * Key features:
+ * - Streaming completion mode for real-time responses
+ * - Automatic response accumulation
+ * - Delegates to RunnerPrivateService
+ * - Supports streaming-capable AI providers
+ *
+ * @example
+ * ```typescript
+ * import { completion } from "agent-swarm-kit";
+ * import { CompletionName } from "./enum/CompletionName";
+ *
+ * const result = await completion(CompletionName.RunnerStreamCompletion, {
+ *   messages: [
+ *     { role: "user", content: "Generate trading analysis" }
+ *   ]
+ * });
+ * // Response is accumulated from stream
+ * ```
+ */
 addCompletion({
     completionName: CompletionName.RunnerStreamCompletion,
     getCompletion: async (params) => {
@@ -2738,6 +4957,32 @@ addCompletion({
     },
 });
 
+/**
+ * Standard runner completion handler registration.
+ *
+ * Registers a non-streaming AI completion handler with agent-swarm-kit.
+ * This completion type is used for standard request-response AI interactions
+ * where the full response is returned at once.
+ *
+ * Key features:
+ * - Standard (non-streaming) completion mode
+ * - Delegates to RunnerPrivateService
+ * - Supports all registered AI providers
+ * - Context-aware provider selection
+ *
+ * @example
+ * ```typescript
+ * import { completion } from "agent-swarm-kit";
+ * import { CompletionName } from "./enum/CompletionName";
+ *
+ * const result = await completion(CompletionName.RunnerCompletion, {
+ *   messages: [
+ *     { role: "system", content: "You are a trading assistant" },
+ *     { role: "user", content: "Analyze BTC/USDT" }
+ *   ]
+ * });
+ * ```
+ */
 addCompletion({
     completionName: CompletionName.RunnerCompletion,
     getCompletion: async (params) => {
@@ -2745,6 +4990,35 @@ addCompletion({
     },
 });
 
+/**
+ * Zod schema for trading signal structured output.
+ *
+ * Defines the JSON schema used for LLM-generated trading signals with
+ * comprehensive field descriptions and validation rules. Used with outline
+ * completion to enforce structured output from language models.
+ *
+ * Fields:
+ * - position: Trading direction (long/short/wait)
+ * - price_open: Entry price in USD
+ * - price_stop_loss: Stop-loss price in USD
+ * - price_take_profit: Take-profit price in USD
+ * - minute_estimated_time: Estimated hold duration in minutes
+ * - risk_note: Detailed risk assessment with specific metrics
+ *
+ * @example
+ * ```typescript
+ * import { SignalSchema } from './schema/Signal.schema';
+ *
+ * const signal = SignalSchema.parse({
+ *   position: 'long',
+ *   price_open: 50000,
+ *   price_stop_loss: 49000,
+ *   price_take_profit: 52000,
+ *   minute_estimated_time: 120,
+ *   risk_note: 'RSI oversold at 32%, volume spike +45%'
+ * });
+ * ```
+ */
 const SignalSchema = z.object({
     position: z
         .enum(["long", "short", "wait"])
@@ -2766,6 +5040,46 @@ const SignalSchema = z.object({
         .describe(str.newline("Description of current market situation risks:", "", "Analyze and specify applicable risks:", "1. Whale manipulations (volume spikes, long shadows, pin bars, candle engulfing, false breakouts)", "2. Order book (order book walls, spoofing, bid/ask imbalance, low liquidity)", "3. P&L history (recurring mistakes on similar patterns)", "4. Time factors (trading session, low liquidity, upcoming events)", "5. Correlations (overall market trend, conflicting trends across timeframes)", "6. Technical risks (indicator divergences, weak volumes, critical levels)", "7. Gaps and anomalies (price gaps, unfilled gaps, movements without volume)", "", "Provide SPECIFIC numbers, percentages and probabilities.")),
 });
 
+/**
+ * Trading signal outline schema registration.
+ *
+ * Registers a structured outline for trading signal generation with comprehensive
+ * validation rules. This outline enforces a strict schema for AI-generated trading
+ * signals, ensuring all required fields are present and correctly formatted.
+ *
+ * Schema fields:
+ * - position: Trading direction ("long", "short", or "wait")
+ * - price_open: Entry price for the position
+ * - price_stop_loss: Stop-loss price level
+ * - price_take_profit: Take-profit price level
+ * - minute_estimated_time: Estimated time to reach TP (in minutes)
+ * - risk_note: Risk assessment and reasoning (markdown format)
+ *
+ * Validation rules:
+ * 1. All required fields must be present
+ * 2. Prices must be positive numbers
+ * 3. For LONG: SL < entry < TP
+ * 4. For SHORT: TP < entry < SL
+ * 5. Estimated time must be <= 360 minutes (6 hours)
+ * 6. Wait position skips price validations
+ *
+ * @example
+ * ```typescript
+ * import { json } from "agent-swarm-kit";
+ * import { OutlineName } from "./enum/OutlineName";
+ *
+ * const { data } = await json(OutlineName.SignalOutline, [
+ *   { role: "user", content: "Analyze BTC/USDT and decide position" }
+ * ]);
+ *
+ * if (data.position !== "wait") {
+ *   console.log(`Position: ${data.position}`);
+ *   console.log(`Entry: ${data.price_open}`);
+ *   console.log(`SL: ${data.price_stop_loss}`);
+ *   console.log(`TP: ${data.price_take_profit}`);
+ * }
+ * ```
+ */
 addOutline({
     outlineName: OutlineName.SignalOutline,
     completion: CompletionName.RunnerOutlineCompletion,
@@ -2862,44 +5176,281 @@ addOutline({
     ],
 });
 
+/**
+ * Bootstrap module for agent-swarm-kit validation.
+ *
+ * Validates that all completion and outline names are properly registered
+ * with agent-swarm-kit before the application starts. This ensures that
+ * all referenced completions and outlines exist and are correctly configured.
+ *
+ * Validation checks:
+ * - All CompletionName enum values have corresponding registered handlers
+ * - All OutlineName enum values have corresponding registered schemas
+ * - No duplicate registrations exist
+ *
+ * This file is imported by index.ts to run validation at startup.
+ *
+ * @throws Error if validation fails (missing or duplicate registrations)
+ */
 validate({
     CompletionName: CompletionName$1,
     OutlineName: OutlineName$1,
 });
 
+/**
+ * Generate structured trading signal from Ollama models.
+ *
+ * Supports token rotation by passing multiple API keys. Automatically enforces
+ * the signal JSON schema defined in Signal.schema.ts.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - Ollama model name (e.g., "llama3.3:70b")
+ * @param apiKey - Single API key or array of keys for rotation
+ * @returns Promise resolving to structured trading signal
+ *
+ * @example
+ * ```typescript
+ * import { ollama } from '@backtest-kit/ollama';
+ *
+ * const signal = await ollama(messages, 'llama3.3:70b', ['key1', 'key2']);
+ * console.log(signal.position); // "long" | "short" | "wait"
+ * ```
+ */
 const ollama = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.OllamaInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from Grok models.
+ *
+ * Uses xAI Grok models through direct API access. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - Grok model name (e.g., "grok-beta")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { grok } from '@backtest-kit/ollama';
+ *
+ * const signal = await grok(messages, 'grok-beta', process.env.GROK_API_KEY);
+ * ```
+ */
 const grok = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.GrokInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from Hugging Face models.
+ *
+ * Uses HuggingFace Router API for model access. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - HuggingFace model name
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ *
+ * @example
+ * ```typescript
+ * import { hf } from '@backtest-kit/ollama';
+ *
+ * const signal = await hf(messages, 'meta-llama/Llama-3-70b', process.env.HF_API_KEY);
+ * ```
+ */
 const hf = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.HfInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from Claude models.
+ *
+ * Uses Anthropic Claude through OpenAI-compatible API. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - Claude model name (e.g., "claude-3-5-sonnet-20241022")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { claude } from '@backtest-kit/ollama';
+ *
+ * const signal = await claude(messages, 'claude-3-5-sonnet-20241022', process.env.ANTHROPIC_API_KEY);
+ * ```
+ */
 const claude = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.ClaudeInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from OpenAI GPT models.
+ *
+ * Uses official OpenAI SDK with JSON schema enforcement. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - OpenAI model name (e.g., "gpt-4o", "gpt-4-turbo")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { gpt5 } from '@backtest-kit/ollama';
+ *
+ * const signal = await gpt5(messages, 'gpt-4o', process.env.OPENAI_API_KEY);
+ * ```
+ */
 const gpt5 = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.GPT5Inference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from DeepSeek models.
+ *
+ * Uses DeepSeek AI through OpenAI-compatible API. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - DeepSeek model name (e.g., "deepseek-chat")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { deepseek } from '@backtest-kit/ollama';
+ *
+ * const signal = await deepseek(messages, 'deepseek-chat', process.env.DEEPSEEK_API_KEY);
+ * ```
+ */
 const deepseek = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.DeepseekInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from Mistral AI models.
+ *
+ * Uses Mistral AI through OpenAI-compatible API. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - Mistral model name (e.g., "mistral-large-latest")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { mistral } from '@backtest-kit/ollama';
+ *
+ * const signal = await mistral(messages, 'mistral-large-latest', process.env.MISTRAL_API_KEY);
+ * ```
+ */
 const mistral = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.MistralInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from Perplexity AI models.
+ *
+ * Uses Perplexity AI through OpenAI-compatible API. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - Perplexity model name (e.g., "llama-3.1-sonar-huge-128k-online")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { perplexity } from '@backtest-kit/ollama';
+ *
+ * const signal = await perplexity(messages, 'llama-3.1-sonar-huge-128k-online', process.env.PERPLEXITY_API_KEY);
+ * ```
+ */
 const perplexity = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.PerplexityInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from Cohere models.
+ *
+ * Uses Cohere AI through OpenAI-compatible API. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - Cohere model name (e.g., "command-r-plus")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { cohere } from '@backtest-kit/ollama';
+ *
+ * const signal = await cohere(messages, 'command-r-plus', process.env.COHERE_API_KEY);
+ * ```
+ */
 const cohere = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.CohereInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from Alibaba Cloud Qwen models.
+ *
+ * Uses Alibaba DashScope API through direct HTTP requests. Does NOT support token rotation.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - Qwen model name (e.g., "qwen-max")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { alibaba } from '@backtest-kit/ollama';
+ *
+ * const signal = await alibaba(messages, 'qwen-max', process.env.ALIBABA_API_KEY);
+ * ```
+ */
 const alibaba = async (messages, model, apiKey) => {
     return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.AlibabaInference, model, apiKey);
 };
+/**
+ * Generate structured trading signal from Zhipu AI GLM-4 models.
+ *
+ * Uses Zhipu AI's GLM-4 through OpenAI-compatible Z.ai API. Does NOT support token rotation.
+ * GLM-4 is a powerful Chinese language model with strong reasoning capabilities.
+ *
+ * @param messages - Array of outline messages (user/assistant/system)
+ * @param model - GLM-4 model name (e.g., "glm-4-plus", "glm-4-air")
+ * @param apiKey - Single API key (token rotation not supported)
+ * @returns Promise resolving to structured trading signal
+ * @throws Error if apiKey is an array (token rotation not supported)
+ *
+ * @example
+ * ```typescript
+ * import { glm4 } from '@backtest-kit/ollama';
+ *
+ * const signal = await glm4(messages, 'glm-4-plus', process.env.ZAI_API_KEY);
+ * console.log(`Position: ${signal.position}`);
+ * console.log(`Entry: ${signal.priceOpen}`);
+ * ```
+ */
+const glm4 = async (messages, model, apiKey) => {
+    return await lib.outlinePublicService.getCompletion(messages, InferenceName$1.GLM4Inference, model, apiKey);
+};
 
+/**
+ * Sets custom logger implementation for the framework.
+ *
+ * All log messages from internal services will be forwarded to the provided logger
+ * with automatic context injection.
+ *
+ * @param logger - Custom logger implementing ILogger interface
+ *
+ * @example
+ * ```typescript
+ * setLogger({
+ *   log: (topic, ...args) => console.log(topic, args),
+ *   debug: (topic, ...args) => console.debug(topic, args),
+ *   info: (topic, ...args) => console.info(topic, args),
+ * });
+ * ```
+ */
 const setLogger = (logger) => {
     lib.loggerService.setLogger(logger);
 };
 
-export { alibaba, claude, cohere, deepseek, gpt5, grok, hf, engine as lib, mistral, ollama, perplexity, setLogger };
+export { alibaba, claude, cohere, deepseek, glm4, gpt5, grok, hf, engine as lib, mistral, ollama, perplexity, setLogger };