flock-core 0.2.17__py3-none-any.whl → 0.3.1__py3-none-any.whl

flock/__init__.py

@@ -1,6 +1,7 @@
 """Flock package initialization."""
 
-from flock.cli.constants import CLI_THEME_BUILDER
+from flock.cli.constants import CLI_EXIT, CLI_NOTES, CLI_THEME_BUILDER
+from flock.cli.load_release_notes import load_release_notes
 from flock.core.logging.formatters.theme_builder import theme_builder
 
 
@@ -20,37 +21,46 @@ def main():
         CLI_START_WEB_SERVER,
     )
     from flock.cli.load_flock import load_flock
-    from flock.core.util.cli_helper import display_banner
+    from flock.core.util.cli_helper import init_console
 
     console = Console()
+    while True:
+        init_console()
 
-    display_banner()
-
-    console.print("Flock Management Console\n", style="bold green")
-
-    result = questionary.select(
-        "What do you want to do?",
-        choices=[
-            questionary.Separator(line=" "),
-            # CLI_CREATE_AGENT,
-            # CLI_CREATE_FLOCK,
-            # CLI_LOAD_AGENT,
-            CLI_LOAD_FLOCK,
-            # CLI_LOAD_EXAMPLE,
-            questionary.Separator(),
-            CLI_THEME_BUILDER,
-            CLI_SETTINGS,
-            questionary.Separator(),
-            CLI_START_ADVANCED_MODE,
-            CLI_START_WEB_SERVER,
-            "Exit",
-        ],
-    ).ask()
-
-    if result == CLI_LOAD_FLOCK:
-        load_flock()
-    if result == CLI_THEME_BUILDER:
-        theme_builder()
+        console.print("Flock Management Console\n", style="bold green")
+
+        result = questionary.select(
+            "What do you want to do?",
+            choices=[
+                questionary.Separator(line=" "),
+                # CLI_CREATE_AGENT,
+                # CLI_CREATE_FLOCK,
+                # CLI_LOAD_AGENT,
+                CLI_LOAD_FLOCK,
+                # CLI_LOAD_EXAMPLE,
+                questionary.Separator(),
+                CLI_THEME_BUILDER,
+                CLI_SETTINGS,
+                questionary.Separator(),
+                CLI_START_ADVANCED_MODE,
+                CLI_START_WEB_SERVER,
+                questionary.Separator(),
+                CLI_NOTES,
+                CLI_EXIT,
+            ],
+        ).ask()
+
+        if result == CLI_LOAD_FLOCK:
+            load_flock()
+        if result == CLI_THEME_BUILDER:
+            theme_builder()
+        if result == CLI_NOTES:
+            load_release_notes()
+        if result == CLI_EXIT:
+            break
+        input("\nPress Enter to continue...\n\n")
+
+        console.clear()
 
 
 if __name__ == "__main__":

flock/cli/assets/release_notes.md

