flatagents 0.1.8__py3-none-any.whl

flatagents/assets/flatmachine.d.ts

@@ -0,0 +1,176 @@
+/**
+ * FlatMachine Configuration Schema v0.1.0
+ * =============================================
+ *
+ * A machine defines how agents are connected and executed:
+ * states, transitions, conditions, and loops.
+ *
+ * While flatagents defines WHAT each agent is (model + prompts + output schema),
+ * flatmachines defines HOW agents are connected and executed.
+ *
+ * STRUCTURE:
+ * ----------
+ * spec           - Fixed string "flatmachine"
+ * spec_version   - Semver string (e.g., "0.1.0")
+ * data           - The machine configuration
+ * metadata       - Extensibility layer
+ *
+ * DATA FIELDS:
+ * ------------
+ * name               - Machine identifier
+ * expression_engine  - "simple" (default) or "cel"
+ * context            - Initial context values (Jinja2 templates)
+ * agents             - Map of agent name to config file path or inline config
+ * states             - Map of state name to state definition
+ * settings           - Optional settings (hooks, etc.)
+ *
+ * STATE FIELDS:
+ * -------------
+ * type              - "initial" or "final" (optional)
+ * agent             - Agent name to execute (from agents map)
+ * execution         - Execution type config: {type: "retry", backoffs: [...], jitter: 0.1}
+ * on_error          - Error handling: "error_state" or {default: "...", ErrorType: "..."}
+ * action            - Hook action to execute
+ * input             - Input mapping (Jinja2 templates)
+ * output_to_context - Map agent output to context (Jinja2 templates)
+ * output            - Final output (for final states)
+ * transitions       - Ordered list of transitions
+ *
+ * TRANSITION FIELDS:
+ * ------------------
+ * condition         - Expression to evaluate (optional, default: always true)
+ * to                - Target state name
+ *
+ * EXPRESSION SYNTAX (Simple Mode):
+ * --------------------------------
+ * Comparisons: ==, !=, <, <=, >, >=
+ * Boolean: and, or, not
+ * Field access: context.field, input.field, output.field
+ * Literals: "string", 42, true, false, null
+ *
+ * Example: "context.score >= 8 and context.round < 4"
+ *
+ * EXPRESSION SYNTAX (CEL Mode):
+ * -----------------------------
+ * All simple syntax, plus:
+ * List macros: context.items.all(i, i > 0)
+ * String methods: context.name.startsWith("test")
+ * Timestamps: context.created > now - duration("24h")
+ *
+ * EXAMPLE CONFIGURATION:
+ * ----------------------
+ *
+ *   spec: flatmachine
+ *   spec_version: "0.1.0"
+ *
+ *   data:
+ *     name: writer-critic-loop
+ *
+ *     context:
+ *       product: "{{ input.product }}"
+ *       score: 0
+ *       round: 0
+ *
+ *     agents:
+ *       writer: ./writer.yml
+ *       critic: ./critic.yml
+ *
+ *     states:
+ *       start:
+ *         type: initial
+ *         transitions:
+ *           - to: write
+ *
+ *       write:
+ *         agent: writer
+ *         execution:
+ *           type: retry
+ *           backoffs: [2, 8, 16, 35]
+ *           jitter: 0.1
+ *         on_error: error_state
+ *         input:
+ *           product: "{{ context.product }}"
+ *         output_to_context:
+ *           tagline: "{{ output.tagline }}"
+ *         transitions:
+ *           - to: review
+ *
+ *       review:
+ *         agent: critic
+ *         input:
+ *           tagline: "{{ context.tagline }}"
+ *         output_to_context:
+ *           score: "{{ output.score }}"
+ *           round: "{{ context.round + 1 }}"
+ *         transitions:
+ *           - condition: "context.score >= 8"
+ *             to: done
+ *           - to: write
+ *
+ *       done:
+ *         type: final
+ *         output:
+ *           tagline: "{{ context.tagline }}"
+ *           score: "{{ context.score }}"
+ *
+ *   metadata:
+ *     description: "Iterative writer-critic loop"
+ */
+
+export interface MachineWrapper {
+  spec: "flatmachine";
+  spec_version: string;
+  data: MachineData;
+  metadata?: Record<string, any>;
+}
+
+export interface MachineData {
+  name?: string;
+  expression_engine?: "simple" | "cel";
+  context?: Record<string, any>;
+  agents?: Record<string, string | AgentWrapper>;
+  states: Record<string, StateDefinition>;
+  settings?: MachineSettings;
+}
+
+export interface MachineSettings {
+  hooks?: string;  // Python module path
+  max_steps?: number;
+  [key: string]: any;
+}
+
+export interface StateDefinition {
+  type?: "initial" | "final";
+  agent?: string;
+  action?: string;
+  execution?: ExecutionConfig;
+  on_error?: string | Record<string, string>;  // Simple: "error_state" or Granular: {default: "...", ErrorType: "..."}
+  input?: Record<string, any>;
+  output_to_context?: Record<string, string>;
+  output?: Record<string, any>;
+  transitions?: Transition[];
+  tool_loop?: boolean;
+  sampling?: "single" | "multi";
+}
+
+export interface ExecutionConfig {
+  type: "default" | "retry" | "parallel" | "mdap_voting";
+  // Retry config
+  backoffs?: number[];  // Delay array in seconds, e.g., [2, 8, 16, 35]
+  jitter?: number;      // Random variation factor, e.g., 0.1 for ±10%
+  // Parallel config
+  n_samples?: number;
+  // MDAP voting config
+  k_margin?: number;
+  max_candidates?: number;
+}
+
+export interface Transition {
+  condition?: string;
+  to: string;
+}
+
+import { AgentWrapper, OutputSchema, ModelConfig } from "./flatagent";
+export { AgentWrapper, OutputSchema };
+
+export type FlatmachineConfig = MachineWrapper;

