flock-core 0.5.20__py3-none-any.whl → 0.5.22__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
@@ -539,13 +539,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 +561,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 +597,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 +623,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=[]")
 

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/dashboard/events.py

@@ -21,7 +21,7 @@ class SubscriptionInfo(BaseModel):
 class VisibilitySpec(BaseModel):
     """Visibility specification for artifacts.
 
-    Matches visibility types from flock.visibility module.
+    Matches visibility types from flock.core.visibility module.
     """
 
     kind: str  # "Public" | "Private" | "Labelled" | "Tenant" | "After"