flock-core 0.2.17__tar.gz → 0.2.18__tar.gz

flock_core-0.2.18/.github/workflows/deploy-documentation.yml

@@ -0,0 +1,16 @@
+name: Deploy MkDocs
+on:
+  push:
+    branches:
+      - master  # or master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - run: pip install mkdocs-material mkdocs mkdocstrings[python]
+      - run: mkdocs gh-deploy --force

{flock_core-0.2.17 → flock_core-0.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.2.17
+Version: 0.2.18
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -38,7 +38,7 @@ 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 src="docs/assets/images/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>
@@ -69,7 +69,15 @@ Flock is a framework for orchestrating LLM-powered agents. It leverages a **decl
 
 https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
 
+## Table of Contents
 
+- [Key Innovations](#key-innovations)
+- [Examples](#examples)
+  - [Hello Flock!](#hello-flock)
+  - [It's not my type](#its-not-my-type)
+  - [Being pydantic](#being-pydantic)
+  - [Building a chain gang!](#building-a-chain-gang)
+- [Installation](#installation)
 
 
 ## Key Innovations
@@ -96,7 +104,7 @@ https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
 
 
 <p align="center">
-<img src="docs/img/flock_cli.png" width="200"><br>
+<img src="docs/assets/images//flock_cli.png" width="200"><br>
 
 ## Examples
 
@@ -294,6 +302,58 @@ And BAM! Your finished data model filled up to the brim with data! 🎊
 }
 ```
 
+### Building a chain gang
+
+Our `bloggy` is great, but what if we want to turn those amazing headers into full blog posts? Time to bring in a friend! 🤝
+Let's see how easy it is to make agents work together 🔗
+
+```python
+from flock.core import Flock, FlockAgent
+
+flock = Flock(model="openai/gpt-4o")
+
+# First agent: Our trusty bloggy generates titles and headers! 📝
+bloggy = FlockAgent(
+    name="bloggy",
+    input="blog_idea: str|The topic to blog about",
+    output=(
+        "funny_blog_title: str|A catchy title for the blog, "
+        "blog_headers: list[str]|List of section headers for the blog"
+    )
+)
+
+# Second agent: The content wizard that brings headers to life! ✨
+content_writer = FlockAgent(
+    name="content_writer",
+    input=(
+        "funny_blog_title: str|The blog title to work with, "
+        "blog_headers: list[str]|The headers to expand into content"
+    ),
+    output="blog_sections: list[BlogSection]|The fully written blog sections"
+)
+
+# Make them besties! 🤝
+bloggy.hand_off = content_writer
+
+# Add your dynamic duo to the flock
+flock.add_agent(bloggy)
+flock.add_agent(content_writer)
+
+# Let them create some magic! 🎨
+result = flock.run(
+    input={"blog_idea": "A blog about cats"},
+    start_agent=bloggy
+)
+```
+
+Super simple rules to remember:
+1. Point the first agent to the next one using `hand_off`
+2. Make sure their inputs and outputs match up
+
+That's all there is to it! `bloggy` comes up with amazing headers, and `content_writer` turns them into full blog sections. No more writer's block! 🎉
+
+And this is just the beginning - you can chain as many agents as you want. Maybe add a proofreader? Or an SEO optimizer? But let's not get ahead of ourselves! 😉
+
 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
@@ -308,7 +368,9 @@ Documentation in progress!
 
 ## Architecture
 
-Documentation in progress!
+<img src="docs/assets/images/components_chart.png" width="800"><br>
+
+<img src="docs/assets/images/flow_chart.png" width="800"><br>
 
 
 ## Requirements

{flock_core-0.2.17 → flock_core-0.2.18}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-<img src="docs/img/flock.png" width="600"><br>
+<img src="docs/assets/images/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>
@@ -30,7 +30,15 @@ Flock is a framework for orchestrating LLM-powered agents. It leverages a **decl
 
 https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
 
+## Table of Contents
 
+- [Key Innovations](#key-innovations)
+- [Examples](#examples)
+  - [Hello Flock!](#hello-flock)
+  - [It's not my type](#its-not-my-type)
+  - [Being pydantic](#being-pydantic)
+  - [Building a chain gang!](#building-a-chain-gang)
+- [Installation](#installation)
 
 
 ## Key Innovations
@@ -57,7 +65,7 @@ https://github.com/user-attachments/assets/bdab4786-d532-459f-806a-024727164dcc
 
 
 <p align="center">
-<img src="docs/img/flock_cli.png" width="200"><br>
+<img src="docs/assets/images//flock_cli.png" width="200"><br>
 
 ## Examples
 
@@ -255,6 +263,58 @@ And BAM! Your finished data model filled up to the brim with data! 🎊
 }
 ```
 
+### Building a chain gang
+
+Our `bloggy` is great, but what if we want to turn those amazing headers into full blog posts? Time to bring in a friend! 🤝
+Let's see how easy it is to make agents work together 🔗
+
+```python
+from flock.core import Flock, FlockAgent
+
+flock = Flock(model="openai/gpt-4o")
+
+# First agent: Our trusty bloggy generates titles and headers! 📝
+bloggy = FlockAgent(
+    name="bloggy",
+    input="blog_idea: str|The topic to blog about",
+    output=(
+        "funny_blog_title: str|A catchy title for the blog, "
+        "blog_headers: list[str]|List of section headers for the blog"
+    )
+)
+
+# Second agent: The content wizard that brings headers to life! ✨
+content_writer = FlockAgent(
+    name="content_writer",
+    input=(
+        "funny_blog_title: str|The blog title to work with, "
+        "blog_headers: list[str]|The headers to expand into content"
+    ),
+    output="blog_sections: list[BlogSection]|The fully written blog sections"
+)
+
+# Make them besties! 🤝
+bloggy.hand_off = content_writer
+
+# Add your dynamic duo to the flock
+flock.add_agent(bloggy)
+flock.add_agent(content_writer)
+
+# Let them create some magic! 🎨
+result = flock.run(
+    input={"blog_idea": "A blog about cats"},
+    start_agent=bloggy
+)
+```
+
+Super simple rules to remember:
+1. Point the first agent to the next one using `hand_off`
+2. Make sure their inputs and outputs match up
+
+That's all there is to it! `bloggy` comes up with amazing headers, and `content_writer` turns them into full blog sections. No more writer's block! 🎉
+
+And this is just the beginning - you can chain as many agents as you want. Maybe add a proofreader? Or an SEO optimizer? But let's not get ahead of ourselves! 😉
+
 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
@@ -269,7 +329,9 @@ Documentation in progress!
 
 ## Architecture
 
-Documentation in progress!
+<img src="docs/assets/images/components_chart.png" width="800"><br>
+
+<img src="docs/assets/images/flow_chart.png" width="800"><br>
 
 
 ## Requirements

flock_core-0.2.18/docs/advanced/complex-workflows.md

@@ -0,0 +1,3 @@
+# Complex Workflows
+
+Documentation in progress...

flock_core-0.2.18/docs/advanced/custom-agents.md

@@ -0,0 +1,3 @@
+# Custom Agents
+
+Documentation in progress...

flock_core-0.2.18/docs/advanced/performance.md

@@ -0,0 +1,3 @@
+# Performance
+
+Documentation in progress...

flock_core-0.2.18/docs/advanced/testing.md

@@ -0,0 +1,3 @@
+# Testing
+
+Documentation in progress...

flock_core-0.2.18/docs/api/flock-core.md

@@ -0,0 +1,3 @@
+# Flock Core
+
+Documentation in progress...

flock_core-0.2.18/docs/api/flockagent.md

@@ -0,0 +1,3 @@
+# Flockagent
+
+Documentation in progress...

flock_core-0.2.18/docs/api/types.md

@@ -0,0 +1,3 @@
+# Types
+
+Documentation in progress...

flock_core-0.2.18/docs/api/utilities.md

@@ -0,0 +1,3 @@
+# Utilities
+
+Documentation in progress...

flock_core-0.2.18/docs/architecture/components.md

@@ -0,0 +1,3 @@
+# Components
+
+Documentation in progress...

flock_core-0.2.18/docs/architecture/design-decisions.md

@@ -0,0 +1,3 @@
+# Design Decisions
+
+Documentation in progress...

flock_core-0.2.18/docs/architecture/overview.md

@@ -0,0 +1,3 @@
+# Overview
+
+Documentation in progress...

flock_core-0.2.18/docs/contributing/code-style.md

@@ -0,0 +1,3 @@
+# Code Style
+
+Documentation in progress...

flock_core-0.2.18/docs/contributing/development.md

@@ -0,0 +1,3 @@
+# Development
+
+Documentation in progress...

flock_core-0.2.18/docs/contributing/documentation.md

@@ -0,0 +1,3 @@
+# Documentation
+
+Documentation in progress...

flock_core-0.2.18/docs/contributing/testing.md

@@ -0,0 +1,3 @@
+# Testing
+
+Documentation in progress...

flock_core-0.2.18/docs/core-concepts/agents.md

@@ -0,0 +1,3 @@
+# Agents
+
+Documentation in progress...

flock_core-0.2.18/docs/core-concepts/declarative.md

@@ -0,0 +1,3 @@
+# Declarative
+
+Documentation in progress...

flock_core-0.2.18/docs/core-concepts/error-handling.md

@@ -0,0 +1,3 @@
+# Error Handling
+
+Documentation in progress...

flock_core-0.2.18/docs/core-concepts/type-system.md

@@ -0,0 +1,3 @@
+# Type System
+
+Documentation in progress...

flock_core-0.2.18/docs/core-concepts/workflows.md

@@ -0,0 +1,3 @@
+# Workflows
+
+Documentation in progress...

flock_core-0.2.18/docs/create_doc_boilerplate.py

@@ -0,0 +1,131 @@
+import os
+from pathlib import Path
+
+import yaml
+
+# The mkdocs navigation structure
+NAV_STRUCTURE = """
+nav:
+  - Home: index.md
+  
+  - Getting Started:
+    - Quick Start: getting-started/quickstart.md
+    - Installation: getting-started/installation.md
+    - Basic Concepts: getting-started/concepts.md
+    - Configuration: getting-started/configuration.md
+    
+  - Core Concepts:
+    - Agents: core-concepts/agents.md
+    - Type System: core-concepts/type-system.md
+    - Workflows: core-concepts/workflows.md
+    - Declarative Programming: core-concepts/declarative.md
+    - Error Handling: core-concepts/error-handling.md
+    
+  - Features:
+    - Agent Definition: features/agent-definition.md
+    - Type Safety: features/type-safety.md
+    - Pydantic Integration: features/pydantic.md
+    - Agent Chaining: features/agent-chaining.md
+    - Lifecycle Hooks: features/lifecycle-hooks.md
+    
+  - Integrations:
+    - Temporal: integrations/temporal.md
+    - DSPy: integrations/dspy.md
+    - LiteLLM: integrations/litellm.md
+    - Tavily: integrations/tavily.md
+    
+  - Advanced Usage:
+    - Custom Agents: advanced/custom-agents.md
+    - Complex Workflows: advanced/complex-workflows.md
+    - Testing: advanced/testing.md
+    - Performance Optimization: advanced/performance.md
+    
+  - Deployment:
+    - Production Setup: deployment/production-setup.md
+    - Monitoring: deployment/monitoring.md
+    - Scalability: deployment/scalability.md
+    - Security: deployment/security.md
+    
+  - Tutorials:
+    - Basic Blog Generator: tutorials/blog-generator.md
+    - Multi-Agent Systems: tutorials/multi-agent.md
+    - Custom Tool Integration: tutorials/custom-tools.md
+    - Error Recovery: tutorials/error-recovery.md
+    
+  - API Reference:
+    - FlockAgent: api/flockagent.md
+    - Flock Core: api/flock-core.md
+    - Types: api/types.md
+    - Utilities: api/utilities.md
+    
+  - Contributing:
+    - Development Setup: contributing/development.md
+    - Code Style: contributing/code-style.md
+    - Testing Guide: contributing/testing.md
+    - Documentation Guide: contributing/documentation.md
+    
+  - Architecture:
+    - Overview: architecture/overview.md
+    - Components: architecture/components.md
+    - Design Decisions: architecture/design-decisions.md
+    
+  - Examples:
+    - Hello Flock: examples/hello-flock.md
+    - Type System Usage: examples/type-system.md
+    - Pydantic Models: examples/pydantic.md
+    - Chain Gang: examples/chain-gang.md
+"""
+
+
+def create_markdown_file(file_path: Path, title: str) -> None:
+    """Create a markdown file with a title and placeholder content."""
+    content = f"""# {title}
+
+Documentation in progress...
+"""
+    file_path.write_text(content)
+
+
+def extract_paths_from_nav(
+    nav_dict: dict, paths: list, current_path: str = ""
+) -> None:
+    """Recursively extract all markdown file paths from the nav structure."""
+    for item in nav_dict:
+        if isinstance(item, dict):
+            for key, value in item.items():
+                if isinstance(value, str):
+                    paths.append(value)
+                elif isinstance(value, list):
+                    extract_paths_from_nav(value, paths, current_path)
+
+
+def main():
+    # Parse the YAML structure
+    nav_data = yaml.safe_load(NAV_STRUCTURE)
+
+    # Extract all markdown file paths
+    markdown_paths = []
+    extract_paths_from_nav(nav_data["nav"], markdown_paths)
+
+    # Create docs directory if it doesn't exist
+    docs_dir = Path("docs")
+    docs_dir.mkdir(exist_ok=True)
+
+    # Create all necessary directories and markdown files
+    for md_path in markdown_paths:
+        # Convert path to Path object relative to docs directory
+        full_path = docs_dir / md_path
+
+        # Create parent directories if they don't exist
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Generate title from the filename
+        title = os.path.splitext(full_path.name)[0].replace("-", " ").title()
+
+        # Create the markdown file
+        create_markdown_file(full_path, title)
+        print(f"Created: {full_path}")
+
+
+if __name__ == "__main__":
+    main()

flock_core-0.2.18/docs/deployment/monitoring.md

@@ -0,0 +1,3 @@
+# Monitoring
+
+Documentation in progress...

flock_core-0.2.18/docs/deployment/production-setup.md

@@ -0,0 +1,3 @@
+# Production Setup
+
+Documentation in progress...

flock_core-0.2.18/docs/deployment/scalability.md

@@ -0,0 +1,3 @@
+# Scalability
+
+Documentation in progress...

flock_core-0.2.18/docs/deployment/security.md

@@ -0,0 +1,3 @@
+# Security
+
+Documentation in progress...

flock_core-0.2.18/docs/examples/chain-gang.md

@@ -0,0 +1,3 @@
+# Chain Gang
+
+Documentation in progress...

flock_core-0.2.18/docs/examples/hello-flock.md

@@ -0,0 +1,3 @@
+# Hello Flock
+
+Documentation in progress...

flock_core-0.2.18/docs/examples/pydantic.md

@@ -0,0 +1,3 @@
+# Pydantic
+
+Documentation in progress...

flock_core-0.2.18/docs/examples/type-system.md

@@ -0,0 +1,3 @@
+# Type System
+
+Documentation in progress...

flock_core-0.2.18/docs/features/agent-chaining.md

@@ -0,0 +1,3 @@
+# Agent Chaining
+
+Documentation in progress...

flock_core-0.2.18/docs/features/agent-definition.md

@@ -0,0 +1,3 @@
+# Agent Definition
+
+Documentation in progress...

flock_core-0.2.18/docs/features/lifecycle-hooks.md

@@ -0,0 +1,3 @@
+# Lifecycle Hooks
+
+Documentation in progress...

flock_core-0.2.18/docs/features/pydantic.md

@@ -0,0 +1,3 @@
+# Pydantic
+
+Documentation in progress...

flock_core-0.2.18/docs/features/type-safety.md

@@ -0,0 +1,3 @@
+# Type Safety
+
+Documentation in progress...

flock_core-0.2.18/docs/getting-started/concepts.md

@@ -0,0 +1,3 @@
+# Concepts
+
+Documentation in progress...

flock_core-0.2.18/docs/getting-started/configuration.md

@@ -0,0 +1,3 @@
+# Configuration
+
+Documentation in progress...

flock_core-0.2.18/docs/getting-started/installation.md

@@ -0,0 +1,3 @@
+# Installation
+
+Documentation in progress...

flock_core-0.2.18/docs/getting-started/quickstart.md

@@ -0,0 +1,3 @@
+# Quickstart
+
+Documentation in progress...

flock_core-0.2.18/docs/index.md

@@ -0,0 +1,92 @@
+# Welcome to Flock
+
+<p align="center">
+<img src="assets/images/flock.png" width="600"><br>
+
+Flock is a powerful framework for orchestrating LLM-powered agents that takes a fresh approach to agent development. Instead of wrestling with complex prompts, you simply declare what your agents need and what they should produce—Flock handles the rest.
+
+## Why Flock?
+
+Flock transforms how you build and deploy LLM-powered agents through its innovative declarative approach:
+
+### 🎯 Declarative Agent Definitions
+Instead of writing lengthy, brittle prompts, simply specify:
+- What inputs your agent needs
+- What outputs it should produce
+- Let Flock handle the rest
+
+### ⚡ Built with platforming in mind
+- **Fault Tolerance**: Built-in retries and error handling through Temporal integration
+- **State Management**: Robust handling of agent state and workflows
+- **Automatic Recovery**: Self-healing capabilities for production deployments
+
+### 🔄 Flexible & Scalable
+- Dynamic agent chaining and hand-offs
+- Modular, concurrent, and batch processing
+- Easily adaptable to changing requirements
+
+## Key Innovations
+
+### 🎨 Declarative Agent System
+Just like ordering a pizza—you specify what you want, not the 30 steps to make it! Thanks to LLMs, Flock can figure out those steps automatically. Define agents through clear input/output interfaces using concise syntax, and let Flock handle the complexity.
+
+### 🔒 Type Safety & Clear Contracts
+- Built on Pydantic models for robust type safety
+- Automatic JSON serialization/deserialization
+- Clear contracts for inputs and outputs
+- Simplified testing and validation
+
+### 🛠 Unparalleled Flexibility
+Every aspect of an agent can be customized:
+- Lifecycle hooks (`initialize()`, `terminate()`, `evaluate()`, `on_error()`)
+- Setup and cleanup procedures
+- Error handling strategies
+- Dynamic property configuration
+
+### ⚙️ Deployment with Temporal
+- Automatic retries
+- Durable state management
+- Resilient workflows
+- Built-in monitoring and observability
+
+### 🔍 Observability with Open Telemetry and Temporal
+- Tracing of all events
+- Supports Jaeger, SQL and File Sinks out of the box
+- Built-in monitoring and observability
+
+## Quick Start
+
+```python
+from flock.core import Flock, FlockAgent
+
+MODEL = "openai/gpt-4"
+
+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"}
+)
+```
+
+## Ready to Get Started?
+
+Check out our guides:
+- [Quick Start Guide](getting-started/quickstart.md)
+- [Core Concepts](core-concepts/agents.md)
+- [Examples](examples/hello-flock.md)
+
+## Join the Flock!
+
+Flock is actively developed and maintained by [whiteduck](https://whiteduck.de). We welcome contributions and feedback from the community as we build the next generation of reliable, production-ready AI agent systems.
+
+---
+
+For detailed documentation on specific features, explore our sidebar navigation. Let's build something amazing together! 🚀

flock_core-0.2.18/docs/integrations/dspy.md

@@ -0,0 +1,3 @@
+# Dspy
+
+Documentation in progress...

flock_core-0.2.18/docs/integrations/litellm.md

@@ -0,0 +1,3 @@
+# Litellm
+
+Documentation in progress...

flock_core-0.2.18/docs/integrations/tavily.md

@@ -0,0 +1,3 @@
+# Tavily
+
+Documentation in progress...