flock-core 0.3.2__tar.gz → 0.3.4__tar.gz

{flock_core-0.3.2 → flock_core-0.3.4}/.vscode/settings.json

@@ -3,11 +3,9 @@
         "tests"
     ],
     "python.envFile": "${workspaceFolder}/.env",
-    "python.terminal.run_asyncEnvInCurrentTerminal": true,
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true,
     "python.testing.autoTestDiscoverOnSaveEnabled": true,
-    "shiny.python.debugJustMyCode": false,
     "editor.formatOnSave": true,
     "editor.codeActionsOnSave": {
         "source.organizeImports.ruff": "always",
@@ -22,7 +20,7 @@
     "editor.fontSize": 15.5,
     "editor.fontLigatures": true,
     //"editor.lineHeight": 1.5,
-    "editor.minimap.enabled": false,
+    "editor.minimap.enabled": true,
     "editor.tabSize": 2,
     "editor.semanticTokenColorCustomizations": {
         "enabled": true
@@ -30,7 +28,7 @@
     "editor.semanticHighlighting.enabled": true,
     // we try to make semantic highlighting look good
     // prevent VSCode from modifying the terminal colors
-    "terminal.integrated.minimumContrastRatio": 0,
+    "terminal.integrated.minimumContrastRatio": 1,
     "cSpell.words": [
         "deptry",
         "gradio",

{flock_core-0.3.2 → flock_core-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.3.2
+Version: 0.3.4
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -12,6 +12,7 @@ Requires-Dist: cloudpickle>=3.1.1
 Requires-Dist: devtools>=0.12.2
 Requires-Dist: dspy==2.5.42
 Requires-Dist: duckduckgo-search>=7.3.2
+Requires-Dist: fastapi>=0.115.8
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: matplotlib>=3.10.0

{flock_core-0.3.2 → flock_core-0.3.4}/docs/release-notes/release_notes.md

@@ -114,7 +114,7 @@ pip install flock-core>=0.3.0
 
 ---  
 
-📖 **Full documentation**: [docs.flock.ai](https://docs.flock.ai)  
-💻 **GitHub**: [github.com/flock-ai](https://github.com/flock-ai)  
+📖 **Full documentation**: [https://whiteducksoftware.github.io/flock](https://whiteducksoftware.github.io/flock)  
+💻 **GitHub**: [https://github.com/whiteducksoftware/flock](https://github.com/whiteducksoftware/flock)  
 
 

flock_core-0.3.4/examples/01_introduction/01_simple_example.py

@@ -0,0 +1,43 @@
+from flock.core import Flock, FlockFactory
+from flock.core.flock_api import FlockAPI
+
+
+# --------------------------------
+# Define the model
+# --------------------------------
+# Flock uses litellm to talk to LLMs
+# Please consult the litellm documentation for valid IDs:
+# https://docs.litellm.ai/docs/providers
+MODEL = "openai/gpt-4o"
+
+
+# --------------------------------
+# Create the flock and context
+# --------------------------------
+# The flock is the place where all the agents are at home
+flock = Flock(model=MODEL)
+
+# --------------------------------
+# Create an agent
+# --------------------------------
+# The Flock doesn't believe in prompts (see the docs for more info)
+# The Flock just declares what agents get in and what agents produce
+# bloggy takes in a blog_idea and outputs a funny_blog_title 
+# and blog_headers
+bloggy = FlockFactory.create_default_agent(
+    name="bloggy",
+    input="blog_idea",
+    output="funny_blog_title, blog_headers",
+)
+flock.add_agent(bloggy)
+
+
+# --------------------------------
+# Run the flock
+# --------------------------------
+# Tell the flock who is the starting and what input to give it
+flock.run(
+    start_agent=bloggy, 
+    input={"blog_idea": "A blog about cats"}
+)
+

{flock_core-0.3.2 → flock_core-0.3.4}/examples/01_introduction/02_typed_output.py

@@ -1,25 +1,3 @@
-"""
-Title: Advanced Flock Agent with Caching, Type Hints, and Tool Integration
-
-In this example, we'll show you how to build a more advanced Flock system that:
-  - Uses a custom output formatter (RichTables) for a polished, swaggy display.
-  - Defines output types using standard Python type hints (including lists and Literals) for structured results.
-  - Integrates external tools (like a web content scraper) so that agents can perform more complex operations.
-  - Leverages caching so that if an agent is called with the same input, the cached result is returned—this is particularly
-    useful for expensive operations such as web scraping or during debugging.
-
-The agent in this example takes a URL as input and outputs:
-  - A title,
-  - A list of headings,
-  - A list of dictionaries mapping entities to metadata, and
-  - A type (limited to one of 'news', 'blog', 'opinion piece', or 'tweet').
-
-After executing the agent, you can work with the result as a real Python object that respects the defined types.
-
-Let's dive in!
-"""
-
-
 from pprint import pprint
 
 from flock.core import Flock, FlockFactory

flock_core-0.3.4/examples/01_introduction/03_tool_and_code_agent.py

@@ -0,0 +1,40 @@
+from flock.core import Flock, FlockFactory
+
+from flock.core.logging.formatters.themes import OutputTheme
+from flock.core.tools import basic_tools
+
+
+# --------------------------------
+# Create the flock
+# --------------------------------
+flock = Flock()
+
+
+# --------------------------------
+# Tools
+# --------------------------------
+# Let's talk about tools
+# A FlockAgent has a tools argument that takes in ANY callable
+# like the ones in flock.core.tools.basic_tools
+# or your own custom tools
+agent = FlockFactory.create_default_agent(
+    name="my_celebrity_age_agent",
+    input="a_person",
+    output="persons_age_in_days",
+    tools=[basic_tools.web_search_duckduckgo, basic_tools.code_eval],
+    enable_rich_tables=True,
+    output_theme=OutputTheme.adventuretime,
+    use_cache=True,
+)
+flock.add_agent(agent)
+
+# --------------------------------
+# Run the agent
+# --------------------------------
+# Let's calculate Johnny Depp's age in days
+flock.run(
+    start_agent=agent,
+    input={"a_person": "Johnny Depp"},
+)
+
+

flock_core-0.3.4/examples/03_misc/api/api_client.py

@@ -0,0 +1,19 @@
+import httpx
+
+from flock.core.flock_api import FlockAPIRequest
+from rich.console import Console
+from rich.pretty import Pretty
+
+
+console = Console()
+
+payload = FlockAPIRequest(agent_name="bloggy", inputs={"blog_idea": "A blog about cats"})
+
+response = httpx.post("http://127.0.0.1:8344/run/flock",content=payload.model_dump_json())
+response.raise_for_status()
+
+pretty = Pretty(response.json())
+console.print(pretty)
+
+
+

flock_core-0.3.4/examples/03_misc/api/api_server.py

@@ -0,0 +1,20 @@
+from flock.core import Flock,FlockFactory,FlockAPI
+
+
+
+MODEL = "openai/gpt-4o"
+
+flock = Flock(model=MODEL,enable_logging=True)
+
+bloggy = FlockFactory.create_default_agent(
+    name="bloggy",
+    input="blog_idea",
+    output="funny_blog_title, blog_headers",
+)
+flock.add_agent(bloggy)
+
+# Swagger: http://127.0.0.1:8344/docs
+# Redoc: http://127.0.0.1:8344/redoc
+# POST: http://127.0.0.1:8344/run 
+api = FlockAPI(flock)
+api.start()

{flock_core-0.3.2 → flock_core-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.3.2"
+version = "0.3.4"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [
@@ -17,6 +17,7 @@ dependencies = [
     "devtools>=0.12.2",
     "dspy==2.5.42",
     "duckduckgo-search>=7.3.2",
+    "fastapi>=0.115.8",
     "httpx>=0.28.1",
     "loguru>=0.7.3",
     "matplotlib>=3.10.0",

{flock_core-0.3.2 → flock_core-0.3.4}/src/flock/core/__init__.py

@@ -2,12 +2,14 @@
 
 from flock.core.flock import Flock
 from flock.core.flock_agent import FlockAgent
+from flock.core.flock_api import FlockAPI
 from flock.core.flock_evaluator import FlockEvaluator, FlockEvaluatorConfig
 from flock.core.flock_factory import FlockFactory
 from flock.core.flock_module import FlockModule, FlockModuleConfig
 
 __all__ = [
     "Flock",
+    "FlockAPI",
     "FlockAgent",
     "FlockEvaluator",
     "FlockEvaluatorConfig",

{flock_core-0.3.2 → flock_core-0.3.4}/src/flock/core/flock.py

@@ -379,6 +379,8 @@ class Flock:
             Exception: For any other errors encountered during execution.
         """
         with tracer.start_as_current_span("run_async") as span:
+            if isinstance(start_agent, str):
+                start_agent = self.registry.get_agent(start_agent)
             span.set_attribute(
                 "start_agent",
                 start_agent.name

flock_core-0.3.4/src/flock/core/flock_api.py

@@ -0,0 +1,215 @@
+"""REST API server for Flock."""
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+import uvicorn
+from fastapi import BackgroundTasks, FastAPI, HTTPException
+from pydantic import BaseModel, Field
+
+from flock.core.flock import Flock
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("api")
+
+
+class FlockAPIRequest(BaseModel):
+    """Request model for running an agent."""
+
+    agent_name: str = Field(..., description="Name of the agent to run")
+    inputs: dict[str, Any] = Field(
+        default_factory=dict, description="Input data for the agent"
+    )
+    async_run: bool = Field(
+        default=False, description="Whether to run asynchronously"
+    )
+
+
+class FlockAPIResponse(BaseModel):
+    """Response model for run requests."""
+
+    run_id: str = Field(..., description="Unique ID for this run")
+    status: str = Field(..., description="Status of the run")
+    result: dict[str, Any] | None = Field(
+        None, description="Run result if completed"
+    )
+    started_at: datetime = Field(..., description="When the run started")
+    completed_at: datetime | None = Field(
+        None, description="When the run completed"
+    )
+    error: str | None = Field(None, description="Error message if failed")
+
+
+class FlockAPI:
+    """REST API server for Flock.
+
+    Provides HTTP endpoints for:
+    - Running agents
+    - Checking run status
+    - Getting run results
+    """
+
+    def __init__(self, flock: Flock):
+        self.flock = flock
+        self.app = FastAPI(title="Flock API")
+        self.runs: dict[str, FlockAPIResponse] = {}
+
+        # Register routes
+        self._setup_routes()
+
+    def _setup_routes(self):
+        """Set up API routes."""
+
+        @self.app.post("/run/flock", response_model=FlockAPIResponse)
+        async def run_flock(
+            request: FlockAPIRequest, background_tasks: BackgroundTasks
+        ):
+            """Run an agent with the provided inputs."""
+            try:
+                # Generate run ID
+                run_id = str(uuid.uuid4())
+
+                # Create initial response
+                response = FlockAPIResponse(
+                    run_id=run_id, status="starting", started_at=datetime.now()
+                )
+                self.runs[run_id] = response
+
+                if request.async_run:
+                    # Start run in background
+                    background_tasks.add_task(
+                        self._run_flock,
+                        run_id,
+                        request.agent_name,
+                        request.inputs,
+                    )
+                    response.status = "running"
+                else:
+                    # Run synchronously
+                    await self._run_flock(
+                        run_id, request.agent_name, request.inputs
+                    )
+
+                return self.runs[run_id]
+
+            except Exception as e:
+                logger.error(f"Error starting run: {e!s}")
+                raise HTTPException(status_code=500, detail=str(e))
+
+        @self.app.post("/run/agent", response_model=FlockAPIResponse)
+        async def run_agent(
+            request: FlockAPIRequest, background_tasks: BackgroundTasks
+        ):
+            """Run an agent with the provided inputs."""
+            try:
+                # Generate run ID
+                run_id = str(uuid.uuid4())
+
+                # Create initial response
+                response = FlockAPIResponse(
+                    run_id=run_id, status="starting", started_at=datetime.now()
+                )
+                self.runs[run_id] = response
+
+                if request.async_run:
+                    # Start run in background
+                    background_tasks.add_task(
+                        self._run_agent,
+                        run_id,
+                        request.agent_name,
+                        request.inputs,
+                    )
+                    response.status = "running"
+                else:
+                    # Run synchronously
+                    await self._run_agent(
+                        run_id, request.agent_name, request.inputs
+                    )
+
+                return self.runs[run_id]
+
+            except Exception as e:
+                logger.error(f"Error starting run: {e!s}")
+                raise HTTPException(status_code=500, detail=str(e))
+
+        @self.app.get("/run/{run_id}", response_model=FlockAPIResponse)
+        async def get_run_status(run_id: str):
+            """Get the status of a run."""
+            if run_id not in self.runs:
+                raise HTTPException(status_code=404, detail="Run not found")
+            return self.runs[run_id]
+
+        @self.app.get("/agents")
+        async def list_agents():
+            """List all available agents."""
+            return {
+                "agents": [
+                    {
+                        "name": agent.name,
+                        "description": agent.description,
+                        "input_schema": agent.input,
+                        "output_schema": agent.output,
+                        "hand_off": agent.hand_off,
+                    }
+                    for agent in self.flock.agents.values()
+                ]
+            }
+
+    async def _run_agent(
+        self, run_id: str, agent_name: str, inputs: dict[str, Any]
+    ):
+        """Execute an agent run."""
+        try:
+            # Get the agent
+            if agent_name not in self.flock.agents:
+                raise ValueError(f"Agent '{agent_name}' not found")
+
+            agent = self.flock.agents[agent_name]
+
+            # Run the agent
+            result = await agent.run_async(inputs)
+
+            # Update run status
+            self.runs[run_id].status = "completed"
+            self.runs[run_id].result = result
+            self.runs[run_id].completed_at = datetime.now()
+
+        except Exception as e:
+            logger.error(f"Error in run {run_id}: {e!s}")
+            self.runs[run_id].status = "failed"
+            self.runs[run_id].error = str(e)
+            self.runs[run_id].completed_at = datetime.now()
+
+    async def _run_flock(
+        self, run_id: str, agent_name: str, inputs: dict[str, Any]
+    ):
+        """Execute an agent run."""
+        try:
+            # Get the agent
+            if agent_name not in self.flock.agents:
+                raise ValueError(f"Agent '{agent_name}' not found")
+
+            result = await self.flock.run_async(
+                start_agent=agent_name, input=inputs
+            )
+
+            # Update run status
+            self.runs[run_id].status = "completed"
+            self.runs[run_id].result = result
+            self.runs[run_id].completed_at = datetime.now()
+
+        except Exception as e:
+            logger.error(f"Error in run {run_id}: {e!s}")
+            self.runs[run_id].status = "failed"
+            self.runs[run_id].error = str(e)
+            self.runs[run_id].completed_at = datetime.now()
+
+    def start(self, host: str = "0.0.0.0", port: int = 8344):
+        """Start the API server."""
+        uvicorn.run(self.app, host=host, port=port)
+
+    async def stop(self):
+        """Stop the API server."""
+        # Cleanup if needed
+        pass

{flock_core-0.3.2 → flock_core-0.3.4}/uv.lock

@@ -987,6 +987,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7b/8f/c4d9bafc34ad7ad5d8dc16dd1347ee0e507a52c3adb6bfa8887e1c6a26ba/executing-2.2.0-py2.py3-none-any.whl", hash = "sha256:11387150cad388d62750327a53d3339fad4888b39a6fe233c3afbb54ecffd3aa", size = 26702 },
 ]
 
+[[package]]
+name = "fastapi"
+version = "0.115.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a2/b2/5a5dc4affdb6661dea100324e19a7721d5dc524b464fe8e366c093fd7d87/fastapi-0.115.8.tar.gz", hash = "sha256:0ce9111231720190473e222cdf0f07f7206ad7e53ea02beb1d2dc36e2f0741e9", size = 295403 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8f/7d/2d6ce181d7a5f51dedb8c06206cbf0ec026a99bf145edd309f9e17c3282f/fastapi-0.115.8-py3-none-any.whl", hash = "sha256:753a96dd7e036b34eeef8babdfcfe3f28ff79648f86551eb36bfc1b0bf4a8cbf", size = 94814 },
+]
+
 [[package]]
 name = "fastcore"
 version = "1.7.29"
@@ -1032,13 +1046,14 @@ wheels = [
 
 [[package]]
 name = "flock-core"
-version = "0.3.2"
+version = "0.3.4"
 source = { editable = "." }
 dependencies = [
     { name = "cloudpickle" },
     { name = "devtools" },
     { name = "dspy" },
     { name = "duckduckgo-search" },
+    { name = "fastapi" },
     { name = "httpx" },
     { name = "loguru" },
     { name = "matplotlib" },
@@ -1108,6 +1123,7 @@ requires-dist = [
     { name = "docling", marker = "extra == 'all-tools'", specifier = ">=2.18.0" },
     { name = "dspy", specifier = "==2.5.42" },
     { name = "duckduckgo-search", specifier = ">=7.3.2" },
+    { name = "fastapi", specifier = ">=0.115.8" },
     { name = "httpx", specifier = ">=0.28.1" },
     { name = "loguru", specifier = ">=0.7.3" },
     { name = "markdownify", marker = "extra == 'all-tools'", specifier = ">=0.14.1" },

flock_core-0.3.2/examples/01_introduction/01_simple_example.py

@@ -1,63 +0,0 @@
-"""
-Title: Building Your First Flock Agent
-
-In this example, we'll walk you through creating and running a simple Flock system with a single agent.
-Flock enables you to build LLM-powered agents by simply declaring what data each agent receives and what it
-produces—no more tedious prompt engineering!
-
-What you'll learn:
-  - How to set up the Flock model (using litellm; check out https://docs.litellm.ai/docs/providers for valid model IDs).
-  - How to create a Flock instance that serves as the central orchestrator and context holder.
-  - How to define a simple agent (named "bloggy") by declaring its input and output.
-  - How to add the agent to your Flock.
-  - How to run the agent workflow asynchronously in local debug mode (without needing Temporal).
-
-The "bloggy" agent in this example is designed to take a blog idea as input and generate a funny blog title
-along with a list of blog headers as output.
-
-Let's get started!
-"""
-
-from flock.core import Flock, FlockFactory
-
-
-# --------------------------------
-# Define the model
-# --------------------------------
-# Flock uses litellm to talk to LLMs
-# Please consult the litellm documentation for valid IDs:
-# https://docs.litellm.ai/docs/providers
-MODEL = "openai/gpt-4o"
-
-
-# --------------------------------
-# Create the flock and context
-# --------------------------------
-# The flock is the place where all the agents are at home
-# set local_debug to True to run the flock without Temporal
-# Check out the examples in /temporal to learn about Temporal
-flock = Flock(model=MODEL)
-
-# --------------------------------
-# Create an agent
-# --------------------------------
-# The Flock doesn't believe in prompts (see the readme for more info)
-# The Flock just declares what agents get in and what agents produce
-# bloggy takes in a blog_idea and outputs a funny_blog_title 
-# and blog_headers
-bloggy = FlockFactory.create_default_agent(
-    name="bloggy",
-    input="blog_idea",
-    output="funny_blog_title, blog_headers",
-)
-flock.add_agent(bloggy)
-
-
-# --------------------------------
-# Run the flock
-# --------------------------------
-# Tell the flock who is the starting and what input to give it
-flock.run(
-    start_agent=bloggy, 
-    input={"blog_idea": "A blog about cats"}
-)

flock_core-0.3.2/examples/01_introduction/03_tool_and_code_agent.py

@@ -1,60 +0,0 @@
-"""
-Title: Celebrity Age Calculator with Themed Output and Tool Integration
-
-In this example, you'll see an advanced Flock agent in action. This agent demonstrates several cool features:
-  - **Themed Output:** We use ThemedAgentResultFormatter with a custom theme (e.g. "adventuretime")
-    to spice up the CLI output.
-  - **Tool Integration:** The agent is configured with multiple tools, so it can, for example,
-    use web search and code evaluation to calculate some advanced maths.
-  - **Caching:** Enabled caching ensures that if you run the agent with the same input,
-    it will return a cached result—ideal for expensive operations or rapid testing.
-  - **Simple Declaration:** Just like all Flock agents, this one declares what it needs ("a_person")
-    and what it produces ("persons_age_in_days"), without the hassle of prompt engineering.
-
-In this scenario, our agent ("my_celebrity_age_agent") takes a person's name as input and returns
-that person's age in days. We then use it to calculate Johnny Depp's age in days. Very advanced maths!
-
-Let's see how it's done!
-"""
-
-
-from flock.core import Flock, FlockFactory
-
-from flock.core.logging.formatters.themes import OutputTheme
-from flock.core.tools import basic_tools
-
-
-# --------------------------------
-# Create the flock
-# --------------------------------
-flock = Flock()
-
-
-# --------------------------------
-# Tools
-# --------------------------------
-# Let's talk about tools
-# A FlockAgent has a tools argument that takes in ANY callable
-# like the ones in flock.core.tools.basic_tools
-# or your own custom tools
-agent = FlockFactory.create_default_agent(
-    name="my_celebrity_age_agent",
-    input="a_person",
-    output="persons_age_in_days",
-    tools=[basic_tools.web_search_duckduckgo, basic_tools.code_eval],
-    enable_rich_tables=True,
-    output_theme=OutputTheme.adventuretime,
-    use_cache=True,
-)
-flock.add_agent(agent)
-
-# --------------------------------
-# Run the agent
-# --------------------------------
-# Let's calculate Johnny Depp's age in days
-flock.run(
-    start_agent=agent,
-    input={"a_person": "Johnny Depp"},
-)
-
-