flock-core 0.1.1__tar.gz → 0.1.2__tar.gz

{flock_core-0.1.1 → flock_core-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.1.1
+Version: 0.1.2
 Summary: An agent framework for the age of agents
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -25,19 +25,30 @@ Requires-Dist: tavily-python>=0.5.0
 Requires-Dist: temporalio>=1.9.0
 Description-Content-Type: text/markdown
 
-# flock
+# Flock by white duck
 
-white duck flock (engl. Herde/Schwarm) ist ein KI-gestütztes Agentenframework. Agenten sind Applikationen die autark und autonom entscheiden wie sie ein Problem lösen, und je nach konfiguration auch selber entscheiden wie sie untereinander kommunizieren. Ein zusammenschluss mehrerer Agenten ist ein Agentensystem.
-
-Wir dachten da vielleicht als Logo einfach eine Herde/Schwarm an Freds, oder ähnlich wie Huggingface an einen James Bond Fred (vgl. https://huggingface.co/docs/smolagents/en/index) oder natürlich auch gerne eine Herde an James Bond Freds!
-
-
-White Duck Flock (engl. Herde/Schwarm) ist ein KI-gestütztes Agentenframework. Agenten sind Applikationen, die autark und autonom entscheiden, wie sie ein Problem lösen – und je nach Konfiguration auch selbst bestimmen, wie sie untereinander kommunizieren. Ein Zusammenschluss mehrerer Agenten bildet ein Agentensystem.
-
-Als Logo dachten wir vielleicht an eine Herde/Schwarm von Freds – oder, ähnlich wie Hugging Face, an einen James-Bond-Fred (vgl. https://huggingface.co/docs/smolagents/en/index). Alternativ natürlich auch gerne eine ganze Herde an James-Bond-Freds!
+### Declarative LLM Orchestration at Scale
 
+<img src="docs/img/image.png" width="600">
 
+| Traditional Agent Frameworks 🙃          |                        Flock 🐤🐧🐓 🦆                         |
+|-----------------------------------------|------------------------------------------------|
+| 🤖 **Interaction Design**                | 📝 **Simplified Agent Logic**                   |
+| • Requires complex prompt tuning        | • Straightforward input/output definitions      |
+| • Fragile and hard-to-maintain          | • No need for prompt engineering               |
+| • Time-consuming adjustments            | • Focused on business logic                    |
+|                                           |                                                |
+| 💥 **Reliability Challenges**             | ⚡ **Robust & Scalable**                        |
+| • Prone to single points of failure      | • Built-in fault tolerance                     |
+| • Lacks automatic recovery               | • Automated retries & error handling           |
+| • Difficult to monitor                   | • Full observability & logging                 |
+|                                           |                                                |
+| 🏗️ **Execution Constraints**              | 🔄 **Flexible Orchestration**                   |
+| • Linear workflows, limited adaptability | • Dynamic and modular execution                |
+| • Lacks parallelism & batching           | • Supports concurrency & batch processing      |
+| • Struggles with scaling                 | • Persistent state management                  |
 
+## Hello, Bot
 
 ```python
 MODEL = "openai/gpt-4o"
@@ -45,29 +56,26 @@ MODEL = "openai/gpt-4o"
 async def main():
  
     #--------------------------------
-    # Create the flock and context
+    # Create the flock
     #--------------------------------
     # The flock is the place where all the agents are at home
-    # The context is everything that happened in the flock
-    flock, context = Flock.create()
+    flock = Flock(model=MODEL)
 
     #--------------------------------
     # Create an agent
     #--------------------------------
-    # The Flock doesn't believe in prompts (see the readme for more info)
-    # The Flock just declares what agents get in and what agents produce
+    # The flock doesn't believe in prompts (continue reading for more info)
+    # The flock just declares what agents get in and what agents produce
     # bloggy takes in a blog_idea and outputs a funny_blog_title and blog_headers
-    bloggy = DeclarativeAgent(
+    bloggy = Flock(
+        DeclarativeAgent,
         name="bloggy",
         input="blog_idea",
-        output="funny_blog_title, blog_headers",
-        model=MODEL
+        output="funny_blog_title, blog_headers"  
     )
-    # Let's add bloggy to the flock
-    flock.add_agent(bloggy)
 
     #--------------------------------
-    # Run the flock
+    # Let the flock do its thing
     #--------------------------------
     # By giving the flock a start_agent and an input, we can run the flock
     # local_debug makes it easier to debug the flock
@@ -80,6 +88,9 @@ async def main():
     # earn the fruits of the flock's labor
     print(result)
 
+
+    # Continue reading to give your flock temporal(ly) super powers, heh.
+
 ```
 
 Problems with other agent frameworks
@@ -88,7 +99,7 @@ Problems with other agent frameworks
 - One crash and your whole agent system is dead
 - Demand having your system be a real DAG and a real state machine
 
-How Flock tries to solve it:
+How flock tries to solve it:
 
 - Just declare what your agents get ind, and what they should return
 - First grade temporalio support. Retry, Error, Timeout etc etc are somethi
@@ -107,6 +118,7 @@ How does a good prompt look like? What happens with your prompt if you switch mo
 With flock you just tell an agent what kind of input it gets, and what it should output. Done. Easy peasy.
 
 The philosophy behind this approach is simple: by focusing on the interface (inputs and outputs) rather than implementation details (prompts), we create more maintainable and adaptable systems. This declarative approach means:
+
 - Your agents are model-agnostic
 - Behavior can be tested and validated objectively
 - Changes are localized and predictable
@@ -115,9 +127,10 @@ The philosophy behind this approach is simple: by focusing on the interface (inp
 ### Testable
 
 Reducing the need for fuzzy natural language to a minimum agents become easily testable, evaluable.
-Flock comes with tools to know exactly how good your agents and therefore the agent system is performing.
+flock comes with tools to know exactly how good your agents and therefore the agent system is performing.
 
 This focus on testability isn't just about catching bugs - it's about building confidence in your AI systems:
+
 - Clear input/output contracts make unit testing straightforward
 - Type safety ensures data consistency
 - Performance metrics are built into the framework
@@ -127,9 +140,10 @@ This focus on testability isn't just about catching bugs - it's about building c
 
 Would you run your agent system in critical environments? The answer is probably no, since with most frameworks one dead endpoint or uncatched exception will break the whole agent system.
 
-Flock uses Temporal as its workflow engine which comes with battle-hardened retry, failure, exception options.
+flock uses Temporal as its workflow engine which comes with battle-hardened retry, failure, exception options.
 
 This production-readiness is achieved through several key design decisions:
+
 - Temporal workflow engine for durability and reliability
 - Strong typing for predictable behavior
 - Modular architecture for maintainability
@@ -146,20 +160,19 @@ This production-readiness is achieved through several key design decisions:
 
 ## Architecture and Flow
 
-![alt text](docs/img/charts/agent_workflow_inv.png) 
+![alt text](docs/img/charts/agent_workflow_inv.png)
 
-
-![alt text](docs/img/charts/core_architecture_inv.png) 
+![alt text](docs/img/charts/core_architecture_inv.png)
 
 ## Requirements
 
 Nothing. Temporal is not needed for development but recommended
 
-Either clone https://github.com/temporalio/docker-compose and up the compose
+Either clone <https://github.com/temporalio/docker-compose> and up the compose
 
 or install the temporal cli
 
-https://docs.temporal.io/cli
+<https://docs.temporal.io/cli>
 
 ## Installation
 
@@ -174,11 +187,11 @@ Here's a simple example of creating and using an agent:
 ```python
 import asyncio
 from flock.core.agents.declarative_agent import DeclarativeAgent
-from flock.core.flock import Flock
+from flock.core.flock import flock
 
 async def main():
-    # Initialize Flock
-    agent_runner = Flock()
+    # Initialize flock
+    agent_runner = flock()
 
     # Create a simple agent
     agent = DeclarativeAgent(
@@ -204,7 +217,7 @@ if __name__ == "__main__":
 
 ![alt text](docs/img/app.png)
 
-Flock comes with a built-in web interface for managing and monitoring your agents. The web app provides a rich, interactive environment for working with your agent systems.
+flock comes with a built-in web interface for managing and monitoring your agents. The web app provides a rich, interactive environment for working with your agent systems.
 
 TODO: Expand
 
@@ -220,7 +233,7 @@ uv run flock
 ### Features
 
 - **Dashboard**: Overview of your agent systems and their status
-- **Agent Management**: 
+- **Agent Management**:
   - List and filter agents
   - View agent details and configuration
   - Monitor production readiness
@@ -234,6 +247,7 @@ uv run flock
 ### Technical Details
 
 The web application is built with:
+
 - FastHTML for UI components
 - MonsterUI for enhanced UI elements
 - Interactive features using D3.js and interact.js
@@ -321,9 +335,10 @@ project_plan_agent.hand_off = content_agent
 
 ## Core Components
 
-### Flock Class
+### flock Class
 
 The main orchestrator that manages agent creation and execution:
+
 - Handles agent registration
 - Manages workflow execution
 - Supports both local debugging and distributed execution
@@ -331,6 +346,7 @@ The main orchestrator that manages agent creation and execution:
 ### DeclarativeAgent
 
 Base class for creating agents with:
+
 - Input/output specifications
 - Tool integration
 - Type validation
@@ -339,6 +355,7 @@ Base class for creating agents with:
 ### Workflow System
 
 Built on Temporal for:
+
 - Durable execution
 - State management
 - Error handling
@@ -347,6 +364,7 @@ Built on Temporal for:
 ### Tools
 
 Built-in tools include:
+
 - Web search (via Tavily)
 - Math evaluation
 - Code execution
@@ -355,14 +373,14 @@ Built-in tools include:
 ## Architecture
 
 ```
-Flock Framework
+flock Framework
 ├── Core
 │   ├── Agents
 │   │   ├── DeclarativeAgent
 │   │   └── Agent Registry
 │   ├── Tools
 │   │   └── Basic Tools
-│   └── Flock Manager
+│   └── flock Manager
 ├── Workflow
 │   ├── Activities
 │   ├── Temporal Setup
@@ -382,18 +400,21 @@ Flock Framework
 ### Setup
 
 1. Clone the repository:
+
 ```bash
 git clone https://github.com/yourusername/flock.git
 cd flock
 ```
 
 2. Create a virtual environment:
+
 ```bash
 python -m venv .venv
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
 3. Install dependencies:
+
 ```bash
 pip install -e .
 ```
@@ -421,17 +442,21 @@ This project is licensed under the terms of the LICENSE file included in the rep
 
 ## Evolution & Future Direction
 
-Flock was born from the realization that current agent frameworks often prioritize flexibility at the cost of reliability and maintainability. The framework's design decisions reflect this focus:
+flock was born from the realization that current agent frameworks often prioritize flexibility at the cost of reliability and maintainability. The framework's design decisions reflect this focus:
 
 ### Why Declarative?
+
 The declarative approach wasn't just a stylistic choice - it was a deliberate decision to separate what agents do from how they do it. This separation means:
+
 - Agents can be optimized independently of their interface
 - Different LLM backends can be swapped without changing agent definitions
 - Testing and validation become straightforward
 - Integration with existing systems is simplified
 
 ### Why Temporal?
+
 Using Temporal as the workflow engine was crucial for production reliability:
+
 - Automatic retry on failures
 - Built-in state management
 - Scalable execution
@@ -439,7 +464,9 @@ Using Temporal as the workflow engine was crucial for production reliability:
 - Production-grade monitoring
 
 ### Future Plans
+
 The framework is actively evolving with several key areas of focus:
+
 - Enhanced type system for more complex agent interactions
 - Expanded tool ecosystem
 - Improved optimization capabilities

{flock_core-0.1.1 → flock_core-0.1.2}/README.md

@@ -1,16 +1,27 @@
-# flock
-
-white duck flock (engl. Herde/Schwarm) ist ein KI-gestütztes Agentenframework. Agenten sind Applikationen die autark und autonom entscheiden wie sie ein Problem lösen, und je nach konfiguration auch selber entscheiden wie sie untereinander kommunizieren. Ein zusammenschluss mehrerer Agenten ist ein Agentensystem.
-
-Wir dachten da vielleicht als Logo einfach eine Herde/Schwarm an Freds, oder ähnlich wie Huggingface an einen James Bond Fred (vgl. https://huggingface.co/docs/smolagents/en/index) oder natürlich auch gerne eine Herde an James Bond Freds!
-
-
-White Duck Flock (engl. Herde/Schwarm) ist ein KI-gestütztes Agentenframework. Agenten sind Applikationen, die autark und autonom entscheiden, wie sie ein Problem lösen – und je nach Konfiguration auch selbst bestimmen, wie sie untereinander kommunizieren. Ein Zusammenschluss mehrerer Agenten bildet ein Agentensystem.
-
-Als Logo dachten wir vielleicht an eine Herde/Schwarm von Freds – oder, ähnlich wie Hugging Face, an einen James-Bond-Fred (vgl. https://huggingface.co/docs/smolagents/en/index). Alternativ natürlich auch gerne eine ganze Herde an James-Bond-Freds!
-
-
-
+# Flock by white duck
+
+### Declarative LLM Orchestration at Scale
+
+<img src="docs/img/image.png" width="600">
+
+| Traditional Agent Frameworks 🙃          |                        Flock 🐤🐧🐓 🦆                         |
+|-----------------------------------------|------------------------------------------------|
+| 🤖 **Interaction Design**                | 📝 **Simplified Agent Logic**                   |
+| • Requires complex prompt tuning        | • Straightforward input/output definitions      |
+| • Fragile and hard-to-maintain          | • No need for prompt engineering               |
+| • Time-consuming adjustments            | • Focused on business logic                    |
+|                                           |                                                |
+| 💥 **Reliability Challenges**             | ⚡ **Robust & Scalable**                        |
+| • Prone to single points of failure      | • Built-in fault tolerance                     |
+| • Lacks automatic recovery               | • Automated retries & error handling           |
+| • Difficult to monitor                   | • Full observability & logging                 |
+|                                           |                                                |
+| 🏗️ **Execution Constraints**              | 🔄 **Flexible Orchestration**                   |
+| • Linear workflows, limited adaptability | • Dynamic and modular execution                |
+| • Lacks parallelism & batching           | • Supports concurrency & batch processing      |
+| • Struggles with scaling                 | • Persistent state management                  |
+
+## Hello, Bot
 
 ```python
 MODEL = "openai/gpt-4o"
@@ -18,29 +29,26 @@ MODEL = "openai/gpt-4o"
 async def main():
  
     #--------------------------------
-    # Create the flock and context
+    # Create the flock
     #--------------------------------
     # The flock is the place where all the agents are at home
-    # The context is everything that happened in the flock
-    flock, context = Flock.create()
+    flock = Flock(model=MODEL)
 
     #--------------------------------
     # Create an agent
     #--------------------------------
-    # The Flock doesn't believe in prompts (see the readme for more info)
-    # The Flock just declares what agents get in and what agents produce
+    # The flock doesn't believe in prompts (continue reading for more info)
+    # The flock just declares what agents get in and what agents produce
     # bloggy takes in a blog_idea and outputs a funny_blog_title and blog_headers
-    bloggy = DeclarativeAgent(
+    bloggy = Flock(
+        DeclarativeAgent,
         name="bloggy",
         input="blog_idea",
-        output="funny_blog_title, blog_headers",
-        model=MODEL
+        output="funny_blog_title, blog_headers"  
     )
-    # Let's add bloggy to the flock
-    flock.add_agent(bloggy)
 
     #--------------------------------
-    # Run the flock
+    # Let the flock do its thing
     #--------------------------------
     # By giving the flock a start_agent and an input, we can run the flock
     # local_debug makes it easier to debug the flock
@@ -53,6 +61,9 @@ async def main():
     # earn the fruits of the flock's labor
     print(result)
 
+
+    # Continue reading to give your flock temporal(ly) super powers, heh.
+
 ```
 
 Problems with other agent frameworks
@@ -61,7 +72,7 @@ Problems with other agent frameworks
 - One crash and your whole agent system is dead
 - Demand having your system be a real DAG and a real state machine
 
-How Flock tries to solve it:
+How flock tries to solve it:
 
 - Just declare what your agents get ind, and what they should return
 - First grade temporalio support. Retry, Error, Timeout etc etc are somethi
@@ -80,6 +91,7 @@ How does a good prompt look like? What happens with your prompt if you switch mo
 With flock you just tell an agent what kind of input it gets, and what it should output. Done. Easy peasy.
 
 The philosophy behind this approach is simple: by focusing on the interface (inputs and outputs) rather than implementation details (prompts), we create more maintainable and adaptable systems. This declarative approach means:
+
 - Your agents are model-agnostic
 - Behavior can be tested and validated objectively
 - Changes are localized and predictable
@@ -88,9 +100,10 @@ The philosophy behind this approach is simple: by focusing on the interface (inp
 ### Testable
 
 Reducing the need for fuzzy natural language to a minimum agents become easily testable, evaluable.
-Flock comes with tools to know exactly how good your agents and therefore the agent system is performing.
+flock comes with tools to know exactly how good your agents and therefore the agent system is performing.
 
 This focus on testability isn't just about catching bugs - it's about building confidence in your AI systems:
+
 - Clear input/output contracts make unit testing straightforward
 - Type safety ensures data consistency
 - Performance metrics are built into the framework
@@ -100,9 +113,10 @@ This focus on testability isn't just about catching bugs - it's about building c
 
 Would you run your agent system in critical environments? The answer is probably no, since with most frameworks one dead endpoint or uncatched exception will break the whole agent system.
 
-Flock uses Temporal as its workflow engine which comes with battle-hardened retry, failure, exception options.
+flock uses Temporal as its workflow engine which comes with battle-hardened retry, failure, exception options.
 
 This production-readiness is achieved through several key design decisions:
+
 - Temporal workflow engine for durability and reliability
 - Strong typing for predictable behavior
 - Modular architecture for maintainability
@@ -119,20 +133,19 @@ This production-readiness is achieved through several key design decisions:
 
 ## Architecture and Flow
 
-![alt text](docs/img/charts/agent_workflow_inv.png) 
-
+![alt text](docs/img/charts/agent_workflow_inv.png)
 
-![alt text](docs/img/charts/core_architecture_inv.png) 
+![alt text](docs/img/charts/core_architecture_inv.png)
 
 ## Requirements
 
 Nothing. Temporal is not needed for development but recommended
 
-Either clone https://github.com/temporalio/docker-compose and up the compose
+Either clone <https://github.com/temporalio/docker-compose> and up the compose
 
 or install the temporal cli
 
-https://docs.temporal.io/cli
+<https://docs.temporal.io/cli>
 
 ## Installation
 
@@ -147,11 +160,11 @@ Here's a simple example of creating and using an agent:
 ```python
 import asyncio
 from flock.core.agents.declarative_agent import DeclarativeAgent
-from flock.core.flock import Flock
+from flock.core.flock import flock
 
 async def main():
-    # Initialize Flock
-    agent_runner = Flock()
+    # Initialize flock
+    agent_runner = flock()
 
     # Create a simple agent
     agent = DeclarativeAgent(
@@ -177,7 +190,7 @@ if __name__ == "__main__":
 
 ![alt text](docs/img/app.png)
 
-Flock comes with a built-in web interface for managing and monitoring your agents. The web app provides a rich, interactive environment for working with your agent systems.
+flock comes with a built-in web interface for managing and monitoring your agents. The web app provides a rich, interactive environment for working with your agent systems.
 
 TODO: Expand
 
@@ -193,7 +206,7 @@ uv run flock
 ### Features
 
 - **Dashboard**: Overview of your agent systems and their status
-- **Agent Management**: 
+- **Agent Management**:
   - List and filter agents
   - View agent details and configuration
   - Monitor production readiness
@@ -207,6 +220,7 @@ uv run flock
 ### Technical Details
 
 The web application is built with:
+
 - FastHTML for UI components
 - MonsterUI for enhanced UI elements
 - Interactive features using D3.js and interact.js
@@ -294,9 +308,10 @@ project_plan_agent.hand_off = content_agent
 
 ## Core Components
 
-### Flock Class
+### flock Class
 
 The main orchestrator that manages agent creation and execution:
+
 - Handles agent registration
 - Manages workflow execution
 - Supports both local debugging and distributed execution
@@ -304,6 +319,7 @@ The main orchestrator that manages agent creation and execution:
 ### DeclarativeAgent
 
 Base class for creating agents with:
+
 - Input/output specifications
 - Tool integration
 - Type validation
@@ -312,6 +328,7 @@ Base class for creating agents with:
 ### Workflow System
 
 Built on Temporal for:
+
 - Durable execution
 - State management
 - Error handling
@@ -320,6 +337,7 @@ Built on Temporal for:
 ### Tools
 
 Built-in tools include:
+
 - Web search (via Tavily)
 - Math evaluation
 - Code execution
@@ -328,14 +346,14 @@ Built-in tools include:
 ## Architecture
 
 ```
-Flock Framework
+flock Framework
 ├── Core
 │   ├── Agents
 │   │   ├── DeclarativeAgent
 │   │   └── Agent Registry
 │   ├── Tools
 │   │   └── Basic Tools
-│   └── Flock Manager
+│   └── flock Manager
 ├── Workflow
 │   ├── Activities
 │   ├── Temporal Setup
@@ -355,18 +373,21 @@ Flock Framework
 ### Setup
 
 1. Clone the repository:
+
 ```bash
 git clone https://github.com/yourusername/flock.git
 cd flock
 ```
 
 2. Create a virtual environment:
+
 ```bash
 python -m venv .venv
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 ```
 
 3. Install dependencies:
+
 ```bash
 pip install -e .
 ```
@@ -394,17 +415,21 @@ This project is licensed under the terms of the LICENSE file included in the rep
 
 ## Evolution & Future Direction
 
-Flock was born from the realization that current agent frameworks often prioritize flexibility at the cost of reliability and maintainability. The framework's design decisions reflect this focus:
+flock was born from the realization that current agent frameworks often prioritize flexibility at the cost of reliability and maintainability. The framework's design decisions reflect this focus:
 
 ### Why Declarative?
+
 The declarative approach wasn't just a stylistic choice - it was a deliberate decision to separate what agents do from how they do it. This separation means:
+
 - Agents can be optimized independently of their interface
 - Different LLM backends can be swapped without changing agent definitions
 - Testing and validation become straightforward
 - Integration with existing systems is simplified
 
 ### Why Temporal?
+
 Using Temporal as the workflow engine was crucial for production reliability:
+
 - Automatic retry on failures
 - Built-in state management
 - Scalable execution
@@ -412,7 +437,9 @@ Using Temporal as the workflow engine was crucial for production reliability:
 - Production-grade monitoring
 
 ### Future Plans
+
 The framework is actively evolving with several key areas of focus:
+
 - Enhanced type system for more complex agent interactions
 - Expanded tool ecosystem
 - Improved optimization capabilities

{flock_core-0.1.1 → flock_core-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.1.1"
+version = "0.1.2"
 description = "An agent framework for the age of agents"
 readme = "README.md"
 authors = [