flock-core 0.5.0b22__tar.gz → 0.5.0b24__tar.gz

flock_core-0.5.0b24/.devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+{
+  "name": "flock dev",
+  "image": "ghcr.io/astral-sh/uv:python3.12-bookworm",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "22",
+      "nodeGypDependencies": true
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "charliermarsh.ruff"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/usr/local/bin/python",
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.formatOnSave": true,
+          "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit",
+            "source.organizeImports": "explicit"
+          }
+        }
+      }
+    }
+  },
+  "forwardPorts": [8888],
+  "postCreateCommand": "uv sync --all-groups --all-extras --frozen"
+}

{flock_core-0.5.0b22 → flock_core-0.5.0b24}/.vscode/settings.json

@@ -92,7 +92,7 @@
     ],
     "editor.guides.indentation": false,
     "python.REPL.enableREPLSmartSend": false,
-    "python-envs.defaultEnvManager": "ms-python.python:conda",
-    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.defaultEnvManager": "ms-python.python:venv",
+    "python-envs.defaultPackageManager": "ms-python.python:pip",
     "python-envs.pythonProjects": []
 }

{flock_core-0.5.0b22 → flock_core-0.5.0b24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b22
+Version: 0.5.0b24
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE

flock_core-0.5.0b24/examples/01-hello-flock.py

@@ -0,0 +1,40 @@
+from flock.cli.utils import print_header, print_subheader
+from flock.core import DefaultAgent, Flock
+
+# 1. Create the main orchestrator
+my_flock = Flock(model="openai/gpt-5-mini")  # Uses DEFAULT_MODEL from environment if set
+
+# 2. Declaratively define an agent
+prd_agent = DefaultAgent(
+    name="prd_generator",
+    description="Generates a product requirements document from a project idea",
+    input="project_idea",
+    output="catchy_title, mission_statement, mvp_scope, target_users, functional_requirements, "
+    "non_functional_requirements, milestones, epics, user_stories",
+)
+
+# 3. Add the agent to the Flock
+my_flock.add_agent(prd_agent)
+
+# 4. Run the agent!
+input_data = {"project_idea": "An agent management dashboard"}
+result = my_flock.run(agent="prd_generator", input=input_data)
+
+# The result is a real object ready for downstream tasks
+print_header(f"{result.catchy_title}")
+print_subheader("Mission Statement")
+print(f"{result.mission_statement}")
+print_subheader("MVP Scope")
+print(f"{result.mvp_scope}")
+print_subheader("Target Users")
+print(f"{result.target_users}")
+print_subheader("Functional Requirements")
+print(f"{result.functional_requirements}")
+print_subheader("Non-Functional Requirements")
+print(f"{result.non_functional_requirements}")
+print_subheader("Milestones")
+print(f"{result.milestones}")
+print_subheader("Epics")
+print(f"{result.epics}")
+print_subheader("User Stories")
+print(f"{result.user_stories}")

flock_core-0.5.0b24/examples/02a-inputs-and-outputs.py

@@ -0,0 +1,61 @@
+
+import json
+
+from flock.cli.utils import print_header, print_subheader, print_success
+from flock.core import DefaultAgent, Flock
+from flock.core.logging.logging import configure_logging
+from flock.core.registry.decorators import flock_tool
+
+MODEL = "azure/gpt-4.1"
+
+flock = Flock(
+    name="example_02a", description="The flock input and output syntax", model=MODEL
+)
+
+@flock_tool
+def save_movie_to_file(title: str, synopsis: str):
+    with open("movie.json", "w") as f:
+        json.dump({"title": title, "synopsis": synopsis}, f)
+
+
+# --------------------------------
+# Define the agent
+# --------------------------------
+# We claimed that flock doesn't care about prompts.
+# This was a little bit of clickbait of course.
+# Flock cares very much about prompts.
+# But with flock you don't prompt the agent as a whole,
+# but the properties of the input and output.
+#
+# General syntax rules:
+# "field_name: type | description"
+#
+# If you need to specify the agents behavior, you can do so with the description field.
+presentation_agent = DefaultAgent(
+    name="my_movie_agent",
+    description="Creates a fun movie about a given topic, and saves it to a file",  # Isn't just a description, but also a control mechanism
+    input="topic: str",
+    output="fun_title: str | The funny title of the movie in all caps, "
+    "runtime: int | The runtime of the movie in minutes, "
+    "synopsis: str | A crazy over the top synopsis of the movie, "
+    "characters: list[dict[str, str]] | Key is character name, Value is a character description ",
+    tools=[save_movie_to_file],
+)
+flock.add_agent(presentation_agent)
+
+
+result = flock.run(agent=presentation_agent, input={"topic": "AI agents"})
+
+# --------------------------------
+# The result
+# --------------------------------
+# The result is a boxed dictionary which enables dot-notation access to the fields.
+
+print_header("Results")
+print_subheader(result.fun_title)
+print_success(result.synopsis)
+print_success(result.characters)
+
+# YOUR TURN!
+# Try changing the types and descriptions of the input and output fields
+# What happens if agent description is at odds with the input and output fields?

flock_core-0.5.0b24/examples/02b-inputs-and-outputs.py

@@ -0,0 +1,59 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from flock.cli.utils import print_header, print_subheader, print_success
+from flock.core import DefaultAgent, Flock
+from flock.core.logging.logging import configure_logging
+from flock.core.registry import (
+    flock_type,  # Decorator for registering custom types
+)
+
+# Logging (internal logs, external logs)
+# configure_logging("DEBUG", "DEBUG")
+
+@flock_type
+class MovieIdea(BaseModel):
+    """The idea of a movie."""
+    topic: str = Field(..., description="The topic of the movie.")
+    genre: Literal["comedy", "drama", "horror", "action", "adventure"] = Field(
+        ..., description="The genre of the movie."
+    )
+
+@flock_type
+class Movie(BaseModel):
+    """The movie."""
+    fun_title: str = Field(..., description="The title of the movie.")
+    runtime: int = Field(..., description="The runtime of the movie.")
+    synopsis: str = Field(..., description="The synopsis of the movie.")
+    characters: list[dict[str, str]] = Field(
+        ..., description="The characters of the movie."
+    )
+
+
+MODEL = "azure/gpt-4.1"
+
+flock = Flock(
+    name="example_02", description="The flock input and output syntax", model=MODEL
+)
+
+
+presentation_agent = DefaultAgent(
+    name="my_movie_agent",
+    description="Creates a fun movie about a given topic",  # Isn't just a description, but also a control mechanism
+    input=MovieIdea,
+    output=Movie,
+)
+flock.add_agent(presentation_agent)
+
+
+result = flock.run(agent=presentation_agent, input=MovieIdea(topic="AI agents", genre="comedy"))
+
+print_header("Results")
+print_subheader(result.fun_title)
+print_success(result.synopsis)
+print_success(result.characters)
+
+# YOUR TURN!
+# Try changing the types and descriptions of the input and output fields
+# What happens if agent description is at odds with the input and output fields?

flock_core-0.5.0b24/examples/03-rest-api-ui.py

@@ -0,0 +1,39 @@
+# 02-core-concepts/02-pydantic-types.py
+"""
+Purpose: Demonstrate using images in Flock
+"""
+
+import os
+
+from flock.core import Flock, FlockFactory
+
+MODEL = "azure/gpt-4.1"
+
+flock = Flock(model=MODEL)
+
+
+# A whimsical agent that turns any sentence into Yoda-speak.
+yoda_agent = FlockFactory.create_default_agent(
+    name="yoda_translator",
+    input="text",
+    output="yoda_text",
+)
+flock.add_agent(yoda_agent)
+
+
+# --------------------------------
+# 2. Run Flock as a REST API
+# --------------------------------
+
+
+# This will start the Flock as a REST API and a UI
+# It will also create a OpenAPI spec
+# http://localhost:8344/docs
+
+flock.serve()
+
+
+# --- YOUR TURN! ---
+# set chat=True to enable the chat interface
+# http://localhost:8344/chat
+# try executing "flock --web" or "flock --chat" or both in your terminal

flock_core-0.5.0b24/examples/04-using-a-tool.py

@@ -0,0 +1,49 @@
+from flock.core import Flock, FlockFactory, flock_tool
+from flock.core.logging.formatters.themes import OutputTheme
+
+@flock_tool
+def write_file(string: str, file_path: str) -> None:
+  with open(file_path, "w") as f:
+    f.write(string)
+
+
+flock = Flock(model="azure/gpt-4.1")
+
+read_website_fast_mcp_server = FlockFactory.create_mcp_server(
+    name="read-website-fast-mcp-server",
+    enable_tools_feature=True,
+    connection_params=FlockFactory.StdioParams(
+        command="npx",
+        args=[
+            "-y",
+            "@just-every/mcp-read-website-fast"
+        ],
+    ),
+)
+flock.add_server(read_website_fast_mcp_server)
+
+
+agent = FlockFactory.create_default_agent(
+    name="my_agent",
+    input="url",
+    output="title, headings: list[str],"
+    "entities_and_metadata: list[dict[str, str]],"
+    "type:Literal['news', 'blog', 'opinion piece', 'tweet']",
+    servers=[read_website_fast_mcp_server],
+    tools=[write_file],
+    enable_rich_tables=True,  # Instead of the json output, you can use the rich library to render the output as a table
+    output_theme=OutputTheme.aardvark_blue,  # flock also comes with a few themes
+    use_cache=False,  # flock will cache the result of the agent and if the input is the same as before, the agent will return the cached result
+)
+flock.add_agent(agent)
+
+
+
+result = flock.run(
+    agent=agent,
+    input={
+        "url": "https://lite.cnn.com/travel/alexander-the-great-macedon-persian-empire-darius/index.html"
+    },
+)
+
+

{flock_core-0.5.0b22 → flock_core-0.5.0b24}/pyproject.toml

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

{flock_core-0.5.0b22 → flock_core-0.5.0b24}/src/flock/components/evaluation/declarative_evaluation_component.py

@@ -40,11 +40,13 @@ def _ensure_live_crop_above() -> None:
         return
 
     # Extend the accepted literal at runtime so type checks don't block the new option.
-    current_args = getattr(_lr.VerticalOverflowMethod, '__args__', ())
-    if 'crop_above' not in current_args:
-        _lr.VerticalOverflowMethod = _Literal['crop', 'crop_above', 'ellipsis', 'visible']  # type: ignore[assignment]
+    current_args = getattr(_lr.VerticalOverflowMethod, "__args__", ())
+    if "crop_above" not in current_args:
+        _lr.VerticalOverflowMethod = _Literal[
+            "crop", "crop_above", "ellipsis", "visible"
+        ]  # type: ignore[assignment]
 
-    if getattr(_lr.LiveRender.__rich_console__, '_flock_crop_above', False):
+    if getattr(_lr.LiveRender.__rich_console__, "_flock_crop_above", False):
         _live_patch_applied = True
         return
 
@@ -55,26 +57,28 @@ def _ensure_live_crop_above() -> None:
     def _patched_rich_console(self, console, options):
         renderable = self.renderable
         style = console.get_style(self.style)
-        lines = console.render_lines(renderable, options, style=style, pad=False)
+        lines = console.render_lines(
+            renderable, options, style=style, pad=False
+        )
         shape = Segment.get_shape(lines)
 
         _, height = shape
         max_height = options.size.height
         if height > max_height:
-            if self.vertical_overflow == 'crop':
-                lines = lines[: max_height]
+            if self.vertical_overflow == "crop":
+                lines = lines[:max_height]
                 shape = Segment.get_shape(lines)
-            elif self.vertical_overflow == 'crop_above':
+            elif self.vertical_overflow == "crop_above":
                 lines = lines[-max_height:]
                 shape = Segment.get_shape(lines)
-            elif self.vertical_overflow == 'ellipsis' and max_height > 0:
+            elif self.vertical_overflow == "ellipsis" and max_height > 0:
                 lines = lines[: (max_height - 1)]
                 overflow_text = Text(
-                    '...',
-                    overflow='crop',
-                    justify='center',
-                    end='',
-                    style='live.ellipsis',
+                    "...",
+                    overflow="crop",
+                    justify="center",
+                    end="",
+                    style="live.ellipsis",
                 )
                 lines.append(list(console.render(overflow_text)))
                 shape = Segment.get_shape(lines)
@@ -126,9 +130,13 @@ class DeclarativeEvaluationConfig(AgentComponentConfig):
         description="Extraction LM for TwoStepAdapter when adapter='two_step'",
     )
     stream_callbacks: list[Callable[..., Any] | Any] | None = None