flatagents/assets/flatmachine.schema.json

@@ -0,0 +1,405 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/MachineWrapper",
+  "definitions": {
+    "MachineWrapper": {
+      "type": "object",
+      "properties": {
+        "spec": {
+          "type": "string",
+          "const": "flatmachine"
+        },
+        "spec_version": {
+          "type": "string"
+        },
+        "data": {
+          "$ref": "#/definitions/MachineData"
+        },
+        "metadata": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "spec",
+        "spec_version",
+        "data"
+      ],
+      "additionalProperties": false,
+      "description": "FlatMachine Configuration Schema v0.1.0 =============================================\n\nA machine defines how agents are connected and executed: states, transitions, conditions, and loops.\n\nWhile flatagents defines WHAT each agent is (model + prompts + output schema), flatmachines defines HOW agents are connected and executed.\n\nSTRUCTURE:\n---------- spec           - Fixed string \"flatmachine\" spec_version   - Semver string (e.g., \"0.1.0\") data           - The machine configuration metadata       - Extensibility layer\n\nDATA FIELDS:\n------------ name               - Machine identifier expression_engine  - \"simple\" (default) or \"cel\" context            - Initial context values (Jinja2 templates) agents             - Map of agent name to config file path or inline config states             - Map of state name to state definition settings           - Optional settings (hooks, etc.)\n\nSTATE FIELDS:\n------------- type              - \"initial\" or \"final\" (optional) agent             - Agent name to execute (from agents map) execution         - Execution type config: {type: \"retry\", backoffs: [...], jitter: 0.1} on_error          - Error handling: \"error_state\" or {default: \"...\", ErrorType: \"...\"} action            - Hook action to execute input             - Input mapping (Jinja2 templates) output_to_context - Map agent output to context (Jinja2 templates) output            - Final output (for final states) transitions       - Ordered list of transitions\n\nTRANSITION FIELDS:\n------------------ condition         - Expression to evaluate (optional, default: always true) to                - Target state name\n\nEXPRESSION SYNTAX (Simple Mode):\n-------------------------------- Comparisons: ==, !=, <, <=, >, >= Boolean: and, or, not Field access: context.field, input.field, output.field Literals: \"string\", 42, true, false, null\n\nExample: \"context.score >= 8 and context.round < 4\"\n\nEXPRESSION SYNTAX (CEL Mode):\n----------------------------- All simple syntax, plus: List macros: context.items.all(i, i > 0) String methods: context.name.startsWith(\"test\") Timestamps: context.created > now - duration(\"24h\")\n\nEXAMPLE CONFIGURATION:\n----------------------\n\n  spec: flatmachine   spec_version: \"0.1.0\"\n\n  data:     name: writer-critic-loop\n\n    context:       product: \"{{ input.product }}\"       score: 0       round: 0\n\n    agents:       writer: ./writer.yml       critic: ./critic.yml\n\n    states:       start:         type: initial         transitions:           - to: write\n\n      write:         agent: writer         execution:           type: retry           backoffs: [2, 8, 16, 35]           jitter: 0.1         on_error: error_state         input:           product: \"{{ context.product }}\"         output_to_context:           tagline: \"{{ output.tagline }}\"         transitions:           - to: review\n\n      review:         agent: critic         input:           tagline: \"{{ context.tagline }}\"         output_to_context:           score: \"{{ output.score }}\"           round: \"{{ context.round + 1 }}\"         transitions:           - condition: \"context.score >= 8\"             to: done           - to: write\n\n      done:         type: final         output:           tagline: \"{{ context.tagline }}\"           score: \"{{ context.score }}\"\n\n  metadata:     description: \"Iterative writer-critic loop\""
+    },
+    "MachineData": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "expression_engine": {
+          "type": "string",
+          "enum": [
+            "simple",
+            "cel"
+          ]
+        },
+        "context": {
+          "type": "object"
+        },
+        "agents": {
+          "type": "object",
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "$ref": "#/definitions/AgentWrapper"
+              }
+            ]
+          }
+        },
+        "states": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/StateDefinition"
+          }
+        },
+        "settings": {
+          "$ref": "#/definitions/MachineSettings"
+        }
+      },
+      "required": [
+        "states"
+      ],
+      "additionalProperties": false
+    },
+    "AgentWrapper": {
+      "type": "object",
+      "properties": {
+        "spec": {
+          "type": "string",
+          "const": "flatagent"
+        },
+        "spec_version": {
+          "type": "string"
+        },
+        "data": {
+          "$ref": "#/definitions/AgentData"
+        },
+        "metadata": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "spec",
+        "spec_version",
+        "data"
+      ],
+      "additionalProperties": false,
+      "description": "FlatAgents Configuration Schema v0.6.0 =============================================\n\nAn agent is a single LLM call: model + prompts + output schema. Workflows handle composition, branching, and loops.\n\nSTRUCTURE:\n---------- spec           - Fixed string \"flatagents\" spec_version   - Semver string (e.g., \"0.1.0\") data           - The agent configuration metadata       - Extensibility layer (runners ignore unrecognized keys)\n\nDATA FIELDS:\n------------ name               - Agent identifier (inferred from filename if omitted) model              - LLM configuration system             - System prompt (Jinja2 template) user               - User prompt template (Jinja2) instruction_suffix - Optional instruction appended after user prompt output             - Output schema (what fields we want) mcp                - Optional MCP (Model Context Protocol) configuration\n\nMCP FIELDS:\n----------- servers            - Map of server name to MCPServerDef tool_filter        - Optional allow/deny lists using \"server:tool\" format tool_prompt        - Jinja2 template for tool prompt (uses {{ tools }} variable)\n\nMODEL FIELDS:\n------------- 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 frequency_penalty - Frequency penalty (-2.0 to 2.0) presence_penalty  - Presence penalty (-2.0 to 2.0)\n\nOUTPUT FIELD DEFINITION:\n------------------------ type        - Field type: str, int, float, bool, json, list, object description - Description (used for structured output / tool calls) enum        - Allowed values (for enum-like fields) required    - Whether the field is required (default: true) items       - For list type: the type of items properties  - For object type: nested properties\n\nTEMPLATE SYNTAX:\n---------------- Prompts use Jinja2 templating. Available variables:   - input.*  - Values passed to the agent at runtime\n\nExample: \"Question: {{ input.question }}\"\n\nEXAMPLE CONFIGURATION:\n----------------------\n\n  spec: flatagents    spec_version: \"0.6.0\"\n\n  data:     name: critic\n\n    model:       provider: cerebras       name: zai-glm-4.6       temperature: 0.5\n\n    system: |       Act as a ruthless critic. Analyze drafts for errors.       Rate severity as: High, Medium, or Low.\n\n    user: |       Question: {{ input.question }}       Draft: {{ input.draft }}\n\n    output:       critique:         type: str         description: \"Specific errors found in the draft\"       severity:         type: str         description: \"Error severity\"         enum: [\"High\", \"Medium\", \"Low\"]\n\n  metadata:     description: \"Critiques draft answers\"     tags: [\"reflection\", \"qa\"]\n\nMCPCONFIG:\n---------- MCP (Model Context Protocol) configuration. Defines MCP servers and tool filtering rules.   servers     - MCP server definitions, keyed by server name   tool_filter - Optional tool filtering rules   tool_prompt - Jinja2 template for tool prompt injection.                 Available variables: tools (list of discovered tools)                 Example: \"{% for tool in tools %}{{ tool.name }}: {{ tool.description }}{% endfor %}\"\n\nMCPSERVERDEF:\n------------- MCP server definition. Supports stdio transport (command) or HTTP transport (server_url). Stdio transport:   command - Command to start the MCP server (e.g., \"npx\", \"python\")   args    - Arguments for the command   env     - Environment variables for the server process HTTP transport:   server_url - Base URL of the MCP server (e.g., \"http://localhost:8000\")   headers    - HTTP headers (e.g., for authentication)   timeout    - Request timeout in seconds\n\nTOOLFILTER:\n----------- Tool filtering rules using \"server:tool\" format. Supports wildcards: \"server:*\" matches all tools from a server.   allow - Tools to allow (if specified, only these are included)   deny  - Tools to deny (takes precedence over allow)"
+    },
+    "AgentData": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "model": {
+          "$ref": "#/definitions/ModelConfig"
+        },
+        "system": {
+          "type": "string"
+        },
+        "user": {
+          "type": "string"
+        },
+        "instruction_suffix": {
+          "type": "string"
+        },
+        "output": {
+          "$ref": "#/definitions/OutputSchema"
+        },
+        "mcp": {
+          "$ref": "#/definitions/MCPConfig"
+        }
+      },
+      "required": [
+        "model",
+        "system",
+        "user"
+      ],
+      "additionalProperties": false
+    },
+    "ModelConfig": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "provider": {
+          "type": "string"
+        },
+        "temperature": {
+          "type": "number"
+        },
+        "max_tokens": {
+          "type": "number"
+        },
+        "top_p": {
+          "type": "number"
+        },
+        "frequency_penalty": {
+          "type": "number"
+        },
+        "presence_penalty": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    },
+    "OutputSchema": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/OutputFieldDef"
+      }
+    },
+    "OutputFieldDef": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "str",
+            "int",
+            "float",
+            "bool",
+            "json",
+            "list",
+            "object"
+          ]
+        },
+        "description": {
+          "type": "string"
+        },
+        "enum": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "items": {
+          "$ref": "#/definitions/OutputFieldDef"
+        },
+        "properties": {
+          "$ref": "#/definitions/OutputSchema"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false
+    },
+    "MCPConfig": {
+      "type": "object",
+      "properties": {
+        "servers": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/MCPServerDef"
+          }
+        },
+        "tool_filter": {
+          "$ref": "#/definitions/ToolFilter"
+        },
+        "tool_prompt": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "servers",
+        "tool_prompt"
+      ],
+      "additionalProperties": false
+    },
+    "MCPServerDef": {
+      "type": "object",
+      "properties": {
+        "command": {
+          "type": "string"
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "server_url": {
+          "type": "string"
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "timeout": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ToolFilter": {
+      "type": "object",
+      "properties": {
+        "allow": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "deny": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "StateDefinition": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "initial",
+            "final"
+          ]
+        },
+        "agent": {
+          "type": "string"
+        },
+        "action": {
+          "type": "string"
+        },
+        "execution": {
+          "$ref": "#/definitions/ExecutionConfig"
+        },
+        "on_error": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "input": {
+          "type": "object"
+        },
+        "output_to_context": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "output": {
+          "type": "object"
+        },
+        "transitions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Transition"
+          }
+        },
+        "tool_loop": {
+          "type": "boolean"
+        },
+        "sampling": {
+          "type": "string",
+          "enum": [
+            "single",
+            "multi"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "ExecutionConfig": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "default",
+            "retry",
+            "parallel",
+            "mdap_voting"
+          ]
+        },
+        "backoffs": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          }
+        },
+        "jitter": {
+          "type": "number"
+        },
+        "n_samples": {
+          "type": "number"
+        },
+        "k_margin": {
+          "type": "number"
+        },
+        "max_candidates": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false
+    },
+    "Transition": {
+      "type": "object",
+      "properties": {
+        "condition": {
+          "type": "string"
+        },
+        "to": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "to"
+      ],
+      "additionalProperties": false
+    },
+    "MachineSettings": {
+      "type": "object",
+      "properties": {
+        "hooks": {
+          "type": "string"
+        },
+        "max_steps": {
+          "type": "number"
+        }
+      }
+    }
+  }
+}

