flock-core 0.5.9__py3-none-any.whl → 0.5.11__py3-none-any.whl

flock/orchestrator_component.py

@@ -150,7 +150,9 @@ class OrchestratorComponent(BaseModel, metaclass=TracedModelMeta):
         >>> # Simple component
         >>> class LoggingComponent(OrchestratorComponent):
         ...     async def on_agent_scheduled(self, orch, agent, artifacts, task):
-        ...         print(f"Agent {agent.name} scheduled with {len(artifacts)} artifacts")
+        ...         print(
+        ...             f"Agent {agent.name} scheduled with {len(artifacts)} artifacts"
+        ...         )
 
         >>> # Circuit breaker component
         >>> class CircuitBreakerComponent(OrchestratorComponent):
@@ -166,7 +168,9 @@ class OrchestratorComponent(BaseModel, metaclass=TracedModelMeta):
     """
 
     name: str | None = None
-    config: OrchestratorComponentConfig = Field(default_factory=OrchestratorComponentConfig)
+    config: OrchestratorComponentConfig = Field(
+        default_factory=OrchestratorComponentConfig
+    )
     priority: int = 0  # Lower priority = earlier execution
 
     # ──────────────────────────────────────────────────────────
@@ -355,7 +359,7 @@ class OrchestratorComponent(BaseModel, metaclass=TracedModelMeta):
             ...     await self.ws.broadcast({
             ...         "event": "agent_scheduled",
             ...         "agent": agent.name,
-            ...         "count": len(artifacts)
+            ...         "count": len(artifacts),
             ...     })
         """
 
@@ -484,7 +488,10 @@ class BuiltinCollectionComponent(OrchestratorComponent):
                     subscription_index=subscription_index,
                 )
 
-                if subscription.batch.timeout and orchestrator._batch_timeout_task is None:
+                if (
+                    subscription.batch.timeout
+                    and orchestrator._batch_timeout_task is None
+                ):
                     import asyncio
 
                     orchestrator._batch_timeout_task = asyncio.create_task(
@@ -500,7 +507,10 @@ class BuiltinCollectionComponent(OrchestratorComponent):
                         subscription_index=subscription_index,
                     )
 
