flock-core 0.3.35__tar.gz → 0.3.36__tar.gz

{flock_core-0.3.35 → flock_core-0.3.36}/.project/specs/01_core_architecture.md

@@ -9,6 +9,8 @@ Flock is a framework for building, orchestrating, and running AI agent systems.
 
 The central orchestrator that manages agents, tools, and execution flow.
 
+**Implementation:** `src/flock/core/flock.py`
+
 **Responsibilities:**
 - Managing agent registration and retrieval
 - Orchestrating workflow execution
@@ -27,6 +29,8 @@ The central orchestrator that manages agents, tools, and execution flow.
 
 The core agent class that defines a single AI agent's capabilities.
 
+**Implementation:** `src/flock/core/flock_agent.py`
+
 **Responsibilities:**
 - Defining agent inputs and outputs
 - Managing agent lifecycle
@@ -49,6 +53,8 @@ The core agent class that defines a single AI agent's capabilities.
 
 Extension system for agents to modify behavior through lifecycle hooks.
 
+**Implementation:** `src/flock/core/flock_module.py`
+
 **Responsibilities:**
 - Hooking into agent lifecycle events
 - Modifying inputs or outputs
@@ -66,6 +72,8 @@ Extension system for agents to modify behavior through lifecycle hooks.
 
 Strategy for evaluating agent requests and generating outputs.
 
+**Implementation:** `src/flock/core/flock_evaluator.py`
+
 **Responsibilities:**
 - Processing agent inputs
 - Formulating appropriate prompts
@@ -77,6 +85,8 @@ Strategy for evaluating agent requests and generating outputs.
 
 Mechanism for directing workflow between agents.
 
+**Implementation:** `src/flock/core/flock_router.py`
+
 **Responsibilities:**
 - Determining the next agent in a workflow
 - Managing input/output mapping between agents
@@ -89,6 +99,8 @@ Mechanism for directing workflow between agents.
 
 Shared execution context for agents and modules.
 
+**Implementation:** `src/flock/core/context/context.py`
+
 **Responsibilities:**
 - Storing global state across agents
 - Providing access to agent definitions

{flock_core-0.3.35 → flock_core-0.3.36}/.project/specs/02_agent_factory.md

@@ -5,6 +5,8 @@ The Factory design pattern is implemented in Flock to simplify agent creation wi
 
 ## FlockFactory
 
+**Implementation:** `src/flock/core/flock_factory.py`
+
 ### Purpose
 Provide a simplified interface for creating pre-configured agents without requiring manual setup of all components.
 
@@ -18,6 +20,8 @@ Provide a simplified interface for creating pre-configured agents without requir
 
 ### Method: `create_default_agent`
 
+**Implementation:** `src/flock/core/flock_factory.py:create_default_agent`
+
 **Parameters:**
 - `name`: Required unique agent identifier
 - `description`: Optional human-readable description

{flock_core-0.3.35 → flock_core-0.3.36}/.project/specs/03_module_system.md

@@ -3,10 +3,14 @@
 ## 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 Implementation:** `src/flock/core/flock_module.py`
+
 ## Core Module Components
 
 ### 1. FlockModuleConfig
 
+**Implementation:** `src/flock/core/flock_module.py:FlockModuleConfig`
+
 **Purpose:**
 Base configuration class for all module configurations.
 
@@ -20,6 +24,8 @@ Base configuration class for all module configurations.
 
 ### 2. FlockModule
 
+**Implementation:** `src/flock/core/flock_module.py:FlockModule`
+
 **Purpose:**
 Base abstract class for all modules that can be attached to agents.
 
@@ -40,10 +46,10 @@ Base abstract class for all modules that can be attached to agents.
 
 ### 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()`
+- Add modules via `add_module(module)` - **Implementation:** `src/flock/core/flock_agent.py:add_module`
+- Remove modules via `remove_module(module_name)` - **Implementation:** `src/flock/core/flock_agent.py:remove_module`
+- Retrieve modules via `get_module(module_name)` - **Implementation:** `src/flock/core/flock_agent.py:get_module`
+- Get all enabled modules via `get_enabled_modules()` - **Implementation:** `src/flock/core/flock_agent.py:get_enabled_modules`
 
 ### Module Execution
 During agent execution, the agent must:
@@ -57,6 +63,8 @@ During agent execution, the agent must:
 
 ### 1. OutputModule
 
+**Implementation:** `src/flock/modules/output/output_module.py`
+
 **Purpose:**
 Handle formatting and displaying agent outputs.
 
@@ -69,6 +77,8 @@ Handle formatting and displaying agent outputs.
 
 ### 2. MetricsModule
 
+**Implementation:** `src/flock/modules/metrics/metrics_module.py`
+
 **Purpose:**
 Track and report agent performance metrics.
 

flock_core-0.3.36/.project/specs/04_evaluator_system.md