flatagents/assets/flatmachine.slim.d.ts

@@ -0,0 +1,47 @@
+export interface MachineWrapper {
+    spec: "flatmachine";
+    spec_version: string;
+    data: MachineData;
+    metadata?: Record<string, any>;
+}
+export interface MachineData {
+    name?: string;
+    expression_engine?: "simple" | "cel";
+    context?: Record<string, any>;
+    agents?: Record<string, string | AgentWrapper>;
+    states: Record<string, StateDefinition>;
+    settings?: MachineSettings;
+}
+export interface MachineSettings {
+    hooks?: string;
+    max_steps?: number;
+    [key: string]: any;
+}
+export interface StateDefinition {
+    type?: "initial" | "final";
+    agent?: string;
+    action?: string;
+    execution?: ExecutionConfig;
+    on_error?: string | Record<string, string>;
+    input?: Record<string, any>;
+    output_to_context?: Record<string, string>;
+    output?: Record<string, any>;
+    transitions?: Transition[];
+    tool_loop?: boolean;
+    sampling?: "single" | "multi";
+}
+export interface ExecutionConfig {
+    type: "default" | "retry" | "parallel" | "mdap_voting";
+    backoffs?: number[];
+    jitter?: number;
+    n_samples?: number;
+    k_margin?: number;
+    max_candidates?: number;
+}
+export interface Transition {
+    condition?: string;
+    to: string;
+}
+import { AgentWrapper, OutputSchema, ModelConfig } from "./flatagent";
+export { AgentWrapper, OutputSchema };
+export type FlatmachineConfig = MachineWrapper;