flock-core 0.5.0b16__tar.gz → 0.5.0b17__tar.gz

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/.github/workflows/ci.yml

@@ -1,4 +1,6 @@
 name: CI
+permissions:
+  contents: read
 
 on:
   push:

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/.gitignore

@@ -10,6 +10,8 @@ __pycache__/
 *.env*
 !*.env_template
 
+.DS_Store
+flock-showcase/
 
 # Distribution / packaging
 .Python

flock_core-0.5.0b16/AGENT.md → flock_core-0.5.0b17/AGENTS.md

@@ -112,7 +112,7 @@ Implement these to finalize the test framework for 0.5.0:
    - Tests for skip private modules and robust behavior on import errors (no crash; log warning).
 
 6. Docs
-   - Keep `testing_strategy.md`, `testing_guide.md`, `testing_todo.md` up to date and linked in CONTRIBUTING/README.
+  - Keep `docs/testing_strategy.md`, `docs/testing_guide.md`, `docs/internal/testing_todo.md` up to date and linked in CONTRIBUTING/README.
 
 ### Strongly Recommended
 
@@ -179,6 +179,47 @@ These patterns have been validated in the current suite and should keep tests de
 - `agent.next_agent`: Next agent in workflow (string, callable, or None)
 - `agent._components`: Component management helper (lazy-loaded)
 
+### Pydantic I/O Contracts (New)
+
+In addition to string-based contracts, agents can define input/output using Pydantic models. The framework converts Pydantic schemas into the canonical flock signature used for DSPy and validation, and it accepts `BaseModel` instances as inputs at runtime.
+
+```python
+from typing import Literal
+from pydantic import BaseModel, Field
+from flock.core.registry import flock_type
+from flock.core import Flock, DefaultAgent
+
+@flock_type  # recommended: registers the model with the TypeRegistry
+class MovieIdea(BaseModel):
+    topic: str
+    genre: Literal["comedy", "drama", "horror", "action", "adventure"]
+
+@flock_type
+class Movie(BaseModel):
+    fun_title: str
+    runtime: int
+    synopsis: str
+    characters: list[dict[str, str]]
+
+flock = Flock(name="example", model="openai/gpt-5")
+agent = DefaultAgent(
+    name="movie_agent",
+    description="Create a fun movie",
+    input=MovieIdea,      # Pydantic class
+    output=Movie,         # Pydantic class
+)
+flock.add_agent(agent)
+
+# You can pass a BaseModel instance directly; it will be normalized to dict
+result = flock.run(agent=agent, input=MovieIdea(topic="AI agents", genre="comedy"))
+print(result.fun_title)
+```
+
+Notes:
+- The framework will auto-register encountered Pydantic models (including nested ones) in the `TypeRegistry` during signature building. Using `@flock_type` is still recommended for clarity and early registration.
+- Internally, these models are translated to a string contract like `"field: type | description"`, so existing components (e.g., DSPy integration) work seamlessly.
+- String-based I/O remains fully supported and unchanged.
+
 ### Execution Flow
 
 ```
@@ -241,10 +282,10 @@ class MyComponent(EvaluationComponentBase):
 
 ### Agent Creation
 ```python
-from flock.core import Flock, FlockFactory
+from flock.core import Flock, DefaultAgent
 
 flock = Flock(model="openai/gpt-4o")
