flock-core 0.4.0b19__tar.gz → 0.4.0b20__tar.gz

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/.gitignore

@@ -38,8 +38,7 @@ news/
 .chroma/
 hierarchical_memory/
 .repomix-output.txt
-output/
-!src/flock/modules/output/output_module.py
+
 .env.*
 .flock/
 

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.4.0b19
+Version: 0.4.0b20
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -58,8 +58,6 @@ Requires-Dist: markdownify>=0.14.1; extra == 'tools'
 Requires-Dist: tavily-python>=0.5.0; extra == 'tools'
 Description-Content-Type: text/markdown
 
-# 🚀 Flock: The Declarative AI Agent Framework 🚀
-
 <p align="center">
   <!-- Placeholder for your Flock Logo/Banner - Replace URL -->
   <img alt="Flock Banner" src="https://raw.githubusercontent.com/whiteducksoftware/flock/master/docs/assets/images/flock.png" width="600">
@@ -95,20 +93,25 @@ Built with real-world deployment in mind, Flock integrates seamlessly with tools
 
 Flock offers a different way to build agentic systems:
 
-| Traditional Agent Frameworks 😟        | Flock Framework 🐤🐧🐓🦆             |
-| :------------------------------------- | :------------------------------------ |
-| 🤯 **Prompt Nightmare**                | ✅ **Declarative Simplicity**         |
-| *Long, brittle, hard-to-tune prompts*  | *Clear input/output specs (typed!)*   |
-| 💥 **Fragile & Unpredictable**         | ⚡ **Robust & Production-Ready**     |
-| *Single errors can halt everything*    | *Fault-tolerant via Temporal option*  |
-| 🧩 **Monolithic & Rigid**             | 🔧 **Modular & Flexible**             |
-| *Hard to extend or modify logic*       | *Pluggable Evaluators, Modules, Tools*|
-| ⛓️ **Basic Chaining**                 | 🚀 **Advanced Orchestration**         |
-| *Often just linear workflows*          | *Dynamic Routing, Batch Processing*   |
-| 🧪 **Difficult Testing**               | ✅ **Testable Components**            |
-| *Hard to unit test prompt logic*       | *Clear I/O contracts aid testing*     |
-| 📄 **Unstructured Output**             | ✨ **Structured Data Handling**       |
-| *Parsing unreliable LLM text output*   | *Native Pydantic/Typed Dict support*  |
+| Traditional Agent Frameworks 😟        | Flock Framework 🐤🐧🐓🦆                   |
+| :------------------------------------ | :------------------------------------- |
+| 🤯 **Prompt Nightmare**                | ✅ **Declarative Simplicity**           |
+| *Long, brittle, hard-to-tune prompts* | *Clear input/output specs (typed!)*    |
+| 💥 **Fragile & Unpredictable**         | ⚡ **Robust & Production-Ready**        |
+| *Single errors can halt everything*   | *Fault-tolerant via Temporal option*   |
+| 🧩 **Monolithic & Rigid**              | 🔧 **Modular & Flexible**               |
+| *Hard to extend or modify logic*      | *Pluggable Evaluators, Modules, Tools* |
+| ⛓️ **Basic Chaining**                  | 🚀 **Advanced Orchestration**           |
+| *Often just linear workflows*         | *Dynamic Routing, Batch Processing*    |
+| 🧪 **Difficult Testing**               | ✅ **Testable Components**              |
+| *Hard to unit test prompt logic*      | *Clear I/O contracts aid testing*      |
+| 📄 **Unstructured Output**             | ✨ **Structured Data Handling**         |
+| *Parsing unreliable LLM text output*  | *Native Pydantic/Typed Dict support*   |
+
+
+## 📹 Video Demo
+
+https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
 
 ## 💡 Core Concepts
 
