devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/ui_grounding/models.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+GroundingStatus = Literal[
+    "grounded_ready",
+    "grounded_with_generated_artifacts",
+    "pass_with_assumptions",
+    "needs_ui_review",
+    "blocked_missing_ui_grounding",
+]
+SurfaceClassification = Literal[
+    "grounded_existing",
+    "grounded_partial",
+    "grounded_with_generated_artifacts",
+    "missing_reference",
+    "non_ui_or_backend_only",
+]
+ReferenceType = Literal[
+    "implemented_ui",
+    "design_doc",
+    "pencil_artifact",
+    "wireframe_package",
+    "screenshot_spec",
+]
+
+
+class UIGroundingContextArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    idea_title: str
+    idea_summary: str
+    idea_path: str | None = None
+    story_paths: list[str] = Field(default_factory=list)
+    story_summaries: list[str] = Field(default_factory=list)
+    design_paths: list[str] = Field(default_factory=list)
+    repo_root: str
+    upstream_refs: list[str] = Field(default_factory=list)
+
+
+class DerivedUISurface(BaseModel):
+    surface_id: str
+    name: str
+    actor: str = "user"
+    jobs: list[str] = Field(default_factory=list)
+    ui_bearing: bool = True
+    confidence: str = "medium"
+    rationale: str
+    source_refs: list[str] = Field(default_factory=list)
+
+
+class UISurfaceDerivationArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    surfaces: list[DerivedUISurface] = Field(default_factory=list)
+    derivation_notes: list[str] = Field(default_factory=list)
+
+
+class UIReferenceInventoryItem(BaseModel):
+    reference_id: str
+    reference_type: ReferenceType
+    path: str
+    surface_labels: list[str] = Field(default_factory=list)
+    provenance: list[str] = Field(default_factory=list)
+    approval_status: str = "unknown"
+
+
+class UIReferenceInventoryArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    references: list[UIReferenceInventoryItem] = Field(default_factory=list)
+    inventory_notes: list[str] = Field(default_factory=list)
+
+
+class CodeDesignGeneratedReference(BaseModel):
+    surface_id: str
+    source_paths: list[str] = Field(default_factory=list)
+    generated_reference_id: str
+    generated_anchor: str
+    generation_kind: Literal["full_screen", "partial_screen", "supporting_extraction"] = "full_screen"
+    review_needed: bool = False
+    normalized_reference: UIReferenceInventoryItem
+
+
+class CodeDesignInventoryArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    status: Literal[
+        "not_requested",
+        "skipped_preflight_not_ready",
+        "skipped_no_missing_surfaces",
+        "skipped_no_relevant_implemented_ui",
+        "generated",
+    ]
+    target_surface_ids: list[str] = Field(default_factory=list)
+    generated_references: list[CodeDesignGeneratedReference] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+class UIGroundingSurfaceResult(BaseModel):
+    surface_id: str
+    name: str
+    classification: SurfaceClassification
+    matched_reference_ids: list[str] = Field(default_factory=list)
+    supporting_paths: list[str] = Field(default_factory=list)
+    assumptions: list[str] = Field(default_factory=list)
+    unresolved_questions: list[str] = Field(default_factory=list)
+    next_required_action: str
+
+
+class UIGroundingReportArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    status: GroundingStatus
+    surfaces: list[UIGroundingSurfaceResult] = Field(default_factory=list)
+    summary: str
+    assumptions: list[str] = Field(default_factory=list)
+    next_actions: list[str] = Field(default_factory=list)
+
+
+class UIGapReportArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    missing_surfaces: list[str] = Field(default_factory=list)
+    reasons: list[str] = Field(default_factory=list)
+    recommendation: str
+    blocked: bool = True
+
+
+UIScreenSurfaceClass = Literal[
+    "admin_web",
+    "field_tablet",
+    "customer_secure_link",
+    "customer_portal",
+    "internal_support_tool",
+    "general_web",
+    "non_ui_or_backend_only",
+]
+UIScreenPlatform = Literal[
+    "web_desktop",
+    "web_mobile_responsive",
+    "tablet",
+    "multi_platform",
+    "not_applicable",
+]
+UIScreenFidelity = Literal["low", "medium", "high"]
+UIScreenAudience = Literal["internal_exploration", "customer_review", "implementation_handoff"]
+
+
+class UIStructureScreenItem(BaseModel):
+    surface_id: str
+    screen_id: str
+    name: str
+    surface_class: UIScreenSurfaceClass
+    platform: UIScreenPlatform = "web_desktop"
+    actor: str = "user"
+    journey_stage: str
+    required: bool = True
+    source_refs: list[str] = Field(default_factory=list)
+    grounding_refs: list[str] = Field(default_factory=list)
+    target_fidelity: UIScreenFidelity = "medium"
+    target_audience: UIScreenAudience = "customer_review"
+    confidence: str = "medium"
+    confidence_reason: str = "Derived from UI grounding status and source wording."
+    open_questions: list[str] = Field(default_factory=list)
+    assumption_tags: list[str] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+    flow_id: str = "primary"
+    shell_id: str | None = None
+    variant_ids: list[str] = Field(default_factory=list)
+    dependency_screen_ids: list[str] = Field(default_factory=list)
+
+
+class UIStructureContractArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    status: Literal["ready_for_generation", "needs_ui_review", "non_ui_only"]
+    default_minimum_fidelity: UIScreenFidelity = "medium"
+    primary_audience: UIScreenAudience = "customer_review"
+    screens: list[UIStructureScreenItem] = Field(default_factory=list)
+    flow_order: list[str] = Field(default_factory=list)
+    shared_shells: list[dict[str, Any]] = Field(default_factory=list)
+    structural_notes: list[str] = Field(default_factory=list)
+    unresolved_questions: list[str] = Field(default_factory=list)
+
+
+class UIFlowMapArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    flows: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class UIScreenRelationshipsArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    relationships: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class UIGenerationManifestArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    primary_audience: UIScreenAudience = "customer_review"
+    default_minimum_fidelity: UIScreenFidelity = "medium"
+    review_packet_outputs: list[str] = Field(default_factory=list)
+    screen_generation_items: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class GroundedStoryReferencePatchArtifact(BaseModel):
+    project_id: str
+    idea_id: str
+    target_refs: list[str] = Field(default_factory=list)
+    attached_ui_anchors: list[dict[str, Any]] = Field(default_factory=list)
+    supporting_evidence_refs: list[str] = Field(default_factory=list)
+    origin: Literal["existing_ui", "generated_ui", "mixed"] = "existing_ui"
+
+
+class UIGroundingDagSummary(BaseModel):
+    exit_code: int
+    run_id: str
+    pipeline_dir: str
+    message: str
+    outcome: dict[str, Any]

