Add tool calling and API format support to flatagents

assets/flatagent.d.ts

@@ -36,16 +36,32 @@
  *
  * MODEL FIELDS:
  * -------------
- * name              - Model name (e.g., "gpt-4", "zai-glm-4.6")
- * provider          - Provider name (e.g., "openai", "anthropic", "cerebras")
- * temperature       - Sampling temperature (0.0 to 2.0)
- * max_tokens        - Maximum tokens to generate
- * top_p             - Nucleus sampling parameter
- * top_k             - Top-k sampling parameter
- * frequency_penalty - Frequency penalty (-2.0 to 2.0)
- * presence_penalty  - Presence penalty (-2.0 to 2.0)
- * seed              - Random seed for reproducibility
- * base_url          - Custom API base URL (for local models/proxies)
+ * name               - Model name (e.g., "gpt-4", "zai-glm-4.6")
+ * provider           - Provider name (e.g., "openai", "anthropic", "cerebras")
+ * temperature        - Sampling temperature (0.0 to 2.0)
+ * max_tokens         - Maximum tokens to generate
+ * top_p              - Nucleus sampling parameter
+ * top_k              - Top-k sampling parameter
+ * frequency_penalty  - Frequency penalty (-2.0 to 2.0)
+ * presence_penalty   - Presence penalty (-2.0 to 2.0)
+ * repetition_penalty - Alternative repetition penalty (some providers)
+ * seed               - Random seed for reproducibility
+ * base_url           - Custom API base URL (for local models/proxies)
+ * stop               - Stop sequence(s) to end generation
+ * logit_bias         - Token bias map (token_id -> bias value)
+ *
+ * TOOL CALLING FIELDS:
+ * --------------------
+ * tools              - Array of tool definitions for function calling
+ * tool_choice        - Control tool usage: "none", "auto", "required", or specific tool
+ * parallel_tool_calls - Allow multiple tool calls in single response (default: true)
+ *
+ * RESPONSE FORMAT FIELDS:
+ * -----------------------
+ * response_format    - Control output format:
+ *   - { type: "text" }         - Plain text output (default)
+ *   - { type: "json_object" }  - Valid JSON output
+ *   - { type: "json_schema", json_schema: {...} } - Structured output with schema
  *
  * MODEL PROFILES:
  * ---------------
