flock-core 0.5.11__py3-none-any.whl → 0.5.21__py3-none-any.whl

flock/{orchestrator_component.py → components/orchestrator/base.py}

@@ -9,18 +9,17 @@ from typing import TYPE_CHECKING
 
 from pydantic import BaseModel, Field
 
-from flock.components import TracedModelMeta
+from flock.components.agent.base import TracedModelMeta
 from flock.logging.logging import get_logger
 
 
 if TYPE_CHECKING:
-    from flock.agent import Agent
-    from flock.artifacts import Artifact
-    from flock.orchestrator import Flock
-    from flock.subscription import Subscription
+    from flock.core import Agent, Flock
+    from flock.core.artifacts import Artifact
+    from flock.core.subscription import Subscription
 
 # Initialize logger for components
-logger = get_logger("flock.component")
+logger = get_logger("flock.components.orchestrator")
 
 
 class ScheduleDecision(str, Enum):
@@ -401,295 +400,8 @@ class OrchestratorComponent(BaseModel, metaclass=TracedModelMeta):
         """
 
 
-class BuiltinCollectionComponent(OrchestratorComponent):
-    """Built-in component that handles AND gates, correlation, and batching.
-
-    This component wraps the existing ArtifactCollector, CorrelationEngine,
-    and BatchEngine to provide collection logic via the component system.
-
-    Priority: 100 (runs after user components for circuit breaking/dedup)
-    """
-
-    priority: int = 100  # Run late (after circuit breaker/dedup components)
-    name: str = "builtin_collection"
-
-    async def on_collect_artifacts(
-        self,
-        orchestrator: Flock,
-        artifact: Artifact,
-        agent: Agent,
-        subscription: Subscription,
-    ) -> CollectionResult | None:
-        """Handle AND gates, correlation (JoinSpec), and batching (BatchSpec).
-
-        This maintains backward compatibility with existing collection engines
-        while allowing user components to override collection logic.
-        """
-        from datetime import timedelta
-
-        # Check if subscription has required attributes (defensive for mocks/tests)
-        if (
-            not hasattr(subscription, "join")
-            or not hasattr(subscription, "type_models")
-            or not hasattr(subscription, "batch")
-        ):
-            # Fallback: immediate with single artifact
-            return CollectionResult.immediate([artifact])
-
-        # JoinSpec CORRELATION: Check if subscription has correlated AND gate
-        if subscription.join is not None:
-            subscription_index = agent.subscriptions.index(subscription)
-            completed_group = orchestrator._correlation_engine.add_artifact(
-                artifact=artifact,
-                subscription=subscription,
-                subscription_index=subscription_index,
-            )
-
-            # Start correlation cleanup task if time-based window
-            if (
-                isinstance(subscription.join.within, timedelta)
-                and orchestrator._correlation_cleanup_task is None
-            ):
-                import asyncio
-
-                orchestrator._correlation_cleanup_task = asyncio.create_task(
-                    orchestrator._correlation_cleanup_loop()
-                )
-
-            if completed_group is None:
-                # Still waiting for correlation to complete
-                await orchestrator._emit_correlation_updated_event(
-                    agent_name=agent.name,
-                    subscription_index=subscription_index,
-                    artifact=artifact,
-                )
-                return CollectionResult.waiting()
-
-            # Correlation complete!
-            artifacts = completed_group.get_artifacts()
-        else:
-            # AND GATE: Use artifact collector for simple AND gates (no correlation)
-            is_complete, artifacts = orchestrator._artifact_collector.add_artifact(
-                agent, subscription, artifact
-            )
-
-            if not is_complete:
-                return CollectionResult.waiting()
-
-        # BatchSpec BATCHING: Check if subscription has batch accumulator
-        if subscription.batch is not None:
-            subscription_index = agent.subscriptions.index(subscription)
-
-            # Treat artifact groups as single batch items
-            if subscription.join is not None or len(subscription.type_models) > 1:
-                should_flush = orchestrator._batch_engine.add_artifact_group(
-                    artifacts=artifacts,
-                    subscription=subscription,
-                    subscription_index=subscription_index,
-                )
-
-                if (
-                    subscription.batch.timeout
-                    and orchestrator._batch_timeout_task is None
-                ):
-                    import asyncio
-
-                    orchestrator._batch_timeout_task = asyncio.create_task(
-                        orchestrator._batch_timeout_checker_loop()
-                    )
-            else:
-                # Single type: Add each artifact individually
-                should_flush = False
-                for single_artifact in artifacts:
-                    should_flush = orchestrator._batch_engine.add_artifact(
-                        artifact=single_artifact,
-                        subscription=subscription,
-                        subscription_index=subscription_index,
-                    )
-
-                    if (
-                        subscription.batch.timeout
-                        and orchestrator._batch_timeout_task is None
-                    ):
-                        import asyncio
-
-                        orchestrator._batch_timeout_task = asyncio.create_task(
-                            orchestrator._batch_timeout_checker_loop()
-                        )
-
-                    if should_flush:
-                        break
-
-            if not should_flush:
-                # Batch not full yet
-                await orchestrator._emit_batch_item_added_event(
-                    agent_name=agent.name,
-                    subscription_index=subscription_index,
-                    subscription=subscription,
-                    artifact=artifact,
-                )
-                return CollectionResult.waiting()
-
-            # Flush batch
-            batched_artifacts = orchestrator._batch_engine.flush_batch(
-                agent.name, subscription_index
-            )
-
-            if batched_artifacts is None:
-                return CollectionResult.waiting()
-
-            artifacts = batched_artifacts
-
-        # Collection complete!
-        return CollectionResult.immediate(artifacts)
-
-
-class CircuitBreakerComponent(OrchestratorComponent):
-    """Circuit breaker to prevent runaway agent loops.
-
-    Tracks iteration count per agent and blocks scheduling when limit is reached.
-    Automatically resets counters when orchestrator becomes idle.
-
-    Priority: 10 (runs early, before deduplication)
-
-    Configuration:
-        max_iterations: Maximum iterations per agent before circuit breaker trips
-
-    Examples:
-        >>> # Use default (1000 iterations)
-        >>> flock = Flock("openai/gpt-4.1")
-
-        >>> # Custom limit
-        >>> flock = Flock("openai/gpt-4.1")
-        >>> for component in flock._components:
-        ...     if component.name == "circuit_breaker":
-        ...         component.max_iterations = 500
-    """
-
-    priority: int = 10  # Run early (before dedup at 20)
-    name: str = "circuit_breaker"
-    max_iterations: int = 1000  # Default from orchestrator
-
-    def __init__(self, max_iterations: int = 1000, **kwargs):
-        """Initialize circuit breaker with iteration limit.
-
-        Args:
-            max_iterations: Maximum iterations per agent (default 1000)
-        """
-        super().__init__(**kwargs)
-        self.max_iterations = max_iterations
-        self._iteration_counts: dict[str, int] = {}
-
-    async def on_before_schedule(
-        self,
-        orchestrator: Flock,
-        artifact: Artifact,
-        agent: Agent,
-        subscription: Subscription,
-    ) -> ScheduleDecision:
-        """Check if agent has exceeded iteration limit.
-
-        Returns SKIP if agent has reached max_iterations, preventing
-        potential infinite loops.
-
-        Uses orchestrator.max_agent_iterations if available, otherwise
-        falls back to self.max_iterations.
-        """
-        current_count = self._iteration_counts.get(agent.name, 0)
-
-        # Check orchestrator property first (allows runtime modification)
-        # Fall back to component's max_iterations if orchestrator property doesn't exist
-        max_limit = self.max_iterations
-        if hasattr(orchestrator, "max_agent_iterations"):
-            orch_limit = orchestrator.max_agent_iterations
-            # Only use orchestrator limit if it's a valid int
-            if isinstance(orch_limit, int):
-                max_limit = orch_limit
-
-        if current_count >= max_limit:
-            # Circuit breaker tripped
-            return ScheduleDecision.SKIP
-
-        # Increment counter
-        self._iteration_counts[agent.name] = current_count + 1
-        return ScheduleDecision.CONTINUE
-
-    async def on_orchestrator_idle(self, orchestrator: Flock) -> None:
-        """Reset iteration counters when orchestrator becomes idle.
-
-        This prevents the circuit breaker from permanently blocking agents
-        across different workflow runs.
-        """
-        self._iteration_counts.clear()
-
-
-class DeduplicationComponent(OrchestratorComponent):
-    """Deduplication to prevent agents from processing same artifact multiple times.
-
-    Tracks which artifacts have been processed by which agents and skips
-    duplicate scheduling attempts.
-
-    Priority: 20 (runs after circuit breaker at 10)
-
-    Examples:
-        >>> # Auto-added to all orchestrators
-        >>> flock = Flock("openai/gpt-4.1")
-
-        >>> # Deduplication prevents:
-        >>> # - Agents re-processing artifacts they already handled
-        >>> # - Feedback loops from agent self-triggers
-        >>> # - Duplicate work from retry logic
-    """
-
-    priority: int = 20  # Run after circuit breaker (10)
-    name: str = "deduplication"
-
-    def __init__(self, **kwargs):
-        """Initialize deduplication with empty processed set."""
-        super().__init__(**kwargs)
-        self._processed: set[tuple[str, str]] = set()  # (artifact_id, agent_name)
-
-    async def on_before_schedule(
-        self,
-        orchestrator: Flock,
-        artifact: Artifact,
-        agent: Agent,
-        subscription: Subscription,
-    ) -> ScheduleDecision:
-        """Check if artifact has already been processed by this agent.
-
-        Returns SKIP if agent has already processed this artifact,
-        preventing duplicate work.
-        """
-        key = (str(artifact.id), agent.name)
-
-        if key in self._processed:
-            # Already processed - skip
-            return ScheduleDecision.SKIP
-
-        # Not yet processed - allow
-        return ScheduleDecision.CONTINUE
-
-    async def on_before_agent_schedule(
-        self, orchestrator: Flock, agent: Agent, artifacts: list[Artifact]
-    ) -> list[Artifact]:
-        """Mark artifacts as processed before agent execution.
-
-        This ensures artifacts are marked as seen even if agent execution fails,
-        preventing infinite retry loops.
-        """
-        for artifact in artifacts:
-            key = (str(artifact.id), agent.name)
-            self._processed.add(key)
-
-        return artifacts
-
-
 __all__ = [
-    "BuiltinCollectionComponent",
-    "CircuitBreakerComponent",
     "CollectionResult",
-    "DeduplicationComponent",
     "OrchestratorComponent",
     "OrchestratorComponentConfig",
     "ScheduleDecision",

flock/components/orchestrator/circuit_breaker.py

@@ -0,0 +1,95 @@
+"""Circuit breaker component to prevent runaway agent loops."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from flock.components.orchestrator.base import OrchestratorComponent, ScheduleDecision
+
+
+if TYPE_CHECKING:
+    from flock.core import Agent, Flock
+    from flock.core.artifacts import Artifact
+    from flock.core.subscription import Subscription
+
+
+class CircuitBreakerComponent(OrchestratorComponent):
+    """Circuit breaker to prevent runaway agent loops.
+
+    Tracks iteration count per agent and blocks scheduling when limit is reached.
+    Automatically resets counters when orchestrator becomes idle.
+
+    Priority: 10 (runs early, before deduplication)
+
+    Configuration:
+        max_iterations: Maximum iterations per agent before circuit breaker trips
+
+    Examples:
+        >>> # Use default (1000 iterations)
+        >>> flock = Flock("openai/gpt-4.1")
+
+        >>> # Custom limit
+        >>> flock = Flock("openai/gpt-4.1")
+        >>> for component in flock._components:
+        ...     if component.name == "circuit_breaker":
+        ...         component.max_iterations = 500
+    """
+
+    priority: int = 10  # Run early (before dedup at 20)
+    name: str = "circuit_breaker"
+    max_iterations: int = 1000  # Default from orchestrator
+
+    def __init__(self, max_iterations: int = 1000, **kwargs):
+        """Initialize circuit breaker with iteration limit.
+
+        Args:
+            max_iterations: Maximum iterations per agent (default 1000)
+        """
+        super().__init__(**kwargs)
+        self.max_iterations = max_iterations
+        self._iteration_counts: dict[str, int] = {}
+
+    async def on_before_schedule(
+        self,
+        orchestrator: Flock,
+        artifact: Artifact,
+        agent: Agent,
+        subscription: Subscription,
+    ) -> ScheduleDecision:
+        """Check if agent has exceeded iteration limit.
+
+        Returns SKIP if agent has reached max_iterations, preventing
+        potential infinite loops.
+
+        Uses orchestrator.max_agent_iterations if available, otherwise
+        falls back to self.max_iterations.
+        """
+        current_count = self._iteration_counts.get(agent.name, 0)
+
+        # Check orchestrator property first (allows runtime modification)
+        # Fall back to component's max_iterations if orchestrator property doesn't exist
+        max_limit = self.max_iterations
+        if hasattr(orchestrator, "max_agent_iterations"):
+            orch_limit = orchestrator.max_agent_iterations
+            # Only use orchestrator limit if it's a valid int
+            if isinstance(orch_limit, int):
+                max_limit = orch_limit
+
+        if current_count >= max_limit:
+            # Circuit breaker tripped
+            return ScheduleDecision.SKIP
+
+        # Increment counter
+        self._iteration_counts[agent.name] = current_count + 1
+        return ScheduleDecision.CONTINUE
+
+    async def on_orchestrator_idle(self, orchestrator: Flock) -> None:
+        """Reset iteration counters when orchestrator becomes idle.
+
+        This prevents the circuit breaker from permanently blocking agents
+        across different workflow runs.
+        """
+        self._iteration_counts.clear()
+
+
+__all__ = ["CircuitBreakerComponent"]