devflow_engine/ui_grounding/pencil_bridge.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ..stores.execution_store import ExecutionStore
+
+DEFAULT_PENCIL_APP_PATH = Path("/Applications/Pencil.app")
+DEFAULT_LAUNCH_TIMEOUT_SECONDS = 15.0
+DEFAULT_MCP_TIMEOUT_SECONDS = 15.0
+DEFAULT_ARTIFACT_PATH = Path(".devflow/ui_grounding/pencil_preflight.json")
+
+
+class PencilMCPProbeResult(BaseModel):
+    server_path: str | None = None
+    initialize_sent: bool = False
+    initialize_acknowledged: bool = False
+    server_name: str | None = None
+    server_version: str | None = None
+    protocol_version: str | None = None
+    error: str | None = None
+
+
+class PencilPreflightArtifact(BaseModel):
+    ok: bool
+    status: str
+    repo_root: str
+    artifact_path: str
+    pencil_app_path: str
+    app_exists: bool
+    process_running_before: bool
+    launched: bool = False
+    process_running_after: bool = False
+    mcp: PencilMCPProbeResult = Field(default_factory=PencilMCPProbeResult)
+    checked_at_epoch: float
+    errors: list[str] = Field(default_factory=list)
+
+
+class PencilPreflightResult(BaseModel):
+    exit_code: int
+    message: str
+    artifact_path: str
+    artifact: PencilPreflightArtifact
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _artifact_path(repo_root: Path, artifact_path: Path | None) -> Path:
+    if artifact_path is not None:
+        return artifact_path if artifact_path.is_absolute() else repo_root / artifact_path
+    return repo_root / DEFAULT_ARTIFACT_PATH
+
+
+def resolve_pencil_app_path(app_path: Path | None = None) -> Path:
+    override = app_path or (Path(os.environ["DEVFLOW_PENCIL_APP_PATH"]) if os.environ.get("DEVFLOW_PENCIL_APP_PATH") else None)
+    return override or DEFAULT_PENCIL_APP_PATH
+
+
+def _pgrep_name_candidates(app_path: Path) -> list[str]:
+    names = [app_path.stem]
+    if app_path.stem.endswith('.app'):
+        names.append(app_path.stem[:-4])
+    return [name for name in names if name]
+
+
+def is_pencil_running(app_path: Path) -> bool:
+    for name in _pgrep_name_candidates(app_path):
+        cp = subprocess.run(["pgrep", "-x", name], capture_output=True, text=True, check=False)
+        if cp.returncode == 0 and cp.stdout.strip():
+            return True
+    return False
+
+
+def launch_pencil(app_path: Path) -> None:
+    subprocess.run(["open", "-a", str(app_path)], capture_output=True, text=True, check=True)
+
+
+def ensure_pencil_running(app_path: Path, *, timeout_seconds: float = DEFAULT_LAUNCH_TIMEOUT_SECONDS) -> tuple[bool, bool]:
+    was_running = is_pencil_running(app_path)
+    launched = False
+    if not was_running:
+        launch_pencil(app_path)
+        launched = True
+        deadline = time.monotonic() + timeout_seconds
+        while time.monotonic() < deadline:
+            if is_pencil_running(app_path):
+                break
+            time.sleep(0.25)
+    return was_running, is_pencil_running(app_path) and launched
+
+
+def locate_mcp_server(app_path: Path) -> Path | None:
+    bundled = app_path / "Contents" / "Resources" / "app.asar.unpacked" / "out" / "mcp-server-darwin-arm64"
+    return bundled if bundled.exists() else None
+
+
+def probe_pencil_mcp(*, app_path: Path, timeout_seconds: float = DEFAULT_MCP_TIMEOUT_SECONDS) -> PencilMCPProbeResult:
+    server_path = locate_mcp_server(app_path)
+    if server_path is None:
+        return PencilMCPProbeResult(error="bundled Pencil MCP server not found")
+    if not os.access(server_path, os.X_OK):
+        return PencilMCPProbeResult(server_path=str(server_path), error="bundled Pencil MCP server is not executable")
+
+    req = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "devflow-engine", "version": "1.0.0"},
+        },
+    }
+    try:
+        cp = subprocess.run(
+            [str(server_path), "-app", str(app_path)],
+            input=json.dumps(req) + "\n",
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=timeout_seconds,
+        )
+    except subprocess.TimeoutExpired:
+        return PencilMCPProbeResult(server_path=str(server_path), initialize_sent=True, error="timed out waiting for MCP initialize response")
+    except Exception as exc:
+        return PencilMCPProbeResult(server_path=str(server_path), initialize_sent=True, error=f"failed to run bundled MCP server: {exc}")
+
+    stdout_lines = [line.strip() for line in cp.stdout.splitlines() if line.strip()]
+    for line in stdout_lines:
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if payload.get("id") != 1:
+            continue
+        if payload.get("jsonrpc") != "2.0":
+            continue
+        if "result" in payload and isinstance(payload["result"], dict):
+            result = payload["result"]
+            server_info = result.get("serverInfo") or {}
+            return PencilMCPProbeResult(
+                server_path=str(server_path),
+                initialize_sent=True,
+                initialize_acknowledged=True,
+                server_name=server_info.get("name"),
+                server_version=server_info.get("version"),
+                protocol_version=result.get("protocolVersion"),
+            )
+        if "error" in payload:
+            return PencilMCPProbeResult(server_path=str(server_path), initialize_sent=True, error=json.dumps(payload["error"], sort_keys=True))
+
+    detail = cp.stderr.strip() or stdout_lines[-1] if stdout_lines else "no initialize response received"
+    return PencilMCPProbeResult(server_path=str(server_path), initialize_sent=True, error=detail)
+
+
+def run_pencil_preflight(*, repo_root: Path, store: ExecutionStore | None = None, app_path: Path | None = None, artifact_path: Path | None = None) -> PencilPreflightResult:
+    resolved_app_path = resolve_pencil_app_path(app_path)
+    resolved_artifact_path = _artifact_path(repo_root, artifact_path)
+    errors: list[str] = []
+    process_running_before = is_pencil_running(resolved_app_path) if shutil.which("pgrep") else False
+
+    artifact = PencilPreflightArtifact(
+        ok=False,
+        status="starting",
+        repo_root=str(repo_root),
+        artifact_path=str(resolved_artifact_path),
+        pencil_app_path=str(resolved_app_path),
+        app_exists=resolved_app_path.exists(),
+        process_running_before=process_running_before,
+        checked_at_epoch=time.time(),
+    )
+
+    if not artifact.app_exists:
+        artifact.status = "not_installed"
+        errors.append(f"Pencil.app not found at {resolved_app_path}")
+        artifact.errors = errors
+        _write_json(resolved_artifact_path, artifact.model_dump())
+        return PencilPreflightResult(exit_code=2, message=json.dumps({"status": artifact.status, "artifact_path": str(resolved_artifact_path)}) + "\n", artifact_path=str(resolved_artifact_path), artifact=artifact)
+
+    try:
+        before_running = is_pencil_running(resolved_app_path)
+        artifact.process_running_before = before_running
+        launched = False
+        if not before_running:
+            launch_pencil(resolved_app_path)
+            launched = True
+            deadline = time.monotonic() + DEFAULT_LAUNCH_TIMEOUT_SECONDS
+            while time.monotonic() < deadline:
+                if is_pencil_running(resolved_app_path):
+                    break
+                time.sleep(0.25)
+        artifact.launched = launched
+        artifact.process_running_after = is_pencil_running(resolved_app_path)
+        if not artifact.process_running_after:
+            artifact.status = "launch_failed"
+            errors.append("Pencil.app is not running after launch attempt")
+        else:
+            artifact.mcp = probe_pencil_mcp(app_path=resolved_app_path)
+            if artifact.mcp.initialize_acknowledged:
+                artifact.ok = True
+                artifact.status = "ready"
+            else:
+                artifact.status = "mcp_unavailable"
+                if artifact.mcp.error:
+                    errors.append(artifact.mcp.error)
+    except subprocess.CalledProcessError as exc:
+        artifact.status = "launch_failed"
+        errors.append(exc.stderr.strip() or exc.stdout.strip() or str(exc))
+    except Exception as exc:
+        artifact.status = "error"
+        errors.append(str(exc))
+
+    artifact.errors = errors
+    _write_json(resolved_artifact_path, artifact.model_dump())
+
+    if store is not None:
+        run_id = store.create_run(
+            dag_id="ui_grounding_pencil_preflight",
+            dag_version="v1",
+            root_correlation_id=f"pencil_preflight:{resolved_app_path}",
+            config={"repo_root": str(repo_root), "pencil_app_path": str(resolved_app_path)},
+        )
+        store.mark_run_started(run_id=run_id)
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=None,
+            kind="ui_grounding.pencil_preflight",
+            uri=str(resolved_artifact_path),
+            metadata=artifact.model_dump(),
+            content_type="application/json",
+            byte_size=resolved_artifact_path.stat().st_size,
+        )
+        store.mark_run_finished(run_id=run_id, status="succeeded" if artifact.ok else "failed")
+
+    exit_code = 0 if artifact.ok else 2
+    message = json.dumps({"status": artifact.status, "artifact_path": str(resolved_artifact_path)}, sort_keys=True) + "\n"
+    return PencilPreflightResult(exit_code=exit_code, message=message, artifact_path=str(resolved_artifact_path), artifact=artifact)

