flock-core 0.4.527__tar.gz → 0.5.0b0__tar.gz

{flock_core-0.4.527 → flock_core-0.5.0b0}/.github/workflows/deploy-whiteduck-pypi.yml

@@ -6,6 +6,7 @@ on:
   push:
     branches:
       - main # Replace with your default branch
+      - 0.5.0b
     paths:
       - 'pyproject.toml'  # Only trigger on changes to pyproject.toml (version number)
 

flock_core-0.5.0b0/AGENT.md

@@ -0,0 +1,351 @@
+# AGENT.md - Flock Framework Onboarding Guide
+
+## Project Overview
+
+**Flock** is a declarative AI agent orchestration framework built by white duck GmbH. It solves common LLM development pain points by providing:
+
+- **Declarative Contracts**: Define inputs/outputs with Pydantic models instead of brittle prompts
+- **Built-in Resilience**: Automatic retries, state persistence via Temporal.io
+- **Production-Ready**: Deploy as REST APIs, scale without rewriting
+- **Actually Testable**: Clear contracts make agents unit-testable
+- **Dynamic Workflows**: Self-correcting loops, conditional routing
+- **Unified Architecture**: Simplified from 4 concepts to 2 (Agent + Components)
+
+**Key Differentiator**: You define what goes in and what should come out - the framework handles the "how" with LLMs.
+
+**Recent Architecture Update**: Flock has been refactored to use a unified component system that simplifies the mental model from "Agent + Evaluator + Router + Modules" to just "Agent + Components". Legacy components have been completely removed.
+
+## Project Structure
+
+```
+flock/
+├── src/flock/
+│   ├── core/                   # Framework foundation
+│   │   ├── flock.py           # Main orchestrator class
+│   │   ├── flock_agent.py     # Base agent class (~500 lines)
+│   │   ├── registry/          # Thread-safe component discovery & registration
+│   │   ├── context/           # State management
+│   │   ├── execution/         # Local & Temporal executors
+│   │   ├── serialization/     # Save/load functionality
+│   │   └── mcp/              # Model Context Protocol integration
+│   ├── components/            # Unified agent components (evaluation, routing, utility)
+│   ├── tools/                 # Utility functions
+│   ├── webapp/                # FastAPI web interface
+│   └── workflow/              # Temporal.io activities
+├── tests/                     # Comprehensive test suite
+│   ├── components/            # Tests for unified components
+│   ├── core/                  # Core framework tests
+│   └── integration/           # Integration tests
+├── examples/                  # Usage examples and showcases
+└── docs/                      # Documentation
+```
+
+## Key Components & Architecture
+
+### Core Classes
+
+1. **`Flock`** (`src/flock/core/flock.py`)
+   - Main orchestrator, manages agents and execution
+   - Handles both local and Temporal.io execution
+   - Entry point for most operations
+
+2. **`FlockAgent`** (`src/flock/core/flock_agent.py`)
+   - Base class for all agents (refactored from 1000+ to ~500 lines)
+   - Lifecycle hooks: initialize → evaluate → terminate
+   - **Unified Architecture**: Uses single `components` list instead of separate evaluator/router/modules
+   - **Workflow State**: `next_agent` property for explicit workflow control
+   - Composition-based architecture with focused components
+
+3. **`RegistryHub`** (`src/flock/core/registry/`)
+   - Thread-safe registry system using composition pattern
+   - Manages agents, callables, types, servers with specialized helpers
+   - Auto-registration capabilities with component discovery
+
+4. **`FlockContext`** (`src/flock/core/context/context.py`)
+   - State management between agent executions
+   - History tracking, variable storage
+
+### Unified Component Architecture
+
+**Mental Model**: Agent + Components (2 concepts instead of 4)
+
+**Component Types** (all follow `*ComponentBase` naming convention):
+- **EvaluationComponentBase**: Core LLM evaluation logic
+- **RoutingComponentBase**: Workflow routing decisions (sets `next_agent`)
+- **UtilityComponentBase**: Cross-cutting concerns (metrics, output, memory)
+
+**Key Properties**:
+- `agent.components`: List of all components
+- `agent.evaluator`: Primary evaluation component (delegates to helper)
+- `agent.router`: Primary routing component (delegates to helper)
+- `agent.next_agent`: Next agent in workflow (string, callable, or None)
+- `agent._components`: Component management helper (lazy-loaded)
+
+### Execution Flow
+
+```
+Flock.run() → FlockAgent.run_async() → Components.evaluate() → Router.set_next_agent() → Next Agent
+```
+
+**Workflow Steps**:
+1. Agent initializes and runs evaluation components
+2. Routing components analyze results and set `agent.next_agent`
+3. Utility components handle cross-cutting concerns
+4. Orchestrator uses `agent.next_agent` to continue workflow
+
+## Development Workflow
+
+### Essential Commands
+
+```bash
+# Project uses UV as package manager
+uv run python -m pytest tests/core/test_flock_core.py -v    # Run core tests
+uv run python -m pytest tests/serialization/ -v            # Test serialization
+uv run python -m pytest tests/components/ -v -k memory      # Test specific components
+
+# Common development tasks
+uv run python examples/01-getting-started/quickstart.py     # Run basic example
+uv run python -c "from flock.core import Flock; print('OK')" # Quick import test
+```
+
+### Testing Strategy
+
+- **Unit Tests**: `tests/core/` for framework components
+- **Component Tests**: `tests/components/` for unified component architecture
+- **Integration Tests**: `tests/integration/` for external dependencies  
+- **Serialization Tests**: `tests/serialization/` for save/load
+
+**Important**: Many tests currently have issues unrelated to core functionality (logging conflicts, registry state). Focus on functionality tests.
+
+## Known Issues & Gotchas
+
+### Current Problems
+1. **Logging conflicts**: `exc_info` parameter duplication causing test failures
+2. **Test brittleness**: Some tests depend on external services or configuration
+
+### Code Quality Issues Found
+- Bare `except:` handlers in multiple files
+- Global state management patterns
+- Some circular import dependencies
+- Complex function complexity (Ruff warnings)
+
+## Important Patterns & Conventions
+
+### Component Registration
+```python
+from flock.core.registry import flock_component
+from flock.core.component.evaluation_component_base import EvaluationComponentBase
+
+@flock_component(config_class=MyComponentConfig)
+class MyComponent(EvaluationComponentBase):
+    # Component implementation
+```
+
+### Agent Creation
+```python
+from flock.core import Flock, FlockFactory
+
+flock = Flock(model="openai/gpt-4o")
+agent = FlockFactory.create_default_agent(
+    name="my_agent",
+    input="query: str",
+    output="result: str"
+)
+flock.add_agent(agent)
+result = flock.run(start_agent="my_agent", input={"query": "test"})
+```
+
+### Manual Component Assembly
+```python
+from flock.core import FlockAgent
+from flock.core.agent.flock_agent_components import FlockAgentComponents
+from flock.components.evaluation.declarative_evaluation_component import (
+    DeclarativeEvaluationComponent, DeclarativeEvaluationConfig
+)
+from flock.components.utility.output_utility_component import (
+    OutputUtilityComponent, OutputUtilityConfig
+)
+from flock.components.routing.default_routing_component import (
+    DefaultRoutingComponent, DefaultRoutingConfig
+)
+
+# Create agent with unified components
+agent = FlockAgent(
+    name="my_agent",
+    input="query: str",
+    output="result: str",
+    components=[
+        DeclarativeEvaluationComponent(name="evaluator", config=DeclarativeEvaluationConfig()),
+        OutputUtilityComponent(name="output", config=OutputUtilityConfig()),
+        DefaultRoutingComponent(name="router", config=DefaultRoutingConfig(hand_off="next_agent"))
+    ]
+)
+
+# Use helper for component management
+helper = agent._components  # Lazy-loaded property
+print(f"Evaluation components: {len(helper.get_evaluation_components())}")
+print(f"Primary evaluator: {helper.get_primary_evaluator()}")
+
+# Basic operations delegate to helper
+agent.add_component(my_component)  # Delegates to helper
+agent.get_component("component_name")  # Delegates to helper
+
+# Alternative: Set next_agent directly
+agent.next_agent = "next_agent_name"
+```
+
+### Component Management Helper
+
+The `FlockAgentComponents` class provides convenient methods for managing components:
+
+```python
+# Access helper through agent property (lazy-loaded)
+helper = agent._components
+
+# Component management
+helper.add_component(my_component)
+helper.remove_component("component_name")
+component = helper.get_component("component_name")
+
+# Type-specific getters
+evaluation_components = helper.get_evaluation_components()
+routing_components = helper.get_routing_components()
+utility_components = helper.get_utility_components()
+
+# Convenience methods
+primary_evaluator = helper.get_primary_evaluator()
+primary_router = helper.get_primary_router()
+enabled_components = helper.get_enabled_components()
+
+# Basic operations delegate to helper automatically
+agent.add_component(my_component)  # Same as helper.add_component()
+agent.evaluator  # Same as helper.get_primary_evaluator()
+agent.router     # Same as helper.get_primary_router()
+```
+
+### Serialization
+- All core classes inherit from `Serializable`
+- Support JSON, YAML, and Python dict formats
+- Use `to_dict()` / `from_dict()` for persistence
+
+## Development Guidelines
+
+### When Making Changes
+1. **Always run diagnostics**: Use `get_diagnostics` tool on modified files
+2. **Test serialization**: Many components need to serialize/deserialize correctly
+3. **Check imports**: Circular imports are a known issue
+4. **Memory management**: Be careful with global state (registry, context)
+
+### Code Style
+- Use Pydantic for all data models
+- Prefer `async`/`await` for I/O operations
+- Type hints are mandatory
+- Error handling should be specific (avoid bare `except`)
+
+### Testing
+- Mock external dependencies (LLM calls, file systems)
+- Use fixtures for complex setup
+- Test both success and failure paths
+- Verify serialization roundtrips
+
+## Quick Start for Development
+
+1. **Understand the flow**: `Flock` → `FlockAgent` → `Utility/Evaluator/Router` → Result
+2. **Start with examples**: Check `examples/01-getting-started/`
+3. **Read tests**: `tests/core/test_flock_core.py` shows usage patterns
+4. **Use the factory**: `FlockFactory.create_default_agent()` for quick setup
+5. **Focus on contracts**: Input/output signatures are key
+
+## Workflow Management
+
+### Setting Next Agent
+
+You can control workflow flow in three ways:
+
+1. **Direct assignment**: `agent.next_agent = "agent_name"`
+2. **Callable**: `agent.next_agent = lambda context, result: "dynamic_agent"`
+3. **Routing component**: Add a routing component that sets `next_agent` based on evaluation results
+
+### Routing Components
+
+Routing components implement workflow logic:
+
+```python
+from flock.components.routing.default_routing_component import DefaultRoutingComponent, DefaultRoutingConfig
+from flock.components.routing.conditional_routing_component import ConditionalRoutingComponent, ConditionalRoutingConfig
+from flock.components.routing.llm_routing_component import LLMRoutingComponent, LLMRoutingConfig
+
+# Simple static routing
+router = DefaultRoutingComponent(
+    name="router",
+    config=DefaultRoutingConfig(hand_off="next_agent")
+)
+
+# Conditional routing based on results
+router = ConditionalRoutingComponent(
+    name="conditional_router", 
+    config=ConditionalRoutingConfig(
+        condition=lambda result: result.get("confidence", 0) > 0.8,
+        true_agent="high_confidence_agent",
+        false_agent="low_confidence_agent"
+    )
+)
+
+# AI-powered routing decisions
+router = LLMRoutingComponent(
+    name="llm_router",
+    config=LLMRoutingConfig(
+        available_agents=["agent_a", "agent_b", "agent_c"],
+        routing_prompt="Choose the best next agent based on the result"
+    )
+)
+```
+
+## Web Interface
+
+The framework includes a FastAPI web application at `src/flock/webapp/` with:
+- Agent execution interface
+- Configuration management
+- File upload/download
+- Real-time execution monitoring
+
+Start with: `flock.serve()` method on any Flock instance.
+
+## External Dependencies
+
+- **DSPy**: LLM interaction and prompt management
+- **Temporal.io**: Workflow orchestration and resilience
+- **FastAPI**: Web interface
+- **Pydantic**: Data validation and serialization
+- **OpenTelemetry**: Observability and tracing
+
+## Next Priority Areas
+
+Based on the review, focus on:
+1. **Fixing logging conflicts** in test suite
+2. **Improving error handling** patterns  
+3. **Adding security guidelines** for component development
+4. **Performance optimization** for component operations
+
+## Migration Notes
+
+The unified architecture completely replaces the legacy system:
+- Legacy evaluators, modules, and routers have been removed
+- All legacy dependencies cleaned up from codebase  
+- FlockFactory creates agents with new unified components
+- Workflow execution uses `agent.next_agent` for routing
+- HandOffRequest system replaced with direct property assignment
+
+**Key Benefits of New Architecture**:
+- Simpler mental model (2 concepts vs 4)
+- Explicit workflow state management via `agent.next_agent`
+- Clean composition over complex inheritance
+- Easier testing and debugging
+- Unified component registration and discovery
+- Consistent `*ComponentBase` naming convention
+- Full composition pattern with `_components`, `_execution`, `_integration`, `_serialization`, `_lifecycle`
+- Lazy-loaded component helper with rich functionality
+- Thread-safe registry system with specialized helpers
+- Zero code duplication in registry operations
+
+This should give you a solid foundation to understand and contribute to the Flock framework efficiently!

