katanakit-js 6.4.3 → 6.7.1

package/dist/core/services/agent.service.d.ts

@@ -1,4 +1,4 @@
-import type { AgentResult, AgentRunOptions, AiChatOptions, AiMessage, AiProviderConfig, AiResult } from "../../types/index.js";
+import type { AgentResult, AgentRunOptions, AiChatOptions, AiMessage, AiProviderConfig, AiResult, AiTool, AiToolCall } from "../../types/index.js";
 /** Default endpoint for Alibaba Cloud Model Studio (DashScope) compatible mode. */
 export declare const KITT_BASE_URL = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
 /** Default model for the Kitt assistant preset. */
@@ -7,11 +7,183 @@ export declare const KITT_DEFAULT_MODEL = "qwen3.8-max";
 export declare const KITT_SYSTEM_PROMPT = "You are Kitt, a helpful assistant. Answer clearly and concisely.";
 /** Reusable preset (base URL + model) for the Kitt assistant. */
 export declare const kittPreset: Pick<AiProviderConfig, "baseUrl" | "model">;
+/** Shape of a `/chat/completions` response. */
+interface ChatCompletionResponse {
+    choices?: Array<{
+        message?: {
+            content?: string | null;
+            tool_calls?: AiToolCall[];
+        };
+        finish_reason?: string | null;
+    }>;
+    error?: {
+        message?: string;
+    };
+}
+/** Request options shared by chat and agent calls. */
+interface RequestOptions {
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    signal?: AbortSignal;
+    tools?: AiTool[];
+}
 /**
- * Registers the AI provider for the Kitt assistant.
+ * Estrategia de proveedor AI - Strategy Pattern.
+ *
+ * Define el contrato que toda implementación de proveedor de completions debe
+ * cumplir. El {@link AgentService} delega la llamada HTTP en una estrategia
+ * concreta, permitiendo intercambiar proveedores (DashScope, OpenAI,
+ * self-hosted, mock en tests) sin tocar el bucle del agente.
+ */
+export interface IAiProviderStrategy {
+    /**
+     * Performs a single `chat/completions` request against the provider.
+     *
+     * @param config - Provider configuration (baseUrl, model, apiKey).
+     * @param messages - Conversation messages.
+     * @param options - Sampling options, tools and abort signal.
+     * @returns The parsed provider response.
+     * @throws On non-2xx responses or transport failures.
+     */
+    requestCompletion(config: AiProviderConfig, messages: AiMessage[], options: RequestOptions): Promise<ChatCompletionResponse>;
+}
+/**
+ * Estrategia por defecto: proveedor compatible con OpenAI
+ * (`POST /chat/completions` con Bearer token). Cubre DashScope en modo
+ * compatible, OpenAI, Azure OpenAI y la mayoría de endpoints self-hosted.
+ *
+ * @example
+ * ```ts
+ * const strategy = new OpenAiCompatibleStrategy();
+ * const response = await strategy.requestCompletion(config, messages, {});
+ * ```
+ */
+export declare class OpenAiCompatibleStrategy implements IAiProviderStrategy {
+    /**
+     * Performs a raw `chat/completions` request against the provider.
+     * Throws {@link AiHttpError} on non-2xx responses.
+     */
+    requestCompletion(config: AiProviderConfig, messages: AiMessage[], options: RequestOptions): Promise<ChatCompletionResponse>;
+}
+/**
+ * AgentService - Singleton facade con Strategy Pattern.
  *
- * `apiKey` falls back to `process.env.DASHSCOPE_API_KEY`; `baseUrl`, `model`
- * and `systemPrompt` fall back to the {@link kittPreset} defaults.
+ * Centraliza el registro del proveedor AI y el bucle de completions,
+ * delegando la llamada HTTP en una {@link IAiProviderStrategy}
+ * intercambiable. Por defecto usa {@link OpenAiCompatibleStrategy}.
+ *
+ * @example
+ * ```ts
+ * // Configurar el proveedor
+ * AgentService.getInstance().useInitAgent({ apiKey: process.env.DASHSCOPE_API_KEY });
+ *
+ * // Cambiar de estrategia en runtime (p. ej. un mock en tests)
+ * AgentService.getInstance().useSetStrategy(new OpenAiCompatibleStrategy());
+ * ```
+ */
+export declare class AgentService {
+    private static instance;
+    private provider;
+    private strategy;
+    /**
+     * Constructor privado - enforce singleton.
+     * @param strategy - Estrategia de proveedor a inyectar (opcional).
+     */
+    private constructor();
+    /**
+     * Obtiene la instancia única del AgentService (Singleton).
+     *
+     * @returns La instancia única de {@link AgentService}.
+     */
+    static getInstance(): AgentService;
+    /**
+     * Crea una instancia NO-singleton con una estrategia específica.
+     * Útil para tests o para aislar varios proveedores.
+     *
+     * @param strategy - Estrategia a inyectar.
+     * @returns Una nueva instancia de {@link AgentService}.
+     */
+    static create(strategy?: IAiProviderStrategy): AgentService;
+    /**
+     * Intercambia la estrategia de proveedor en runtime (Strategy Pattern).
+     *
+     * @param strategy - La nueva estrategia a utilizar.
+     */
+    useSetStrategy(strategy: IAiProviderStrategy): void;
+    /** Returns the currently active provider strategy. */
+    useGetStrategy(): IAiProviderStrategy;
+    /** Retrieves the configured provider or throws. */
+    private useGetProvider;
+    /**
+     * Registers the AI provider for the Kitt assistant.
+     *
+     * `apiKey` falls back to `process.env.DASHSCOPE_API_KEY`; `baseUrl`, `model`
+     * and `systemPrompt` fall back to the {@link kittPreset} defaults.
+     *
+     * @param config - Partial provider configuration.
+     *
+     * @example
+     * ```ts
+     * import { useInitAgent } from "katanakit-js";
+     *
+     * useInitAgent({
+     *   apiKey: process.env.DASHSCOPE_API_KEY,
+     *   model: "qwen3.8-max",
+     * });
+     * ```
+     */
+    useInitAgent(config?: Partial<AiProviderConfig>): void;
+    /**
+     * Sends a single chat completion and returns the assistant text as a Safe Result.
+     *
+     * Use this for review / questioning (single-shot). For autonomous multi-step
+     * work with tools, use {@link useRunAgent}.
+     *
+     * @param messages - Conversation messages (a system prompt is prepended if absent).
+     * @param options - Optional completion options.
+     * @returns A `AiResult` with the assistant text.
+     *
+     * @example
+     * ```ts
+     * import { useChat } from "katanakit-js";
+     *
+     * const result = await useChat([
+     *   { role: "user", content: "Summarize the benefits of solar energy in three bullet points." },
+     * ]);
+     * if (result.ok) console.log(result.data);
+     * ```
+     */
+    useChat(messages: AiMessage[], options?: AiChatOptions): Promise<AiResult<string>>;
+    /**
+     * Runs the tool-calling agent loop against a goal until it emits a final
+     * answer or exhausts `maxSteps`.
+     *
+     * @param goal - The natural-language objective.
+     * @param options - Tools, step budget and completion options.
+     * @returns An `AgentResult` with the final message and executed steps.
+     *
+     * @example
+     * ```ts
+     * import { useRunAgent } from "katanakit-js";
+     *
+     * const result = await useRunAgent("Fix the type errors reported by tsc", {
+     *   tools: [
+     *     {
+     *       name: "runCommand",
+     *       description: "Runs a shell command and returns its output",
+     *       parameters: { type: "object", properties: { command: { type: "string" } } },
+     *       execute: (input) => shell.run(input.command),
+     *     },
+     *   ],
+     *   maxSteps: 12,
+     * });
+     * ```
+     */
+    useRunAgent(goal: string, options?: AgentRunOptions): Promise<AgentResult>;
+}
+/**
+ * Registers the AI provider for the Kitt assistant.
  *
  * @param config - Partial provider configuration.
  *
@@ -19,30 +191,22 @@ export declare const kittPreset: Pick<AiProviderConfig, "baseUrl" | "model">;
  * ```ts
  * import { useInitAgent } from "katanakit-js";
  *
- * useInitAgent({
- *   apiKey: process.env.DASHSCOPE_API_KEY,
- *   model: "qwen3.8-max",
- * });
+ * useInitAgent({ apiKey: process.env.DASHSCOPE_API_KEY });
  * ```
  */
 export declare function useInitAgent(config?: Partial<AiProviderConfig>): void;
 /**
  * Sends a single chat completion and returns the assistant text as a Safe Result.
  *
- * Use this for review / questioning (single-shot). For autonomous multi-step
- * work with tools, use {@link useRunAgent}.
- *
  * @param messages - Conversation messages (a system prompt is prepended if absent).
  * @param options - Optional completion options.
- * @returns A {@link AiResult} with the assistant text.
+ * @returns An `AiResult` with the assistant text.
  *
  * @example
  * ```ts
  * import { useChat } from "katanakit-js";
  *
- * const result = await useChat([
- *   { role: "user", content: "Summarize the benefits of solar energy in three bullet points." },
- * ]);
+ * const result = await useChat([{ role: "user", content: "Hello" }]);
  * if (result.ok) console.log(result.data);
  * ```
  */
