flock-core 0.3.17__tar.gz → 0.3.18__tar.gz

flock_core-0.3.18/.cursor/specs/01_core_architecture.md

@@ -0,0 +1,135 @@
+# Flock Core Architecture Specification
+
+## Overview
+Flock is a framework for building, orchestrating, and running AI agent systems. It provides a declarative approach to agent design, focusing on inputs and outputs rather than prompts. This specification defines the core architecture components of the Flock framework.
+
+## Components
+
+### 1. Flock
+
+The central orchestrator that manages agents, tools, and execution flow.
+
+**Responsibilities:**
+- Managing agent registration and retrieval
+- Orchestrating workflow execution
+- Providing execution context
+- Supporting local and distributed execution modes (Temporal)
+- Initializing and managing logging
+
+**Key Attributes:**
+- `agents`: Collection of registered agents
+- `registry`: Central registry for agents and tools
+- `context`: Global execution context
+- `model`: Default LLM model identifier
+- `enable_temporal`: Flag for distributed execution
+
+### 2. FlockAgent
+
+The core agent class that defines a single AI agent's capabilities.
+
+**Responsibilities:**
+- Defining agent inputs and outputs
+- Managing agent lifecycle
+- Providing access to tools
+- Supporting serialization and deserialization
+- Integrating with modules for extensibility
+
+**Key Attributes:**
+- `name`: Unique identifier
+- `description`: Human-readable agent description
+- `model`: LLM model identifier
+- `input`: Input field definitions
+- `output`: Output field definitions
+- `tools`: Available tools for the agent
+- `evaluator`: Strategy for evaluation
+- `modules`: Attached modules for extensibility
+- `handoff_router`: Optional router for multi-agent workflows
+
+### 3. FlockModule
+
+Extension system for agents to modify behavior through lifecycle hooks.
+
+**Responsibilities:**
+- Hooking into agent lifecycle events
+- Modifying inputs or outputs
+- Adding capabilities to agents
+- Maintaining module-specific state
+
+**Lifecycle Hooks:**
+- `initialize`: Called when agent starts
+- `pre_evaluate`: Called before evaluation
+- `post_evaluate`: Called after evaluation
+- `terminate`: Called when agent finishes
+- `on_error`: Called when errors occur
+
+### 4. FlockEvaluator
+
+Strategy for evaluating agent requests and generating outputs.
+
+**Responsibilities:**
+- Processing agent inputs
+- Formulating appropriate prompts
+- Managing model interactions
+- Processing model outputs
+- Handling tool usage
+
+### 5. FlockRouter
+
+Mechanism for directing workflow between agents.
+
+**Responsibilities:**
+- Determining the next agent in a workflow
+- Managing input/output mapping between agents
+- Supporting workflow branching logic
+
+**Key Concepts:**
+- `HandOffRequest`: Definition of the next agent and input mapping
+
+### 6. FlockContext
+
+Shared execution context for agents and modules.
+
+**Responsibilities:**
+- Storing global state across agents
+- Providing access to agent definitions
+- Supporting serialization for distributed execution
+
+## Design Principles
+
+1. **Declarative over Imperative**:
+   - Focus on what agents do, not how they do it
+   - Define inputs and outputs clearly
+   - Minimize prompt engineering
+
+2. **Modular Extension**:
+   - Module system for adding functionality
+   - Clear lifecycle hooks
+   - Separation of concerns
+
+3. **Resilient Execution**:
+   - Support for local and distributed execution
+   - Error handling at each level
+   - Observability through logging and tracing
+
+4. **Serialization Support**:
+   - All components can be serialized
+   - Support for saving and loading agent definitions
+   - State preservation across execution environments
+
+5. **Tool Integration**:
+   - First-class support for tool usage
+   - Flexible tool registration
+   - Dynamic tool discovery
+
+## Execution Flow
+
+1. User creates a Flock instance
+2. User adds agents to the Flock
+3. User registers tools if needed
+4. User calls `run()` with a starting agent and input
+5. Flock initializes context and resolves the starting agent
+6. Agent initializes and resolves modules
+7. Agent evaluates input using its evaluator
+8. If a router is defined, Flock determines the next agent
+9. Process repeats until no next agent is specified
+10. Final result is returned 