devflow_engine/vendor/datalumina_genai/__init__.py

@@ -0,0 +1,11 @@
+"""Vendored subset of Datalumina GenAI.
+
+This package is intentionally vendored to keep DevFlow Engine self-contained.
+Only the workflow/DAG engine components used by DevFlow are included.
+"""
+
+from .core.workflow import Workflow
+from .core.schema import WorkflowSchema
+from .core.validate import WorkflowValidator
+
+__all__ = ["Workflow", "WorkflowSchema", "WorkflowValidator"]

devflow_engine/vendor/datalumina_genai/core/exceptions.py

@@ -0,0 +1,9 @@
+import logging
+
+
+class LangfuseAuthenticationError(Exception):
+    """Raised when Langfuse authentication fails."""
+
+    def __init__(self, message: str = "Failed to authenticate with Langfuse."):
+        logging.error(message)
+        super().__init__(message)

devflow_engine/vendor/datalumina_genai/core/nodes/agent.py

@@ -0,0 +1,48 @@
+"""Agent node (vendored stub).
+
+Upstream Datalumina GenAI includes deep integrations (OpenAI/Anthropic/Bedrock/etc).
+DevFlow Engine does not require those dependencies for its CLI-first workflow engine.
+
+This stub preserves the public class names used by the workflow runner.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+from .base import Node
+from ..task import TaskContext
+
+
+@dataclass
+class AgentConfig:
+    """Placeholder config for compatibility."""
+
+    instructions: Optional[str] = None
+    output_type: Any = str
+
+
+class AgentNode(Node, ABC):
+    """A minimal async node interface.
+
+    Subclasses are expected to implement `process` and may use `task_context.event`
+    and `task_context.nodes` for state.
+    """
+
+    class DepsType(BaseModel):
+        pass
+
+    class OutputType(BaseModel):
+        pass
+
+    @abstractmethod
+    def get_agent_config(self) -> AgentConfig:  # pragma: no cover
+        raise NotImplementedError
+
+    @abstractmethod
+    async def process(self, task_context: TaskContext) -> TaskContext:  # pragma: no cover
+        raise NotImplementedError

devflow_engine/vendor/datalumina_genai/core/nodes/agent_streaming_node.py

@@ -0,0 +1,26 @@
+"""Streaming agent node (vendored stub).
+
+DevFlow Engine does not ship with LLM providers; streaming is optional.
+This stub allows workflows to type-check and run without extra dependencies.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator, Dict
+
+from .agent import AgentNode
+from ..task import TaskContext
+
+
+class AgentStreamingNode(AgentNode, ABC):
+    """A node that can yield intermediate events."""
+
+    @abstractmethod
+    async def process(self, task_context: TaskContext) -> TaskContext:  # pragma: no cover
+        raise NotImplementedError
+
+    async def stream(self, task_context: TaskContext) -> AsyncIterator[Dict[str, Any]]:
+        # Default behaviour: run `process` and yield one terminal event.
+        result = await self.process(task_context)
+        yield {"type": "result", "data": result.model_dump()}

