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

flock/api/themes.py

@@ -0,0 +1,71 @@
+"""
+Theme API Endpoints
+
+Serves 300+ terminal color themes from TOML files.
+Themes are loaded from src/flock/themes/
+"""
+
+from pathlib import Path
+from typing import Any
+
+import toml
+from fastapi import APIRouter, HTTPException
+
+
+router = APIRouter()
+
+# Path to themes directory
+THEMES_DIR = Path(__file__).parent.parent / "themes"
+
+
+@router.get("/themes")
+async def list_themes() -> dict[str, list[str]]:
+    """
+    List all available theme names.
+
+    Returns:
+        Dictionary with 'themes' key containing sorted list of theme names
+    """
+    try:
+        if not THEMES_DIR.exists():
+            return {"themes": []}
+
+        theme_files = list(THEMES_DIR.glob("*.toml"))
+        theme_names = sorted([f.stem for f in theme_files])
+
+        return {"themes": theme_names}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to list themes: {e!s}")
+
+
+@router.get("/themes/{theme_name}")
+async def get_theme(theme_name: str) -> dict[str, Any]:
+    """
+    Get theme data by name.
+
+    Args:
+        theme_name: Name of the theme (without .toml extension)
+
+    Returns:
+        Dictionary with 'name' and 'data' containing theme colors
+
+    Raises:
+        HTTPException: If theme not found or failed to load
+    """
+    try:
+        # Sanitize theme name to prevent path traversal
+        theme_name = theme_name.replace("/", "").replace("\\", "").replace("..", "")
+
+        theme_path = THEMES_DIR / f"{theme_name}.toml"
+
+        if not theme_path.exists():
+            raise HTTPException(status_code=404, detail=f"Theme '{theme_name}' not found")
+
+        # Load TOML theme
+        theme_data = toml.load(theme_path)
+
+        return {"name": theme_name, "data": theme_data}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to load theme '{theme_name}': {e!s}")

flock/artifacts.py

