flock-core 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

flock/workflow/temporal_setup.py

@@ -1,37 +1,38 @@
-import asyncio
-import uuid
-
-from temporalio.client import Client
-from temporalio.worker import Worker
-
-
-async def create_temporal_client() -> Client:
-    client = await Client.connect("localhost:7233")
-    return client
-
-async def setup_worker(workflow,activity) -> Client:
-    worker_client = await create_temporal_client()
-    worker = Worker(worker_client, task_queue="flock-queue", workflows=[workflow], activities=[activity])
-    asyncio.create_task(worker.run())
-    await asyncio.sleep(1)
-
-
-async def run_worker(client: Client, task_queue: str, workflows, activities):
-    worker = Worker(client, task_queue=task_queue, workflows=workflows, activities=activities)
-    await worker.run()
-
-
-async def run_activity(client: Client, name: str, func, param):
-    run_id = f"{name}_{uuid.uuid4().hex[:4]}"
-
-    try:
-        result = await client.execute_activity(
-            func,
-            param,
-            id=run_id,
-            task_queue="flock-queue",
-            start_to_close_timeout=300,  # e.g., 5 minutes
-        )
-        return result
-    except Exception:
-        raise
+import asyncio
+import uuid
+
+from temporalio.client import Client
+from temporalio.worker import Worker
+
+
+async def create_temporal_client() -> Client:
+    client = await Client.connect("localhost:7233")
+    return client
+
+
+async def setup_worker(workflow, activity) -> Client:
+    worker_client = await create_temporal_client()
+    worker = Worker(worker_client, task_queue="flock-queue", workflows=[workflow], activities=[activity])
+    asyncio.create_task(worker.run())
+    await asyncio.sleep(1)
+
+
+async def run_worker(client: Client, task_queue: str, workflows, activities):
+    worker = Worker(client, task_queue=task_queue, workflows=workflows, activities=activities)
+    await worker.run()
+
+
+async def run_activity(client: Client, name: str, func, param):
+    run_id = f"{name}_{uuid.uuid4().hex[:4]}"
+
+    try:
+        result = await client.execute_activity(
+            func,
+            param,
+            id=run_id,
+            task_queue="flock-queue",
+            start_to_close_timeout=300,  # e.g., 5 minutes
+        )
+        return result
+    except Exception:
+        raise

flock/workflow/workflow.py

@@ -1,53 +1,58 @@
-from datetime import timedelta
-
-from temporalio import workflow
-
-from flock.core.context import FlockContext
-from flock.core.logging import flock_logger
-from flock.workflow.activities import run_agent
-
-# Import activity, passing it through the sandbox without reloading the module
-with workflow.unsafe.imports_passed_through():
-    from flock.workflow.activities import run_agent
-
-
-@workflow.defn
-class FlockWorkflow:
-    def __init__(self) -> None:
-        self.context = None
-
-    @workflow.run
-    async def run(self, context_dict: dict) -> dict:
-        self.context = FlockContext.from_dict(context_dict)
-        self.context.workflow_id = workflow.info().workflow_id
-        self.context.workflow_timestamp = workflow.info().start_time.strftime("%Y-%m-%d %H:%M:%S")
-
-        try:
-            flock_logger.set_context(workflow_id=self.context.workflow_id)
-            flock_logger.workflow_event(f"Starting workflow execution at {self.context.workflow_timestamp}")
-
-            result = await workflow.execute_activity(
-                run_agent, self.context, start_to_close_timeout=timedelta(minutes=5)
-            )
-
-            self.context.set_variable(
-                "flock.result",
-                {
-                    "result": result,
-                    "success": True,
-                },
-            )
-
-            flock_logger.workflow_event("Workflow completed successfully")
-            return result
-
-        except Exception as e:
-            flock_logger.error(f"Workflow execution failed: {e}")
-            self.context.set_variable(
-                "flock.result",
-                {
-                    "result": f"Failed: {e}",
-                    "success": False,
-                },
-            )
-            return self.context
+from datetime import timedelta
+
+from temporalio import workflow
+
+from flock.core.context.context import FlockContext
+from flock.core.logging.logging import get_logger
+from flock.workflow.activities import run_agent
+
+# Import activity, passing it through the sandbox without reloading the module
+
+
+logger = get_logger("workflow")
+
+
+@workflow.defn
+class FlockWorkflow:
+    def __init__(self) -> None:
+        self.context = None
+
+    @workflow.run
+    async def run(self, context_dict: dict) -> dict:
+        self.context = FlockContext.from_dict(context_dict)
+        self.context.workflow_id = workflow.info().workflow_id
+        self.context.workflow_timestamp = workflow.info().start_time.strftime("%Y-%m-%d %H:%M:%S")
+
+        try:
+            logger.info(
+                "Starting workflow execution",
+                timestamp=self.context.workflow_timestamp,
+            )
+
+            result = await workflow.execute_activity(
+                run_agent,
+                self.context,
+                start_to_close_timeout=timedelta(minutes=5),
+            )
+
+            self.context.set_variable(
+                "flock.result",
+                {
+                    "result": result,
+                    "success": True,
+                },
+            )
+
+            logger.success("Workflow completed successfully")
+            return result
+
+        except Exception as e:
+            logger.exception("Workflow execution failed", error=str(e))
+            self.context.set_variable(
+                "flock.result",
+                {
+                    "result": f"Failed: {e}",
+                    "success": False,
+                },
+            )
+            return self.context