@@ -0,0 +1,103 @@
+# Flock Evaluator System Specification
+
+## Overview
+The evaluator system is responsible for processing agent inputs and generating outputs. It defines how agents interact with language models, including prompt formulation, model configuration, and output processing. This specification outlines the requirements and architecture of the evaluator system.
+
+## Core Components
+
+### 1. FlockEvaluator
+
+**Implementation:** `src/flock/core/flock_evaluator.py`
+
+**Purpose:**
+Abstract base class defining the interface for all evaluators.
+
+**Requirements:**
+- Must define an `evaluate(agent, inputs, context)` method
+- Must handle varied input and output formats
+- Must integrate with tools if provided
+- Should support caching when enabled
+
+### 2. DeclarativeEvaluator
+
+**Implementation:** `src/flock/evaluators/declarative/declarative_evaluator.py`
+
+**Purpose:**
+Standard evaluator that generates outputs based on agent's declared inputs and outputs.
+
+**Configuration:**
+- `agent_type_override`: Optional override for agent type
+- `model`: The LLM to use for evaluation (default: openai/gpt-4o)
+- `use_cache`: Whether to cache evaluation results (default: True)
+- `temperature`: Sampling temperature (default: 0.0)
+- `max_tokens`: Maximum generated tokens (default: 4096)
+
+**Behavior:**
+1. Creates a DSPy signature from agent input/output declarations
+2. Configures the language model with appropriate settings
+3. Selects the task type based on tool requirements
+4. Executes the task with provided inputs
+5. Processes and returns the structured results
+
+**Mixins:**
+- `DSPyIntegrationMixin`: Provides DSPy framework integration
+- `PromptParserMixin`: Handles prompt parsing and formatting
+
+## Evaluator Integration
+
+### Agent Integration
+The FlockAgent must:
+- Store the evaluator in its `evaluator` attribute
+- Call `evaluator.evaluate()` during its own `evaluate()` method
+- Pass the appropriate context and inputs to the evaluator
+
+### Factory Integration
+The FlockFactory must:
+- Create and configure the appropriate evaluator based on agent parameters
+- Attach the evaluator to the agent during creation
+
+## Specializations
+
+### 1. Natural Language Evaluators
+
+**Implementation:** `src/flock/evaluators/natural_language/`
+
+**Purpose:**
+Evaluators that use natural language processing techniques.
+
+### 2. Memory-Enhanced Evaluators 
+
+**Implementation:** `src/flock/evaluators/memory/`
+
+**Purpose:**
+Evaluators that incorporate memory capabilities for stateful conversations and reasoning.
+
+## Design Principles
+
+1. **Separation of Concerns**:
+   - Evaluators handle prompt creation and model interaction
+   - Agents define inputs and outputs
+   - Clear division of responsibilities
+
+2. **Flexibility**:
+   - Support for different model providers via LiteLLM
+   - Configurable parameters for each evaluation
+   - Extensible through specializations
+
+3. **Consistency**:
+   - Standard interface for all evaluators
+   - Predictable input and output processing
+   - Common error handling patterns
+
+4. **Performance**:
+   - Built-in caching support
+   - Efficient DSPy integration
+   - Optimized model calls
+
+## Implementation Requirements
+
+1. Evaluators must be serializable
+2. Evaluators should have minimal dependencies on specific model providers
+3. Error handling should be graceful and informative
+4. Caching should be configurable and efficient
+5. Tool integration should be seamless and standardized 

{flock_core-0.3.35 → flock_core-0.3.36}/.project/specs/05_router_system.md

@@ -3,18 +3,17 @@
 ## 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 Implementation:** `src/flock/core/flock_router.py`
+
 ## Core Router Components
 
 ### 1. HandOffRequest
 
+**Implementation:** `src/flock/core/flock_router.py`
+
 **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')
@@ -23,29 +22,22 @@ Define the next agent to execute and how inputs should be handled.
 
 ### 2. FlockRouterConfig
 
+**Implementation:** `src/flock/core/flock_router.py`
+
 **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
 
+**Implementation:** `src/flock/core/flock_router.py`
+
 **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
 
@@ -67,11 +59,46 @@ During Flock execution:
 
 ## Standard Routers
 
