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

flock/core/flock.py

@@ -146,10 +146,13 @@ class Flock:
         context: FlockContext = None,
         run_id: str = "",
         box_result: bool = True,
+        agents: list[FlockAgent] = [],
     ) -> dict:
         """Entry point for running an agent system synchronously."""
         return asyncio.run(
-            self.run_async(start_agent, input, context, run_id, box_result)
+            self.run_async(
+                start_agent, input, context, run_id, box_result, agents
+            )
         )
 
     def save_to_file(
@@ -310,6 +313,7 @@ class Flock:
         context: FlockContext = None,
         run_id: str = "",
         box_result: bool = True,
+        agents: list[FlockAgent] = [],
     ) -> dict:
         """Entry point for running an agent system asynchronously.
 
@@ -326,6 +330,7 @@ class Flock:
             context (FlockContext, optional): A FlockContext instance to use. If not provided, a default context is used.
             run_id (str, optional): A unique identifier for this run. If empty, one is generated automatically.
             box_result (bool, optional): If True, wraps the output in a Box for nicer formatting. Defaults to True.
+            agents (list, optional): additional way to add agents to flock instead of add_agent
 
         Returns:
             dict: A dictionary containing the result of the agent workflow execution.
@@ -341,6 +346,9 @@ class Flock:
                 if hasattr(start_agent, "name")
                 else start_agent,
             )
+            for agent in agents:
+                self.add_agent(agent)
+
             if start_agent:
                 self.start_agent = start_agent
             if input:

flock/core/flock_agent.py

@@ -69,6 +69,9 @@ class FlockAgentOutputConfig:
     wait_for_input: bool = field(
         default=False, metadata={"description": "Wait for input."}
     )
+    write_to_file: bool = field(
+        default=False, metadata={"description": "Write to file."}
+    )
 
 
 @dataclass
@@ -465,6 +468,7 @@ class FlockAgent(BaseModel, ABC, PromptParserMixin, DSPyIntegrationMixin):
             self.output_config.max_length,
             self.output_config.render_table,
             self.output_config.wait_for_input,
+            self.output_config.write_to_file,
         ).display_result(result, self.name)
 
     async def run_temporal(self, inputs: dict[str, Any]) -> dict[str, Any]:

flock/core/logging/formatters/themed_formatter.py

@@ -416,6 +416,7 @@ class ThemedAgentResultFormatter:
         max_length: int = -1,
         render_table: bool = True,
         wait_for_input: bool = False,
+        write_to_file: bool = False,
     ):
         """Initialize the formatter with a theme and optional max length."""
         self.theme = theme
@@ -423,6 +424,7 @@ class ThemedAgentResultFormatter:
         self.max_length = max_length
         self.render_table = render_table
         self.wait_for_input = wait_for_input
+        self.write_to_file = write_to_file
 
     def format_result(
         self,
@@ -482,6 +484,11 @@ class ThemedAgentResultFormatter:
 
         s = pformat(result, highlight=False)
 
+        if self.write_to_file:
+            output_file = pathlib.Path(f"{agent_name}_result.txt")
+            with open(output_file, "w") as f:
+                f.write(s)
+
         if self.render_table:
             return Panel(
                 table,

flock/core/util/hydrator.py

@@ -0,0 +1,306 @@
+import asyncio
+import json
+from typing import get_origin, get_type_hints
+
+
+# -----------------------------------------------------------
+# Dummy FlockAgent for demonstration:
+# -----------------------------------------------------------
+class FlockAgent:
+    def __init__(self, name, input, output, model, description):
+        self.name = name
+        self.input = input
+        self.output = output
+        self.model = model
+        self.description = description
+
+    async def evaluate(self, data: dict) -> dict:
+        """Pretend LLM call.
+        We'll parse self.output to see which keys we want,
+        then generate some placeholders for those keys.
+        """
+        print(
+            f"[FlockAgent] Evaluate called for agent {self.name} with data: {data}"
+        )
+
+        # Very naive parse of output string: "title: str | desc, budget: int | desc, ..."
+        fields = []
+        for out_part in self.output.split(","):
+            out_part = out_part.strip()
+            # out_part might look like: "title: str | property of MyBlogPost"
+            if not out_part:
+                continue
+            field_name = out_part.split(":")[0].strip()
+            fields.append(field_name)
+
+        # We'll pretend the LLM returns either an integer for int fields or a string for others:
+        response = {}
+        for f in fields:
+            if " int" in self.output:  # naive
+                response[f] = 42
+            else:
+                response[f] = f"Generated data for {f}"
+        return response
+
+
+# -----------------------------------------------------------
+# Optional: a decorator that marks a class as "flockclass"
+# -----------------------------------------------------------
+def flockclass(model: str):
+    def decorator(cls):
+        cls.__is_flockclass__ = True
+        cls.__flock_model__ = model
+        return cls
+
+    return decorator
+
+
+# -----------------------------------------------------------
+# Utility sets
+# -----------------------------------------------------------
+BASIC_TYPES = {str, int, float, bool}
+
+
+# -----------------------------------------------------------
+# The main hydrator that can handle:
+#   - basic types (do nothing)
+#   - user-defined classes (auto-fill missing fields + recurse)
+#   - lists (ask LLM how many items to create + fill them)
+#   - dicts (ask LLM how many key->value pairs to create + fill them)
+# -----------------------------------------------------------
+def hydrate_object(obj, model="gpt-4", class_name=None):
+    """Recursively hydrates the object in-place,
+    calling an LLM for missing fields or structure.
+    """
+    # 1) If None or basic, do nothing
+    if obj is None or isinstance(obj, (str, int, float, bool)):
+        return
+
+    # 2) If list, check if it is empty => ask the LLM how many items we need
+    if isinstance(obj, list):
+        if len(obj) == 0:
+            # We'll do a single LLM call to decide how many items to put in:
+            # In real usage, you'd put a more robust prompt.
+            list_agent = FlockAgent(
+                name=f"{class_name or 'list'}Generator",
+                input="Generate number of items for this list",
+                output="count: int | number of items to create",
+                model=model,
+                description="Agent that decides how many items to create in a list.",
+            )
+            result = asyncio.run(list_agent.evaluate({}))
+            num_items = result.get("count", 0)
+            # We'll assume the list should hold some type T.
+            # But in Python, we rarely store that info in the runtime.
+            # For demonstration, let's just store dummy strings or we can guess "object".
+            for i in range(num_items):
+                # For demonstration, create a simple string or dict
+                # If you want a typed approach, you'll need additional metadata or pass in generics
+                item = f"Generated item {i + 1}"
+                obj.append(item)
+
+        # Now recursively fill each item
+        for i in range(len(obj)):
+            hydrate_object(
+                obj[i],
+                model=model,
+                class_name=f"{class_name or 'list'}[item={i}]",
+            )
+        return
+
+    # 3) If dict, check if it is empty => ask LLM for which keys to create
+    if isinstance(obj, dict):
+        if len(obj) == 0:
+            # We'll do a single LLM call that returns a list of keys
+            dict_agent = FlockAgent(
+                name=f"{class_name or 'dict'}Generator",
+                input="Generate keys for this dict",
+                output="keys: str | comma-separated list of keys to create",
+                model=model,
+                description="Agent that decides which keys to create in a dict.",
+            )
+            result = asyncio.run(dict_agent.evaluate({}))
+            keys_str = result.get("keys", "")
+            keys = [k.strip() for k in keys_str.split(",") if k.strip()]
+
+            # For demonstration, let's assume the dict holds sub-objects that we can fill further
+            # We'll create a plain dict or plain string for each key
+            for k in keys:
+                obj[k] = f"Placeholder for {k}"
+
+        # Now recursively fill each value
+        for key, val in obj.items():
+            hydrate_object(
+                val,
+                model=model,
+                class_name=f"{class_name or 'dict'}[key={key}]",
+            )
+        return
+
+    # 4) If it's a user-defined class with annotations, fill missing fields
+    cls = type(obj)
+    if hasattr(cls, "__annotations__"):
+        # If there's a model stored on the class, we can use that. Else fallback to the default
+        used_model = getattr(cls, "__flock_model__", model)
+
+        # Figure out which fields are missing or None
+        type_hints = get_type_hints(cls)
+        missing_basic_fields = []
+        complex_fields = []
+        for field_name, field_type in type_hints.items():
+            value = getattr(obj, field_name, None)
+            if value is None:
+                # It's missing. See if it's a basic type or complex
+                if _is_basic_type(field_type):
+                    missing_basic_fields.append(field_name)
+                else:
+                    complex_fields.append(field_name)
+            else:
+                # Already has some value, but if it's a complex type, we should recurse
+                if not _is_basic_type(field_type):
+                    complex_fields.append(field_name)
+
+        # If we have missing basic fields, do a single LLM call to fill them
+        if missing_basic_fields:
+            input_str = (
+                f"Existing data: {json.dumps(obj.__dict__, default=str)}"
+            )
+            output_fields_str = []
+            for bf in missing_basic_fields:
+                bf_type = type_hints[bf]
+                bf_type_name = (
+                    bf_type.__name__
+                    if hasattr(bf_type, "__name__")
+                    else str(bf_type)
+                )
+                desc = f"property of a class named {cls.__name__}"
+                output_fields_str.append(f"{bf}: {bf_type_name} | {desc}")
+
+            agent = FlockAgent(
+                name=cls.__name__,
+                input=input_str,
+                output=", ".join(output_fields_str),
+                model=used_model,
+                description=f"Agent for {cls.__name__}",
+            )
+            result = asyncio.run(agent.evaluate(obj.__dict__))
+            for bf in missing_basic_fields:
+                if bf in result:
+                    setattr(obj, bf, result[bf])
+
+        # For each "complex" field, instantiate if None + recurse
+        for cf in complex_fields:
+            cf_value = getattr(obj, cf, None)
+            cf_type = type_hints[cf]
+
+            if cf_value is None:
+                # We need to create something of the appropriate type
+                new_val = _instantiate_type(cf_type)
+                setattr(obj, cf, new_val)
+                hydrate_object(
+                    new_val, model=used_model, class_name=cf_type.__name__
+                )
+            else:
+                # Recurse into it
+                hydrate_object(
+                    cf_value, model=used_model, class_name=cf_type.__name__
+                )
+
+    else:
+        # It's some Python object with no annotations -> do nothing
+        pass
+
+
+# -----------------------------------------------------------
+# Helper: is a type "basic"?
+# -----------------------------------------------------------
+def _is_basic_type(t):
+    if t in BASIC_TYPES:
+        return True
+    # You may want to check for Optionals or Unions
+    # e.g., if get_origin(t) == Union, parse that, etc.
+    return False
+
+
+# -----------------------------------------------------------
+# Helper: instantiate a type (list, dict, or user-defined)
+# -----------------------------------------------------------
+def _instantiate_type(t):
+    origin = get_origin(t)
+    if origin is list:
+        return []
+    if origin is dict:
+        return {}
+
+    # If it's a built-in basic type, return None (we fill it from LLM).
+    if t in BASIC_TYPES:
+        return None
+
+    # If it's a user-defined class
+    if isinstance(t, type):
+        try:
+            # Attempt parameterless init
+            return t()
+        except:
+            # Or try __new__
+            try:
+                return t.__new__(t)
+            except:
+                return None
+    return None
+
+
+# -----------------------------------------------------------
+# Example classes
+# -----------------------------------------------------------
+@flockclass("gpt-4")
+class LongContent:
+    title: str
+    content: str
+
+
+@flockclass("gpt-4")
+class MyBlogPost:
+    title: str
+    headers: str
+    # We'll have a dict of key->LongContent
+    content: dict[str, LongContent]
+
+
+@flockclass("gpt-4")
+class MyProjectPlan:
+    project_idea: str
+    budget: int
+    title: str
+    content: MyBlogPost
+
+
+# -----------------------------------------------------------
+# Demo
+# -----------------------------------------------------------
+if __name__ == "__main__":
+    plan = MyProjectPlan()
+    plan.project_idea = "a declarative agent framework"
+    plan.budget = 100000
+
+    # content is None by default, so the hydrator will create MyBlogPost
+    # and fill it in. MyBlogPost.content is a dict[str, LongContent],
+    # also None -> becomes an empty dict -> we let the LLM decide the keys.
+
+    hydrate_object(plan, model="gpt-4", class_name="MyProjectPlan")
+
+    print("\n--- MyProjectPlan hydrated ---")
+    for k, v in plan.__dict__.items():
+        print(f"{k} = {v}")
+    if plan.content:
+        print("\n--- MyBlogPost hydrated ---")
+        for k, v in plan.content.__dict__.items():
+            print(f"  {k} = {v}")
+            if k == "content" and isinstance(v, dict):
+                print("    (keys) =", list(v.keys()))
+                for sub_k, sub_val in v.items():
+                    print(f"    {sub_k} -> {sub_val}")
+                    if isinstance(sub_val, LongContent):
+                        print(
+                            f"       -> LongContent fields: {sub_val.__dict__}"
+                        )

flock_core-0.2.17.dist-info/METADATA

@@ -0,0 +1,441 @@
+Metadata-Version: 2.4
+Name: flock-core
+Version: 0.2.17
+Summary: Declarative LLM Orchestration at Scale
+Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: cloudpickle>=3.1.1
+Requires-Dist: devtools>=0.12.2
+Requires-Dist: dspy==2.5.42
+Requires-Dist: duckduckgo-search>=7.3.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: msgpack>=1.1.0
+Requires-Dist: opentelemetry-api>=1.30.0
+Requires-Dist: opentelemetry-exporter-jaeger-proto-grpc>=1.21.0
+Requires-Dist: opentelemetry-exporter-jaeger>=1.21.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.30.0
+Requires-Dist: opentelemetry-instrumentation-logging>=0.51b0
+Requires-Dist: opentelemetry-sdk>=1.30.0
+Requires-Dist: pydantic>=2.10.5
+Requires-Dist: python-box>=7.3.2
+Requires-Dist: python-decouple>=3.8
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=13.9.4
+Requires-Dist: temporalio>=1.9.0
+Requires-Dist: toml>=0.10.2
+Provides-Extra: all-tools
+Requires-Dist: docling>=2.18.0; extra == 'all-tools'
+Requires-Dist: markdownify>=0.14.1; extra == 'all-tools'
+Requires-Dist: tavily-python>=0.5.0; extra == 'all-tools'
+Provides-Extra: tools
+Requires-Dist: markdownify>=0.14.1; extra == 'tools'
+Requires-Dist: tavily-python>=0.5.0; extra == 'tools'
+Description-Content-Type: text/markdown
+
+<p align="center">
+<img src="docs/img/flock.png" width="600"><br>
+<img alt="Dynamic TOML Badge" src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fwhiteducksoftware%2Fflock%2Frefs%2Fheads%2Fmaster%2Fpyproject.toml&query=%24.project.version&style=for-the-badge&logo=pypi&label=pip%20version">
+<a href="https://www.linkedin.com/company/whiteduck" target="_blank"><img alt="LinkedIn" src="https://img.shields.io/badge/linkedin-%230077B5.svg?style=for-the-badge&logo=linkedin&logoColor=white&label=whiteduck"></a>
+<a href="https://bsky.app/profile/whiteduck-gmbh.bsky.social" target="_blank"><img alt="Bluesky" src="https://img.shields.io/badge/bluesky-Follow-blue?style=for-the-badge&logo=bluesky&logoColor=%23fff&color=%23333&labelColor=%230285FF&label=whiteduck-gmbh"></a>
+
+## Overview
+
+Flock is a framework for orchestrating LLM-powered agents. It leverages a **declarative approach** where you simply specify what each agent needs as input and what it produces as output—without having to write lengthy, brittle prompts. Under the hood, Flock transforms these declarations into robust workflows, using cutting-edge components such as Temporal and DSPy to handle fault tolerance, state management, and error recovery.
+
+
+
+| Traditional Agent Frameworks 🙃          |                        Flock 🐤🐧🐓🦆                         |
+|------------------------------------------|--------------------------------------------------------------|
+| 🤖 **Complex Prompt Engineering**         | 📝 **Declarative Agent Definitions**                         |
+| • Lengthy, brittle prompts               | • Clear, concise input/output declarations                   |
+| • Hard-to-tune and adapt                 | • No need for manual prompt engineering                      |
+|                                          |                                                              |
+| 💥 **Fragile Execution**                  | ⚡ **Robust & Scalable**                                      |
+| • Single failure can break the system    | • Fault-tolerant with built-in retries and error handling      |
+| • Difficult to monitor and recover       | • Automatic recovery via Temporal workflow integration         |
+|                                          |                                                              |
+| 🏗️ **Rigid Workflows**                    | 🔄 **Flexible Orchestration**                                |
+| • Limited adaptability                   | • Dynamic agent chaining and hand-offs                       |
+| • Hard to scale and parallelize          | • Modular, concurrent, and batch processing                   |
+|                                          |                                                              |
+
+## Video Demonstration
+
+
+https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
+
+
+
+
+## Key Innovations
+
+- **Declarative Agent System:**  
+  When you order a pizza at your favorite place, you just tell them what pizza you want, not the 30 steps to get there!
+  And thanks to an invention called LLMs, we now have the technology to come up with those 30 steps.
+
+  Flock takes advantage of that.
+
+  Define agents by declaring their input/output interfaces (with type hints and human-readable descriptions) using a concise syntax.  
+  The framework automatically extracts type and description details, builds precise prompts, and configures the underlying LLM.
+
+  Testing becomes quite simple as well. You got the pizza you ordered? Passed ✅
+
+- **Type Safety and Clear Contracts:**  
+  Agents are implemented as Pydantic models. This provides automatic JSON serialization/deserialization, strong typing, and an explicit contract for inputs and outputs. Testing, validation, and integration become straightforward.
+
+- **Unparalleled Flexibility:**  
+  Each agent (via the new `FlockAgent` base class) supports lifecycle hooks such as `initialize()`, `terminate()`, `evaluate()`, and `on_error()`. This ensures that agents can perform setup, cleanup, and robust error handling—all without cluttering the main business logic. Everything is overridable or lets you provide your own callables per callback. We mean `everything` quite literally. Except for the agent name, literally every property of an agent can be set to a callable, leading to highly dynamic and capable agents.
+
+- **Fault Tolerance & Temporal Integration:**  
+  Flock is built with production readiness in mind. By integrating with Temporal, your agent workflows enjoy automatic retries, durable state management, and resilience against failures. This means that a single agent crash won't bring down your entire system.
+
+
+<p align="center">
+<img src="docs/img/flock_cli.png" width="200"><br>
+
+## Examples
+
+Let's showcase easy to understand examples to give you an idea what flock offers!
+All examples and/or similar examples can be found in the examples folder!
+
+### Hello Flock!
+
+
+Let's start the most simple way possible 🚀
+
+```python
+
+from flock.core import Flock, FlockAgent
+
+MODEL = "openai/gpt-4o"
+
+flock = Flock(model=MODEL, local_debug=True)
+
+bloggy = FlockAgent(
+    name="bloggy", 
+    input="blog_idea", 
+    output="funny_blog_title, blog_headers"
+)
+flock.add_agent(bloggy)
+
+result = flock.run(
+    start_agent=bloggy, 
+    input={"blog_idea": "A blog about cats"}
+)
+
+```
+
+With almost no boilerplate needed, getting your first agent to run is as easy as cake!
+
+`bloggy` takes in a `blog_idea` to produce a `funny_blog_title` and `blog_headers`. That is all!
+
+Flock does take care of the rest, which frees you from needing to write paragraphs of text.
+You might think abstracting prompting like this means less control - but nope! Quite the contrary, it'll increase your control over it!
+
+When we let `bloggy` loose in the flock:
+
+
+```python
+{
+    'funny_blog_title': '"Whisker Wonders: The Purr-fect Guide to Cat-tastrophes and Feline Follies"',
+    'blog_headers': (
+        '1. "The Cat\'s Meow: Understanding Your Feline\'s Language"\n'
+        '2. "Paws and Reflect: The Secret Life of Cats"\n'
+        '3. "Fur Real: Debunking Myths About Our Furry Friends"\n'
+        '4. "Claw-some Adventures: How to Entertain Your Indoor Cat"\n'
+        '5. "Cat-astrophic Cuteness: Why We Can\'t Resist Those Whiskers"\n'
+        '6. "Tail Tales: The History of Cats and Their Human Companions"\n'
+        '7. "Purr-sonality Plus: What Your Cat\'s Behavior Says About Them"\n'
+        '8. "Kitty Conundrums: Solving Common Cat Problems with Humor"'
+    ),
+    'blog_idea': 'A blog about cats',
+}
+```
+
+Look at that! A real Python object with fields exactly as we defined them in the agent.
+No need to mess around with parsing or post-processing! 🎉
+
+### It's not my type
+
+You probably noticed that your headers aren't a real Python list, but you need one for your downstream task. Flock got you! Just sprinkle some type hints in your agent definition! ✨
+
+```python
+
+from flock.core import Flock, FlockAgent
+
+MODEL = "openai/gpt-4o"
+
+flock = Flock(model=MODEL, local_debug=True)
+
+bloggy = FlockAgent(
+    name="bloggy", 
+    input="blog_idea", 
+    output="funny_blog_title, blog_headers: list[str]"
+)
+flock.add_agent(bloggy)
+
+result = flock.run(
+    start_agent=bloggy, 
+    input={"blog_idea": "A blog about cats"}
+)
+
+```
+
+Et voila! Now you get:
+
+```python
+{
+    'funny_blog_title': '"Whisker Me This: The Purr-fect Guide to Cat-tastic Adventures"',
+    'blog_headers': [
+        "The Cat's Out of the Bag: Understanding Feline Behavior",
+        'Paws and Reflect: The Secret Life of Cats',
+        'Feline Fine: Health Tips for Your Kitty',
+        "Cat-astrophic Cuteness: Why We Can't Resist Them",
+        'Meow-sic to Your Ears: Communicating with Your Cat',
+        'Claw-some Toys and Games: Keeping Your Cat Entertained',
+        'The Tail End: Myths and Facts About Cats',
+    ],
+    'blog_idea': 'A blog about cats',
+}
+
+```
+
+### Being pydantic
+
+That's not enough for you, since you already got your data classes defined and don't want to redefine them again for some agents?
+
+Also got some hard constraints, like the title needs to be in ALL CAPS? 🔥
+
+Check this out:
+
+```python
+from pydantic import BaseModel, Field
+
+class BlogSection(BaseModel):
+    header: str
+    content: str
+
+class MyBlog(BaseModel):
+    funny_blog_title: str = Field(description="The funny blog title in all caps")
+    blog_sections: list[BlogSection]
+```
+
+Since flock is bein' pedantic about pydantic, you can just use your pydantic models like you would use type hints:
+
+```python
+bloggy = FlockAgent(
+    name="bloggy", 
+    input="blog_idea", 
+    output="blog: MyBlog",
+)
+```
+
+And BAM! Your finished data model filled up to the brim with data! 🎊
+
+
+```python
+{
+  'blog': MyBlog(
+      funny_blog_title='THE PURR-FECT LIFE: CATS AND THEIR QUIRKY ANTICS',
+      blog_sections=[
+          BlogSection(
+              header='Introduction to the Feline World',
+              content=(
+                  'Cats have been our companions for thousands of years, yet they remain as mysterious and intriguin'
+                  'g as ever. From their graceful movements to their independent nature, cats have a unique charm th'
+                  "at captivates us. In this blog, we'll explore the fascinating world of cats and their quirky anti"
+                  'cs that make them the purr-fect pets.'
+              ),
+          ),
+          BlogSection(
+              header='The Mysterious Ways of Cats',
+              content=(
+                  'Ever wonder why your cat suddenly sprints across the room at 3 AM or stares at a blank wall for h'
+                  'ours? Cats are known for their mysterious behaviors that often leave us scratching our heads. The'
+                  'se antics are not just random; they are deeply rooted in their instincts and natural behaviors. L'
+                  "et's dive into some of the most common and puzzling cat behaviors."
+              ),
+          ),
+          BlogSection(
+              header="The Art of Napping: A Cat's Guide",
+              content=(
+                  "Cats are the ultimate nappers, spending up to 16 hours a day snoozing. But there's more to a catn"
+                  'ap than meets the eye. Cats have perfected the art of napping, and each nap serves a purpose, whe'
+                  "ther it's a quick power nap or a deep sleep. Learn how cats choose their napping spots and the sc"
+                  'ience behind their sleep patterns.'
+              ),
+          ),
+          BlogSection(
+              header='The Great Cat Conspiracy: Do They Really Rule the World?',
+              content=(
+                  "It's a well-known fact among cat owners that cats secretly rule the world. With their ability to "
+                  "manipulate humans into providing endless treats and belly rubs, it's no wonder they have us wrapp"
+                  "ed around their little paws. Explore the humorous side of cat ownership and the 'conspiracy' theo"
+                  'ries that suggest cats are the true overlords of our homes.'
+              ),
+          ),
+          BlogSection(
+              header='Conclusion: Why We Love Cats',
+              content=(
+                  'Despite their quirks and sometimes aloof nature, cats have a special place in our hearts. Their c'
+                  "ompanionship, playful antics, and soothing purrs bring joy and comfort to our lives. Whether you'"
+                  "re a lifelong cat lover or a new cat parent, there's no denying the unique bond we share with our"
+                  " feline friends. So, here's to the purr-fect life with cats!"
+              ),
+          ),
+      ],
+  ),
+  'blog_idea': 'A blog about cats',
+}
+```
+
+So far we've barely scratched the surface of what flock has to offer, and we're currently hard at work building up the documentation for all the other super cool features Flock has up its sleeve! Stay tuned! 🚀
+
+## Temporal Workflow Integration
+
+Flock supports execution on Temporal, ensuring robust, fault-tolerant workflows:
+
+- **Durability:** Persistent state management even in the case of failures.
+- **Retries & Error Handling:** Automatic recovery via Temporal's built-in mechanisms.
+- **Scalability:** Seamless orchestration of distributed agent workflows.
+
+Documentation in progress!
+
+## Architecture
+
+Documentation in progress!
+
+
+## Requirements
+
+- Python 3.10+
+- (Optional) Temporal server running locally for production-grade workflow features
+- API keys for integrated services
+
+
+recommended services
+```bash
+export OPENAI_API_KEY=sk-proj-
+export TAVILY_API_KEY=tvly-
+```
+
+or in `.env`
+
+For LLM interaction LiteLLM is getting used. Please refer to its documentation on how to easily use other models and/or provider.
+
+https://docs.litellm.ai/docs/providers
+
+## Installation
+
+```bash
+pip install flock-core
+```
+
+if you want to use the integrated tools
+
+```bash
+pip install flock-core[tools]
+```
+
+and for the docling tools
+
+```bash
+pip install flock-core[all-tools]
+```
+
+## Development
+
+
+1. **Clone the Repository:**
+
+   ```bash
+   git clone https://github.com/whiteducksoftware/flock
+   cd flock
+   ```
+
+2. **Create a Virtual Environment and sync all packages:**
+
+   ```bash
+   uv sync --all-groups --all-extras
+   ```
+
+3. **Install local version of flock:**
+
+   ```bash
+   uv build && uv pip install -e .
+   ```
+
+4. **Install Jaeger for telemetry**
+    ```
+
+    docker run -d --name jaeger \
+      -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
+      -p 5775:5775/udp \
+      -p 6831:6831/udp \
+      -p 6832:6832/udp \
+      -p 5778:5778 \
+      -p 16686:16686 \
+      -p 14268:14268 \
+      -p 14250:14250 \
+      -p 9411:9411 \
+      jaegertracing/all-in-one:1.41
+
+
+    ```
+
+5. **Create your .env**
+
+    Use `.env_template` as a template for you custom config variables
+
+
+## Contributing
+
+Contributions are welcome! Please submit Pull Requests and open issues on GitHub.
+
+## License
+
+This project is licensed under the terms of the LICENSE file included in the repository.
+
+## Acknowledgments
+
+- Built with [DSPy](https://github.com/stanfordnlp/dspy)
+- Uses [Temporal](https://temporal.io/) for workflow management
+- Integrates with [Tavily](https://tavily.com/) for web search capabilities
+
+## Evolution & Future Direction
+
+Flock was created to overcome the limitations of traditional agent frameworks. Key design goals include:
+
+### Declarative Over Prompt Engineering
+
+- **Simplify Agent Definitions:**  
+  Focus on clear input/output contracts rather than long, complex prompts.
+- **Model Agnostic:**  
+  Change LLM backends without altering agent logic.
+- **Improved Testability:**  
+  Clear, structured interfaces facilitate unit testing and validation.
+
+### Robust, Production-Grade Orchestration
+
+- **Fault Tolerance:**  
+  Leveraging Temporal for automatic retries, durable state, and robust error handling.
+- **Scalability:**  
+  Support for concurrent, batch, and distributed workflows.
+- **Observability:**  
+  Built-in logging and monitoring for real-time insights into workflow execution.
+
+### Future Enhancements
+
+- Expanded type system for richer agent interactions
+- Enhanced tool ecosystem and custom integrations
+- Advanced monitoring, debugging, and performance metrics
+- Extended testing frameworks and validation tools
+
+Join us in building the next generation of reliable, production-ready AI agent systems!
+Become part of the FLOCK!
+

{flock_core-0.2.16.dist-info → flock_core-0.2.17.dist-info}/RECORD

@@ -8,8 +8,8 @@ flock/cli/load_examples.py,sha256=DkeLUlrb7rGx3nZ04aADU9HXXu5mZTf_DBwT0xhzIv4,7
 flock/cli/load_flock.py,sha256=3JdECvt5X7uyOG2vZS3-Zk5C5SI_84_QZjcsB3oJmfA,932
 flock/cli/settings.py,sha256=DkeLUlrb7rGx3nZ04aADU9HXXu5mZTf_DBwT0xhzIv4,7
 flock/core/__init__.py,sha256=0Xq_txurlxxjKGXjRn6GNJusGTiBcd7zw2eF0L7JyuU,183
-flock/core/flock.py,sha256=3EQqrAej3Tb1vLYsILkXBcV9Feb2b1ABUviM3Xp9tMs,17151
-flock/core/flock_agent.py,sha256=FPi6hz8pOvHpsk5YzzKScnOaQzGo1W3lIOwzfHzrjyE,30572
+flock/core/flock.py,sha256=RoLatRW91dSJjFhq6T5t03y_zsIYPxcatn6IHpRUcVc,17435
+flock/core/flock_agent.py,sha256=WWhYMnLGvaeJ47gVX5s3v6sJx1VsGkcU6NDrA3ELbVY,30723
 flock/core/context/context.py,sha256=jH06w4C_O5CEL-YxjX_x_dmgLe9Rcllnn1Ebs0dvwaE,6171
 flock/core/context/context_manager.py,sha256=qMySVny_dbTNLh21RHK_YT0mNKIOrqJDZpi9ZVdBsxU,1103
 flock/core/context/context_vars.py,sha256=0Hn6fM2iNc0_jIIU0B7KX-K2o8qXqtZ5EYtwujETQ7U,272
@@ -21,7 +21,7 @@ flock/core/logging/telemetry.py,sha256=3E9Tyj6AUR6A5RlIufcdCdWm5BAA7tbOsCa7lHoUQ
 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=kCmGXLD8yzhfzENJUQOsqX3Sdo2PuN8JIZvBBWO22JI,20834
+flock/core/logging/formatters/themed_formatter.py,sha256=6WO9RPr6Su05rJEX9bRXd8peE-QzGCQeO5veIjQH-Vc,21086
 flock/core/logging/formatters/themes.py,sha256=vZqDyPlxZ1RGwzp8QCm0-Y0aXBZ62gTllulK6nbi_L4,10675
 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
@@ -33,6 +33,7 @@ flock/core/registry/agent_registry.py,sha256=YkYIyvFNjm7gYKRAiQQdOvVYMtsYH5cijfr
 flock/core/tools/basic_tools.py,sha256=OwWaFu4NoVrc3Uijj56RY9XDDaP_mOnEa5B3wSWwwLE,4756
 flock/core/tools/dev_tools/github.py,sha256=a2OTPXS7kWOVA4zrZHynQDcsmEi4Pac5MfSjQOLePzA,5308
 flock/core/util/cli_helper.py,sha256=nlSnPrc1pnYEFQXcL_wCqPI6g1Jr7AzNtmGoOPs0zKw,936
+flock/core/util/hydrator.py,sha256=6qNwOwCZB7r6y25BZ--0PGofrAlfMaXbDKFQeP5NLts,11196
 flock/core/util/input_resolver.py,sha256=g9vDPdY4OH-G7qjas5ksGEHueokHGFPMoLOvC-ngeLo,5984
 flock/core/util/serializable.py,sha256=SymJ0YrjBx48mOBItYSqoRpKuzIc4vKWRS6ScTzre7s,2573
 flock/interpreter/python_interpreter.py,sha256=pq2e7KJfAYtBCP2hhbtFNeg18QdMFF66esoYn3MHfA4,26177
@@ -379,8 +380,8 @@ flock/workflow/activities.py,sha256=2zcYyDoCuYs9oQbnhLjCzBUdEi7d5IEIemKJ7TV_B8w,
 flock/workflow/agent_activities.py,sha256=NhBZscflEf2IMfSRa_pBM_TRP7uVEF_O0ROvWZ33eDc,963
 flock/workflow/temporal_setup.py,sha256=VWBgmBgfTBjwM5ruS_dVpA5AVxx6EZ7oFPGw4j3m0l0,1091
 flock/workflow/workflow.py,sha256=I9MryXW_bqYVTHx-nl2epbTqeRy27CAWHHA7ZZA0nAk,1696
-flock_core-0.2.16.dist-info/METADATA,sha256=GYQ8kQbOOthWVA3ld9RF2a06BFuA8iSk0q1h6E2h5ao,12057
-flock_core-0.2.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-flock_core-0.2.16.dist-info/entry_points.txt,sha256=rWaS5KSpkTmWySURGFZk6PhbJ87TmvcFQDi2uzjlagQ,37
-flock_core-0.2.16.dist-info/licenses/LICENSE,sha256=iYEqWy0wjULzM9GAERaybP4LBiPeu7Z1NEliLUdJKSc,1072
-flock_core-0.2.16.dist-info/RECORD,,
+flock_core-0.2.17.dist-info/METADATA,sha256=uluO8ie9LjTnlmLXTdaNTvanGOE-tsIcGdYB-tPKJjk,16930
+flock_core-0.2.17.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+flock_core-0.2.17.dist-info/entry_points.txt,sha256=rWaS5KSpkTmWySURGFZk6PhbJ87TmvcFQDi2uzjlagQ,37
+flock_core-0.2.17.dist-info/licenses/LICENSE,sha256=iYEqWy0wjULzM9GAERaybP4LBiPeu7Z1NEliLUdJKSc,1072
+flock_core-0.2.17.dist-info/RECORD,,

flock_core-0.2.16.dist-info/METADATA

@@ -1,332 +0,0 @@
-Metadata-Version: 2.4
-Name: flock-core
-Version: 0.2.16
-Summary: Declarative LLM Orchestration at Scale
-Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
-License-File: LICENSE
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.10
-Requires-Dist: cloudpickle>=3.1.1
-Requires-Dist: devtools>=0.12.2
-Requires-Dist: dspy==2.5.42
-Requires-Dist: duckduckgo-search>=7.3.2
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: loguru>=0.7.3
-Requires-Dist: msgpack>=1.1.0
-Requires-Dist: opentelemetry-api>=1.30.0
-Requires-Dist: opentelemetry-exporter-jaeger-proto-grpc>=1.21.0
-Requires-Dist: opentelemetry-exporter-jaeger>=1.21.0
-Requires-Dist: opentelemetry-exporter-otlp>=1.30.0
-Requires-Dist: opentelemetry-instrumentation-logging>=0.51b0
-Requires-Dist: opentelemetry-sdk>=1.30.0
-Requires-Dist: pydantic>=2.10.5
-Requires-Dist: python-box>=7.3.2
-Requires-Dist: python-decouple>=3.8
-Requires-Dist: questionary>=2.1.0
-Requires-Dist: rich>=13.9.4
-Requires-Dist: temporalio>=1.9.0
-Requires-Dist: toml>=0.10.2
-Provides-Extra: all-tools
-Requires-Dist: docling>=2.18.0; extra == 'all-tools'
-Requires-Dist: markdownify>=0.14.1; extra == 'all-tools'
-Requires-Dist: tavily-python>=0.5.0; extra == 'all-tools'
-Provides-Extra: tools
-Requires-Dist: markdownify>=0.14.1; extra == 'tools'
-Requires-Dist: tavily-python>=0.5.0; extra == 'tools'
-Description-Content-Type: text/markdown
-
-<p align="center">
-<img src="docs/img/flock.png" width="600"><br>
-<img alt="Dynamic TOML Badge" src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fwhiteducksoftware%2Fflock%2Frefs%2Fheads%2Fmaster%2Fpyproject.toml&query=%24.project.version&style=for-the-badge&logo=pypi&label=pip%20version">
-<a href="https://www.linkedin.com/company/whiteduck" target="_blank"><img alt="LinkedIn" src="https://img.shields.io/badge/linkedin-%230077B5.svg?style=for-the-badge&logo=linkedin&logoColor=white&label=whiteduck"></a>
-<a href="https://bsky.app/profile/whiteduck-gmbh.bsky.social" target="_blank"><img alt="Bluesky" src="https://img.shields.io/badge/bluesky-Follow-blue?style=for-the-badge&logo=bluesky&logoColor=%23fff&color=%23333&labelColor=%230285FF&label=whiteduck-gmbh"></a>
-
-## Overview
-
-Flock is a framework for orchestrating LLM-powered agents. It leverages a **declarative approach** where you simply specify what each agent needs as input and what it produces as output—without having to write lengthy, brittle prompts. Under the hood, Flock transforms these declarations into robust workflows, using cutting-edge components such as Temporal and DSPy to handle fault tolerance, state management, and error recovery.
-
-
-
-| Traditional Agent Frameworks 🙃          |                        Flock 🐤🐧🐓🦆                         |
-|------------------------------------------|--------------------------------------------------------------|
-| 🤖 **Complex Prompt Engineering**         | 📝 **Declarative Agent Definitions**                         |
-| • Lengthy, brittle prompts               | • Clear, concise input/output declarations                   |
-| • Hard-to-tune and adapt                 | • No need for manual prompt engineering                      |
-|                                          |                                                              |
-| 💥 **Fragile Execution**                  | ⚡ **Robust & Scalable**                                      |
-| • Single failure can break the system    | • Fault-tolerant with built-in retries and error handling      |
-| • Difficult to monitor and recover       | • Automatic recovery via Temporal workflow integration         |
-|                                          |                                                              |
-| 🏗️ **Rigid Workflows**                    | 🔄 **Flexible Orchestration**                                |
-| • Limited adaptability                   | • Dynamic agent chaining and hand-offs                       |
-| • Hard to scale and parallelize          | • Modular, concurrent, and batch processing                   |
-|                                          |                                                              |
-
-## Video Demonstration
-
-
-https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
-
-
-
-
-## Key Innovations
-
-- **Declarative Agent System:**  
-  Define agents by declaring their input/output interfaces (with type hints and human-readable descriptions) using a concise syntax.  
-
-
-  <img src="docs/img/examples/01_01.png" width="300"><br>
-
-
-  Example syntax:
-  ```python
-  input = "query: str|The search query, context: dict|The full conversation context"
-  output = "idea: str|The generated software project idea"
-  ```
-  The framework automatically extracts type and description details, builds precise prompts, and configures the underlying LLM.
-
-- **Lifecycle Hooks:**  
-  Each agent (via the new `FlockAgent` base class) supports lifecycle hooks such as `initialize()`, `terminate()`, and `on_error()`. This ensures that agents can perform setup, cleanup, and robust error handling—all without cluttering the main business logic.
-
-- **Fault Tolerance & Temporal Integration:**  
-  Flock is built with production readiness in mind. By integrating with Temporal, your agent workflows enjoy automatic retries, durable state management, and resilience against failures. This means that a single agent crash won't bring down your entire system.
-
-- **Type Safety and Clear Contracts:**  
-  Agents are implemented as Pydantic models. This provides automatic JSON serialization/deserialization, strong typing, and an explicit contract for inputs and outputs. Testing, validation, and integration become straightforward.
-
-- **DSPy Integration:**  
-  Flock leverages DSPy for managing LLM interactions. The framework constructs clean signature strings and updates field metadata so that DSPy can include detailed instructions and context for each agent call.
-
-
-<p align="center">
-<img src="docs/img/flock_cli.png" width="200"><br>
-
-## Quick Start
-
-Below is a simple example of how to create and run an agent with Flock:
-
-```python
-import asyncio
-from flock.core.flock import Flock
-from flock.core.agents.flock_agent import FlockAgent
-from flock.core.tools import basic_tools
-
-async def main():
-    # Initialize Flock
-    flock = Flock(model="openai/gpt-4o")
-
-    # Create an agent with clear input/output declarations and optional tools.
-    idea_agent = FlockAgent(
-        name="idea_agent",
-        input="query: str|The search query, context: dict|Additional context",
-        output="a_fun_software_project_idea: str|The generated software project idea",
-        tools=[basic_tools.web_search_tavily],
-    )
-    flock.add_agent(idea_agent)
-
-    # Run the agent locally (with built-in debugging/logging)
-    result = await flock.run_async(
-        start_agent=idea_agent,
-        input="build a revolutionary app",
-        local_debug=True
-    )
-    print(result)
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-## Advanced Usage
-
-### Agents with Lifecycle Hooks
-
-Customize behavior by overriding lifecycle methods:
-
-- **initialize(inputs):** Set up resources, validate inputs, or log pre-run state.
-- **terminate(inputs, result):** Clean up resources, log output, or perform post-run actions.
-- **on_error(error, inputs):** Handle exceptions gracefully, log detailed error information, and trigger recovery logic.
-
-### Agents with Tools
-
-Agents can seamlessly integrate external tools for enhanced functionality:
-
-```python
-from flock.core.tools import basic_tools
-
-research_agent = FlockAgent(
-    name="research_agent",
-    input="research_topic: str|Topic to investigate",
-    output="research_result: str|The outcome of the research",
-    tools=[basic_tools.web_search_tavily],
-)
-```
-
-### Agent Chaining
-
-Chain agents together to create complex workflows:
-
-```python
-# Define the first agent in the chain.
-project_plan_agent = FlockAgent(
-    name="project_plan_agent",
-    input="project_idea: str|Initial project idea",
-    output="plan_headings: list[str]|Headings for the project plan",
-    tools=[basic_tools.web_search_tavily, basic_tools.code_eval],
-)
-
-# Define a second agent that builds on the output of the first.
-content_agent = FlockAgent(
-    name="content_agent",
-    input="context: dict|Global context, project_plan_agent.plan_headings: list[str]|Plan headings",
-    output="project_plan_content: str|Detailed content for the plan",
-)
-
-# Set up hand-off from the first agent to the second.
-project_plan_agent.hand_off = content_agent
-```
-
-### Temporal Workflow Integration
-
-Flock supports execution on Temporal, ensuring robust, fault-tolerant workflows:
-
-- **Durability:** Persistent state management even in the case of failures.
-- **Retries & Error Handling:** Automatic recovery via Temporal's built-in mechanisms.
-- **Scalability:** Seamless orchestration of distributed agent workflows.
-
-## Architecture
-
-TODO: Insert charts
-
-## Requirements
-
-- Python 3.12+
-- (Optional) Temporal server running locally for production-grade workflow features
-- API keys for integrated services
-
-
-recommended services
-```bash
-export OPENAI_API_KEY=sk-proj-
-export TAVILY_API_KEY=tvly-
-```
-
-or in `.env`
-
-For LLM interaction LiteLLM is getting used. Please refer to its documentation on how to easily use other models and/or provider.
-
-https://docs.litellm.ai/docs/providers
-
-## Installation
-
-```bash
-pip install flock-core
-```
-
-if you want to use the integrated tools
-
-```bash
-pip install flock-core[tools]
-```
-
-and for the docling tools
-
-```bash
-pip install flock-core[all-tools]
-```
-
-## Development
-
-
-1. **Clone the Repository:**
-
-   ```bash
-   git clone https://github.com/yourusername/flock.git
-   cd flock
-   ```
-
-2. **Create a Virtual Environment and sync all packages:**
-
-   ```bash
-   uv sync --all-groups --all-extras
-   ```
-
-3. **Install local version of flock:**
-
-   ```bash
-   uv build && uv pip install -e .
-   ```
-
-Install Jaeger for telemetry
-```
-
-docker run -d --name jaeger \
-  -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
-  -p 5775:5775/udp \
-  -p 6831:6831/udp \
-  -p 6832:6832/udp \
-  -p 5778:5778 \
-  -p 16686:16686 \
-  -p 14268:14268 \
-  -p 14250:14250 \
-  -p 9411:9411 \
-  jaegertracing/all-in-one:1.41
-
-
-```
-
-or zipkin
-
-```
-docker run -d -p 9411:9411 openzipkin/zipkin
-
-```
-
-## Contributing
-
-Contributions are welcome! Please submit Pull Requests and open issues on GitHub.
-
-## License
-
-This project is licensed under the terms of the LICENSE file included in the repository.
-
-## Acknowledgments
-
-- Built with [DSPy](https://github.com/stanfordnlp/dspy)
-- Uses [Temporal](https://temporal.io/) for workflow management
-- Integrates with [Tavily](https://tavily.com/) for web search capabilities
-- Web interface built with FastHTML and MonsterUI
-
-## Evolution & Future Direction
-
-Flock was created to overcome the limitations of traditional agent frameworks. Key design goals include:
-
-### Declarative Over Prompt Engineering
-
-- **Simplify Agent Definitions:**  
-  Focus on clear input/output contracts rather than long, complex prompts.
-- **Model Agnostic:**  
-  Change LLM backends without altering agent logic.
-- **Improved Testability:**  
-  Clear, structured interfaces facilitate unit testing and validation.
-
-### Robust, Production-Grade Orchestration
-
-- **Fault Tolerance:**  
-  Leveraging Temporal for automatic retries, durable state, and robust error handling.
-- **Scalability:**  
-  Support for concurrent, batch, and distributed workflows.
-- **Observability:**  
-  Built-in logging and monitoring for real-time insights into workflow execution.
-
-### Future Enhancements
-
-- Expanded type system for richer agent interactions
-- Enhanced tool ecosystem and custom integrations
-- Advanced monitoring, debugging, and performance metrics
-- Extended testing frameworks and validation tools
-
-Join us in building the next generation of reliable, production-ready AI agent systems!
-