flock-core 0.5.3__py3-none-any.whl → 0.5.5__py3-none-any.whl

flock/agent.py

@@ -249,7 +249,26 @@ class Agent(metaclass=AutoTracedMeta):
             accumulated_metrics: dict[str, float] = {}
             for engine in engines:
                 current_inputs = await engine.on_pre_evaluate(self, ctx, current_inputs)
-                result = await engine.evaluate(self, ctx, current_inputs)
+                use_batch_mode = bool(getattr(ctx, "is_batch", False))
+                try:
+                    if use_batch_mode:
+                        logger.debug(
+                            "Agent %s: routing %d artifacts to %s.evaluate_batch",
+                            self.name,
+                            len(current_inputs.artifacts),
+                            engine.__class__.__name__,
+                        )
+                        result = await engine.evaluate_batch(self, ctx, current_inputs)
+                    else:
+                        result = await engine.evaluate(self, ctx, current_inputs)
+                except NotImplementedError:
+                    if use_batch_mode:
+                        logger.error(
+                            "Agent %s: engine %s does not implement evaluate_batch()",
+                            self.name,
+                            engine.__class__.__name__,
+                        )
+                    raise
 
                 # AUTO-WRAP: If engine returns BaseModel instead of EvalResult, wrap it
                 from flock.runtime import EvalResult as ER

flock/artifact_collector.py

@@ -110,9 +110,8 @@ class ArtifactCollector:
 
             del self._waiting_pools[pool_key]  # Clear for next cycle
             return (True, artifacts)
-        else:
-            # Incomplete - still waiting for more artifacts
-            return (False, [])
+        # Incomplete - still waiting for more artifacts
+        return (False, [])
 
     def get_waiting_status(
         self, agent: Agent, subscription_index: int

flock/batch_accumulator.py

@@ -11,10 +11,10 @@ Supports BatchSpec-based batching:
 
 from __future__ import annotations
 
-from collections import defaultdict
-from datetime import datetime, timedelta
+from datetime import datetime
 from typing import TYPE_CHECKING
 
+
 if TYPE_CHECKING:
     from flock.artifacts import Artifact
     from flock.subscription import BatchSpec, Subscription
@@ -184,7 +184,7 @@ class BatchEngine:
             # This will work correctly if all groups are the same size
 
             # Actually, let's track group count properly:
-            if not hasattr(accumulator, '_group_count'):
+            if not hasattr(accumulator, "_group_count"):
                 accumulator._group_count = 0
 
             accumulator._group_count += 1
@@ -249,4 +249,4 @@ class BatchEngine:
         return results
 
 
-__all__ = ["BatchEngine", "BatchAccumulator"]
+__all__ = ["BatchAccumulator", "BatchEngine"]

flock/components.py

@@ -109,6 +109,38 @@ class EngineComponent(AgentComponent):
         """Override this method in your engine implementation."""
         raise NotImplementedError
 
+    async def evaluate_batch(self, agent: Agent, ctx: Context, inputs: EvalInputs) -> EvalResult:
+        """Process batch of accumulated artifacts (BatchSpec).
+
+        Override this method if your engine supports batch processing.
+
+        Args:
+            agent: Agent instance executing this engine
+            ctx: Execution context (ctx.is_batch will be True)
+            inputs: EvalInputs with inputs.artifacts containing batch items
+
+        Returns:
+            EvalResult with processed artifacts
+
+        Raises:
+            NotImplementedError: If engine doesn't support batching
+
+        Example:
+            >>> async def evaluate_batch(self, agent, ctx, inputs):
+            ...     events = inputs.all_as(Event)  # Get ALL items
+            ...     results = await bulk_process(events)
+            ...     return EvalResult.from_objects(*results, agent=agent)
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support batch processing.\n\n"
+            f"To fix this:\n"
+            f"1. Remove BatchSpec from agent subscription, OR\n"
+            f"2. Implement evaluate_batch() in {self.__class__.__name__}, OR\n"
+            f"3. Use a batch-aware engine (e.g., CustomBatchEngine)\n\n"
+            f"Agent: {agent.name}\n"
+            f"Engine: {self.__class__.__name__}"
+        )
+
     async def fetch_conversation_context(
         self,
         ctx: Context,

flock/correlation_engine.py

@@ -14,6 +14,7 @@ from collections import defaultdict
 from datetime import datetime, timedelta
 from typing import TYPE_CHECKING, Any
 
+
 if TYPE_CHECKING:
     from flock.artifacts import Artifact
     from flock.subscription import JoinSpec, Subscription
@@ -51,7 +52,9 @@ class CorrelationGroup:
     def add_artifact(self, artifact: Artifact, current_sequence: int) -> None:
         """Add artifact to this correlation group's waiting pool."""
         if self.created_at_time is None:
-            self.created_at_time = datetime.now()
+            from datetime import timezone
+
+            self.created_at_time = datetime.now(timezone.utc)
 
         self.waiting_artifacts[artifact.type].append(artifact)
 
@@ -67,11 +70,13 @@ class CorrelationGroup:
         if isinstance(self.window_spec, int):
             # Count window: expired if current sequence exceeds created + window
             return (current_sequence - self.created_at_sequence) > self.window_spec
-        elif isinstance(self.window_spec, timedelta):
+        if isinstance(self.window_spec, timedelta):
             # Time window: expired if current time exceeds created + window
             if self.created_at_time is None:
                 return False
-            elapsed = datetime.now() - self.created_at_time
+            from datetime import timezone
+
+            elapsed = datetime.now(timezone.utc) - self.created_at_time
             return elapsed > self.window_spec
         return False
 
@@ -154,7 +159,7 @@ class CorrelationEngine:
 
         try:
             correlation_key = join_spec.by(payload_instance)
-        except Exception as e:
+        except Exception:
             # Key extraction failed - skip this artifact
             # TODO: Log warning?
             return None

flock/dashboard/collector.py

@@ -80,6 +80,9 @@ class AgentSnapshot:
     first_seen: datetime
     last_seen: datetime
     signature: str
+    logic_operations: list[dict] = field(
+        default_factory=list
+    )  # Phase 1.2: JoinSpec/BatchSpec config
 
 
 class DashboardEventCollector(AgentComponent):
@@ -514,6 +517,7 @@ class DashboardEventCollector(AgentComponent):
             first_seen=snapshot.first_seen,
             last_seen=snapshot.last_seen,
             signature=snapshot.signature,
+            logic_operations=[dict(op) for op in snapshot.logic_operations],  # Phase 1.2
         )
 
     def _snapshot_to_record(self, snapshot: AgentSnapshot) -> AgentSnapshotRecord:

