flock-core 0.3.6__py3-none-any.whl → 0.3.10__py3-none-any.whl

flock/cli/assets/release_notes.md

@@ -1,4 +1,3 @@
-
 # Flock v0.3 - Hummingbird  
 
 We're excited to announce Flock v0.3, codenamed **"Hummingbird"**! This release brings a fundamental redesign of Flock's core architecture, introducing **unprecedented modularity and flexibility** to AI agent development.  
@@ -13,17 +12,17 @@ Like a hummingbird, modules are small and nimble code packages. Put enough of th
 
 ### Other notable additions:  
 - **CLI Interface** – Flock now has a command-line interface  
+- **REST API Server** – Expose your agents via HTTP endpoints
 - **Color-coded logging** – Better debugging experience  
 - **New examples**  
 - ...and much more!  
 
 ---
 
-## Core Changes  
+## Core Changes   
 
-### New Module System  
-- **Complete redesign** of the module architecture  
-- Simple yet powerful lifecycle hooks: `initialize`, `pre_evaluate`, `post_evaluate`, `terminate`  
+### New Module System   
+- **Pluggable modules system á la FastAPI**   
 - **Easy-to-implement** module interface  
 - **Configuration system** for clean parameter management  
 
@@ -32,15 +31,44 @@ Like a hummingbird, modules are small and nimble code packages. Put enough of th
 - Built-in support for multiple evaluation strategies:  
   - **Declarative Evaluator** – The default way Flock is designed  
   - **Natural Language Evaluator** – Use "classic" prompting  
+  - **Zep Evaluator** – Add or query data
 - **Easily extendable** with custom evaluation approaches  
 
-### FlockFactory  
+### New Router System
+- **Pluggable router system** for dynamic agent chaining
+- Built-in support for multiple routing strategies:
+  - **Default Router** – Uses the agent's hand_off property
+  - **LLM Router** – Uses an LLM to determine the next agent
+  - **Agent Router** – Uses a dedicated agent to make routing decisions
+- **Easily extendable** with custom routing approaches
+
+### REST API Server
+- **FastAPI-based** HTTP server for exposing agents
+- **Synchronous and asynchronous** execution modes
+- **Run status tracking** with unique run IDs
+- **Agent discovery** endpoint to list available agents
+- **Simple integration** with existing Flock instances
+
+### Auto-Handoff Feature
+- **Dynamic agent chaining** without explicit handoff definitions
+- **LLM-powered routing** to determine the best next agent
+- **Emergent behavior** in multi-agent systems
+- **Simple to use** with the "auto_handoff" string value
+
+### New high end examples like the Repository Analyzer
+- **Automatic documentation generation** for any codebase
+- **Rule-based version** using custom evaluators
+- **LLM-based version** for more flexible and powerful analysis
+- **Comprehensive documentation** including overview, architecture, components, and more
+
+### FlockFactory    
 - Provides **pre-configured agents**, so you don't have to manage modules and evaluators manually!  
 
 ### Built-in Modules  
 - **Memory Module** – Persistent agent memory  
 - **Output Module** – Advanced output formatting and storage  
 - **Metrics Module** – Detailed performance tracking  
+- **Zep Module** – Uses Zep for Knowledge Graphs
 
 ---
 
@@ -99,7 +127,7 @@ See? **Basically nothing changed!** Just more modular and flexible.
 
 ---
 
