flock-core 0.5.0b8__tar.gz → 0.5.0b9__tar.gz

flock_core-0.5.0b9/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: flock-core
+Version: 0.5.0b9
+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
+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.

flock_core-0.5.0b9/README.md

@@ -0,0 +1,209 @@
+<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.

{flock_core-0.5.0b8 → flock_core-0.5.0b9}/legacy/routers/conditional/conditional_router.py

@@ -115,6 +115,10 @@ class ConditionalRouterConfig(FlockRouterConfig):
         default="flock.assertion_feedback",  # Useful if paired with AssertionCheckerModule
         description="Optional context key containing feedback message to potentially include when retrying.",
     )
+    feedback_on_failure: str | None = Field(
+        default=None,
+        description="Default feedback message to use when condition evaluation fails.",
+    )
     retry_count_context_key_prefix: str = Field(
         default="flock.conditional_retry_count_",
         description="Internal prefix for context key storing retry attempts per agent.",

{flock_core-0.5.0b8 → flock_core-0.5.0b9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.5.0b8"
+version = "0.5.0b9"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [

{flock_core-0.5.0b8 → flock_core-0.5.0b9}/src/flock/webapp/app/services/sharing_store.py

@@ -4,6 +4,7 @@ import logging
 import sqlite3
 from abc import ABC, abstractmethod
 from pathlib import Path
+from typing import Any
 
 import aiosqlite
 
@@ -227,7 +228,7 @@ class SQLiteSharedLinkStore(SharedLinkStoreInterface):
         except sqlite3.Error as e:
             logger.error(f"SQLite error saving feedback {record.feedback_id}: {e}", exc_info=True)
             raise
-# flock/webapp/app/services/sharing_store.py  ← replace only this class
+
 
 # ---------------------------------------------------------------------------
 # Azure Table + Blob implementation
@@ -366,14 +367,42 @@ class AzureTableSharedLinkStore(SharedLinkStoreInterface):
 
     # -------------------------------------------------------- save_feedback --
     async def save_feedback(self, record: FeedbackRecord) -> FeedbackRecord:
+        """Persist a feedback record. If a flock_definition is present, upload it as a blob and
+        store only a reference in the table row to avoid oversized entities (64 KiB limit).
+        """
         tbl_client = self.table_svc.get_table_client(self._FEEDBACK_TBL_NAME)
-        entity = {
+
+        # Core entity fields (avoid dumping the full Pydantic model – too many columns / large value)
+        entity: dict[str, Any] = {
             "PartitionKey": "feedback",
             "RowKey":       record.feedback_id,
-            **record.model_dump(exclude={"feedback_id"})  # all other fields
+            "share_id":     record.share_id,
+            "context_type": record.context_type,
+            "reason":       record.reason,
+            "expected_response": record.expected_response,
+            "actual_response":   record.actual_response,
+            "created_at":   record.created_at.isoformat(),
         }
+        if record.flock_name is not None:
+            entity["flock_name"] = record.flock_name
+        if record.agent_name is not None:
+            entity["agent_name"] = record.agent_name
+
+        # ------------------------------------------------------------------ YAML → Blob
+        if record.flock_definition:
+            blob_name   = f"{record.feedback_id}.yaml"
+            blob_client = self.blob_svc.get_blob_client(self._CONTAINER_NAME, blob_name)
+            # Overwrite=true so repeated feedback_id uploads (shouldn't happen) won't error
+            await blob_client.upload_blob(record.flock_definition,
+                                          overwrite=True,
+                                          content_type="text/yaml")
+            entity["flock_blob_name"] = blob_name  # lightweight reference only
+
+        # ------------------------------------------------------------------ Table upsert
         await tbl_client.upsert_entity(entity)
-        logger.info("Saved feedback %s", record.feedback_id)
+        logger.info("Saved feedback %s%s",
+                    record.feedback_id,
+                    f" → blob '{entity['flock_blob_name']}'" if "flock_blob_name" in entity else "")
         return record
 
 

{flock_core-0.5.0b8 → flock_core-0.5.0b9}/uv.lock

@@ -960,7 +960,7 @@ wheels = [
 
 [[package]]
 name = "flock-core"
-version = "0.5.0b8"
+version = "0.5.0b9"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },