flock-core 0.4.0b17__tar.gz → 0.4.0b19__tar.gz

flock_core-0.4.0b19/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: flock-core
+Version: 0.4.0b19
+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: azure-search-documents>=11.5.2
+Requires-Dist: chromadb>=0.6.3
+Requires-Dist: cloudpickle>=3.1.1
+Requires-Dist: datasets>=3.2.0
+Requires-Dist: devtools>=0.12.2
+Requires-Dist: dspy==2.6.16
+Requires-Dist: duckduckgo-search>=7.3.2
+Requires-Dist: fastapi>=0.115.8
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: litellm==1.63.7
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: msgpack>=1.1.0
+Requires-Dist: nltk>=3.9.1
+Requires-Dist: notion-client>=2.3.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: 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: python-fasthtml>=0.12.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=13.9.4
+Requires-Dist: sentence-transformers>=3.4.1
+Requires-Dist: temporalio>=1.9.0
+Requires-Dist: tiktoken>=0.8.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: uvicorn>=0.34.0
+Requires-Dist: zep-python>=2.0.2
+Provides-Extra: all
+Requires-Dist: docling>=2.18.0; extra == 'all'
+Requires-Dist: markdownify>=0.14.1; extra == 'all'
+Requires-Dist: tavily-python>=0.5.0; extra == 'all'
+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
+
+# 🚀 Flock: The Declarative AI Agent Framework 🚀
+
+<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>
+
+🐤 Flock 0.4.0 currently in beta - use `pip install flock-core==0.4.0b5` 🐤
+
+🐤 `pip install flock-core` will install the latest non-beta version 🐤
+
+🐤  Expected Release for 0.4.0 `Magpie`: End of April 2025 🐤
+
+---
+
+**Tired of wrestling with paragraphs of prompt text just to get your AI agent to perform a specific, structured task?** 😫
+
+Enter **Flock**, the agent framework that lets you ditch the prompt-palaver and focus on **what** you want your agents to achieve through a **declarative approach**. Define your agent's inputs, outputs, and available tools using clear Python structures (including type hints!), and let Flock handle the complex LLM interactions and orchestration.
+
+Built with real-world deployment in mind, Flock integrates seamlessly with tools like **Temporal** (optional) for building robust, fault-tolerant, and scalable agent systems right out of the box.
+
+**Looking for examples and tutorials?** Check out the dedicated [**👉 flock-showcase Repository**](https://github.com/whiteducksoftware/flock-showcase)!
+
+## ✨ Why Join the Flock?
+
+Flock offers a different way to build agentic systems:
+
+| Traditional Agent Frameworks 😟        | Flock Framework 🐤🐧🐓🦆             |
+| :------------------------------------- | :------------------------------------ |
+| 🤯 **Prompt Nightmare**                | ✅ **Declarative Simplicity**         |
+| *Long, brittle, hard-to-tune prompts*  | *Clear input/output specs (typed!)*   |
+| 💥 **Fragile & Unpredictable**         | ⚡ **Robust & Production-Ready**     |
+| *Single errors can halt everything*    | *Fault-tolerant via Temporal option*  |
+| 🧩 **Monolithic & Rigid**             | 🔧 **Modular & Flexible**             |
+| *Hard to extend or modify logic*       | *Pluggable Evaluators, Modules, Tools*|
+| ⛓️ **Basic Chaining**                 | 🚀 **Advanced Orchestration**         |
+| *Often just linear workflows*          | *Dynamic Routing, Batch Processing*   |
+| 🧪 **Difficult Testing**               | ✅ **Testable Components**            |
+| *Hard to unit test prompt logic*       | *Clear I/O contracts aid testing*     |
+| 📄 **Unstructured Output**             | ✨ **Structured Data Handling**       |
+| *Parsing unreliable LLM text output*   | *Native Pydantic/Typed Dict support*  |
+
+## 💡 Core Concepts
+
+Flock's power comes from a few key ideas (Learn more in the [Full Documentation](https://whiteducksoftware.github.io/flock/)):
+
+1. **Declarative Agents:** Define agents by *what* they do (inputs/outputs), not *how*. Flock uses **Evaluators** (like the default `DeclarativeEvaluator` powered by DSPy) to handle the underlying logic.
+2. **Typed Signatures:** Specify agent inputs and outputs using Python type hints and optional descriptions (e.g., `"query: str | User request, context: Optional[List[MyType]]"`).
+3. **Modular Components:** Extend agent capabilities with pluggable **Modules** (e.g., for memory, metrics, output formatting) that hook into the agent's lifecycle.
+4. **Intelligent Workflows:** Chain agents explicitly or use **Routers** (LLM-based, Agent-based, or custom) for dynamic decision-making.
+5. **Reliable Execution:** Run locally for easy debugging or seamlessly switch to **Temporal** (optional) for production-grade fault tolerance, retries, and state management.
+6. **Tool Integration:** Equip agents with standard or custom Python functions (`@flock_tool`) registered via the `FlockRegistry`.
+7. **Registry:** A central place (`@flock_component`, `@flock_type`, `@flock_tool`) to register your custom classes, types, and functions, enabling robust serialization and dynamic loading.
+
+## 💾 Installation
+
+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
+# Common tools (Tavily, Markdownify)
+uv pip install flock-core[tools]
+
+# All optional dependencies (including tools, docling, etc.)
+uv pip install flock-core[all]
+```
+
+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"
+```
+
+Remember to add .env to your .gitignore!
+
+## ⚡ Quick Start Syntax
+
+While detailed examples and tutorials now live in the flock-showcase repository, here's a minimal example to illustrate the core syntax:
+
+```python
+from flock.core import Flock, FlockFactory
+
+# 1. Create the main orchestrator
+# Uses DEFAULT_MODEL from .env or defaults to "openai/gpt-4o" if not set
+my_flock = Flock(name="SimpleFlock")
+
+# 2. Declaratively define an agent using the Factory
+# Input: a topic (string)
+# Output: a title (string) and bullet points (list of strings)
+brainstorm_agent = FlockFactory.create_default_agent(
+    name="idea_generator",
+    description="Generates titles and key points for a given topic.",
+    input="topic: str | The subject to brainstorm about",
+    output="catchy_title: str, key_points: list[str] | 3-5 main bullet points"
+)
+
+# 3. Add the agent to the Flock
+my_flock.add_agent(brainstorm_agent)
+
+# 4. Run the agent!
+if __name__ == "__main__":
+    input_data = {"topic": "The future of AI agents"}
+    try:
+        # The result is a Box object (dot-accessible dict)
+        result = my_flock.run(start_agent="idea_generator", input=input_data)
+        print(f"Generated Title: {result.catchy_title}")
+        print("Key Points:")
+        for point in result.key_points:
+            print(f"- {point}")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+        print("Ensure your LLM API key (e.g., OPENAI_API_KEY) is set in your .env file!")
+```
+
+## ✨ Utility: @flockclass Hydrator
+
+Flock also provides conveniences. The @flockclass decorator allows you to easily populate Pydantic models using an LLM:
+
+```python
+from pydantic import BaseModel
+from flock.util.hydrator import flockclass # Assuming hydrator utility exists
+import asyncio
+
+@flockclass(model="openai/gpt-4o") # Decorate your Pydantic model
+class CharacterIdea(BaseModel):
+    name: str
+    char_class: str
+    race: str
+    backstory_hook: str | None = None # Field to be filled by hydrate
+    personality_trait: str | None = None # Field to be filled by hydrate
+
+async def create_character():
+    # Create with minimal data
+    char = CharacterIdea(name="Gorok", char_class="Barbarian", race="Orc")
+    print(f"Before Hydration: {char}")
+
+    # Call hydrate to fill in the None fields using the LLM
+    hydrated_char = await char.hydrate()
+
+    print(f"\nAfter Hydration: {hydrated_char}")
+    print(f"Backstory Hook: {hydrated_char.backstory_hook}")
+
+# asyncio.run(create_character())
+```
+
+## 📚 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.
+- Join our Discord Community to discuss development! <!-- Add Discord link -->
+
+## 📜 License
+
+Flock is licensed under the Apache License 2.0. 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.

flock_core-0.4.0b19/README.md

@@ -0,0 +1,220 @@
+# 🚀 Flock: The Declarative AI Agent Framework 🚀
+
+<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>
+
+🐤 Flock 0.4.0 currently in beta - use `pip install flock-core==0.4.0b5` 🐤
+
+🐤 `pip install flock-core` will install the latest non-beta version 🐤
+
+🐤  Expected Release for 0.4.0 `Magpie`: End of April 2025 🐤
+
+---
+
+**Tired of wrestling with paragraphs of prompt text just to get your AI agent to perform a specific, structured task?** 😫
+
+Enter **Flock**, the agent framework that lets you ditch the prompt-palaver and focus on **what** you want your agents to achieve through a **declarative approach**. Define your agent's inputs, outputs, and available tools using clear Python structures (including type hints!), and let Flock handle the complex LLM interactions and orchestration.
+
+Built with real-world deployment in mind, Flock integrates seamlessly with tools like **Temporal** (optional) for building robust, fault-tolerant, and scalable agent systems right out of the box.
+
+**Looking for examples and tutorials?** Check out the dedicated [**👉 flock-showcase Repository**](https://github.com/whiteducksoftware/flock-showcase)!
+
+## ✨ Why Join the Flock?
+
+Flock offers a different way to build agentic systems:
+
+| Traditional Agent Frameworks 😟        | Flock Framework 🐤🐧🐓🦆             |
+| :------------------------------------- | :------------------------------------ |
+| 🤯 **Prompt Nightmare**                | ✅ **Declarative Simplicity**         |
+| *Long, brittle, hard-to-tune prompts*  | *Clear input/output specs (typed!)*   |
+| 💥 **Fragile & Unpredictable**         | ⚡ **Robust & Production-Ready**     |
+| *Single errors can halt everything*    | *Fault-tolerant via Temporal option*  |
+| 🧩 **Monolithic & Rigid**             | 🔧 **Modular & Flexible**             |
+| *Hard to extend or modify logic*       | *Pluggable Evaluators, Modules, Tools*|
+| ⛓️ **Basic Chaining**                 | 🚀 **Advanced Orchestration**         |
+| *Often just linear workflows*          | *Dynamic Routing, Batch Processing*   |
+| 🧪 **Difficult Testing**               | ✅ **Testable Components**            |
+| *Hard to unit test prompt logic*       | *Clear I/O contracts aid testing*     |
+| 📄 **Unstructured Output**             | ✨ **Structured Data Handling**       |
+| *Parsing unreliable LLM text output*   | *Native Pydantic/Typed Dict support*  |
+
+## 💡 Core Concepts
+
+Flock's power comes from a few key ideas (Learn more in the [Full Documentation](https://whiteducksoftware.github.io/flock/)):
+
+1. **Declarative Agents:** Define agents by *what* they do (inputs/outputs), not *how*. Flock uses **Evaluators** (like the default `DeclarativeEvaluator` powered by DSPy) to handle the underlying logic.
+2. **Typed Signatures:** Specify agent inputs and outputs using Python type hints and optional descriptions (e.g., `"query: str | User request, context: Optional[List[MyType]]"`).
+3. **Modular Components:** Extend agent capabilities with pluggable **Modules** (e.g., for memory, metrics, output formatting) that hook into the agent's lifecycle.
+4. **Intelligent Workflows:** Chain agents explicitly or use **Routers** (LLM-based, Agent-based, or custom) for dynamic decision-making.
+5. **Reliable Execution:** Run locally for easy debugging or seamlessly switch to **Temporal** (optional) for production-grade fault tolerance, retries, and state management.
+6. **Tool Integration:** Equip agents with standard or custom Python functions (`@flock_tool`) registered via the `FlockRegistry`.
+7. **Registry:** A central place (`@flock_component`, `@flock_type`, `@flock_tool`) to register your custom classes, types, and functions, enabling robust serialization and dynamic loading.
+
+## 💾 Installation
+
+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
+# Common tools (Tavily, Markdownify)
+uv pip install flock-core[tools]
+
+# All optional dependencies (including tools, docling, etc.)
+uv pip install flock-core[all]
+```
+
+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"
+```
+
+Remember to add .env to your .gitignore!
+
+## ⚡ Quick Start Syntax
+
+While detailed examples and tutorials now live in the flock-showcase repository, here's a minimal example to illustrate the core syntax:
+
+```python
+from flock.core import Flock, FlockFactory
+
+# 1. Create the main orchestrator
+# Uses DEFAULT_MODEL from .env or defaults to "openai/gpt-4o" if not set
+my_flock = Flock(name="SimpleFlock")
+
+# 2. Declaratively define an agent using the Factory
+# Input: a topic (string)
+# Output: a title (string) and bullet points (list of strings)
+brainstorm_agent = FlockFactory.create_default_agent(
+    name="idea_generator",
+    description="Generates titles and key points for a given topic.",
+    input="topic: str | The subject to brainstorm about",
+    output="catchy_title: str, key_points: list[str] | 3-5 main bullet points"
+)
+
+# 3. Add the agent to the Flock
+my_flock.add_agent(brainstorm_agent)
+
+# 4. Run the agent!
+if __name__ == "__main__":
+    input_data = {"topic": "The future of AI agents"}
+    try:
+        # The result is a Box object (dot-accessible dict)
+        result = my_flock.run(start_agent="idea_generator", input=input_data)
+        print(f"Generated Title: {result.catchy_title}")
+        print("Key Points:")
+        for point in result.key_points:
+            print(f"- {point}")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+        print("Ensure your LLM API key (e.g., OPENAI_API_KEY) is set in your .env file!")
+```
+
+## ✨ Utility: @flockclass Hydrator
+
+Flock also provides conveniences. The @flockclass decorator allows you to easily populate Pydantic models using an LLM:
+
+```python
+from pydantic import BaseModel
+from flock.util.hydrator import flockclass # Assuming hydrator utility exists
+import asyncio
+
+@flockclass(model="openai/gpt-4o") # Decorate your Pydantic model
+class CharacterIdea(BaseModel):
+    name: str
+    char_class: str
+    race: str
+    backstory_hook: str | None = None # Field to be filled by hydrate
+    personality_trait: str | None = None # Field to be filled by hydrate
+
+async def create_character():
+    # Create with minimal data
+    char = CharacterIdea(name="Gorok", char_class="Barbarian", race="Orc")
+    print(f"Before Hydration: {char}")
+
+    # Call hydrate to fill in the None fields using the LLM
+    hydrated_char = await char.hydrate()
+
+    print(f"\nAfter Hydration: {hydrated_char}")
+    print(f"Backstory Hook: {hydrated_char.backstory_hook}")
+
+# asyncio.run(create_character())
+```
+
+## 📚 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.
+- Join our Discord Community to discuss development! <!-- Add Discord link -->
+
+## 📜 License
+
+Flock is licensed under the Apache License 2.0. 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.

flock_core-0.4.0b19/docs/interacting-with-flock/cli-tool.md

@@ -0,0 +1,40 @@
+---
+hide:
+  - toc
+---
+
+# 🛠️ Flock CLI Tool
+
+Beyond integrating Flock into your Python code or exposing it via an API, Flock provides a dedicated command-line interface (CLI) tool, accessed simply by running `flock` in your terminal (once installed).
+
+This tool is primarily designed for **managing and interacting with persistent Flock configurations** stored in `.flock.yaml` files.
+
+## Key Features
+
+* **Loading Flocks:** Load complete Flock configurations, including agents, types, and components, from `.flock.yaml` files.
+* **Creating Flocks:** A guided wizard (`flock` -> "Create a new Flock") helps you scaffold a new `.flock.yaml` file with basic settings and initial agents.
+* **Executing Flocks:** Run workflows (single or batch) defined within a loaded `.flock.yaml` file directly from the command line.
+* **Registry Management:** View, add, remove, and automatically scan for components (agents, types, callables/tools) in the global Flock registry. This is crucial for ensuring correct serialization and deserialization.
+* **Settings Management:** View and edit global Flock settings, primarily environment variables stored in `~/.flock/.env`, including API keys and configuration flags. Manage different `.env` profiles.
+* **Theme Builder:** Interactively preview and configure output themes for agents using rich tables.
+* **(Future):** Potential deployment commands (e.g., to Docker, Kubernetes).
+
+## How to Use
+
+1. **Installation:** Ensure `flock-core` (or the relevant package) is installed in your environment.
+2. **Run:** Simply type `flock` in your terminal.
+3. **Navigate:** Use the interactive menu (powered by `questionary`) to select actions like "Load a *.flock file", "Create a new Flock", "Registry management", "Settings", etc.
+
+*(Placeholder: Screenshot of the main `flock` CLI menu)*
+
+## Distinction from Other Interaction Methods
+
+* **vs. Programmatic API:** The CLI tool operates on *serialized* Flock states (`.flock.yaml`), while the programmatic API works with `Flock` *objects* in Python memory. The CLI is for management; the API is for integration.
+* **vs. Interactive Script CLI:** The `flock` tool is a standalone application for managing configurations. The `flock.start_cli()` method discussed in [Interactive Script CLI](interactive-cli.md) is used *within* a Python script for debugging the *current*, in-memory `Flock` instance.
+
+Use the Flock CLI tool when you need to:
+
+* Save and load reusable Flock configurations.
+* Execute predefined workflows without writing Python scripts each time.
+* Manage the global registry of components, types, and tools shared across your projects.
+* Configure global settings like API keys or CLI behavior.

flock_core-0.4.0b19/docs/interacting-with-flock/index.md

@@ -0,0 +1,20 @@
+---
+hide:
+  - toc
+---
+
+# Interacting with Flock: Beyond the Build 🚀
+
+You've designed your Flock, defined your agents, and maybe even chained them together. Now what? How do you actually *use* your sophisticated AI system?
+
+Flock is designed for flexibility, offering multiple ways to interact with your agents and workflows, catering to different needs from development and debugging to integration and deployment.
+
+This section explores the primary methods for interacting with a configured `Flock` instance:
+
+*   **[🐍 Programmatic API (Python)](programmatic.md):** The most direct way. Integrate Flock directly into your Python applications, trigger runs, and process results using simple method calls like `flock.run()`, `flock.run_async()`, and `flock.run_batch()`. Ideal for core development and integration within Python projects.
+*   **[🌐 REST API](rest-api.md):** Expose your Flock as a web service. Start a FastAPI server (`flock.start_api()`) to allow remote execution via HTTP requests. Perfect for integrating Flock with web frontends, other microservices, or external systems.
+*   **[🖥️ Web UI (FastHTML)](web-ui.md):** A simple, automatically generated web interface for interactive testing and demonstrations. Launch it alongside the REST API (`flock.start_api(create_ui=True)`) for a quick way to select agents, provide inputs, and view results in your browser.
+*   **[🛠️ Flock CLI Tool](cli-tool.md):** Manage your Flock configurations using the main `flock` command-line tool. Load `.flock.yaml` files, execute runs, manage the registry, and configure settings without writing Python code. Best for system administration and managing saved Flock states.
+*   **[⌨️ Interactive Script CLI](interactive-cli.md):** Debug agent interactions directly within your terminal while running a Python script using `flock.start_cli()`. Useful for stepping through agent handoffs and inspecting context during development.
+
+Choose the interaction method that best suits your current task, whether it's embedding AI logic deep within an application, providing an API for others, quickly demoing capabilities, or managing persistent configurations.

flock_core-0.4.0b19/docs/interacting-with-flock/interactive-cli.md

@@ -0,0 +1,79 @@
+---
+hide:
+  - toc
+---
+
+# ⌨️ Interactive Script CLI (`flock.start_cli()`)
+
+While the main [Flock CLI Tool](cli-tool.md) is used for managing saved configurations, Flock also offers an **interactive command-line interface directly within your running Python script** using the `flock.start_cli()` method.
+
+This mode is specifically designed for **development and debugging** purposes, allowing you to step through agent interactions and inspect the context of your *current, in-memory* `Flock` instance.
+
+## Starting the Interactive CLI
+
+You typically call `start_cli()` at a point in your script where you have a fully configured `Flock` object ready.
+
+```python
+from flock.core import Flock, FlockFactory
+from flock.routers.default import DefaultRouter, DefaultRouterConfig # Assuming DefaultRouter is used
+
+# --- Configure your Flock and Agents ---
+flock = Flock(name="Debug Flock", model="openai/gpt-4o")
+
+agent_a = FlockFactory.create_default_agent(
+    name="AgentA",
+    input="start_query: str",
+    output="intermediate_result: str",
+    wait_for_input=True # Useful in interactive mode
+)
+
+agent_b = FlockFactory.create_default_agent(
+    name="AgentB",
+    input="intermediate_result: str", # Takes output from AgentA
+    output="final_answer: str",
+    wait_for_input=True # Useful in interactive mode
+)
+
+# Setup handoff (simple chain)
+agent_a.handoff_router = DefaultRouter(config=DefaultRouterConfig(hand_off=agent_b.name))
+
+flock.add_agent(agent_a)
+flock.add_agent(agent_b)
+
+# --- Start the Interactive CLI ---
+if __name__ == "__main__":
+    print("Starting Flock Interactive CLI...")
+    print("Type your initial query for AgentA, or 'quit' to exit.")
+    # This call enters an interactive loop in the terminal
+    flock.start_cli(start_agent=agent_a) # Specify the starting agent
+
+    print("Interactive CLI finished.")
+```
+
+## Using the Interactive CLI
+
+When you run the script above, instead of executing the full workflow automatically, `flock.start_cli()` will present an interactive prompt in your terminal:
+
+1. **Initial Input:** It will typically prompt for the input required by the start_agent you specified.
+
+2. **Agent Execution:** After you provide input, the starting agent (AgentA in the example) executes.
+
+3. **Output Display:** The agent's output is displayed (often using the configured OutputModule, potentially with rich tables).
+
+4. **Handoff & Next Input:** If the agent has a handoff_router, Flock determines the next agent (AgentB). If the next agent is configured with wait_for_input=True (or if interaction is needed), the CLI might pause or show the next agent's expected input. Often, data flows automatically via context matching the handoff mode.
+
+5. **Loop:** The process repeats for the next agent.
+
+6. **Commands:** You can typically type commands like `quit`, `exit`, or potentially others (depending on implementation details) to control the flow or inspect state.
+
+(Placeholder: Screenshot of the terminal during an interactive flock.start_cli() session)
+
+## Use Cases
+
+- **Debugging Agent Chains:** Observe the output of each agent in a sequence.
+- **Inspecting Context:** (If enhanced) See how the FlockContext changes after each step.
+- **Testing Routers:** Verify that your LLMRouter or AgentRouter selects the expected next agent based on intermediate results.
+- **Manual Control:** Intervene in the workflow or provide specific inputs at different stages.
+
+**Important:** `flock.start_cli()` operates on the Flock object currently in your Python script's memory. It does not load or save .flock.yaml files like the main flock management tool. It's purely a development aid within a script.
+