@@ -0,0 +1,86 @@
+"""Artifact modelling utilities."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+from flock.registry import type_registry
+from flock.visibility import Visibility, ensure_visibility
+
+
+class Artifact(BaseModel):
+    """Typed artifact stored on the blackboard."""
+
+    id: UUID = Field(default_factory=uuid4)
+    type: str
+    payload: dict[str, Any]
+    produced_by: str
+    correlation_id: UUID | None = None
+    partition_key: str | None = None
+    tags: set[str] = Field(default_factory=set)
+    visibility: Visibility = Field(default_factory=lambda: ensure_visibility(None))
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    version: int = 1
+
+    def model_dump_payload(self) -> dict[str, Any]:  # pragma: no cover - convenience
+        return dict(self.payload)
+
+
+class ArtifactSpec(BaseModel):
+    """Wiring description used for validation on publish."""
+
+    type_name: str
+    model: type[BaseModel]
+
+    @classmethod
+    def from_model(cls, model: type[BaseModel]) -> ArtifactSpec:
+        type_name = type_registry.register(model)
+        return cls(type_name=type_name, model=model)
+
+    def build(
+        self,
+        *,
+        produced_by: str,
+        data: dict[str, Any],
+        visibility: Visibility | None = None,
+        correlation_id: UUID | None = None,
+        partition_key: str | None = None,
+        tags: set[str] | None = None,
+        version: int = 1,
+        artifact_id: UUID | None = None,  # Phase 6: Optional pre-generated ID
+    ) -> Artifact:
+        payload_model = self.model(**data)
+        artifact_kwargs = {
+            "type": self.type_name,
+            "payload": payload_model.model_dump(),
+            "produced_by": produced_by,
+            "visibility": ensure_visibility(visibility),
+            "correlation_id": correlation_id,
+            "partition_key": partition_key,
+            "tags": tags or set(),
+            "version": version,
+        }
+
+        # Phase 6: Use pre-generated ID if provided (for streaming message preview)
+        if artifact_id is not None:
+            artifact_kwargs["id"] = artifact_id
+
+        return Artifact(**artifact_kwargs)
+
+
+class ArtifactEnvelope(BaseModel):
+    """Envelope passed to components/engines during evaluation."""
+
+    artifact: Artifact
+    state: dict[str, Any] = Field(default_factory=dict)
+
+
+__all__ = [
+    "Artifact",
+    "ArtifactEnvelope",
+    "ArtifactSpec",
+]

flock/cli.py

@@ -0,0 +1,147 @@
+"""Typer-based CLI for blackboard agents."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+
+import typer
+from rich.console import Console
+from rich.table import Table
+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
+
+
+app = typer.Typer(help="Blackboard Agents CLI")
+console = Console()
+
+
+@app.command()
+def demo(
+    topic: str = typer.Option("AI agents collaborating", help="Idea topic"),
+    genre: str = typer.Option("comedy", help="Idea genre"),
+) -> None:
+    """Run the demo pipeline locally and stream results to the console."""
+
+    from flock.examples import Idea, create_demo_orchestrator
+
+    orchestrator, agents = create_demo_orchestrator()
+    idea = Idea(topic=topic, genre=genre)
+
+    async def _run_demo() -> None:
+        await orchestrator.arun(agents["movie"], idea)
+        await orchestrator.run_until_idle()
+        table = Table(title="Published Artifacts")
+        table.add_column("Type")
+        table.add_column("Payload", overflow="fold")
+        for artifact in await orchestrator.store.list():
+            table.add_row(artifact.type, repr(artifact.payload))
+        console.print(table)
+
+    asyncio.run(_run_demo())
+
+
+@app.command()
+def list_agents() -> None:
+    """List registered agents for the demo orchestrator."""
+
+    from flock.examples import create_demo_orchestrator
+
+    orchestrator, _agents = create_demo_orchestrator()
+    table = Table(title="Agents")
+    table.add_column("Name")
+    table.add_column("Description")
+    for agent in orchestrator.agents:
+        table.add_row(agent.name, agent.description or "")
+    console.print(table)
+
+
+@app.command()
+def serve(
+    host: str = "127.0.0.1",
+    port: int = 8344,
+    sqlite_db: str | None = typer.Option(None, help="Path to SQLite blackboard store"),
+) -> None:
+    """Run the HTTP control plane bound to the demo orchestrator."""
+
+    from flock.examples import create_demo_orchestrator
+
+    if isinstance(sqlite_db, OptionInfo):  # Allow direct invocation in tests
+        sqlite_db = sqlite_db.default
+
+    store = None
+    if sqlite_db is not None:
+        sqlite_store = SQLiteBlackboardStore(sqlite_db)
+
+        async def _prepare() -> SQLiteBlackboardStore:
+            await sqlite_store.ensure_schema()
+            return sqlite_store
+
+        store = asyncio.run(_prepare())
+
+    orchestrator, _ = create_demo_orchestrator(store=store)
+    service = BlackboardHTTPService(orchestrator)
+    service.run(host=host, port=port)
+
+
+@app.command("init-sqlite-store")
+def init_sqlite_store(
+    db_path: str = typer.Argument(..., help="Path to SQLite blackboard database"),
+) -> None:
+    """Initialise the SQLite store schema."""
+
+    store = SQLiteBlackboardStore(db_path)
+
+    async def _init() -> None:
+        await store.ensure_schema()
+        await store.close()
+
+    asyncio.run(_init())
+    console.print(f"[green]Initialised SQLite blackboard at {db_path}[/green]")
+
+
+@app.command("sqlite-maintenance")
+def sqlite_maintenance(
+    db_path: str = typer.Argument(..., help="Path to SQLite blackboard database"),
+    delete_before: str | None = typer.Option(
+        None, help="ISO timestamp; delete artifacts before this time"
+    ),
+    vacuum: bool = typer.Option(False, help="Run VACUUM after maintenance"),
+) -> None:
+    """Perform maintenance tasks for the SQLite store."""
+
+    store = SQLiteBlackboardStore(db_path)
+
+    async def _maintain() -> tuple[int, bool]:
+        await store.ensure_schema()
+        deleted = 0
+        if delete_before is not None:
+            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
+            deleted = await store.delete_before(before_dt)
+        if vacuum:
+            await store.vacuum()
+        await store.close()
+        return deleted, vacuum
+
+    deleted, vacuum_run = asyncio.run(_maintain())
+    console.print(
+        f"[yellow]Deleted {deleted} artifacts[/yellow]"
+        if delete_before is not None
+        else "[yellow]No deletions requested[/yellow]"
+    )
+    if vacuum_run:
+        console.print("[yellow]VACUUM completed[/yellow]")
+
+
+def main() -> None:
+    app()
+
+
+__all__ = ["app", "main"]

flock/components.py

