flock-core 0.5.10__py3-none-any.whl → 0.5.20__py3-none-any.whl

flock/{service.py → api/service.py}

@@ -10,18 +10,46 @@ from uuid import UUID
 from fastapi import FastAPI, HTTPException, Query
 from fastapi.responses import PlainTextResponse
 
+from flock.api.models import (
+    Agent,
+    AgentListResponse,
+    AgentRunRequest,
+    AgentRunResponse,
+    AgentSubscription,
+    ArtifactListResponse,
+    ArtifactPublishRequest,
+    ArtifactPublishResponse,
+    ArtifactSummaryResponse,
+    CorrelationStatusResponse,
+    HealthResponse,
+    ProducedArtifact,
+)
+from flock.core.store import ArtifactEnvelope, ConsumptionRecord, FilterConfig
 from flock.registry import type_registry
-from flock.store import ArtifactEnvelope, ConsumptionRecord, FilterConfig
 
 
 if TYPE_CHECKING:
-    from flock.orchestrator import Flock
+    from flock.core import Flock
 
 
 class BlackboardHTTPService:
     def __init__(self, orchestrator: Flock) -> None:
         self.orchestrator = orchestrator
-        self.app = FastAPI(title="Blackboard Agents Service", version="1.0.0")
+        self.app = FastAPI(
+            title="Flock REST API Documentation",
+            version="1.0.0",
+            description="RESTful API for interacting with Flock agents and artifacts",
+            openapi_tags=[
+                {
+                    "name": "Public API",
+                    "description": "**Production-ready endpoints** for publishing artifacts, running agents, and querying data. Use these in your applications.",
+                },
+                {
+                    "name": "Health & Metrics",
+                    "description": "Monitoring endpoints for health checks and metrics collection.",
+                },
+            ],
+        )
         self._register_routes()
 
     def _register_routes(self) -> None:
@@ -92,19 +120,25 @@ class BlackboardHTTPService:
                 end=_parse_datetime(end, "to"),
             )
 
-        @app.post("/api/v1/artifacts")
-        async def publish_artifact(body: dict[str, Any]) -> dict[str, str]:
-            type_name = body.get("type")
-            payload = body.get("payload") or {}
-            if not type_name:
-                raise HTTPException(status_code=400, detail="type is required")
+        @app.post(
+            "/api/v1/artifacts",
+            response_model=ArtifactPublishResponse,
+            tags=["Public API"],
+        )
+        async def publish_artifact(
+            body: ArtifactPublishRequest,
+        ) -> ArtifactPublishResponse:
             try:
-                await orchestrator.publish({"type": type_name, **payload})
+                await orchestrator.publish({"type": body.type, **body.payload})
             except Exception as exc:  # pragma: no cover - FastAPI converts
                 raise HTTPException(status_code=400, detail=str(exc)) from exc
-            return {"status": "accepted"}
+            return ArtifactPublishResponse(status="accepted")
 
-        @app.get("/api/v1/artifacts")
+        @app.get(
+            "/api/v1/artifacts",
+            response_model=ArtifactListResponse,
+            tags=["Public API"],
+        )
         async def list_artifacts(
             type_names: list[str] | None = Query(None, alias="type"),
             produced_by: list[str] | None = Query(None),
@@ -116,7 +150,7 @@ class BlackboardHTTPService:
             limit: int = Query(50, ge=1, le=500),
             offset: int = Query(0, ge=0),
             embed_meta: bool = Query(False, alias="embed_meta"),
-        ) -> dict[str, Any]:
+        ) -> ArtifactListResponse:
             filters = _make_filter_config(
                 type_names,
                 produced_by,
@@ -140,12 +174,16 @@ class BlackboardHTTPService:
                     )
                 else:
                     items.append(_serialize_artifact(artifact))
-            return {
-                "items": items,
-                "pagination": {"limit": limit, "offset": offset, "total": total},
-            }
+            return ArtifactListResponse(
+                items=items,
+                pagination={"limit": limit, "offset": offset, "total": total},
+            )
 