-    stream_vertical_overflow: Literal["crop", "ellipsis", "crop_above", "visible"] = Field(
+    stream_vertical_overflow: Literal[
+        "crop", "ellipsis", "crop_above", "visible"
+    ] = Field(
         default="crop_above",
-        description=("Rich Live vertical overflow strategy; select how tall output is handled; 'crop_above' keeps the most recent rows visible."),
+        description=(
+            "Rich Live vertical overflow strategy; select how tall output is handled; 'crop_above' keeps the most recent rows visible."
+        ),
     )
     kwargs: dict[str, Any] = Field(default_factory=dict)
 
@@ -138,7 +146,7 @@ class DeclarativeEvaluationComponent(
     EvaluationComponent, DSPyIntegrationMixin, PromptParserMixin
 ):
     """Evaluation component that uses DSPy for generation.
-    
+
     This component provides the core intelligence for agents using DSPy's
     declarative programming model. It handles LLM interactions, tool usage,
     and prompt management through DSPy's framework.
@@ -156,7 +164,9 @@ class DeclarativeEvaluationComponent(
         super().__init__(**data)
 
     @override
-    def set_model(self, model: str, temperature: float = 1.0, max_tokens: int = 32000) -> None:
+    def set_model(
+        self, model: str, temperature: float = 1.0, max_tokens: int = 32000
+    ) -> None:
         """Set the model for the evaluation component."""
         self.config.model = model
         self.config.temperature = temperature
@@ -171,7 +181,9 @@ class DeclarativeEvaluationComponent(
         mcp_tools: list[Any] | None = None,
     ) -> dict[str, Any]:
         """Core evaluation logic using DSPy - migrated from DeclarativeEvaluator."""
-        logger.debug(f"Starting declarative evaluation for component '{self.name}'")
+        logger.debug(
+            f"Starting declarative evaluation for component '{self.name}'"
+        )
 
         # Prepare LM and optional adapter; keep settings changes scoped with dspy.context
         lm = dspy.LM(
@@ -190,17 +202,22 @@ class DeclarativeEvaluationComponent(
                 elif self.config.adapter == "xml":
                     adapter = dspy.XMLAdapter()
                 elif self.config.adapter == "two_step":
-                    extractor = dspy.LM(self.config.extraction_model or "openai/gpt-4o-mini")
+                    extractor = dspy.LM(
+                        self.config.extraction_model or "openai/gpt-4o-mini"
+                    )
                     adapter = dspy.TwoStepAdapter(extraction_model=extractor)
                 else:
                     # chat is default; leave adapter=None
                     adapter = None
             except Exception as e:
-                logger.warning(f"Failed to construct adapter '{self.config.adapter}': {e}. Proceeding without.")
+                logger.warning(
+                    f"Failed to construct adapter '{self.config.adapter}': {e}. Proceeding without."
+                )
 
         with dspy.context(lm=lm, adapter=adapter):
             try:
                 from rich.console import Console
+
                 console = Console()
 
                 # Create DSPy signature from agent definition
@@ -238,17 +255,23 @@ class DeclarativeEvaluationComponent(
 
             # Execute with streaming or non-streaming
             if self.config.stream:
-                return await self._execute_streaming(_dspy_signature, agent_task, inputs, agent, console)
+                return await self._execute_streaming(
+                    _dspy_signature, agent_task, inputs, agent, console
+                )
             else:
                 return await self._execute_standard(agent_task, inputs, agent)
 
-    async def _execute_streaming(self, signature, agent_task, inputs: dict[str, Any], agent: Any, console) -> dict[str, Any]:
+    async def _execute_streaming(
+        self, signature, agent_task, inputs: dict[str, Any], agent: Any, console
+    ) -> dict[str, Any]:
         """Execute DSPy program in streaming mode with rich table updates."""
         logger.info(f"Evaluating agent '{agent.name}' with async streaming.")
 
         if not callable(agent_task):
             logger.error("agent_task is not callable, cannot stream.")
-            raise TypeError("DSPy task could not be created or is not callable.")
+            raise TypeError(
+                "DSPy task could not be created or is not callable."
+            )
 
         # Prepare stream listeners for any string output fields
         listeners = []
@@ -306,7 +329,7 @@ class DeclarativeEvaluationComponent(
             live_cm = Live(
                 initial_panel,
                 console=console,
-                refresh_per_second=400,
+                refresh_per_second=4,
                 transient=False,
                 vertical_overflow=overflow_mode,
             )
@@ -314,6 +337,7 @@ class DeclarativeEvaluationComponent(
         final_result: dict[str, Any] | None = None
 
         with live_cm as live:
+
             def _refresh_panel() -> None:
                 if formatter is None or live is None:
                     return
@@ -347,7 +371,9 @@ class DeclarativeEvaluationComponent(
                         except Exception as e:
                             logger.warning(f"Stream callback error: {e}")
                     token = getattr(value, "chunk", None)
-                    signature_field = getattr(value, "signature_field_name", None)
+                    signature_field = getattr(
+                        value, "signature_field_name", None
+                    )
                     if signature_field:
                         if signature_field not in display_data:
                             display_data[signature_field] = ""
@@ -385,7 +411,9 @@ class DeclarativeEvaluationComponent(
                                 ordered_final[key] = final_result[key]
                         for field_name in signature_order:
                             if field_name in final_result:
-                                ordered_final[field_name] = final_result[field_name]
+                                ordered_final[field_name] = final_result[
+                                    field_name
+                                ]
                         for key, val in final_result.items():
                             if key not in ordered_final:
                                 ordered_final[key] = val
@@ -410,14 +438,18 @@ class DeclarativeEvaluationComponent(
 
         return filtered_result
 
-    async def _execute_standard(self, agent_task, inputs: dict[str, Any], agent: Any) -> dict[str, Any]:
+    async def _execute_standard(
+        self, agent_task, inputs: dict[str, Any], agent: Any
+    ) -> dict[str, Any]:
         """Execute DSPy program in standard mode (from original implementation)."""
         logger.info(f"Evaluating agent '{agent.name}' without streaming.")
 
         try:
             # Ensure the call is awaited if the underlying task is async
             result_obj = await agent_task.acall(**inputs)
-            result_dict, cost, lm_history = self._process_result(result_obj, inputs)
+            result_dict, cost, lm_history = self._process_result(
+                result_obj, inputs
+            )
             self._cost = cost
             self._lm_history = lm_history
             result_dict = self.filter_reasoning(

{flock_core-0.5.0b22 → flock_core-0.5.0b24}/src/flock/core/mcp/flock_mcp_server.py

@@ -155,7 +155,11 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
                     await self.post_init()
             if not self.config.allow_all_tools:
                 whitelist = self.config.feature_config.tool_whitelist
-                if whitelist is not None and len(whitelist) > 0 and name not in whitelist:
+                if (
+                    whitelist is not None
+                    and len(whitelist) > 0
+                    and name not in whitelist
+                ):
                     return None
             async with self.condition:
                 try:
@@ -267,6 +271,7 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
                     error=str(module_error),
                 )
                 span.record_exception(module_error)
+            return additional_params
 
     async def pre_init(self) -> None:
         """Run pre-init hooks on modules."""
@@ -276,11 +281,15 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
         with tracer.start_as_current_span("server.pre_init") as span:
             span.set_attribute("server.name", self.config.name)
             # run whitelist checks
-            whitelist = self.config.feature_config
-            if whitelist is not None and len(whitelist) > 0:
-                self.config.feature_config = False
-            else:
-                # if the whitelist is none..
+            feature_config = self.config.feature_config
+            whitelist = (
+                feature_config.tool_whitelist if feature_config else None
+            )
+            if whitelist:
+                # Enforce whitelist usage by disabling blanket tool access
+                self.config.allow_all_tools = False
+            elif whitelist is None:
+                # No whitelist configured; ensure defaults allow full access
                 self.config.allow_all_tools = True
             try:
                 for module in self.get_enabled_components():
@@ -449,7 +458,7 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
                 span.record_exception(server_error)
 
     # --- Serialization Implementation ---
-    def to_dict(self, path_type: str = "relative") -> dict[str, Any]:
+    def to_dict(self, path_type: str = "relative") -> dict[str, Any]:  # noqa: C901 - TODO: refactor to simplify serialization logic
         """Convert instance to dictionary representation suitable for serialization."""
         from flock.core.registry import get_registry
 
@@ -469,7 +478,6 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
         config_data = self.config.to_dict(path_type=path_type)
         data["config"] = config_data
 
-
         builtin_by_transport = {}
 
         try:
@@ -638,7 +646,13 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
             data["config"] = config_object
 
         # now construct
-        server = real_cls(**{k: v for k, v in data.items() if k not in ["modules", "components"]})
+        server = real_cls(
+            **{
+                k: v
+                for k, v in data.items()
+                if k not in ["modules", "components"]
+            }
+        )
 
         # re-hydrate components (both legacy modules and new components)
         for cname, cdata in data.get("components", {}).items():
@@ -646,7 +660,9 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
 
         # Handle legacy modules for backward compatibility during transition
         for mname, mdata in data.get("modules", {}).items():
-            logger.warning(f"Legacy module '{mname}' found during deserialization - consider migrating to unified components")
+            logger.warning(
+                f"Legacy module '{mname}' found during deserialization - consider migrating to unified components"
+            )
             # Skip legacy modules during migration
 
         # --- Separate Data ---

{flock_core-0.5.0b22 → flock_core-0.5.0b24}/uv.lock

@@ -1154,7 +1154,7 @@ wheels = [
 
 [[package]]
 name = "flock-core"
-version = "0.5.0b22"
+version = "0.5.0b24"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },

flock_core-0.5.0b22/.devcontainer/devcontainer.json

@@ -1,36 +0,0 @@
-{
-	"name": "flock dev",
-	"image": "ghcr.io/astral-sh/uv:python3.12-bookworm",
-	"customizations": {
-		"vscode": {
-			"extensions": [
-				"ms-python.python",
-				"charliermarsh.ruff"
-			],
-			"settings": {
-				"python.defaultInterpreterPath": "/usr/local/bin/python",
-				"[python]": {
-					"editor.defaultFormatter": "charliermarsh.ruff",
-					"editor.formatOnSave": true,
-					"editor.codeActionsOnSave": {
-						"source.fixAll": "explicit",
-						"source.organizeImports": "explicit"
-					}
-				},
-				"ruff.lint.run": "onSave",
-				"ruff.format.args": [
-					"--line-length",
-					"88"
-				],
-				"ruff.lint.args": [
-					"--line-length",
-					"88"
-				]
-			}
-		}
-	},
-	"forwardPorts": [
-		8888
-	],
-	"postCreateCommand": "uv sync --all-groups --all-extras --frozen"
-}