-agent = FlockFactory.create_default_agent(
+agent = DefaultAgent(
     name="my_agent",
     input="query: str",
     output="result: str"
@@ -326,6 +367,24 @@ agent.router     # Same as helper.get_primary_router()
 - Support JSON, YAML, and Python dict formats
 - Use `to_dict()` / `from_dict()` for persistence
 
+### Hydrator (Pydantic)
+You can “hydrate” Pydantic models (fill missing/None fields) using the `@flockclass` decorator, which spins up a temporary agent based on the model’s schema.
+
+```python
+from pydantic import BaseModel, Field
+from flock.core.util.hydrator import flockclass
+
+@flockclass(model="openai/gpt-5")
+class RandomPerson(BaseModel):
+    name: str | None = None
+    age: int | None = None
+    bio: str | None = Field(default=None, description="A short biography")
+
+person = RandomPerson()
+person = person.hydrate()  # fills in missing fields via a dynamic agent
+```
+See `07-hydrator.py` for a full example.
+
 ## Development Guidelines
 
 ### When Making Changes
@@ -351,7 +410,7 @@ agent.router     # Same as helper.get_primary_router()
 1. **Understand the flow**: `Flock` → `FlockAgent` → `Utility/Evaluator/Router` → Result
 2. **Start with examples**: Check `examples/01-getting-started/`
 3. **Read tests**: `tests/core/test_flock_core.py` shows usage patterns
-4. **Use the factory**: `FlockFactory.create_default_agent()` for quick setup
+4. **Use DefaultAgent**: prefer `DefaultAgent(...)` for explicit setup; `FlockFactory` is deprecated
 5. **Focus on contracts**: Input/output signatures are key
 
 ## Workflow Management
@@ -430,7 +489,7 @@ Based on the review, focus on:
 The unified architecture completely replaces the legacy system:
 - Legacy evaluators, modules, and routers have been removed
 - All legacy dependencies cleaned up from codebase  
-- FlockFactory creates agents with new unified components
+- DefaultAgent wires unified components under the hood
 - Workflow execution uses `agent.next_agent` for routing
 - HandOffRequest system replaced with direct property assignment
 
@@ -447,3 +506,17 @@ The unified architecture completely replaces the legacy system:
 - Zero code duplication in registry operations
 
 This should give you a solid foundation to understand and contribute to the Flock framework efficiently!
+
+## Branching & Pre‑Release Policy
+
+- Pre‑release main branch for 0.5.0: `0.5.0b`.
+  - All PRs targeting the 0.5.0 pre‑release must be opened against `0.5.0b`, not `main`.
+  - We use a `[Phase0]` prefix in GitHub issue titles for the 0.5.0 peak‑condition tasks.
+- Once 0.5.0 ships, `main` will receive a fast‑forward or merge from `0.5.0b` according to release policy.
+
+## Contributor Tips (0.5.0 → 1.0)
+
+- Prefer explicit Agent classes over factory helpers. Factory APIs remain during 0.5.0 but will be deprecated in favor of real agent classes (e.g., `DefaultAgent`).
+- Contracts first: for complex schemas, pass Pydantic models for `input`/`output` and pass `BaseModel` instances as `flock.run(..., input=...)` — they are normalized under the hood.
+- Unified components only: Evaluation/Routing/Utility; legacy “modules” are considered internal/legacy and will be removed in 1.0.
+- Reactive path: future 1.0 work will add a `SubscriptionComponent` and `agent.subscribe_to(...)` sugar; no need to author graphs or decorators.

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/CONTRIBUTING.md

@@ -130,8 +130,9 @@ We follow the [Contributor Covenant](https://www.contributor-covenant.org/) code
 Flock aims to provide an easy and reliable way to implement agentic applications. Therefore, well tested code is crucial.
 
 Start here:
-- Strategy: see `testing_strategy.md` for priorities and coverage goals.
-- How-to: see `testing_guide.md` for setup, patterns, and examples.
+- Strategy: see `docs/testing_strategy.md` for priorities and coverage goals.
+- How-to: see `docs/testing_guide.md` for setup, patterns, and examples.
+- TODOs (internal): see `docs/internal/testing_todo.md`.
 
 Run tests with uv (recommended):
 - Quick suite (CI-equivalent): `uv run poe test`
@@ -144,6 +145,10 @@ Guidelines:
 - Place tests under `tests/` by concern (see strategy structure).
 - Use [`pytest`](https://docs.pytest.org/en/stable/) fixtures instead of duplicating setup code.
 
+### Pydantic I/O and Hydrator
+- Agents may define input/output contracts using Pydantic models as an alternative to string contracts. See `AGENT.md#pydantic-io-contracts-new` for examples and guidelines.
+- To generate structured data with an LLM into a model instance, use the hydrator decorator. See `AGENT.md#hydrator-pydantic`.
+
 
 <!-- TOC --><a name="release-process"></a>
 ## Release Process:
@@ -154,4 +159,3 @@ Guidelines:
 5. GitHub Action publishes to PyPI.
 
 Thank you for contributing to Flock, the declarative Agent-Framework. 🦆💓
-

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b16
+Version: 0.5.0b17
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -16,10 +16,10 @@ 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: dspy>=3.0.0
 Requires-Dist: fastapi>=0.115.8
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: litellm[proxy]==v1.75.3
+Requires-Dist: litellm>=1.75.3
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: markdown2>=2.5.3
 Requires-Dist: mcp>=1.7.1
@@ -38,7 +38,7 @@ 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: pydantic>=2.10.5
 Requires-Dist: python-box>=7.3.2
 Requires-Dist: python-decouple>=3.8
 Requires-Dist: python-dotenv>=1.0.1
@@ -118,16 +118,16 @@ No brittle prompts. No guesswork. Just reliable, testable AI agents.
 ## ⚡ Quick Start
 
 ```python
-from flock.core import Flock, FlockFactory
+from flock.core import Flock, DefaultAgent
 
 # 1. Create the main orchestrator
 my_flock = Flock(model="openai/gpt-4.1")
 
 # 2. Declaratively define an agent
-brainstorm_agent = FlockFactory.create_default_agent(
+brainstorm_agent = DefaultAgent(
     name="idea_generator",
     input="topic",
-    output="catchy_title, key_points"
+    output="catchy_title, key_points",
 )
 
 # 3. Add the agent to the Flock

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/README.md

@@ -53,16 +53,16 @@ No brittle prompts. No guesswork. Just reliable, testable AI agents.
 ## ⚡ Quick Start
 
 ```python
-from flock.core import Flock, FlockFactory
+from flock.core import Flock, DefaultAgent
 
 # 1. Create the main orchestrator
 my_flock = Flock(model="openai/gpt-4.1")
 
 # 2. Declaratively define an agent
-brainstorm_agent = FlockFactory.create_default_agent(
+brainstorm_agent = DefaultAgent(
     name="idea_generator",
     input="topic",
-    output="catchy_title, key_points"
+    output="catchy_title, key_points",
 )
 
 # 3. Add the agent to the Flock

flock_core-0.5.0b17/docs/components/evaluators.md

@@ -0,0 +1,52 @@
+---
+hide: # Optional: Hide table of contents on simple pages
+  - toc
+---
+
+# Evaluation Components 🧠
+
+Evaluation components implement the agent’s core logic. The default option uses DSPy for structured prompting and tool use.
+
+## DeclarativeEvaluationComponent (default)
+
+Created when you construct a `DefaultAgent`, it converts your contracts into a DSPy signature and runs a suitable program (`Predict`, `ReAct`, or `ChainOfThought`).
+
+### Highlights
+- Honors `description`, `input`, and `output` (string or Pydantic) contracts
+- Supports streaming output and optional reasoning/trajectory fields
+- Integrates native Python tools and MCP tools
+
+### Example
+```python
+from flock.core import DefaultAgent
+
+agent = DefaultAgent(
+    name="summarizer",
+    description="Summarize the provided text",
+    input="text: str",
+    output="summary: str | A concise abstract"
+)
+```
+
+## Custom Evaluation Components
+
+Subclass `EvaluationComponent` and implement `evaluate_core`.
+
+```python
+from flock.core.component.evaluation_component import EvaluationComponent
+from flock.core.registry import flock_component
+
+@flock_component
+class MyEvaluator(EvaluationComponent):
+    async def evaluate_core(self, agent, inputs, context=None, tools=None, mcp_tools=None):
+        return {"result": inputs.get("text", "").upper()}
+```
+
+Register via `@flock_component` for discovery and serialization.
+
+## Best Practices
+
+- Respect the agent’s `model` unless you have a strong reason to override.
+- Validate inputs early; raise errors to trigger `on_error` hooks.
+- Make network calls async.
+- Return only declared output fields; keep responses compact and structured.

flock_core-0.5.0b17/docs/components/index.md

@@ -0,0 +1,46 @@
+---
+hide: # Optional: Hide table of contents on simple pages
+  - toc
+---
+
+# Components Overview 🧩
+
+Flock uses a unified component system: every agent has a single list `agent.components` that may include any of the following:
+
+| Component Type | Purpose | Base Class |
+| -------------- | ------- | ---------- |
+| **Evaluation** | Implements an agent’s core logic (LLM/DSPy or custom code). | `EvaluationComponent` |
+| **Routing** | Chooses the next agent in a workflow (static, conditional, LLM-based). | `RoutingComponent` |
+| **Utility** | Cross-cutting concerns: output formatting, metrics, memory, etc. | `AgentComponent` |
+
+Tools are simple callables (or MCP tools) that evaluators may invoke; register them via `@flock_tool`.
+
+Learn more:
+
+* [Evaluation Components](evaluators.md)
+* [Utility Components](utility.md)
+* [Tools](tools.md)
+
+---
+
+## Version Compatibility
+
+All core component base classes follow **Semantic Versioning**.  Adding new optional hook methods counts as a *minor* version bump, so custom components will keep working.
+
+---
+
+## Lifecycle Hooks
+
+All components inherit from `AgentComponent` and can implement lifecycle hooks:
+
+- `on_initialize(agent, inputs, context)`
+- `on_pre_evaluate(agent, inputs, context)`
+- `on_post_evaluate(agent, inputs, context, result)`
+- `terminate(agent, inputs, result, context)`
+- `on_error(agent, inputs, context, error)`
+
+Evaluation components also implement `evaluate_core(...)`.
+
+---
+
+Continue reading the dedicated pages for implementation details.

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/docs/components/tools.md

@@ -29,7 +29,9 @@ Decorating with `@flock_tool` registers the function in the **global registry**
 ## 2. Using Tools in Agents
 
 ```python
-agent = FlockFactory.create_default_agent(
+from flock.core import DefaultAgent
+
+agent = DefaultAgent(
     name="page_analyser",
     input="url: str",
     output="title: str, headings: list[str]",

flock_core-0.5.0b17/docs/components/utility.md

@@ -0,0 +1,44 @@
+# Utility Components 🧰
+
+Utility components provide cross‑cutting behavior for agents without changing their core logic. Common examples include:
+
+- Output formatting (pretty printing, theming, streaming)
+- Metrics/latency tracking and alerts
+- Memory or context injection
+
+These components inherit from `AgentComponent` and typically implement lifecycle hooks.
+
+## Built‑in Examples
+
+- `OutputUtilityComponent`
+  - Formats and prints results; can render tables and control verbosity.
+- `MetricsUtilityComponent`
+  - Tracks latency/cost thresholds and emits warnings.
+
+## Adding a Utility Component
+
+```python
+from pydantic import BaseModel, Field
+from flock.core.registry import flock_component
+from flock.core.component.agent_component_base import AgentComponent, AgentComponentConfig
+
+class MyOutputConfig(AgentComponentConfig):
+    shout: bool = Field(default=False)
+
+@flock_component(name="my_output", config_class=MyOutputConfig)
+class MyOutput(AgentComponent):
+    config: MyOutputConfig
+
+    async def on_post_evaluate(self, agent, inputs, context, result):
+        if self.config.shout and isinstance(result, dict) and "text" in result:
+            result["text"] = result["text"].upper()
+        return result
+```
+
+Registering with `@flock_component` makes the component discoverable via the registry and serializable.
+
+## When To Use Utility Components
+
+- You want consistent output across many agents.
+- You need metrics/telemetry without coupling it to evaluation logic.
+- You need to adjust inputs/outputs around evaluation in a reusable way.

flock_core-0.5.0b17/docs/core-concepts/agents.md

@@ -0,0 +1,159 @@
+---
+hide: # Optional: Hide table of contents on simple pages
+  - toc
+---
+
+# Flock Agents 🐦
+
+A **FlockAgent** is the fundamental unit of work. Each agent is declarative — you specify what goes in and what should come out. Components provide the “how”.
+
+---
+
+## 1. Anatomy of an Agent (Unified)
+
+```python
+from flock.core import DefaultAgent
+
+agent = DefaultAgent(
+    name="movie_pitcher",
+    description="Create a fun movie idea",
+    input="topic: str | Central subject",
+    output="title: str, runtime: int, synopsis: str",
+)
+```
+
+### Key Fields
+
+| Field | Type | Intent |
+| ----- | ---- | ------ |
+| `name` | `str` | Unique identifier; becomes the registry key. |
+| `model` | `str | None` | Override the default model for this agent. |
+| `description` | `str \| Callable \| BaseModel` | High-level instruction (string or callable). |
+| `input` | `str | BaseModel` | Contract for accepted data. |
+| `output` | `str | BaseModel` | Contract for produced data. |
+| `tools` | `list[Callable]` | Extra callables the evaluator may invoke. |
+| `tool_whitelist` | `list[str] \| None` | Filter tools by name for security (recommended). |
+| `servers` | `list[str \| FlockMCPServer]` | MCP servers providing additional tools. |
+| `components` | `list[AgentComponent]` | Unified list: evaluation, routing, utility. |
+| `evaluator` | `EvaluationComponent | None` | Convenience property: primary evaluator. |
+| `router` | `RoutingComponent | None` | Convenience property: primary router. |
+
+All these fields are **Pydantic-validated** and fully serialisable via `Serializable`.
+
+---
+
+## 2. Contracts: Input & Output
+
+Signatures are written in a compact mini-DSL:
+
+* `field` – just a name (type & description inferred by the LLM).
+* `field: type` – adds a type hint.
+* `field: type | description` – adds a natural-language description.
+* Multiple fields are comma-separated.
+* Lists/dicts follow normal Python typing: `list[dict[str, str]]`.
+
+Alternatively, pass **Pydantic models** (recommended for complex schemas):
+
+```python
+from pydantic import BaseModel
+
+class SearchIn(BaseModel):
+    query: str
+    top_k: int = 5
+
+class SearchOut(BaseModel):
+    documents: list[str]
+
+search_agent = DefaultAgent(
+    name="searcher",
+    input=SearchIn,
+    output=SearchOut,
+)
+```
+
+---
+
+## 3. Tools & Security
+
+Agents can use both native Python functions and tools from MCP (Model Context Protocol) servers:
+
+```python
+agent = DefaultAgent(
+    name="research_agent",
+    tools=[my_python_function],      # Native Python tools
+    servers=["web-search-server"],   # MCP servers
+    tool_whitelist=["search_web", "summarize"],  # Security filtering
+)
+```
+
+### Tool Whitelisting
+
+For security and control, agents support tool filtering via `tool_whitelist`:
+
+* **`tool_whitelist: list[str] | None`** – If provided, only tools with names in this list are accessible
+* Applies to both native Python tools (by `__name__`) and MCP tools (by `name` attribute)
+* If `None`, all tools from servers and the tools list are available
+
+**Example:**
+```python
+# Only allow specific tools
+secure_agent = DefaultAgent(
+    name="secure_agent",
+    servers=["general-tools"],
+    tool_whitelist=["safe_search", "validate_input"],  # Restricted access
+)
+
+# Allow all tools (default)
+open_agent = DefaultAgent(
+    name="open_agent", 
+    servers=["general-tools"],
+    # No tool_whitelist = all server tools available
+)
+```
+
+**Best Practice:** Use agent-level filtering for granular control. Different agents can access different tool subsets from the same server.
+
+See the **[Tool Whitelisting & Security Guide](../guides/tool-whitelist.md)** for comprehensive security patterns and implementation details.
+
+---
+
+## 4. Lifecycle
+
+```mermaid
+flowchart LR
+    A[initialize] --> B[evaluate]
+    B --> C[terminate]
+    B -. error .-> D[on_error]
+```
+
+1. **initialize** – prepare resources (DB connection, load embeddings, etc.).
+2. **evaluate** – main logic executed by the evaluator.
+3. **terminate** – clean-up, persist metrics.
+4. **on_error** – triggered if any previous stage raises.
+
+Components (utility) can hook into each stage to extend behavior.
+
+---
+
+## 4. Adding Components
+
+```python
+from flock.components.utility.output_utility_component import OutputUtilityComponent, OutputUtilityConfig
+from flock.components.routing.default_routing_component import DefaultRoutingComponent, DefaultRoutingConfig
+
+agent.add_component(OutputUtilityComponent(name="output", config=OutputUtilityConfig(render_table=True)))
+agent.add_component(DefaultRoutingComponent(name="router", config=DefaultRoutingConfig()))
+```
+
+---
+
+## 5. Best Practices
+
+* Keep `description` concise; use the signature for fine-grained control.
+* Prefer Pydantic models for complex schemas – you get validation for free.
+* Separate concerns: evaluator handles logic, utility components handle cross‑cutting tasks.
+* Register reusable tools with `@flock_tool` so any agent can adopt them.
+
+---
+
+**Next:**  Learn *why* this declarative approach works in [Declarative Programming](declarative.md).

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/docs/core-concepts/workflows.md

@@ -12,18 +12,18 @@ A **workflow** in Flock is *simply* a sequence of agent evaluations managed by a
 ## 1. Creating a Workflow
 
 ```python
-from flock.core import Flock, FlockFactory
+from flock.core import Flock, DefaultAgent
 from flock.routers.agent import AgentRouter
 
 flock = Flock(name="demo")
 
-search_agent = FlockFactory.create_default_agent(
+search_agent = DefaultAgent(
     name="searcher",
     input="query: str",
     output="documents: list[str]",
 )
 
-summariser = FlockFactory.create_default_agent(
+summariser = DefaultAgent(
     name="summariser",
     input="docs: list[str]",
     output="summary: str",
@@ -42,7 +42,7 @@ search_agent.handoff_router = AgentRouter(
 You can start the workflow by **name** or by passing the agent instance:
 
 ```python
-result = flock.run(start_agent="searcher", input={"query": "LLM frameworks"})
+result = flock.run(agent="searcher", input={"query": "LLM frameworks"})
 print(result.summary)
 ```
 
@@ -78,7 +78,7 @@ Agents and modules can read/write to the context at will, enabling memory and co
 ```python
 # Run multiple inputs concurrently
 results = await flock.run_batch_async(
-    start_agent="searcher",
+    agent="searcher",
     input_list=[{"query": q} for q in queries],
 )
 ```

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/docs/getting-started/configuration.md

@@ -79,7 +79,7 @@ You can also override or set configurations directly when creating Flock or Floc
 
 ### Configure Flock instance
 ```python
-from flock.core import Flock, FlockAgent, FlockFactory
+from flock.core import Flock, FlockAgent, DefaultAgent
 from flock.core.logging.logging import configure_logging
 
 # Only show error logs
@@ -94,7 +94,7 @@ my_flock = Flock(
 
 ### Configure Agent instance
 ```python
-specific_agent = FlockFactory.create_default_agent(
+specific_agent = DefaultAgent(
     name="SpecificAgent",
     model="openai/gpt-3.5-turbo", # Use a different model for this agent
     use_cache=False,              # Disable caching for this agent

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/docs/getting-started/index.md

@@ -15,7 +15,7 @@ This section covers the essentials to get you up and running:
 
 *   **[Quick Start](quickstart.md):** Jump right in and build your very first Flock agent in minutes. See how simple the declarative approach can be.
 *   **[Installation](installation.md):** Get Flock set up on your machine, along with any necessary dependencies.
-*   **[Basic Concepts](concepts.md):** Understand the fundamental ideas behind Flock – Agents, the Declarative approach, and the core components you'll interact with. *(Coming Soon)*
+*   **[Core Concepts](../core-concepts/index.md):** Understand the fundamental ideas behind Flock – Agents, the declarative approach, and the component system.
 *   **[Configuration](configuration.md):** Learn how to configure Flock for your specific needs, including setting up LLM providers.
 
 ## Prerequisites
@@ -47,4 +47,4 @@ Based on these information all you need to do for flock using any anthropic mode
 
 We recommend starting with the **[Quick Start](quickstart.md)** guide for a hands-on introduction. If you prefer to set up everything first, head over to the **[Installation](installation.md)** page.
 
-Let's get your first agent airborne! 🐦‍⬛💨
+Let's get your first agent airborne! 🐦‍⬛💨

{flock_core-0.5.0b16 → flock_core-0.5.0b17}/docs/getting-started/quickstart.md

@@ -17,7 +17,7 @@ Create a new Python file (e.g., `hello_flock.py`) and paste the following code:
 
 ```python
 # hello_flock.py
-from flock.core import Flock, FlockFactory
+from flock.core import Flock, DefaultAgent
 
 # --------------------------------
 # 1. Choose Your LLM
@@ -41,8 +41,7 @@ flock = Flock(
 # 3. Define Your Agent Declaratively
 # --------------------------------
 # No complex prompts needed! Just declare what goes in and what comes out.
-# We'll use FlockFactory for a quick setup.
-presentation_agent = FlockFactory.create_default_agent(
+presentation_agent = DefaultAgent(
     name="my_presentation_agent",
     description="Creates a fun presentation outline about a given topic",
     input="topic: str", # The agent expects a string named 'topic'
@@ -60,8 +59,8 @@ flock.add_agent(presentation_agent)
 # Tell the Flock which agent to start with and provide the input.
 print(f"Running agent '{presentation_agent.name}'...")
 result = flock.run(
-    start_agent=presentation_agent, # Or use the name: "my_presentation_agent"
-    input={"topic": "Why Llamas Make Great Urban Pets"} # The input data
+    agent=presentation_agent,  # Or use the name: "my_presentation_agent"
+    input={"topic": "Why Llamas Make Great Urban Pets"}
 )
 
 # --------------------------------
@@ -100,7 +99,7 @@ Let's break down the magic:
 
 **Create Your Flock**: The Flock object acts as the container and orchestrator for your agents.
 
-**Define Your Agent Declaratively**: This is the core of Flock! Instead of writing a long prompt, you used FlockFactory.create_default_agent and simply declared:
+**Define Your Agent Declaratively**: This is the core of Flock! Instead of writing a long prompt, you constructed a `DefaultAgent` and simply declared:
 
 `input="topic: str"`: The agent needs one input called topic, which should be a string.