flock_core-0.3.18/.cursor/specs/02_agent_factory.md

@@ -0,0 +1,78 @@
+# Flock Agent Factory Specification
+
+## Overview
+The Factory design pattern is implemented in Flock to simplify agent creation with sensible defaults. This specification defines the requirements and behavior of the agent factory system.
+
+## FlockFactory
+
+### Purpose
+Provide a simplified interface for creating pre-configured agents without requiring manual setup of all components.
+
+### Responsibilities
+- Create agents with sensible defaults
+- Configure common modules automatically
+- Set up evaluators with appropriate configuration
+- Simplify the agent creation process
+
+## Default Agent Creation
+
+### Method: `create_default_agent`
+
+**Parameters:**
+- `name`: Required unique agent identifier
+- `description`: Optional human-readable description
+- `model`: Optional LLM model identifier (defaults to configured default)
+- `input`: Required input field definitions
+- `output`: Required output field definitions
+- `tools`: Optional list of callable tools
+- `use_cache`: Whether to cache evaluation results (default: True)
+- `enable_rich_tables`: Whether to render rich tables in output (default: False)
+- `output_theme`: Visual theme for rendered output
+- `wait_for_input`: Whether to pause after execution (default: False)
+- `temperature`: Model temperature setting (default: 0.0)
+- `max_tokens`: Maximum generated tokens (default: 4096)
+- `alert_latency_threshold_ms`: Threshold for latency alerts (default: 30000)
+- `no_output`: Whether to suppress output (default: False)
+- `print_context`: Whether to print context (default: False)
+
+**Return Value:**
+- A fully configured `FlockAgent` instance
+
+**Default Configuration:**
+1. Creates a `DeclarativeEvaluator` with:
+   - Specified model or default
+   - Configured cache settings
+   - Specified max tokens and temperature
+
+2. Creates an `OutputModule` with:
+   - Table rendering settings
+   - Theme configuration
+   - Wait-for-input behavior
+
+3. Creates a `MetricsModule` with:
+   - Latency threshold alerts
+
+## Design Principles
+
+1. **Convention over Configuration**:
+   - Reasonable defaults for most parameters
+   - Only essential parameters required
+
+2. **Complete Configuration**:
+   - Agents created are fully functional
+   - All required components initialized
+
+3. **Flexibility**:
+   - All defaults can be overridden
+   - Additional configuration possible after creation
+
+4. **Extension**:
+   - Factory pattern allows future specialized factory methods
+   - Custom agent templates possible
+
+## Implementation Notes
+
+1. The factory uses the standard `FlockAgent` class
+2. Modules are attached via the agent's `add_module` method
+3. The agent is ready to use immediately after creation
+4. The agent is not automatically added to a Flock instance 

flock_core-0.3.18/.cursor/specs/03_module_system.md

