flatagents 0.4.1__py3-none-any.whl

flatagents/__init__.py

@@ -0,0 +1,136 @@
+__version__ = "0.4.1"
+
+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,
+)
+from .monitoring import (
+    setup_logging,
+    get_logger,
+    get_meter,
+    AgentMonitor,
+    track_operation,
+)
+from .backends import (
+    ResultBackend,
+    InMemoryResultBackend,
+    LaunchIntent,
+    make_uri,
+    parse_uri,
+    get_default_result_backend,
+    reset_default_result_backend,
+)
+from .persistence import (
+    PersistenceBackend,
+    LocalFileBackend,
+    MemoryBackend,
+    CheckpointManager,
+    MachineSnapshot,
+)
+
+__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",
+    # Monitoring & Observability
+    "setup_logging",
+    "get_logger",
+    "get_meter",
+    "AgentMonitor",
+    "track_operation",
+    # Result Backends (v0.4.0)
+    "ResultBackend",
+    "InMemoryResultBackend",
+    "LaunchIntent",
+    "make_uri",
+    "parse_uri",
+    "get_default_result_backend",
+    "reset_default_result_backend",
+    # Persistence Backends
+    "PersistenceBackend",
+    "LocalFileBackend",
+    "MemoryBackend",
+    "CheckpointManager",
+    "MachineSnapshot",
+]

flatagents/actions.py

