flock-core 0.5.10__py3-none-any.whl → 0.5.20__py3-none-any.whl

flock/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from flock.cli import main
-from flock.orchestrator import Flock, start_orchestrator
+from flock.core import Flock, start_orchestrator
 from flock.registry import flock_tool, flock_type
 
 

flock/agent/__init__.py

@@ -0,0 +1,30 @@
+"""Agent implementation modules.
+
+This package contains internal implementation details for the Agent class.
+
+Phase 5B Additions:
+- BuilderHelpers: PublishBuilder, RunHandle, Pipeline helper classes
+- BuilderValidator: Validation and normalization logic for AgentBuilder
+"""
+
+from flock.agent.builder_helpers import Pipeline, PublishBuilder, RunHandle
+from flock.agent.builder_validator import BuilderValidator
+from flock.agent.component_lifecycle import ComponentLifecycle
+from flock.agent.context_resolver import ContextResolver
+from flock.agent.mcp_integration import MCPIntegration
+from flock.agent.output_processor import OutputProcessor
+from flock.core.visibility import AgentIdentity
+
+
+__all__ = [
+    "AgentIdentity",
+    "BuilderHelpers",
+    "BuilderValidator",
+    "ComponentLifecycle",
+    "ContextResolver",
+    "MCPIntegration",
+    "OutputProcessor",
+    "Pipeline",
+    "PublishBuilder",
+    "RunHandle",
+]

flock/agent/builder_helpers.py