-## 🛠 Installation  
+## Installation  
 
 ```bash
 pip install flock-core>=0.3.0
@@ -107,5 +135,5 @@ pip install flock-core>=0.3.0
 
 ---  
 
-**Full documentation**: [docs.flock.ai](https://docs.flock.ai)  
-**GitHub**: [github.com/flock-ai](https://github.com/flock-ai)  
+**Full documentation**: [https://whiteducksoftware.github.io/flock](https://whiteducksoftware.github.io/flock)  
+**GitHub**: [https://github.com/whiteducksoftware/flock](https://github.com/whiteducksoftware/flock)

flock/core/context/context_manager.py

@@ -5,6 +5,7 @@ from flock.core.context.context_vars import (
     FLOCK_CURRENT_AGENT,
     FLOCK_INITIAL_INPUT,
     FLOCK_LOCAL_DEBUG,
+    FLOCK_MODEL,
     FLOCK_RUN_ID,
 )
 
@@ -15,6 +16,7 @@ def initialize_context(
     input_data: dict,
     run_id: str,
     local_debug: bool,
+    model: str,
 ) -> None:
     """Initialize the FlockContext with standard variables before running an agent.
 
@@ -32,3 +34,4 @@ def initialize_context(
     context.set_variable(FLOCK_LOCAL_DEBUG, local_debug)
     context.run_id = run_id
     context.set_variable(FLOCK_RUN_ID, run_id)
+    context.set_variable(FLOCK_MODEL, model)

flock/core/context/context_vars.py

@@ -6,3 +6,4 @@ FLOCK_LOCAL_DEBUG = "flock.local_debug"
 FLOCK_RUN_ID = "flock.run_id"
 FLOCK_LAST_AGENT = "flock.last_agent"
 FLOCK_LAST_RESULT = "flock.last_result"
+FLOCK_MODEL = "flock.model"

flock/core/flock.py

@@ -135,7 +135,7 @@ class Flock:
         with tracer.start_as_current_span("add_agent") as span:
             span.set_attribute("agent_name", agent.name)
             if not agent.model:
-                agent.model = self.model
+                agent.set_model(self.model)
                 logger.debug(
                     f"Using default model for agent {agent.name}",
                     model=self.model,
@@ -443,6 +443,7 @@ class Flock:
                     self.input,
                     run_id,
                     not self.enable_temporal,
+                    self.model,
                 )
 
                 logger.info(

flock/core/flock_agent.py

@@ -5,15 +5,15 @@ import json
 import os
 from abc import ABC
 from collections.abc import Callable
-from typing import Any, TypeVar, Union
+from typing import Any, TypeVar
 
 import cloudpickle
 from opentelemetry import trace
 from pydantic import BaseModel, Field
 
-from flock.core.context.context import FlockContext
 from flock.core.flock_evaluator import FlockEvaluator
 from flock.core.flock_module import FlockModule
+from flock.core.flock_router import FlockRouter
 from flock.core.logging.logging import get_logger
 
 logger = get_logger("agent")
@@ -23,21 +23,6 @@ tracer = trace.get_tracer(__name__)
 T = TypeVar("T", bound="FlockAgent")
 
 
-class HandOff(BaseModel):
-    """Base class for handoff returns."""
-
-    next_agent: Union[str, "FlockAgent"] = Field(
-        default="", description="Next agent to invoke"
-    )
-    input: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Input data for the next agent",
-    )
-    context: FlockContext = Field(
-        default=None, descrio="Override context parameters"
-    )
-
-
 class FlockAgent(BaseModel, ABC):
     name: str = Field(..., description="Unique identifier for the agent.")
     model: str | None = Field(
@@ -72,12 +57,9 @@ class FlockAgent(BaseModel, ABC):
         description="Set to True to enable caching of the agent's results.",
     )
 
-    hand_off: str | HandOff | Callable[..., HandOff] | None = Field(
-        None,
-        description=(
-            "Specifies the next agent in the workflow or a callable that determines the handoff. "
-            "This allows chaining of agents."
-        ),
+    handoff_router: FlockRouter | None = Field(
+        default=None,
+        description="Router to use for determining the next agent in the workflow.",
     )
 
     evaluator: FlockEvaluator = Field(
@@ -218,6 +200,11 @@ class FlockAgent(BaseModel, ABC):
         """Run the agent with the given inputs and return its generated output."""
         return asyncio.run(self.run_async(inputs))
 
+    def set_model(self, model: str):
+        """Set the model for the agent."""
+        self.model = model
+        self.evaluator.config.model = model
+
     async def run_async(self, inputs: dict[str, Any]) -> dict[str, Any]:
         with tracer.start_as_current_span("agent.run") as span:
             span.set_attribute("agent.name", self.name)

flock/core/flock_factory.py

@@ -3,14 +3,17 @@
 from collections.abc import Callable
 from typing import Any
 
-from flock.core.flock_agent import FlockAgent, HandOff
+from flock.core.flock_agent import FlockAgent
 from flock.core.logging.formatters.themes import OutputTheme
 from flock.evaluators.declarative.declarative_evaluator import (
     DeclarativeEvaluator,
     DeclarativeEvaluatorConfig,
 )
-from flock.modules.performance.metrics_module import MetricsModule, MetricsModuleConfig
 from flock.modules.output.output_module import OutputModule, OutputModuleConfig
+from flock.modules.performance.metrics_module import (
+    MetricsModule,
+    MetricsModuleConfig,
+)
 
 
 class FlockFactory:
@@ -20,11 +23,10 @@ class FlockFactory:
     def create_default_agent(
         name: str,
         description: str | Callable[..., str] | None = None,
-        model: str | Callable[..., str] | None = "openai/gpt-4o",
+        model: str | Callable[..., str] | None = None,
         input: str | Callable[..., str] | None = None,
         output: str | Callable[..., str] | None = None,
         tools: list[Callable[..., Any] | Any] | None = None,
-        hand_off: str | HandOff | Callable[..., HandOff] | None = None,
         use_cache: bool = True,
         enable_rich_tables: bool = False,
         output_theme: OutputTheme = OutputTheme.abernathy,
@@ -53,7 +55,6 @@ class FlockFactory:
             input=input,
             output=output,
             tools=tools,
-            hand_off=hand_off,
             model=model,
             description=description,
             evaluator=evaluator,
@@ -65,7 +66,9 @@ class FlockFactory:
         )
         output_module = OutputModule("output", config=output_config)
 
-        metrics_config = MetricsModuleConfig(latency_threshold_ms=alert_latency_threshold_ms)
+        metrics_config = MetricsModuleConfig(
+            latency_threshold_ms=alert_latency_threshold_ms
+        )
         metrics_module = MetricsModule("metrics", config=metrics_config)
 
         agent.add_module(output_module)

flock/core/flock_module.py

@@ -43,7 +43,9 @@ class FlockModule(BaseModel, ABC):
     2. Using FlockModuleConfig.with_fields() to create a config class
     """
 
-    name: str = Field(..., description="Unique identifier for the module")
+    name: str = Field(
+        default="", description="Unique identifier for the module"
+    )
     config: FlockModuleConfig = Field(
         default_factory=FlockModuleConfig, description="Module configuration"
     )

flock/core/flock_router.py

@@ -0,0 +1,70 @@
+"""Base router class for the Flock framework."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from flock.core.context.context import FlockContext
+
+
+class HandOffRequest(BaseModel):
+    """Base class for handoff returns."""
+
+    next_agent: str = Field(default="", description="Next agent to invoke")
+    # match = use the output fields of the current agent that also exists as input field of the next agent
+    # add = add the output of the current agent to the input of the next agent
+    hand_off_mode: Literal["match", "add"] = Field(default="match")
+    override_next_agent: Any | None = Field(
+        default=None,
+        description="Override the next agent to hand off to",
+    )
+    override_context: FlockContext | None = Field(
+        default=None, descrio="Override context parameters"
+    )
+
+
+class FlockRouterConfig(BaseModel):
+    """Configuration for a router.
+
+    This class defines the configuration parameters for a router.
+    Subclasses can extend this to add additional parameters.
+    """
+
+    enabled: bool = Field(
+        default=True, description="Whether the router is enabled"
+    )
+    agents: list[str] | None = Field(
+        default=None,
+        description="List of agents to choose from",
+    )
+
+
+class FlockRouter(BaseModel, ABC):
+    """Base class for all routers.
+
+    A router is responsible for determining the next agent in a workflow
+    based on the current agent's output.
+    """
+
+    name: str = Field(..., description="Name of the router")
+    config: FlockRouterConfig = Field(default_factory=FlockRouterConfig)
+
+    @abstractmethod
+    async def route(
+        self,
+        current_agent: Any,
+        result: dict[str, Any],
+        context: FlockContext,
+    ) -> HandOffRequest:
+        """Determine the next agent to hand off to based on the current agent's output.
+
+        Args:
+            current_agent: The agent that just completed execution
+            result: The output from the current agent
+            context: The global execution context
+
+        Returns:
+            A HandOff object containing the next agent and input data
+        """
+        pass

flock/core/util/cli_helper.py

@@ -52,7 +52,7 @@ def init_console(clear_screen: bool = True):
 │ ▒█▀▀▀ █░░ █▀▀█ █▀▀ █░█ │
 │ ▒█▀▀▀ █░░ █░░█ █░░ █▀▄ │
 │ ▒█░░░ ▀▀▀ ▀▀▀▀ ▀▀▀ ▀░▀ │
-╰━━━━━━━━━v{__version__}━━━━━━━━━╯
+╰━━━━━━━━━v{__version__}━━━━━━━━╯
 🦆     🐤    🐧     🐓
 """,
         justify="center",
@@ -83,5 +83,3 @@ def display_banner_no_version():
     )
     console.print(banner_text)
     console.print(f"[bold]white duck GmbH[/] - [cyan]https://whiteduck.de[/]\n")
-
-

flock/evaluators/zep/zep_evaluator.py

@@ -40,6 +40,8 @@ class ZepEvaluator(FlockEvaluator, DSPyIntegrationMixin, PromptParserMixin):
                 zep_api_key=self.config.zep_api_key,
                 zep_url=self.config.zep_url,
                 min_fact_rating=self.config.min_fact_rating,
+                enable_read=True,
+                enable_write=True,
             ),
         )
         client = zep.get_client()