@@ -197,8 +213,45 @@ export interface ModelConfig {
   top_k?: number;
   frequency_penalty?: number;
   presence_penalty?: number;
+  repetition_penalty?: number;
   seed?: number;
   base_url?: string;
+  stop?: string | string[];
+  logit_bias?: Record<string, number>;
+  tools?: ToolDefinition[];
+  tool_choice?: ToolChoice;
+  parallel_tool_calls?: boolean;
+  response_format?: ResponseFormat;
+}
+
+export type ToolChoice =
+  | "none"
+  | "auto"
+  | "required"
+  | { type: "function"; function: { name: string } };
+
+export type ResponseFormat =
+  | { type: "text" }
+  | { type: "json_object" }
+  | { type: "json_schema"; json_schema: JsonSchemaResponseFormat };
+
+export interface JsonSchemaResponseFormat {
+  name: string;
+  description?: string;
+  schema: Record<string, any>;
+  strict?: boolean;
+}
+
+export interface ToolDefinition {
+  type: "function";
+  function: ToolFunction;
+}
+
+export interface ToolFunction {
+  name: string;
+  description?: string;
+  parameters?: Record<string, any>;
+  strict?: boolean;
 }
 
 export interface ProfiledModelConfig extends Partial<ModelConfig> {

assets/flatagents-runtime.d.ts

@@ -225,6 +225,17 @@ export interface MachineHooks {
 
     /** Called for custom actions defined in state config. */
     onAction?(action: string, context: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
+
+    /**
+     * Called when an agent requests a tool call during tool_loop execution.
+     * Must return the tool result which will be sent back to the agent.
+     *
+     * @param toolName - Name of the tool to execute
+     * @param arguments - Arguments passed to the tool (parsed from JSON)
+     * @param context - Current machine context
+     * @returns Tool execution result (will be JSON serialized for the agent)
+     */
+    onToolCall?(toolName: string, arguments: Record<string, any>, context: Record<string, any>): any | Promise<any>;
 }
 
 export interface LLMBackend {
@@ -260,17 +271,48 @@ export interface ToolCall {
 export interface LLMOptions {
     temperature?: number;
     max_tokens?: number;
+    top_p?: number;
+    top_k?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    repetition_penalty?: number;
+    seed?: number;
+    stop?: string | string[];
+    logit_bias?: Record<string, number>;
     tools?: ToolDefinition[];
-    response_format?: { type: "json_object" } | { type: "text" };
+    tool_choice?: ToolChoice;
+    parallel_tool_calls?: boolean;
+    response_format?: ResponseFormat;
+}
+
+export type ToolChoice =
+    | "none"
+    | "auto"
+    | "required"
+    | { type: "function"; function: { name: string } };
+
+export type ResponseFormat =
+    | { type: "text" }
+    | { type: "json_object" }
+    | { type: "json_schema"; json_schema: JsonSchemaResponseFormat };
+
+export interface JsonSchemaResponseFormat {
+    name: string;
+    description?: string;
+    schema: Record<string, any>;
+    strict?: boolean;
 }
 
 export interface ToolDefinition {
     type: "function";
-    function: {
-        name: string;
-        description?: string;
-        parameters?: Record<string, any>;  // JSON Schema
-    };
+    function: ToolFunction;
+}
+
+export interface ToolFunction {
+    name: string;
+    description?: string;
+    parameters?: Record<string, any>;  // JSON Schema
+    strict?: boolean;  // For strict structured outputs
 }
 
 export interface MachineInvoker {

assets/flatmachine.d.ts

@@ -43,6 +43,9 @@
  * output_to_context - Map agent output to context (Jinja2 templates)
  * output            - Final output (for final states)
  * transitions       - Ordered list of transitions
+ * tool_loop         - Enable multi-round tool calling (boolean or ToolLoopConfig)
+ * tools             - Tool definitions for this state (OpenAI function format)
+ * tool_choice       - Control tool usage: "none", "auto", "required", or specific
  *
  * PARALLEL EXECUTION (v0.4.0):
  * ----------------------------
@@ -203,6 +206,45 @@
  *       transitions:
  *         - to: continue_immediately
  *
+ * TOOL LOOP EXAMPLE:
+ * ------------------
+ * Multi-round tool calling allows an agent to call tools repeatedly until
+ * it has enough information to produce a final response.
+ *
+ *   states:
+ *     research:
+ *       agent: researcher
+ *       tool_loop:
+ *         max_rounds: 10
+ *       tools:
+ *         - type: function
+ *           function:
+ *             name: search_web
+ *             description: Search the web for information
+ *             parameters:
+ *               type: object
+ *               properties:
+ *                 query: { type: string, description: "Search query" }
+ *               required: [query]
+ *         - type: function
+ *           function:
+ *             name: read_url
+ *             description: Read content from a URL
+ *             parameters:
+ *               type: object
+ *               properties:
+ *                 url: { type: string, description: "URL to read" }
+ *               required: [url]
+ *       input:
+ *         question: "{{ context.question }}"
+ *       output_to_context:
+ *         answer: "{{ output.answer }}"
+ *       transitions:
+ *         - to: done
+ *
+ * The machine will call hooks.on_tool_call(tool_name, arguments) for each
+ * tool call. Hooks must implement this method to execute tools and return results.
+ *
  * PERSISTENCE (v0.2.0):
  * --------------------
  * MachineSnapshot    - Wire format for checkpoints (execution_id, state, context, step)
@@ -324,7 +366,9 @@ export interface StateDefinition {
   output_to_context?: Record<string, any>;
   output?: Record<string, any>;
   transitions?: Transition[];
-  tool_loop?: boolean;
+  tool_loop?: boolean | ToolLoopConfig;
+  tools?: ToolDefinition[];
+  tool_choice?: ToolChoice;
   sampling?: "single" | "multi";
   foreach?: string;
   as?: string;
@@ -335,6 +379,62 @@ export interface StateDefinition {
   launch_input?: Record<string, any>;
 }
 
+/**
+ * Configuration for multi-round tool calling loops.
+ *
+ * When tool_loop is enabled on a state with an agent, the machine will:
+ * 1. Call the agent with available tools
+ * 2. If the agent returns tool calls, execute them
+ * 3. Send tool results back to the agent
+ * 4. Repeat until agent returns final response (no tool calls) or max_rounds reached
+ *
+ * Example:
+ *   states:
+ *     process:
+ *       agent: assistant
+ *       tool_loop:
+ *         max_rounds: 10
+ *         tools:
+ *           - type: function
+ *             function:
+ *               name: search
+ *               description: Search the knowledge base
+ *               parameters:
+ *                 type: object
+ *                 properties:
+ *                   query: { type: string }
+ *       input:
+ *         question: "{{ context.question }}"
+ */
+export interface ToolLoopConfig {
+  /** Maximum number of tool call rounds (default: 10) */
+  max_rounds?: number;
+  /** Tool definitions (OpenAI function calling format) */
+  tools?: ToolDefinition[];
+  /** Control tool usage: "none", "auto", "required", or specific tool */
+  tool_choice?: ToolChoice;
+  /** Allow parallel tool calls in single response (default: true) */
+  parallel_tool_calls?: boolean;
+}
+
+export type ToolChoice =
+  | "none"
+  | "auto"
+  | "required"
+  | { type: "function"; function: { name: string } };
+
+export interface ToolDefinition {
+  type: "function";
+  function: ToolFunction;
+}
+
+export interface ToolFunction {
+  name: string;
+  description?: string;
+  parameters?: Record<string, any>;
+  strict?: boolean;
+}
+
 export interface MachineInput {
   name: string;
   input?: Record<string, any>;

assets/profiles.d.ts

@@ -95,16 +95,19 @@
  * MODELPROFILECONFIG FIELDS:
  * --------------------------
  * Defines all parameters for an LLM model.
- * name              - Model name (e.g., "gpt-4", "zai-glm-4.6", "claude-3-opus-20240229")
- * provider          - Provider name (e.g., "openai", "anthropic", "cerebras", "ollama")
- * temperature       - Sampling temperature (0.0 to 2.0)
- * max_tokens        - Maximum tokens to generate
- * top_p             - Nucleus sampling parameter (0.0 to 1.0)
- * top_k             - Top-k sampling parameter
- * frequency_penalty - Frequency penalty (-2.0 to 2.0)
- * presence_penalty  - Presence penalty (-2.0 to 2.0)
- * seed              - Random seed for reproducibility
- * base_url          - Custom base URL for the API (e.g., for local models or proxies)
+ * name               - Model name (e.g., "gpt-4", "zai-glm-4.6", "claude-3-opus-20240229")
+ * provider           - Provider name (e.g., "openai", "anthropic", "cerebras", "ollama")
+ * temperature        - Sampling temperature (0.0 to 2.0)
+ * max_tokens         - Maximum tokens to generate
+ * top_p              - Nucleus sampling parameter (0.0 to 1.0)
+ * top_k              - Top-k sampling parameter
+ * frequency_penalty  - Frequency penalty (-2.0 to 2.0)
+ * presence_penalty   - Presence penalty (-2.0 to 2.0)
+ * repetition_penalty - Alternative repetition penalty (some providers)
+ * seed               - Random seed for reproducibility
+ * base_url           - Custom base URL for the API (e.g., for local models or proxies)
+ * stop               - Stop sequence(s) to end generation
+ * logit_bias         - Token bias map (token_id -> bias value)
  */
 
 export const SPEC_VERSION = "0.9.0";
@@ -131,8 +134,11 @@ export interface ModelProfileConfig {
   top_k?: number;
   frequency_penalty?: number;
   presence_penalty?: number;
+  repetition_penalty?: number;
   seed?: number;
   base_url?: string;
+  stop?: string | string[];
+  logit_bias?: Record<string, number>;
 }
 
 export type FlatprofilesConfig = ProfilesWrapper;