flatagents 0.1.8__py3-none-any.whl

flatagents/__init__.py

@@ -0,0 +1,93 @@
+__version__ = "0.1.5"
+
+from .baseagent import (
+    # Base agent (abstract, for multi-step agents)
+    FlatAgent as BaseFlatAgent,
+    # LLM Backends
+    LLMBackend,
+    LiteLLMBackend,
+    AISuiteBackend,
+    # Extractors
+    Extractor,
+    FreeExtractor,
+    FreeThinkingExtractor,
+    StructuredExtractor,
+    ToolsExtractor,
+    RegexExtractor,
+    # MCP Types
+    MCPToolProvider,
+    ToolCall,
+    AgentResponse,
+)
+from .flatagent import FlatAgent
+from .flatmachine import FlatMachine
+from .hooks import (
+    MachineHooks,
+    LoggingHooks,
+    MetricsHooks,
+    CompositeHooks,
+)
+from .expressions import get_expression_engine, ExpressionEngine
+from .execution import (
+    ExecutionType,
+    DefaultExecution,
+    ParallelExecution,
+    RetryExecution,
+    MDAPVotingExecution,
+    get_execution_type,
+)
+from .validation import (
+    validate_flatagent_config,
+    validate_flatmachine_config,
+    get_flatagent_schema,
+    get_flatmachine_schema,
+    get_asset,
+    ValidationWarning,
+)
+
+__all__ = [
+    "__version__",
+    # Main agent class
+    "FlatAgent",
+    # Base agent for custom multi-step agents
+    "BaseFlatAgent",
+    # State machine orchestration
+    "FlatMachine",
+    # Machine hooks
+    "MachineHooks",
+    "LoggingHooks",
+    "MetricsHooks",
+    "CompositeHooks",
+    # Expression engines
+    "ExpressionEngine",
+    "get_expression_engine",
+    # Execution types
+    "ExecutionType",
+    "DefaultExecution",
+    "ParallelExecution",
+    "RetryExecution",
+    "MDAPVotingExecution",
+    "get_execution_type",
+    # LLM Backends
+    "LLMBackend",
+    "LiteLLMBackend",
+    "AISuiteBackend",
+    # Extractors
+    "Extractor",
+    "FreeExtractor",
+    "FreeThinkingExtractor",
+    "StructuredExtractor",
+    "ToolsExtractor",
+    "RegexExtractor",
+    # MCP Types
+    "MCPToolProvider",
+    "ToolCall",
+    "AgentResponse",
+    # Validation
+    "validate_flatagent_config",
+    "validate_flatmachine_config",
+    "get_flatagent_schema",
+    "get_flatmachine_schema",
+    "get_asset",
+    "ValidationWarning",
+]

flatagents/assets/flatagent.d.ts

