outline-completion

Author: tripolskypetr

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-swarm-kit",
-  "version": "1.1.116",
+  "version": "1.1.118",
   "description": "A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems",
   "author": {
     "name": "Petr Tripolsky",

package.json

@@ -263,7 +263,12 @@ const RUN_FN = async (incoming: string, self: ClientAgent): Promise<string> => {
     mode: "user" as const,
     tools: [],
   };
-  const rawMessage = await self.params.completion.getCompletion(args);
+  const completionMessage = await self.params.completion.getCompletion(args);
+  const rawMessage: IModelMessage = {
+    agentName: self.params.agentName,
+    mode: "tool",
+    ...completionMessage,
+  };
   self.params.completion.callbacks?.onComplete &&
     self.params.completion.callbacks?.onComplete(args, rawMessage);
   const message = await self.params.map(
@@ -1039,7 +1044,12 @@ export class ClientAgent implements IAgent {
         tools
       ),
     };
-    const output = await this.params.completion.getCompletion(args);
+    const rawMessage = await this.params.completion.getCompletion(args);
+    const output: IModelMessage = {
+      agentName: this.params.agentName,
+      mode: "tool",
+      ...rawMessage,
+    };
     if (GLOBAL_CONFIG.CC_RESQUE_STRATEGY === "flush") {
       this.params.completion.callbacks?.onComplete &&
         this.params.completion.callbacks?.onComplete(args, output);
@@ -1106,7 +1116,12 @@ export class ClientAgent implements IAgent {
           tools
         ),
       };
-      const output = await this.params.completion.getCompletion(args);
+      const rawMessage = await this.params.completion.getCompletion(args);
+      const output: IModelMessage = {
+        agentName: this.params.agentName,
+        mode: "tool",
+        ...rawMessage,
+      };
       this.params.completion.callbacks?.onComplete &&
         this.params.completion.callbacks?.onComplete(args, output);
       return {

src/client/ClientAgent.ts

@@ -11,7 +11,7 @@ import {
   IOutlineValidationArgs,
   IOutlineResult,
 } from "../../interfaces/Outline.interface";
-import { getErrorMessage, randomString, str } from "functools-kit";
+import { getErrorMessage, randomString } from "functools-kit";
 
 const METHOD_NAME = "function.target.json";
 
@@ -32,11 +32,23 @@ class OutlineHistory implements IOutlineHistory {
    * @param {string} [prompt] - An optional system prompt to initialize the history with.
    * @constructor
    */
-  constructor(prompt?: string) {
-    prompt && this.messages.push({
-      role: "system",
-      content: prompt
-    })
+  constructor(prompt?: string | string[]) {
+    if (!prompt) {
+      return;
+    }
+    if (typeof prompt === "string") {
+      this.messages.push({
+        role: "system",
+        content: prompt,
+      });
+      return;
+    }
+    prompt.forEach((content) => {
+      this.messages.push({
+        role: "system",
+        content,
+      });
+    });
   }
 
   /**
@@ -93,20 +105,25 @@ const jsonInternal = beginContext(
     const resultId = randomString();
 
     const {
-      getStructuredOutput,
+      getOutlineHistory,
+      completion,
       validations = [],
       maxAttempts = MAX_ATTEMPTS,
       format,
       prompt,
-      callbacks,
+      callbacks: outlineCallbacks,
     } = swarm.outlineSchemaService.get(outlineName);
 
+    swarm.completionValidationService.validate(completion, METHOD_NAME);
+
+    const { getCompletion, callbacks: completionCallbacks } =
+      swarm.completionSchemaService.get(completion);
+
     let errorMessage: string = "";
     let history: OutlineHistory;
 
-    const systemPrompt = str.newline(
-      typeof prompt === "function" ? await prompt(outlineName) : prompt
-    );
+    const systemPrompt =
+      typeof prompt === "function" ? await prompt(outlineName) : prompt;
 
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       history = new OutlineHistory(systemPrompt);
@@ -116,41 +133,52 @@ const jsonInternal = beginContext(
         param,
         history,
       };
-      if (callbacks?.onAttempt) {
-        callbacks.onAttempt(inputArgs);
+      if (outlineCallbacks?.onAttempt) {
+        outlineCallbacks.onAttempt(inputArgs);
       }
-      const data = await getStructuredOutput(inputArgs);
-      const validationArgs: IOutlineValidationArgs = {
-        ...inputArgs,
-        data,
-      };
-      let isValid = true;
-      for (const validation of validations) {
-        const validate =
-          typeof validation === "object" ? validation.validate : validation;
-        try {
+      await getOutlineHistory(inputArgs);
+      const messages = await history.list();
+      try {
+        const output = await getCompletion({
+          messages: await history.list(),
+          mode: "tool",
+          outlineName,
+        });
+        if (completionCallbacks?.onComplete) {
+          completionCallbacks.onComplete(
+            {
+              messages,
+              mode: "tool",
+              outlineName,
+            },
+            output
+          );
+        }
+        const data = JSON.parse(output.content) as IOutlineData;
+        const validationArgs: IOutlineValidationArgs = {
+          ...inputArgs,
+          data,
+        };
+        for (const validation of validations) {
+          const validate =
+            typeof validation === "object" ? validation.validate : validation;
           await validate(validationArgs);
-        } catch (error) {
-          isValid = false;
-          errorMessage = getErrorMessage(error);
-          break;
         }
+        const result = {
+          isValid: true,
+          attempt,
+          param,
+          history: await history.list(),
+          data,
+          resultId,
+        };
+        if (outlineCallbacks?.onValidDocument) {
+          outlineCallbacks.onValidDocument(result);
+        }
+        return result;
+      } catch (error) {
+        errorMessage = getErrorMessage(error);
       }
-      if (!isValid) {
-        continue;
-      }
-      const result = {
-        isValid: true,
-        attempt,
-        param,
-        history: await history.list(),
-        data,
-        resultId,
-      };
-      if (callbacks?.onValidDocument) {
-        callbacks.onValidDocument(result);
-      }
-      return result;
     }
     const result = {
       isValid: false,
@@ -161,8 +189,8 @@ const jsonInternal = beginContext(
       data: null,
       resultId,
     };
-    if (callbacks?.onInvalidDocument) {
-      callbacks.onInvalidDocument(result);
+    if (outlineCallbacks?.onInvalidDocument) {
+      outlineCallbacks.onInvalidDocument(result);
     }
     return result;
   }

src/functions/target/json.ts

@@ -1,6 +1,7 @@
 import { IModelMessage } from "../model/ModelMessage.model";
 import { ITool } from "../model/Tool.model";
 import { AgentName } from "./Agent.interface";
+import { IOutlineMessage, OutlineName } from "./Outline.interface";
 import { ExecutionMode } from "./Session.interface";
 
 /**
@@ -15,17 +16,34 @@ export interface ICompletion extends ICompletionSchema {}
  * Encapsulates context and inputs for generating a model response.
  */
 export interface ICompletionArgs {
-  /** The unique ID of the client requesting the completion. */
-  clientId: string;
+  /**
+   * The unique identifier for the client making the request.
+   * This is used to track the request and associate it with the correct client context.
+   * For outline completions, this being skipped
+   * @type {string}
+   */
+  clientId?: string;
 
-  /** The unique name of the agent associated with the completion request. */
-  agentName: AgentName;
+  /**
+   * The name of the agent for which the completion is requested.
+   * This is used to identify the agent context in which the completion will be generated.
+   * @type {AgentName}
+   */
+  agentName?: AgentName;
+
+  /**
+   * The outline used for json completions, if applicable.
+   * This is the name of the outline schema that defines the structure of the expected JSON response.
+   * Used to ensure that the completion adheres to the specified outline format.
+   * @type {OutlineName}
+   */
+  outlineName?: OutlineName;
 
   /** The source of the last message, indicating whether it originated from a tool or user. */
   mode: ExecutionMode;
 
   /** An array of model messages providing the conversation history or context for the completion. */
-  messages: IModelMessage[];
+  messages: (IModelMessage | IOutlineMessage)[];
 
   /** Optional array of tools available for the completion process (e.g., for tool calls). */
   tools?: ITool[];
@@ -42,7 +60,7 @@ export interface ICompletionCallbacks {
    * @param {ICompletionArgs} args - The arguments used to generate the completion.
    * @param {IModelMessage} output - The model-generated message resulting from the completion.
    */
-  onComplete?: (args: ICompletionArgs, output: IModelMessage) => void;
+  onComplete?: (args: ICompletionArgs, output: IModelMessage | IOutlineMessage) => void;
 }
 
 /**
@@ -60,7 +78,14 @@ export interface ICompletionSchema {
    * @returns {Promise<IModelMessage>} A promise resolving to the generated model message.
    * @throws {Error} If completion generation fails (e.g., due to invalid arguments, model errors, or tool issues).
    */
-  getCompletion(args: ICompletionArgs): Promise<IModelMessage>;
+  getCompletion(args: ICompletionArgs): Promise<IModelMessage | IOutlineMessage>;
+
+  /*
+   * Flag if the completion is a JSON completion.
+   * If true, the completion will be treated as a JSON object.
+   * Should be used for completions that return structured data using Outlines.
+   */
+  json?: boolean;
 
   /** List of flags for llm model. As example, `/no_think` for `lmstudio-community/Qwen3-32B-GGUF`  */
   flags?: string[];

src/interfaces/Completion.interface.ts

@@ -1,3 +1,6 @@
+import { IToolCall } from "../model/Tool.model";
+import { CompletionName } from "./Completion.interface";
+
 /**
  * Generic type representing arbitrary param for outline operations.
  * Used as a flexible placeholder for input param in outline schemas and arguments.
@@ -101,16 +104,29 @@ export interface IOutlineMessage {
   /**
    * The role of the message sender, either user, assistant, or system.
    * Determines the context or source of the message in the outline history.
-   * @type {"user" | "assistant" | "system"}
+   * @type {"assistant" | "system" | "tool" | "user"}
    */
-  role: "user" | "assistant" | "system";
+  role: "assistant" | "system" | "tool" | "user";
 
   /**
    * The content of the message.
    * Contains the raw text or param of the message, used in history storage or processing.
    * @type {string}
    */
   content: string;
+
+  /**
+   * The name of the agent associated with the message.
+   * Allow to attach tool call request to specific message
+   */
+  tool_calls?: IToolCall[];
+
+  /**
+   * Optional ID of the tool call associated with the message.
+   * Used to link the message to a specific tool execution request.
+   * @type {string | undefined}
+   */
+  tool_call_id?: string;
 }
 
 /**
@@ -310,6 +326,9 @@ export interface IOutlineSchema<
   Param extends IOutlineParam = IOutlineParam
 > {
 
+  /** The name of the completion for JSON */
+  completion: CompletionName;
+
   /**
    * The prompt or prompt generator for the outline operation.
    * Can be a string, an array of strings, or a function that returns a string, array of strings, or a promise resolving to either.
@@ -339,7 +358,7 @@ export interface IOutlineSchema<
    * @param {IOutlineArgs<Param>} args - The arguments containing input param and history.
    * @returns {Promise<Data>} A promise resolving to the structured data.
    */
-  getStructuredOutput(args: IOutlineArgs<Param>): Promise<Data>;
+  getOutlineHistory(args: IOutlineArgs<Param>): Promise<void>;
 
   /**
    * Array of validation functions or configurations to apply to the outline data.

src/interfaces/Outline.interface.ts

@@ -430,6 +430,13 @@ export class DocService {
         result.push("");
       }
 
+      if (outlineSchema.completion) {
+        result.push(
+          `**Completion:** \`${sanitizeMarkdown(outlineSchema.completion)}\``
+        );
+        result.push("");
+      }
+
       const getPrompt = async () => {
         try {
           if (typeof outlineSchema.prompt === "string") {