flock-core 0.4.511__py3-none-any.whl → 0.4.513__py3-none-any.whl

flock/core/config/flock_agent_config.py

@@ -0,0 +1,11 @@
+
+
+from pydantic import BaseModel
+
+
+class FlockAgentConfig(BaseModel):
+    """FlockAgentConfig is a class that holds the configuration for a Flock agent.
+    It is used to store various settings and parameters that can be accessed throughout the agent's lifecycle.
+    """
+
+    pass

flock/core/config/scheduled_agent_config.py

@@ -0,0 +1,40 @@
+
+
+
+from pydantic import Field
+
+from flock.core.config.flock_agent_config import FlockAgentConfig
+
+
+class ScheduledAgentConfig(FlockAgentConfig):
+    """Configuration specific to agents that run on a schedule."""
+    schedule_expression: str = Field(
+        ...,
+        description="Defines when the agent should run. "
+                    "Examples: 'every 60m', 'every 1h', 'daily at 02:00', '0 */2 * * *' (cron expression)"
+    )
+    enabled: bool = Field(
+        True,
+        description="Whether the scheduled agent is enabled. "
+                    "If False, the agent will not run even if the schedule expression is valid."
+    )
+    initial_run: bool = Field(
+        False,
+        description="If True, the agent will run immediately after being scheduled, "
+                    "regardless of the schedule expression."
+    )
+    max_runs: int = Field(
+        0,
+        description="Maximum number of times the agent can run. "
+                    "0 means unlimited runs. If set, the agent will stop running after reaching this limit."
+    )
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        # Ensure schedule_expression is always set
+        if 'schedule_expression' not in kwargs:
+            raise ValueError("schedule_expression is required for ScheduledAgentConfig")
+
+        # Validate initial_run and max_runs
+        if self.initial_run and self.max_runs > 0:
+            raise ValueError("Cannot set initial_run to True if max_runs is greater than 0")

flock/core/flock_agent.py

@@ -10,6 +10,7 @@ from collections.abc import Callable
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, TypeVar
 
+from flock.core.config.flock_agent_config import FlockAgentConfig
 from flock.core.mcp.flock_mcp_server import FlockMCPServerBase
 from flock.core.serialization.json_encoder import FlockJSONEncoder
 from flock.workflow.temporal_config import TemporalActivityConfig
@@ -124,6 +125,11 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         description="Dictionary of FlockModules attached to this agent.",
     )
 
+    config: FlockAgentConfig = Field(
+        default_factory=lambda: FlockAgentConfig(),
+        description="Configuration for this agent, holding various settings and parameters.",
+    )
+
     # --- Temporal Configuration (Optional) ---
     temporal_activity_config: TemporalActivityConfig | None = Field(
         default=None,
@@ -378,7 +384,7 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
                             )
                         else:
                             logger.warning(
-                                f"No Server with name '{server}' registered! Skipping."
+                                f"No Server with name '{server.config.name}' registered! Skipping."
                             )
                         mcp_tools = mcp_tools + server_tools
 

flock/core/flock_factory.py

@@ -5,8 +5,10 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any, Literal
 
-from pydantic import AnyUrl, BaseModel, Field, FileUrl
+import httpx
+from pydantic import AnyUrl, BaseModel, ConfigDict, Field, FileUrl
 
+from flock.core.config.scheduled_agent_config import ScheduledAgentConfig
 from flock.core.flock_agent import FlockAgent, SignatureType
 from flock.core.logging.formatters.themes import OutputTheme
 from flock.core.mcp.flock_mcp_server import FlockMCPServerBase
