flock-core 0.3.5__py3-none-any.whl → 0.3.8__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.py

@@ -7,7 +7,7 @@ from opentelemetry import trace
 
 from flock.core.context.context_vars import FLOCK_LAST_AGENT, FLOCK_LAST_RESULT
 from flock.core.logging.logging import get_logger
-from flock.core.util.serializable import Serializable
+from flock.core.serialization.serializable import Serializable
 
 logger = get_logger("context")
 tracer = trace.get_tracer(__name__)

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(

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:
@@ -24,7 +27,6 @@ class FlockFactory:
         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/serialization/secure_serializer.py

@@ -0,0 +1,175 @@
+import cloudpickle
+
+
+class SecureSerializer:
+    """Security-focused serialization system with capability controls for Flock objects."""
+
+    # Define capability levels for different modules
+    MODULE_CAPABILITIES = {
+        # Core Python - unrestricted
+        "builtins": "unrestricted",
+        "datetime": "unrestricted",
+        "re": "unrestricted",
+        "math": "unrestricted",
+        "json": "unrestricted",
+        # Framework modules - unrestricted
+        "flock": "unrestricted",
+        # System modules - restricted but allowed
+        "os": "restricted",
+        "io": "restricted",
+        "sys": "restricted",
+        "subprocess": "high_risk",
+        # Network modules - high risk
+        "socket": "high_risk",
+        "requests": "high_risk",
+    }
+
+    # Functions that should never be serialized
+    BLOCKED_FUNCTIONS = {
+        "os.system",
+        "os.popen",
+        "os.spawn",
+        "os.exec",
+        "subprocess.call",
+        "subprocess.run",
+        "subprocess.Popen",
+        "eval",
+        "exec",
+        "__import__",
+    }
+
+    @staticmethod
+    def _get_module_capability(module_name):
+        """Get the capability level for a module."""
+        for prefix, level in SecureSerializer.MODULE_CAPABILITIES.items():
+            if module_name == prefix or module_name.startswith(f"{prefix}."):
+                return level
+        return "unknown"  # Default to unknown for unlisted modules
+
+    @staticmethod
+    def _is_safe_callable(obj):
+        """Check if a callable is safe to serialize."""
+        if not callable(obj) or isinstance(obj, type):
+            return True, "Not a callable function"
+
+        module = obj.__module__
+        func_name = (
+            f"{module}.{obj.__name__}"
+            if hasattr(obj, "__name__")
+            else "unknown"
+        )
+
+        # Check against blocked functions
+        if func_name in SecureSerializer.BLOCKED_FUNCTIONS:
+            return False, f"Function {func_name} is explicitly blocked"
+
+        # Check module capability level
+        capability = SecureSerializer._get_module_capability(module)
+        if capability == "unknown":
+            return False, f"Module {module} has unknown security capability"
+
+        return True, capability
+
+    @staticmethod
+    def serialize(obj, allow_restricted=True, allow_high_risk=False):
+        """Serialize an object with capability checks."""
+        if callable(obj) and not isinstance(obj, type):
+            is_safe, capability = SecureSerializer._is_safe_callable(obj)
+
+            if not is_safe:
+                raise ValueError(
+                    f"Cannot serialize unsafe callable: {capability}"
+                )
+
+            if capability == "high_risk" and not allow_high_risk:
+                raise ValueError(
+                    f"High risk callable {obj.__module__}.{obj.__name__} requires explicit permission"
+                )
+
+            if capability == "restricted" and not allow_restricted:
+                raise ValueError(
+                    f"Restricted callable {obj.__module__}.{obj.__name__} requires explicit permission"
+                )
+
+            # Store metadata about the callable for verification during deserialization
+            metadata = {
+                "module": obj.__module__,
+                "name": getattr(obj, "__name__", "unknown"),
+                "capability": capability,
+            }
+
+            return {
+                "__serialized_callable__": True,
+                "data": cloudpickle.dumps(obj).hex(),
+                "metadata": metadata,
+            }
+
+        if isinstance(obj, list):
+            return [
+                SecureSerializer.serialize(
+                    item, allow_restricted, allow_high_risk
+                )
+                for item in obj
+            ]
+
+        if isinstance(obj, dict):
+            return {
+                k: SecureSerializer.serialize(
+                    v, allow_restricted, allow_high_risk
+                )
+                for k, v in obj.items()
+            }
+
+        return obj
+
+    @staticmethod
+    def deserialize(obj, allow_restricted=True, allow_high_risk=False):
+        """Deserialize an object with capability enforcement."""
+        if isinstance(obj, dict) and obj.get("__serialized_callable__") is True:
+            # Validate the capability level during deserialization
+            metadata = obj.get("metadata", {})
+            capability = metadata.get("capability", "unknown")
+
+            if capability == "high_risk" and not allow_high_risk:
+                raise ValueError(
+                    f"Cannot deserialize high risk callable {metadata.get('module')}.{metadata.get('name')}"
+                )
+
+            if capability == "restricted" and not allow_restricted:
+                raise ValueError(
+                    f"Cannot deserialize restricted callable {metadata.get('module')}.{metadata.get('name')}"
+                )
+
+            try:
+                callable_obj = cloudpickle.loads(bytes.fromhex(obj["data"]))
+
+                # Additional verification that the deserialized object matches its metadata
+                if callable_obj.__module__ != metadata.get("module") or (
+                    hasattr(callable_obj, "__name__")
+                    and callable_obj.__name__ != metadata.get("name")
+                ):
+                    raise ValueError(
+                        "Callable metadata mismatch - possible tampering detected"
+                    )
+
+                return callable_obj
+            except Exception as e:
+                raise ValueError(f"Failed to deserialize callable: {e!s}")
+
+        if isinstance(obj, list):
+            return [
+                SecureSerializer.deserialize(
+                    item, allow_restricted, allow_high_risk
+                )
+                for item in obj
+            ]
+
+        if isinstance(obj, dict) and "__serialized_callable__" not in obj:
+            return {
+                k: SecureSerializer.deserialize(
+                    v, allow_restricted, allow_high_risk
+                )
+                for k, v in obj.items()
+            }
+
+        return obj

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()

flock/routers/__init__.py

@@ -0,0 +1 @@
+"""Routers for the Flock framework."""

flock/routers/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent-based router implementation for the Flock framework."""