@@ -0,0 +1,192 @@
+"""Helper classes for AgentBuilder fluent API.
+
+Phase 5B: Extracted from agent.py to reduce file size and improve modularity.
+
+This module contains three helper classes that support the fluent builder pattern:
+- PublishBuilder: Enables .only_for() and .visibility() configuration sugar
+- RunHandle: Represents chained agent execution (agent.run().then().execute())
+- Pipeline: Represents sequential agent pipeline execution
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from flock.core.visibility import Visibility, only_for
+
+
+if TYPE_CHECKING:
+    from flock.core import Agent
+    from flock.core.artifacts import Artifact
+
+
+class PublishBuilder:
+    """Helper returned by `.publishes(...)` to support `.only_for` sugar.
+
+    This class enables method chaining after .publishes() calls, allowing
+    conditional visibility configuration and delegation back to AgentBuilder.
+
+    Examples:
+        >>> agent.publishes(Report).only_for("manager", "analyst")
+        >>> agent.publishes(Alert).visibility(PrivateVisibility())
+    """
+
+    def __init__(self, parent: Any, outputs: Sequence[Any]) -> None:
+        """Initialize PublishBuilder.
+
+        Args:
+            parent: AgentBuilder instance to return to for chaining
+            outputs: List of AgentOutput objects to configure
+        """
+        self._parent = parent
+        self._outputs = list(outputs)
+
+    def only_for(self, *agent_names: str) -> Any:
+        """Set visibility to allow only specific agents.
+
+        Convenience method that creates PrivateVisibility with allowlist.
+
+        Args:
+            *agent_names: Names of agents that can see these outputs
+
+        Returns:
+            Parent AgentBuilder for continued method chaining
+
+        Example:
+            >>> agent.publishes(Report).only_for("manager", "analyst")
+        """
+        visibility = only_for(*agent_names)
+        for output in self._outputs:
+            output.default_visibility = visibility
+        return self._parent
+
+    def visibility(self, value: Visibility) -> Any:
+        """Set explicit visibility for published outputs.
+
+        Args:
+            value: Visibility instance (PublicVisibility, PrivateVisibility, etc.)
+
+        Returns:
+            Parent AgentBuilder for continued method chaining
+
+        Example:
+            >>> agent.publishes(Report).visibility(TenantVisibility())
+        """
+        for output in self._outputs:
+            output.default_visibility = value
+        return self._parent
+
+    def __getattr__(self, item):
+        """Delegate unknown attributes to parent AgentBuilder.
+
+        This enables seamless chaining like:
+        >>> agent.publishes(Report).only_for("alice").consumes(Task)
+        """
+        return getattr(self._parent, item)
+
+
+class RunHandle:
+    """Represents a chained run starting from a given agent.
+
+    Enables fluent API for sequential agent execution:
+    >>> await agent1.run(input).then(agent2).then(agent3).execute()
+
+    The chain executes agents in sequence, passing outputs from one to the next.
+    """
+
+    def __init__(self, agent: Agent, inputs: list[BaseModel]) -> None:
+        """Initialize RunHandle.
+
+        Args:
+            agent: First agent in the chain
+            inputs: Initial inputs to process
+        """
+        self.agent = agent
+        self.inputs = inputs
+        self._chain: list[Agent] = [agent]
+
+    def then(self, builder: Any) -> RunHandle:
+        """Add another agent to the execution chain.
+
+        Args:
+            builder: AgentBuilder whose agent to add to chain
+
+        Returns:
+            self for continued chaining
+
+        Example:
+            >>> await agent1.run(task).then(agent2).then(agent3).execute()
+        """
+        self._chain.append(builder.agent)
+        return self
+
+    async def execute(self) -> list[Artifact]:
+        """Execute the agent chain sequentially.
+
+        Runs each agent in order, passing outputs from one as inputs to the next.
+
+        Returns:
+            Final list of artifacts from the last agent in the chain
+
+        Example:
+            >>> results = await agent1.run(input).then(agent2).execute()
+        """
+        orchestrator = self.agent._orchestrator
+        artifacts = await orchestrator.direct_invoke(self.agent, self.inputs)
+        for agent in self._chain[1:]:
+            artifacts = await orchestrator.direct_invoke(agent, artifacts)
+        return artifacts
+
+
+class Pipeline:
+    """Pipeline of agents executed in sequence.
+
+    Alternative to RunHandle for building multi-agent pipelines:
+    >>> pipeline = Pipeline([agent1, agent2, agent3])
+    >>> results = await pipeline.execute()
+    """
+
+    def __init__(self, builders: Sequence[Any]) -> None:
+        """Initialize Pipeline.
+
+        Args:
+            builders: Sequence of AgentBuilder instances
+        """
+        self.builders = list(builders)
+
+    def then(self, builder: Any) -> Pipeline:
+        """Add another agent to the pipeline.
+
+        Args:
+            builder: AgentBuilder to add
+
+        Returns:
+            self for continued chaining
+
+        Example:
+            >>> pipeline = Pipeline([agent1]).then(agent2).then(agent3)
+        """
+        self.builders.append(builder)
+        return self
+
+    async def execute(self) -> list[Artifact]:
+        """Execute all agents in the pipeline sequentially.
+
+        Returns:
+            Final list of artifacts from the last agent
+
+        Example:
+            >>> results = await Pipeline([agent1, agent2, agent3]).execute()
+        """
+        orchestrator = self.builders[0].agent._orchestrator
+        artifacts: list[Artifact] = []
+        for builder in self.builders:
+            inputs = artifacts if artifacts else []
+            artifacts = await orchestrator.direct_invoke(builder.agent, inputs)
+        return artifacts
+
+
+__all__ = ["Pipeline", "PublishBuilder", "RunHandle"]

flock/agent/builder_validator.py

@@ -0,0 +1,169 @@
+"""Validation and normalization logic for AgentBuilder fluent API.
+
+Phase 5B: Extracted from agent.py to reduce file size and improve modularity.
+
+This module contains validation methods that warn about common configuration issues
+and normalization methods that convert dict-based specs to proper dataclass instances.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from flock.core.subscription import BatchSpec, JoinSpec
+
+
+if TYPE_CHECKING:
+    from flock.core import Agent
+
+
+class BuilderValidator:
+    """Validation and normalization logic for AgentBuilder configuration.
+
+    This class provides static methods for:
+    - Warning about feedback loop risks (self-trigger detection)
+    - Warning about excessive best_of or max_concurrency values
+    - Normalizing dict-based JoinSpec and BatchSpec to proper instances
+    """
+
+    @staticmethod
+    def validate_self_trigger_risk(agent: Agent) -> None:
+        """T074: Warn if agent consumes and publishes same type (feedback loop risk).
+
+        Detects when an agent subscribes to and publishes the same artifact type,
+        which could create infinite feedback loops if not configured carefully.
+
+        Args:
+            agent: Agent instance to validate
+        """
+        from flock.logging.logging import get_logger
+
+        logger = get_logger(__name__)
+
+        # Get types agent consumes
+        consuming_types = set()
+        for sub in agent.subscriptions:
+            consuming_types.update(sub.type_names)
+
+        # Get types agent publishes
+        publishing_types = {
+            output.spec.type_name
+            for group in agent.output_groups
+            for output in group.outputs
+        }
+
+        # Check for overlap
+        overlap = consuming_types.intersection(publishing_types)
+        if overlap and agent.prevent_self_trigger:
+            logger.warning(
+                f"Agent '{agent.name}' consumes and publishes {overlap}. "
+                f"Feedback loop risk detected. Agent has prevent_self_trigger=True (safe), "
+                f"but consider adding filtering: .consumes(Type, where=lambda x: ...) "
+                f"or use .prevent_self_trigger(False) for intentional feedback."
+            )
+
+    @staticmethod
+    def validate_best_of(agent_name: str, n: int) -> None:
+        """T074: Warn if best_of value is excessively high.
+
+        High best_of values (>100) dramatically increase cost and latency
+        by running the same evaluation multiple times.
+
+        Args:
+            agent_name: Name of agent being validated
+            n: best_of value to validate
+        """
+        from flock.logging.logging import get_logger
+
+        logger = get_logger(__name__)
+
+        if n > 100:
+            logger.warning(
+                f"Agent '{agent_name}' has best_of({n}) which is very high. "
+                f"Typical values are 3-10. High values increase cost and latency. "
+                f"Consider reducing unless you have specific requirements."
+            )
+
+    @staticmethod
+    def validate_concurrency(agent_name: str, n: int) -> None:
+        """T074: Warn if max_concurrency is excessively high.
+
+        Excessive concurrency (>1000) may overwhelm resources and cause
+        rate limiting, memory issues, or performance degradation.
+
+        Args:
+            agent_name: Name of agent being validated
+            n: max_concurrency value to validate
+        """
+        from flock.logging.logging import get_logger
+
+        logger = get_logger(__name__)
+
+        if n > 1000:
+            logger.warning(
+                f"Agent '{agent_name}' has max_concurrency({n}) which is very high. "
+                f"Typical values are 1-50. Excessive concurrency may cause resource issues. "
+                f"Consider reducing unless you have specific infrastructure."
+            )
+
+    @staticmethod
+    def normalize_join(value: dict | JoinSpec | None) -> JoinSpec | None:
+        """Normalize dict-based JoinSpec to proper JoinSpec instance.
+
+        Converts dict syntax to JoinSpec dataclass for backward compatibility:
+        >>> normalize_join({"by": "user_id", "within": 60.0})
+        JoinSpec(by="user_id", within=timedelta(seconds=60.0))
+
+        Args:
+            value: Either a JoinSpec instance, a dict with join config, or None
+
+        Returns:
+            JoinSpec instance or None
+        """
+        if value is None or isinstance(value, JoinSpec):
+            return value
+
+        # Phase 2: New JoinSpec API with 'by' and 'within' (time OR count)
+        within_value = value.get("within")
+        if isinstance(within_value, (int, float)):
+            # Count window or seconds as float - keep as is
+            within = (
+                int(within_value)
+                if isinstance(within_value, int)
+                else timedelta(seconds=within_value)
+            )
+        else:
+            # Default to 1 minute time window
+            within = timedelta(minutes=1)
+
+        return JoinSpec(
+            by=value["by"],  # Required
+            within=within,
+        )
+
+    @staticmethod
+    def normalize_batch(value: dict | BatchSpec | None) -> BatchSpec | None:
+        """Normalize dict-based BatchSpec to proper BatchSpec instance.
+
+        Converts dict syntax to BatchSpec dataclass for backward compatibility:
+        >>> normalize_batch({"size": 10, "within": 5.0})
+        BatchSpec(size=10, within=5.0, by=None)
+
+        Args:
+            value: Either a BatchSpec instance, a dict with batch config, or None
+
+        Returns:
+            BatchSpec instance or None
+        """
+        if value is None or isinstance(value, BatchSpec):
+            return value
+
+        return BatchSpec(
+            size=int(value.get("size", 1)),
+            within=float(value.get("within", 0.0)),
+            by=value.get("by"),
+        )
+
+
+__all__ = ["BuilderValidator"]