@@ -23,6 +25,7 @@ from flock.core.mcp.types.types import (
     MCPRoot,
     SseServerParameters,
     StdioServerParameters,
+    StreamableHttpServerParameters,
     WebsocketServerParameters,
 )
 from flock.evaluators.declarative.declarative_evaluator import (
@@ -39,6 +42,11 @@ from flock.mcp.servers.stdio.flock_stdio_server import (
     FlockStdioConfig,
     FlockStdioConnectionConfig,
 )
+from flock.mcp.servers.streamable_http.flock_streamable_http_server import (
+    FlockStreamableHttpConfig,
+    FlockStreamableHttpConnectionConfig,
+    FlockStreamableHttpServer,
+)
 from flock.mcp.servers.websockets.flock_websocket_server import (
     FlockWSConfig,
     FlockWSConnectionConfig,
@@ -100,6 +108,44 @@ class FlockFactory:
             description="The text encoding error handler. See https://docs.python.org/3/library/codecs.html#codec-base-classes for explanations of possible values",
         )
 
+    class StreamableHttpParams(BaseModel):
+        """Factory-Params for Streamable Http Servers."""
+
+        url: str | AnyUrl = Field(
+            ...,
+            description="Url the server listens at."
+        )
+
+        headers: dict[str, Any] | None = Field(
+            default=None,
+            description="Additional Headers to pass to the client."
+        )
+
+        auth: httpx.Auth | None = Field(
+            default=None,
+            description="Httpx Auth Schema."
+        )
+
+        timeout_seconds: float | int = Field(
+            default=5,
+            description="Http Timeout in Seconds"
+        )
+
+        sse_read_timeout_seconds: float | int = Field(
+            default=60*5,
+            description="How many seconds to wait for server-sent events until closing the connection."
+        )
+
+        terminate_on_close: bool = Field(
+            default=True,
+            description="Whether or not to terminate the underlying connection on close."
+        )
+
+        model_config = ConfigDict(
+            arbitrary_types_allowed=True,
+            extra="allow",
+        )
+
     class SSEParams(BaseModel):
         """Factory-Params for SSE-Servers."""
 
@@ -122,6 +168,16 @@ class FlockFactory:
             description="How many seconds to wait for server-sent events until closing the connection. (connections will be automatically re-established.)",
         )
 
+        auth: httpx.Auth | None = Field(
+            default=None,
+            description="Httpx Auth Scheme."
+        )
+
+        model_config = ConfigDict(
+            arbitrary_types_allowed=True,
+            extra="allow",
+        )
+
     class WebsocketParams(BaseModel):
         """Factory-Params for Websocket Servers."""
 
@@ -133,7 +189,7 @@ class FlockFactory:
     @staticmethod
     def create_mcp_server(
         name: str,
-        connection_params: SSEParams | StdioParams | WebsocketParams,
+        connection_params: StreamableHttpParams | SSEParams | StdioParams | WebsocketParams,
         max_retries: int = 3,
         mount_points: list[str | MCPRoot] | None = None,
         timeout_seconds: int | float = 10,
@@ -175,6 +231,9 @@ class FlockFactory:
         if isinstance(connection_params, FlockFactory.WebsocketParams):
             server_kind = "websockets"
             concrete_server_cls = FlockWSServer
+        if isinstance(connection_params, FlockFactory.StreamableHttpParams):
+            server_kind = "streamable_http"
+            concrete_server_cls = FlockStreamableHttpServer
 
         # convert mount points.
         mounts: list[MCPRoot] = []
@@ -243,12 +302,37 @@ class FlockFactory:
                 caching_config=caching_config,
                 callback_config=callback_config,
             )