@@ -0,0 +1,181 @@
+/**
+ * FlatAgents Configuration Schema v0.6.0
+ * =============================================
+ *
+ * An agent is a single LLM call: model + prompts + output schema.
+ * Workflows handle composition, branching, and loops.
+ *
+ * STRUCTURE:
+ * ----------
+ * spec           - Fixed string "flatagents"
+ * spec_version   - Semver string (e.g., "0.1.0")
+ * data           - The agent configuration
+ * metadata       - Extensibility layer (runners ignore unrecognized keys)
+ *
+ * DATA FIELDS:
+ * ------------
+ * 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
+ *
+ * MCP FIELDS:
+ * -----------
+ * 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)
+ *
+ * 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
+ * frequency_penalty - Frequency penalty (-2.0 to 2.0)
+ * presence_penalty  - Presence penalty (-2.0 to 2.0)
+ *
+ * OUTPUT FIELD DEFINITION:
+ * ------------------------
+ * 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
+ *
+ * TEMPLATE SYNTAX:
+ * ----------------
+ * Prompts use Jinja2 templating. Available variables:
+ *   - input.*  - Values passed to the agent at runtime
+ *
+ * Example: "Question: {{ input.question }}"
+ *
+ * EXAMPLE CONFIGURATION:
+ * ----------------------
+ *
+ *   spec: flatagents 
+ *   spec_version: "0.6.0"
+ *
+ *   data:
+ *     name: critic
+ *
+ *     model:
+ *       provider: cerebras
+ *       name: zai-glm-4.6
+ *       temperature: 0.5
+ *
+ *     system: |
+ *       Act as a ruthless critic. Analyze drafts for errors.
+ *       Rate severity as: High, Medium, or Low.
+ *
+ *     user: |
+ *       Question: {{ input.question }}
+ *       Draft: {{ input.draft }}
+ *
+ *     output:
+ *       critique:
+ *         type: str
+ *         description: "Specific errors found in the draft"
+ *       severity:
+ *         type: str
+ *         description: "Error severity"
+ *         enum: ["High", "Medium", "Low"]
+ *
+ *   metadata:
+ *     description: "Critiques draft answers"
+ *     tags: ["reflection", "qa"]
+ *
+ * MCPCONFIG:
+ * ----------
+ * 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 %}"
+ *
+ * MCPSERVERDEF:
+ * -------------
+ * 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
+ *
+ * TOOLFILTER:
+ * -----------
+ * 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)
+ */
+
+export interface AgentWrapper {
+  spec: "flatagent";
+  spec_version: string;
+  data: AgentData;
+  metadata?: Record<string, any>;
+}
+
+export interface AgentData {
+  name?: string;
+  model: ModelConfig;
+  system: string;
+  user: string;
+  instruction_suffix?: string;
+  output?: OutputSchema;
+  mcp?: MCPConfig;
+}
+
+export interface MCPConfig {
+  servers: Record<string, MCPServerDef>;
+  tool_filter?: ToolFilter;
+  tool_prompt: string;
+}
+
+export interface MCPServerDef {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  server_url?: string;
+  headers?: Record<string, string>;
+  timeout?: number;
+}
+
+export interface ToolFilter {
+  allow?: string[];
+  deny?: string[];
+}
+
+export interface ModelConfig {
+  name: string;
+  provider?: string;
+  temperature?: number;
+  max_tokens?: number;
+  top_p?: number;
+  frequency_penalty?: number;
+  presence_penalty?: number;
+}
+
+export type OutputSchema = Record<string, OutputFieldDef>;
+
+export interface OutputFieldDef {
+  type: "str" | "int" | "float" | "bool" | "json" | "list" | "object";
+  description?: string;
+  enum?: string[];
+  required?: boolean;
+  items?: OutputFieldDef;
+  properties?: OutputSchema;
+}
+
+export type FlatagentsConfig = AgentWrapper;

flatagents/assets/flatagent.schema.json

@@ -0,0 +1,211 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/AgentWrapper",
+  "definitions": {
+    "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
+    }
+  }
+}

flatagents/assets/flatagent.slim.d.ts

@@ -0,0 +1,51 @@
+export interface AgentWrapper {
+    spec: "flatagent";
+    spec_version: string;
+    data: AgentData;
+    metadata?: Record<string, any>;
+}
+export interface AgentData {
+    name?: string;
+    model: ModelConfig;
+    system: string;
+    user: string;
+    instruction_suffix?: string;
+    output?: OutputSchema;
+    mcp?: MCPConfig;
+}
+export interface MCPConfig {
+    servers: Record<string, MCPServerDef>;
+    tool_filter?: ToolFilter;
+    tool_prompt: string;
+}
+export interface MCPServerDef {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    server_url?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+export interface ToolFilter {
+    allow?: string[];
+    deny?: string[];
+}
+export interface ModelConfig {
+    name: string;
+    provider?: string;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+}
+export type OutputSchema = Record<string, OutputFieldDef>;
+export interface OutputFieldDef {
+    type: "str" | "int" | "float" | "bool" | "json" | "list" | "object";
+    description?: string;
+    enum?: string[];
+    required?: boolean;
+    items?: OutputFieldDef;
+    properties?: OutputSchema;
+}
+export type FlatagentsConfig = AgentWrapper;