flock-core 0.4.519__py3-none-any.whl → 0.5.0b1__py3-none-any.whl

flock/routers/feedback/feedback_router.py

@@ -1,114 +0,0 @@
-# src/flock/routers/correction/correction_router.py (New File)
-
-from typing import Any
-
-from pydantic import Field
-
-from flock.core.context.context import FlockContext
-from flock.core.flock_agent import FlockAgent
-from flock.core.flock_registry import flock_component
-from flock.core.flock_router import (
-    FlockRouter,
-    FlockRouterConfig,
-    HandOffRequest,
-)
-from flock.core.logging.logging import get_logger
-
-logger = get_logger("router.correction")
-
-
-class FeedbackRetryRouterConfig(FlockRouterConfig):
-    max_retries: int = Field(
-        default=1,
-        description="Maximum number of times to retry the same agent on failure.",
-    )
-    feedback_context_key: str = Field(
-        default="flock.assertion_feedback",
-        description="Context key containing feedback from AssertionCheckerModule.",
-    )
-    retry_count_context_key_prefix: str = Field(
-        default="flock.retry_count_",
-        description="Prefix for context key storing retry attempts per agent.",
-    )
-    fallback_agent: str | None = Field(
-        None, description="Agent to route to if max_retries is exceeded."
-    )
-
-
-@flock_component(config_class=FeedbackRetryRouterConfig)
-class FeedbackRetryRouter(FlockRouter):
-    """Routes based on assertion feedback in the context.
-
-    If feedback exists for the current agent and retries are not exhausted,
-    it routes back to the same agent, adding the feedback to its input.
-    Otherwise, it can route to a fallback agent or stop the chain.
-    """
-
-    name: str = "feedback_retry_router"
-    config: FeedbackRetryRouterConfig = Field(
-        default_factory=FeedbackRetryRouterConfig
-    )
-
-    async def route(
-        self,
-        current_agent: FlockAgent,
-        result: dict[str, Any],
-        context: FlockContext,
-    ) -> HandOffRequest:
-        feedback = context.get_variable(self.config.feedback_context_key)
-
-        if feedback:
-            logger.warning(
-                f"Assertion feedback detected for agent '{current_agent.name}'. Attempting retry."
-            )
-
-            retry_key = f"{self.config.retry_count_context_key_prefix}{current_agent.name}"
-            retry_count = context.get_variable(retry_key, 0)
-            logger.warning(f"Feedback: {feedback} - Retry Count {retry_count}")
-
-            if retry_count < self.config.max_retries:
-                logger.info(
-                    f"Routing back to agent '{current_agent.name}' for retry #{retry_count + 1}"
-                )
-                context.set_variable(retry_key, retry_count + 1)
-                context.set_variable(
-                    f"{current_agent.name}_prev_result", result
-                )
-                # Add feedback to the *next* agent's input (which is the same agent)
-                # Requires the agent's signature to potentially accept a 'feedback' input field.
-                return HandOffRequest(
-                    next_agent=current_agent.name,
-                    output_to_input_merge_strategy="match",  # Add feedback to existing context/previous results
-                    add_input_fields=[
-                        f"{self.config.feedback_context_key} | Feedback for prev result",
-                        f"{current_agent.name}_prev_result | Previous Result",
-                    ],
-                    add_description=f"Try to fix the previous result based on the feedback.",
-                    override_context=None,  # Context already updated with feedback and retry count
-                )
-            else:
-                logger.error(
-                    f"Max retries ({self.config.max_retries}) exceeded for agent '{current_agent.name}'."
-                )
-                # Max retries exceeded, route to fallback or stop
-                if self.config.fallback_agent:
-                    logger.info(
-                        f"Routing to fallback agent '{self.config.fallback_agent}'"
-                    )
-                    # Clear feedback before going to fallback? Optional.
-                    if self.config.feedback_context_key in context.state:
-                        del context.state[self.config.feedback_context_key]
-                    return HandOffRequest(next_agent=self.config.fallback_agent)
-                else:
-                    logger.info("No fallback agent defined. Stopping workflow.")
-                    return HandOffRequest(next_agent="")  # Stop the chain
-
-        else:
-            # No feedback, assertions passed or module not configured for feedback
-            logger.debug(
-                f"No assertion feedback for agent '{current_agent.name}'. Proceeding normally."
-            )
-            # Default behavior: Stop the chain if no other routing is defined
-            # In a real system, you might chain this with another router (e.g., LLMRouter)
-            # to decide the *next different* agent if assertions passed.
-            return HandOffRequest(next_agent="")  # Stop or pass to next router