flock/dashboard/events.py

@@ -177,10 +177,84 @@ class AgentErrorEvent(BaseModel):
     failed_at: str  # ISO timestamp of failure
 
 
+class CorrelationGroupUpdatedEvent(BaseModel):
+    """Event emitted when artifact added to correlation group.
+
+    Phase 1.2: Logic Operations UX Enhancement
+    Emitted when an artifact is added to a JoinSpec correlation group
+    that has not yet collected all required types.
+    """
+
+    # Event metadata
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    # Agent identification
+    agent_name: str
+    subscription_index: int
+
+    # Correlation group
+    correlation_key: str  # "patient_123"
+
+    # Progress
+    collected_types: dict[str, int]  # {"XRayImage": 1, "LabResults": 0}
+    required_types: dict[str, int]  # {"XRayImage": 1, "LabResults": 1}
+    waiting_for: list[str]  # ["LabResults"]
+
+    # Window progress
+    elapsed_seconds: float
+    expires_in_seconds: float | None  # For time windows
+    expires_in_artifacts: int | None  # For count windows
+
+    # Artifact that triggered this event
+    artifact_id: str
+    artifact_type: str
+
+    is_complete: bool  # Will trigger agent in next orchestrator cycle
+
+
+class BatchItemAddedEvent(BaseModel):
+    """Event emitted when artifact added to batch accumulator.
+
+    Phase 1.2: Logic Operations UX Enhancement
+    Emitted when an artifact is added to a BatchSpec accumulator
+    that has not yet reached its flush threshold.
+    """
+
+    # Event metadata
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    # Agent identification
+    agent_name: str
+    subscription_index: int
+
+    # Batch progress
+    items_collected: int
+    items_target: int | None  # None if no size limit
+    items_remaining: int | None
+
+    # Timeout progress
+    elapsed_seconds: float
+    timeout_seconds: float | None
+    timeout_remaining_seconds: float | None
+
+    # Trigger prediction
+    will_flush: str  # "on_size" | "on_timeout" | "unknown"
+
+    # Artifact that triggered this event
+    artifact_id: str
+    artifact_type: str
+
+
 __all__ = [
     "AgentActivatedEvent",
     "AgentCompletedEvent",
     "AgentErrorEvent",
+    "BatchItemAddedEvent",
+    "CorrelationGroupUpdatedEvent",
     "MessagePublishedEvent",
     "StreamingOutputEvent",
     "SubscriptionInfo",

flock/dashboard/graph_builder.py

@@ -73,6 +73,9 @@ class GraphAssembler(metaclass=AutoTracedMeta):
                 agent_snapshots,
             )
             edges = self._derive_agent_edges(artifacts)