+        elif server_kind == "streamable_http":
+            # build streamable http config
+            connection_config = FlockStreamableHttpConnectionConfig(
+                max_retries=max_retries,
+                connection_parameters=StreamableHttpServerParameters(
+                    url=connection_params.url,
+                    headers=connection_params.headers,
+                    auth=connection_params.auth,
+                    timeout=connection_params.timeout_seconds,
+                    sse_read_timeout=connection_params.sse_read_timeout_seconds,
+                    terminate_on_close=connection_params.terminate_on_close,
+                ),
+                mount_points=mounts,
+                server_logging_level=server_logging_level,
+            )
+
+            server_config = FlockStreamableHttpConfig(
+                name=name,
+                connection_config=connection_config,
+                feature_config=feature_config,
+                caching_config=caching_config,
+                callback_config=callback_config,
+            )
+
         elif server_kind == "sse":
             # build sse config
             connection_config = FlockSSEConnectionConfig(
                 max_retries=max_retries,
                 connection_parameters=SseServerParameters(
                     url=connection_params.url,
+                    auth=connection_params.auth,
                     headers=connection_params.headers,
                     timeout=connection_params.timeout_seconds,
                     sse_read_timeout=connection_params.sse_read_timeout_seconds,
@@ -381,3 +465,46 @@ class FlockFactory:
         agent.add_module(output_module)
         agent.add_module(metrics_module)
         return agent
+
+    @staticmethod
+    def create_scheduled_agent(
+        name: str,
+        schedule_expression: str, # e.g., "every 1h", "0 0 * * *"
+        description: str | Callable[..., str] | None = None,
+        model: str | Callable[..., str] | None = None,
+        input: SignatureType = None, # Input might be implicit or none
+        output: SignatureType = None, # Input might be implicit or none
+        tools: list[Callable[..., Any] | Any] | None = None,
+        servers: list[str | FlockMCPServerBase] | None = None,
+        use_cache: bool = False, # Whether to cache results
+        temperature: float = 0.7, # Temperature for model responses
+        # ... other common agent params from create_default_agent ...
+        temporal_activity_config: TemporalActivityConfig | None = None, # If you want scheduled tasks to be Temporal activities
+        **kwargs # Forward other standard agent params
+    ) -> FlockAgent:
+        """Creates a FlockAgent configured to run on a schedule."""
+        agent_config = ScheduledAgentConfig( # Use the new config type
+            schedule_expression=schedule_expression,
+            enabled=True,
+            initial_run=True,
+            max_runs=0,
+            **kwargs
+        )
+
+
+        agent = FlockFactory.create_default_agent( # Reuse your existing factory
+            name=name,
+            description=description,
+            model=model,
+            input=input + ", trigger_time: str | Time of scheduled execution",
+            output=output,
+            tools=tools,
+            servers=servers,
+            temporal_activity_config=temporal_activity_config,
+            use_cache=use_cache,
+            temperature=temperature,
+            **kwargs
+        )
+        agent.config = agent_config  # Assign the scheduled agent config
+
+        return agent

flock/core/flock_scheduler.py

@@ -0,0 +1,166 @@
+# src/flock/core/scheduler.py (new file or inside flock.py)
+import asyncio
+import traceback
+from datetime import datetime, timedelta, timezone
+
+from croniter import croniter  # pip install croniter
+
+from flock.core.flock import Flock
+from flock.core.flock_agent import FlockAgent  # For type hinting
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("flock.scheduler")
+
+class FlockScheduler:
+    def __init__(self, flock_instance: Flock):
+        self.flock = flock_instance
+        self._scheduled_tasks: list[tuple[FlockAgent, croniter | timedelta, datetime | None]] = []
+        self._stop_event = asyncio.Event()
+        self._is_running = False
+
+    def _parse_schedule_expression(self, expression: str) -> croniter | timedelta:
+        """Parses a schedule expression.
+        Supports cron syntax and simple intervals like 'every Xm', 'every Xh', 'every Xd'.
+        """
+        expression = expression.strip().lower()
+        if expression.startswith("every "):
+            try:
+                parts = expression.split(" ")
+                value = int(parts[1][:-1])
+                unit = parts[1][-1]
+                if unit == 's': return timedelta(seconds=value)
+                if unit == 'm': return timedelta(minutes=value)
+                elif unit == 'h': return timedelta(hours=value)
+                elif unit == 'd': return timedelta(days=value)
+                else: raise ValueError(f"Invalid time unit: {unit}")
+            except Exception as e:
+                logger.error(f"Invalid interval expression '{expression}': {e}")
+                raise ValueError(f"Invalid interval expression: {expression}") from e
+        else:
+            # Assume cron expression
+            if not croniter.is_valid(expression):
+                raise ValueError(f"Invalid cron expression: {expression}")
+            return croniter(expression, datetime.now(timezone.utc))
+
+    def add_agent(self, agent: FlockAgent):
+        """Adds an agent to the scheduler if it has a schedule expression."""
+        # Assuming schedule_expression is stored in agent._flock_config or a dedicated field
+        schedule_expression = None
+        if hasattr(agent, '_flock_config') and isinstance(agent._flock_config, dict):
+            schedule_expression = agent._flock_config.get('schedule_expression')
+        elif hasattr(agent, 'schedule_expression'): # If directly on agent
+             schedule_expression = agent.schedule_expression
+        elif hasattr(agent, 'config') and hasattr(agent.config, 'schedule_expression'): # If on agent.config
+            schedule_expression = agent.config.schedule_expression
+
+
+        if not schedule_expression:
+            logger.warning(f"Agent '{agent.name}' has no schedule_expression. Skipping.")
+            return
+
+        try:
+            parsed_schedule = self._parse_schedule_expression(schedule_expression)
+            self._scheduled_tasks.append((agent, parsed_schedule, None)) # agent, schedule, last_run_utc
+            logger.info(f"Scheduled agent '{agent.name}' with expression: {schedule_expression}")
+        except ValueError as e:
+            logger.error(f"Could not schedule agent '{agent.name}': {e}")
+
+    def _load_scheduled_agents_from_flock(self):
+        """Scans the Flock instance for agents with scheduling configuration."""
+        self._scheduled_tasks = [] # Clear existing before loading
+        for agent_name, agent_instance in self.flock.agents.items():
+            self.add_agent(agent_instance)
+        logger.info(f"Loaded {len(self._scheduled_tasks)} scheduled agents from Flock '{self.flock.name}'.")
+
+    async def _run_agent_task(self, agent: FlockAgent, trigger_time: datetime):
+        logger.info(f"Triggering scheduled agent '{agent.name}' at {trigger_time.isoformat()}")
+        try:
+            # Input for a scheduled agent could include the trigger time
+            await self.flock.run_async(start_agent=agent.name, input={"trigger_time": trigger_time})
+            logger.info(f"Scheduled agent '{agent.name}' finished successfully.")
+        except Exception as e:
+            logger.error(f"Error running scheduled agent '{agent.name}': {e}\n{traceback.format_exc()}")
+
+    async def _scheduler_loop(self):
+        self._is_running = True
+        logger.info("FlockScheduler loop started.")
+        while not self._stop_event.is_set():
+            now_utc = datetime.now(timezone.utc)
+            tasks_to_run_this_cycle = []
+
+            for i, (agent, schedule, last_run_utc) in enumerate(self._scheduled_tasks):
+                should_run = False
+                next_run_utc = None
+
+                if isinstance(schedule, croniter):
+                    # For cron, get the next scheduled time AFTER the last run (or now if never run)
+                    base_time = last_run_utc if last_run_utc else now_utc
+                    # Croniter's get_next gives the next time *after* the base_time.
+                    # If last_run_utc is None (first run), we check if the *current* now_utc
+                    # is past the first scheduled time.
+                    # A simpler check: is `now_utc` >= `schedule.get_next(datetime, base_time=last_run_utc if last_run_utc else now_utc - timedelta(seconds=1))` ?
+                    # Let's refine croniter check to be more precise.
+                    # If we are past the *next* scheduled time since *last check*
+                    if last_run_utc is None: # First run check
+                        next_run_utc = schedule.get_next(datetime, start_time=now_utc - timedelta(seconds=1)) # Check if first run is due
+                        if next_run_utc <= now_utc:
+                            should_run = True
+                    else:
+                        next_run_utc = schedule.get_next(datetime, start_time=last_run_utc)
+                        if next_run_utc <= now_utc:
+                            should_run = True
+
+                elif isinstance(schedule, timedelta): # Simple interval
+                    if last_run_utc is None or (now_utc - last_run_utc >= schedule):
+                        should_run = True
+                        next_run_utc = now_utc # Or now_utc + schedule for next interval start
+                    else:
+                        next_run_utc = last_run_utc + schedule
+
+
+                if should_run:
+                    tasks_to_run_this_cycle.append(self._run_agent_task(agent, now_utc))
+                    # Update last_run_utc for this agent *before* awaiting its execution
+                    # For cron, advance the iterator to the *current* scheduled time that triggered it.
+                    if isinstance(schedule, croniter):
+                         current_cron_trigger = schedule.get_current(datetime) # This is the time it *should* have run
+                         self._scheduled_tasks[i] = (agent, schedule, current_cron_trigger)
+
+                    elif isinstance(schedule, timedelta):
+                        self._scheduled_tasks[i] = (agent, schedule, now_utc) # Mark as run now
+
+            if tasks_to_run_this_cycle:
+                await asyncio.gather(*tasks_to_run_this_cycle, return_exceptions=True)
+
+            try:
+                # Sleep for a short interval, e.g., 10 seconds, or until stop_event is set
+                await asyncio.wait_for(self._stop_event.wait(), timeout=10.0)
+            except asyncio.TimeoutError:
+                pass # Timeout is normal, means continue loop
+        self._is_running = False
+        logger.info("FlockScheduler loop stopped.")
+
+    async def start(self) -> asyncio.Task | None: # Modified to return Task or None
+        if self._is_running:
+            logger.warning("Scheduler is already running.")
+            return None # Or return the existing task if you store it
+
+        self._load_scheduled_agents_from_flock()
+        if not self._scheduled_tasks:
+            logger.info("No scheduled agents found. Scheduler will not start a loop task.")
+            return None # Return None if no tasks to schedule
+
+        self._stop_event.clear()
+        loop_task = asyncio.create_task(self._scheduler_loop())
+        # Store the task if you need to reference it, e.g., for forced cancellation beyond _stop_event
+        # self._loop_task = loop_task
+        return loop_task # Return the created task
+
+    async def stop(self):
+        if not self._is_running and not self._stop_event.is_set(): # Check if stop already called
+            logger.info("Scheduler is not running or already signaled to stop.")
+            return
+        logger.info("Stopping FlockScheduler...")
+        self._stop_event.set()
+        # If you stored self._loop_task, you can await it here or in the lifespan manager
+        # await self._loop_task # (This might block if loop doesn't exit quickly)

flock/core/logging/logging.py

@@ -68,6 +68,14 @@ COLOR_MAP = {
     "workflow": "cyan",  # Color only
     "activities": "cyan",
     "context": "green",
+    "mcp.server": "blue",
+    "mcp.tool": "cyan",
+    "mcp.client_manager": "light-blue",
+    "mcp.client": "light-cyan",
+    "mcp.callback.logging": "white",
+    "mcp.callback.sampling": "pink",
+    "mcp.callback.root": "light-yellow",
+    "mcp.callback.message": "light-blue",
     # Components & Mechanisms
     "registry": "yellow",  # Color only
     "serialization": "yellow",

flock/core/mcp/flock_mcp_server.py

@@ -26,7 +26,7 @@ from flock.core.serialization.serialization_utils import (
     serialize_item,
 )
 
-logger = get_logger("core.mcp.server_base")
+logger = get_logger("mcp.server")
 tracer = trace.get_tracer(__name__)
 T = TypeVar("T", bound="FlockMCPServerBase")
 
@@ -206,7 +206,6 @@ class FlockMCPServerBase(BaseModel, Serializable, ABC):
             async with self.condition:
                 try:
                     await self.pre_mcp_call()
-                    # TODO: inject additional params here.
                     additional_params: dict[str, Any] = {}
                     additional_params = await self.before_connect(
                         additional_params=additional_params
@@ -314,7 +313,7 @@ class FlockMCPServerBase(BaseModel, Serializable, ABC):
     async def post_terminate(self) -> None:
         """Run post-terminate hooks on modules."""
         logger.debug(
-            f"Running post_terminat hooks for modules in server: '{self.config.name}'"
+            f"Running post_terminate hooks for modules in server: '{self.config.name}'"
         )
         with tracer.start_as_current_span("server.post_terminate") as span:
             span.set_attribute("server.name", self.config.name)
@@ -437,7 +436,7 @@ class FlockMCPServerBase(BaseModel, Serializable, ABC):
 
         FlockRegistry = get_registry()
 
-        exclude = ["modules"]
+        exclude = ["modules", "config"]
 
         logger.debug(f"Serializing server '{self.config.name}' to dict.")
         # Use Pydantic's dump, exclued manually handled fields.
@@ -447,6 +446,11 @@ class FlockMCPServerBase(BaseModel, Serializable, ABC):
             exclude_none=True,  # Exclude None values for cleaner output
         )
 
+        # --- Let the config handle its own serialization ---
+        config_data = self.config.to_dict(path_type=path_type)
+        data["config"] = config_data
+
+
         builtin_by_transport = {}
 
         try:
@@ -454,12 +458,16 @@ class FlockMCPServerBase(BaseModel, Serializable, ABC):
             from flock.mcp.servers.stdio.flock_stdio_server import (
                 FlockMCPStdioServer,
             )
+            from flock.mcp.servers.streamable_http.flock_streamable_http_server import (
+                FlockStreamableHttpServer,
+            )
             from flock.mcp.servers.websockets.flock_websocket_server import (
                 FlockWSServer,
             )
 
             builtin_by_transport = {
                 "stdio": FlockMCPStdioServer,
+                "streamable_http": FlockStreamableHttpServer,
                 "sse": FlockSSEServer,
                 "websockets": FlockWSServer,
             }
@@ -570,6 +578,9 @@ class FlockMCPServerBase(BaseModel, Serializable, ABC):
             from flock.mcp.servers.stdio.flock_stdio_server import (
                 FlockMCPStdioServer,
             )
+            from flock.mcp.servers.streamable_http.flock_streamable_http_server import (
+                FlockStreamableHttpServer,
+            )
             from flock.mcp.servers.websockets.flock_websocket_server import (
                 FlockWSServer,
             )
@@ -577,6 +588,7 @@ class FlockMCPServerBase(BaseModel, Serializable, ABC):
             builtin_by_transport = {
                 "stdio": FlockMCPStdioServer,
                 "sse": FlockSSEServer,
+                "streamable_http": FlockStreamableHttpServer,
                 "websockets": FlockWSServer,
             }
         except ImportError:
@@ -592,6 +604,20 @@ class FlockMCPServerBase(BaseModel, Serializable, ABC):
             transport = data["config"]["connection_config"]["transport_type"]
             real_cls = builtin_by_transport.get(transport, cls)
 
+        # deserialize the config:
+        config_data = data.pop("config", None)
+        if config_data:
+            # Forcing a square into a round hole
+            # pretty ugly, but gets the job done.
+            try:
+                config_field = real_cls.model_fields["config"]
+                config_cls = config_field.annotation
+            except (AttributeError, KeyError):
+                # fallback if Pydantic v1 or missing
+                config_cls = FlockMCPConfigurationBase
+            config_object = config_cls.from_dict(config_data)
+            data["config"] = config_object
+
         # now construct
         server = real_cls(**{k: v for k, v in data.items() if k != "modules"})
 

flock/core/mcp/flock_mcp_tool_base.py

@@ -10,7 +10,7 @@ from pydantic import BaseModel, Field
 
 from flock.core.logging.logging import get_logger
 
-logger = get_logger("core.mcp.tool_base")
+logger = get_logger("mcp.tool")
 tracer = trace.get_tracer(__name__)
 
 T = TypeVar("T", bound="FlockMCPToolBase")