flock-core 0.5.22__tar.gz → 0.5.24__tar.gz

{flock_core-0.5.22 → flock_core-0.5.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.22
+Version: 0.5.24
 Summary: Flock: A declrative framework for building and orchestrating AI agents.
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License: MIT
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
   <a href="LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/github/license/whiteducksoftware/flock?style=for-the-badge"></a>
   <a href="https://whiteduck.de" target="_blank"><img alt="Built by white duck" src="https://img.shields.io/badge/Built%20by-white%20duck%20GmbH-white?style=for-the-badge&labelColor=black"></a>
   <a href="https://codecov.io/gh/whiteducksoftware/flock" target="_blank"><img alt="Test Coverage" src="https://codecov.io/gh/whiteducksoftware/flock/branch/main/graph/badge.svg?token=YOUR_TOKEN_HERE&style=for-the-badge"></a>
-  <img alt="Tests" src="https://img.shields.io/badge/tests-1300+-brightgreen?style=for-the-badge">
+  <img alt="Tests" src="https://img.shields.io/badge/tests-1400+-brightgreen?style=for-the-badge">
 </p>
 
 ---

{flock_core-0.5.22 → flock_core-0.5.24}/README.md

@@ -8,7 +8,7 @@
   <a href="LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/github/license/whiteducksoftware/flock?style=for-the-badge"></a>
   <a href="https://whiteduck.de" target="_blank"><img alt="Built by white duck" src="https://img.shields.io/badge/Built%20by-white%20duck%20GmbH-white?style=for-the-badge&labelColor=black"></a>
   <a href="https://codecov.io/gh/whiteducksoftware/flock" target="_blank"><img alt="Test Coverage" src="https://codecov.io/gh/whiteducksoftware/flock/branch/main/graph/badge.svg?token=YOUR_TOKEN_HERE&style=for-the-badge"></a>
-  <img alt="Tests" src="https://img.shields.io/badge/tests-1300+-brightgreen?style=for-the-badge">
+  <img alt="Tests" src="https://img.shields.io/badge/tests-1400+-brightgreen?style=for-the-badge">
 </p>
 
 ---

{flock_core-0.5.22 → flock_core-0.5.24}/docs/about/changelog.md

@@ -189,8 +189,7 @@ similar_incidents = await provider.get_context(store)
 - Added 4 runnable examples in `examples/08-semantic/`:
   - `00_verify_semantic_features.py` - Quick verification (no LLM)
   - `01_intelligent_ticket_routing.py` - Smart routing demo
-  - `02_context_aware_responses.py` - Context-aware with history
-  - `03_multi_criteria_filtering.py` - Advanced filtering patterns
+  - `02_multi_criteria_filtering.py` - Advanced filtering patterns
 - Updated README with semantic subscriptions feature
 - Added API documentation for all new features
 

{flock_core-0.5.22 → flock_core-0.5.24}/docs/guides/semantic-subscriptions.md

@@ -695,8 +695,7 @@ Additional examples in `examples/08-semantic/`:
 
 - `00_verify_semantic_features.py` - Installation verification
 - `01_intelligent_ticket_routing.py` - Multi-agent semantic routing
-- `02_context_aware_responses.py` - Using SemanticContextProvider
-- `03_multi_criteria_filtering.py` - Multiple semantic predicates
+- `02_multi_criteria_filtering.py` - Multiple semantic predicates
 
 ## License
 

{flock_core-0.5.22 → flock_core-0.5.24}/examples/08-semantic/01_intelligent_ticket_routing.py

@@ -38,7 +38,6 @@ class SupportTicket(BaseModel):
 
     message: str = Field(description="The customer's issue or question")
     customer_id: str = Field(description="Customer identifier")
-    category: str | None = Field(default=None, description="Auto-assigned category")
 
 
 @flock_type
@@ -99,7 +98,7 @@ billing_team = (
 # Matches: "can't login", "error message", "not working", "broken feature"
 tech_support = (
     flock.agent("tech_support")
-    .consumes(SupportTicket, semantic_match="technical issue error bug problem")
+    .consumes(SupportTicket, semantic_match="technical issue error bug problem device")
     .publishes(TechnicalResponse)
 )
 
@@ -130,7 +129,7 @@ async def main_cli():
     print("   Expected Route: → Security Team")
 
     await flock.publish(security_ticket)
-    await flock.run_until_idle()
+    await flock.run_until_idle(wait_for_input=True)
 
     # Test Case 2: Billing Issue
     print("\n📋 Ticket 2: Billing Issue")
@@ -142,7 +141,7 @@ async def main_cli():
     print("   Expected Route: → Billing Team")
 
     await flock.publish(billing_ticket)
-    await flock.run_until_idle()
+    await flock.run_until_idle(wait_for_input=True)
 
     # Test Case 3: Technical Issue
     print("\n📋 Ticket 3: Technical Problem")
@@ -154,7 +153,7 @@ async def main_cli():
     print("   Expected Route: → Tech Support")
 
     await flock.publish(tech_ticket)
-    await flock.run_until_idle()
+    await flock.run_until_idle(wait_for_input=True)
 
     # Test Case 4: General Question
     print("\n📋 Ticket 4: General Inquiry")

flock_core-0.5.22/examples/08-semantic/03_multi_criteria_filtering.py → flock_core-0.5.24/examples/08-semantic/02_multi_criteria_filtering.py

@@ -75,7 +75,7 @@ class AuditReport(BaseModel):
 # ============================================================================
 # 🎛️  SETUP: Create agents with advanced semantic filters
 # ============================================================================
-flock = Flock("openai/gpt-4o-mini")
+flock = Flock()
 
 # Agent 1: STRICT security + compliance filter
 # Requires: BOTH "security" AND "compliance" topics + published status

{flock_core-0.5.22 → flock_core-0.5.24}/examples/08-semantic/README.md

@@ -40,32 +40,7 @@ All routing happens automatically based on semantic similarity!
 
 ---
 
-### 02_context_aware_responses.py
-**Learning from historical incidents**
-
-Shows how `SemanticContextProvider` finds similar past incidents and recommends actions based on successful historical resolutions.
-
-**Key Concepts:**
-- `SemanticContextProvider` for historical context
-- Learning from past similar cases
-- Context-enriched decision making
-
-**Run:**
-```bash
-uv run examples/08-semantic/02_context_aware_responses.py
-```
-
-**What You'll See:**
-1. System populates incident history
-2. New incidents arrive
-3. System finds semantically similar past incidents
-4. Recommends actions based on past successful resolutions
-
-Example: "Database connection failures" → Finds similar past "connection pool exhausted" → Recommends "Increase max connections"
-
----
-
-### 03_multi_criteria_filtering.py
+### 02_multi_criteria_filtering.py
 **Advanced semantic filtering with multiple criteria**
 
 Demonstrates sophisticated filtering combining:
@@ -82,7 +57,7 @@ Demonstrates sophisticated filtering combining:
 
 **Run:**
 ```bash
-uv run examples/08-semantic/03_multi_criteria_filtering.py
+uv run examples/08-semantic/02_multi_criteria_filtering.py
 ```
 
 **What You'll See:**

{flock_core-0.5.22 → flock_core-0.5.24}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.5.22"
+version = "0.5.24"
 description = "Flock: A declrative framework for building and orchestrating AI agents."
 readme = "README.md"
 requires-python = ">=3.12"

{flock_core-0.5.22 → flock_core-0.5.24}/src/flock/core/agent.py

@@ -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))
 

{flock_core-0.5.22 → flock_core-0.5.24}/src/flock/core/orchestrator.py

@@ -492,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.
@@ -514,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
@@ -553,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]:
@@ -715,6 +731,7 @@ class Flock(metaclass=AutoTracedMeta):
         partition_key: str | None = None,
         tags: set[str] | None = None,
         is_dashboard: bool = False,
+        schedule_immediately: bool = True,
     ) -> Artifact:
         """Publish an artifact to the blackboard (event-driven).
 
@@ -727,16 +744,22 @@ class Flock(metaclass=AutoTracedMeta):
             partition_key=partition_key,
             tags=tags,
             is_dashboard=is_dashboard,
+            schedule_immediately=schedule_immediately,
         )
 
     async def publish_many(
-        self, objects: Iterable[BaseModel | dict | Artifact], **kwargs: Any
+        self,
+        objects: Iterable[BaseModel | dict | Artifact],
+        schedule_immediately: bool = True,
+        **kwargs: Any,
     ) -> list[Artifact]:
         """Publish multiple artifacts at once (event-driven).
 
         Delegates to ArtifactManager for batch publishing.
         """
-        return await self._artifact_manager.publish_many(objects, **kwargs)
+        return await self._artifact_manager.publish_many(
+            objects, schedule_immediately=schedule_immediately, **kwargs
+        )
 
     # -----------------------------------------------------------------------------
     # NEW DIRECT INVOCATION API - Explicit Control

{flock_core-0.5.22 → flock_core-0.5.24}/src/flock/orchestrator/artifact_manager.py

@@ -53,6 +53,7 @@ class ArtifactManager:
         partition_key: str | None = None,
         tags: set[str] | None = None,
         is_dashboard: bool = False,
+        schedule_immediately: bool = True,
     ) -> Artifact:
         """Publish an artifact to the blackboard (event-driven).
 