@@ -53,24 +217,15 @@ export declare function useChat(messages: AiMessage[], options?: AiChatOptions):
  *
  * @param goal - The natural-language objective.
  * @param options - Tools, step budget and completion options.
- * @returns An {@link AgentResult} with the final message and executed steps.
+ * @returns An `AgentResult` with the final message and executed steps.
  *
  * @example
  * ```ts
  * import { useRunAgent } from "katanakit-js";
  *
- * const result = await useRunAgent("Fix the type errors reported by tsc", {
- *   tools: [
- *     {
- *       name: "runCommand",
- *       description: "Runs a shell command and returns its output",
- *       parameters: { type: "object", properties: { command: { type: "string" } } },
- *       execute: (input) => shell.run(input.command),
- *     },
- *   ],
- *   maxSteps: 12,
- * });
+ * const result = await useRunAgent("Fix the type errors reported by tsc");
  * ```
  */
 export declare function useRunAgent(goal: string, options?: AgentRunOptions): Promise<AgentResult>;
+export {};
 //# sourceMappingURL=agent.service.d.ts.map

package/dist/core/services/agent.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/agent.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,WAAW,EACX,eAAe,EAEf,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,QAAQ,EAGR,MAAM,sBAAsB,CAAC;AAE9B,mFAAmF;AACnF,eAAO,MAAM,aAAa,2DAA2D,CAAC;AAEtF,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,qEACoC,CAAC;AAEpE,iEAAiE;AACjE,eAAO,MAAM,UAAU,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,OAAO,CAGlE,CAAC;AAgLF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM,GAAG,IAAI,CAiBzE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,OAAO,CAC5B,QAAQ,EAAE,SAAS,EAAE,EACrB,OAAO,GAAE,aAAkB,GACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAuB3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC3B,OAAO,CAAC,WAAW,CAAC,CA4EtB"}
+{"version":3,"file":"agent.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/agent.service.ts"],"names":[],"mappings":"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"}