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

flock/api/models.py

@@ -20,8 +20,9 @@ class AgentSubscription(BaseModel):
     """Subscription configuration for an agent."""
 
     types: list[str] = Field(description="Artifact types this subscription consumes")
-    mode: str = Field(description="Subscription mode (e.g., 'all', 'any')")
-    delivery: str = Field(description="Delivery mode (e.g., 'immediate', 'batch')")
+    mode: str = Field(
+        description="Subscription mode (e.g., 'both', 'direct', 'events')"
+    )
 
 
 class Agent(BaseModel):

flock/api/service.py

@@ -261,7 +261,6 @@ class BlackboardHTTPService:
                             AgentSubscription(
                                 types=list(subscription.type_names),
                                 mode=subscription.mode,
-                                delivery=subscription.delivery,
                             )
                             for subscription in agent.subscriptions
                         ],

flock/core/agent.py

@@ -19,7 +19,7 @@ from flock.agent.mcp_integration import MCPIntegration
 # Phase 4: Import extracted modules
 from flock.agent.output_processor import OutputProcessor
 from flock.core.artifacts import Artifact, ArtifactSpec
-from flock.core.subscription import BatchSpec, JoinSpec, Subscription, TextPredicate
+from flock.core.subscription import BatchSpec, JoinSpec, Subscription
 from flock.core.visibility import AgentIdentity, Visibility, ensure_visibility
 from flock.logging.auto_trace import AutoTracedMeta
 from flock.logging.logging import get_logger
@@ -226,11 +226,7 @@ class Agent(metaclass=AutoTracedMeta):
             comp_name = self._component_display_name(component)
             priority = getattr(component, "priority", 0)
             logger.info(
-                "Agent %s: utility added: component=%s, priority=%s, total_utilities=%s",
-                self.name,
-                comp_name,
-                priority,
-                len(self.utilities),
+                f"Agent {self.name}: utility added: component={comp_name}, priority={priority}, total_utilities={len(self.utilities)}"
             )
         self.utilities.sort(key=lambda comp: getattr(comp, "priority", 0))
 
@@ -539,13 +535,16 @@ class AgentBuilder:
         where: Callable[[BaseModel], bool]
         | Sequence[Callable[[BaseModel], bool]]
         | None = None,
-        text: str | None = None,
-        min_p: float = 0.0,
+        semantic_match: str
+        | list[str]
+        | list[dict[str, Any]]
+        | dict[str, Any]
+        | None = None,
+        semantic_threshold: float = 0.0,
         from_agents: Iterable[str] | None = None,
         tags: Iterable[str] | None = None,
         join: dict | JoinSpec | None = None,
         batch: dict | BatchSpec | None = None,
-        delivery: str = "exclusive",
         mode: str = "both",
         priority: int = 0,
     ) -> AgentBuilder:
@@ -558,14 +557,21 @@ class AgentBuilder:
             *types: Artifact types (Pydantic models) to consume
             where: Optional filter predicate(s). Agent only executes if predicate returns True.
                 Can be a single callable or sequence of callables (all must pass).
-            text: Optional semantic text filter using embedding similarity
-            min_p: Minimum probability threshold for text similarity (0.0-1.0)
+            semantic_match: Optional semantic similarity filter. Matches artifacts based on
+                meaning rather than keywords. Can be:
+                - str: Single query (e.g., "security vulnerability")
+                - list[str]: Multiple queries, all must match (AND logic)
+                - dict: Advanced config with "query", "threshold", "field"
+                - list[dict]: Multiple queries with individual thresholds
+            semantic_threshold: Minimum similarity threshold for semantic matching (0.0-1.0).
+                Applied to all queries when semantic_match is a string or list of strings.
+                Ignored if semantic_match is a dict/list of dicts with explicit "threshold".
+                Default: 0.0 (uses default 0.4 when not specified)
             from_agents: Only consume artifacts from specific agents
             tags: Only consume artifacts with matching tags
             join: Join specification for coordinating multiple artifact types
             batch: Batch specification for processing multiple artifacts together
-            delivery: Delivery mode - "exclusive" (one agent) or "broadcast" (all matching)
-            mode: Processing mode - "both", "streaming", or "batch"
+            mode: Processing mode - "both", "direct", or "events"
             priority: Execution priority (higher = executes first)
 
         Returns:
@@ -587,6 +593,12 @@ class AgentBuilder:
             ...     where=[lambda o: o.total > 100, lambda o: o.status == "pending"],
             ... )
 
