flock-core 0.4.543__py3-none-any.whl → 0.5.0__py3-none-any.whl

flock/registry.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+
+"""Runtime registries for blackboard artifact and function declarations."""
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class RegistryError(RuntimeError):
+    """Raised when a registry operation fails."""
+
+
+class TypeRegistry:
+    """In-memory registry for blackboard artifact types."""
+
+    def __init__(self) -> None:
+        self._by_name: dict[str, type[BaseModel]] = {}
+        self._by_cls: dict[type[BaseModel], str] = {}
+
+    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.")
+        type_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:
+            self._by_cls.pop(existing_model, None)
+        existing_name = self._by_cls.get(model)
+        if existing_name and existing_name != type_name:
+            self._by_name.pop(existing_name, None)
+
+        self._by_name[type_name] = model
+        self._by_cls[model] = type_name
+        model.__flock_type__ = type_name
+        return type_name
+
+    def resolve(self, type_name: str) -> type[BaseModel]:
+        try:
+            return self._by_name[type_name]
+        except KeyError as exc:  # pragma: no cover - defensive
+            raise RegistryError(f"Unknown artifact type '{type_name}'.") from exc
+
+    def resolve_name(self, type_name: str) -> str:
+        """
+        Resolve a type name (simple or qualified) to its canonical form.
+
+        Args:
+            type_name: Simple name ("Document") or qualified ("__main__.Document")
+
+        Returns:
+            Canonical type name from registry
+
+        Raises:
+            RegistryError: Type not found or ambiguous
+        """
+        # If already canonical, return as-is (O(1) lookup)
+        if type_name in self._by_name:
+            return type_name
+
+        # Search for models with matching simple name (O(n) scan)
+        matches = []
+        for canonical_name, model_cls in self._by_name.items():
+            if model_cls.__name__ == type_name:
+                matches.append(canonical_name)
+
+        if len(matches) == 0:
+            raise RegistryError(f"Unknown artifact type '{type_name}'.")
+        if len(matches) == 1:
+            return matches[0]
+        raise RegistryError(
+            f"Ambiguous type name '{type_name}'. Matches: {', '.join(matches)}. Use qualified name."
+        )
+
+    def name_for(self, model: type[BaseModel]) -> str:
+        try:
+            return self._by_cls[model]
+        except KeyError as exc:
+            raise RegistryError(
+                f"Model '{model.__name__}' is not registered as an artifact type."
+            ) from exc
+
+
+class FunctionRegistry:
+    """Registry for deterministic callable helpers (flock_tool)."""
+
+    def __init__(self) -> None:
+        self._callables: dict[str, Callable[..., Any]] = {}
+
+    def register(self, func: Callable[..., Any], *, name: str | None = None) -> str:
+        func_name = name or getattr(func, "__flock_tool__", None) or func.__name__
+        existing = self._callables.get(func_name)
+        if existing is func:
+            return func_name
+        self._callables[func_name] = func
+        func.__flock_tool__ = func_name
+        return func_name
+
+    def resolve(self, func_name: str) -> Callable[..., Any]:
+        try:
+            return self._callables[func_name]
+        except KeyError as exc:
+            raise RegistryError(
+                f"Function '{func_name}' is not registered with flock_tool."
+            ) from exc
+
+
+type_registry = TypeRegistry()
+function_registry = FunctionRegistry()
+
+
+def flock_type(model: type[BaseModel] | None = None, *, name: str | None = None) -> Any:
+    """Decorator to register a Pydantic model as a blackboard artifact type."""
+
+    def _wrap(cls: type[BaseModel]) -> type[BaseModel]:
+        type_registry.register(cls, name=name)
+        return cls
+
+    if model is None:
+        return _wrap
+    return _wrap(model)
+
+
+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]:
+        function_registry.register(callable_, name=name)
+        return callable_
+
+    if func is None:
+        return _wrap
+    return _wrap(func)
+
+
+__all__ = [
+    "RegistryError",
+    "flock_tool",
+    "flock_type",
+    "function_registry",
+    "type_registry",
+]

flock/runtime.py