-                    if subscription.batch.timeout and orchestrator._batch_timeout_task is None:
+                    if (
+                        subscription.batch.timeout
+                        and orchestrator._batch_timeout_task is None
+                    ):
                         import asyncio
 
                         orchestrator._batch_timeout_task = asyncio.create_task(

flock/patches/dspy_streaming_patch.py

@@ -45,7 +45,9 @@ def patched_sync_send_to_stream(stream, message):
         try:
             asyncio.run(_send())
         except Exception as e:
-            logger.debug(f"DSPy status message send failed in sync context (non-critical): {e}")
+            logger.debug(
+                f"DSPy status message send failed in sync context (non-critical): {e}"
+            )
 
 
 def apply_patch():
@@ -55,12 +57,16 @@ def apply_patch():
 
         # Store original for reference (in case we need to restore)
         if not hasattr(dspy_messages, "_original_sync_send_to_stream"):
-            dspy_messages._original_sync_send_to_stream = dspy_messages.sync_send_to_stream
+            dspy_messages._original_sync_send_to_stream = (
+                dspy_messages.sync_send_to_stream
+            )
 
         # Replace with our non-blocking version
         dspy_messages.sync_send_to_stream = patched_sync_send_to_stream
 
-        logger.info("Applied DSPy streaming patch - status messages are now non-blocking")
+        logger.info(
+            "Applied DSPy streaming patch - status messages are now non-blocking"
+        )
         return True
 
     except Exception as e:
@@ -74,7 +80,9 @@ def restore_original():
         import dspy.streaming.messages as dspy_messages
 
         if hasattr(dspy_messages, "_original_sync_send_to_stream"):
-            dspy_messages.sync_send_to_stream = dspy_messages._original_sync_send_to_stream
+            dspy_messages.sync_send_to_stream = (
+                dspy_messages._original_sync_send_to_stream
+            )
             logger.info("Restored original DSPy streaming function")
             return True
 

flock/registry.py

@@ -25,9 +25,13 @@ class TypeRegistry:
 
     def register(self, model: type[BaseModel], name: str | None = None) -> str:
         if not issubclass(model, BaseModel):
-            raise RegistryError("Only Pydantic models can be registered as artifact types.")
+            raise RegistryError(
+                "Only Pydantic models can be registered as artifact types."
+            )
         type_name = (
-            name or getattr(model, "__flock_type__", None) or f"{model.__module__}.{model.__name__}"
+            name
+            or getattr(model, "__flock_type__", None)
+            or f"{model.__module__}.{model.__name__}"
         )
         existing_model = self._by_name.get(type_name)
         if existing_model is not None and existing_model is not model:
@@ -127,7 +131,9 @@ def flock_type(model: type[BaseModel] | None = None, *, name: str | None = None)
     return _wrap(model)
 
 
-def flock_tool(func: Callable[..., Any] | None = None, *, name: str | None = None) -> Any:
+def flock_tool(
+    func: Callable[..., Any] | None = None, *, name: str | None = None
+) -> Any:
     """Decorator to register a deterministic helper function for agents."""
 
     def _wrap(callable_: Callable[..., Any]) -> Callable[..., Any]:

flock/runtime.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any
 from uuid import UUID
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 from flock.artifacts import Artifact
 
@@ -28,7 +28,9 @@ class EvalInputs(BaseModel):
 
         Example:
             >>> class TaskProcessor(EngineComponent):
-            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...     async def evaluate(
+            ...         self, agent, ctx, inputs: EvalInputs
+            ...     ) -> EvalResult:
             ...         task = inputs.first_as(Task)
             ...         if not task:
             ...             return EvalResult.empty()
@@ -88,9 +90,13 @@ class EvalResult(BaseModel):
 
         Example:
             >>> class TaskProcessor(EngineComponent):
-            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...     async def evaluate(
+            ...         self, agent, ctx, inputs: EvalInputs
+            ...     ) -> EvalResult:
             ...         task = inputs.first_as(Task)
-            ...         processed = Task(name=f"Done: {task.name}", priority=task.priority)
+            ...         processed = Task(
+            ...             name=f"Done: {task.name}", priority=task.priority
+            ...         )
             ...         return EvalResult.from_object(processed, agent=agent)
         """
         from flock.artifacts import Artifact
@@ -136,14 +142,16 @@ class EvalResult(BaseModel):
 
         Example:
             >>> class MovieEngine(EngineComponent):
-            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...     async def evaluate(
+            ...         self, agent, ctx, inputs: EvalInputs
+            ...     ) -> EvalResult:
             ...         idea = inputs.first_as(Idea)
-            ...         movie = Movie(title=idea.topic.upper(), runtime=240, synopsis="...")
+            ...         movie = Movie(
+            ...             title=idea.topic.upper(), runtime=240, synopsis="..."
+            ...         )
             ...         tagline = Tagline(line="Don't miss it!")
             ...         return EvalResult.from_objects(
-            ...             movie, tagline,
-            ...             agent=agent,
-            ...             metrics={"confidence": 0.9}
+            ...             movie, tagline, agent=agent, metrics={"confidence": 0.9}
             ...         )
         """
         from flock.artifacts import Artifact
@@ -190,7 +198,9 @@ class EvalResult(BaseModel):
 
         Example:
             >>> class ConditionalProcessor(EngineComponent):
-            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...     async def evaluate(
+            ...         self, agent, ctx, inputs: EvalInputs
+            ...     ) -> EvalResult:
             ...         task = inputs.first_as(Task)
             ...         if task.priority < 3:
             ...             return EvalResult.empty()  # Skip low priority
@@ -229,12 +239,15 @@ class EvalResult(BaseModel):
 
         Example:
             >>> class ValidationAgent(EngineComponent):
-            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...     async def evaluate(
+            ...         self, agent, ctx, inputs: EvalInputs
+            ...     ) -> EvalResult:
             ...         task = inputs.first_as(Task)
             ...         is_valid = task.priority >= 1
-            ...         return EvalResult.with_state(
-            ...             {"validation_passed": is_valid, "validator": "priority_check"}
-            ...         )
+            ...         return EvalResult.with_state({
+            ...             "validation_passed": is_valid,
+            ...             "validator": "priority_check",
+            ...         })
         """
         return cls(
             artifacts=[],
@@ -245,13 +258,51 @@ class EvalResult(BaseModel):
 
 
 class Context(BaseModel):
-    board: Any
-    orchestrator: Any
-    correlation_id: UUID | None = None  # NEW!
+    """Runtime context for agent execution.
+
+    SECURITY FIX (2025-10-17): Simplified to data-only design.
+    Context is now just pre-filtered data with ZERO capabilities.
+
+    Vulnerabilities fixed:
+    - Vulnerability #1 (READ): Agents could bypass visibility via ctx.board.list()
+    - Vulnerability #2 (WRITE): Agents could bypass validation via ctx.board.publish()
+    - Vulnerability #3 (GOD MODE): Agents had unlimited ctx.orchestrator access
+    - Vulnerability #4 (STORE ACCESS): Agents could access ctx.store or ctx.provider._store
+
+    Solution: Orchestrator evaluates context BEFORE creating Context.
+    Engines receive only pre-filtered artifact data via ctx.artifacts.
+    No provider, no store, no capabilities - just immutable data.
+
+    Design Philosophy: Engines are pure functions (input + context → output).
+    They don't query, they don't mutate - they only transform data.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    # ❌ REMOVED: board: Any (security vulnerability)
+    # ❌ REMOVED: orchestrator: Any (security vulnerability)
+    # ❌ REMOVED: provider: Any (security vulnerability - engines could call provider methods)
+    # ❌ REMOVED: store: Any (security vulnerability - direct store access)
+
+    # ✅ FINAL SOLUTION: Pre-filtered artifacts (evaluated by orchestrator)
+    # Engines can only read this list - they cannot query for more data
+    artifacts: list[Artifact] = Field(
+        default_factory=list,
+        description="Pre-filtered conversation context artifacts (evaluated by orchestrator using context provider)",
+    )
+
+    # ✅ Agent identity (informational only - used by orchestrator for logging/tracing)
+    agent_identity: Any = Field(
+        default=None,
+        description="Agent identity (informational) - engines cannot use this to query data",
+    )
+
+    correlation_id: UUID | None = None
     task_id: str
     state: dict[str, Any] = Field(default_factory=dict)
     is_batch: bool = Field(
-        default=False, description="True if this execution is processing a BatchSpec accumulation"
+        default=False,
+        description="True if this execution is processing a BatchSpec accumulation",
     )
 
     def get_variable(self, key: str, default: Any = None) -> Any:

flock/service.py

@@ -10,6 +10,20 @@ 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.registry import type_registry
 from flock.store import ArtifactEnvelope, ConsumptionRecord, FilterConfig
 
@@ -21,7 +35,21 @@ if TYPE_CHECKING:
 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:
@@ -40,7 +68,9 @@ class BlackboardHTTPService:
                 "visibility": artifact.visibility.model_dump(mode="json"),
                 "visibility_kind": getattr(artifact.visibility, "kind", "Unknown"),
                 "created_at": artifact.created_at.isoformat(),
-                "correlation_id": str(artifact.correlation_id) if artifact.correlation_id else None,
+                "correlation_id": str(artifact.correlation_id)
+                if artifact.correlation_id
+                else None,
                 "partition_key": artifact.partition_key,
                 "tags": sorted(artifact.tags),
                 "version": artifact.version,
@@ -56,7 +86,9 @@ class BlackboardHTTPService:
                     }
                     for record in consumptions
                 ]