@@ -210,7 +213,17 @@ if __name__ == "__main__":
         print("Ensure your LLM API key (e.g., OPENAI_API_KEY) is set in your .env file!")
 ```
 
-## ✨ Utility: @flockclass Hydrator
+## 🐤 New in Flock 0.4.0 `Magpie` 🐤
+
+### REST API - Deploy Flock Agents as REST API Endpoints
+
+### Web UI - Test Flock Agents in the Browser
+
+### CLI Tool - Manage Flock Agents via the Command Line
+
+### Serialization - Share, Deploy, and Run Flock Agents by human readable yaml files
+
+### ✨ Utility: @flockclass Hydrator
 
 Flock also provides conveniences. The @flockclass decorator allows you to easily populate Pydantic models using an LLM:
 
@@ -269,11 +282,10 @@ Ways to contribute:
 - Improve documentation.
 - Contribute new Modules, Evaluators, or Routers.
 - Add examples to the flock-showcase repository.
-- Join our Discord Community to discuss development! <!-- Add Discord link -->
 
 ## 📜 License
 
-Flock is licensed under the Apache License 2.0. See the LICENSE file for details.
+Flock is licensed under the MIT License. See the LICENSE file for details.
 
 ## 🏢 About
 

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/README.md

@@ -1,5 +1,3 @@
-# 🚀 Flock: The Declarative AI Agent Framework 🚀
-
 <p align="center">
   <!-- Placeholder for your Flock Logo/Banner - Replace URL -->
   <img alt="Flock Banner" src="https://raw.githubusercontent.com/whiteducksoftware/flock/master/docs/assets/images/flock.png" width="600">
@@ -35,20 +33,25 @@ Built with real-world deployment in mind, Flock integrates seamlessly with tools
 
 Flock offers a different way to build agentic systems:
 
-| Traditional Agent Frameworks 😟        | Flock Framework 🐤🐧🐓🦆             |
-| :------------------------------------- | :------------------------------------ |
-| 🤯 **Prompt Nightmare**                | ✅ **Declarative Simplicity**         |
-| *Long, brittle, hard-to-tune prompts*  | *Clear input/output specs (typed!)*   |
-| 💥 **Fragile & Unpredictable**         | ⚡ **Robust & Production-Ready**     |
-| *Single errors can halt everything*    | *Fault-tolerant via Temporal option*  |
-| 🧩 **Monolithic & Rigid**             | 🔧 **Modular & Flexible**             |
-| *Hard to extend or modify logic*       | *Pluggable Evaluators, Modules, Tools*|
-| ⛓️ **Basic Chaining**                 | 🚀 **Advanced Orchestration**         |
-| *Often just linear workflows*          | *Dynamic Routing, Batch Processing*   |
-| 🧪 **Difficult Testing**               | ✅ **Testable Components**            |
-| *Hard to unit test prompt logic*       | *Clear I/O contracts aid testing*     |
-| 📄 **Unstructured Output**             | ✨ **Structured Data Handling**       |
-| *Parsing unreliable LLM text output*   | *Native Pydantic/Typed Dict support*  |
+| Traditional Agent Frameworks 😟        | Flock Framework 🐤🐧🐓🦆                   |
+| :------------------------------------ | :------------------------------------- |
+| 🤯 **Prompt Nightmare**                | ✅ **Declarative Simplicity**           |
+| *Long, brittle, hard-to-tune prompts* | *Clear input/output specs (typed!)*    |
+| 💥 **Fragile & Unpredictable**         | ⚡ **Robust & Production-Ready**        |
+| *Single errors can halt everything*   | *Fault-tolerant via Temporal option*   |
+| 🧩 **Monolithic & Rigid**              | 🔧 **Modular & Flexible**               |
+| *Hard to extend or modify logic*      | *Pluggable Evaluators, Modules, Tools* |
+| ⛓️ **Basic Chaining**                  | 🚀 **Advanced Orchestration**           |
+| *Often just linear workflows*         | *Dynamic Routing, Batch Processing*    |
+| 🧪 **Difficult Testing**               | ✅ **Testable Components**              |
+| *Hard to unit test prompt logic*      | *Clear I/O contracts aid testing*      |
+| 📄 **Unstructured Output**             | ✨ **Structured Data Handling**         |
+| *Parsing unreliable LLM text output*  | *Native Pydantic/Typed Dict support*   |
+
+
+## 📹 Video Demo
+
+https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
 
 ## 💡 Core Concepts
 
@@ -150,7 +153,17 @@ if __name__ == "__main__":
         print("Ensure your LLM API key (e.g., OPENAI_API_KEY) is set in your .env file!")
 ```
 
-## ✨ Utility: @flockclass Hydrator
+## 🐤 New in Flock 0.4.0 `Magpie` 🐤
+
+### REST API - Deploy Flock Agents as REST API Endpoints
+
+### Web UI - Test Flock Agents in the Browser
+
+### CLI Tool - Manage Flock Agents via the Command Line
+
+### Serialization - Share, Deploy, and Run Flock Agents by human readable yaml files
+
+### ✨ Utility: @flockclass Hydrator
 
 Flock also provides conveniences. The @flockclass decorator allows you to easily populate Pydantic models using an LLM:
 
