flock-core 0.5.0b27__tar.gz → 0.5.0b28__tar.gz

{flock_core-0.5.0b27 → flock_core-0.5.0b28}/.gitignore

@@ -9,7 +9,7 @@ __pycache__/
 # ignore all .env* files except .env_template
 *.env*
 !*.env_template
-
+pr.md
 .DS_Store
 flock-showcase/
 .showcase/

{flock_core-0.5.0b27 → flock_core-0.5.0b28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b27
+Version: 0.5.0b28
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE

flock_core-0.5.0b28/examples/09-n-shot-learning.py

@@ -0,0 +1,90 @@
+"""
+Example demonstrating n-shot learning with the ExampleUtilityComponent.
+
+This example shows how to:
+1. Create example records
+2. Seed them into storage using the static seed_examples method
+3. Create an agent with example learning enabled
+4. Run the agent to see examples being injected into the input
+"""
+
+from datetime import datetime
+
+from flock.components.utility.example_utility_component import ExampleRecord, ExampleUtilityComponent, ExampleUtilityConfig
+from flock.core import Flock, DefaultAgent
+
+# Create some example records for a customer service agent
+examples = [
+    ExampleRecord(
+        agent_name="customer_service",
+        example_id="example_1",
+        content="Q: How do I reset my password?\nA: To reset your password, click on the 'Forgot Password' link on the login page and follow the instructions sent to your email."
+    ),
+    ExampleRecord(
+        agent_name="customer_service",
+        example_id="example_2", 
+        content="Q: What is your return policy?\nA: We offer a 30-day return policy for all unused items in their original packaging. Simply contact our support team to initiate a return."
+    ),
+    ExampleRecord(
+        agent_name="customer_service",
+        example_id="example_3",
+        content="Q: How long does shipping take?\nA: Standard shipping typically takes 5-7 business days. Express shipping options are available at checkout for 2-3 day delivery."
+    )
+]
+
+# Seed the examples into storage
+print("Seeding examples into storage...")
+ExampleUtilityComponent.seed_examples(examples)
+print(f"Seeded {len(examples)} examples for customer service agent")
+
+# Create a customer service agent with example learning enabled
+agent = DefaultAgent(
+    name="customer_service",
+    description="Helps customers with their inquiries using examples",
+    input="customer_query: str | The customer's question or issue",
+    output="response: str | A helpful response to the customer",
+    enable_examples=True,
+    example_config=ExampleUtilityConfig(
+        max_examples=3,
+        example_timeframe_days=30,
+        example_input_key="examples_context"
+    )
+)
+
+# Create flock and add agent
+flock = Flock(model="azure/gpt-4")
+flock.add_agent(agent)
+
+# Example interaction
+query = "How do I track my order?"
+print(f"\nCustomer query: {query}")
+
+# Run the agent - examples will be automatically injected
+result = flock.run(
+    agent="customer_service",
+    input={"customer_query": query}
+)
+
+print(f"\nAgent response: {result.response}")
+
+# The agent will have received relevant examples in the 'examples_context' input key
+# which can influence its response based on the provided examples
+
+# You can also add more examples programmatically
+new_example = ExampleRecord(
+    agent_name="customer_service",
+    example_id="example_4",
+    content="Q: How do I track my order?\nA: You can track your order by logging into your account and clicking on 'My Orders'. Enter your order number to see the current status and tracking information."
+)
+
+# Seed the new example
+ExampleUtilityComponent.seed_examples([new_example])
+print("\nAdded new example for order tracking")
+
+# Run the agent again with the same query
+result = flock.run(
+    agent="customer_service",
+    input={"customer_query": query}
+)
+
+print(f"\nAgent response with new example: {result.response}")

{flock_core-0.5.0b27 → flock_core-0.5.0b28}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.5.0b27"
+version = "0.5.0b28"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [

{flock_core-0.5.0b27 → flock_core-0.5.0b28}/src/flock/components/utility/__init__.py

@@ -1,11 +1,18 @@
 # src/flock/components/utility/__init__.py
 """Utility components for the Flock framework."""
 
+from .example_utility_component import ExampleUtilityComponent, ExampleUtilityConfig, ExampleRecord
+from .feedback_utility_component import FeedbackUtilityComponent, FeedbackUtilityConfig
 from .memory_utility_component import MemoryUtilityComponent, MemoryUtilityConfig
 from .metrics_utility_component import MetricsUtilityComponent, MetricsUtilityConfig
 from .output_utility_component import OutputUtilityComponent, OutputUtilityConfig
 
 __all__ = [
+    "ExampleUtilityComponent",
+    "ExampleUtilityConfig",
+    "ExampleRecord",
+    "FeedbackUtilityComponent",
+    "FeedbackUtilityConfig",
     "MemoryUtilityComponent",
     "MemoryUtilityConfig",
     "MetricsUtilityComponent",

flock_core-0.5.0b28/src/flock/components/utility/example_utility_component.py

@@ -0,0 +1,250 @@
+"""Example utility component for n-shot learning."""
+
+from datetime import datetime, timedelta
+from typing import Any, Literal
+
+from pydantic import Field
+
+from flock.core.component.agent_component_base import AgentComponentConfig
+from flock.core.component.utility_component import UtilityComponent
+from flock.core.context.context import FlockContext
+from flock.core.logging.logging import get_logger
+from flock.core.registry import flock_component
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+    from flock.webapp.app.services.sharing_store import SharedLinkStoreInterface
+
+logger = get_logger("components.utility.example")
+
+
+class ExampleUtilityConfig(AgentComponentConfig):
+    """Configuration for the ExampleUtilityComponent."""
+    
+    # Storage configuration
+    storage_type: Literal["sqlite", "azure"] = Field(
+        default="sqlite",
+        description="Type of storage backend for example data"
+    )
+    
+    # SQLite configuration
+    sqlite_db_path: str = Field(
+        default="./flock_examples.db",
+        description="Path to SQLite database file"
+    )
+    
+    # Azure Table Storage configuration
+    azure_connection_string: str | None = Field(
+        default=None,
+        description="Azure Table Storage connection string"
+    )
+    azure_table_name: str = Field(
+        default="flockexamples",
+        description="Azure Table Storage table name"
+    )
+    
+    # Example selection criteria
+    max_examples: int = Field(
+        default=5,
+        description="Maximum number of examples to include"
+    )
+    example_timeframe_days: int = Field(
+        default=30,
+        description="Only include examples from the last N days"
+    )
+    
+    # Example injection settings
+    example_input_key: str = Field(
+        default="examples_context",
+        description="Input key to use for injected examples"
+    )
+    
+    # Example filtering
+    example_filter_keywords: list[str] = Field(
+        default_factory=list,
+        description="Keywords to filter examples (only include examples containing these)"
+    )
+    example_exclude_keywords: list[str] = Field(
+        default_factory=list,
+        description="Keywords to exclude examples containing these"
+    )
+
+
+@flock_component(config_class=ExampleUtilityConfig)
+class ExampleUtilityComponent(UtilityComponent):
+    """Utility component that injects relevant examples into agent inputs for n-shot learning."""
+    
+    config: ExampleUtilityConfig = Field(
+        default_factory=ExampleUtilityConfig,
+        description="Example component configuration"
+    )
+    
+    def __init__(self, name: str = "examples", config: ExampleUtilityConfig | None = None, **data):
+        super().__init__(name=name, config=config or ExampleUtilityConfig(), **data)
+        self._store: SharedLinkStoreInterface | None = None
+    
+    async def _get_store(self) -> SharedLinkStoreInterface:
+        """Get the appropriate example store based on configuration."""
+        if self._store is None:
+            if self.config.storage_type == "sqlite":
+                from flock.webapp.app.services.sharing_store import SQLiteSharedLinkStore
+                self._store = SQLiteSharedLinkStore(self.config.sqlite_db_path)
+            elif self.config.storage_type == "azure":
+                if not self.config.azure_connection_string:
+                    raise ValueError("Azure connection string is required for Azure storage")
+                from flock.webapp.app.services.sharing_store import AzureTableSharedLinkStore
+                self._store = AzureTableSharedLinkStore(
+                    connection_string=self.config.azure_connection_string,
+                    table_name=self.config.azure_table_name
+                )
+            else:
+                raise ValueError(f"Unsupported storage type: {self.config.storage_type}")
+            
+            await self._store.initialize()
+        
+        return self._store
+    
+    @staticmethod
+    def seed_examples(examples: list["ExampleRecord"]) -> None:
+        """Seed examples into the storage system.
+        
+        Args:
+            examples: List of ExampleRecord objects to seed
+        """
+        import asyncio
+        
+        async def _seed_examples():
+            # Create a default component for seeding
+            component = ExampleUtilityComponent()
+            store = await component._get_store()
+            
+            for example in examples:
+                await store.save_example(example)
+            
+            logger.info(f"Seeded {len(examples)} examples into storage")
+        
+        # Run the async function
+        asyncio.run(_seed_examples())
+    
+    async def _get_relevant_examples(
+        self, 
+        agent_name: str, 
+        inputs: dict[str, Any]
+    ) -> list["ExampleRecord"]:
+        """Get relevant examples for the given agent and inputs."""
+        store = await self._get_store()
+        
+        # Get all examples for this agent
+        all_examples = await store.get_all_examples_for_agent(agent_name)
+        
+        # Filter by timeframe
+        cutoff_date = datetime.utcnow() - timedelta(days=self.config.example_timeframe_days)
+        filtered_examples = [
+            ex for ex in all_examples 
+            if ex.created_at >= cutoff_date
+        ]
+        
+        # Filter by keywords if specified
+        if self.config.example_filter_keywords:
+            filtered_examples = [
+                ex for ex in filtered_examples
+                if any(keyword.lower() in ex.content.lower() for keyword in self.config.example_filter_keywords)
+            ]
+        
+        # Exclude by keywords if specified
+        if self.config.example_exclude_keywords:
+            filtered_examples = [
+                ex for ex in filtered_examples
+                if not any(keyword.lower() in ex.content.lower() for keyword in self.config.example_exclude_keywords)
+            ]
+        
+        # Sort by recency and limit
+        filtered_examples.sort(key=lambda ex: ex.created_at, reverse=True)
+        return filtered_examples[:self.config.max_examples]
+    
+    def _format_examples_for_injection(
+        self, 
+        example_records: list["ExampleRecord"]
+    ) -> str:
+        """Format example records for injection into agent input."""
+        if not example_records:
+            return "No relevant examples available."
+        
+        formatted_parts = []
+        formatted_parts.append(f"Here are {len(example_records)} examples to guide your response:")
+        
+        for i, ex in enumerate(example_records, 1):
+            ex_text = f"\nExample {i} (ID: {ex.example_id}):"
+            ex_text += f"\n{ex.content}"
+            ex_text += f"\nDate: {ex.created_at.strftime('%Y-%m-%d')}"
+            formatted_parts.append(ex_text)
+        
+        return "\n".join(formatted_parts)
+    
+    async def on_pre_evaluate(
+        self,
+        agent: "FlockAgent",
+        inputs: dict[str, Any],
+        context: FlockContext | None = None,
+    ) -> dict[str, Any]:
+        """Inject relevant examples into agent inputs before evaluation."""
+        logger.debug(f"Injecting examples for agent '{agent.name}'")
+        
+        try:
+            # Get relevant examples for this agent
+            example_records = await self._get_relevant_examples(agent.name, inputs)
+            
+            # Format examples for injection
+            formatted_examples = self._format_examples_for_injection(example_records)
+            
+            # Create a copy of inputs to avoid modifying the original
+            enhanced_inputs = inputs.copy()
+            
+            # Inject examples using the configured key
+            enhanced_inputs[self.config.example_input_key] = formatted_examples
+            
+            logger.debug(f"Injected {len(example_records)} examples into '{self.config.example_input_key}'")
+            
+            return enhanced_inputs
+            
+        except Exception as e:
+            logger.error(f"Error injecting examples: {e}")
+            # Return original inputs if example injection fails
+            return inputs
+
+
+# Example record model
+class ExampleRecord:
+    """Record for storing example data."""
+    
+    def __init__(
+        self,
+        agent_name: str,
+        example_id: str,
+        content: str,
+        created_at: datetime | None = None
+    ):
+        self.agent_name = agent_name
+        self.example_id = example_id
+        self.content = content
+        self.created_at = created_at or datetime.utcnow()
+    
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for storage."""
+        return {
+            "agent_name": self.agent_name,
+            "example_id": self.example_id,
+            "content": self.content,
+            "created_at": self.created_at.isoformat(),
+            "context_type": "example"
+        }
+    
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ExampleRecord":
+        """Create from dictionary from storage."""
+        return cls(
+            agent_name=data["agent_name"],
+            example_id=data["example_id"],
+            content=data["content"],
+            created_at=datetime.fromisoformat(data["created_at"])
+        )

flock_core-0.5.0b28/src/flock/components/utility/feedback_utility_component.py

@@ -0,0 +1,206 @@
+"""Feedback utility component for learning from user feedback."""
+
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import Field
+
+from flock.core.component.agent_component_base import AgentComponentConfig
+from flock.core.component.utility_component import UtilityComponent
+from flock.core.context.context import FlockContext
+from flock.core.logging.logging import get_logger
+from flock.core.registry import flock_component
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+    from flock.webapp.app.services.sharing_models import FeedbackRecord
+    from flock.webapp.app.services.sharing_store import SharedLinkStoreInterface
+
+logger = get_logger("components.utility.feedback")
+
+
+class FeedbackUtilityConfig(AgentComponentConfig):
+    """Configuration for the FeedbackUtilityComponent."""
+    
+    # Storage configuration
+    storage_type: Literal["sqlite", "azure"] = Field(
+        default="sqlite",
+        description="Type of storage backend for feedback data"
+    )
+    
+    # SQLite configuration
+    sqlite_db_path: str = Field(
+        default="./flock_feedback.db",
+        description="Path to SQLite database file"
+    )
+    
+    # Azure Table Storage configuration
+    azure_connection_string: str | None = Field(
+        default=None,
+        description="Azure Table Storage connection string"
+    )
+    azure_table_name: str = Field(
+        default="flockfeedback",
+        description="Azure Table Storage table name"
+    )
+    
+    # Feedback selection criteria
+    max_feedback_items: int = Field(
+        default=5,
+        description="Maximum number of feedback items to include"
+    )
+    feedback_timeframe_days: int = Field(
+        default=30,
+        description="Only include feedback from the last N days"
+    )
+    
+    # Feedback injection settings
+    feedback_input_key: str = Field(
+        default="feedback_context",
+        description="Input key to use for injected feedback"
+    )
+    include_expected_responses: bool = Field(
+        default=True,
+        description="Whether to include expected responses from feedback"
+    )
+    include_actual_responses: bool = Field(
+        default=False,
+        description="Whether to include actual responses from feedback"
+    )
+    
+    # Feedback filtering
+    feedback_filter_keywords: list[str] = Field(
+        default_factory=list,
+        description="Keywords to filter feedback (only include feedback containing these)"
+    )
+    feedback_exclude_keywords: list[str] = Field(
+        default_factory=list,
+        description="Keywords to exclude feedback containing these"
+    )
+
+
+@flock_component(config_class=FeedbackUtilityConfig)
+class FeedbackUtilityComponent(UtilityComponent):
+    """Utility component that injects relevant feedback into agent inputs."""
+    
+    config: FeedbackUtilityConfig = Field(
+        default_factory=FeedbackUtilityConfig,
+        description="Feedback component configuration"
+    )
+    
+    def __init__(self, name: str = "feedback", config: FeedbackUtilityConfig | None = None, **data):
+        super().__init__(name=name, config=config or FeedbackUtilityConfig(), **data)
+        self._store: SharedLinkStoreInterface | None = None
+    
+    async def _get_store(self) -> SharedLinkStoreInterface:
+        """Get the appropriate feedback store based on configuration."""
+        if self._store is None:
+            if self.config.storage_type == "sqlite":
+                from flock.webapp.app.services.sharing_store import SQLiteSharedLinkStore
+                self._store = SQLiteSharedLinkStore(self.config.sqlite_db_path)
+            elif self.config.storage_type == "azure":
+                if not self.config.azure_connection_string:
+                    raise ValueError("Azure connection string is required for Azure storage")
+                from flock.webapp.app.services.sharing_store import AzureTableSharedLinkStore
+                self._store = AzureTableSharedLinkStore(
+                    connection_string=self.config.azure_connection_string,
+                    table_name=self.config.azure_table_name
+                )
+            else:
+                raise ValueError(f"Unsupported storage type: {self.config.storage_type}")
+            
+            await self._store.initialize()
+        
+        return self._store
+    
+    async def _get_relevant_feedback(
+        self, 
+        agent_name: str, 
+        inputs: dict[str, Any]
+    ) -> list["FeedbackRecord"]:
+        """Get relevant feedback for the given agent and inputs."""
+        store = await self._get_store()
+        
+        # Get all feedback for this agent
+        all_feedback = await store.get_all_feedback_records_for_agent(agent_name)
+        
+        # Filter by timeframe
+        cutoff_date = datetime.utcnow() - timedelta(days=self.config.feedback_timeframe_days)
+        filtered_feedback = [
+            fb for fb in all_feedback 
+            if fb.created_at >= cutoff_date
+        ]
+        
+        # Filter by keywords if specified
+        if self.config.feedback_filter_keywords:
+            filtered_feedback = [
+                fb for fb in filtered_feedback
+                if any(keyword.lower() in fb.reason.lower() for keyword in self.config.feedback_filter_keywords)
+            ]
+        
+        # Exclude by keywords if specified
+        if self.config.feedback_exclude_keywords:
+            filtered_feedback = [
+                fb for fb in filtered_feedback
+                if not any(keyword.lower() in fb.reason.lower() for keyword in self.config.feedback_exclude_keywords)
+            ]
+        
+        # Sort by recency and limit
+        filtered_feedback.sort(key=lambda fb: fb.created_at, reverse=True)
+        return filtered_feedback[:self.config.max_feedback_items]
+    
+    def _format_feedback_for_injection(
+        self, 
+        feedback_records: list["FeedbackRecord"]
+    ) -> str:
+        """Format feedback records for injection into agent input."""
+        if not feedback_records:
+            return "No relevant feedback available."
+        
+        formatted_parts = []
+        formatted_parts.append(f"Here are {len(feedback_records)} pieces of relevant feedback from previous interactions:")
+        
+        for i, fb in enumerate(feedback_records, 1):
+            fb_text = f"\n{i}. Feedback: {fb.reason}"
+            
+            if self.config.include_expected_responses and fb.expected_response:
+                fb_text += f"\n   Expected response: {fb.expected_response}"
+            
+            if self.config.include_actual_responses and fb.actual_response:
+                fb_text += f"\n   Actual response: {fb.actual_response}"
+            
+            fb_text += f"\n   Date: {fb.created_at.strftime('%Y-%m-%d')}"
+            formatted_parts.append(fb_text)
+        
+        return "\n".join(formatted_parts)
+    
+    async def on_pre_evaluate(
+        self,
+        agent: "FlockAgent",
+        inputs: dict[str, Any],
+        context: FlockContext | None = None,
+    ) -> dict[str, Any]:
+        """Inject relevant feedback into agent inputs before evaluation."""
+        logger.debug(f"Injecting feedback for agent '{agent.name}'")
+        
+        try:
+            # Get relevant feedback for this agent
+            feedback_records = await self._get_relevant_feedback(agent.name, inputs)
+            
+            # Format feedback for injection
+            formatted_feedback = self._format_feedback_for_injection(feedback_records)
+            
+            # Create a copy of inputs to avoid modifying the original
+            enhanced_inputs = inputs.copy()
+            
+            # Inject feedback using the configured key
+            enhanced_inputs[self.config.feedback_input_key] = formatted_feedback
+            
+            logger.debug(f"Injected {len(feedback_records)} feedback items into '{self.config.feedback_input_key}'")
+            
+            return enhanced_inputs
+            
+        except Exception as e:
+            logger.error(f"Error injecting feedback: {e}")
+            # Return original inputs if feedback injection fails
+            return inputs

{flock_core-0.5.0b27 → flock_core-0.5.0b28}/src/flock/core/agent/default_agent.py

@@ -10,6 +10,14 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any, Literal
 
+from flock.components.utility.example_utility_component import (
+    ExampleUtilityComponent,
+    ExampleUtilityConfig,
+)
+from flock.components.utility.feedback_utility_component import (
+    FeedbackUtilityComponent,
+    FeedbackUtilityConfig,
+)
 from flock.components.utility.metrics_utility_component import (
     MetricsUtilityComponent,
     MetricsUtilityConfig,
@@ -28,6 +36,7 @@ class DefaultAgent(FlockAgent):
     - DeclarativeEvaluationComponent (LLM evaluation)
     - OutputUtilityComponent (formatting/printing)
     - MetricsUtilityComponent (latency tracking)
+    - FeedbackUtilityComponent (feedback learning) - optional
     """
 
     def __init__(
@@ -62,6 +71,12 @@ class DefaultAgent(FlockAgent):
         wait_for_input: bool = False,
         # Metrics utility
         alert_latency_threshold_ms: int = 30_000,
+        # Feedback utility
+        enable_feedback: bool = False,
+        feedback_config: FeedbackUtilityConfig | None = None,
+        # Example utility
+        enable_examples: bool = False,
+        example_config: ExampleUtilityConfig | None = None,
         # Workflow
         next_agent: DynamicStr | None = None,
         temporal_activity_config: TemporalActivityConfig | None = None,
@@ -99,6 +114,10 @@ class DefaultAgent(FlockAgent):
             write_to_file: Save outputs to file
             wait_for_input: Wait for user input after execution
             alert_latency_threshold_ms: Threshold for latency alerts
+            enable_feedback: Whether to enable feedback learning component
+            feedback_config: Configuration for feedback component
+            enable_examples: Whether to enable example learning component
+            example_config: Configuration for example component
             next_agent: Next agent in workflow chain
             temporal_activity_config: Configuration for Temporal workflow execution
         """
@@ -161,6 +180,23 @@ class DefaultAgent(FlockAgent):
             name="metrics_tracker", config=metrics_config
         )
 
+        # Feedback utility component (optional)
+        components = [evaluator, output_component, metrics_component]
+        if enable_feedback:
+            feedback_component = FeedbackUtilityComponent(
+                name="feedback",
+                config=feedback_config or FeedbackUtilityConfig()
+            )
+            components.append(feedback_component)
+        
+        # Example utility component (optional)
+        if enable_examples:
+            example_component = ExampleUtilityComponent(
+                name="examples",
+                config=example_config or ExampleUtilityConfig()
+            )
+            components.append(example_component)
+
         super().__init__(
             name=name,
             model=model,
@@ -170,7 +206,7 @@ class DefaultAgent(FlockAgent):
             tools=tools,
             servers=servers,
             tool_whitelist=tool_whitelist,
-            components=[evaluator, output_component, metrics_component],
+            components=components,
             config=FlockAgentConfig(
                 write_to_file=write_to_file,
                 wait_for_input=wait_for_input,