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

flock/api_models.py

@@ -0,0 +1,285 @@
+"""Pydantic response models for Flock REST API.
+
+Provides proper OpenAPI schemas for all public API endpoints.
+This improves API documentation and enables SDK generation.
+
+All models maintain 100% backwards compatibility with existing wire format.
+"""
+
+from datetime import datetime
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+# ============================================================================
+# Agent Models
+# ============================================================================
+
+
+class AgentSubscription(BaseModel):
+    """Subscription configuration for an agent."""
+
+    types: list[str] = Field(description="Artifact types this subscription consumes")
+    mode: str = Field(description="Subscription mode (e.g., 'all', 'any')")
+    delivery: str = Field(description="Delivery mode (e.g., 'immediate', 'batch')")
+
+
+class Agent(BaseModel):
+    """Single agent representation."""
+
+    name: str = Field(description="Unique name of the agent")
+    description: str = Field(default="", description="Human-readable description")
+    subscriptions: list[AgentSubscription] = Field(
+        description="List of subscriptions this agent listens to"
+    )
+    outputs: list[str] = Field(description="Artifact types this agent can produce")
+
+
+class AgentListResponse(BaseModel):
+    """Response for GET /api/v1/agents."""
+
+    agents: list[Agent] = Field(description="List of all registered agents")
+
+
+# ============================================================================
+# Artifact Models
+# ============================================================================
+
+
+class VisibilityInfo(BaseModel):
+    """Artifact visibility configuration."""
+
+    kind: str = Field(description="Visibility kind (e.g., 'Public', 'Private')")
+    # Additional visibility fields added dynamically
+
+
+class ArtifactBase(BaseModel):
+    """Base artifact representation with common fields."""
+
+    id: str = Field(description="Unique artifact identifier (UUID)")
+    type: str = Field(description="Artifact type name")
+    payload: dict[str, Any] = Field(description="Artifact payload data")
+    produced_by: str = Field(description="Name of agent/source that produced this")
+    visibility: dict[str, Any] = Field(description="Visibility configuration")
+    visibility_kind: str = Field(description="Visibility kind (Public/Private/etc)")
+    created_at: str = Field(
+        description="Timestamp when artifact was created (ISO 8601)"
+    )
+    correlation_id: str | None = Field(
+        None, description="Optional correlation ID for workflow tracking"
+    )
+    partition_key: str | None = Field(None, description="Optional partition key")
+    tags: list[str] = Field(default_factory=list, description="List of tags")
+    version: int = Field(description="Artifact version number")
+
+
+class ConsumptionRecord(BaseModel):
+    """Record of an artifact being consumed by an agent."""
+
+    artifact_id: str = Field(description="ID of the artifact that was consumed")
+    consumer: str = Field(description="Name of the agent that consumed it")
+    run_id: str = Field(description="Run ID of the consumption")
+    correlation_id: str = Field(description="Correlation ID of the consumption")
+    consumed_at: str = Field(description="Timestamp of consumption (ISO 8601)")
+
+
+class ArtifactWithConsumptions(ArtifactBase):
+    """Artifact with consumption metadata included."""
+
+    consumptions: list[ConsumptionRecord] = Field(
+        default_factory=list, description="List of consumption records"
+    )
+    consumed_by: list[str] = Field(
+        default_factory=list,
+        description="List of unique agent names that consumed this artifact",
+    )
+
+
+class PaginationInfo(BaseModel):
+    """Pagination metadata."""
+
+    limit: int = Field(description="Number of items per page")
+    offset: int = Field(description="Offset into the result set")
+    total: int = Field(description="Total number of items matching the query")
+
+
+class ArtifactListResponse(BaseModel):
+    """Response for GET /api/v1/artifacts."""
+
+    items: list[ArtifactBase | ArtifactWithConsumptions] = Field(
+        description="List of artifacts (may include consumption data if embed_meta=true)"
+    )
+    pagination: PaginationInfo = Field(description="Pagination information")
+
+
+class ArtifactPublishRequest(BaseModel):
+    """Request body for POST /api/v1/artifacts."""
+
+    type: str = Field(description="Artifact type name")
+    payload: dict[str, Any] = Field(
+        default_factory=dict, description="Artifact payload data"
+    )
+
+
+class ArtifactPublishResponse(BaseModel):
+    """Response for POST /api/v1/artifacts."""
+
+    status: Literal["accepted"] = Field(description="Publication status")
+
+
+class ArtifactSummary(BaseModel):
+    """Summary statistics for artifacts."""
+
+    # Define based on actual summary structure from store
+    # This is a placeholder - update based on actual implementation
+
+
+class ArtifactSummaryResponse(BaseModel):
+    """Response for GET /api/v1/artifacts/summary."""
+
+    summary: dict[str, Any] = Field(description="Summary statistics")
+
+
+# ============================================================================
+# Agent Run Models
+# ============================================================================
+
+
+class AgentRunInput(BaseModel):
+    """Input artifact for agent run."""
+
+    type: str = Field(description="Artifact type name")
+    payload: dict[str, Any] = Field(
+        default_factory=dict, description="Artifact payload data"
+    )
+
+
+class AgentRunRequest(BaseModel):
+    """Request body for POST /api/v1/agents/{name}/run."""
+
+    inputs: list[AgentRunInput] = Field(
+        default_factory=list, description="List of input artifacts"
+    )
+
+
+class ProducedArtifact(BaseModel):
+    """Artifact produced by agent run."""
+
+    id: str = Field(description="Artifact ID (UUID)")
+    type: str = Field(description="Artifact type name")
+    payload: dict[str, Any] = Field(description="Artifact payload data")
+    produced_by: str = Field(description="Name of agent that produced this")
+
+
+class AgentRunResponse(BaseModel):
+    """Response for POST /api/v1/agents/{name}/run."""
+
+    artifacts: list[ProducedArtifact] = Field(
+        description="Artifacts produced by the agent run"
+    )
+
+
+# ============================================================================
+# Schema Discovery Models
+# ============================================================================
+
+
+class ArtifactTypeSchema(BaseModel):
+    """Schema information for an artifact type."""
+
+    model_config = {"populate_by_name": True}  # Allow using 'schema' as field name
+
+    name: str = Field(description="Type name")
+    schema_: dict[str, Any] = Field(
+        alias="schema", description="JSON Schema for this type"
+    )
+
+
+class ArtifactTypesResponse(BaseModel):
+    """Response for GET /api/artifact-types."""
+
+    artifact_types: list[ArtifactTypeSchema] = Field(
+        description="List of all registered artifact types with their schemas"
+    )
+
+
+# ============================================================================
+# Agent History Models
+# ============================================================================
+
+
+class AgentHistorySummary(BaseModel):
+    """Summary of agent execution history."""
+
+    agent_id: str = Field(description="Agent identifier")
+    summary: dict[str, Any] = Field(description="History summary statistics")
+
+
+# ============================================================================
+# Correlation Status Models
+# ============================================================================
+
+
+class CorrelationStatusResponse(BaseModel):
+    """Response for GET /api/v1/correlations/{correlation_id}/status."""
+
+    correlation_id: str = Field(description="The correlation ID")
+    state: Literal["active", "completed", "failed", "not_found"] = Field(
+        description="Workflow state: active (work pending), completed (success), failed (only errors), not_found (no artifacts)"
+    )
+    has_pending_work: bool = Field(
+        description="Whether the orchestrator has pending work for this correlation"
+    )
+    artifact_count: int = Field(
+        description="Total number of artifacts with this correlation_id"
+    )
+    error_count: int = Field(description="Number of WorkflowError artifacts")
+    started_at: str | None = Field(
+        None, description="Timestamp of first artifact (ISO 8601)"
+    )
+    last_activity_at: str | None = Field(
+        None, description="Timestamp of most recent artifact (ISO 8601)"
+    )
+
+
+# ============================================================================
+# Health & Metrics Models
+# ============================================================================
+
+
+class HealthResponse(BaseModel):
+    """Response for GET /health."""
+
+    status: Literal["ok"] = Field(description="Health status")
+
+
+__all__ = [
+    # Agent models
+    "Agent",
+    "AgentSubscription",
+    "AgentListResponse",
+    # Artifact models
+    "ArtifactBase",
+    "ArtifactWithConsumptions",
+    "ArtifactListResponse",
+    "ArtifactPublishRequest",
+    "ArtifactPublishResponse",
+    "ArtifactSummaryResponse",
+    "PaginationInfo",
+    "ConsumptionRecord",
+    # Agent run models
+    "AgentRunRequest",
+    "AgentRunResponse",
+    "ProducedArtifact",
+    # Schema discovery
+    "ArtifactTypesResponse",
+    "ArtifactTypeSchema",
+    # History
+    "AgentHistorySummary",
+    # Correlation status
+    "CorrelationStatusResponse",
+    # Health
+    "HealthResponse",
+]

