flock-core 0.3.3__tar.gz → 0.3.5__tar.gz

{flock_core-0.3.3 → flock_core-0.3.5}/.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.3 → flock_core-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.3.3
+Version: 0.3.5
 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
@@ -34,6 +35,7 @@ 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-tools
 Requires-Dist: docling>=2.18.0; extra == 'all-tools'

flock_core-0.3.5/docs/core-concepts/evaluators.md

@@ -0,0 +1 @@
+# Evaluators

flock_core-0.3.5/docs/core-concepts/modules.md

@@ -0,0 +1 @@
+# Modules

{flock_core-0.3.3 → flock_core-0.3.5}/docs/getting-started/quickstart.md

@@ -68,7 +68,7 @@ flock = Flock(
 )
 
 # Meet your new AI friend
-bloggy = FlockAgent(
+bloggy = FlockFactory.create_default_agent(
     name="bloggy",
     input="topic",
     output="catchy_title, blog_headers"
@@ -106,12 +106,13 @@ Let's break down the magic:
 
 2. **Creating Your First Agent**:
    ```python
-   bloggy = FlockAgent(
+   bloggy = FlockFactory.create_default_agent(
         name="bloggy",
         input="topic",
         output="catchy_title, blog_headers"
     )
    ```
+   The FlockFactory is churning out your agents.
    Think of this as defining your agent's job description - what they need and what they'll create.
 
 3. **Action Time!**:
@@ -149,7 +150,7 @@ Also the agent itself offers a description field.
 
 ```python
 # Your agent just got an upgrade!
-bloggy = FlockAgent(
+bloggy = FlockFactory.create_default_agent(
             name="bloggy",
             input="topic",
             description="Bloggy creates fun blog outlines for any given topic",

flock_core-0.3.5/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.3 → flock_core-0.3.5}/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.5/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.3 → flock_core-0.3.5}/examples/01_introduction/04_descriptions.py

@@ -1,14 +1,3 @@
-"""
-Title: Getting into the details with descriptions
-
-Perhaps your co-worker who loves writing blog post long prompts for his agents thought he has found an out:
-"Due to my long prompts I can make my agents do anything I want, which is not possible with your little declarative flocky!" he proclaimed.
-"What do you do when you need your agents to handle edge cases?" he asked. 
-
-You, being the flocky expert, decided to show him how to use 'descriptions' to make your agents do anything his agents can do and more.
-"""
-
-
 from flock.core import Flock, FlockFactory
  
 flock = Flock()

{flock_core-0.3.3 → flock_core-0.3.5}/examples/01_introduction/05_typed_output2.py

@@ -1,21 +1,3 @@
-"""
-Title: Random User List Generator with Data Class Integration and Caching
-
-In this example, you'll see a simple Flock agent in action that generates a list of random users.
-This example demonstrates several cool features:
-  - **Data Class Integration:** We define a `RandomPerson` dataclass to structure the random user data.
-  - **Caching:** Enabled caching ensures that if you run the agent with the same input,
-    it will return a cached result—ideal for speeding up repeated requests.
-  - **Simple Agent Declaration:** Like all Flock agents, this one declares what it needs 
-    ("amount_of_people") and what it produces ("random_user_list: list[RandomPerson]") 
-    without the hassle of prompt engineering.
-
-In this scenario, our agent ("people_agent") takes the number of people to generate as input,
-and returns a list of randomly generated users. We then print the number of generated users.
-Let's see how it's done!
-"""
-
-
 from dataclasses import dataclass
 from pprint import pprint
 from typing import Literal

flock_core-0.3.5/examples/01_introduction/06_simple_hand_off.py

@@ -0,0 +1,31 @@
+from flock.core import Flock, FlockFactory
+
+
+
+flock = Flock()
+
+idea_agent = FlockFactory.create_default_agent(
+    name="idea_agent",
+    input="query",
+    output="a_fun_software_project_idea",
+    enable_rich_tables=True,
+    wait_for_input=True,
+)
+
+project_plan_agent = FlockFactory.create_default_agent(
+    name="project_plan_agent",
+    input="a_fun_software_project_idea",
+    output="catchy_project_name, project_pitch, techstack, project_implementation_plan",
+    enable_rich_tables=True,
+    wait_for_input=True,
+)
+
+idea_agent.hand_off = project_plan_agent
+
+flock.run(
+    input={"query": "fun software project idea about ducks"},
+    start_agent=idea_agent,
+    agents=[idea_agent,project_plan_agent]
+)
+
+

flock_core-0.3.5/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.5/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.3 → flock_core-0.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.3.3"
+version = "0.3.5"
 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",
@@ -39,6 +40,7 @@ dependencies = [
     "tiktoken>=0.8.0",
     "toml>=0.10.2",
     "tqdm>=4.67.1",
+    "uvicorn>=0.34.0",
     "zep-python>=2.0.2",
 ]
 

{flock_core-0.3.3 → flock_core-0.3.5}/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.3 → flock_core-0.3.5}/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.5/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.3 → flock_core-0.3.5}/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.3"
+version = "0.3.5"
 source = { editable = "." }
 dependencies = [
     { name = "cloudpickle" },
     { name = "devtools" },
     { name = "dspy" },
     { name = "duckduckgo-search" },
+    { name = "fastapi" },
     { name = "httpx" },
     { name = "loguru" },
     { name = "matplotlib" },
@@ -1061,6 +1076,7 @@ dependencies = [
     { name = "tiktoken" },
     { name = "toml" },
     { name = "tqdm" },
+    { name = "uvicorn" },
     { name = "zep-python" },
 ]
 
@@ -1108,6 +1124,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" },
@@ -1134,6 +1151,7 @@ requires-dist = [
     { name = "tiktoken", specifier = ">=0.8.0" },
     { name = "toml", specifier = ">=0.10.2" },
     { name = "tqdm", specifier = ">=4.67.1" },
+    { name = "uvicorn", specifier = ">=0.34.0" },
     { name = "zep-python", specifier = ">=2.0.2" },
 ]
 provides-extras = ["all-tools", "tools"]