-        @app.get("/api/v1/artifacts/summary")
+        @app.get(
+            "/api/v1/artifacts/summary",
+            response_model=ArtifactSummaryResponse,
+            tags=["Public API"],
+        )
         async def summarize_artifacts(
             type_names: list[str] | None = Query(None, alias="type"),
             produced_by: list[str] | None = Query(None),
@@ -154,7 +192,7 @@ class BlackboardHTTPService:
             start: str | None = Query(None, alias="from"),
             end: str | None = Query(None, alias="to"),
             visibility: list[str] | None = Query(None),
-        ) -> dict[str, Any]:
+        ) -> ArtifactSummaryResponse:
             filters = _make_filter_config(
                 type_names,
                 produced_by,
@@ -165,33 +203,30 @@ class BlackboardHTTPService:
                 end,
             )
             summary = await orchestrator.store.summarize_artifacts(filters)
-            return {"summary": summary}
+            return ArtifactSummaryResponse(summary=summary)
 
-        @app.get("/api/v1/artifacts/{artifact_id}")
+        @app.get("/api/v1/artifacts/{artifact_id}", tags=["Public API"])
         async def get_artifact(artifact_id: UUID) -> dict[str, Any]:
             artifact = await orchestrator.store.get(artifact_id)
             if artifact is None:
                 raise HTTPException(status_code=404, detail="artifact not found")
             return _serialize_artifact(artifact)
 
-        @app.post("/api/v1/agents/{name}/run")
-        async def run_agent(name: str, body: dict[str, Any]) -> dict[str, Any]:
+        @app.post(
+            "/api/v1/agents/{name}/run",
+            response_model=AgentRunResponse,
+            tags=["Public API"],
+        )
+        async def run_agent(name: str, body: AgentRunRequest) -> AgentRunResponse:
             try:
                 agent = orchestrator.get_agent(name)
             except KeyError as exc:
                 raise HTTPException(status_code=404, detail="agent not found") from exc
 
-            inputs_data: list[dict[str, Any]] = body.get("inputs") or []
             inputs = []
-            for item in inputs_data:
-                type_name = item.get("type")
-                payload = item.get("payload") or {}
-                if not type_name:
-                    raise HTTPException(
-                        status_code=400, detail="Each input requires 'type'."
-                    )
-                model = type_registry.resolve(type_name)
-                instance = model(**payload)
+            for item in body.inputs:
+                model = type_registry.resolve(item.type)
+                instance = model(**item.payload)
                 inputs.append(instance)
 
             try:
@@ -201,40 +236,42 @@ class BlackboardHTTPService:
                     status_code=500, detail=f"Agent execution failed: {exc}"
                 ) from exc
 
