flock-core 0.2.13__py3-none-any.whl → 0.2.15__py3-none-any.whl

flock/__init__.py

@@ -1 +1,57 @@
 """Flock package initialization."""
+
+from flock.cli.constants import CLI_THEME_BUILDER
+from flock.core.logging.formatters.theme_builder import theme_builder
+
+
+def main():
+    """Main function."""
+    import questionary
+    from rich.console import Console
+
+    from flock.cli.constants import (
+        CLI_CREATE_AGENT,
+        CLI_CREATE_FLOCK,
+        CLI_LOAD_AGENT,
+        CLI_LOAD_EXAMPLE,
+        CLI_LOAD_FLOCK,
+        CLI_SETTINGS,
+        CLI_START_ADVANCED_MODE,
+        CLI_START_WEB_SERVER,
+    )
+    from flock.cli.load_flock import load_flock
+    from flock.core.util.cli_helper import display_banner
+
+    console = 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()
+
+
+if __name__ == "__main__":
+    main()

flock/cli/constants.py

@@ -0,0 +1,23 @@
+"""Constants for the CLI module."""
+
+CLI_CREATE_AGENT = "Create an agent"
+CLI_CREATE_FLOCK = "Create a flock"
+CLI_LOAD_AGENT = "Load an agent"
+CLI_LOAD_FLOCK = "Load a *.flock file"
+CLI_THEME_BUILDER = "Theme builder"
+CLI_LOAD_EXAMPLE = "Load a example"
+CLI_SETTINGS = "Settings"
+CLI_START_ADVANCED_MODE = "Start advanced mode (coming soon)"
+CLI_START_WEB_SERVER = "Start web server (coming soon)"
+CLI_EXIT = "Exit"
+CLI_CHOICES = [
+    CLI_CREATE_AGENT,
+    CLI_CREATE_FLOCK,
+    CLI_LOAD_AGENT,
+    CLI_LOAD_FLOCK,
+    CLI_LOAD_EXAMPLE,
+    CLI_SETTINGS,
+    CLI_START_ADVANCED_MODE,
+    CLI_START_WEB_SERVER,
+    CLI_EXIT,
+]

flock/cli/create_agent.py

@@ -0,0 +1 @@
+# TODO

flock/cli/create_flock.py

@@ -0,0 +1 @@
+# TODO

flock/cli/load_agent.py

@@ -0,0 +1 @@
+# TODO

flock/cli/load_examples.py

@@ -0,0 +1 @@
+# TODO

flock/cli/load_flock.py

@@ -0,0 +1,38 @@
+"""Load a Flock from a file."""
+
+from pathlib import Path
+
+import questionary
+from rich.console import Console
+from rich.markdown import Markdown
+
+from flock.core.flock import Flock
+
+
+def filter(file_path) -> bool:
+    """Filter function for file selection."""
+    path = Path(file_path)
+    if path.is_dir():
+        return True
+    return path.is_file() and path.suffix == ".flock"
+
+
+def load_flock():
+    """Load a Flock from a file."""
+    console = Console()
+
+    console.print("\nPlease select a *.flock file\n", style="bold green")
+
+    result = questionary.path("", file_filter=filter).ask()
+
+    selected_file = Path(result)
+    if selected_file.is_file():
+        console.print(f"Selected file: {selected_file}", style="bold green")
+
+        flock = Flock.load_from_file(result)
+
+        console.line()
+        console.print(Markdown("# Flock loaded...."), style="bold orange")
+        console.line()
+
+        flock.run()

flock/cli/settings.py

@@ -0,0 +1 @@
+# TODO

flock/config.py

@@ -44,4 +44,3 @@ TELEMETRY = TelemetryConfig(
     OTEL_ENABLE_FILE,
     OTEL_ENABLE_SQL,
 )
-TELEMETRY.setup_tracing()

flock/core/execution/local_executor.py

@@ -1,12 +1,16 @@
 # src/your_package/core/execution/local_executor.py
 from flock.core.context.context import FlockContext
 from flock.core.logging.logging import get_logger
-from flock.workflow.activities import run_agent  # This should be the local activity function
+from flock.workflow.activities import (
+    run_agent,  # This should be the local activity function
+)
 
 logger = get_logger("flock")
 
 