flock/components/orchestrator/collection.py

@@ -0,0 +1,143 @@
+"""Built-in collection component for AND gates, correlation, and batching."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from flock.components.orchestrator.base import (
+    CollectionResult,
+    OrchestratorComponent,
+)
+
+
+if TYPE_CHECKING:
+    from flock.core import Agent, Flock
+    from flock.core.artifacts import Artifact
+    from flock.core.subscription import Subscription
+
+
+class BuiltinCollectionComponent(OrchestratorComponent):
+    """Built-in component that handles AND gates, correlation, and batching.
+
+    This component wraps the existing ArtifactCollector, CorrelationEngine,
+    and BatchEngine to provide collection logic via the component system.
+
+    Priority: 100 (runs after user components for circuit breaking/dedup)
+    """
+
+    priority: int = 100  # Run late (after circuit breaker/dedup components)
+    name: str = "builtin_collection"
+
+    async def on_collect_artifacts(
+        self,
+        orchestrator: Flock,
+        artifact: Artifact,
+        agent: Agent,
+        subscription: Subscription,
+    ) -> CollectionResult | None:
+        """Handle AND gates, correlation (JoinSpec), and batching (BatchSpec).
+
+        Provides collection logic via the component system, allowing user
+        components to override if needed.
+        """
+        from datetime import timedelta
+
+        # Check if subscription has required attributes (defensive for mocks/tests)
+        if (
+            not hasattr(subscription, "join")
+            or not hasattr(subscription, "type_models")
+            or not hasattr(subscription, "batch")
+        ):
+            # Fallback: immediate with single artifact
+            return CollectionResult.immediate([artifact])
+
+        # JoinSpec CORRELATION: Check if subscription has correlated AND gate
+        if subscription.join is not None:
+            subscription_index = agent.subscriptions.index(subscription)
+            completed_group = orchestrator._correlation_engine.add_artifact(
+                artifact=artifact,
+                subscription=subscription,
+                subscription_index=subscription_index,
+            )
+
+            # Phase 5A: Start correlation cleanup task if time-based window (delegate to LifecycleManager)
+            if isinstance(subscription.join.within, timedelta):
+                await orchestrator._lifecycle_manager.start_correlation_cleanup()
+
+            if completed_group is None:
+                # Still waiting for correlation to complete
+                await orchestrator._emit_correlation_updated_event(
+                    agent_name=agent.name,
+                    subscription_index=subscription_index,
+                    artifact=artifact,
+                )
+                return CollectionResult.waiting()
+
+            # Correlation complete!
+            artifacts = completed_group.get_artifacts()
+        else:
+            # AND GATE: Use artifact collector for simple AND gates (no correlation)
+            is_complete, artifacts = orchestrator._artifact_collector.add_artifact(
+                agent, subscription, artifact
+            )
+
+            if not is_complete:
+                return CollectionResult.waiting()
+
+        # BatchSpec BATCHING: Check if subscription has batch accumulator
+        if subscription.batch is not None:
+            subscription_index = agent.subscriptions.index(subscription)
+
+            # Treat artifact groups as single batch items
+            if subscription.join is not None or len(subscription.type_models) > 1:
+                should_flush = orchestrator._batch_engine.add_artifact_group(
+                    artifacts=artifacts,
+                    subscription=subscription,
+                    subscription_index=subscription_index,
+                )
+
+                # Phase 5A: Start batch timeout checker if batch has timeout (delegate to LifecycleManager)
+                if subscription.batch.timeout:
+                    await orchestrator._lifecycle_manager.start_batch_timeout_checker()
+            else:
+                # Single type: Add each artifact individually
+                should_flush = False
+                for single_artifact in artifacts:
+                    should_flush = orchestrator._batch_engine.add_artifact(
+                        artifact=single_artifact,
+                        subscription=subscription,
+                        subscription_index=subscription_index,
+                    )
+
+                    # Phase 5A: Start batch timeout checker if batch has timeout (delegate to LifecycleManager)
+                    if subscription.batch.timeout:
+                        await orchestrator._lifecycle_manager.start_batch_timeout_checker()
+
+                    if should_flush:
+                        break
+
+            if not should_flush:
+                # Batch not full yet
+                await orchestrator._emit_batch_item_added_event(
+                    agent_name=agent.name,
+                    subscription_index=subscription_index,
+                    subscription=subscription,
+                    artifact=artifact,
+                )
+                return CollectionResult.waiting()
+
+            # Flush batch
+            batched_artifacts = orchestrator._batch_engine.flush_batch(
+                agent.name, subscription_index
+            )
+
+            if batched_artifacts is None:
+                return CollectionResult.waiting()
+
+            artifacts = batched_artifacts
+
+        # Collection complete!
+        return CollectionResult.immediate(artifacts)
+
+
+__all__ = ["BuiltinCollectionComponent"]

flock/components/orchestrator/deduplication.py

@@ -0,0 +1,78 @@
+"""Deduplication component to prevent duplicate artifact processing."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from flock.components.orchestrator.base import OrchestratorComponent, ScheduleDecision
+
+
+if TYPE_CHECKING:
+    from flock.core import Agent, Flock
+    from flock.core.artifacts import Artifact
+    from flock.core.subscription import Subscription
+
+
+class DeduplicationComponent(OrchestratorComponent):
+    """Deduplication to prevent agents from processing same artifact multiple times.
+
+    Tracks which artifacts have been processed by which agents and skips
+    duplicate scheduling attempts.
+
+    Priority: 20 (runs after circuit breaker at 10)
+
+    Examples:
+        >>> # Auto-added to all orchestrators
+        >>> flock = Flock("openai/gpt-4.1")
+
+        >>> # Deduplication prevents:
+        >>> # - Agents re-processing artifacts they already handled
+        >>> # - Feedback loops from agent self-triggers
+        >>> # - Duplicate work from retry logic
+    """
+
+    priority: int = 20  # Run after circuit breaker (10)
+    name: str = "deduplication"
+
+    def __init__(self, **kwargs):
+        """Initialize deduplication with empty processed set."""
+        super().__init__(**kwargs)
+        self._processed: set[tuple[str, str]] = set()  # (artifact_id, agent_name)
+
+    async def on_before_schedule(
+        self,
+        orchestrator: Flock,
+        artifact: Artifact,
+        agent: Agent,
+        subscription: Subscription,
+    ) -> ScheduleDecision:
+        """Check if artifact has already been processed by this agent.
+
+        Returns SKIP if agent has already processed this artifact,
+        preventing duplicate work.
+        """
+        key = (str(artifact.id), agent.name)
+
+        if key in self._processed:
+            # Already processed - skip
+            return ScheduleDecision.SKIP
+
+        # Not yet processed - allow
+        return ScheduleDecision.CONTINUE
+
+    async def on_before_agent_schedule(
+        self, orchestrator: Flock, agent: Agent, artifacts: list[Artifact]
+    ) -> list[Artifact]:
+        """Mark artifacts as processed before agent execution.
+
+        This ensures artifacts are marked as seen even if agent execution fails,
+        preventing infinite retry loops.
+        """
+        for artifact in artifacts:
+            key = (str(artifact.id), agent.name)
+            self._processed.add(key)
+
+        return artifacts
+
+
+__all__ = ["DeduplicationComponent"]

flock/core/__init__.py

@@ -0,0 +1,30 @@
+"""Core abstractions and interfaces."""
+
+from flock.core.agent import (
+    Agent,
+    AgentBuilder,
+    AgentOutput,
+    MCPServerConfig,
+    OutputGroup,
+    Pipeline,
+    PublishBuilder,
+    RunHandle,
+)
+from flock.core.orchestrator import BoardHandle, Flock, start_orchestrator
+from flock.core.visibility import AgentIdentity
+
+
+__all__ = [
+    "Agent",
+    "AgentBuilder",
+    "AgentIdentity",
+    "AgentOutput",
+    "BoardHandle",
+    "Flock",
+    "MCPServerConfig",
+    "OutputGroup",
+    "Pipeline",
+    "PublishBuilder",
+    "RunHandle",
+    "start_orchestrator",
+]