@@ -125,12 +126,18 @@ class ArtifactManager:
                 "Expected BaseModel, dict, or Artifact."
             )
 
-        # Persist and schedule matching agents
-        await self.persist_and_schedule(artifact)
+        if schedule_immediately:
+            await self.persist_and_schedule(artifact)
+        else:
+            await self.persist(artifact)
+
         return artifact
 
     async def publish_many(
-        self, objects: Iterable[BaseModel | dict | Artifact], **kwargs: Any
+        self,
+        objects: Iterable[BaseModel | dict | Artifact],
+        schedule_immediately: bool = True,
+        **kwargs: Any,
     ) -> list[Artifact]:
         """Publish multiple artifacts at once (event-driven).
 
@@ -150,7 +157,9 @@ class ArtifactManager:
         """
         artifacts = []
         for obj in objects:
-            artifact = await self.publish(obj, **kwargs)
+            artifact = await self.publish(
+                obj, schedule_immediately=schedule_immediately, **kwargs
+            )
             artifacts.append(artifact)
         return artifacts
 
@@ -164,5 +173,14 @@ class ArtifactManager:
         self._orchestrator.metrics["artifacts_published"] += 1
         await self._scheduler.schedule_artifact(artifact)
 
+    async def persist(self, artifact: Artifact) -> None:
+        """Persist artifact to store without scheduling.
+
+        Args:
+            artifact: Artifact to publish
+        """
+        await self._store.publish(artifact)
+        self._orchestrator.metrics["artifacts_published"] += 1
+
 
 __all__ = ["ArtifactManager"]

{flock_core-0.5.22 → flock_core-0.5.24}/src/flock/semantic/embedding_service.py