-async def run_local_workflow(context: FlockContext, output_formatter, box_result: bool = True) -> dict:
+async def run_local_workflow(
+    context: FlockContext, box_result: bool = True
+) -> dict:
     """Execute the agent workflow locally (for debugging).
 
     Args:
@@ -18,7 +22,7 @@ async def run_local_workflow(context: FlockContext, output_formatter, box_result
         A dictionary containing the workflow result.
     """
     logger.info("Running local debug workflow")
-    result = await run_agent(context, output_formatter)
+    result = await run_agent(context)
     if box_result:
         from box import Box
 

flock/core/execution/temporal_executor.py

@@ -1,9 +1,7 @@
 # src/your_package/core/execution/temporal_executor.py
-from devtools import pprint
 
 from flock.core.context.context import FlockContext
 from flock.core.context.context_vars import FLOCK_RUN_ID
-from flock.core.logging.formatters.formatter_factory import FormatterFactory
 from flock.core.logging.logging import get_logger
 from flock.workflow.activities import (
     run_agent,  # Activity function used in Temporal
@@ -16,7 +14,6 @@ logger = get_logger("flock")
 
 async def run_temporal_workflow(
     context: FlockContext,
-    output_formatter,
     box_result: bool = True,
 ) -> dict:
     """Execute the agent workflow via Temporal for robust, distributed processing.
@@ -43,11 +40,7 @@ async def run_temporal_workflow(
 
     agent_name = context.get_variable("FLOCK_CURRENT_AGENT")
     logger.debug("Formatting Temporal result", agent=agent_name)
-    if output_formatter:
-        formatter = FormatterFactory.create_formatter(output_formatter)
-        formatter.display(result, agent_name, output_formatter.wait_for_input)
-    else:
-        pprint(result)
+
     if box_result:
         from box import Box
 

flock/core/flock.py

@@ -1,19 +1,21 @@
 """High-level orchestrator for creating and executing agents."""
 
+import asyncio
+import json
 import os
 import uuid
-from typing import TypeVar
+from typing import Any, TypeVar
 
+import cloudpickle
 from opentelemetry import trace
 from opentelemetry.baggage import get_baggage, set_baggage
 
+from flock.config import TELEMETRY
 from flock.core.context.context import FlockContext
 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.formatters.base_formatter import FormatterOptions
-from flock.core.logging.formatters.pprint_formatter import PrettyPrintFormatter
 from flock.core.logging.logging import get_logger
 from flock.core.registry.agent_registry import Registry
 from flock.core.util.cli_helper import display_banner
@@ -21,7 +23,7 @@ from flock.core.util.input_resolver import top_level_to_keys
 
 T = TypeVar("T", bound=FlockAgent)
 logger = get_logger("flock")
-
+TELEMETRY.setup_tracing()
 tracer = trace.get_tracer(__name__)
 
 
@@ -37,9 +39,6 @@ class Flock:
         model: str = "openai/gpt-4o",
         local_debug: bool = False,
         enable_logging: bool = False,
-        output_formatter: FormatterOptions = FormatterOptions(
-            PrettyPrintFormatter
-        ),
         show_cli_banner: bool = True,
     ):
         """Initialize the Flock orchestrator.
@@ -54,9 +53,6 @@ class Flock:
             span.set_attribute("model", model)
             span.set_attribute("local_debug", local_debug)
             span.set_attribute("enable_logging", enable_logging)
-            span.set_attribute(
-                "output_formatter", output_formatter.formatter.__name__
-            )
             logger.info(
                 "Initializing Flock",
                 model=model,
@@ -77,7 +73,8 @@ class Flock:
             self.context = FlockContext()
             self.model = model
             self.local_debug = local_debug
-            self.output_formatter = output_formatter
+            self.start_agent: FlockAgent | str | None = None
+            self.input: dict = {}
 
             if local_debug:
                 os.environ["LOCAL_DEBUG"] = "1"
@@ -142,9 +139,173 @@ class Flock:
             self.registry.register_tool(tool_name, tool)
             logger.debug("Tool registered successfully")
 
+    def run(
+        self,
+        start_agent: FlockAgent | str | None = None,
+        input: dict = {},
+        context: FlockContext = None,
+        run_id: str = "",
+        box_result: bool = True,
+    ) -> dict:
+        """Entry point for running an agent system synchronously."""
+        return asyncio.run(
+            self.run_async(start_agent, input, context, run_id, box_result)
+        )
+
+    def save_to_file(
+        self,
+        file_path: str,
+        start_agent: str | None = None,
+        input: dict | None = None,
+    ) -> None:
+        """Save the Flock instance to a file.
+
+        This method serializes the Flock instance to a dictionary using the `to_dict()` method and saves it to a file.
+        The saved file can be reloaded later using the `from_file()` method.
+
+        Args:
+            file_path (str): The path to the file where the Flock instance should be saved.
+        """
+        hex_str = cloudpickle.dumps(self).hex()
+
+        result = {
+            "start_agent": start_agent,
+            "input": input,
+            "flock": hex_str,
+        }
+
+        path = os.path.dirname(file_path)
+        if path:
+            os.makedirs(os.path.dirname(file_path), exist_ok=True)
+
+        with open(file_path, "w") as file:
+            file.write(json.dumps(result))
+
+    @staticmethod
+    def load_from_file(file_path: str) -> "Flock":
+        """Load a Flock instance from a file.
+
+        This class method deserializes a Flock instance from a file that was previously saved using the `save_to_file()`
+        method. It reads the file, converts the hexadecimal string back into a Flock instance, and returns it.
+
+        Args:
+            file_path (str): The path to the file containing the serialized Flock instance.
+
+        Returns:
+            Flock: A new Flock instance reconstructed from the saved file.
+        """
+        with open(file_path) as file:
+            json_flock = json.load(file)
+            hex_str = json_flock["flock"]
+            flock = cloudpickle.loads(bytes.fromhex(hex_str))
+            if json_flock["start_agent"]:
+                agent = flock.registry.get_agent(json_flock["start_agent"])
+                flock.start_agent = agent
+            if json_flock["input"]:
+                flock.input = json_flock["input"]
+            return flock
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the FlockAgent instance to a dictionary.
+
+        This method converts the entire agent instance—including its configuration, state, and lifecycle hooks—
+        into a dictionary format. It uses cloudpickle to serialize any callable objects (such as functions or
+        methods), converting them into hexadecimal string representations. This ensures that the agent can be
+        easily persisted, transmitted, or logged as JSON.
+
+        The serialization process is recursive:
+        - If a field is a callable (and not a class), it is serialized using cloudpickle.
+        - Lists and dictionaries are processed recursively to ensure that all nested callables are properly handled.
+
+        **Returns:**
+            dict[str, Any]: A dictionary representing the FlockAgent, which includes all of its configuration data.
+            This dictionary is suitable for storage, debugging, or transmission over the network.
+
+        **Example:**
+            For an agent defined as:
+                name = "idea_agent",
+                model = "openai/gpt-4o",
+                input = "query: str | The search query, context: dict | The full conversation context",
+                output = "idea: str | The generated idea"
+            Calling `agent.to_dict()` might produce:
+                {
+                    "name": "idea_agent",
+                    "model": "openai/gpt-4o",
+                    "input": "query: str | The search query, context: dict | The full conversation context",
+                    "output": "idea: str | The generated idea",
+                    "tools": ["<serialized tool representation>"],
+                    "use_cache": False,
+                    "hand_off": None,
+                    "termination": None,
+                    ...
+                }
+        """
+
+        def convert_callable(obj: Any) -> Any:
+            if callable(obj) and not isinstance(obj, type):
+                return cloudpickle.dumps(obj).hex()
+            if isinstance(obj, list):
+                return [convert_callable(item) for item in obj]
+            if isinstance(obj, dict):
+                return {k: convert_callable(v) for k, v in obj.items()}
+            return obj
+
+        data = self.model_dump()
+        return convert_callable(data)
+
+    @classmethod
+    def from_dict(cls: type[T], data: dict[str, Any]) -> T:
+        """Deserialize a FlockAgent instance from a dictionary.
+
+        This class method reconstructs a FlockAgent from its serialized dictionary representation, as produced
+        by the `to_dict()` method. It recursively processes the dictionary to convert any serialized callables
+        (stored as hexadecimal strings via cloudpickle) back into executable callable objects.
+
+        **Arguments:**
+            data (dict[str, Any]): A dictionary representation of a FlockAgent, typically produced by `to_dict()`.
+                The dictionary should contain all configuration fields and state information necessary to fully
+                reconstruct the agent.
+
+        **Returns:**
+            FlockAgent: An instance of FlockAgent reconstructed from the provided dictionary. The deserialized agent
+            will have the same configuration, state, and behavior as the original instance.
+
+        **Example:**
+            Suppose you have the following dictionary:
+                {
+                    "name": "idea_agent",
+                    "model": "openai/gpt-4o",
+                    "input": "query: str | The search query, context: dict | The full conversation context",
+                    "output": "idea: str | The generated idea",
+                    "tools": ["<serialized tool representation>"],
+                    "use_cache": False,
+                    "hand_off": None,
+                    "termination": None,
+                    ...
+                }
+            Then, calling:
+                agent = FlockAgent.from_dict(data)
+            will return a FlockAgent instance with the same properties and behavior as when it was originally serialized.
+        """
+
+        def convert_callable(obj: Any) -> Any:
+            if isinstance(obj, str) and len(obj) > 2:
+                try:
+                    return cloudpickle.loads(bytes.fromhex(obj))
+                except Exception:
+                    return obj
+            if isinstance(obj, list):
+                return [convert_callable(item) for item in obj]
+            if isinstance(obj, dict):
+                return {k: convert_callable(v) for k, v in obj.items()}
+            return obj
+
+        converted = convert_callable(data)
+        return cls(**converted)
+
     async def run_async(
         self,
-        start_agent: FlockAgent | str,
+        start_agent: FlockAgent | str | None = None,
         input: dict = {},
         context: FlockContext = None,
         run_id: str = "",
@@ -180,68 +341,70 @@ class Flock:
                 if hasattr(start_agent, "name")
                 else start_agent,
             )
+            if start_agent:
+                self.start_agent = start_agent
+            if input:
+                self.input = input
 
-            span.set_attribute("input", str(input))
+            span.set_attribute("input", str(self.input))
             span.set_attribute("context", str(context))
             span.set_attribute("run_id", run_id)
             span.set_attribute("box_result", box_result)
 
             try:
-                if isinstance(start_agent, str):
+                if isinstance(self.start_agent, str):
                     logger.debug(
-                        "Looking up agent by name", agent_name=start_agent
+                        "Looking up agent by name", agent_name=self.start_agent
                     )
-                    start_agent = self.registry.get_agent(start_agent)
-                    if not start_agent:
-                        logger.error("Agent not found", agent_name=start_agent)
+                    self.start_agent = self.registry.get_agent(self.start_agent)
+                    if not self.start_agent:
+                        logger.error(
+                            "Agent not found", agent_name=self.start_agent
+                        )
                         raise ValueError(
-                            f"Agent '{start_agent}' not found in registry"
+                            f"Agent '{self.start_agent}' not found in registry"
                         )
-                    start_agent.resolve_callables(context=self.context)
+                    self.start_agent.resolve_callables(context=self.context)
                 if context:
                     logger.debug("Using provided context")
                     self.context = context
                 if not run_id:
-                    run_id = f"{start_agent.name}_{uuid.uuid4().hex[:4]}"
+                    run_id = f"{self.start_agent.name}_{uuid.uuid4().hex[:4]}"
                     logger.debug("Generated run ID", run_id=run_id)
 
                 set_baggage("run_id", run_id)
 
                 # TODO - Add a check for required input keys
-                input_keys = top_level_to_keys(start_agent.input)
+                input_keys = top_level_to_keys(self.start_agent.input)
                 for key in input_keys:
                     if key.startswith("flock."):
                         key = key[6:]  # Remove the "flock." prefix
-                    if key not in input:
+                    if key not in self.input:
                         from rich.prompt import Prompt
 
-                        input[key] = Prompt.ask(
-                            f"Please enter {key} for {start_agent.name}"
+                        self.input[key] = Prompt.ask(
+                            f"Please enter {key} for {self.start_agent.name}"
                         )
 
                 # Initialize the context with standardized variables
                 initialize_context(
                     self.context,
-                    start_agent.name,
-                    input,
+                    self.start_agent.name,
+                    self.input,
                     run_id,
                     self.local_debug,
                 )
 
                 logger.info(
                     "Starting agent execution",
-                    agent=start_agent.name,
+                    agent=self.start_agent.name,
                     local_debug=self.local_debug,
                 )
 
                 if self.local_debug:
-                    return await run_local_workflow(
-                        self.context, self.output_formatter, box_result
-                    )
+                    return await run_local_workflow(self.context, box_result)
                 else:
-                    return await run_temporal_workflow(
-                        self.context, self.output_formatter, box_result
-                    )
+                    return await run_temporal_workflow(self.context, box_result)
             except Exception as e:
                 logger.exception("Execution failed", error=str(e))
                 raise