@@ -209,11 +222,10 @@ Ways to contribute:
 - Improve documentation.
 - Contribute new Modules, Evaluators, or Routers.
 - Add examples to the flock-showcase repository.
-- Join our Discord Community to discuss development! <!-- Add Discord link -->
 
 ## 📜 License
 
-Flock is licensed under the Apache License 2.0. See the LICENSE file for details.
+Flock is licensed under the MIT License. See the LICENSE file for details.
 
 ## 🏢 About
 

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.4.0b-19"
+version = "0.4.0b-20"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [

flock_core-0.4.0b20/src/flock/cli/utils.py

@@ -0,0 +1,135 @@
+# src/pilot_rules/collector/utils.py
+import datetime
+from pathlib import Path
+from typing import Any
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn
+from rich.table import Table
+
+# Create a shared console instance for consistent styling
+console = Console()
+
+
+def get_file_metadata(file_path: str) -> dict[str, Any]:
+    """Extract metadata from a file."""
+    metadata = {
+        "path": file_path,
+        "size_bytes": 0,
+        "line_count": 0,
+        "last_modified": "Unknown",
+        "created": "Unknown",
+    }
+
+    try:
+        p = Path(file_path)
+        stats = p.stat()
+        metadata["size_bytes"] = stats.st_size
+        metadata["last_modified"] = datetime.datetime.fromtimestamp(
+            stats.st_mtime
+        ).strftime("%Y-%m-%d %H:%M:%S")
+        # ctime is platform dependent (creation on Windows, metadata change on Unix)
+        # Use mtime as a reliable fallback for "created" if ctime is older than mtime
+        ctime = stats.st_ctime
+        mtime = stats.st_mtime
+        best_ctime = ctime if ctime <= mtime else mtime  # Heuristic
+        metadata["created"] = datetime.datetime.fromtimestamp(
+            best_ctime
+        ).strftime("%Y-%m-%d %H:%M:%S")
+
+        try:
+            # Attempt to read as text, fallback for binary or encoding issues
+            with p.open("r", encoding="utf-8", errors="ignore") as f:
+                content = f.read()
+                metadata["line_count"] = len(content.splitlines())
+        except (OSError, UnicodeDecodeError) as read_err:
+            # Handle cases where reading might fail (binary file, permissions etc.)
+            console.print(
+                f"[yellow]⚠ Warning:[/yellow] Could not read content/count lines for [cyan]{file_path}[/cyan]: [red]{read_err}[/red]"
+            )
+            metadata["line_count"] = 0  # Indicate unreadable or binary
+
+    except Exception as e:
+        console.print(
+            f"[yellow]⚠ Warning:[/yellow] Could not get complete metadata for [cyan]{file_path}[/cyan]: [red]{e}[/red]"
+        )
+
+    return metadata
+
+
+# --- Rich Formatting Utilities ---
+
+
+def print_header(title: str, style: str = "blue") -> None:
+    """Print a styled header with a panel."""
+    console.rule()
+    console.print(
+        Panel.fit(f"[bold {style}]{title}[/bold {style}]", border_style=style)
+    )
+
+
+def print_subheader(title: str, style: str = "cyan") -> None:
+    """Print a styled subheader."""
+    console.print(f"[bold {style}]== {title} ==[/bold {style}]")
+
+
+def print_success(message: str) -> None:
+    """Print a success message."""
+    console.print(f"[bold green]✓[/bold green] {message}")
+
+
+def print_error(message: str, exit_code: int | None = None) -> None:
+    """Print an error message and optionally exit."""
+    console.print(f"[bold red]✗ ERROR:[/bold red] {message}")
+    if exit_code is not None:
+        exit(exit_code)
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message."""
+    console.print(f"[yellow]⚠ Warning:[/yellow] {message}")
+
+
+def create_progress() -> Progress:
+    """Create a standardized progress bar."""
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[bold blue]{task.description}"),
+        BarColumn(complete_style="green", finished_style="green"),
+        TextColumn("[bold]{task.completed}/{task.total}"),
+        console=console,
+    )
+
+
+def create_task_table(title: str) -> Table:
+    """Create a standardized table for displaying task information."""
+    table = Table(
+        title=title, show_header=True, header_style="bold cyan", box=box.ROUNDED
+    )
+    return table
+
+
+def print_file_stats(files: list[str], title: str = "File Statistics") -> None:
+    """Print statistics about a list of files."""
+    if not files:
+        console.print("[yellow]No files found to display statistics.[/yellow]")
+        return
+
+    table = Table(title=title, show_header=True, header_style="bold magenta")
+    table.add_column("Statistic", style="cyan")
+    table.add_column("Value", style="green")
+
+    extensions = {Path(f).suffix.lower() for f in files if Path(f).suffix}
+    total_size = sum(get_file_metadata(f).get("size_bytes", 0) for f in files)
+    total_lines = sum(get_file_metadata(f).get("line_count", 0) for f in files)
+
+    table.add_row("Total Files", str(len(files)))
+    table.add_row("Total Size", f"{total_size / 1024:.2f} KB")
+    table.add_row("Total Lines", str(total_lines))
+    table.add_row(
+        "Extensions", ", ".join(sorted(extensions)) if extensions else "None"
+    )
+
+    console.print(table)

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/src/flock/core/flock.py

@@ -150,8 +150,7 @@ class Flock(BaseModel, Serializable):
                     )
 
         # Initialize console if needed for banner
-        if self.show_flock_banner:  # Use instance attribute
-            init_console()
+        init_console(clear_screen=True, show_banner=self.show_flock_banner)
 
         # Set Temporal debug environment variable
         self._set_temporal_debug_flag()
@@ -225,7 +224,7 @@ class Flock(BaseModel, Serializable):
             raise ValueError("Agent must have a name.")
 
         if agent.name in self._agents:
-            logger.warning(f"Agent '{agent.name}' already exists. Overwriting.")
+            raise ValueError("Agent with this name already exists.")
         self._agents[agent.name] = agent
         FlockRegistry.register_agent(agent)  # Register globally
 

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/src/flock/core/flock_factory.py

@@ -38,6 +38,7 @@ class FlockFactory:
         print_context: bool = False,
         write_to_file: bool = False,
         stream: bool = False,
+        include_thought_process: bool = False,
     ) -> FlockAgent:
         """Creates a default FlockAgent.
 
@@ -52,6 +53,7 @@ class FlockFactory:
             max_tokens=max_tokens,
             temperature=temperature,
             stream=stream,
+            include_thought_process=include_thought_process,
         )
 
         evaluator = DeclarativeEvaluator(name="default", config=eval_config)

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/src/flock/core/mixin/dspy_integration.py

