flock-core 0.5.0b26__py3-none-any.whl → 0.5.0b28__py3-none-any.whl

flock/components/evaluation/declarative_evaluation_component.py

@@ -121,6 +121,14 @@ class DeclarativeEvaluationConfig(AgentComponentConfig):
         default=False,
         description="Include the reasoning in the output.",
     )
+    status_output_field: str = Field(
+        default="_status_output",
+        description="The field name for the status output.",
+    )
+    include_status_output: bool = Field(
+        default=False,
+        description="Include the status output in the finaloutput.",
+    )
     adapter: Literal["chat", "json", "xml", "two_step"] | None = Field(
         default=None,
         description="Optional DSPy adapter to use for formatting/parsing.",
@@ -296,6 +304,7 @@ class DeclarativeEvaluationComponent(
         from rich.live import Live
 
         signature_order = []
+        status_field = self.config.status_output_field
         try:
             signature_order = list(signature.output_fields.keys())
         except Exception:
@@ -309,7 +318,10 @@ class DeclarativeEvaluationComponent(
             if field_name not in display_data:
                 display_data[field_name] = ""
 
+        display_data[status_field] = ""
+
         stream_buffers: defaultdict[str, list[str]] = defaultdict(list)
+        stream_buffers[status_field] = []
 
         formatter = theme_dict = styles = agent_label = None
         live_cm = nullcontext()
@@ -359,9 +371,14 @@ class DeclarativeEvaluationComponent(
                     _d = None
 
                 if isinstance(value, StatusMessage):
-                    message = getattr(value, "message", "")
-                    if message and live is not None:
-                        live.console.log(f"[status] {message}")
+                    token = getattr(value, "message", "")
+                    if token:
+                        stream_buffers[status_field].append(str(token) + "\n")
+                        display_data[status_field] = "".join(
+                            stream_buffers[status_field]
+                        )
+                        if formatter is not None:
+                            _refresh_panel()
                     continue
 
                 if isinstance(value, StreamResponse):
@@ -387,14 +404,37 @@ class DeclarativeEvaluationComponent(
                     continue
 
                 if isinstance(value, ModelResponseStream):
-                    try:
-                        chunk = value
-                        text = chunk.choices[0].delta.content or ""
-                        if text and live is not None:
-                            live.console.log(text)
-                    except Exception:
-                        pass
+                    for callback in self.config.stream_callbacks or []:
+                        try:
+                            callback(value)
+                        except Exception as e:
+                            logger.warning(f"Stream callback error: {e}")
+
+                    chunk = value
+                    token = chunk.choices[0].delta.content or ""
+                    signature_field = getattr(
+                        value, "signature_field_name", None
+                    )
+                    if signature_field:
+                        if signature_field not in display_data:
+                            display_data[signature_field] = ""
+                        if token:
+                            stream_buffers[signature_field].append(str(token))
+                            display_data[signature_field] = "".join(
+                                stream_buffers[signature_field]
+                            )
+                        if formatter is not None:
+                            _refresh_panel()
+                    else:
+                        if token:
+                            stream_buffers[status_field].append(str(token))
+                            display_data[status_field] = "".join(
+                                stream_buffers[status_field]
+                            )
+                        if formatter is not None:
+                            _refresh_panel()
                     continue
+                    
 
                 if _d and isinstance(value, _d.Prediction):
                     result_dict, cost, lm_history = self._process_result(
@@ -414,9 +454,14 @@ class DeclarativeEvaluationComponent(
                                 ordered_final[field_name] = final_result[
                                     field_name
                                 ]
+                            
+                        
                         for key, val in final_result.items():
                             if key not in ordered_final:
                                 ordered_final[key] = val
+                        
+                        if self.config.include_status_output:   
+                            ordered_final[self.config.status_output_field] = display_data[self.config.status_output_field]
                         display_data.clear()
                         display_data.update(ordered_final)
                         _refresh_panel()
@@ -533,6 +578,19 @@ class DeclarativeEvaluationComponent(
                 for k, v in result_dict.items()
                 if not (k.startswith("reasoning") or k.startswith("trajectory"))
             }
+    
+    def filter_status_output(
+        self, result_dict: dict[str, Any], include_status_output: bool
+    ) -> dict[str, Any]:
+        """Filter out status output from the result dictionary."""
+        if include_status_output:
+            return result_dict
+        else:
+            return {
+                k: v
+                for k, v in result_dict.items()
+                if not (k.startswith("_status_output"))
+            }
 
     def filter_reasoning(
         self, result_dict: dict[str, Any], include_reasoning: bool

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/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/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/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__(
@@ -44,13 +53,14 @@ class DefaultAgent(FlockAgent):
         use_cache: bool = False,
         temperature: float = 0.7,
         max_tokens: int | None = None,
-        max_tool_calls: int = 0,
+        max_tool_calls: int = 10,
         max_retries: int = 2,
         stream: bool = True,
         stream_callbacks: list[Callable[..., Any] | Any] | None = None,
         stream_vertical_overflow: Literal["crop", "ellipsis", "crop_above", "visible"] = "crop_above",
         include_thought_process: bool = False,
         include_reasoning: bool = False,
+        include_status_output: bool = False,
         # Output utility parameters
         enable_rich_tables: bool = True,
         output_theme: OutputTheme | None = None,
@@ -61,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,
@@ -90,6 +106,7 @@ class DefaultAgent(FlockAgent):
             stream_vertical_overflow: Rich Live overflow handling ('ellipsis', 'crop', 'crop_above', 'visible')
             include_thought_process: Include reasoning in output
             include_reasoning: Include detailed reasoning steps
+            include_status_output: Include status output in output
             enable_rich_tables: Enable rich table formatting for output
             output_theme: Theme for output formatting
             no_output: Disable output printing
@@ -97,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
         """
@@ -129,6 +150,7 @@ class DefaultAgent(FlockAgent):
             stream_vertical_overflow=stream_vertical_overflow,
             include_thought_process=include_thought_process,
             include_reasoning=include_reasoning,
+            include_status_output=include_status_output,
         )
         if max_tokens is not None:
             _eval_kwargs["max_tokens"] = max_tokens
@@ -158,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,
@@ -167,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,

flock/core/flock_factory.py

@@ -443,6 +443,30 @@ class FlockFactory:
         include_reasoning: bool = False,
         next_agent: DynamicStr | None = None,
         temporal_activity_config: TemporalActivityConfig | None = None,
+        # Feedback parameters
+        enable_feedback: bool = False,
+        feedback_storage_type: Literal["sqlite", "azure"] = "sqlite",
+        feedback_max_items: int = 5,
+        feedback_timeframe_days: int = 30,
+        feedback_input_key: str = "feedback_context",
+        feedback_include_expected_responses: bool = True,
+        feedback_include_actual_responses: bool = False,
+        feedback_filter_keywords: list[str] | None = None,
+        feedback_exclude_keywords: list[str] | None = None,
+        feedback_sqlite_db_path: str = "./flock_feedback.db",
+        feedback_azure_connection_string: str | None = None,
+        feedback_azure_table_name: str = "flockfeedback",
+        # Example parameters
+        enable_examples: bool = False,
+        example_storage_type: Literal["sqlite", "azure"] = "sqlite",
+        example_max_examples: int = 5,
+        example_timeframe_days: int = 30,
+        example_input_key: str = "examples_context",
+        example_filter_keywords: list[str] | None = None,
+        example_exclude_keywords: list[str] | None = None,
+        example_sqlite_db_path: str = "./flock_examples.db",
+        example_azure_connection_string: str | None = None,
+        example_azure_table_name: str = "flockexamples",
     ) -> FlockAgent:
         """Create a default FlockAgent.
 
@@ -452,6 +476,40 @@ class FlockFactory:
         """
         _maybe_warn_factory_deprecation()
 
+        # Configure feedback if enabled
+        feedback_config = None
+        if enable_feedback:
+            from flock.components.utility.feedback_utility_component import FeedbackUtilityConfig
+            feedback_config = FeedbackUtilityConfig(
+                storage_type=feedback_storage_type,
+                max_feedback_items=feedback_max_items,
+                feedback_timeframe_days=feedback_timeframe_days,
+                feedback_input_key=feedback_input_key,
+                include_expected_responses=feedback_include_expected_responses,
+                include_actual_responses=feedback_include_actual_responses,
+                feedback_filter_keywords=feedback_filter_keywords or [],
+                feedback_exclude_keywords=feedback_exclude_keywords or [],
+                sqlite_db_path=feedback_sqlite_db_path,
+                azure_connection_string=feedback_azure_connection_string,
+                azure_table_name=feedback_azure_table_name,
+            )
+        
+        # Configure examples if enabled
+        example_config = None
+        if enable_examples:
+            from flock.components.utility.example_utility_component import ExampleUtilityConfig
+            example_config = ExampleUtilityConfig(
+                storage_type=example_storage_type,
+                max_examples=example_max_examples,
+                example_timeframe_days=example_timeframe_days,
+                example_input_key=example_input_key,
+                example_filter_keywords=example_filter_keywords or [],
+                example_exclude_keywords=example_exclude_keywords or [],
+                sqlite_db_path=example_sqlite_db_path,
+                azure_connection_string=example_azure_connection_string,
+                azure_table_name=example_azure_table_name,
+            )
+
         return DefaultAgent(
             name=name,
             description=description,
@@ -477,6 +535,10 @@ class FlockFactory:
             alert_latency_threshold_ms=alert_latency_threshold_ms,
             next_agent=next_agent,
             temporal_activity_config=temporal_activity_config,
+            enable_feedback=enable_feedback,
+            feedback_config=feedback_config,
+            enable_examples=enable_examples,
+            example_config=example_config,
         )
 
     @staticmethod

flock/core/logging/formatters/themed_formatter.py

@@ -256,6 +256,14 @@ def create_rich_renderable(
     if styles is None:
         styles = get_default_styles(theme)
 
+    # Convert Pydantic BaseModel instances to dicts for rendering
+    try:
+        from pydantic import BaseModel
+        if isinstance(value, BaseModel):
+            value = value.model_dump()
+    except ImportError:
+        pass
+
     # If the value is a dictionary, render it as a table.
     if isinstance(value, dict):
         # Convert table_box string into an actual box style.

flock/webapp/app/services/sharing_store.py

@@ -5,6 +5,7 @@ import sqlite3
 from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Any
+from datetime import datetime
 
 import aiosqlite
 
@@ -65,6 +66,22 @@ class SharedLinkStoreInterface(ABC):
     async def get_all_feedback_records_for_agent(self, agent_name: str) -> list[FeedbackRecord]:
         """Get all feedback records for a given agent."""
         pass
+    
+    # Examples
+    @abstractmethod
+    async def save_example(self, example: Any):
+        """Persist an example record."""
+        pass
+    
+    @abstractmethod
+    async def get_example(self, id: str) -> Any | None:
+        """Get a single example record."""
+        pass
+    
+    @abstractmethod
+    async def get_all_examples_for_agent(self, agent_name: str) -> list[Any]:
+        """Get all example records for a given agent."""
+        pass
 
 class SQLiteSharedLinkStore(SharedLinkStoreInterface):
     """SQLite implementation for storing and retrieving shared link configurations."""
@@ -99,18 +116,13 @@ class SQLiteSharedLinkStore(SharedLinkStoreInterface):
                     ("chat_history_key", "TEXT"),
                     ("chat_response_key", "TEXT")
                 ]
-
-                for column_name, column_type in new_columns:
+                for col_name, col_def in new_columns:
                     try:
-                        await db.execute(f"ALTER TABLE shared_links ADD COLUMN {column_name} {column_type}")
-                        logger.info(f"Added column '{column_name}' to shared_links table.")
-                    except sqlite3.OperationalError as e:
-                        if "duplicate column name" in str(e).lower():
-                            logger.debug(f"Column '{column_name}' already exists in shared_links table.")
-                        else:
-                            raise # Re-raise if it's a different operational error
-
-                # Feedback table
+                        await db.execute(f"ALTER TABLE shared_links ADD COLUMN {col_name} {col_def}")
+                    except sqlite3.OperationalError:
+                        pass  # Column already exists
+
+                # Create feedback table if it doesn't exist
                 await db.execute(
                     """
                     CREATE TABLE IF NOT EXISTS feedback (
@@ -123,16 +135,27 @@ class SQLiteSharedLinkStore(SharedLinkStoreInterface):
                         flock_name TEXT,
                         agent_name TEXT,
                         flock_definition TEXT,
+                        created_at TEXT NOT NULL
+                    )
+                    """
+                )
+                
+                # Create examples table if it doesn't exist
+                await db.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS examples (
+                        example_id TEXT PRIMARY KEY,
+                        agent_name TEXT NOT NULL,
+                        content TEXT NOT NULL,
                         created_at TEXT NOT NULL,
-                        FOREIGN KEY(share_id) REFERENCES shared_links(share_id)
+                        context_type TEXT NOT NULL DEFAULT 'example'
                     )
                     """
                 )
 
                 await db.commit()
-            logger.info(f"Database initialized and shared_links table schema ensured at {self.db_path}")
-        except sqlite3.Error as e:
-            logger.error(f"SQLite error during initialization: {e}", exc_info=True)
+        except Exception as e:
+            logger.error(f"Error initializing database: {e}", exc_info=True)
             raise
 
     async def save_config(self, config: SharedLinkConfig) -> SharedLinkConfig:
@@ -304,6 +327,76 @@ class SQLiteSharedLinkStore(SharedLinkStoreInterface):
             logger.error(f"SQLite error saving feedback {record.feedback_id}: {e}", exc_info=True)
             raise
 
+    async def save_example(self, example: Any) -> Any:
+        """Persist an example record to SQLite."""
+        try:
+            example_dict = example.to_dict()
+            async with aiosqlite.connect(self.db_path) as db:
+                await db.execute(
+                    """INSERT INTO examples (
+                        example_id, agent_name, content, created_at, context_type
+                    ) VALUES (?, ?, ?, ?, ?)""",
+                    (
+                        example_dict["example_id"],
+                        example_dict["agent_name"],
+                        example_dict["content"],
+                        example_dict["created_at"],
+                        example_dict["context_type"],
+                    ),
+                )
+                await db.commit()
+            logger.info(f"Saved example {example_dict['example_id']} for agent {example_dict['agent_name']}")
+            return example
+        except sqlite3.Error as e:
+            logger.error(f"SQLite error saving example {example.example_id}: {e}", exc_info=True)
+            raise
+
+    async def get_example(self, id: str) -> Any | None:
+        """Get a single example record."""
+        try:
+            async with aiosqlite.connect(self.db_path) as db, db.execute(
+                """SELECT example_id, agent_name, content, created_at FROM examples WHERE example_id = ?""",
+                (id,)
+            ) as cursor:
+                row = await cursor.fetchone()
+                if row:
+                    from flock.components.utility.example_utility_component import ExampleRecord
+                    return ExampleRecord(
+                        example_id=row[0],
+                        agent_name=row[1],
+                        content=row[2],
+                        created_at=datetime.fromisoformat(row[3])
+                    )
+                return None
+        except sqlite3.Error as e:
+            logger.error(f"SQLite error retrieving example {id}: {e}", exc_info=True)
+            return None
+
+    async def get_all_examples_for_agent(self, agent_name: str) -> list[Any]:
+        """Retrieve all example records from SQLite."""
+        try:
+            async with aiosqlite.connect(self.db_path) as db, db.execute(
+                """SELECT example_id, agent_name, content, created_at FROM examples WHERE agent_name = ? ORDER BY created_at DESC""",
+                (agent_name,)
+            ) as cursor:
+                rows = await cursor.fetchall()
+
+            examples = []
+            for row in rows:
+                from flock.components.utility.example_utility_component import ExampleRecord
+                examples.append(ExampleRecord(
+                    example_id=row[0],
+                    agent_name=row[1],
+                    content=row[2],
+                    created_at=datetime.fromisoformat(row[3])
+                ))
+
+            logger.debug(f"Retrieved {len(examples)} example records")
+            return examples
+        except sqlite3.Error as e:
+            logger.error(f"SQLite error retrieving all example records: {e}", exc_info=True)
+            return []  # Return empty list on error
+
 
 # ---------------------------------------------------------------------------
 # Azure Table + Blob implementation
@@ -568,6 +661,77 @@ class AzureTableSharedLinkStore(SharedLinkStoreInterface):
             )
             return records
 
+    # -------------------------------------------------------- save_example --
+    async def save_example(self, example: Any) -> Any:
+        """Persist an example record to Azure Table Storage."""
+        tbl_client = self.table_svc.get_table_client("flockexamples")
+        
+        example_dict = example.to_dict()
+        
+        entity = {
+            "PartitionKey": "examples",
+            "RowKey": example_dict["example_id"],
+            "agent_name": example_dict["agent_name"],
+            "content": example_dict["content"],
+            "created_at": example_dict["created_at"],
+            "context_type": example_dict["context_type"]
+        }
+        
+        # ------------------------------------------------------------------ Table upsert
+        await tbl_client.upsert_entity(entity)
+        logger.info(f"Saved example {example_dict['example_id']} for agent {example_dict['agent_name']}")
+        return example
+
+    # -------------------------------------------------------- get_example --
+    async def get_example(self, id: str) -> Any | None:
+        """Retrieve a single example record from Azure Table Storage."""
+        tbl_client = self.table_svc.get_table_client("flockexamples")
+        try:
+            entity = await tbl_client.get_entity("examples", id)
+        except ResourceNotFoundError:
+            logger.debug("No example record found for ID: %s", id)
+            return None
+
+        from flock.components.utility.example_utility_component import ExampleRecord
+        return ExampleRecord(
+            example_id=id,
+            agent_name=entity["agent_name"],
+            content=entity["content"],
+            created_at=entity["created_at"]
+        )
+
+    # ------------------------------------------- get_all_examples_for_agent --
+    async def get_all_examples_for_agent(self, agent_name: str) -> list[Any]:
+        """Retrieve all example records from Azure Table Storage for a specific agent."""
+        tbl_client = self.table_svc.get_table_client("flockexamples")
+
+        # Use Azure Table Storage filtering to only get records for the specified agent
+        escaped_agent_name = agent_name.replace("'", "''")
+        filter_query = f"agent_name eq '{escaped_agent_name}'"
+
+        logger.debug(f"Querying example records with filter: {filter_query}")
+
+        examples = []
+        try:
+            async for entity in tbl_client.query_entities(filter_query):
+                from flock.components.utility.example_utility_component import ExampleRecord
+                examples.append(ExampleRecord(
+                    example_id=entity["RowKey"],
+                    agent_name=entity["agent_name"],
+                    content=entity["content"],
+                    created_at=entity["created_at"]
+                ))
+
+            logger.debug("Retrieved %d example records for agent %s", len(examples), agent_name)
+            return examples
+
+        except Exception as e:
+            # Log the error.
+            logger.error(
+                f"Unable to query example entries for agent {agent_name}. Exception: {e}"
+            )
+            return examples
+
 
 # ----------------------- Factory Function -----------------------
 

{flock_core-0.5.0b26.dist-info → flock_core-0.5.0b28.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b26
+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.0b26.dist-info → flock_core-0.5.0b28.dist-info}/RECORD

@@ -27,23 +27,25 @@ flock/cli/yaml_editor.py,sha256=K3N0bh61G1TSDAZDnurqW9e_-hO6CtSQKXQqlDhCjVo,1252
 flock/cli/assets/release_notes.md,sha256=bqnk50jxM3w5uY44Dc7MkdT8XmRREFxrVBAG9XCOSSU,4896
 flock/components/__init__.py,sha256=qDcaP0O7_b5RlUEXluqwskpKCkhM73kSMeNXReze63M,963
 flock/components/evaluation/__init__.py,sha256=_M3UlRFeNN90fEny6byt5VdLDE5o5khbd0EPT0o9S9k,303
-flock/components/evaluation/declarative_evaluation_component.py,sha256=SiW6NddBsNNLte3sPiqkLe-sPCH1ACCyximhZoUsvpY,20706
+flock/components/evaluation/declarative_evaluation_component.py,sha256=tEMs5mENuQL84ZXJlQObvSygqajaJcu0LLOEKAdaYoE,23195
 flock/components/routing/__init__.py,sha256=BH_pFm9T6bUuf8HH4byDJ0dO0fzEVHv9m-ghUdDVdm0,542
 flock/components/routing/conditional_routing_component.py,sha256=WqZLMz-0Dhfb97xvttNrJCIVe6FNMLEQ2m4KQTDpIbI,21374
 flock/components/routing/default_routing_component.py,sha256=ZHt2Kjf-GHB5n7evU5NSGeQJ1Wuims5soeMswqaUb1E,3370
 flock/components/routing/llm_routing_component.py,sha256=SAaOFjlnhnenM6QEBn3WIpjjNXO-tFpP44TS73zvqzQ,7502
-flock/components/utility/__init__.py,sha256=JRj932upddjzZMWs1avOupEFr_GZNu21ac66Rhw_XgY,532
+flock/components/utility/__init__.py,sha256=FRgYC06ko6mlNiGDCpYCez_61LQ4s7YJKI2Rys8Ba6w,861
+flock/components/utility/example_utility_component.py,sha256=PUbObpFaBG8dtM3llZemjT9RS_R_wsolZ2bqqrHB6-8,9206
+flock/components/utility/feedback_utility_component.py,sha256=XsE-em-KGvrkwQeDvNrzliSlvIGb9EoikKSn7kgiK4c,8144
 flock/components/utility/memory_utility_component.py,sha256=26Io61bbCGjD8UQ4BltMA5RLkMXp8tQoQmddXbQSrzA,20183
 flock/components/utility/metrics_utility_component.py,sha256=Mck_sFCkfXvNpoSgW2N_WOLnjxazzx8jh79tIx5zJhw,24635
 flock/components/utility/output_utility_component.py,sha256=TdHhY5qJJDUk-_LK54zAFMSG_Zafe-UiEkwiJwPjfh0,8063
 flock/core/__init__.py,sha256=OkjsVjRkAB-I6ibeTKVikZ3MxLIcTIzWKphHTbzbr7s,3231
 flock/core/flock.py,sha256=wRycQlGeaq-Vd75mFpPe02qyWTOEyXthT873iBhA3TI,23388
 flock/core/flock_agent.py,sha256=4Vdhyk-rdsPEuN3xYBsLBBsfpklad6bNj_it9r6XIDc,12868
-flock/core/flock_factory.py,sha256=Z6GJpYXN9_DXuOqvBH9ir0SMoUw78DkWhrhkm90luAQ,20910
+flock/core/flock_factory.py,sha256=1EI4lj9SDlNAR1RSg1-39zevDjXe9RRn37CsQbk2MoA,24145
 flock/core/flock_scheduler.py,sha256=ng_s7gyijmc-AmYvBn5rtg61CSUZiIkXPRSlA1xO6VQ,8766
 flock/core/flock_server_manager.py,sha256=tM_nOs37vAbEvxmhwy_DL2JPvgFViWroNxrRSu5MfUQ,4523
 flock/core/agent/__init__.py,sha256=l32KFMJnC_gidMXpAXK8-OX228bWOhNc8OY_NzXm59Q,515
-flock/core/agent/default_agent.py,sha256=924SWDx8axJ57JCWREZuLzV8039Wt_-5WIBNTvx479Y,7483
+flock/core/agent/default_agent.py,sha256=Y_Kd-ziScW3o1M_q9z2NfAIaHtMuvYQjwF-Hn7ySbpY,9126
 flock/core/agent/flock_agent_components.py,sha256=LamOgpRC7wDKuU3d6enDG0UFlNxyKPErLpH7SQ_Pi74,4539
 flock/core/agent/flock_agent_execution.py,sha256=pdOddBGv8y1P89Ix8XFWa1eW9i3bWjOYiQQxeY2K0yo,4217
 flock/core/agent/flock_agent_integration.py,sha256=fnxzEA8-gIopHwD1de8QKt2A7Ilb1iH5Koxk1uiASas,10737
@@ -80,7 +82,7 @@ flock/core/logging/telemetry.py,sha256=2T_o5qjvWWGMEP3UmlF9pbiTr4HDUcojHNrAbsad0
 flock/core/logging/trace_and_logged.py,sha256=5vNrK1kxuPMoPJ0-QjQg-EDJL1oiEzvU6UNi6X8FiMs,2117
 flock/core/logging/formatters/enum_builder.py,sha256=LgEYXUv84wK5vwHflZ5h8HBGgvLH3sByvUQe8tZiyY0,981
 flock/core/logging/formatters/theme_builder.py,sha256=Wnaal3HuUDA4HFg9tdql1BxYwK83ACOZBBQy-DXnxcA,17342
-flock/core/logging/formatters/themed_formatter.py,sha256=f9BiIBUk3cLma6eAPbW8BnvUqTzPzcPhjLNQoia7pI4,20656
+flock/core/logging/formatters/themed_formatter.py,sha256=7SjkayQINY7ttxcqMWeZ0mxrqXWq6tgUgeEPKeLgddk,20888
 flock/core/logging/formatters/themes.py,sha256=80BRJJB0LZr11N0yQw2f8vdb_9179qjQO8PoeBaLMN0,10680
 flock/core/logging/span_middleware/baggage_span_processor.py,sha256=gJfRl8FeB6jdtghTaRHCrOaTo4fhPMRKgjqtZj-8T48,1118
 flock/core/logging/telemetry_exporter/base_exporter.py,sha256=rQJJzS6q9n2aojoSqwCnl7ZtHrh5LZZ-gkxUuI5WfrQ,1124
@@ -497,7 +499,7 @@ flock/webapp/app/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJW
 flock/webapp/app/services/feedback_file_service.py,sha256=6WYJjml8lt_ULH5vq7JSWrPQPvUSLvp91qMBt-_tg5Q,9376
 flock/webapp/app/services/flock_service.py,sha256=a2gcmx7_8uxSnu_Y3IlEl6e-JbeWO5_ejDyE5yOKVeA,14929
 flock/webapp/app/services/sharing_models.py,sha256=XeJk1akILV_1l-cIUaG8k_eYhjV3EWBCWZ2kpwbdImA,3609
-flock/webapp/app/services/sharing_store.py,sha256=Ee7D-2g44oM_PixxEuN1oqe1PmBqONHvfo3LY7SMlzY,27164
+flock/webapp/app/services/sharing_store.py,sha256=eFcNzfLrMmmjXJkvbJQt3SeKoNyVKqRR-QMXl_AVlos,33929
 flock/webapp/app/templates/theme_mapper.html,sha256=z8ZY7nmk6PiUGzD_-px7wSXcEnuBM121rMq6u-2oaCo,14249
 flock/webapp/static/css/chat.css,sha256=Njc9gXfQzbXMrqtFJH2Yda-IQlwNPd2z4apXxzfA0sY,8169
 flock/webapp/static/css/components.css,sha256=WnicEHy3ptPzggKmyG9_oZp3X30EMJBUW3KEXaiUCUE,6018
@@ -552,8 +554,8 @@ flock/workflow/agent_execution_activity.py,sha256=0exwmeWKYXXxdUqDf4YaUVpn0zl06S
 flock/workflow/flock_workflow.py,sha256=sKFsRIL_bDGonXSNhK1zwu6UechghC_PihJJMidI-VI,9139
 flock/workflow/temporal_config.py,sha256=3_8O7SDEjMsSMXsWJBfnb6XTp0TFaz39uyzSlMTSF_I,3988
 flock/workflow/temporal_setup.py,sha256=KR6MlWOrpMtv8NyhaIPAsfl4tjobt81OBByQvg8Kw-Y,1948
-flock_core-0.5.0b26.dist-info/METADATA,sha256=zJZHhoco6VnScWx6VOAZoCGsIOkMqEkqX2p_Y_RooxQ,9997
-flock_core-0.5.0b26.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-flock_core-0.5.0b26.dist-info/entry_points.txt,sha256=rWaS5KSpkTmWySURGFZk6PhbJ87TmvcFQDi2uzjlagQ,37
-flock_core-0.5.0b26.dist-info/licenses/LICENSE,sha256=iYEqWy0wjULzM9GAERaybP4LBiPeu7Z1NEliLUdJKSc,1072
-flock_core-0.5.0b26.dist-info/RECORD,,
+flock_core-0.5.0b28.dist-info/METADATA,sha256=X_aEWYlTDI-nVJnkxCKu_4OKBMSS604qO5UHVeFn56U,9997
+flock_core-0.5.0b28.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+flock_core-0.5.0b28.dist-info/entry_points.txt,sha256=rWaS5KSpkTmWySURGFZk6PhbJ87TmvcFQDi2uzjlagQ,37
+flock_core-0.5.0b28.dist-info/licenses/LICENSE,sha256=iYEqWy0wjULzM9GAERaybP4LBiPeu7Z1NEliLUdJKSc,1072
+flock_core-0.5.0b28.dist-info/RECORD,,