@@ -0,0 +1,189 @@
+"""Agent component abstractions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field, create_model
+from pydantic._internal._model_construction import ModelMetaclass
+from typing_extensions import Self, TypeVar
+
+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
+    from flock.artifacts import Artifact
+    from flock.runtime import Context, EvalInputs, EvalResult
+
+T = TypeVar("T", bound="AgentComponentConfig")
+
+
+class TracedModelMeta(ModelMetaclass, AutoTracedMeta):
+    """Combined metaclass for Pydantic models with auto-tracing.
+
+    This metaclass combines Pydantic's ModelMetaclass with AutoTracedMeta
+    to enable both Pydantic functionality and automatic method tracing.
+    """
+
+
+class AgentComponentConfig(BaseModel):
+    enabled: bool = True
+    model: str | None = None
+
+    @classmethod
+    def with_fields(cls, **field_definitions) -> type[Self]:
+        """Create a new config class with additional fields.
+
+        This allows dynamic config creation for components with custom configuration needs.
+
+        Example:
+            CustomConfig = AgentComponentConfig.with_fields(
+                temperature=Field(default=0.7, description="LLM temperature"),
+                max_tokens=Field(default=1000, description="Max tokens to generate")
+            )
+        """
+        return create_model(f"Dynamic{cls.__name__}", __base__=cls, **field_definitions)
+
+
+class AgentComponent(BaseModel, metaclass=TracedModelMeta):
+    """Base class for agent components with lifecycle hooks.
+
+    All public methods are automatically traced via OpenTelemetry.
+    """
+
+    name: str | None = None
+    config: AgentComponentConfig = Field(default_factory=AgentComponentConfig)
+
+    async def on_initialize(
+        self, agent: Agent, ctx: Context
+    ) -> None:  # pragma: no cover - default no-op
+        return None
+
+    async def on_pre_consume(
+        self, agent: Agent, ctx: Context, inputs: list[Artifact]
+    ) -> list[Artifact]:
+        return inputs
+
+    async def on_pre_evaluate(self, agent: Agent, ctx: Context, inputs: EvalInputs) -> EvalInputs:
+        return inputs
+
+    async def on_post_evaluate(
+        self, agent: Agent, ctx: Context, inputs: EvalInputs, result: EvalResult
+    ) -> EvalResult:
+        return result
+
+    async def on_post_publish(
+        self, agent: Agent, ctx: Context, artifact: Artifact
+    ) -> None:  # pragma: no cover - default
+        return None
+
+    async def on_error(
+        self, agent: Agent, ctx: Context, error: Exception
+    ) -> None:  # pragma: no cover - default
+        return None
+
+    async def on_terminate(self, agent: Agent, ctx: Context) -> None:  # pragma: no cover - default
+        return None
+
+
+class EngineComponent(AgentComponent):
+    """Base class for engine components with built-in conversation context support."""
+
+    # Configuration for context fetching
+    enable_context: bool = Field(
+        default=True,
+        description="Whether to automatically fetch conversation context based on correlation_id",
+    )
+    context_max_artifacts: int | None = Field(
+        default=None,
+        description="Maximum number of artifacts to include in context (None = unlimited)",
+    )
+    context_exclude_types: set[str] = Field(
+        default_factory=set, description="Artifact types to exclude from context"
+    )
+
+    async def evaluate(self, agent: Agent, ctx: Context, inputs: EvalInputs) -> EvalResult:
+        """Override this method in your engine implementation."""
+        raise NotImplementedError
+
+    async def fetch_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 []
+
+        target_correlation_id = correlation_id or getattr(ctx, "correlation_id", None)
+        if not target_correlation_id:
+            return []
+
+        try:
+            all_artifacts = await ctx.board.list()
+
+            context_artifacts = [
+                a
+                for a in all_artifacts
+                if (
+                    a.correlation_id == target_correlation_id
+                    and a.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 []
+
+    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
+
+    def should_use_context(self, inputs: EvalInputs) -> bool:
+        """Determine if context should be included based on the current inputs."""
+        if not self.enable_context:
+            return False
+
+        if inputs.artifacts:
+            return inputs.artifacts[0].correlation_id is not None
+
+        return False
+
+
+__all__ = [
+    "AgentComponent",
+    "AgentComponentConfig",
+    "EngineComponent",
+]

flock/dashboard/__init__.py

@@ -0,0 +1,30 @@
+"""Real-time dashboard event collection for flock-flow.
+
+Phase 1: Backend event capture system.
+Phase 3: WebSocket infrastructure for real-time communication.
+"""
+
+from flock.dashboard.collector import DashboardEventCollector
+from flock.dashboard.events import (
+    AgentActivatedEvent,
+    AgentCompletedEvent,
+    AgentErrorEvent,
+    MessagePublishedEvent,
+    StreamingOutputEvent,
+)
+from flock.dashboard.graph_builder import GraphAssembler
+from flock.dashboard.service import DashboardHTTPService
+from flock.dashboard.websocket import WebSocketManager
+
+
+__all__ = [
+    "AgentActivatedEvent",
+    "AgentCompletedEvent",
+    "AgentErrorEvent",
+    "DashboardEventCollector",
+    "DashboardHTTPService",
+    "GraphAssembler",
+    "MessagePublishedEvent",
+    "StreamingOutputEvent",
+    "WebSocketManager",
+]