flock/routers/list_generator/list_generator_router.py

@@ -1,166 +0,0 @@
-# src/flock/routers/list_generator/iterative_list_router.py (New File)
-
-from typing import Any
-
-from pydantic import Field
-
-from flock.core.context.context import FlockContext
-from flock.core.flock_agent import FlockAgent
-from flock.core.flock_registry import flock_component
-from flock.core.flock_router import (
-    FlockRouter,
-    FlockRouterConfig,
-    HandOffRequest,
-)
-from flock.core.logging.logging import get_logger
-
-# Need signature utils
-
-logger = get_logger("router.list_generator")
-
-
-class IterativeListGeneratorRouterConfig(FlockRouterConfig):
-    target_list_field: str = Field(
-        ...,
-        description="Name of the final list output field (e.g., 'chapters').",
-    )
-    item_output_field: str = Field(
-        ...,
-        description="Name of the single item output field for each iteration (e.g., 'chapter').",
-    )
-    context_input_field: str = Field(
-        default="previous_items",
-        description="Input field name for passing back generated items (e.g., 'existing_chapters').",
-    )
-    max_iterations: int = Field(
-        default=10, description="Maximum number of items to generate."
-    )
-    # More advanced: termination_condition: Optional[Callable] = None
-    # Store iteration state in context under this prefix
-    context_state_prefix: str = Field(
-        default="flock.iterator_state_",
-        description="Prefix for context keys storing iteration state.",
-    )
-
-    # Field to extract item type from target_list_field signature
-    # This might require parsing the original agent's output signature
-    # item_type_str: Optional[str] = None # e.g., 'dict[str, str]' or 'MyChapterType'
-
-
-@flock_component(config_class=IterativeListGeneratorRouterConfig)
-class IterativeListGeneratorRouter(FlockRouter):
-    name: str = "iterative_list_generator"
-    config: IterativeListGeneratorRouterConfig = Field(
-        default_factory=IterativeListGeneratorRouterConfig
-    )
-
-    # Helper to get state keys
-    def _get_state_keys(self, agent_name: str) -> tuple[str, str]:
-        prefix = self.config.context_state_prefix
-        list_key = f"{prefix}{agent_name}_{self.config.target_list_field}"
-        count_key = f"{prefix}{agent_name}_iteration_count"
-        return list_key, count_key
-
-    async def route(
-        self,
-        current_agent: FlockAgent,
-        result: dict[str, Any],
-        context: FlockContext,
-    ) -> HandOffRequest:
-        list_key, count_key = self._get_state_keys(current_agent.name)
-
-        # --- State Initialization (First Run) ---
-        if count_key not in context.state:
-            logger.debug(
-                f"Initializing iterative list generation for '{self.config.target_list_field}' in agent '{current_agent.name}'."
-            )
-            context.set_variable(count_key, 0)
-            context.set_variable(list_key, [])
-            # Modify agent signature for the *first* iteration (remove context_input_field, use item_output_field)
-            # This requires modifying the agent's internal state or creating a temporary one.
-            # Let's try modifying the context passed to the *next* run instead.
-            context.set_variable(
-                f"{current_agent.name}.next_run_output_field",
-                self.config.item_output_field,
-            )
-            context.set_variable(
-                f"{current_agent.name}.next_run_input_fields_to_exclude",
-                {self.config.context_input_field},
-            )
-
-        # --- Process Result of Previous Iteration ---
-        iteration_count = context.get_variable(count_key, 0)
-        generated_items = context.get_variable(list_key, [])
-
-        # Get the single item generated in the *last* run
-        # The result dict should contain the 'item_output_field' if it wasn't the very first run
-        new_item = result.get(self.config.item_output_field)
-
-        if (
-            new_item is not None and iteration_count > 0
-        ):  # Add item from previous run (not the init run)
-            generated_items.append(new_item)
-            context.set_variable(list_key, generated_items)  # Update context
-            logger.info(
-                f"Added item #{iteration_count} to list '{self.config.target_list_field}' for agent '{current_agent.name}'."
-            )
-        elif iteration_count > 0:
-            logger.warning(
-                f"Iteration {iteration_count} for agent '{current_agent.name}' did not produce expected output field '{self.config.item_output_field}'."
-            )
-            # Decide how to handle: stop, retry, continue? Let's continue for now.
-
-        # Increment iteration count *after* processing the result of the previous one
-        current_iteration = iteration_count + 1
-        context.set_variable(count_key, current_iteration)
-
-        # --- Termination Check ---
-        if current_iteration > self.config.max_iterations:
-            logger.info(
-                f"Max iterations ({self.config.max_iterations}) reached for '{self.config.target_list_field}' in agent '{current_agent.name}'. Finalizing."
-            )
-            # Clean up state
-            del context.state[count_key]
-            # Final result should be the list itself under the target_list_field key
-            final_result = {self.config.target_list_field: generated_items}
-            # Handoff with empty next_agent to stop, but potentially override the *result*
-            # This is tricky. Routers usually decide the *next agent*, not the *final output*.
-            # Maybe the router should just signal termination, and the Flock run loop handles assembling the final output?
-            # Let's assume the router signals termination by returning next_agent=""
-            # The final list is already in the context under list_key.
-            # A final "AssemblerAgent" could read this context variable.
-            # OR we modify the HandOffRequest:
-            return HandOffRequest(
-                next_agent="", final_output_override=final_result
-            )  # Needs HandOffRequest modification
-
-        # --- Prepare for Next Iteration ---
-        logger.info(
-            f"Routing back to agent '{current_agent.name}' for item #{current_iteration} of '{self.config.target_list_field}'."
-        )
-
-        # The agent needs the context (previously generated items) and the original inputs again.
-        # We will pass the generated items via the context_input_field.
-        # The original inputs (like story_outline) should still be in the context.
-        next_input_override = {
-            self.config.context_input_field: generated_items  # Pass the list back
-        }
-
-        # Modify agent signature for the *next* iteration (add context_input_field, use item_output_field)
-        # This is the trickiest part - how to modify the agent's perceived signature for the next run?
-        # Option 1: Pass overrides via HandOffRequest (cleanest)
-        next_signature_input = f"{current_agent.input}, {self.config.context_input_field}: list | Previously generated items"  # Needs smarter joining
-        next_signature_output = (
-            self.config.item_output_field
-        )  # Only ask for one item
-
-        # This requires HandOffRequest and Flock execution loop to support signature overrides
-        return HandOffRequest(
-            next_agent=current_agent.name,
-            output_to_input_merge_strategy="add",  # Add the context_input_field to existing context
-            input_override=next_input_override,  # Provide the actual list data
-            # --- Hypothetical Overrides ---
-            next_run_input_signature_override=next_signature_input,
-            next_run_output_signature_override=next_signature_output,
-            # -----------------------------
-        )