+            # Phase 1.5: Add pending edges for artifacts waiting in correlation/batch
+            pending_edges = self._derive_pending_edges(artifacts)
+            edges.extend(pending_edges)
         else:
             nodes = self._build_message_nodes(artifacts)
             edges = self._derive_blackboard_edges(artifacts, graph_state)
@@ -192,6 +195,14 @@ class GraphAssembler(metaclass=AutoTracedMeta):
             consumed = consumed_metrics.get(agent.name)
             snapshot = agent_snapshots.get(agent.name)
 
+            # Phase 1.2: Build logic_operations from live agent subscriptions
+            logic_operations = []
+            for idx, subscription in enumerate(agent.subscriptions):
+                if subscription.join or subscription.batch:
+                    logic_config = self._build_logic_config_for_subscription(agent, subscription, idx)
+                    if logic_config:
+                        logic_operations.append(logic_config)
+
             node_data = {
                 "name": agent.name,
                 "status": agent_status.get(agent.name, "idle"),
@@ -206,6 +217,7 @@ class GraphAssembler(metaclass=AutoTracedMeta):
                 "firstSeen": snapshot.first_seen.isoformat() if snapshot else None,
                 "lastSeen": snapshot.last_seen.isoformat() if snapshot else None,
                 "signature": snapshot.signature if snapshot else None,
+                "logicOperations": logic_operations,  # Phase 1.2
             }
 
             nodes.append(
@@ -241,6 +253,7 @@ class GraphAssembler(metaclass=AutoTracedMeta):
                 "firstSeen": snapshot.first_seen.isoformat(),
                 "lastSeen": snapshot.last_seen.isoformat(),
                 "signature": snapshot.signature,
+                "logicOperations": list(snapshot.logic_operations),  # Phase 1.2: From snapshot
             }
 
             nodes.append(
@@ -378,6 +391,196 @@ class GraphAssembler(metaclass=AutoTracedMeta):
 
         return edges
 
+    def _derive_pending_edges(
+        self,
+        artifacts: Mapping[str, GraphArtifact],
+    ) -> list[GraphEdge]:
+        """
+        Phase 1.5: Build pending edges for artifacts waiting in correlation/batch.
+
+        Creates visual edges (purple/orange dashed) from artifact producers to agents
+        that have those artifacts waiting in JoinSpec/BatchSpec queues.
+
+        Returns edges with type "pending_join" or "pending_batch".
+        """
+        edges: list[GraphEdge] = []
+        edge_counter = 0
+
+        # Build map of artifact_id -> artifact for quick lookup
+        artifact_map = {art.artifact_id: art for art in artifacts.values()}
+
+        # Iterate through all active agents with JoinSpec/BatchSpec subscriptions
+        for agent in self._orchestrator.agents:
+            for sub_idx, subscription in enumerate(agent.subscriptions):
+                # JoinSpec pending edges
+                if subscription.join:
+                    pending_join_edges = self._build_pending_join_edges(
+                        agent.name,
+                        sub_idx,
+                        subscription,
+                        artifact_map,
+                        edge_counter
+                    )
+                    edges.extend(pending_join_edges)
+                    edge_counter += len(pending_join_edges)
+
+                # BatchSpec pending edges
+                if subscription.batch:
+                    pending_batch_edges = self._build_pending_batch_edges(
+                        agent.name,
+                        sub_idx,
+                        subscription,
+                        artifact_map,
+                        edge_counter
+                    )
+                    edges.extend(pending_batch_edges)
+                    edge_counter += len(pending_batch_edges)
+
+        return edges
+
+    def _build_pending_join_edges(
+        self,
+        agent_name: str,
+        sub_idx: int,
+        subscription: "Subscription",  # noqa: F821
+        artifact_map: Mapping[str, GraphArtifact],
+        start_counter: int,
+    ) -> list[GraphEdge]:
+        """Build pending edges for JoinSpec correlation groups."""
+        from flock.dashboard.service import _get_correlation_groups
+
+        edges: list[GraphEdge] = []
+        correlation_groups = _get_correlation_groups(
+            self._orchestrator._correlation_engine,
+            agent_name,
+            sub_idx
+        )
+
+        if not correlation_groups:
+            return edges
+
+        edge_counter = start_counter
+
+        # For each correlation group, create edges for waiting artifacts
+        for group in correlation_groups:
+            # Get artifacts in this correlation group's waiting pool
+            correlation_key = group.get("correlation_key")
+            if not correlation_key:
+                continue
+
+            # Get the actual correlation group from engine
+            pool_key = (agent_name, sub_idx)
+            groups_dict = self._orchestrator._correlation_engine.correlation_groups.get(pool_key, {})
+            corr_group = groups_dict.get(correlation_key)
+
+            if not corr_group:
+                continue
+
+            # Build edges for each artifact type in the waiting pool
+            for artifact_type, artifact_list in corr_group.waiting_artifacts.items():
+                for artifact in artifact_list:
+                    artifact_id = str(artifact.id)
+                    graph_artifact = artifact_map.get(artifact_id)
+
+                    if not graph_artifact:
+                        continue
+
+                    producer = graph_artifact.produced_by or "external"
+
+                    # Create pending join edge
+                    edge_id = f"pending_join__{producer}__{agent_name}__{artifact_id}__{edge_counter}"
+                    edge_counter += 1
+
+                    edges.append(
+                        GraphEdge(
+                            id=edge_id,
+                            source=producer,
+                            target=agent_name,
+                            type="pending_join",
+                            label=f"⋈ {correlation_key}",
+                            data={
+                                "artifactId": artifact_id,
+                                "artifactType": artifact_type,
+                                "correlationKey": correlation_key,
+                                "subscriptionIndex": sub_idx,
+                                "waitingFor": group.get("waiting_for", []),
+                                "labelOffset": 0.0,
+                            },
+                            marker_end=GraphMarker(),
+                            hidden=False,
+                        )
+                    )
+
+        return edges
+
+    def _build_pending_batch_edges(
+        self,
+        agent_name: str,
+        sub_idx: int,
+        subscription: "Subscription",  # noqa: F821
+        artifact_map: Mapping[str, GraphArtifact],
+        start_counter: int,
+    ) -> list[GraphEdge]:
+        """Build pending edges for BatchSpec accumulation."""
+        from flock.dashboard.service import _get_batch_state
+
+        edges: list[GraphEdge] = []
+        batch_state = _get_batch_state(
+            self._orchestrator._batch_engine,
+            agent_name,
+            sub_idx,
+            subscription.batch
+        )
+
+        if not batch_state:
+            return edges
+
+        # Get the batch accumulator
+        batch_key = (agent_name, sub_idx)
+        accumulator = self._orchestrator._batch_engine.batches.get(batch_key)
+
+        if not accumulator or not accumulator.artifacts:
+            return edges
+
+        edge_counter = start_counter
+
+        # Create edges for each artifact in the batch
+        for artifact in accumulator.artifacts:
+            artifact_id = str(artifact.id)
+            graph_artifact = artifact_map.get(artifact_id)
+
+            if not graph_artifact:
+                continue
+
+            producer = graph_artifact.produced_by or "external"
+            artifact_type = graph_artifact.artifact_type
+
+            # Create pending batch edge
+            edge_id = f"pending_batch__{producer}__{agent_name}__{artifact_id}__{edge_counter}"
+            edge_counter += 1
+
+            edges.append(
+                GraphEdge(
+                    id=edge_id,
+                    source=producer,
+                    target=agent_name,
+                    type="pending_batch",
+                    label=f"⊞ {batch_state['items_collected']}/{batch_state['items_target'] or '∞'}",
+                    data={
+                        "artifactId": artifact_id,
+                        "artifactType": artifact_type,
+                        "subscriptionIndex": sub_idx,
+                        "itemsCollected": batch_state["items_collected"],
+                        "itemsTarget": batch_state["items_target"],
+                        "labelOffset": 0.0,
+                    },
+                    marker_end=GraphMarker(),
+                    hidden=False,
+                )
+            )
+
+        return edges
+
     def _derive_blackboard_edges(
         self,
         artifacts: Mapping[str, GraphArtifact],
@@ -561,3 +764,72 @@ class GraphAssembler(metaclass=AutoTracedMeta):
             for index, edge_id in enumerate(edge_ids):
                 offsets[edge_id] = index * step - offset_range / 2
         return offsets
+
+    def _build_logic_config_for_subscription(self, agent, subscription, idx):
+        """Build logic operations config for a subscription (Phase 1.2 + 1.2.1: with waiting_state)."""
+        if not subscription.join and not subscription.batch:
+            return None
+
+        config = {
+            "subscription_index": idx,
+            "subscription_types": list(subscription.type_names),
+        }
+
+        # JoinSpec configuration
+        if subscription.join:
+            join_spec = subscription.join
+            window_type = "time" if isinstance(join_spec.within, timedelta) else "count"
+            window_value = (
+                int(join_spec.within.total_seconds())
+                if isinstance(join_spec.within, timedelta)
+                else join_spec.within
+            )
+
+            config["join"] = {
+                "correlation_strategy": "by_key",
+                "window_type": window_type,
+                "window_value": window_value,
+                "window_unit": "seconds" if window_type == "time" else "artifacts",
+                "required_types": list(subscription.type_names),
+                "type_counts": dict(subscription.type_counts),
+            }
+
+            # Phase 1.2.1: Get waiting state from CorrelationEngine
+            from flock.dashboard.service import _get_correlation_groups
+            correlation_groups = _get_correlation_groups(
+                self._orchestrator._correlation_engine, agent.name, idx
+            )
+            if correlation_groups:
+                config["waiting_state"] = {
+                    "is_waiting": True,
+                    "correlation_groups": correlation_groups,
+                }
+
+        # BatchSpec configuration
+        if subscription.batch:
+            batch_spec = subscription.batch
+            strategy = (
+                "hybrid"
+                if batch_spec.size and batch_spec.timeout
+                else "size"
+                if batch_spec.size
+                else "timeout"
+            )
+
+            config["batch"] = {
+                "strategy": strategy,
+            }
+            if batch_spec.size:
+                config["batch"]["size"] = batch_spec.size
+            if batch_spec.timeout:
+                config["batch"]["timeout_seconds"] = int(batch_spec.timeout.total_seconds())
+
+            # Phase 1.2.1: Get waiting state from BatchEngine
+            from flock.dashboard.service import _get_batch_state
+            batch_state = _get_batch_state(self._orchestrator._batch_engine, agent.name, idx, batch_spec)
+            if batch_state:
+                if "waiting_state" not in config:
+                    config["waiting_state"] = {"is_waiting": True}
+                config["waiting_state"]["batch_state"] = batch_state
+
+        return config

flock/dashboard/models/graph.py

@@ -79,7 +79,9 @@ class GraphEdge(BaseModel):
     id: str
     source: str
     target: str
-    type: Literal["message_flow", "transformation"]
+    type: Literal[
+        "message_flow", "transformation", "pending_join", "pending_batch"
+    ]  # Phase 1.5: Added pending edge types
     label: str | None = None
     data: dict[str, Any] = Field(default_factory=dict)
     marker_end: GraphMarker | None = Field(default=None, alias="markerEnd")