{flock_core-0.4.527 → flock_core-0.5.0b0}/CONTRIBUTING.md

@@ -40,7 +40,7 @@ We follow the [Contributor Covenant](https://www.contributor-covenant.org/) code
 
 <!-- TOC --><a name="-reporting-issues"></a>
 ## ❗ Reporting Issues:
-- Before submitting a new issue, pleas check [existing issues](https://github.com/whiteducksoftware/flock/issues) if it has already been reported.
+- Before submitting a new issue, please check [existing issues](https://github.com/whiteducksoftware/flock/issues) if it has already been reported.
 - To submit a new issue, please use the provided **Issue Templates** and provide a clear and descriptive title along with a detailed description of the problem or feature request, including steps to reproduce if it's a bug.
 
 <!-- TOC --><a name="-pull-requests"></a>
@@ -104,15 +104,15 @@ We follow the [Contributor Covenant](https://www.contributor-covenant.org/) code
 <!-- TOC --><a name="a-few-best-practices-for-writing-good-documentation"></a>
 ### A few best practices for writing good documentation:
 1. Document the **Why**, not just the how:
-    - Documentation should explain the rational behind your decisions, rather than just describing the "how".
-    - This helps other developers understand the context and reasoning for the implementation, making the code more maintainable and modifyiable.
+    - Documentation should explain the rationale behind your decisions, rather than just describing the "how".
+    - This helps other developers understand the context and reasoning for the implementation, making the code more maintainable and modifiable.
 2. Keep it Up to Date:
    - Your documentation should evolve alongside the code. If you change the behavior of an existing component of Flock, please also take care to make sure the documentation reflects this fact.
 3. Write for the Reader:
    - Consider the audience for your documentation.
    - It should be accessible and understandable for developers who are not intimately familiar with the code.
 4. Document Intent and Design:
-   - Refering to Point 1, Document your decisions of **why** you chose to implement a new component or code change the way you did, if it is not immediately obvious.
+   - Referring to Point 1, Document your decisions of **why** you chose to implement a new component or code change the way you did, if it is not immediately obvious.
 5. Code as Documentation:
    - Well-written code can serve as it's own documentation.
    - Code should be clear, expressive and self-explanatory where possible.
@@ -120,19 +120,19 @@ We follow the [Contributor Covenant](https://www.contributor-covenant.org/) code
 6. Provide Examples:
    - Examples can help other developers understand your changes and are therefore encouraged.
 7. Use Comments Wisely:
-   - Aviod redundant comments that merely restate what the code does, which can clutter the codebase and detract from its readability.
+   - Avoid redundant comments that merely restate what the code does, which can clutter the codebase and detract from its readability.
 8. Be Pragmatic:
    - There is no need for you to excessively comment every line of code you provide.
    - Add documentation where necessary and focus on keeping documentation on a high level.
 
 <!-- TOC --><a name="-testing-and-reliability"></a>
 ## 🔭 Testing and Reliability:
-Flock aims to provide a easy and reliable way to implement agentic applications. Therefore, well tested code is crucial.
+Flock aims to provide an easy and reliable way to implement agentic applications. Therefore, well tested code is crucial.
 
 - Test your changes thoroughly! Ensure that existing tests pass and add **new tests** for any new functionality.
 - Follow Flock's testing conventions and use the provided testing framework.
 - Run the tests before submitting your pull request to confirm that nothing is broken.
-- Test can be run locally with `pytest -q`
+- Tests can be run locally with `pytest -q`
 - Place new tests in `tests/` mirroring the package path.
 - Use [`pytest`](https://docs.pytest.org/en/stable/) fixtures instead of duplicating setup code.
 - For Temporal code, rely on the *Temporal Test Server* fixture.
@@ -140,7 +140,7 @@ Flock aims to provide a easy and reliable way to implement agentic applications.
 
 <!-- TOC --><a name="release-process"></a>
 ## Release Process:
-1. Maintainer bumps versiion in `pyproject.toml` following **SemVer**.
+1. Maintainer bumps version in `pyproject.toml` following **SemVer**.
 2. Changelog entry added in `docs/about/changelog.md`.
 3. `uv pip install -e .[all] && pytest`
 4. `git tag v.X.Y.Z && git push --tags`

flock_core-0.5.0b0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: flock-core
+Version: 0.5.0b0
+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: aiosqlite>=0.21.0
+Requires-Dist: azure-data-tables>=12.7.0
+Requires-Dist: chromadb>=0.6.3
+Requires-Dist: cloudpickle>=3.1.1
+Requires-Dist: croniter>=6.0.0
+Requires-Dist: datasets>=3.2.0
+Requires-Dist: devtools>=0.12.2
+Requires-Dist: dspy==2.6.23
+Requires-Dist: fastapi>=0.115.8
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: litellm==1.69.3
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: markdown2>=2.5.3
+Requires-Dist: mcp>=1.7.1
+Requires-Dist: msgpack>=1.1.0
+Requires-Dist: neo4j>=5.28.1
+Requires-Dist: openai==1.75.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: opik>=1.7.26
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pillow>=10.4.0
+Requires-Dist: prometheus-client>=0.21.1
+Requires-Dist: psutil>=6.1.1
+Requires-Dist: pydantic-settings>=2.7.1
+Requires-Dist: pydantic==2.10.5
+Requires-Dist: python-box>=7.3.2
+Requires-Dist: python-decouple>=3.8
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=13.9.4
+Requires-Dist: rouge-score>=0.1.2
+Requires-Dist: sentence-transformers>=3.4.1
+Requires-Dist: temporalio>=1.9.0
+Requires-Dist: thefuzz>=0.22.1
+Requires-Dist: tiktoken>=0.8.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: tqdm>=4.60.1
+Requires-Dist: uvicorn>=0.34.0
+Requires-Dist: wd-di>=0.2.14
+Requires-Dist: websockets>=15.0.1
+Requires-Dist: werkzeug>=3.1.3
+Provides-Extra: memory
+Requires-Dist: matplotlib>=3.10.0; extra == 'memory'
+Requires-Dist: mem0ai[graph]>=0.1.101; extra == 'memory'
+Requires-Dist: zep-python>=2.0.2; extra == 'memory'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <!-- Placeholder for your Flock Logo/Banner - Replace URL -->
+  <img alt="Flock Banner" src="https://raw.githubusercontent.com/whiteducksoftware/flock/master/docs/assets/images/flock.png" width="600">
+</p>
+<p align="center">
+  <!-- Update badges -->
+  <a href="https://pypi.org/project/flock-core/" target="_blank"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/flock-core?style=for-the-badge&logo=pypi&label=pip%20version"></a>
+  <img alt="Python Version" src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python">
+  <a href="https://github.com/whiteducksoftware/flock/actions/workflows/deploy-whiteduck-pypi.yml" target="_blank"><img alt="CI Status" src="https://img.shields.io/github/actions/workflow/status/whiteducksoftware/flock/deploy-whiteduck-pypi.yml?branch=master&style=for-the-badge&logo=githubactions&logoColor=white"></a>
+  <a href="https://github.com/whiteducksoftware/flock/blob/master/LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/pypi/l/flock-core?style=for-the-badge"></a>
+  <a href="https://whiteduck.de" target="_blank"><img alt="Built by white duck" src="https://img.shields.io/badge/Built%20by-white%20duck%20GmbH-white?style=for-the-badge&labelColor=black"></a>
+  <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>
+</p>
+
+
+---
+
+
+## The Problem You Know Too Well
+
+🤯 **Prompt Hell**: Brittle 500-line prompts that break with every model update.  
+💥 **System Failures**: One bad LLM response crashes your entire workflow  
+🧪 **Testing Nightmares**: "How do I unit test a prompt?" (You don't.)  
+🧪 **Measuring Quality**: "How do I know my prompts are close to optimal?" (You also don't.)  
+📄 **Output Chaos**: Parsing unstructured LLM responses into reliable data  
+⛓️ **Orchestration Limits**: Moving beyond simple chains and DAGs? Good luck  
+🚀 **Production Gap**: Jupyter notebooks don't scale to enterprise systems  
+
+*After building dozens of AI systems for enterprise clients, we realized the tooling was fundamentally broken.*
+
+
+**Build with agents, not against them.**
+
+
+## The Flock Solution
+
+**What if you could just skip that 'prompt engineering' step?**
+
+Flock is an agent framework for declarative AI workflows. You define what goes in and what should come out, the how is handled by the agent.   
+No brittle prompts. No guesswork. Just reliable, testable AI agents.
+
+
+✅ **Declarative Contracts**: Define inputs/outputs with Pydantic models. Flock handles the LLM complexity.  
+⚡ **Built-in Resilience**: Automatic retries, state persistence, and workflow resumption via Temporal.io  
+🧪 **Actually Testable**: Clear contracts make agents unit-testable like any other code  
+🧪 **Optimal Quality**: Agents posses multiple self-optimization algorithms based on latest research  
+🚀 **Dynamic Workflows**: Self-correcting loops, conditional routing, and intelligent decision-making  
+🔧 **Zero-Config Production**: Deploy as REST APIs with one command. Scale without rewriting.
+
+**Ready to see it in action?**
+
+## ⚡ Quick Start
+
+```python
+from flock.core import Flock, FlockFactory
+
+# 1. Create the main orchestrator
+my_flock = Flock(model="openai/gpt-4.1")
+
+# 2. Declaratively define an agent
+brainstorm_agent = FlockFactory.create_default_agent(
+    name="idea_generator",
+    input="topic",
+    output="catchy_title, key_points"
+)
+
+# 3. Add the agent to the Flock
+my_flock.add_agent(brainstorm_agent)
+
+# 4. Run the agent!
+input_data = {"topic": "The future of AI agents"}
+result = my_flock.run(start_agent="idea_generator", input=input_data)
+
+# The result is a Box object (dot-accessible dict)
+print(f"Generated Title: {result.catchy_title}")
+print(f"Key Points: {result.key_points}")
+```
+
+**No 20-line prompt fiddling. Just structured output, every time.**
+
+![image](https://github.com/user-attachments/assets/37a897cb-910f-49fc-89d4-510a780ad775)
+
+**Explore more examples →** [**Flock Showcase Repository**](https://github.com/whiteducksoftware/flock-showcase)
+
+
+
+## 💾 Installation - Use Flock in your project
+
+Get started with the core Flock library:
+
+```bash
+# Using uv (recommended)
+uv pip install flock-core
+
+# Using pip
+pip install flock-core
+```
+
+Extras: Install optional dependencies for specific features:
+
+```bash
+# Flock tools and mcp server
+uv pip install flock-mcp
+```
+
+## 🔑 Installation - Develop Flock
+
+```bash
+git clone https://github.com/whiteducksoftware/flock.git
+cd flock
+
+# One-liner dev setup after cloning
+pip install poethepoet && poe install
+```
+
+Additional provided `poe` tasks and commands:
+
+```bash
+poe install # Install the project
+poe build # Build the project
+poe docs # Serve the docs
+poe format # Format the code
+poe lint # Lint the code
+```
+
+## 🔑 Environment Setup
+
+Flock uses environment variables (typically in a .env file) for configuration, especially API keys. Create a .env file in your project root:
+
+```bash
+# .env - Example
+
+# --- LLM Provider API Keys (Required by most examples) ---
+# Add keys for providers you use (OpenAI, Anthropic, Gemini, Azure, etc.)
+# Refer to litellm docs (https://docs.litellm.ai/docs/providers) for names
+OPENAI_API_KEY="your-openai-api-key"
+# ANTHROPIC_API_KEY="your-anthropic-api-key"
+
+# --- Tool-Specific Keys (Optional) ---
+# TAVILY_API_KEY="your-tavily-search-key"
+# GITHUB_PAT="your-github-personal-access-token"
+
+# --- Default Flock Settings (Optional) ---
+DEFAULT_MODEL="openai/gpt-4o" # Default LLM if agent doesn't specify
+
+# --- Flock CLI Settings (Managed by `flock settings`) ---
+# SHOW_SECRETS="False"
+# VARS_PER_PAGE="20"
+```
+
+Be sure that the .env file is added to your .gitignore!
+
+
+## 🐤 New in Flock 0.5.0 `Kea` 🐤
+
+Keas are one of the smartest birds in the world famous for figuring out multi-step puzzles, unlatching doors, and coordinating in small groups to get what it wants.
+
+<Insert Kea Logo>
+
+### Self-optimizing agents
+
+### Everything you need to evaluate and optimize agents
+
+### Benchmarks
+
+### Smooth Jupyter experience
+
+### Multi-Threading and Thread Safety
+
+
+--------------------------------
+
+## 📚 Examples & Tutorials
+
+For a comprehensive set of examples, ranging from basic usage to complex projects and advanced features, please visit our dedicated showcase repository:
+
+➡️ [github.com/whiteducksoftware/flock-showcase](https://github.com/whiteducksoftware/flock-showcase) ⬅️
+
+The showcase includes:
+
+- Step-by-step guides for core concepts.
+- Examples of tool usage, routing, memory, and more.
+- Complete mini-projects demonstrating practical applications.
+
+## 📖 Documentation
+
+Full documentation, including API references and conceptual explanations, can be found at:
+
+➡️ [whiteducksoftware.github.io/flock/](https://whiteducksoftware.github.io/flock/) ⬅️
+
+## 🤝 Contributing
+
+We welcome contributions! Please see the CONTRIBUTING.md file (if available) or open an issue/pull request on GitHub.
+
+Ways to contribute:
+
+- Report bugs or suggest features.
+- Improve documentation.
+- Contribute new Modules, Evaluators, or Routers.
+- Add examples to the flock-showcase repository.
+
+## 📜 License
+
+Flock is licensed under the MIT License. See the LICENSE file for details.
+
+## 🏢 About
+
+Flock is developed and maintained by white duck GmbH, your partner for cloud-native solutions and AI integration.