flock/routers/llm/__init__.py

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

flock/routers/llm/llm_router.py

@@ -1,365 +0,0 @@
-"""LLM-based router implementation for the Flock framework."""
-
-import json
-from typing import Any
-
-import litellm
-
-from flock.core.context.context import FlockContext
-from flock.core.flock_agent import FlockAgent
-from flock.core.flock_registry import flock_component
-from flock.core.flock_router import (
-    FlockRouter,
-    FlockRouterConfig,
-    HandOffRequest,
-)
-from flock.core.logging.logging import get_logger
-
-logger = get_logger("llm_router")
-
-
-class LLMRouterConfig(FlockRouterConfig):
-    """Configuration for the LLM router.
-
-    This class extends FlockRouterConfig with parameters specific to the LLM router.
-    """
-
-    temperature: float = 0.2
-    max_tokens: int = 500
-    confidence_threshold: float = 0.5
-    prompt: str = ""
-
-
-@flock_component(config_class=LLMRouterConfig)
-class LLMRouter(FlockRouter):
-    """Router that uses an LLM to determine the next agent in a workflow.
-
-    This class is responsible for:
-    1. Analyzing available agents in the registry
-    2. Using an LLM to score each agent's suitability as the next step
-    3. Selecting the highest-scoring agent
-    4. Creating a HandOff object with the selected agent
-    """
-
-    def __init__(
-        self,
-        name: str = "llm_router",
-        config: LLMRouterConfig | None = None,
-    ):
-        """Initialize the LLMRouter.
-
-        Args:
-            registry: The agent registry containing all available agents
-            name: The name of the router
-            config: The router configuration
-        """
-        logger.info(f"Initializing LLM Router '{name}'")
-        super().__init__(name=name, config=config or LLMRouterConfig(name=name))
-        logger.debug(
-            "LLM Router configuration",
-            temperature=self.config.temperature,
-            max_tokens=self.config.max_tokens,
-        )
-
-    async def route(
-        self,
-        current_agent: FlockAgent,
-        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
-        """
-        logger.info(
-            f"Routing from agent '{current_agent.name}'",
-            current_agent=current_agent.name,
-        )
-        logger.debug("Current agent result", result=result)
-
-        agent_definitions = context.agent_definitions
-        # Get all available agents from the registry
-        available_agents = self._get_available_agents(
-            agent_definitions, current_agent.name
-        )
-        logger.debug(
-            "Available agents for routing",
-            count=len(available_agents),
-            agents=[a.agent_data["name"] for a in available_agents],
-        )
-
-        if not available_agents:
-            logger.warning(
-                "No available agents for routing",
-                current_agent=current_agent.name,
-            )
-            return HandOffRequest(
-                next_agent="", override_next_agent={}, override_context=None
-            )
-
-        # Use LLM to determine the best next agent
-        next_agent_name, score = await self._select_next_agent(
-            current_agent, result, available_agents
-        )
-        logger.info(
-            "Agent selection result",
-            next_agent=next_agent_name,
-            score=score,
-        )
-
-        if not next_agent_name or score < self.config.confidence_threshold:
-            logger.warning(
-                "No suitable next agent found",
-                best_score=score,
-            )
-            return HandOffRequest(
-                next_agent="", override_next_agent={}, override_context=None
-            )
-
-        # Get the next agent from the registry
-        next_agent = agent_definitions.get(next_agent_name)
-        if not next_agent:
-            logger.error(
-                "Selected agent not found in registry",
-                agent_name=next_agent_name,
-            )
-            return HandOffRequest(
-                next_agent="", override_next_agent={}, override_context=None
-            )
-
-        # Create input for the next agent
-
-        logger.success(
-            f"Successfully routed to agent '{next_agent_name}'",
-            score=score,
-            from_agent=current_agent.name,
-        )
-        return HandOffRequest(
-            next_agent=next_agent_name,
-            output_to_input_merge_strategy="add",
-            override_next_agent=None,
-            override_context=None,
-        )
-
-    def _get_available_agents(
-        self, agent_definitions: dict[str, Any], current_agent_name: str
-    ) -> list[FlockAgent]:
-        """Get all available agents except the current one.
-
-        Args:
-            current_agent_name: Name of the current agent to exclude
-
-        Returns:
-            List of available agents
-        """
-        logger.debug(
-            "Getting available agents",
-            total_agents=len(agent_definitions),
-            current_agent=current_agent_name,
-        )
-        agents = []
-        for agent in agent_definitions:
-            if agent != current_agent_name:
-                agents.append(agent_definitions.get(agent))
-        return agents
-
-    async def _select_next_agent(
-        self,
-        current_agent: FlockAgent,
-        result: dict[str, Any],
-        available_agents: list[FlockAgent],
-    ) -> tuple[str, float]:
-        """Use an LLM to select the best next agent.
-
-        Args:
-            current_agent: The agent that just completed execution
-            result: The output from the current agent
-            available_agents: List of available agents to choose from
-
-        Returns:
-            Tuple of (selected_agent_name, confidence_score)
-        """
-        logger.debug(
-            "Selecting next agent",
-            current_agent=current_agent.name,
-            available_count=len(available_agents),
-        )
-
-        # Prepare the prompt for the LLM
-        prompt = self._create_selection_prompt(
-            current_agent, result, available_agents
-        )
-        logger.debug("Generated selection prompt", prompt_length=len(prompt))
-
-        try:
-            logger.info(
-                "Calling LLM for agent selection",
-                model=current_agent.model,
-                temperature=self.config.temperature,
-            )
-            # Call the LLM to get the next agent
-            response = await litellm.acompletion(
-                model=current_agent.model,
-                messages=[{"role": "user", "content": prompt}],
-                temperature=self.config.temperature
-                if isinstance(self.config, LLMRouterConfig)
-                else 0.2,
-                max_tokens=self.config.max_tokens
-                if isinstance(self.config, LLMRouterConfig)
-                else 500,
-            )
-
-            content = response.choices[0].message.content
-            # Parse the response to get the agent name and score
-            try:
-                # extract the json object from the response
-                content = content.split("```json")[1].split("```")[0]
-                data = json.loads(content)
-                next_agent = data.get("next_agent", "")
-                score = float(data.get("score", 0))
-                reasoning = data.get("reasoning", "")
-                logger.info(
-                    "Successfully parsed LLM response",
-                    next_agent=next_agent,
-                    score=score,
-                    reasoning=reasoning,
-                )
-                return next_agent, score
-            except (json.JSONDecodeError, ValueError) as e:
-                logger.error(
-                    "Failed to parse LLM response",
-                    error=str(e),
-                    raw_response=content,
-                )
-                logger.debug("Attempting fallback parsing")
-
-                # Fallback: try to extract the agent name from the text
-                for agent in available_agents:
-                    if agent.agent_data["name"] in content:
-                        logger.info(
-                            "Found agent name in response using fallback",
-                            agent=agent.agent_data["name"],
-                        )
-                        return agent.agent_data[
-                            "name"
-                        ], 0.6  # Default score for fallback
-
-                return "", 0.0
-
-        except Exception as e:
-            logger.error(
-                "Error calling LLM for agent selection",
-                error=str(e),
-                current_agent=current_agent.name,
-            )
-            return "", 0.0
-
-    def _create_selection_prompt(
-        self,
-        current_agent: FlockAgent,
-        result: dict[str, Any],
-        available_agents: list[FlockAgent],
-    ) -> str:
-        """Create a prompt for the LLM to select the next agent.
-
-        Args:
-            current_agent: The agent that just completed execution
-            result: The output from the current agent
-            available_agents: List of available agents to choose from
-
-        Returns:
-            Prompt string for the LLM
-        """
-        # Format the current agent's output
-        result_str = json.dumps(result, indent=2)
-
-        # Format the available agents' information
-        agents_info = []
-        for agent in available_agents:
-            agent_info = {
-                "name": agent.agent_data["name"],
-                "description": agent.agent_data["description"]
-                if agent.agent_data["description"]
-                else "",
-                "input": agent.agent_data["input"],
-                "output": agent.agent_data["output"],
-            }
-            agents_info.append(agent_info)
-
-        agents_str = json.dumps(agents_info, indent=2)
-
-        # Create the prompt
-        if self.config.prompt:
-            prompt = self.config.prompt
-        else:
-            prompt = f"""
-You are a workflow router that determines the next agent to execute in a multi-agent system.
-
-CURRENT AGENT:
-Name: {current_agent.name}
-Description: {current_agent.description}
-Input: {current_agent.input}
-Output: {current_agent.output}
-
-CURRENT AGENT'S OUTPUT:
-{result_str}
-
-AVAILABLE AGENTS:
-{agents_str}
-
-Based on the current agent's output and the available agents, determine which agent should be executed next.
-Consider the following:
-1. Which agent's input requirements best match the current agent's output?
-2. Which agent's purpose and description make it the most logical next step?
-3. Which agent would provide the most value in continuing the workflow?
-
-Respond with a JSON object containing:
-1. "next_agent": The name of the selected agent
-2. "score": A confidence score between 0 and 1 indicating how suitable this agent is
-3. "reasoning": A brief explanation of why this agent was selected
-
-If no agent is suitable, set "next_agent" to an empty string and "score" to 0.
-
-JSON Response:
-"""
-        return prompt
-
-    def _create_next_input(
-        self,
-        current_agent: FlockAgent,
-        result: dict[str, Any],
-        next_agent: FlockAgent,
-    ) -> dict[str, Any]:
-        """Create the input for the next agent, including the previous agent's output.
-
-        Args:
-            current_agent: The agent that just completed execution
-            result: The output from the current agent
-            next_agent: The next agent to execute
-
-        Returns:
-            Input dictionary for the next agent
-        """
-        # Start with an empty input
-        next_input = {}
-
-        # Add a special field for the previous agent's output
-        next_input["previous_agent_output"] = {
-            "agent_name": current_agent.name,
-            "result": result,
-        }
-
-        # Try to map the current agent's output to the next agent's input
-        # This is a simple implementation that could be enhanced with more sophisticated mapping
-        for key in result:
-            # If the next agent expects this key, add it directly
-            if key in next_agent.input:
-                next_input[key] = result[key]
-
-        return next_input