+            >>> # Semantic matching
+            >>> agent.consumes(Ticket, semantic_match="security vulnerability")
+
+            >>> # Semantic matching with custom threshold
+            >>> agent.consumes(Ticket, semantic_match="urgent", semantic_threshold=0.6)
+
             >>> # Consume from specific agents
             >>> agent.consumes(Report, from_agents=["analyzer", "validator"])
 
@@ -607,17 +619,40 @@ class AgentBuilder:
         # Phase 5B: Use BuilderValidator for normalization
         join_spec = BuilderValidator.normalize_join(join)
         batch_spec = BuilderValidator.normalize_batch(batch)
-        text_predicates = [TextPredicate(text=text, min_p=min_p)] if text else []
+
+        # Handle semantic_threshold parameter to control semantic matching threshold
+        # If semantic_threshold is provided and semantic_match is simple, convert to dict
+        semantic_param: (
+            str | list[str] | list[dict[str, Any]] | dict[str, Any] | None
+        ) = semantic_match
+        if semantic_match is not None and semantic_threshold > 0.0:
+            if isinstance(semantic_match, str):
+                # Simple string: create dict with semantic_threshold as threshold
+                semantic_param = {
+                    "query": semantic_match,
+                    "threshold": semantic_threshold,
+                }
+            elif isinstance(semantic_match, list):
+                # List of strings: convert to list of dicts with semantic_threshold
+                semantic_param = [
+                    {"query": q, "threshold": semantic_threshold}
+                    for q in semantic_match
+                ]
+            elif isinstance(semantic_match, dict) and "threshold" not in semantic_match:
+                # Dict without explicit threshold: add semantic_threshold
+                semantic_param = {**semantic_match, "threshold": semantic_threshold}
+
+        # Semantic matching: pass semantic_match parameter to Subscription
+        # which will parse it into TextPredicate objects
         subscription = Subscription(
             agent_name=self._agent.name,
             types=types,
             where=predicates,
-            text_predicates=text_predicates,
+            semantic_match=semantic_param,  # Let Subscription handle conversion
             from_agents=from_agents,
             tags=tags,
             join=join_spec,
             batch=batch_spec,
-            delivery=delivery,
             mode=mode,
             priority=priority,
         )

flock/core/orchestrator.py

@@ -111,7 +111,7 @@ class Flock(metaclass=AutoTracedMeta):
         # Patch litellm imports and setup logger
         self._patch_litellm_proxy_imports()
         self._logger = logging.getLogger(__name__)