@@ -0,0 +1,262 @@
+"""Runtime envelopes exchanged between orchestrator and components."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from flock.artifacts import Artifact
+
+
+class EvalInputs(BaseModel):
+    artifacts: list[Artifact] = Field(default_factory=list)
+    state: dict[str, Any] = Field(default_factory=dict)
+
+    def first_as(self, model_cls: type[BaseModel]) -> BaseModel | None:
+        """Extract first artifact as model instance.
+
+        Convenience method to deserialize the first artifact's payload
+        into a typed Pydantic model.
+
+        Args:
+            model_cls: Pydantic model class to deserialize to
+
+        Returns:
+            Model instance or None if no artifacts
+
+        Example:
+            >>> class TaskProcessor(EngineComponent):
+            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...         task = inputs.first_as(Task)
+            ...         if not task:
+            ...             return EvalResult.empty()
+            ...         # Process task...
+        """
+        if not self.artifacts:
+            return None
+        return model_cls(**self.artifacts[0].payload)
+
+    def all_as(self, model_cls: type[BaseModel]) -> list[BaseModel]:
+        """Extract all artifacts as model instances.
+
+        Args:
+            model_cls: Pydantic model class to deserialize to
+
+        Returns:
+            List of model instances (empty if no artifacts)
+
+        Example:
+            >>> tasks = inputs.all_as(Task)
+            >>> for task in tasks:
+            ...     # Process each task
+        """
+        return [model_cls(**artifact.payload) for artifact in self.artifacts]
+
+
+class EvalResult(BaseModel):
+    artifacts: list[Artifact] = Field(default_factory=list)
+    state: dict[str, Any] = Field(default_factory=dict)
+    metrics: dict[str, float] = Field(default_factory=dict)
+    logs: list[str] = Field(default_factory=list)
+
+    @classmethod
+    def from_object(
+        cls,
+        obj: BaseModel,
+        *,
+        agent: Any,
+        state: dict | None = None,
+        metrics: dict | None = None,
+        errors: list[str] | None = None,
+    ) -> EvalResult:
+        """Create EvalResult from a single model instance.
+
+        Automatically constructs an Artifact from the model instance,
+        handling type registry lookup and payload serialization.
+
+        Args:
+            obj: Pydantic model instance to publish as artifact
+            agent: Agent producing the artifact (for produced_by field)
+            state: Optional state dict to include in result
+            metrics: Optional metrics dict (e.g., {"confidence": 0.95})
+            errors: Optional list of error messages
+
+        Returns:
+            EvalResult with single artifact
+
+        Example:
+            >>> class TaskProcessor(EngineComponent):
+            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...         task = inputs.first_as(Task)
+            ...         processed = Task(name=f"Done: {task.name}", priority=task.priority)
+            ...         return EvalResult.from_object(processed, agent=agent)
+        """
+        from flock.artifacts import Artifact
+        from flock.registry import type_registry
+
+        type_name = type_registry.name_for(type(obj))
+        artifact = Artifact(
+            type=type_name,
+            payload=obj.model_dump(),
+            produced_by=agent.name,
+        )
+
+        return cls(
+            artifacts=[artifact],
+            state=state or {},
+            metrics=metrics or {},
+            errors=errors or [],
+        )
+
+    @classmethod
+    def from_objects(
+        cls,
+        *objs: BaseModel,
+        agent: Any,
+        state: dict | None = None,
+        metrics: dict | None = None,
+        errors: list[str] | None = None,
+    ) -> EvalResult:
+        """Create EvalResult from multiple model instances.
+
+        Automatically constructs Artifacts from all model instances.
+        Useful when an agent produces multiple outputs in one evaluation.
+
+        Args:
+            *objs: Pydantic model instances to publish as artifacts
+            agent: Agent producing the artifacts
+            state: Optional state dict
+            metrics: Optional metrics dict
+            errors: Optional list of error messages
+
+        Returns:
+            EvalResult with multiple artifacts
+
+        Example:
+            >>> class MovieEngine(EngineComponent):
+            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...         idea = inputs.first_as(Idea)
+            ...         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}
+            ...         )
+        """
+        from flock.artifacts import Artifact
+        from flock.registry import type_registry
+
+        artifacts = []
+        for obj in objs:
+            type_name = type_registry.name_for(type(obj))
+            artifact = Artifact(
+                type=type_name,
+                payload=obj.model_dump(),
+                produced_by=agent.name,
+            )
+            artifacts.append(artifact)
+
+        return cls(
+            artifacts=artifacts,
+            state=state or {},
+            metrics=metrics or {},
+            errors=errors or [],
+        )
+
+    @classmethod
+    def empty(
+        cls,
+        state: dict | None = None,
+        metrics: dict | None = None,
+        errors: list[str] | None = None,
+    ) -> EvalResult:
+        """Return empty result with no artifacts.
+
+        Useful when:
+        - Conditions aren't met for processing
+        - Agent only updates state without producing output
+        - Processing failed (use errors parameter)
+
+        Args:
+            state: Optional state dict
+            metrics: Optional metrics dict
+            errors: Optional list of error messages
+
+        Returns:
+            EvalResult with empty artifacts list
+
+        Example:
+            >>> class ConditionalProcessor(EngineComponent):
+            ...     async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:
+            ...         task = inputs.first_as(Task)
+            ...         if task.priority < 3:
+            ...             return EvalResult.empty()  # Skip low priority
+            ...         # Process high priority tasks...
+
+            >>> # With error reporting
+            >>> return EvalResult.empty(errors=["Validation failed: missing field"])
+        """
+        return cls(
+            artifacts=[],
+            state=state or {},
+            metrics=metrics or {},
+            errors=errors or [],
+        )
+
+    @classmethod
+    def with_state(
+        cls,
+        state: dict,
+        *,
+        metrics: dict | None = None,
+        errors: list[str] | None = None,
+    ) -> EvalResult:
+        """Return result with only state updates (no artifacts).
+
+        Useful for agents that only update context without producing outputs,
+        such as validation or enrichment agents.
+
+        Args:
+            state: State dict to pass to downstream agents
+            metrics: Optional metrics dict
+            errors: Optional list of error messages
+
+        Returns:
+            EvalResult with state but no artifacts
+
+        Example:
+            >>> class ValidationAgent(EngineComponent):
+            ...     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 cls(
+            artifacts=[],
+            state=state,
+            metrics=metrics or {},
+            errors=errors or [],
+        )
+
+
+class Context(BaseModel):
+    board: Any
+    orchestrator: Any
+    correlation_id: UUID | None = None  # NEW!
+    task_id: str
+    state: dict[str, Any] = Field(default_factory=dict)
+
+    def get_variable(self, key: str, default: Any = None) -> Any:
+        return self.state.get(key, default)
+
+
+__all__ = [
+    "Context",
+    "EvalInputs",
+    "EvalResult",
+]