@@ -336,8 +336,9 @@ class DSPyIntegrationMixin:
     def _select_task(
         self,
         signature: Any,
-        agent_type_override: AgentType,
+        override_evaluator_type: AgentType,
         tools: list[Any] | None = None,
+        kwargs: dict[str, Any] = {},
     ) -> Any:
         """Select and instantiate the appropriate DSPy Program/Module."""
         try:
@@ -360,7 +361,7 @@ class DSPyIntegrationMixin:
                     )
 
         dspy_program = None
-        selected_type = agent_type_override
+        selected_type = override_evaluator_type
 
         # Determine type if not overridden
         if not selected_type:
@@ -374,11 +375,12 @@ class DSPyIntegrationMixin:
 
         try:
             if selected_type == "ChainOfThought":
-                dspy_program = dspy.ChainOfThought(signature)
+                dspy_program = dspy.ChainOfThought(signature, **kwargs)
             elif selected_type == "ReAct":
-                # ReAct requires tools, even if empty list
+                if not kwargs:
+                    kwargs = {"max_iters": 10}
                 dspy_program = dspy.ReAct(
-                    signature, tools=processed_tools or [], max_iters=10
+                    signature, tools=processed_tools or [], **kwargs
                 )
             elif selected_type == "Predict":  # Default or explicitly Completion
                 dspy_program = dspy.Predict(signature)
@@ -401,8 +403,10 @@ class DSPyIntegrationMixin:
 
     def _process_result(
         self, result: Any, inputs: dict[str, Any]
-    ) -> dict[str, Any]:
+    ) -> tuple[dict[str, Any], float, list]:
         """Convert the DSPy result object to a dictionary."""
+        import dspy
+
         if result is None:
             logger.warning("DSPy program returned None result.")
             return {}
@@ -429,7 +433,12 @@ class DSPyIntegrationMixin:
             logger.debug(f"Processed DSPy result to dict: {output_dict}")
             # Optionally merge inputs back if desired (can make result dict large)
             final_result = {**inputs, **output_dict}