@@ -0,0 +1,239 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, TYPE_CHECKING
+import logging
+
+if TYPE_CHECKING:
+    from .flatmachine import FlatMachine
+
+logger = logging.getLogger(__name__)
+
+class Action(ABC):
+    """
+    Base class for state actions (when state has 'action:' key).
+    """
+    
+    @abstractmethod
+    async def execute(
+        self,
+        action_name: str,
+        context: Dict[str, Any],
+        config: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Execute the action.
+        Returns modified context.
+        """
+        pass
+
+class HookAction(Action):
+    """
+    Default action: delegates to machine hooks (on_action).
+    """
+    
+    def __init__(self, hooks):
+        self.hooks = hooks
+        
+    async def execute(
+        self,
+        action_name: str,
+        context: Dict[str, Any],
+        config: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        return self.hooks.on_action(action_name, context)
+
+# -------------------------------------------------------------------------
+# Machine Invokers (Graph Execution)
+# -------------------------------------------------------------------------
+
+class MachineInvoker(ABC):
+    """
+    Interface for invoking other machines (graph execution).
+    
+    See flatagents-runtime.d.ts for canonical interface definition.
+    """
+    
+    @abstractmethod
+    async def invoke(
+        self,
+        caller_machine: 'FlatMachine',
+        target_config: Dict[str, Any],
+        input_data: Dict[str, Any],
+        execution_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Invoke another machine and wait for result.
+        
+        Args:
+            caller_machine: The machine initiating the call
+            target_config: Config dict for the target machine
+            input_data: Input to pass to the target machine
+            execution_id: Optional predetermined ID (for resume support)
+        
+        Returns:
+            The target machine's output
+        """
+        pass
+    
+    @abstractmethod
+    async def launch(
+        self,
+        caller_machine: 'FlatMachine',
+        target_config: Dict[str, Any],
+        input_data: Dict[str, Any],
+        execution_id: str
+    ) -> None:
+        """
+        Launch a machine fire-and-forget style.
+        
+        The launched machine runs independently. Results are written
+        to the result backend using the execution_id.
+        
+        Args:
+            caller_machine: The machine initiating the launch
+            target_config: Config dict for the target machine
+            input_data: Input to pass to the target machine
+            execution_id: The predetermined execution ID for the launched machine
+        """
+        pass
+
+class InlineInvoker(MachineInvoker):
+    """
+    Default Invoker for local execution.
+    
+    - invoke(): Runs target machine in same event loop, awaits result
+    - launch(): Creates background task, returns immediately
+    
+    Both share the same persistence/lock backends as the caller.
+    """
+    
+    def __init__(self):
+        # Track background tasks for cleanup
+        self._background_tasks: set = set()
+    
+    async def invoke(
+        self,
+        caller_machine: 'FlatMachine',
+        target_config: Dict[str, Any],
+        input_data: Dict[str, Any],
+        execution_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        from .flatmachine import FlatMachine  # lazy import to avoid cycle
+        import hashlib
+        
+        target_name = target_config.get('data', {}).get('name', 'unknown')
+        
+        # Generate execution_id if not provided
+        if not execution_id:
+            context_hash = hashlib.md5(str(sorted(input_data.items())).encode()).hexdigest()[:8]
+            execution_id = f"{caller_machine.execution_id}:peer:{target_name}:{context_hash}"
+
+        logger.info(f"Invoking peer machine: {target_name} (ID: {execution_id})")
+        
+        target = FlatMachine(
+            config_dict=target_config,
+            persistence=caller_machine.persistence,
+            lock=caller_machine.lock,
+            result_backend=caller_machine.result_backend,
+            _config_dir=caller_machine._config_dir,
+            _execution_id=execution_id,
+            _parent_execution_id=caller_machine.execution_id,
+        )
+        
+        result = await target.execute(input=input_data, resume_from=execution_id)
+        
+        # Aggregate stats back to caller
+        caller_machine.total_api_calls += target.total_api_calls
+        caller_machine.total_cost += target.total_cost
+        
+        return result
+    
+    async def launch(
+        self,
+        caller_machine: 'FlatMachine',
+        target_config: Dict[str, Any],
+        input_data: Dict[str, Any],
+        execution_id: str
+    ) -> None:
+        import asyncio
+        from .flatmachine import FlatMachine
+        from .backends import make_uri
+        
+        target_name = target_config.get('data', {}).get('name', 'unknown')
+        logger.info(f"Launching peer machine (fire-and-forget): {target_name} (ID: {execution_id})")
+        
+        async def _execute_and_write():
+            target = FlatMachine(
+                config_dict=target_config,
+                persistence=caller_machine.persistence,
+                lock=caller_machine.lock,
+                result_backend=caller_machine.result_backend,
+                _config_dir=caller_machine._config_dir,
+                _execution_id=execution_id,
+                _parent_execution_id=caller_machine.execution_id,
+            )
+            
+            try:
+                result = await target.execute(input=input_data)
+                # Write result to backend so parent can read if needed
+                uri = make_uri(execution_id, "result")
+                await caller_machine.result_backend.write(uri, result)
+            except Exception as e:
+                uri = make_uri(execution_id, "result")
+                await caller_machine.result_backend.write(uri, {
+                    "_error": str(e),
+                    "_error_type": type(e).__name__
+                })
+                raise
+        
+        # Create background task
+        task = asyncio.create_task(_execute_and_write())
+        caller_machine._background_tasks.add(task)
+        task.add_done_callback(caller_machine._background_tasks.discard)
+
+
+class QueueInvoker(MachineInvoker):
+    """
+    Invoker that enqueues launches to an external queue.
+    
+    For production deployments using SQS, Cloud Tasks, etc.
+    Subclass and implement _enqueue() for your queue provider.
+    """
+    
+    async def invoke(
+        self,
+        caller_machine: 'FlatMachine',
+        target_config: Dict[str, Any],
+        input_data: Dict[str, Any],
+        execution_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        # For queue-based invocation, we launch and then poll for result
+        import uuid
+        from .backends import make_uri
+        
+        if not execution_id:
+            execution_id = str(uuid.uuid4())
+        
+        await self.launch(caller_machine, target_config, input_data, execution_id)
+        
+        # Block until result is available
+        uri = make_uri(execution_id, "result")
+        return await caller_machine.result_backend.read(uri, block=True)
+    
+    async def launch(
+        self,
+        caller_machine: 'FlatMachine',
+        target_config: Dict[str, Any],
+        input_data: Dict[str, Any],
+        execution_id: str
+    ) -> None:
+        await self._enqueue(execution_id, target_config, input_data)
+    
+    async def _enqueue(
+        self,
+        execution_id: str,
+        config: Dict[str, Any],
+        input_data: Dict[str, Any]
+    ) -> None:
+        """Override in subclass to enqueue to your queue provider."""
+        raise NotImplementedError("Subclass must implement _enqueue()")
+

flatagents/assets/flatagent.d.ts

@@ -0,0 +1,189 @@
+/**
+ * FlatAgents Configuration Schema
+ * ===============================
+ *
+ * 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
+ * data           - The agent configuration
+ * metadata       - Extensibility layer (runners ignore unrecognized keys)
+ *
+ * DERIVED SCHEMAS:
+ * ----------------
+ * This file (/flatagent.d.ts) is the SOURCE OF TRUTH for all FlatAgent schemas.
+ * Other schemas (JSON Schema, etc.) are DERIVED from this file using scripts.
+ * See: /scripts/generate-spec-assets.ts
+ *
+ * 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.0.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 const SPEC_VERSION = "0.6.0";
+
+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;