flock/service.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+
+"""HTTP control plane for the blackboard orchestrator."""
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import PlainTextResponse
+
+from flock.registry import type_registry
+from flock.store import ArtifactEnvelope, ConsumptionRecord, FilterConfig
+
+
+if TYPE_CHECKING:
+    from flock.orchestrator 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._register_routes()
+
+    def _register_routes(self) -> None:
+        app = self.app
+        orchestrator = self.orchestrator
+
+        def _serialize_artifact(
+            artifact,
+            consumptions: list[ConsumptionRecord] | None = None,
+        ) -> dict[str, Any]:
+            data = {
+                "id": str(artifact.id),
+                "type": artifact.type,
+                "payload": artifact.payload,
+                "produced_by": artifact.produced_by,
+                "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,
+                "partition_key": artifact.partition_key,
+                "tags": sorted(artifact.tags),
+                "version": artifact.version,
+            }
+            if consumptions is not None:
+                data["consumptions"] = [
+                    {
+                        "artifact_id": str(record.artifact_id),
+                        "consumer": record.consumer,
+                        "run_id": record.run_id,
+                        "correlation_id": record.correlation_id,
+                        "consumed_at": record.consumed_at.isoformat(),
+                    }
+                    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:
+            if value is None:
+                return None
+            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
+
+        def _make_filter_config(
+            type_names: list[str] | None,
+            produced_by: list[str] | None,
+            correlation_id: str | None,
+            tags: list[str] | None,
+            visibility: list[str] | None,
+            start: str | None,
+            end: str | None,
+        ) -> FilterConfig:
+            return FilterConfig(
+                type_names=set(type_names) if type_names else None,
+                produced_by=set(produced_by) if produced_by else None,
+                correlation_id=correlation_id,
+                tags=set(tags) if tags else None,
+                visibility=set(visibility) if visibility else None,
+                start=_parse_datetime(start, "from"),
+                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")
+            try:
+                await orchestrator.publish({"type": type_name, **payload})
+            except Exception as exc:  # pragma: no cover - FastAPI converts
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+            return {"status": "accepted"}
+
+        @app.get("/api/v1/artifacts")
+        async def list_artifacts(
+            type_names: list[str] | None = Query(None, alias="type"),
+            produced_by: list[str] | None = Query(None),
+            correlation_id: str | None = None,
+            tag: list[str] | None = Query(None),
+            start: str | None = Query(None, alias="from"),
+            end: str | None = Query(None, alias="to"),
+            visibility: list[str] | None = Query(None),
+            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]:
+            filters = _make_filter_config(
+                type_names,
+                produced_by,
+                correlation_id,
+                tag,
+                visibility,
+                start,
+                end,
+            )
+            artifacts, total = await orchestrator.store.query_artifacts(
+                filters,
+                limit=limit,
+                offset=offset,
+                embed_meta=embed_meta,
+            )
+            items: list[dict[str, Any]] = []
+            for artifact in artifacts:
+                if isinstance(artifact, ArtifactEnvelope):
+                    items.append(_serialize_artifact(artifact.artifact, artifact.consumptions))
+                else:
+                    items.append(_serialize_artifact(artifact))
+            return {
+                "items": items,
+                "pagination": {"limit": limit, "offset": offset, "total": total},
+            }
+
+        @app.get("/api/v1/artifacts/summary")
+        async def summarize_artifacts(
+            type_names: list[str] | None = Query(None, alias="type"),
+            produced_by: list[str] | None = Query(None),
+            correlation_id: str | None = None,
+            tag: list[str] | None = Query(None),
+            start: str | None = Query(None, alias="from"),
+            end: str | None = Query(None, alias="to"),
+            visibility: list[str] | None = Query(None),
+        ) -> dict[str, Any]:
+            filters = _make_filter_config(
+                type_names,
+                produced_by,
+                correlation_id,
+                tag,
+                visibility,
+                start,
+                end,
+            )
+            summary = await orchestrator.store.summarize_artifacts(filters)
+            return {"summary": summary}
+
+        @app.get("/api/v1/artifacts/{artifact_id}")
+        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]:
+            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)
+                inputs.append(instance)
+
+            try:
+                outputs = await orchestrator.direct_invoke(agent, inputs)
+            except Exception as exc:
+                raise HTTPException(
+                    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,
+                    }
+                    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,
+                            }
+                            for subscription in agent.subscriptions
+                        ],
+                        "outputs": [output.spec.type_name for output in agent.outputs],
+                    }
+                    for agent in orchestrator.agents
+                ]
+            }
+
+        @app.get("/api/v1/agents/{agent_id}/history-summary")
+        async def agent_history(
+            agent_id: str,
+            type_names: list[str] | None = Query(None, alias="type"),
+            produced_by: list[str] | None = Query(None),
+            correlation_id: str | None = None,
+            tag: list[str] | None = Query(None),
+            start: str | None = Query(None, alias="from"),
+            end: str | None = Query(None, alias="to"),
+            visibility: list[str] | None = Query(None),
+        ) -> dict[str, Any]:
+            filters = _make_filter_config(
+                type_names,
+                produced_by,
+                correlation_id,
+                tag,
+                visibility,
+                start,
+                end,
+            )
+            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("/metrics")
+        async def metrics() -> PlainTextResponse:
+            lines = [f"blackboard_{key} {value}" for key, value in orchestrator.metrics.items()]
+            return PlainTextResponse("\n".join(lines))
+
+    def run(
+        self, host: str = "127.0.0.1", port: int = 8344
+    ) -> None:  # pragma: no cover - manual execution
+        import uvicorn
+
+        uvicorn.run(self.app, host=host, port=port)
+
+    async def run_async(
+        self, host: str = "127.0.0.1", port: int = 8344
+    ) -> None:  # pragma: no cover - manual execution
+        """Run the service asynchronously (for use within async context)."""
+        import uvicorn
+
+        config = uvicorn.Config(self.app, host=host, port=port)
+        server = uvicorn.Server(config)
+        await server.serve()
+
+
+__all__ = ["BlackboardHTTPService"]