@@ -0,0 +1,106 @@
+# Flock Module System Specification
+
+## Overview
+The module system provides a way to extend agent functionality through lifecycle hooks. Modules can modify agent behavior, add new capabilities, or provide cross-cutting concerns like logging or metrics without changing the core agent implementation.
+
+## Core Module Components
+
+### 1. FlockModuleConfig
+
+**Purpose:**
+Base configuration class for all module configurations.
+
+**Requirements:**
+- Must extend Pydantic's BaseModel
+- Must include an `enabled` flag to toggle module functionality
+- Must support extension through subclassing or the `with_fields` factory method
+
+**API:**
+- `with_fields(**field_definitions)`: Factory method to create derived config classes with additional fields
+
+### 2. FlockModule
+
+**Purpose:**
+Base abstract class for all modules that can be attached to agents.
+
+**Requirements:**
+- Must extend Pydantic's BaseModel and be abstract (ABC)
+- Must include a unique name identifier
+- Must include a configuration instance
+- Must implement all lifecycle hook methods
+
+**Lifecycle Hooks:**
+- `initialize(agent, inputs, context)`: Called when agent starts execution
+- `pre_evaluate(agent, inputs, context)`: Called before agent evaluation, can modify inputs
+- `post_evaluate(agent, inputs, result, context)`: Called after agent evaluation, can modify results
+- `terminate(agent, inputs, result, context)`: Called when agent completes execution
+- `on_error(agent, error, inputs, context)`: Called when an error occurs during execution
+
+## Module Integration
+
+### Agent Module Management
+The FlockAgent must provide methods to:
+- Add modules via `add_module(module)`
+- Remove modules via `remove_module(module_name)`
+- Retrieve modules via `get_module(module_name)`
+- Get all enabled modules via `get_enabled_modules()`
+
+### Module Execution
+During agent execution, the agent must:
+1. Call `initialize()` on all enabled modules during agent initialization
+2. Call `pre_evaluate()` on all enabled modules before evaluation
+3. Call `post_evaluate()` on all enabled modules after evaluation
+4. Call `terminate()` on all enabled modules during agent termination
+5. Call `on_error()` on all enabled modules when errors occur
+
+## Standard Modules
+
+### 1. OutputModule
+
+**Purpose:**
+Handle formatting and displaying agent outputs.
+
+**Configuration:**
+- `render_table`: Whether to render outputs as rich tables
+- `theme`: Visual theme for rendered outputs
+- `wait_for_input`: Whether to pause for user input after output
+- `no_output`: Whether to suppress output entirely
+- `print_context`: Whether to print context along with output
+
+### 2. MetricsModule
+
+**Purpose:**
+Track and report agent performance metrics.
+
+**Configuration:**
+- `latency_threshold_ms`: Threshold for latency alerts
+
+## Design Principles
+
+1. **Separation of Concerns**:
+   - Modules handle cross-cutting concerns
+   - Core agent logic remains focused
+   - Modules can be added/removed without modifying agent code
+
+2. **Composability**:
+   - Multiple modules can be attached to an agent
+   - Modules can interact through shared context
+   - Order-independent execution where possible
+
+3. **Configurability**:
+   - All modules have configuration classes
+   - Configuration can be modified at runtime
+   - Modules can be enabled/disabled through configuration
+
+4. **Extension Points**:
+   - Clear lifecycle hooks for integration
+   - Standardized interfaces for all modules
+   - Predictable execution ordering
+
+## Implementation Requirements
+
+1. Modules must be serializable along with agents
+2. Modules should have minimal dependencies on each other
+3. Modules should gracefully handle missing context or configuration
+4. Module hooks should be implemented as async methods
+5. Module hooks should not raise exceptions (handle internally) 

flock_core-0.3.18/.cursor/specs/04_evaluator_system.md

