flock-core 0.5.0b59__py3-none-any.whl → 0.5.0b60__py3-none-any.whl

flock/agent.py

@@ -362,6 +362,22 @@ class AgentBuilder:
     # Fluent configuration -------------------------------------------------
 
     def description(self, text: str) -> AgentBuilder:
+        """Set the agent's description for documentation and tracing.
+
+        Args:
+            text: Human-readable description of what the agent does
+
+        Returns:
+            self for method chaining
+
+        Example:
+            >>> agent = (
+            ...     flock.agent("pizza_chef")
+            ...     .description("Creates authentic Italian pizza recipes")
+            ...     .consumes(Idea)
+            ...     .publishes(Recipe)
+            ... )
+        """
         self._agent.description = text
         return self
 
@@ -379,6 +395,59 @@ class AgentBuilder:
         mode: str = "both",
         priority: int = 0,
     ) -> AgentBuilder:
+        """Declare which artifact types this agent processes.
+
+        Sets up subscription rules that determine when the agent executes.
+        Supports type-based matching, conditional filters, batching, and joins.
+
+        Args:
+            *types: Artifact types (Pydantic models) to consume
+            where: Optional filter predicate(s). Agent only executes if predicate returns True.
+                Can be a single callable or sequence of callables (all must pass).
+            text: Optional semantic text filter using embedding similarity
+            min_p: Minimum probability threshold for text similarity (0.0-1.0)
+            from_agents: Only consume artifacts from specific agents
+            channels: Only consume artifacts with matching tags
+            join: Join specification for coordinating multiple artifact types
+            batch: Batch specification for processing multiple artifacts together
+            delivery: Delivery mode - "exclusive" (one agent) or "broadcast" (all matching)
+            mode: Processing mode - "both", "streaming", or "batch"
+            priority: Execution priority (higher = executes first)
+
+        Returns:
+            self for method chaining
+
+        Examples:
+            >>> # Basic type subscription
+            >>> agent.consumes(Task)
+
+            >>> # Multiple types
+            >>> agent.consumes(Task, Event, Command)
+
+            >>> # Conditional consumption (filtering)
+            >>> agent.consumes(Review, where=lambda r: r.score >= 8)
+
+            >>> # Multiple predicates (all must pass)
+            >>> agent.consumes(
+            ...     Order,
+            ...     where=[
+            ...         lambda o: o.total > 100,
+            ...         lambda o: o.status == "pending"
+            ...     ]
+            ... )
+
+            >>> # Consume from specific agents
+            >>> agent.consumes(Report, from_agents=["analyzer", "validator"])
+
+            >>> # Channel-based routing
+            >>> agent.consumes(Alert, channels={"critical", "security"})
+
+            >>> # Batch processing
+            >>> agent.consumes(
+            ...     Email,
+            ...     batch={"size": 10, "timeout": 5.0}
+            ... )
+        """
         predicates: Sequence[Callable[[BaseModel], bool]] | None
         if where is None:
             predicates = None
@@ -409,6 +478,48 @@ class AgentBuilder:
     def publishes(
         self, *types: type[BaseModel], visibility: Visibility | None = None
     ) -> PublishBuilder:
+        """Declare which artifact types this agent produces.
+
+        Configures the output types and default visibility controls for artifacts
+        published by this agent. Can chain with .where() for conditional publishing.
+
+        Args:
+            *types: Artifact types (Pydantic models) to publish
+            visibility: Default visibility control for all outputs. Defaults to PublicVisibility.
+                Can be overridden per-publish or with .where() chaining.
+
+        Returns:
+            PublishBuilder for conditional publishing configuration
+
+        Examples:
+            >>> # Basic output declaration
+            >>> agent.publishes(Report)
+
+            >>> # Multiple output types
+            >>> agent.publishes(Summary, DetailedReport, Alert)
+
+            >>> # Private outputs (only specific agents can see)
+            >>> agent.publishes(
+            ...     SecretData,
+            ...     visibility=PrivateVisibility(agents={"admin", "auditor"})
+            ... )
+
+            >>> # Tenant-isolated outputs
+            >>> agent.publishes(
+            ...     Invoice,
+            ...     visibility=TenantVisibility()
+            ... )
+
+            >>> # Conditional publishing with chaining
+            >>> (agent.publishes(Alert)
+            ...  .where(lambda result: result.severity == "critical"))
+
+        See Also:
+            - PublicVisibility: Default, visible to all agents
+            - PrivateVisibility: Allowlist-based access control
+            - TenantVisibility: Multi-tenant isolation
+            - LabelledVisibility: Role-based access control
+        """
         outputs = []
         for model in types:
             spec = ArtifactSpec.from_model(model)