flock_core-0.2.1.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: flock-core
+Version: 0.2.1
+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: cloudpickle>=3.1.1
+Requires-Dist: devtools>=0.12.2
+Requires-Dist: dspy==2.5.42
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: msgpack>=1.1.0
+Requires-Dist: pydantic>=2.10.5
+Requires-Dist: python-box>=7.3.2
+Requires-Dist: rich>=13.9.4
+Requires-Dist: temporalio>=1.9.0
+Requires-Dist: toml>=0.10.2
+Provides-Extra: all-tools
+Requires-Dist: docling>=2.18.0; extra == 'all-tools'
+Requires-Dist: markdownify>=0.14.1; extra == 'all-tools'
+Requires-Dist: tavily-python>=0.5.0; extra == 'all-tools'
+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
+
+<p align="center">
+<img src="docs/img/flock.png" width="600"><br>
+<h1 align="center">Flock</h1><br>
+
+
+## Overview
+
+Flock is a framework for orchestrating LLM-powered agents. It leverages a **declarative approach** where you simply specify what each agent needs as input and what it produces as output—without having to write lengthy, brittle prompts. Under the hood, Flock transforms these declarations into robust workflows, using cutting-edge components such as Temporal and DSPy to handle fault tolerance, state management, and error recovery.
+
+
+
+| Traditional Agent Frameworks 🙃          |                        Flock 🐤🐧🐓🦆                         |
+|------------------------------------------|--------------------------------------------------------------|
+| 🤖 **Complex Prompt Engineering**         | 📝 **Declarative Agent Definitions**                         |
+| • Lengthy, brittle prompts               | • Clear, concise input/output declarations                   |
+| • Hard-to-tune and adapt                 | • No need for manual prompt engineering                      |
+|                                          |                                                              |
+| 💥 **Fragile Execution**                  | ⚡ **Robust & Scalable**                                      |
+| • Single failure can break the system    | • Fault-tolerant with built-in retries and error handling      |
+| • Difficult to monitor and recover       | • Automatic recovery via Temporal workflow integration         |
+|                                          |                                                              |
+| 🏗️ **Rigid Workflows**                    | 🔄 **Flexible Orchestration**                                |
+| • Limited adaptability                   | • Dynamic agent chaining and hand-offs                       |
+| • Hard to scale and parallelize          | • Modular, concurrent, and batch processing                   |
+|                                          |                                                              |
+
+
+## Key Innovations
+
+- **Declarative Agent System:**  
+  Define agents by declaring their input/output interfaces (with type hints and human-readable descriptions) using a concise syntax.  
+
+
+  <img src="docs/img/examples/01_01.png" width="300"><br>
+
+
+  Example syntax:
+  ```python
+  input = "query: str|The search query, context: dict|The full conversation context"
+  output = "idea: str|The generated software project idea"
+  ```
+  The framework automatically extracts type and description details, builds precise prompts, and configures the underlying LLM.
+
+- **Lifecycle Hooks:**  
+  Each agent (via the new `FlockAgent` base class) supports lifecycle hooks such as `initialize()`, `terminate()`, and `on_error()`. This ensures that agents can perform setup, cleanup, and robust error handling—all without cluttering the main business logic.
+
+- **Fault Tolerance & Temporal Integration:**  
+  Flock is built with production readiness in mind. By integrating with Temporal, your agent workflows enjoy automatic retries, durable state management, and resilience against failures. This means that a single agent crash won't bring down your entire system.
+
+- **Type Safety and Clear Contracts:**  
+  Agents are implemented as Pydantic models. This provides automatic JSON serialization/deserialization, strong typing, and an explicit contract for inputs and outputs. Testing, validation, and integration become straightforward.
+
+- **DSPy Integration:**  
+  Flock leverages DSPy for managing LLM interactions. The framework constructs clean signature strings and updates field metadata so that DSPy can include detailed instructions and context for each agent call.
+
+## Quick Start
+
+Below is a simple example of how to create and run an agent with Flock:
+
+```python
+import asyncio
+from flock.core.flock import Flock
+from flock.core.agents.flock_agent import FlockAgent
+from flock.core.tools import basic_tools
+
+async def main():
+    # Initialize Flock
+    flock = Flock(model="openai/gpt-4o")
+
+    # Create an agent with clear input/output declarations and optional tools.
+    idea_agent = FlockAgent(
+        name="idea_agent",
+        input="query: str|The search query, context: dict|Additional context",
+        output="a_fun_software_project_idea: str|The generated software project idea",
+        tools=[basic_tools.web_search_tavily],
+    )
+    flock.add_agent(idea_agent)
+
+    # Run the agent locally (with built-in debugging/logging)
+    result = await flock.run_async(
+        start_agent=idea_agent,
+        input="build a revolutionary app",
+        local_debug=True
+    )
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Agents with Lifecycle Hooks
+
+Customize behavior by overriding lifecycle methods:
+
+- **initialize(inputs):** Set up resources, validate inputs, or log pre-run state.
+- **terminate(inputs, result):** Clean up resources, log output, or perform post-run actions.
+- **on_error(error, inputs):** Handle exceptions gracefully, log detailed error information, and trigger recovery logic.
+
+### Agents with Tools
+
+Agents can seamlessly integrate external tools for enhanced functionality:
+
+```python
+from flock.core.tools import basic_tools
+
+research_agent = FlockAgent(
+    name="research_agent",
+    input="research_topic: str|Topic to investigate",
+    output="research_result: str|The outcome of the research",
+    tools=[basic_tools.web_search_tavily],
+)
+```
+
+### Agent Chaining
+
+Chain agents together to create complex workflows:
+
+```python
+# Define the first agent in the chain.
+project_plan_agent = FlockAgent(
+    name="project_plan_agent",
+    input="project_idea: str|Initial project idea",
+    output="plan_headings: list[str]|Headings for the project plan",
+    tools=[basic_tools.web_search_tavily, basic_tools.code_eval],
+)
+
+# Define a second agent that builds on the output of the first.
+content_agent = FlockAgent(
+    name="content_agent",
+    input="context: dict|Global context, project_plan_agent.plan_headings: list[str]|Plan headings",
+    output="project_plan_content: str|Detailed content for the plan",
+)
+
+# Set up hand-off from the first agent to the second.
+project_plan_agent.hand_off = content_agent
+```
+
+### Temporal Workflow Integration
+
+Flock supports execution on Temporal, ensuring robust, fault-tolerant workflows:
+
+- **Durability:** Persistent state management even in the case of failures.
+- **Retries & Error Handling:** Automatic recovery via Temporal's built-in mechanisms.
+- **Scalability:** Seamless orchestration of distributed agent workflows.
+
+## Architecture
+
+TODO: Insert charts
+
+## Requirements
+
+- Python 3.12+
+- (Optional) Temporal server running locally for production-grade workflow features
+- API keys for integrated services
+
+
+recommended services
+```bash
+export OPENAI_API_KEY=sk-proj-
+export TAVILY_API_KEY=tvly-
+```
+
+or in `.env`
+
+For LLM interaction LiteLLM is getting used. Please refer to its documentation on how to easily use other models and/or provider.
+
+https://docs.litellm.ai/docs/providers
+
+## Installation
+
+```bash
+pip install flock-core
+```
+
+if you want to use the integrated tools
+
+```bash
+pip install flock-core[tools]
+```
+
+and for the docling tools
+
+```bash
+pip install flock-core[all-tools]
+```
+
+## Development
+
+
+1. **Clone the Repository:**
+
+   ```bash
+   git clone https://github.com/yourusername/flock.git
+   cd flock
+   ```
+
+2. **Create a Virtual Environment and sync all packages:**
+
+   ```bash
+   uv sync --all-groups --all-extras
+   ```
+
+3. **Install local version of flock:**
+
+   ```bash
+   uv build && uv pip install -e .
+   ```
+
+
+## Contributing
+
+Contributions are welcome! Please submit Pull Requests and open issues on GitHub.
+
+## License
+
+This project is licensed under the terms of the LICENSE file included in the repository.
+
+## Acknowledgments
+
+- Built with [DSPy](https://github.com/stanfordnlp/dspy)
+- Uses [Temporal](https://temporal.io/) for workflow management
+- Integrates with [Tavily](https://tavily.com/) for web search capabilities
+- Web interface built with FastHTML and MonsterUI
+
+## Evolution & Future Direction
+
+Flock was created to overcome the limitations of traditional agent frameworks. Key design goals include:
+
+### Declarative Over Prompt Engineering
+
+- **Simplify Agent Definitions:**  
+  Focus on clear input/output contracts rather than long, complex prompts.
+- **Model Agnostic:**  
+  Change LLM backends without altering agent logic.
+- **Improved Testability:**  
+  Clear, structured interfaces facilitate unit testing and validation.
+
+### Robust, Production-Grade Orchestration
+
+- **Fault Tolerance:**  
+  Leveraging Temporal for automatic retries, durable state, and robust error handling.
+- **Scalability:**  
+  Support for concurrent, batch, and distributed workflows.
+- **Observability:**  
+  Built-in logging and monitoring for real-time insights into workflow execution.
+
+### Future Enhancements
+
+- Expanded type system for richer agent interactions
+- Enhanced tool ecosystem and custom integrations
+- Advanced monitoring, debugging, and performance metrics
+- Extended testing frameworks and validation tools
+
+Join us in building the next generation of reliable, production-ready AI agent systems!
+