@@ -0,0 +1,100 @@
+# Flock Evaluator System Specification
+
+## Overview
+The evaluator system provides the core evaluation mechanism for agents, defining how inputs are processed and outputs are generated. It abstracts the interaction with language models and provides a standardized interface for agent evaluation.
+
+## Core Evaluator Components
+
+### 1. FlockEvaluatorConfig
+
+**Purpose:**
+Base configuration class for all evaluator configurations.
+
+**Requirements:**
+- Must extend Pydantic's BaseModel
+- Must include common configuration options for model interaction
+
+**Standard Fields:**
+- Model identifier
+- Caching preferences
+- Temperature settings
+- Token limits
+
+### 2. FlockEvaluator
+
+**Purpose:**
+Base abstract class for all evaluators.
+
+**Requirements:**
+- Must implement an `evaluate` method that processes agent inputs
+- Must handle tool execution when applicable
+- Must properly format inputs based on agent definitions
+- Must process and structure outputs according to agent output definitions
+
+**API:**
+- `evaluate(agent, inputs, tools)`: Asynchronous method to evaluate inputs and produce structured outputs
+
+## Standard Evaluators
+
+### 1. DeclarativeEvaluator
+
+**Purpose:**
+Default evaluator that uses a declarative approach, focusing on input/output mapping.
+
+**Functionality:**
+- Creates DSPy signatures from agent definitions
+- Configures language models appropriately
+- Selects appropriate agent tasks based on tool requirements
+- Processes model results into structured outputs
+
+**Configuration:**
+- `agent_type_override`: Optional override for agent type
+- `model`: Model identifier (default: 'openai/gpt-4o')
+- `use_cache`: Whether to cache results (default: True)
+- `temperature`: Model temperature (default: 0.0)
+- `max_tokens`: Maximum token generation (default: 4096)
+
+## Integration Points
+
+### DSPy Integration
+
+**Requirements:**
+- Must support DSPy for language model interactions
+- Must properly convert agent definitions to DSPy signatures
+- Must support DSPy caching when enabled
+
+### Tool Execution
+
+**Requirements:**
+- Must properly format tools for model access
+- Must handle tool execution when requested by the model
+- Must support synchronous and asynchronous tools
+- Must properly format tool results for the model
+
+## Design Principles
+
+1. **Modularity**:
+   - Evaluators should be interchangeable
+   - Different evaluation strategies possible with same agent definition
+
+2. **Abstraction**:
+   - Hide complexity of model interactions
+   - Provide a consistent interface regardless of underlying model
+
+3. **Flexibility**:
+   - Support different model providers
+   - Support different evaluation strategies
+   - Allow configuration of evaluation parameters
+
+4. **Performance**:
+   - Support caching of results
+   - Optimize token usage
+   - Handle rate limiting appropriately
+
+## Implementation Requirements
+
+1. Evaluators must be serializable
+2. Evaluators must handle exceptions gracefully
+3. Evaluators should provide appropriate debugging information
+4. Evaluators should support observability through tracing
+5. Evaluators should maintain compatibility with multiple model providers 

flock_core-0.3.18/.cursor/specs/05_router_system.md

@@ -0,0 +1,104 @@
+# Flock Router System Specification
+
+## Overview
+The router system enables multi-agent workflows by determining which agent should execute next based on the current agent's outputs. It provides a mechanism for building complex agent pipelines and workflows.
+
+## Core Router Components
+
+### 1. HandOffRequest
+
+**Purpose:**
+Define the next agent to execute and how inputs should be handled.
+
+**Requirements:**
+- Must extend Pydantic's BaseModel
+- Must identify the next agent to execute
+- Must define how inputs are mapped between agents
+
+**Fields:**
+- `next_agent`: Name of the next agent to invoke
+- `hand_off_mode`: Strategy for mapping outputs to inputs ('match' or 'add')
+- `override_next_agent`: Optional direct reference to next agent
+- `override_context`: Optional context override
+
+### 2. FlockRouterConfig
+
+**Purpose:**
+Configuration for router behavior.
+
+**Requirements:**
+- Must extend Pydantic's BaseModel
+- Must include an enabled flag
+- Must support a list of possible agent destinations
+
+**Fields:**
+- `enabled`: Whether the router is active
+- `agents`: Optional list of potential target agents
+
+### 3. FlockRouter
+
+**Purpose:**
+Base abstract class for all routers.
+
+**Requirements:**
+- Must extend Pydantic's BaseModel and be abstract (ABC)
+- Must include a unique name
+- Must include a configuration
+- Must implement a `route` method
+
+**API:**
+- `route(current_agent, result, context)`: Async method to determine the next agent
+
+## Router Integration
+
+### Agent Integration
+FlockAgent includes an optional `handoff_router` field:
+- When present, enables multi-agent workflows
+- When absent, execution stops after the agent completes
+
+### Workflow Execution
+During Flock execution:
+1. After agent evaluation, check if agent has a router
+2. If router exists and is enabled, call its `route` method
+3. Process the HandOffRequest to determine the next agent
+4. Map outputs to inputs according to hand_off_mode
+5. Execute the next agent
+6. Repeat until no next agent is specified
+
+## Standard Routers
+
+### 1. SimpleFlockRouter
+A basic router that selects from a fixed list of next agents.
+
+### 2. LLMFlockRouter
+A router that uses LLM to determine the next agent based on result content.
+
+## Design Principles
+
+1. **Flexibility**:
+   - Support different routing strategies
+   - Allow both static and dynamic routing
+   - Enable complex workflow patterns
+
+2. **Clear Handoff Definition**:
+   - Explicit next agent specification
+   - Well-defined input mapping strategies
+   - Support for context modification
+
+3. **Extensibility**:
+   - Easy to implement custom routers
+   - Support for different routing criteria
+   - Integration with external systems
+
+4. **Predictability**:
+   - Clear execution paths
+   - Debuggable routing decisions
+   - Avoidance of circular references
+
+## Implementation Requirements
+
+1. Routers must be serializable
+2. Routers must support both string-based and direct agent references
+3. Routers must handle missing or invalid next agent gracefully
+4. Router implementations should avoid side effects
+5. Routers should support tracing of routing decisions 

flock_core-0.3.18/.cursor/specs/06_tool_system.md

@@ -0,0 +1,88 @@
+# Flock Tool System Specification
+
+## Overview
+The tool system provides agents with capabilities to perform actions beyond generating text. Tools can retrieve information, perform calculations, interact with external systems, or execute code. This specification defines how tools are integrated and used within the Flock framework.
+
+## Tool Definition
+
+### Requirements
+- Tools must be callable functions or methods
+- Tools must accept standard Python types as inputs
+- Tools must return JSON-serializable outputs
+- Tools should include proper docstrings for agent instruction
+- Tools should handle errors gracefully
+
+### Tool Registration
+Tools can be registered in two ways:
+1. Through agent definition: `tools=[tool1, tool2]`
+2. Through Flock registration: `flock.add_tool("tool_name", tool_function)`
+
+## Tool Integration
+
+### Agent Integration
+Tools attached to an agent are:
+1. Registered in the global registry
+2. Made available to the agent during evaluation
+3. Formatted appropriately for the model to understand their capabilities
+
+### Evaluator Integration
+The evaluator is responsible for:
+1. Formatting tools for model consumption
+2. Detecting tool invocation in model outputs
+3. Executing tools with appropriate parameters
+4. Formatting tool results for continued model interaction
+
+## Standard Tool Categories
+
+### 1. Basic Tools
+- Web search tools
+- Code evaluation tools
+- System information tools
+- File manipulation tools
+
+### 2. Specialized Tools
+- Data analysis tools
+- API interaction tools
+- Database tools
+- Visualization tools
+
+## Tool Execution Flow
+
+1. Agent provides tools list during initialization
+2. Evaluator formats tools as function descriptions for the model
+3. Model generates output that may include tool invocation
+4. Evaluator parses the tool invocation and parameters
+5. Evaluator executes the tool with parsed parameters
+6. Tool result is formatted and provided back to the model
+7. Model continues generation with tool results available
+8. Final model output is returned as agent result
+
+## Design Principles
+
+1. **Flexibility**:
+   - Support for any callable function
+   - No special base classes required
+   - Dynamic addition of tools possible
+
+2. **Safety**:
+   - Tools should have clear boundaries
+   - Error handling to prevent failures
+   - Input validation for security
+
+3. **Discoverability**:
+   - Clear documentation for agent understanding
+   - Consistent interface patterns
+   - Self-describing capabilities
+
+4. **Performance**:
+   - Efficient execution
+   - Proper handling of async tools
+   - Support for caching tool results
+
+## Implementation Requirements
+
+1. Tools must work with different model providers
+2. Tools must handle both synchronous and asynchronous execution
+3. Tools should provide clear error messages
+4. Tools should be testable in isolation
+5. Complex tools should be composable from simpler tools