-        self.model = model
+        self.model = model or os.getenv("DEFAULT_MODEL")
 
         # Phase 3: Initialize all components using OrchestratorInitializer
         components = OrchestratorInitializer.initialize_components(
@@ -168,10 +168,6 @@ class Flock(metaclass=AutoTracedMeta):
         self._scheduler = AgentScheduler(self, self._component_runner)
         self._artifact_manager = ArtifactManager(self, self.store, self._scheduler)
 
-        # Resolve model default
-        if not model:
-            self.model = os.getenv("DEFAULT_MODEL")
-
         # Log initialization
         self._logger.debug("Orchestrator initialized: components=[]")
 
@@ -496,13 +492,17 @@ class Flock(metaclass=AutoTracedMeta):
 
     # Runtime --------------------------------------------------------------
 
-    async def run_until_idle(self) -> None:
+    async def run_until_idle(self, *, wait_for_input: bool = False) -> None:
         """Wait for all scheduled agent tasks to complete.
 
         This method blocks until the blackboard reaches a stable state where no
         agents are queued for execution. Essential for batch processing and ensuring
         all agent cascades complete before continuing.
 
+        Args:
+            wait_for_input: If True, waits for user input before returning (default: False).
+                Useful for debugging or step-by-step execution.
+
         Note:
             Automatically resets circuit breaker counters and shuts down MCP connections
             when idle. Used with publish() for event-driven workflows.
@@ -518,6 +518,12 @@ class Flock(metaclass=AutoTracedMeta):
             >>> await flock.publish_many([task1, task2, task3])
             >>> await flock.run_until_idle()  # All tasks processed in parallel
 
+            >>> # Step-by-step execution with user prompts
+            >>> await flock.publish(task1)
+            >>> await flock.run_until_idle(wait_for_input=True)  # Pauses for user input
+            >>> await flock.publish(task2)
+            >>> await flock.run_until_idle(wait_for_input=True)  # Pauses again
+
         See Also:
             - publish(): Event-driven artifact publishing
             - publish_many(): Batch publishing for parallel execution
@@ -557,6 +563,12 @@ class Flock(metaclass=AutoTracedMeta):
         # Automatically shutdown MCP connections when idle
         await self.shutdown(include_components=False)
 
+        # Wait for user input if requested
+        if wait_for_input:
+            # Use asyncio.to_thread to avoid blocking the event loop
+            # since input() is a blocking I/O operation
+            await asyncio.to_thread(input, "Press any key to continue....")
+
     async def direct_invoke(
         self, agent: Agent, inputs: Sequence[BaseModel | Mapping[str, Any] | Artifact]
     ) -> list[Artifact]:

flock/core/subscription.py

@@ -21,8 +21,17 @@ Predicate = Callable[[BaseModel], bool]
 
 @dataclass
 class TextPredicate:
-    text: str
-    min_p: float = 0.0
+    """Semantic text matching predicate.
+
+    Args:
+        query: The semantic query text to match against
+        threshold: Minimum similarity score (0.0 to 1.0) to consider a match
+        field: Optional field name to extract from payload. If None, uses all text.
+    """
+
+    query: str
+    threshold: float = 0.4  # Default threshold for semantic matching
+    field: str | None = None  # Optional field to extract from payload
 
 
 @dataclass
@@ -97,21 +106,21 @@ class Subscription:
     def __init__(
         self,
         *,
-        agent_name: str,
+        agent_name: str | None = None,
         types: Sequence[type[BaseModel]],
         where: Sequence[Predicate] | None = None,
         text_predicates: Sequence[TextPredicate] | None = None,
+        semantic_match: str | list[str | dict[str, Any]] | dict[str, Any] | None = None,
         from_agents: Iterable[str] | None = None,
         tags: Iterable[str] | None = None,
         join: JoinSpec | None = None,
         batch: BatchSpec | None = None,
-        delivery: str = "exclusive",
         mode: str = "both",
         priority: int = 0,
     ) -> None:
         if not types:
             raise ValueError("Subscription must declare at least one type.")
-        self.agent_name = agent_name
+        self.agent_name = agent_name or ""
         self.type_models: list[type[BaseModel]] = list(types)
 
         # Register all types and build counts (supports duplicates for count-based AND gates)
@@ -127,15 +136,62 @@ class Subscription:
             self.type_counts[type_name] = self.type_counts.get(type_name, 0) + 1
 
         self.where = list(where or [])
-        self.text_predicates = list(text_predicates or [])
+
+        # Parse semantic_match parameter into TextPredicate objects
+        parsed_text_predicates = self._parse_semantic_match_parameter(semantic_match)
+        self.text_predicates = list(text_predicates or []) + parsed_text_predicates
+
         self.from_agents = set(from_agents or [])
         self.tags = set(tags or [])
         self.join = join
         self.batch = batch
-        self.delivery = delivery
         self.mode = mode
         self.priority = priority
 
+    def _parse_semantic_match_parameter(
+        self, semantic_match: str | list[str | dict[str, Any]] | dict[str, Any] | None
+    ) -> list[TextPredicate]:
+        """Parse the semantic_match parameter into TextPredicate objects.
+
+        Args:
+            semantic_match: Can be:
+                - str: "query" → TextPredicate(query="query", threshold=0.4)
+                - list: ["q1", "q2"] → multiple TextPredicates (AND logic)
+                       or [{"query": "q1", "threshold": 0.8}, ...] with explicit thresholds
+                - dict: {"query": "...", "threshold": 0.8, "field": "body"}
+
+        Returns:
+            List of TextPredicate objects
+        """
+        if semantic_match is None:
+            return []
+
+        if isinstance(semantic_match, str):
+            return [TextPredicate(query=semantic_match)]
+
+        if isinstance(semantic_match, list):
+            # Handle both list of strings and list of dicts
+            predicates = []
+            for item in semantic_match:
+                if isinstance(item, str):
+                    predicates.append(TextPredicate(query=item))
+                elif isinstance(item, dict):
+                    query = item.get("query", "")
+                    threshold = item.get("threshold", 0.4)
+                    field = item.get("field", None)
+                    predicates.append(
+                        TextPredicate(query=query, threshold=threshold, field=field)
+                    )
+            return predicates
+
+        if isinstance(semantic_match, dict):
+            query = semantic_match.get("query", "")
+            threshold = semantic_match.get("threshold", 0.4)  # Match dataclass default
+            field = semantic_match.get("field", None)
+            return [TextPredicate(query=query, threshold=threshold, field=field)]
+
+        return []
+
     def accepts_direct(self) -> bool:
         return self.mode in {"direct", "both"}
 
@@ -159,12 +215,99 @@ class Subscription:
                     return False
             except Exception:
                 return False
+
+        # Evaluate text predicates using semantic matching
+        if self.text_predicates:
+            if not self._matches_text_predicates(artifact):
+                return False
+
         return True
 
+    def _matches_text_predicates(self, artifact: Artifact) -> bool:
+        """Check if artifact matches all text predicates (AND logic).
+
+        Args:
+            artifact: The artifact to check
+
+        Returns:
+            bool: True if all text predicates match (or if semantic unavailable)
+        """
+        # Check if semantic features available
+        try:
+            from flock.semantic import SEMANTIC_AVAILABLE, EmbeddingService
+        except ImportError:
+            # Graceful degradation - if semantic not available, skip text predicates
+            return True
+
+        if not SEMANTIC_AVAILABLE:
+            # Graceful degradation
+            return True
+
+        try:
+            embedding_service = EmbeddingService.get_instance()
+        except Exception:
+            # If embedding service fails, degrade gracefully
+            return True
+
+        # Extract text from artifact payload
+        artifact_text = self._extract_text_from_payload(artifact.payload)
+        if not artifact_text or not artifact_text.strip():
+            # No text to match against
+            return False
+
+        # Check all predicates (AND logic)
+        for predicate in self.text_predicates:
+            try:
+                # Extract text based on field specification
+                if predicate.field:
+                    # Use specific field
+                    text_to_match = str(artifact.payload.get(predicate.field, ""))
+                else:
+                    # Use all text from payload
+                    text_to_match = artifact_text
+
+                if not text_to_match or not text_to_match.strip():
+                    return False
+
+                # Compute semantic similarity
+                similarity = embedding_service.similarity(
+                    predicate.query, text_to_match
+                )
+
+                # Check threshold
+                if similarity < predicate.threshold:
+                    return False
+
+            except Exception:
+                # If any error occurs, fail the match
+                return False
+
+        return True
+
+    def _extract_text_from_payload(self, payload: dict[str, Any]) -> str:
+        """Extract all text content from payload.
+
+        Args:
+            payload: The artifact payload dict
+
+        Returns:
+            str: Concatenated text from all string fields
+        """
+        text_parts = []
+        for value in payload.values():
+            if isinstance(value, str):
+                text_parts.append(value)
+            elif isinstance(value, (list, tuple)):
+                for item in value:
+                    if isinstance(item, str):
+                        text_parts.append(item)
+
+        return " ".join(text_parts)
+
     def __repr__(self) -> str:  # pragma: no cover - debug helper
         return (
             f"Subscription(agent={self.agent_name!r}, types={list(self.type_names)!r}, "
-            f"delivery={self.delivery!r}, mode={self.mode!r})"
+            f"mode={self.mode!r})"
         )
 
 

flock/semantic/__init__.py

@@ -0,0 +1,49 @@
+"""Semantic subscriptions for Flock.
+
+This module provides semantic matching capabilities using sentence-transformers.
+It's an optional feature that requires installing the [semantic] extra:
+
+    uv add flock-core[semantic]
+
+If sentence-transformers is not installed, semantic features will gracefully
+degrade and core Flock functionality remains unaffected.
+"""
+
+# Try to import semantic features
+try:
+    from sentence_transformers import SentenceTransformer  # noqa: F401
+
+    from .context_provider import SemanticContextProvider
+    from .embedding_service import EmbeddingService
+
+    SEMANTIC_AVAILABLE = True
+except ImportError as e:
+    SEMANTIC_AVAILABLE = False
+    _import_error = e
+
+    # Provide helpful error message when features are used
+    class EmbeddingService:  # type: ignore
+        """Placeholder when semantic extras not installed."""
+
+        @staticmethod
+        def get_instance(*args, **kwargs):
+            raise ImportError(
+                "Semantic features require sentence-transformers. "
+                "Install with: uv add flock-core[semantic]"
+            ) from _import_error
+
+    class SemanticContextProvider:  # type: ignore
+        """Placeholder when semantic extras not installed."""
+
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                "Semantic features require sentence-transformers. "
+                "Install with: uv add flock-core[semantic]"
+            ) from _import_error
+
+
+__all__ = [
+    "SEMANTIC_AVAILABLE",
+    "EmbeddingService",
+    "SemanticContextProvider",
+]

flock/semantic/context_provider.py

@@ -0,0 +1,173 @@
+"""Semantic context providers for agent execution.
+
+This module provides context providers that use semantic similarity to find
+relevant historical artifacts for agent context.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+
+if TYPE_CHECKING:
+    from flock.core.artifacts import Artifact
+    from flock.core.store import ArtifactStore
+
+
+class SemanticContextProvider:
+    """Context provider that retrieves semantically relevant historical artifacts.
+
+    This provider uses semantic similarity to find artifacts that are relevant
+    to a given query text, enabling agents to make decisions based on similar
+    past events.
+
+    Args:
+        query_text: The semantic query to match against artifacts
+        threshold: Minimum similarity score (0.0 to 1.0) to include in results
+        limit: Maximum number of artifacts to return
+        extract_field: Optional field name to extract from artifact payload for matching.
+                      If None, uses all text from payload.
+        artifact_type: Optional type filter - only return artifacts of this type
+        where: Optional predicate filter for additional filtering
+
+    Example:
+        ```python
+        provider = SemanticContextProvider(
+            query_text="user authentication issues", threshold=0.5, limit=5
+        )
+
+        relevant_artifacts = await provider.get_context(store)
+        ```
+    """
+
+    def __init__(
+        self,
+        query_text: str,
+        threshold: float = 0.4,
+        limit: int = 10,
+        extract_field: str | None = None,
+        artifact_type: type[BaseModel] | None = None,
+        where: Callable[[Artifact], bool] | None = None,
+    ):
+        """Initialize semantic context provider.
+
+        Args:
+            query_text: The semantic query text
+            threshold: Minimum similarity score (default: 0.4)
+            limit: Maximum results to return (default: 10)
+            extract_field: Optional field to extract from payload
+            artifact_type: Optional type filter
+            where: Optional predicate for additional filtering
+        """
+        if not query_text or not query_text.strip():
+            raise ValueError("query_text cannot be empty")
+
+        if not 0.0 <= threshold <= 1.0:
+            raise ValueError("threshold must be between 0 and 1")
+
+        if limit < 1:
+            raise ValueError("limit must be at least 1")
+
+        self.query_text = query_text
+        self.threshold = threshold
+        self.limit = limit
+        self.extract_field = extract_field
+        self.artifact_type = artifact_type
+        self.where = where
+
+    async def get_context(self, store: ArtifactStore) -> list[Artifact]:
+        """Retrieve semantically relevant artifacts from store.
+
+        Args:
+            store: The artifact store to query
+
+        Returns:
+            List of relevant artifacts, sorted by similarity (highest first)
+        """
+        # Check if semantic features available
+        try:
+            from flock.semantic import SEMANTIC_AVAILABLE, EmbeddingService
+        except ImportError:
+            return []
+
+        if not SEMANTIC_AVAILABLE:
+            return []
+
+        try:
+            embedding_service = EmbeddingService.get_instance()
+        except Exception:
+            return []
+
+        # Get query embedding
+        try:
+            query_embedding = embedding_service.embed(self.query_text)
+        except Exception:
+            return []
+
+        # Get all artifacts from store
+        all_artifacts = await store.list()
+
+        # Filter by type if specified
+        if self.artifact_type:
+            from flock.registry import type_registry
+
+            type_name = type_registry.register(self.artifact_type)
+            all_artifacts = [a for a in all_artifacts if a.type == type_name]
+
+        # Filter by where clause if specified
+        if self.where:
+            all_artifacts = [a for a in all_artifacts if self.where(a)]
+
+        # Compute similarities and filter
+        results: list[tuple[Artifact, float]] = []
+
+        for artifact in all_artifacts:
+            try:
+                # Extract text from artifact
+                if self.extract_field:
+                    # Use specific field
+                    text = str(artifact.payload.get(self.extract_field, ""))
+                else:
+                    # Use all text from payload
+                    text = self._extract_text_from_payload(artifact.payload)
+
+                if not text or not text.strip():
+                    continue
+
+                # Compute similarity
+                similarity = embedding_service.similarity(self.query_text, text)
+
+                # Check threshold
+                if similarity >= self.threshold:
+                    results.append((artifact, similarity))
+
+            except Exception:
+                # Skip artifacts that fail processing
+                continue
+
+        # Sort by similarity (highest first) and take top N
+        results.sort(key=lambda x: x[1], reverse=True)
+        return [artifact for artifact, _ in results[: self.limit]]
+
+    def _extract_text_from_payload(self, payload: dict[str, Any]) -> str:
+        """Extract all text content from payload.
+
+        Args:
+            payload: The artifact payload dict
+
+        Returns:
+            str: Concatenated text from all string fields
+        """
+        text_parts = []
+        for value in payload.values():
+            if isinstance(value, str):
+                text_parts.append(value)
+            elif isinstance(value, (list, tuple)):
+                for item in value:
+                    if isinstance(item, str):
+                        text_parts.append(item)
+
+        return " ".join(text_parts)