@@ -4,13 +4,13 @@ This module provides a singleton service for generating and caching embeddings
 using sentence-transformers.
 """
 
-import logging
+from flock.logging.logging import get_logger
 from collections import OrderedDict
 
 import numpy as np
 
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class LRUCache:
@@ -213,6 +213,10 @@ class EmbeddingService:
 
         similarity = dot_product / (norm1 * norm2)
 
+        logger.debug(
+            f"Computed similarity: {similarity:.4f} between texts '{text1}' and '{text2}'",
+        )
+
         # Clamp to [0, 1] and handle floating point errors
         return float(max(0.0, min(1.0, similarity)))
 

{flock_core-0.5.22 → flock_core-0.5.24}/uv.lock

@@ -847,7 +847,7 @@ wheels = [
 
 [[package]]
 name = "flock-core"
-version = "0.5.22"
+version = "0.5.24"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },

flock_core-0.5.22/examples/08-semantic/02_context_aware_responses.py

@@ -1,259 +0,0 @@
-"""
-Semantic Subscriptions: Context-Aware Incident Response
-
-This example demonstrates using SemanticContextProvider to find similar
-historical incidents and provide informed responses based on past resolutions.
-
-🎯 Key Concepts:
-- SemanticContextProvider for historical context
-- Learning from past similar cases
-- Context-enriched decision making
-
-🎛️  CONFIGURATION: Set USE_DASHBOARD to switch between CLI and Dashboard modes
-
-📚 Requires: uv add flock-core[semantic]
-"""
-
-import asyncio
-from collections import Counter
-
-from pydantic import BaseModel, Field
-
-from flock import Flock
-from flock.components.agent import EngineComponent
-from flock.registry import flock_type
-from flock.semantic import SemanticContextProvider
-from flock.utils.runtime import EvalInputs, EvalResult
-
-
-# ============================================================================
-# 🎛️  CONFIGURATION: Switch between CLI and Dashboard modes
-# ============================================================================
-USE_DASHBOARD = False  # Set to True for dashboard mode, False for CLI mode
-# ============================================================================
-
-
-# ============================================================================
-# 🎛️  TYPE REGISTRATION: Incident types
-# ============================================================================
-@flock_type
-class Incident(BaseModel):
-    """A system incident that needs resolution."""
-
-    description: str = Field(description="Description of the incident")
-    severity: str = Field(description="critical, high, medium, or low")
-    system: str = Field(description="Affected system or service")
-    resolved: bool = Field(default=False, description="Whether incident is resolved")
-    resolution: str | None = Field(default=None, description="How it was resolved")
-
-
-@flock_type
-class IncidentResponse(BaseModel):
-    """Recommended response to an incident."""
-
-    incident_description: str
-    recommended_action: str
-    confidence: str
-    similar_incidents_found: int
-    past_resolutions: list[str] = Field(default_factory=list)
-
-
-# ============================================================================
-# 🎛️  CUSTOM ENGINE: Context-aware incident analyzer
-# ============================================================================
-class ContextAwareEngine(EngineComponent):
-    """Engine that uses historical context to inform decisions."""
-
-    async def evaluate(
-        self, agent, ctx, inputs: EvalInputs, output_group
-    ) -> EvalResult:
-        """Find similar past incidents and recommend action."""
-        from flock.registry import type_registry
-
-        # Get the incoming incident
-        artifact = inputs.artifacts[0]
-        incident = Incident(**artifact.payload)
-
-        print(f"\n📊 Analyzing: {incident.description}")
-
-        # Use SemanticContextProvider to find similar RESOLVED incidents
-        provider = SemanticContextProvider(
-            query_text=incident.description,
-            artifact_type=Incident,
-            where=lambda a: a.payload.get("resolved") is True,
-            threshold=0.4,
-            limit=5,
-        )
-
-        similar = await provider.get_context(ctx.store)
-        print(f"   Found {len(similar)} similar past incidents")
-
-        # Extract past resolutions
-        past_resolutions = []
-        for sim in similar:
-            resolution = sim.payload.get("resolution")
-            if resolution:
-                past_resolutions.append(resolution)
-                print(f"   - Past resolution: {resolution}")
-
-        # Determine recommendation based on past success
-        if past_resolutions:
-            # Use most common resolution
-            most_common = Counter(past_resolutions).most_common(1)[0][0]
-            recommended = most_common
-            confidence = "high"
-        else:
-            # No historical data
-            recommended = "Escalate to on-call engineer for investigation"
-            confidence = "low"
-
-        print(f"   Recommendation: {recommended}")
-        print(f"   Confidence: {confidence}\n")
-
-        # Create response artifact
-        response = IncidentResponse(
-            incident_description=incident.description,
-            recommended_action=recommended,
-            confidence=confidence,
-            similar_incidents_found=len(similar),
-            past_resolutions=past_resolutions,
-        )
-
-        # Return as artifact
-        response_artifact = type_registry.resolve("IncidentResponse")(**response.dict())
-
-        return EvalResult(
-            artifacts=[artifact],  # Pass through for potential further processing
-            state={"response": response.dict()},
-        )
-
-
-# ============================================================================
-# 🎛️  SETUP: Create incident response system
-# ============================================================================
-flock = Flock("openai/gpt-4o-mini")
-
-# Incident responder that learns from history
-incident_responder = (
-    flock.agent("incident_responder")
-    .consumes(Incident)
-    .publishes(IncidentResponse)
-    .with_engines(ContextAwareEngine())
-)
-
-
-# ============================================================================
-# 🎛️  RUN: Simulate incident history and new incidents
-# ============================================================================
-async def main_cli():
-    """CLI mode: Demonstrate context-aware incident response"""
-    print("\n🔍 Context-Aware Incident Response Demo\n")
-    print("=" * 70)
-
-    # Step 1: Populate incident history
-    print("\n📚 Step 1: Populating incident history...")
-    print("-" * 70)
-
-    history = [
-        Incident(
-            description="Database connection pool exhausted",
-            severity="high",
-            system="postgres",
-            resolved=True,
-            resolution="Increased max connections from 100 to 200",
-        ),
-        Incident(
-            description="Database timeout errors during peak traffic",
-            severity="high",
-            system="postgres",
-            resolved=True,
-            resolution="Increased max connections from 100 to 200",
-        ),
-        Incident(
-            description="API response time degraded significantly",
-            severity="medium",
-            system="api-gateway",
-            resolved=True,
-            resolution="Added caching layer with Redis",
-        ),
-        Incident(
-            description="Memory leak in application server",
-            severity="critical",
-            system="app-server",
-            resolved=True,
-            resolution="Restarted service and deployed hotfix for leak",
-        ),
-        Incident(
-            description="Slow query causing database locks",
-            severity="high",
-            system="postgres",
-            resolved=True,
-            resolution="Added database index on user_id column",
-        ),
-    ]
-
-    for inc in history:
-        await flock.store.publish(
-            flock.store._build_artifact(inc, produced_by="history_loader")
-        )
-        print(f"   ✓ {inc.description}")
-
-    print("\n✅ Historical data loaded!")
-
-    # Step 2: Process new incidents with context
-    print("\n📋 Step 2: Processing new incidents with historical context...")
-    print("-" * 70)
-
-    new_incidents = [
-        Incident(
-            description="Database connection failures under load",
-            severity="high",
-            system="postgres",
-        ),
-        Incident(
-            description="API latency spiking during business hours",
-            severity="medium",
-            system="api-gateway",
-        ),
-        Incident(
-            description="Disk space running low on server",
-            severity="low",
-            system="file-server",
-        ),
-    ]
-
-    for incident in new_incidents:
-        await flock.publish(incident)
-        await flock.run_until_idle()
-
-    print("\n" + "=" * 70)
-    print("✅ Incident analysis complete!")
-    print("\n💡 Key Takeaway:")
-    print("   The system learned from past resolutions to recommend")
-    print("   actions for new but similar incidents automatically!")
-    print("\n   - Database connection issues → Increase max connections")
-    print("   - API latency → Add caching layer")
-    print("   - Unknown issue → Escalate to engineer")
-
-
-async def main_dashboard():
-    """Dashboard mode: Serve with interactive web interface"""
-    print("\n🌐 Starting Flock Dashboard...")
-    print("   Visit http://localhost:8000 to see context-aware responses!")
-    print("\n💡 The system will:")
-    print("   1. Find similar past incidents using semantic search")
-    print("   2. Learn from successful past resolutions")
-    print("   3. Recommend actions based on historical data\n")
-
-    await flock.serve(dashboard=True)
-
-
-async def main():
-    if USE_DASHBOARD:
-        await main_dashboard()
-    else:
-        await main_cli()
-
-
-if __name__ == "__main__":
-    asyncio.run(main(), debug=True)