devflow_engine/vendor/datalumina_genai/core/nodes/base.py

@@ -0,0 +1,89 @@
+from abc import ABC, abstractmethod
+from typing import Type, Optional
+
+from pydantic import BaseModel
+
+from ..task import TaskContext
+
+"""
+Base Node Module
+
+This module defines the foundational Node class that all workflow nodes inherit from.
+It implements the Chain of Responsibility pattern, allowing nodes to process tasks
+sequentially and pass results to the next node in the chain.
+"""
+
+
+class Node(ABC):
+    class OutputType(BaseModel):
+        """
+        OutputType class for representing structured outputs for Nodes.
+        """
+
+        pass
+
+    def __init__(self, task_context: TaskContext = None):
+        """
+        The constructor is used to initialize the class with a provided TaskContext
+        instance or without any context.
+
+        Parameters:
+        task_context (TaskContext, optional): Context associated with the task.
+            Defaults to None.
+        """
+        self.task_context = task_context
+
+    def save_output(self, output: BaseModel):
+        """
+        Saves the output of a task node into the task context, associating it with the
+        node's name for future reference.
+
+        Args:
+            output (BaseModel): The model instance representing the result of the task
+            to be stored in the task_context.
+        """
+        self.task_context.nodes[self.node_name] = output
+
+    def get_output(self, node_class: Type["Node"]) -> Optional[OutputType]:
+        """
+        Retrieves the output associated with a specific node class from the task context.
+
+        Parameters:
+        node_class: Type[Node]
+            The class of the node whose output is to be retrieved.
+
+        Returns:
+        Optional[OutputType]
+            The output associated with the specified node class if it exists, otherwise None.
+        """
+        return self.task_context.nodes.get(node_class.__name__, None)
+
+    @property
+    def node_name(self) -> str:
+        """Gets the name of the node.
+
+        Returns:
+            String name derived from the class name
+        """
+        return self.__class__.__name__
+
+    @abstractmethod
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        """Processes the task context in the responsibility chain.
+
+        This method implements the Chain of Responsibility pattern's handle
+        method. Each node in the workflow processes the task and passes it
+        to the next node through the workflow orchestrator.
+
+        Args:
+            task_context: The shared context object passed through the workflow
+
+        Returns:
+            Updated TaskContext with this node's processing results
+
+        Note:
+            Implementations should:
+            1. Process the task according to their specific responsibility
+            2. Store results using the save_output method
+        """
+        pass

devflow_engine/vendor/datalumina_genai/core/nodes/concurrent.py

@@ -0,0 +1,30 @@
+import asyncio
+from abc import ABC, abstractmethod
+
+from .base import Node
+from ..schema import NodeConfig
+from ..task import TaskContext
+
+
+class ConcurrentNode(Node, ABC):
+    """
+    Base class for nodes that execute other nodes concurrently using asyncio.
+
+    This class provides a method to execute a list of nodes concurrently on a single thread,
+    using asyncio.gather. This ensures that I/O-bound operations can proceed in parallel
+    without blocking the main thread or event loop.
+
+    Subclasses must implement the `process` method to define the specific logic of the concurrent node.
+    """
+
+    async def execute_nodes_concurrently(self, task_context: TaskContext):
+        node_config: NodeConfig = task_context.metadata["nodes"][self.__class__]
+        coroutines = [
+            node(task_context).process(task_context)
+            for node in node_config.concurrent_nodes
+        ]
+        return await asyncio.gather(*coroutines)
+
+    @abstractmethod
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        pass