-            return final_result
+
+            lm = dspy.settings.get("lm")
+            cost = sum([x["cost"] for x in lm.history if x["cost"] is not None])
+            lm_history = lm.inspect_history()
+
+            return final_result, cost, lm_history
 
         except Exception as conv_error:
             logger.error(

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/src/flock/core/util/cli_helper.py

@@ -43,7 +43,7 @@ def display_hummingbird():
 """)
 
 
-def init_console(clear_screen: bool = True):
+def init_console(clear_screen: bool = True, show_banner: bool = True):
     """Display the Flock banner."""
     banner_text = Text(
         f"""
@@ -60,7 +60,9 @@ def init_console(clear_screen: bool = True):
     )
     if clear_screen:
         console.clear()
-    console.print(banner_text)
+
+    if show_banner:
+        console.print(banner_text)
     console.print(
         f"[italic]'Magpie'[/] milestone - [bold]white duck GmbH[/] - [cyan]https://whiteduck.de[/]\n"
     )

{flock_core-0.4.0b19 → flock_core-0.4.0b20}/src/flock/evaluators/declarative/declarative_evaluator.py

@@ -19,7 +19,7 @@ logger = get_logger("evaluators.declarative")
 class DeclarativeEvaluatorConfig(FlockEvaluatorConfig):
     """Configuration for the DeclarativeEvaluator."""
 
-    agent_type_override: str | None = None
+    override_evaluator_type: str | None = None
     model: str | None = "openai/gpt-4o"
     use_cache: bool = True
     temperature: float = 0.0
@@ -28,6 +28,11 @@ class DeclarativeEvaluatorConfig(FlockEvaluatorConfig):
         default=False,
         description="Enable streaming output from the underlying DSPy program.",
     )
+    include_thought_process: bool = Field(
+        default=False,
+        description="Include the thought process in the output.",
+    )
+    kwargs: dict[str, Any] = Field(default_factory=dict)
 
 
 class DeclarativeEvaluator(
@@ -40,6 +45,9 @@ class DeclarativeEvaluator(
         description="Evaluator configuration",
     )
 
+    cost: float = 0.0
+    lm_history: list = Field(default_factory=list)
+
     async def evaluate(
         self, agent: FlockAgent, inputs: dict[str, Any], tools: list[Any]
     ) -> dict[str, Any]:
@@ -68,8 +76,9 @@ class DeclarativeEvaluator(
             )
             agent_task = self._select_task(
                 _dspy_signature,
-                agent_type_override=self.config.agent_type_override,
+                override_evaluator_type=self.config.override_evaluator_type,
                 tools=tools,
+                kwargs=self.config.kwargs,
             )
         except Exception as setup_error:
             logger.error(
@@ -109,21 +118,46 @@ class DeclarativeEvaluator(
                 if delta_content:
                     console.print(delta_content, end="")
 
-                result_dict = self._process_result(chunk, inputs)
+                result_dict, cost, lm_history = self._process_result(
+                    chunk, inputs
+                )
+                self.cost = cost
+                self.lm_history = lm_history
 
             console.print("\n")
-            return result_dict
+            return self.filter_thought_process(
+                result_dict, self.config.include_thought_process
+            )
 
         else:  # Non-streaming path
             logger.info(f"Evaluating agent '{agent.name}' without streaming.")
             try:
                 # Ensure the call is awaited if the underlying task is async
                 result_obj = agent_task(**inputs)
-                result_dict = self._process_result(result_obj, inputs)
-                return result_dict
+                result_dict, cost, lm_history = self._process_result(
+                    result_obj, inputs
+                )
+                self.cost = cost
+                self.lm_history = lm_history
+                return self.filter_thought_process(
+                    result_dict, self.config.include_thought_process
+                )
             except Exception as e:
                 logger.error(
                     f"Error during non-streaming evaluation for agent '{agent.name}': {e}",
                     exc_info=True,
                 )
                 raise RuntimeError(f"Evaluation failed: {e}") from e
+
+    def filter_thought_process(
+        result_dict: dict[str, Any], include_thought_process: bool
+    ) -> dict[str, Any]:
+        """Filter out thought process from the result dictionary."""
+        if include_thought_process:
+            return result_dict
+        else:
+            return {
+                k: v
+                for k, v in result_dict.items()
+                if not (k.startswith("reasoning") or k.startswith("trajectory"))
+            }