flock/artifact_collector.py

@@ -43,8 +43,8 @@ class ArtifactCollector:
         # Structure: {(agent_name, subscription_index): {type_name: [artifact1, artifact2, ...]}}
         # Example: {("diagnostician", 0): {"XRay": [artifact1], "LabResult": [artifact2]}}
         # For count-based AND gates: {"TypeA": [artifact1, artifact2, artifact3]} (3 As collected)
-        self._waiting_pools: dict[tuple[str, int], dict[str, list[Artifact]]] = defaultdict(
-            lambda: defaultdict(list)
+        self._waiting_pools: dict[tuple[str, int], dict[str, list[Artifact]]] = (
+            defaultdict(lambda: defaultdict(list))
         )
 
     def add_artifact(
@@ -72,7 +72,10 @@ class ArtifactCollector:
             - After returning complete=True, the pool is automatically cleared
         """
         # Single-type subscription with count=1: No waiting needed (immediate trigger)
-        if len(subscription.type_names) == 1 and subscription.type_counts[artifact.type] == 1:
+        if (
+            len(subscription.type_names) == 1
+            and subscription.type_counts[artifact.type] == 1
+        ):
             return (True, [artifact])
 
         # Multi-type or count-based subscription: Use waiting pool (AND gate logic)

flock/batch_accumulator.py

@@ -194,7 +194,9 @@ class BatchEngine:
 
         return False  # Not ready to flush yet
 
-    def flush_batch(self, agent_name: str, subscription_index: int) -> list[Artifact] | None:
+    def flush_batch(
+        self, agent_name: str, subscription_index: int
+    ) -> list[Artifact] | None:
         """
         Flush a batch and return its artifacts.
 

flock/cli.py

@@ -123,7 +123,9 @@ def sqlite_maintenance(
             try:
                 before_dt = datetime.fromisoformat(delete_before)
             except ValueError as exc:  # pragma: no cover - Typer handles but defensive
-                raise typer.BadParameter(f"Invalid ISO timestamp: {delete_before}") from exc
+                raise typer.BadParameter(
+                    f"Invalid ISO timestamp: {delete_before}"
+                ) from exc
             deleted = await store.delete_before(before_dt)
         if vacuum:
             await store.vacuum()

flock/components.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Self
+from typing import TYPE_CHECKING, Self
 
 from pydantic import BaseModel, Field, create_model
 from pydantic._internal._model_construction import ModelMetaclass
@@ -12,8 +12,6 @@ from flock.logging.auto_trace import AutoTracedMeta
 
 
 if TYPE_CHECKING:  # pragma: no cover - type checking only
-    from uuid import UUID
-
     from flock.agent import Agent, OutputGroup
     from flock.artifacts import Artifact
     from flock.runtime import Context, EvalInputs, EvalResult
@@ -71,7 +69,9 @@ class AgentComponent(BaseModel, metaclass=TracedModelMeta):
     ) -> list[Artifact]:
         return inputs
 
-    async def on_pre_evaluate(self, agent: Agent, ctx: Context, inputs: EvalInputs) -> EvalInputs:
+    async def on_pre_evaluate(
+        self, agent: Agent, ctx: Context, inputs: EvalInputs
+    ) -> EvalInputs:
         return inputs
 
     async def on_post_evaluate(
@@ -89,7 +89,9 @@ class AgentComponent(BaseModel, metaclass=TracedModelMeta):
     ) -> None:  # pragma: no cover - default
         return None
 
-    async def on_terminate(self, agent: Agent, ctx: Context) -> None:  # pragma: no cover - default
+    async def on_terminate(
+        self, agent: Agent, ctx: Context
+    ) -> None:  # pragma: no cover - default
         return None
 
 
@@ -153,67 +155,54 @@ class EngineComponent(AgentComponent):
         """
         raise NotImplementedError
 
-    async def fetch_conversation_context(
+    def get_conversation_context(
         self,
         ctx: Context,
-        correlation_id: UUID | None = None,
         max_artifacts: int | None = None,
-    ) -> list[dict[str, Any]]:
-        """Fetch all artifacts with the same correlation_id for conversation context."""
-        if not self.enable_context or not ctx:
-            return []
+    ) -> list[Artifact]:
+        """Get conversation context from Context (read-only helper).
+
+        Phase 8 Security Fix: This method now simply reads pre-filtered artifacts from
+        Context. The orchestrator evaluates context BEFORE creating Context, so engines
+        can no longer query arbitrary data.
+
+        REMOVED METHODS (Security Fix):
+        - fetch_conversation_context() - REMOVED (engines can't query anymore)
+        - get_latest_artifact_of_type() - REMOVED (engines can't query anymore)
+
+        Migration Guide:
+            Old (vulnerable): context = await self.fetch_conversation_context(ctx, agent, exclude_ids)
+            New (secure): context = ctx.artifacts  # Pre-filtered by orchestrator!
 
-        target_correlation_id = correlation_id or getattr(ctx, "correlation_id", None)
-        if not target_correlation_id:
+        Args:
+            ctx: Execution context with pre-filtered artifacts
+            max_artifacts: Optional limit (applies to already-filtered list)
+
+        Returns:
+            List of Artifact objects (pre-filtered by orchestrator via context provider)
+            with full metadata (type, payload, produced_by, created_at, tags, etc.)
+        """
+        if not self.enable_context or not ctx:
             return []
 
-        try:
-            all_artifacts = await ctx.board.list()
+        context_items = list(ctx.artifacts)  # Copy to avoid mutation
 
-            context_artifacts = [
-                a
-                for a in all_artifacts
-                if (
-                    a.correlation_id == target_correlation_id
-                    and a.type not in self.context_exclude_types
-                )
+        # Apply engine-level filtering (type exclusions)
+        if self.context_exclude_types:
+            context_items = [
+                item
+                for item in context_items
+                if item.type not in self.context_exclude_types
             ]
 
-            context_artifacts.sort(key=lambda a: a.created_at)
-
-            max_limit = max_artifacts if max_artifacts is not None else self.context_max_artifacts
-            if max_limit is not None and max_limit > 0:
-                context_artifacts = context_artifacts[-max_limit:]
-
-            context = []
-            i = 0
-            for artifact in context_artifacts:
-                context.append(
-                    {
-                        "type": artifact.type,
-                        "payload": artifact.payload,
-                        "produced_by": artifact.produced_by,
-                        "event_number": i,
-                        # "created_at": artifact.created_at.isoformat(),
-                    }
-                )
-                i += 1
-
-            return context
-
-        except Exception:
-            return []
+        # Apply max artifacts limit
+        max_limit = (
+            max_artifacts if max_artifacts is not None else self.context_max_artifacts
+        )
+        if max_limit is not None and max_limit > 0:
+            context_items = context_items[-max_limit:]
 
-    async def get_latest_artifact_of_type(
-        self,
-        ctx: Context,
-        artifact_type: str,
-        correlation_id: UUID | None = None,
-    ) -> dict[str, Any] | None:
-        """Get the most recent artifact of a specific type in the conversation."""
-        context = await self.fetch_conversation_context(ctx, correlation_id)
-        matching = [a for a in context if a["type"].endswith(artifact_type)]
-        return matching[-1] if matching else None
+        return context_items
 
     def should_use_context(self, inputs: EvalInputs) -> bool:
         """Determine if context should be included based on the current inputs."""