-### 1. SimpleFlockRouter
-A basic router that selects from a fixed list of next agents.
+### 1. DefaultRouter
+
+**Implementation:** `src/flock/routers/default/default_router.py`
+
+**Purpose:**
+A basic router that directs to a predefined next agent.
+
+**Configuration:**
+- `hand_off`: Static agent name, HandOffRequest instance, or callable returning HandOffRequest
+
+**Behavior:**
+Provides a simple, non-dynamic routing based on a predetermined path.
+
+### 2. LLMRouter
+
+**Implementation:** `src/flock/routers/llm/llm_router.py`
+
+**Purpose:**
+A router that uses an LLM to determine the next agent based on result content.
+
+**Configuration:**
+- `with_output`: Whether to include the current agent's output in the routing decision
+- `config_model`: Routing model to use
+
+**Behavior:**
+Uses an LLM to dynamically select the next agent from a list of available agents based on the current result.
+
+### 3. AgentRouter
+
+**Implementation:** `src/flock/routers/agent/agent_router.py`
+
+**Purpose:**
+A router that uses a separate agent to determine the next agent in the workflow.
+
+**Configuration:**
+- `router_agent`: The specialized agent that makes routing decisions
+- `input_template`: Template for creating input for the router agent
 
-### 2. LLMFlockRouter
-A router that uses LLM to determine the next agent based on result content.
+**Behavior:**
+Delegates routing decisions to a specialized agent designed specifically for workflow orchestration.
 
 ## Design Principles
 

{flock_core-0.3.35 → flock_core-0.3.36}/.project/specs/06_tool_system.md

@@ -3,6 +3,8 @@
 ## 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.
 
+**Core Implementation:** `src/flock/core/tools/`
+
 ## Tool Definition
 
 ### Requirements
@@ -35,16 +37,45 @@ The evaluator is responsible for:
 ## 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
+
+**Implementation:** `src/flock/core/tools/basic_tools.py`
+
+- Web search tools (Tavily, DuckDuckGo, Bing)
+- Web content extraction and parsing
+- Code evaluation (via PythonInterpreter)
+- Math evaluation
+- Time and date functions
+- Text parsing and extraction (URLs, numbers)
+- File operations (read/write)
+- JSON processing
+
+### 2. LLM-specific Tools
+
+**Implementation:** `src/flock/core/tools/llm_tools.py`
+
+- Text chunking and splitting (multiple strategies)
+- Token counting and management
+- Keyword extraction
+- Text cleaning and formatting
+- Chat history formatting
+- Language detection
+- JSON extraction from text
+- Table formatting
+- Text hashing
+
+### 3. Azure Tools
+
+**Implementation:** `src/flock/core/tools/azure_tools.py`
+
+- Azure-specific functionality
+- Cloud resource management
+
+### 4. Markdown Tools
+
+**Implementation:** `src/flock/core/tools/markdown_tools.py`
+
+- Markdown processing and generation
+- Documentation creation helpers
 
 ## Tool Execution Flow
 

{flock_core-0.3.35 → flock_core-0.3.36}/.project/specs/07_execution_system.md

@@ -21,21 +21,30 @@ The execution system defines how agent workflows are executed, with support for
 
 ### 1. Local Executor
 
+**Implementation:** `src/flock/core/execution/local_executor.py`
+
 **Responsibilities:**
 - Execute agent workflows synchronously
-- Manage agent context and state
-- Handle agent initialization and termination
-- Process routing between agents
-- Collect and return final results
+- Process context through workflow
+- Return formatted results
+- Support debugging workflows
+
+**Key Function:**
+- `run_local_workflow(context, box_result)`: Executes the workflow locally
 
 ### 2. Temporal Executor
 
+**Implementation:** `src/flock/core/execution/temporal_executor.py`
+
 **Responsibilities:**
-- Set up Temporal workflow definitions
-- Convert agents to Temporal activities
-- Manage serialization/deserialization for distributed execution
-- Handle workflow state persistence
-- Provide reliability features like retries and timeouts
+- Set up Temporal workflow and worker
+- Create Temporal client
+- Execute workflow through Temporal
+- Maintain workflow ID management
+- Return formatted results
+
+**Key Function:**
+- `run_temporal_workflow(context, box_result)`: Executes the workflow via Temporal
 
 ## Execution Flow
 
@@ -44,7 +53,7 @@ The execution system defines how agent workflows are executed, with support for
 2. Flock resolves the start agent (by name or reference)
 3. Flock initializes the context
 4. Flock calls `run_local_workflow()` to execute the workflow
-5. Local executor calls `agent.run_async()` on the start agent
+5. Local executor calls `run_agent()` to process the workflow
 6. If agent has a router, determine next agent and continue execution
 7. Continue until no next agent is specified
 8. Return final result to the user
@@ -52,19 +61,19 @@ The execution system defines how agent workflows are executed, with support for
 ### Temporal Execution Flow
 1. User calls `flock.run()` with start agent and input
 2. Flock checks `enable_temporal` flag and identifies Temporal execution
-3. Flock serializes the necessary components
-4. Flock calls `run_temporal_workflow()` with serialized components
-5. Temporal workflow executes agent activities asynchronously
-6. Workflow handles routing between agents
-7. Workflow returns final result to the user
+3. Flock initializes context with run ID
+4. Flock calls `run_temporal_workflow()`
+5. Temporal executor sets up worker and client
+6. Workflow is executed through Temporal infrastructure
+7. Results are returned to the user
 
 ## Serialization Requirements
 
 For Temporal execution, components must be serializable:
-1. Agents must be convertible to/from dictionaries
-2. Tools must be properly serialized/deserialized
-3. Context must maintain state across activities
-4. All inputs and outputs must be JSON-serializable
+1. Context is serialized to/from dictionary
+2. Agents must be accessible through registry
+3. Tools must be properly registered
+4. All inputs and outputs must be serializable
 
 ## Error Handling
 
@@ -94,12 +103,12 @@ For Temporal execution, components must be serializable:
 3. **Observability**:
    - Tracing through all execution steps
    - Logging at key points
-   - Metrics for performance analysis
+   - Consistent workflow IDs for tracking
 
 4. **Flexibility**:
    - Support for synchronous and asynchronous APIs
    - Compatible with different execution environments
-   - Extensible to other execution engines
+   - Result formatting options
 
 ## Implementation Requirements
 

flock_core-0.3.36/.project/specs/08_context_system.md

@@ -0,0 +1,121 @@
+# Flock Context System Specification
+
+## Overview
+The context system provides shared state management across agent executions within a Flock workflow. It enables agents to access shared data, store intermediate results, and communicate with each other beyond direct input/output mapping. This specification defines the requirements and behavior of the context system.
+
+**Core Implementation:** `src/flock/core/context/`
+
+## Core Components
+
+### 1. FlockContext
+
+**Implementation:** `src/flock/core/context/context.py`
+
+**Purpose:**
+Provides a centralized state container for sharing data across agent executions.
+
+**Key Features:**
+- State storage for variables
+- Agent execution history tracking
+- Agent definition registry
+- Run/workflow identification
+- Variable access via key-value or dictionary-style access
+- Serialization support
+
+**API:**
+- `get_variable(key, default=None)`: Retrieve a value by key
+- `set_variable(key, value)`: Store a value by key
+- `__getitem__`/`__setitem__`: Dictionary-style access
+- `record(agent_name, data, timestamp, hand_off, called_from)`: Record agent execution
+- `get_agent_history(agent_name)`: Get execution history for an agent
+- `next_input_for(agent)`: Determine the next input for an agent
+- `get_most_recent_value(variable_name)`: Get most recent value from history
+- `get_agent_definition(agent_name)`: Get agent definition
+- `add_agent_definition(agent_type, agent_name, agent_data)`: Register agent definition
+
+### 2. Context Manager
+
+**Implementation:** `src/flock/core/context/context_manager.py`
+
+**Purpose:**
+Initializes and manages context instances for workflows.
+
+**API:**
+- `initialize_context(flock_args)`: Create and initialize a new context
+
+## Supporting Models
+
+### 1. AgentRunRecord
+
+**Implementation:** `src/flock/core/context/context.py`
+
+**Purpose:**
+Records the details of each agent execution for history tracking.
+
+**Fields:**
+- `id`: Unique identifier for the run
+- `agent`: Name of the agent
+- `data`: Input/output data associated with the run 
+- `timestamp`: When the execution occurred
+- `hand_off`: Routing information
+- `called_from`: Origin of the execution request
+
+### 2. AgentDefinition
+
+**Implementation:** `src/flock/core/context/context.py`
+
+**Purpose:**
+Stores information about registered agents.
+
+**Fields:**
+- `agent_type`: Type of the agent
+- `agent_name`: Name identifier
+- `agent_data`: Agent configuration
+- `serializer`: Serialization method
+
+## Context Integration
+
+### Flock Integration
+- Flock creates and initializes the global context
+- Flock passes context to each agent during execution
+- Flock ensures context consistency across agents
+
+### Agent Integration
+- Agents receive context during initialization and evaluation
+- Agents can read from and write to context
+- Context determines appropriate inputs for agents based on their input schema
+
+### Module Integration
+- Modules receive context in all lifecycle methods
+- Modules can use context to store and retrieve state
+- Modules can communicate with each other via context
+
+## Design Principles
+
+1. **Shared State Management**:
+   - Consistent state across agent executions
+   - History tracking for debugging and analysis
+   - Dictionary-like access patterns
+
+2. **Flexibility**:
+   - Support for various data types
+   - Both key-value and path-based access
+   - Robust serialization for distribution
+
+3. **Serialization Support**:
+   - Full serialization for distributed execution
+   - Support for complex object types
+   - Proper handling of datetime objects
+
+4. **Observability**:
+   - Tracing integration
+   - Logging of state changes
+   - History recording for execution flow
+
+## Implementation Requirements
+
+1. Context must be serializable for Temporal workflows
+2. Context operations must be thread-safe
+3. Context should handle large data volumes efficiently
+4. Context should support common data operations (get, set, delete)
+5. Context should provide clear error messages for invalid operations