-                data["consumed_by"] = sorted({record.consumer for record in consumptions})
+                data["consumed_by"] = sorted({
+                    record.consumer for record in consumptions
+                })
             return data
 
         def _parse_datetime(value: str | None, label: str) -> datetime | None:
@@ -65,7 +97,9 @@ class BlackboardHTTPService:
             try:
                 return datetime.fromisoformat(value)
             except ValueError as exc:  # pragma: no cover - FastAPI converts
-                raise HTTPException(status_code=400, detail=f"Invalid {label}: {value}") from exc
+                raise HTTPException(
+                    status_code=400, detail=f"Invalid {label}: {value}"
+                ) from exc
 
         def _make_filter_config(
             type_names: list[str] | None,
@@ -86,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),
@@ -110,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,
@@ -129,15 +169,21 @@ class BlackboardHTTPService:
             items: list[dict[str, Any]] = []
             for artifact in artifacts:
                 if isinstance(artifact, ArtifactEnvelope):
-                    items.append(_serialize_artifact(artifact.artifact, artifact.consumptions))
+                    items.append(
+                        _serialize_artifact(artifact.artifact, artifact.consumptions)
+                    )
                 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),
@@ -146,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,
@@ -157,31 +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:
@@ -191,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"),
@@ -247,13 +294,37 @@ 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}" for key, value in orchestrator.metrics.items()]
+            lines = [
+                f"blackboard_{key} {value}"
+                for key, value in orchestrator.metrics.items()
+            ]
             return PlainTextResponse("\n".join(lines))
 
     def run(