-            return {
-                "artifacts": [
-                    {
-                        "id": str(artifact.id),
-                        "type": artifact.type,
-                        "payload": artifact.payload,
-                        "produced_by": artifact.produced_by,
-                    }
+            return AgentRunResponse(
+                artifacts=[
+                    ProducedArtifact(
+                        id=str(artifact.id),
+                        type=artifact.type,
+                        payload=artifact.payload,
+                        produced_by=artifact.produced_by,
+                    )
                     for artifact in outputs
                 ]
-            }
+            )
 
-        @app.get("/api/v1/agents")
-        async def list_agents() -> dict[str, Any]:
-            return {
-                "agents": [
-                    {
-                        "name": agent.name,
-                        "description": agent.description,
-                        "subscriptions": [
-                            {
-                                "types": list(subscription.type_names),
-                                "mode": subscription.mode,
-                                "delivery": subscription.delivery,
-                            }
+        @app.get(
+            "/api/v1/agents", response_model=AgentListResponse, tags=["Public API"]
+        )
+        async def list_agents() -> AgentListResponse:
+            return AgentListResponse(
+                agents=[
+                    Agent(
+                        name=agent.name,
+                        description=agent.description or "",
+                        subscriptions=[
+                            AgentSubscription(
+                                types=list(subscription.type_names),
+                                mode=subscription.mode,
+                                delivery=subscription.delivery,
+                            )
                             for subscription in agent.subscriptions
                         ],
-                        "outputs": [output.spec.type_name for output in agent.outputs],
-                    }
+                        outputs=[output.spec.type_name for output in agent.outputs],
+                    )
                     for agent in orchestrator.agents
                 ]
-            }
+            )
 
-        @app.get("/api/v1/agents/{agent_id}/history-summary")
+        @app.get("/api/v1/agents/{agent_id}/history-summary", tags=["Public API"])
         async def agent_history(
             agent_id: str,
             type_names: list[str] | None = Query(None, alias="type"),
@@ -257,11 +294,32 @@ class BlackboardHTTPService:
             summary = await orchestrator.store.agent_history_summary(agent_id, filters)
             return {"agent_id": agent_id, "summary": summary}
 
-        @app.get("/health")
-        async def health() -> dict[str, str]:  # pragma: no cover - trivial
-            return {"status": "ok"}
+        @app.get(
+            "/api/v1/correlations/{correlation_id}/status",
+            response_model=CorrelationStatusResponse,
+            tags=["Public API"],
+        )
+        async def get_correlation_status(
+            correlation_id: str,
+        ) -> CorrelationStatusResponse:
+            """Get the status of a workflow by correlation ID.
+
+            Returns workflow state (active/completed/failed/not_found), pending work status,
+            artifact counts, error counts, and timestamps.
+
+            This endpoint is useful for polling to check if a workflow has completed.
+            """
+            try:
+                status = await orchestrator.get_correlation_status(correlation_id)
+                return CorrelationStatusResponse(**status)
+            except ValueError as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+        @app.get("/health", response_model=HealthResponse, tags=["Health & Metrics"])
+        async def health() -> HealthResponse:  # pragma: no cover - trivial
+            return HealthResponse(status="ok")
 
-        @app.get("/metrics")
+        @app.get("/metrics", tags=["Health & Metrics"])
         async def metrics() -> PlainTextResponse:
             lines = [
                 f"blackboard_{key} {value}"

flock/cli.py

@@ -12,8 +12,8 @@ from typer.models import OptionInfo
 
 # Lazy import: only import examples when CLI commands are invoked
 # This prevents polluting type_registry on every package import
-from flock.service import BlackboardHTTPService
-from flock.store import SQLiteBlackboardStore
+from flock.api.service import BlackboardHTTPService
+from flock.core.store import SQLiteBlackboardStore
 
 
 app = typer.Typer(help="Blackboard Agents CLI")

flock/components/__init__.py

@@ -0,0 +1,41 @@
+"""Component library for extending Flock agents and orchestrators."""
+
+# Agent components
+from flock.components.agent import (
+    AgentComponent,
+    AgentComponentConfig,
+    EngineComponent,
+    OutputUtilityComponent,
+    OutputUtilityConfig,
+    TracedModelMeta,
+)
+
+# Orchestrator components
+from flock.components.orchestrator import (
+    BuiltinCollectionComponent,
+    CircuitBreakerComponent,
+    CollectionResult,
+    DeduplicationComponent,
+    OrchestratorComponent,
+    OrchestratorComponentConfig,
+    ScheduleDecision,
+)
+
+
+__all__ = [
+    # Agent components
+    "AgentComponent",
+    "AgentComponentConfig",
+    "EngineComponent",
+    "OutputUtilityComponent",
+    "OutputUtilityConfig",
+    "TracedModelMeta",
+    # Orchestrator components
+    "BuiltinCollectionComponent",
+    "CircuitBreakerComponent",
+    "CollectionResult",
+    "DeduplicationComponent",
+    "OrchestratorComponent",
+    "OrchestratorComponentConfig",
+    "ScheduleDecision",
+]

flock/components/agent/__init__.py

@@ -0,0 +1,22 @@
+"""Agent component library - Base classes and built-in components."""
+
+from flock.components.agent.base import (
+    AgentComponent,
+    AgentComponentConfig,
+    EngineComponent,
+    TracedModelMeta,
+)
+from flock.components.agent.output_utility import (
+    OutputUtilityComponent,
+    OutputUtilityConfig,
+)
+
+
+__all__ = [
+    "AgentComponent",
+    "AgentComponentConfig",
+    "EngineComponent",
+    "OutputUtilityComponent",
+    "OutputUtilityConfig",
+    "TracedModelMeta",
+]

flock/{components.py → components/agent/base.py}

@@ -1,4 +1,4 @@
-"""Agent component abstractions."""
+"""Agent component base classes and configuration."""
 
 from __future__ import annotations
 
@@ -13,8 +13,8 @@ from flock.logging.auto_trace import AutoTracedMeta
 
 if TYPE_CHECKING:  # pragma: no cover - type checking only
     from flock.agent import Agent, OutputGroup
-    from flock.artifacts import Artifact
-    from flock.runtime import Context, EvalInputs, EvalResult
+    from flock.core.artifacts import Artifact
+    from flock.utils.runtime import Context, EvalInputs, EvalResult
 
 T = TypeVar("T", bound="AgentComponentConfig")
 
@@ -219,4 +219,5 @@ __all__ = [
     "AgentComponent",
     "AgentComponentConfig",
     "EngineComponent",
+    "TracedModelMeta",
 ]

flock/{utility/output_utility_component.py → components/agent/output_utility.py}

@@ -1,25 +1,24 @@
-# src/flock/components/utility/output_utility_component.py
-"""Output formatting and display functionality for agents using unified component architecture."""
+"""Output formatting and display functionality for agents."""
 
 import re
 from typing import TYPE_CHECKING, Any
 
 from pydantic import Field
 
-from flock.components import AgentComponent, AgentComponentConfig
+from flock.components.agent.base import AgentComponent, AgentComponentConfig
 from flock.logging.formatters.themed_formatter import (
     ThemedAgentResultFormatter,
 )
 from flock.logging.formatters.themes import OutputTheme
 from flock.logging.logging import get_logger
-from flock.runtime import Context, EvalInputs, EvalResult
+from flock.utils.runtime import Context, EvalInputs, EvalResult
 
 
 if TYPE_CHECKING:  # pragma: no cover - type checking only
-    from flock.agent import Agent
+    from flock.core import Agent
 
 
-logger = get_logger("components.utility.output")
+logger = get_logger("components.agent.output_utility")
 
 
 class OutputUtilityConfig(AgentComponentConfig):
@@ -188,7 +187,7 @@ class OutputUtilityComponent(AgentComponent):
             if ctx:
                 import asyncio
 
-                from flock.agent import Agent
+                from flock.core import Agent
 
                 # Wait until no streams are active
                 max_wait = 30  # seconds
@@ -244,3 +243,9 @@ class OutputUtilityComponent(AgentComponent):
     def add_custom_formatter(self, key: str, formatter_name: str) -> None:
         """Add a custom formatter for a specific output key."""
         self.config.custom_formatters[key] = formatter_name
+
+
+__all__ = [
+    "OutputUtilityComponent",
+    "OutputUtilityConfig",
+]

flock/components/orchestrator/__init__.py

@@ -0,0 +1,22 @@
+"""Orchestrator component library - Base classes and built-in components."""
+
+from flock.components.orchestrator.base import (
+    CollectionResult,
+    OrchestratorComponent,
+    OrchestratorComponentConfig,
+    ScheduleDecision,
+)
+from flock.components.orchestrator.circuit_breaker import CircuitBreakerComponent
+from flock.components.orchestrator.collection import BuiltinCollectionComponent
+from flock.components.orchestrator.deduplication import DeduplicationComponent
+
+
+__all__ = [
+    "BuiltinCollectionComponent",
+    "CircuitBreakerComponent",
+    "CollectionResult",
+    "DeduplicationComponent",
+    "OrchestratorComponent",
+    "OrchestratorComponentConfig",
+    "ScheduleDecision",
+]