@@ -0,0 +1,111 @@
+
+# Flock v0.3 - Hummingbird  
+
+We're excited to announce Flock v0.3, codenamed **"Hummingbird"**! This release brings a fundamental redesign of Flock's core architecture, introducing **unprecedented modularity and flexibility** to AI agent development.  
+
+Modules and evaluators were the last missing pieces to fully modularize Flock.  
+
+Worried this might lead to hard-to-manage boilerplate? No problem! **FlockFactory** provides pre-configured agents, making interaction with modules and evaluators **purely optional**, so you can focus on **what** the agent does, not **how** it works.  
+
+But if you want **total control** over your agent, feel free to dive into these new additions. They unlock **crazy new possibilities** in Flock!  
+
+Like a hummingbird, modules are small and nimble code packages. Put enough of them inside a flock, and... well, even we don't know what happens next.  
+
+### Other notable additions:  
+- **CLI Interface** – Flock now has a command-line interface  
+- **Color-coded logging** – Better debugging experience  
+- **New examples**  
+- ...and much more!  
+
+---
+
+## Core Changes  
+
+### New Module System  
+- **Complete redesign** of the module architecture  
+- Simple yet powerful lifecycle hooks: `initialize`, `pre_evaluate`, `post_evaluate`, `terminate`  
+- **Easy-to-implement** module interface  
+- **Configuration system** for clean parameter management  
+
+### New Evaluator System  
+- **Pluggable evaluation system**  
+- Built-in support for multiple evaluation strategies:  
+  - **Declarative Evaluator** – The default way Flock is designed  
+  - **Natural Language Evaluator** – Use "classic" prompting  
+- **Easily extendable** with custom evaluation approaches  
+
+### FlockFactory  
+- Provides **pre-configured agents**, so you don't have to manage modules and evaluators manually!  
+
+### Built-in Modules  
+- **Memory Module** – Persistent agent memory  
+- **Output Module** – Advanced output formatting and storage  
+- **Metrics Module** – Detailed performance tracking  
+
+---
+
+## Breaking Changes  
+- **Removed callback handlers** from `FlockAgent` in favor of modules  
+- **Changed agent initialization** pattern to support evaluators  
+- **Simplified module lifecycle hooks** (removed redundant pre/post hooks)  
+
+---
+
+## Small Changes & Fixes 
+
+### Theme Designer
+
+### Color Coded Logging
+
+---
+
+## Code Rundown  
+
+### Old way:  
+```python
+agent = FlockAgent(
+    name="bloggy",
+    input="blog_idea",
+    output="funny_blog_title, blog_headers",
+)
+flock.add_agent(bloggy)
+```  
+
+### New way:  
+```python
+bloggy = FlockFactory.create_default_agent(
+    name="bloggy",
+    input="blog_idea",
+    output="funny_blog_title, blog_headers",
+)
+flock.add_agent(bloggy)
+```  
+
+See? **Basically nothing changed!** Just more modular and flexible.  
+
+---
+
+## What's Next?  
+
+### Coming in v0.3 updates:  
+- **More modules** (built-in RAG coming soon!)  
+- **More evaluators**  
+- **CLI management tool improvements**  
+- **Finishing documentation**
+
+### Looking ahead to v0.4 – *Magpie*:  
+- **Flock WebUI** – Real-time monitoring, no-code agent creation & management  
+- **Seamless deployment** – Kubernetes, Docker, and enterprise-ready solutions  
+
+---
+
+## 🛠 Installation  
+
+```bash
+pip install flock-core>=0.3.0
+```  
+
+---  
+
+**Full documentation**: [docs.flock.ai](https://docs.flock.ai)  
+**GitHub**: [github.com/flock-ai](https://github.com/flock-ai)  

flock/cli/constants.py

@@ -7,6 +7,7 @@ CLI_LOAD_FLOCK = "Load a *.flock file"
 CLI_THEME_BUILDER = "Theme builder"
 CLI_LOAD_EXAMPLE = "Load a example"
 CLI_SETTINGS = "Settings"
+CLI_NOTES = "'Hummingbird' release notes"
 CLI_START_ADVANCED_MODE = "Start advanced mode (coming soon)"
 CLI_START_WEB_SERVER = "Start web server (coming soon)"
 CLI_EXIT = "Exit"

flock/cli/load_release_notes.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+from flock.core.util.cli_helper import display_hummingbird
+
+
+def load_release_notes():
+    """Load release notes."""
+    from rich.console import Console
+    from rich.markdown import Markdown
+
+    from flock.core.util.cli_helper import init_console
+
+    console = Console()
+    file_path = Path(__file__).parent / "assets" / "release_notes.md"
+
+    init_console()
+    console.print(Markdown("# *'Hummingbird'* Release Notes"))
+    display_hummingbird()
+    with open(file_path) as file:
+        release_notes = file.read()
+
+    
+    console.print(Markdown(release_notes))

flock/core/__init__.py

@@ -2,5 +2,16 @@
 
 from flock.core.flock import Flock
 from flock.core.flock_agent import FlockAgent
+from flock.core.flock_evaluator import FlockEvaluator, FlockEvaluatorConfig
+from flock.core.flock_factory import FlockFactory
+from flock.core.flock_module import FlockModule, FlockModuleConfig
 
-__all__ = ["Flock", "FlockAgent"]
+__all__ = [
+    "Flock",
+    "FlockAgent",
+    "FlockEvaluator",
+    "FlockEvaluatorConfig",
+    "FlockFactory",
+    "FlockModule",
+    "FlockModuleConfig",
+]

flock/core/context/context.py

@@ -1,3 +1,4 @@
+import uuid
 from dataclasses import asdict, dataclass, field
 from datetime import datetime
 from typing import Any, Literal
@@ -14,6 +15,7 @@ tracer = trace.get_tracer(__name__)
 
 @dataclass
 class AgentRunRecord:
+    id: str = field(default="")
     agent: str = field(default="")
     data: dict[str, Any] = field(default_factory=dict)
     timestamp: str = field(default="")
@@ -49,6 +51,7 @@ class FlockContext(Serializable):
         called_from: str,
     ) -> None:
         record = AgentRunRecord(
+            id=agent_name + "_" + uuid.uuid4().hex[:4],
             agent=agent_name,
             data=data.copy(),
             timestamp=timestamp,
@@ -61,7 +64,7 @@ class FlockContext(Serializable):
         self.set_variable(FLOCK_LAST_RESULT, data)
         self.set_variable(FLOCK_LAST_AGENT, agent_name)
         logger.info(
-            "Agent run recorded",
+            f"Agent run recorded - run_id '{record.id}'",
             agent=agent_name,
             timestamp=timestamp,
             data=data,
@@ -80,12 +83,14 @@ class FlockContext(Serializable):
         old_value = self.state.get(key)
         self.state[key] = value
         if old_value != value:
+            escaped_value = str(value).replace("{", "{{").replace("}", "}}")
+
             logger.info(
-                "Context variable updated",
-                variable=key,
-                old=old_value,
-                new=value,
+                "Context variable updated - {} -> {}",
+                key,
+                escaped_value,  # Arguments in order
             )
+
             current_span = trace.get_current_span()
             if current_span.get_span_context().is_valid:
                 current_span.add_event(

flock/core/flock.py

@@ -16,9 +16,9 @@ from flock.core.context.context_manager import initialize_context
 from flock.core.execution.local_executor import run_local_workflow
 from flock.core.execution.temporal_executor import run_temporal_workflow
 from flock.core.flock_agent import FlockAgent
-from flock.core.logging.logging import get_logger
+from flock.core.logging.logging import LOGGERS, get_logger, get_module_loggers
 from flock.core.registry.agent_registry import Registry
-from flock.core.util.cli_helper import display_banner
+from flock.core.util.cli_helper import init_console
 from flock.core.util.input_resolver import top_level_to_keys
 
 T = TypeVar("T", bound=FlockAgent)
@@ -27,6 +27,43 @@ TELEMETRY.setup_tracing()
 tracer = trace.get_tracer(__name__)
 
 
+def init_loggers(enable_logging: bool | list[str] = False):
+    """Initialize the loggers for the Flock system.
+
+    Args:
+        enable_logging (bool): If True, enable verbose logging. Defaults to False.
+    """
+    if isinstance(enable_logging, list):
+        for logger in LOGGERS:
+            if logger in enable_logging:
+                other_loggers = get_logger(logger)
+                other_loggers.enable_logging = True
+            else:
+                other_loggers = get_logger(logger)
+                other_loggers.enable_logging = False
+    else:
+        logger = get_logger("flock")
+        logger.enable_logging = enable_logging
+        other_loggers = get_logger("interpreter")
+        other_loggers.enable_logging = enable_logging
+        other_loggers = get_logger("memory")
+        other_loggers.enable_logging = enable_logging
+        other_loggers = get_logger("activities")
+        other_loggers.enable_logging = enable_logging
+        other_loggers = get_logger("context")
+        other_loggers.enable_logging = enable_logging
+        other_loggers = get_logger("registry")
+        other_loggers.enable_logging = enable_logging
+        other_loggers = get_logger("tools")
+        other_loggers.enable_logging = enable_logging
+        other_loggers = get_logger("agent")
+        other_loggers.enable_logging = enable_logging
+
+        module_loggers = get_module_loggers()
+        for module_logger in module_loggers:
+            module_logger.enable_logging = enable_logging
+
+
 class Flock:
     """High-level orchestrator for creating and executing agents.
 
@@ -37,9 +74,8 @@ class Flock:
     def __init__(
         self,
         model: str = "openai/gpt-4o",
-        local_debug: bool = False,
-        enable_logging: bool = False,
-        show_cli_banner: bool = True,
+        enable_temporal: bool = False,
+        enable_logging: bool | list[str] = False,
     ):
         """Initialize the Flock orchestrator.
 
@@ -51,32 +87,32 @@ class Flock:
         """
         with tracer.start_as_current_span("flock_init") as span:
             span.set_attribute("model", model)
-            span.set_attribute("local_debug", local_debug)
+            span.set_attribute("enable_temporal", enable_temporal)
             span.set_attribute("enable_logging", enable_logging)
+
+            init_loggers(enable_logging)
             logger.info(
                 "Initializing Flock",
                 model=model,
-                local_debug=local_debug,
+                enable_temporal=enable_temporal,
                 enable_logging=enable_logging,
             )
-            logger.enable_logging = enable_logging
             session_id = get_baggage("session_id")
             if not session_id:
                 session_id = str(uuid.uuid4())
                 set_baggage("session_id", session_id)
 
-            if show_cli_banner:
-                display_banner()
+            init_console()
 
             self.agents: dict[str, FlockAgent] = {}
             self.registry = Registry()
             self.context = FlockContext()
             self.model = model
-            self.local_debug = local_debug
+            self.enable_temporal = enable_temporal
             self.start_agent: FlockAgent | str | None = None
             self.input: dict = {}
 
-            if local_debug:
+            if not enable_temporal:
                 os.environ["LOCAL_DEBUG"] = "1"
                 logger.debug("Set LOCAL_DEBUG environment variable")
             elif "LOCAL_DEBUG" in os.environ:
@@ -110,7 +146,7 @@ class Flock:
                     f"Agent {agent.name} already exists, returning existing instance"
                 )
                 return self.agents[agent.name]
-            logger.info("Adding new agent")
+            logger.info(f"Adding new agent '{agent.name}'")
 
             self.agents[agent.name] = agent
             self.registry.register_agent(agent)
@@ -121,8 +157,11 @@ class Flock:
             if hasattr(agent, "tools") and agent.tools:
                 for tool in agent.tools:
                     self.registry.register_tool(tool.__name__, tool)
-                    logger.debug("Registered tool", tool_name=tool.__name__)
-            logger.success("Agent added successfully")
+                    logger.debug(
+                        f"Registered tool '{tool.__name__}'",
+                        tool_name=tool.__name__,
+                    )
+            logger.success(f"'{agent.name}' added successfully")
             return agent
 
     def add_tool(self, tool_name: str, tool: callable):
@@ -362,7 +401,8 @@ class Flock:
             try:
                 if isinstance(self.start_agent, str):
                     logger.debug(
-                        "Looking up agent by name", agent_name=self.start_agent
+                        f"Looking up agent '{self.start_agent.name}' in registry",
+                        agent_name=self.start_agent,
                     )
                     self.start_agent = self.registry.get_agent(self.start_agent)
                     if not self.start_agent:
@@ -377,8 +417,8 @@ class Flock:
                     logger.debug("Using provided context")
                     self.context = context
                 if not run_id:
-                    run_id = f"{self.start_agent.name}_{uuid.uuid4().hex[:4]}"
-                    logger.debug("Generated run ID", run_id=run_id)
+                    run_id = f"flock_{uuid.uuid4().hex[:4]}"
+                    logger.debug(f"Generated run ID '{run_id}'", run_id=run_id)
 
                 set_baggage("run_id", run_id)
 
@@ -400,16 +440,16 @@ class Flock:
                     self.start_agent.name,
                     self.input,
                     run_id,
-                    self.local_debug,
+                    not self.enable_temporal,
                 )
 
                 logger.info(
                     "Starting agent execution",
                     agent=self.start_agent.name,
-                    local_debug=self.local_debug,
+                    enable_temporal=self.enable_temporal,
                 )
 
-                if self.local_debug:
+                if not self.enable_temporal:
                     return await run_local_workflow(self.context, box_result)
                 else:
                     return await run_temporal_workflow(self.context, box_result)