@@ -420,10 +531,80 @@ class AgentBuilder:
         return PublishBuilder(self, outputs)
 
     def with_utilities(self, *components: AgentComponent) -> AgentBuilder:
+        """Add utility components to customize agent lifecycle and behavior.
+
+        Components are hooks that run at specific points in the agent execution
+        lifecycle. Common uses include rate limiting, budgets, metrics, caching,
+        and custom preprocessing/postprocessing.
+
+        Args:
+            *components: AgentComponent instances with lifecycle hooks
+
+        Returns:
+            self for method chaining
+
+        Examples:
+            >>> # Rate limiting
+            >>> agent.with_utilities(
+            ...     RateLimiter(max_calls=10, window=60)
+            ... )
+
+            >>> # Budget control
+            >>> agent.with_utilities(
+            ...     TokenBudget(max_tokens=10000)
+            ... )
+
+            >>> # Multiple components (executed in order)
+            >>> agent.with_utilities(
+            ...     RateLimiter(max_calls=5),
+            ...     MetricsCollector(),
+            ...     CacheLayer(ttl=3600)
+            ... )
+
+        See Also:
+            - AgentComponent: Base class for custom components
+            - Lifecycle hooks: on_initialize, on_pre_consume, on_post_publish, etc.
+        """
         self._agent.utilities.extend(components)
         return self
 
     def with_engines(self, *engines: EngineComponent) -> AgentBuilder:
+        """Configure LLM engines for agent evaluation.
+
+        Engines determine how agents process inputs. Default is DSPy with the
+        orchestrator's model. Custom engines enable different LLM backends,
+        non-LLM logic, or hybrid approaches.
+
+        Args:
+            *engines: EngineComponent instances for evaluation
+
+        Returns:
+            self for method chaining
+
+        Examples:
+            >>> # DSPy engine with specific model
+            >>> agent.with_engines(
+            ...     DSPyEngine(model="openai/gpt-4o")
+            ... )
+
+            >>> # Custom non-LLM engine
+            >>> agent.with_engines(
+            ...     RuleBasedEngine(rules=my_rules)
+            ... )
+
+            >>> # Hybrid approach (multiple engines)
+            >>> agent.with_engines(
+            ...     DSPyEngine(model="openai/gpt-4o-mini"),
+            ...     FallbackEngine()
+            ... )
+
+        Note:
+            If no engines specified, agent uses DSPy with the orchestrator's default model.
+
+        See Also:
+            - DSPyEngine: Default LLM-based evaluation
+            - EngineComponent: Base class for custom engines
+        """
         self._agent.engines.extend(engines)
         return self
 

flock/frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flock-ui",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Flock Flow Real-Time Dashboard Frontend",
   "type": "module",
   "scripts": {

flock/orchestrator.py

@@ -84,6 +84,31 @@ class Flock(metaclass=AutoTracedMeta):
         store: BlackboardStore | None = None,
         max_agent_iterations: int = 1000,
     ) -> None:
+        """Initialize the Flock orchestrator for blackboard-based agent coordination.
+
+        Args:
+            model: Default LLM model for agents (e.g., "openai/gpt-4o-mini").
+                Can be overridden per-agent. If None, uses DEFAULT_MODEL env var.
+            store: Custom blackboard storage backend. Defaults to InMemoryBlackboardStore.
+            max_agent_iterations: Circuit breaker limit to prevent runaway agent loops.
+                Defaults to 1000 iterations per agent before reset.
+
+        Examples:
+            >>> # Basic initialization with default model
+            >>> flock = Flock("openai/gpt-4o-mini")
+
+            >>> # Custom storage backend
+            >>> flock = Flock(
+            ...     "openai/gpt-4o",
+            ...     store=CustomBlackboardStore()
+            ... )
+
+            >>> # Circuit breaker configuration
+            >>> flock = Flock(
+            ...     "openai/gpt-4o-mini",
+            ...     max_agent_iterations=500
+            ... )
+        """
         self._patch_litellm_proxy_imports()
         self.model = model
         self.store: BlackboardStore = store or InMemoryBlackboardStore()
@@ -113,6 +138,34 @@ class Flock(metaclass=AutoTracedMeta):
     # Agent management -----------------------------------------------------
 
     def agent(self, name: str) -> AgentBuilder:
+        """Create a new agent using the fluent builder API.
+
+        Args:
+            name: Unique identifier for the agent. Used for visibility controls and metrics.
+
+        Returns:
+            AgentBuilder for fluent configuration
+
+        Raises:
+            ValueError: If an agent with this name already exists
+
+        Examples:
+            >>> # Basic agent
+            >>> pizza_agent = (
+            ...     flock.agent("pizza_master")
+            ...     .description("Creates delicious pizza recipes")
+            ...     .consumes(DreamPizza)
+            ...     .publishes(Pizza)
+            ... )
+
+            >>> # Advanced agent with filtering
+            >>> critic = (
+            ...     flock.agent("critic")
+            ...     .consumes(Movie, where=lambda m: m.rating >= 8)
+            ...     .publishes(Review)
+            ...     .with_utilities(RateLimiter(max_calls=10))
+            ... )
+        """
         if name in self._agents:
             raise ValueError(f"Agent '{name}' already registered.")
         return AgentBuilder(self, name)
@@ -346,6 +399,32 @@ class Flock(metaclass=AutoTracedMeta):
     # Runtime --------------------------------------------------------------
 
     async def run_until_idle(self) -> None:
+        """Wait for all scheduled agent tasks to complete.
+
+        This method blocks until the blackboard reaches a stable state where no
+        agents are queued for execution. Essential for batch processing and ensuring
+        all agent cascades complete before continuing.
+
+        Note:
+            Automatically resets circuit breaker counters and shuts down MCP connections
+            when idle. Used with publish() for event-driven workflows.
+
+        Examples:
+            >>> # Event-driven workflow (recommended)
+            >>> await flock.publish(task1)
+            >>> await flock.publish(task2)
+            >>> await flock.run_until_idle()  # Wait for all cascades
+            >>> # All agents have finished processing
+
+            >>> # Parallel batch processing
+            >>> await flock.publish_many([task1, task2, task3])
+            >>> await flock.run_until_idle()  # All tasks processed in parallel
+
+        See Also:
+            - publish(): Event-driven artifact publishing
+            - publish_many(): Batch publishing for parallel execution
+            - invoke(): Direct agent invocation without cascade
+        """
         while self._tasks:
             await asyncio.sleep(0.01)
             pending = {task for task in self._tasks if not task.done()}
@@ -368,11 +447,59 @@ class Flock(metaclass=AutoTracedMeta):
         return await agent.execute(ctx, artifacts)
 
     async def arun(self, agent_builder: AgentBuilder, *inputs: BaseModel) -> list[Artifact]:
+        """Execute an agent with inputs and wait for all cascades to complete (async).
+
+        Convenience method that combines direct agent invocation with run_until_idle().
+        Useful for testing and synchronous request-response patterns.
+
+        Args:
+            agent_builder: Agent to execute (from flock.agent())
+            *inputs: Input objects (BaseModel instances)
+
+        Returns:
+            Artifacts produced by the agent and any triggered cascades
+
+        Examples:
+            >>> # Test a single agent
+            >>> flock = Flock("openai/gpt-4o-mini")
+            >>> pizza_agent = flock.agent("pizza").consumes(Idea).publishes(Pizza)
+            >>> results = await flock.arun(pizza_agent, Idea(topic="Margherita"))
+
+            >>> # Multiple inputs
+            >>> results = await flock.arun(
+            ...     task_agent,
+            ...     Task(name="deploy"),
+            ...     Task(name="test")
+            ... )
+
+        Note:
+            For event-driven workflows, prefer publish() + run_until_idle() for better
+            control over execution timing and parallel processing.
+        """
         artifacts = await self.direct_invoke(agent_builder.agent, list(inputs))
         await self.run_until_idle()
         return artifacts
 
     def run(self, agent_builder: AgentBuilder, *inputs: BaseModel) -> list[Artifact]:
+        """Synchronous wrapper for arun() - executes agent and waits for completion.
+
+        Args:
+            agent_builder: Agent to execute (from flock.agent())
+            *inputs: Input objects (BaseModel instances)
+
+        Returns:
+            Artifacts produced by the agent and any triggered cascades
+
+        Examples:
+            >>> # Synchronous execution (blocks until complete)
+            >>> flock = Flock("openai/gpt-4o-mini")
+            >>> agent = flock.agent("analyzer").consumes(Data).publishes(Report)
+            >>> results = flock.run(agent, Data(value=42))
+
+        Warning:
+            Cannot be called from within an async context. Use arun() instead
+            if already in an async function.
+        """
         return asyncio.run(self.arun(agent_builder, *inputs))
 
     async def shutdown(self) -> None:

{flock_core-0.5.0b59.dist-info → flock_core-0.5.0b60.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b59
+Version: 0.5.0b60
 Summary: Add your description here
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -32,10 +32,13 @@ Description-Content-Type: text/markdown
   <img alt="Flock Banner" src="https://raw.githubusercontent.com/whiteducksoftware/flock/master/docs/assets/images/flock.png" width="800">
 </p>
 <p align="center">
+  <a href="https://docs.flock.whiteduck.de" target="_blank"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge&logo=readthedocs"></a>
   <a href="https://pypi.org/project/flock-core/" target="_blank"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/flock-core?style=for-the-badge&logo=pypi&label=pip%20version"></a>
   <img alt="Python Version" src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python">
   <a href="LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/pypi/l/flock-core?style=for-the-badge"></a>
   <a href="https://whiteduck.de" target="_blank"><img alt="Built by white duck" src="https://img.shields.io/badge/Built%20by-white%20duck%20GmbH-white?style=for-the-badge&labelColor=black"></a>
+  <img alt="Test Coverage" src="https://img.shields.io/badge/coverage-77%25-green?style=for-the-badge">
+  <img alt="Tests" src="https://img.shields.io/badge/tests-743%20passing-brightgreen?style=for-the-badge">
 </p>
 
 ---
@@ -46,7 +49,14 @@ Description-Content-Type: text/markdown
 
 Flock is a production-focused framework for orchestrating AI agents through **declarative type contracts** and **blackboard architecture**—proven patterns from distributed systems, decades of experience with microservice architectures, and classical AI—now applied to modern LLMs.
 
+**📖 [Read the full documentation →](https://docs.flock.whiteduck.de)**
 
+**Quick links:**
+- **[Getting Started](https://docs.flock.whiteduck.de/getting-started/installation/)** - Installation and first steps
+- **[Tutorials](https://docs.flock.whiteduck.de/tutorials/)** - Step-by-step learning path
+- **[User Guides](https://docs.flock.whiteduck.de/guides/)** - In-depth feature documentation
+- **[API Reference](https://docs.flock.whiteduck.de/reference/api/)** - Complete API documentation
+- **[Roadmap](https://docs.flock.whiteduck.de/about/roadmap/)** - What's coming in v1.0
 
 ---
 
@@ -912,13 +922,14 @@ uv run python examples/05-claudes-workshop/lesson_01_code_detective.py
 - 📚 [7-Lesson Workshop](examples/05-claudes-workshop/) - Progressive lessons from basics to advanced
 - 🆚 [The Blackboard](examples/02-the-blackboard/) - See data-driven orchestration without graphs
 - 🎯 [Declarative Basics](examples/01-the-declarative-way/) - Understanding declarative programming
-- 📖 [Documentation](AGENTS.md) - Complete development guide
+- 📖 [Documentation](https://docs.flock.whiteduck.de) - Complete online documentation
+- 📘 [AGENTS.md](AGENTS.md) - Development guide
 
 ---
 
 ## Contributing
 
-We're building Flock in the open. See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for development setup.
+We're building Flock in the open. See **[Contributing Guide](https://docs.flock.whiteduck.de/about/contributing/)** for development setup, or check [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) locally.
 
 **We welcome:**
 - Bug reports and feature requests
@@ -981,7 +992,7 @@ We're calling this 0.5 to signal:
 
 **"Declarative contracts eliminate prompt hell. Blackboard architecture eliminates graph spaghetti. Proven patterns applied to modern LLMs."**
 
-[⭐ Star on GitHub](https://github.com/whiteducksoftware/flock-flow) | [📖 Read the Docs](AGENTS.md) | [🚀 Try Examples](examples/) | [💼 Enterprise Support](mailto:support@whiteduck.de)
+[⭐ Star on GitHub](https://github.com/whiteducksoftware/flock-flow) | [📖 Documentation](https://docs.flock.whiteduck.de) | [🚀 Try Examples](examples/) | [💼 Enterprise Support](mailto:support@whiteduck.de)
 
 </div>
 

{flock_core-0.5.0b59.dist-info → flock_core-0.5.0b60.dist-info}/RECORD

@@ -1,10 +1,10 @@
 flock/__init__.py,sha256=fvp4ltfaAGmYliShuTY_XVIpOUN6bMXbWiBnwb1NBoM,310
-flock/agent.py,sha256=vNvfn6UzIyjGLdRwPutoWUJQETnPpX4K8Y2H8lMEFXM,25341
+flock/agent.py,sha256=V8fnLxE7vtTf5R7A-oCAY8Tq_LVf63i2EyZOf5e-gq4,31977
 flock/artifacts.py,sha256=Xnizu0V4Jbwd1yV_FhXjUZG8Em-5GYsLt7sMX0V2OKI,2222
 flock/cli.py,sha256=Ay_Z4KDd5wnnF1fLr0NqjMF7kRm_9X_1RXyv5GETDAY,2126
 flock/components.py,sha256=17vhNMHKc3VUruEbSdb9YNKcDziIe0coS9jpfWBmX4o,6259
 flock/examples.py,sha256=61xkD48yCW-aDrUXIrqrvxLtV8Vn4DrraQrHrrEUnWA,3530
-flock/orchestrator.py,sha256=u5OOyB49kTd8lHyI4gprGk_YyNhQ3nZgYSKz45LpZiQ,28761
+flock/orchestrator.py,sha256=FJGsK9YU0J8KhLdSJU9dkDKiWs6gktniafLwUIxi_x0,33729
 flock/registry.py,sha256=s0-H-TMtOsDZiZQCc7T1tYiWQg3OZHn5T--jaI_INIc,4786
 flock/runtime.py,sha256=3C8AYzwwQEwFvwAsIoFN9QSQDWT8l8KzgekhPEsdUM0,8508
 flock/service.py,sha256=cfvcsqZw9xOsEggncZ08zmiDxFiZpxsBYDSji5OIQQ8,5256
@@ -24,7 +24,7 @@ flock/engines/dspy_engine.py,sha256=Q2gPYLW_f8f-JuBYOMtjtoCZH8Fc447zWF8cHpJl4ew,
 flock/frontend/README.md,sha256=OFdOItV8FGifmUDb694rV2xLC0vl1HlR5KBEtYv5AB0,25054
 flock/frontend/index.html,sha256=BFg1VR_YVAJ_MGN16xa7sT6wTGwtFYUhfJhGuKv89VM,312
 flock/frontend/package-lock.json,sha256=F-KmPhq6IbHXzxtmHL0S7dt6DGs4fWrOkrfKeXaSx6U,150998
-flock/frontend/package.json,sha256=X5mMewghkW5K03Y4CI6unF2GIGbV0QoS-kZ04RNtQ3k,1258
+flock/frontend/package.json,sha256=8cpupeJo0xlJgHiEHpBYCU-nHFiiNGJ73NfZLr5-FSg,1258
 flock/frontend/tsconfig.json,sha256=B9p9jXohg_jrCZAq5_yIHvznpeXHiHQkwUZrVE2oMRA,705
 flock/frontend/tsconfig.node.json,sha256=u5_YWSqeNkZBRBIZ8Q2E2q6bospcyF23mO-taRO7glc,233
 flock/frontend/vite.config.ts,sha256=OQOr6Hl75iW7EvEm2_GXFdicYWthgdLhp4lz3d7RkJA,566
@@ -508,8 +508,8 @@ flock/themes/zenburned.toml,sha256=UEmquBbcAO3Zj652XKUwCsNoC2iQSlIh-q5c6DH-7Kc,1
 flock/themes/zenwritten-dark.toml,sha256=-dgaUfg1iCr5Dv4UEeHv_cN4GrPUCWAiHSxWK20X1kI,1663
 flock/themes/zenwritten-light.toml,sha256=G1iEheCPfBNsMTGaVpEVpDzYBHA_T-MV27rolUYolmE,1666
 flock/utility/output_utility_component.py,sha256=yVHhlIIIoYKziI5UyT_zvQb4G-NsxCTgLwA1wXXTTj4,9047
-flock_core-0.5.0b59.dist-info/METADATA,sha256=giTj_P11jQIQwHGwYtXmUS5MK6_Rb2au_3Ytw_w79U0,34735
-flock_core-0.5.0b59.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-flock_core-0.5.0b59.dist-info/entry_points.txt,sha256=UQdPmtHd97gSA_IdLt9MOd-1rrf_WO-qsQeIiHWVrp4,42
-flock_core-0.5.0b59.dist-info/licenses/LICENSE,sha256=U3IZuTbC0yLj7huwJdldLBipSOHF4cPf6cUOodFiaBE,1072
-flock_core-0.5.0b59.dist-info/RECORD,,
+flock_core-0.5.0b60.dist-info/METADATA,sha256=BFJPOOq0FFHMUP4FdjcGQO8rl5-fi0ItNfZTPhF9vlU,35901
+flock_core-0.5.0b60.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+flock_core-0.5.0b60.dist-info/entry_points.txt,sha256=UQdPmtHd97gSA_IdLt9MOd-1rrf_WO-qsQeIiHWVrp4,42
+flock_core-0.5.0b60.dist-info/licenses/LICENSE,sha256=U3IZuTbC0yLj7huwJdldLBipSOHF4cPf6cUOodFiaBE,1072
+flock_core-0.5.0b60.dist-info/RECORD,,