DeepFabric 4.4.0__py3-none-any.whl

deepfabric/spin/__init__.py

@@ -0,0 +1,6 @@
+"""Spin Framework integration for tool execution."""
+
+from .client import SpinClient, SpinSession
+from .models import SpinExecutionResult
+
+__all__ = ["SpinClient", "SpinSession", "SpinExecutionResult"]

deepfabric/spin/client.py

@@ -0,0 +1,263 @@
+"""Spin Framework HTTP client for tool execution."""
+
+import json
+import logging
+import uuid
+
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from .models import SpinComponentsResponse, SpinExecutionResult, SpinHealthResponse
+
+logger = logging.getLogger(__name__)
+
+
+class SpinClient:
+    """HTTP client for communicating with Spin service."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        timeout: float = 30.0,
+        tool_execute_path: str | None = None,
+    ):
+        """Initialize Spin client.
+
+        Args:
+            endpoint: Base URL of Spin service (e.g., "http://localhost:3000")
+            timeout: Request timeout in seconds
+            tool_execute_path: Custom path for tool execution (e.g., "/mock/execute").
+                              When set, uses MCP-style payload format.
+        """
+        self.endpoint = endpoint.rstrip("/")
+        self.timeout = timeout
+        self.tool_execute_path = tool_execute_path
+        self._client: httpx.AsyncClient | None = None
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        """Ensure async client is initialized."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+        return self._client
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def health_check(self) -> SpinHealthResponse:
+        """Check if Spin service is healthy.
+
+        Returns:
+            SpinHealthResponse with status and available components
+
+        Raises:
+            httpx.HTTPError: If service is unreachable
+        """
+        client = await self._ensure_client()
+        response = await client.get(f"{self.endpoint}/health")
+        response.raise_for_status()
+        return SpinHealthResponse.model_validate(response.json())
+
+    async def get_components(self) -> list[str]:
+        """Get list of available tool components.
+
+        Returns:
+            List of component names
+
+        Raises:
+            httpx.HTTPError: If request fails
+        """
+        client = await self._ensure_client()
+        response = await client.get(f"{self.endpoint}/components")
+        response.raise_for_status()
+        data = SpinComponentsResponse.model_validate(response.json())
+        return data.components
+
+    async def execute_tool(
+        self,
+        session_id: str,
+        tool_name: str,
+        arguments: dict[str, Any],
+        component: str | None = None,
+    ) -> SpinExecutionResult:
+        """Execute a tool via Spin.
+
+        Args:
+            session_id: Session identifier for state isolation
+            tool_name: Name of the tool to execute
+            arguments: Tool arguments
+            component: Spin component that implements this tool (e.g., 'vfs', 'github')
+
+        Returns:
+            SpinExecutionResult with success status and result/error
+        """
+        client = await self._ensure_client()
+
+        # Use custom tool_execute_path if configured (MCP/mock style)
+        if self.tool_execute_path:
+            execute_url = f"{self.endpoint}{self.tool_execute_path}"
+            # MCP-style payload format
+            payload = {
+                "name": tool_name,
+                "arguments": arguments,
+            }
+        else:
+            # Standard component-based routing
+            if component:
+                execute_url = f"{self.endpoint}/{component}/execute"
+            else:
+                execute_url = f"{self.endpoint}/execute"
+            # Standard payload format
+            payload = {
+                "session_id": session_id,
+                "tool": tool_name,
+                "args": arguments,
+            }
+
+        try:
+            response = await client.post(
+                execute_url,
+                json=payload,
+            )
+
+            if response.status_code == HTTPStatus.OK:
+                data = response.json()
+
+                # Handle MCP/mock response format (has "result" key with nested data)
+                if self.tool_execute_path and "result" in data:
+                    # Mock component returns {"result": {...}}
+
+                    return SpinExecutionResult(
+                        success=True,
+                        result=json.dumps(data["result"]),
+                        error_type=None,
+                    )
+
+                # Standard Spin component response format
+                return SpinExecutionResult(
+                    success=data.get("success", False),
+                    result=data.get("result", ""),
+                    error_type=data.get("error_type"),
+                )
+
+            error_data = response.json() if response.content else {}
+            return SpinExecutionResult(
+                success=False,
+                result=error_data.get("error", f"HTTP {response.status_code}"),
+                error_type="HTTPError",
+            )
+
+        except httpx.TimeoutException:
+            return SpinExecutionResult(
+                success=False,
+                result="Tool execution timed out",
+                error_type="Timeout",
+            )
+        except httpx.HTTPError as e:
+            return SpinExecutionResult(
+                success=False,
+                result=f"HTTP error: {e!s}",
+                error_type="HTTPError",
+            )
+
+    async def cleanup_session(self, session_id: str) -> bool:
+        """Clean up all state for a session.
+
+        Args:
+            session_id: Session to clean up
+
+        Returns:
+            True if cleanup succeeded
+        """
+        client = await self._ensure_client()
+
+        try:
+            response = await client.delete(f"{self.endpoint}/session/{session_id}")
+        except httpx.HTTPError as e:
+            logger.warning("Failed to cleanup session %s: %s", session_id, e)
+            return False
+        else:
+            return response.status_code == HTTPStatus.OK
+
+
+class SpinSession:
+    """Manages a Spin session with state persistence across tool calls."""
+
+    def __init__(self, client: SpinClient, session_id: str | None = None):
+        """Initialize a Spin session.
+
+        Args:
+            client: SpinClient instance
+            session_id: Optional session ID (generates UUID if not provided)
+        """
+        self.client = client
+        self.session_id = session_id or str(uuid.uuid4())
+        self._initialized = False
+
+    async def execute_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        component: str | None = None,
+    ) -> SpinExecutionResult:
+        """Execute a tool in this session.
+
+        Args:
+            tool_name: Name of the tool
+            arguments: Tool arguments
+            component: Spin component that implements this tool (e.g., 'vfs', 'github')
+
+        Returns:
+            SpinExecutionResult with execution outcome
+        """
+        return await self.client.execute_tool(
+            session_id=self.session_id,
+            tool_name=tool_name,
+            arguments=arguments,
+            component=component,
+        )
+
+    async def seed_files(self, files: dict[str, str]) -> bool:
+        """Seed initial files into the session's virtual filesystem.
+
+        Args:
+            files: Dictionary of file_path -> content
+
+        Returns:
+            True if all files were seeded successfully
+        """
+        for file_path, content in files.items():
+            result = await self.execute_tool(
+                tool_name="write_file",
+                arguments={"file_path": file_path, "content": content},
+                component="vfs",  # Builtin VFS tool
+            )
+            if not result.success:
+                logger.error("Failed to seed file %s: %s", file_path, result.result)
+                return False
+
+        self._initialized = True
+        logger.debug("Seeded %d files for session %s", len(files), self.session_id)
+        return True
+
+    async def cleanup(self) -> bool:
+        """Clean up this session's state.
+
+        Returns:
+            True if cleanup succeeded
+        """
+        result = await self.client.cleanup_session(self.session_id)
+        self._initialized = False
+        return result
+
+    async def __aenter__(self) -> "SpinSession":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit - cleanup session."""
+        await self.cleanup()

deepfabric/spin/models.py

@@ -0,0 +1,26 @@
+"""Data models for Spin integration."""
+
+from pydantic import BaseModel, Field
+
+
+class SpinExecutionResult(BaseModel):
+    """Result from Spin tool execution."""
+
+    success: bool = Field(description="Whether execution succeeded")
+    result: str = Field(description="Tool output or error message")
+    error_type: str | None = Field(
+        default=None, description="Error type if failed (e.g., 'FileNotFound', 'Timeout')"
+    )
+
+
+class SpinHealthResponse(BaseModel):
+    """Response from Spin health check."""
+
+    status: str = Field(description="Service status")
+    components: list[str] = Field(default_factory=list, description="Available components")
+
+
+class SpinComponentsResponse(BaseModel):
+    """Response from Spin components listing."""
+
+    components: list[str] = Field(default_factory=list, description="Available component names")

deepfabric/stream_simulator.py

@@ -0,0 +1,90 @@
+"""Buffered stream simulation for TUI preview.
+
+This module provides a fire-and-forget streaming simulation that emits chunks
+to the TUI preview without impacting generation performance. The simulation
+runs in background while generation continues immediately.
+"""
+
+import asyncio
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from .constants import STREAM_SIM_CHUNK_DELAY_MS, STREAM_SIM_CHUNK_SIZE
+
+if TYPE_CHECKING:
+    from .progress import ProgressReporter
+
+
+# Track current stream task to prevent interleaving
+class _StreamState:
+    current_task: asyncio.Task | None = None
+
+
+_stream_state = _StreamState()
+
+
+class StreamSimulatorConfig(BaseModel):
+    """Configuration for buffered stream simulation."""
+
+    chunk_size: int = Field(default=STREAM_SIM_CHUNK_SIZE, ge=1, le=100)
+    chunk_delay_ms: float = Field(default=STREAM_SIM_CHUNK_DELAY_MS, ge=0.0, le=100.0)
+    enabled: bool = Field(default=True)
+
+
+def simulate_stream(
+    progress_reporter: "ProgressReporter | None",
+    content: str,
+    source: str,
+    config: StreamSimulatorConfig | None = None,
+    **metadata,
+) -> asyncio.Task | None:
+    """Fire-and-forget stream simulation (non-blocking).
+
+    Starts simulation in background and returns immediately. This is the
+    primary interface for stream simulation throughout the codebase.
+
+    Cancels any in-flight stream task before starting a new one to prevent
+    interleaved chunks from multiple generations appearing scrambled in the TUI.
+
+    Args:
+        progress_reporter: ProgressReporter instance or None
+        content: Text to simulate streaming
+        source: Source identifier for TUI routing
+        config: Optional StreamSimulatorConfig override
+        **metadata: Additional metadata passed to emit_chunk
+
+    Returns:
+        Task if started, None if no-op (no reporter or disabled)
+    """
+    _config = config or StreamSimulatorConfig()
+    if not progress_reporter or not _config.enabled:
+        return None
+
+    # Cancel any in-flight stream to prevent interleaving
+    if _stream_state.current_task is not None and not _stream_state.current_task.done():
+        _stream_state.current_task.cancel()
+
+    async def _simulate_impl() -> None:
+        """Internal implementation of chunk emission."""
+        if not content:
+            return
+
+        delay = _config.chunk_delay_ms / 1000.0
+        chunk_size = _config.chunk_size
+
+        try:
+            for i in range(0, len(content), chunk_size):
+                # Await before emitting to ensure cancellation is processed
+                # and event loop is not blocked when delay is 0
+                if i > 0:
+                    await asyncio.sleep(delay)
+                chunk = content[i : i + chunk_size]
+                progress_reporter.emit_chunk(source, chunk, **metadata)
+        except asyncio.CancelledError:
+            # Gracefully handle cancellation
+            pass
+
+    _stream_state.current_task = asyncio.create_task(_simulate_impl())
+    return _stream_state.current_task

deepfabric/tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tool definitions and utilities for agent-based dataset generation."""
+
+from .defaults import BUILTIN_TOOL_REGISTRY
+
+__all__ = ["BUILTIN_TOOL_REGISTRY"]

deepfabric/tools/defaults.py

@@ -0,0 +1,85 @@
+"""Default tool definitions for common use cases."""
+
+from ..schemas import ToolDefinition, ToolParameter, ToolRegistry
+
+# =============================================================================
+# Builtin Tools - Execute via Spin VFS component
+# These are the only hardcoded tools. Custom components (github, slack, etc.)
+# should be configured via YAML config with tools loaded from endpoints.
+# =============================================================================
+
+# Component mapping: "builtin" in config routes to "/vfs/execute" in Spin
+BUILTIN_COMPONENT = "vfs"
+
+READ_FILE_TOOL = ToolDefinition(
+    name="read_file",
+    description="Read content from a file",
+    parameters=[
+        ToolParameter(
+            name="file_path",
+            type="str",
+            description="Path to the file to read",
+            required=True,
+        ),
+    ],
+    returns="File content as a string",
+    category="filesystem",
+    component=BUILTIN_COMPONENT,
+)
+
+WRITE_FILE_TOOL = ToolDefinition(
+    name="write_file",
+    description="Write content to a file",
+    parameters=[
+        ToolParameter(
+            name="file_path",
+            type="str",
+            description="Path to the file to write",
+            required=True,
+        ),
+        ToolParameter(
+            name="content",
+            type="str",
+            description="Content to write to the file",
+            required=True,
+        ),
+    ],
+    returns="Confirmation message with bytes written",
+    category="filesystem",
+    component=BUILTIN_COMPONENT,
+)
+
+LIST_FILES_TOOL = ToolDefinition(
+    name="list_files",
+    description="List all files in the current session",
+    parameters=[],
+    returns="JSON array of file paths",
+    category="filesystem",
+    component=BUILTIN_COMPONENT,
+)
+
+DELETE_FILE_TOOL = ToolDefinition(
+    name="delete_file",
+    description="Delete a file",
+    parameters=[
+        ToolParameter(
+            name="file_path",
+            type="str",
+            description="Path to the file to delete",
+            required=True,
+        ),
+    ],
+    returns="Confirmation that file was deleted",
+    category="filesystem",
+    component=BUILTIN_COMPONENT,
+)
+
+# Builtin tools registry
+BUILTIN_TOOL_REGISTRY = ToolRegistry(
+    tools=[
+        READ_FILE_TOOL,
+        WRITE_FILE_TOOL,
+        LIST_FILES_TOOL,
+        DELETE_FILE_TOOL,
+    ]
+)

deepfabric/tools/loader.py

@@ -0,0 +1,87 @@
+"""Tool loading and management utilities."""
+
+import json
+import logging
+
+from typing import Any
+
+import httpx
+
+from pydantic import ValidationError
+
+from ..exceptions import ConfigurationError
+from ..schemas import MCPToolDefinition, ToolDefinition, ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+
+def load_tools_from_endpoint(endpoint_url: str, timeout: float = 30.0) -> ToolRegistry:
+    """Load tool definitions from an HTTP endpoint in MCP format.
+
+    Fetches tools from an endpoint like /mock/list-tools that returns
+    MCP-format tool definitions with inputSchema.
+
+    Args:
+        endpoint_url: Full URL to fetch tools from (e.g., 'http://localhost:3000/mock/list-tools')
+        timeout: Request timeout in seconds
+
+    Returns:
+        ToolRegistry with loaded tools converted from MCP format
+
+    Raises:
+        ConfigurationError: If endpoint cannot be reached or returns invalid data
+    """
+    try:
+        response = httpx.get(endpoint_url, timeout=timeout)
+        response.raise_for_status()
+        data = response.json()
+    except httpx.RequestError as e:
+        raise ConfigurationError(f"Failed to connect to tools endpoint {endpoint_url}: {e}") from e
+    except httpx.HTTPStatusError as e:
+        raise ConfigurationError(
+            f"Tools endpoint returned error {e.response.status_code}: {e.response.text}"
+        ) from e
+    except json.JSONDecodeError as e:
+        raise ConfigurationError(f"Invalid JSON from tools endpoint: {e}") from e
+
+    # Extract tools array - handle both {"tools": [...]} and direct array
+    if isinstance(data, dict) and "tools" in data:
+        tools_data = data["tools"]
+    elif isinstance(data, list):
+        tools_data = data
+    else:
+        raise ConfigurationError(
+            f"Invalid response from {endpoint_url}: expected 'tools' key or array"
+        )
+
+    # Convert MCP tools to ToolDefinition
+    try:
+        tools = []
+        for tool_dict in tools_data:
+            mcp_tool = MCPToolDefinition.model_validate(tool_dict)
+            tools.append(ToolDefinition.from_mcp(mcp_tool))
+
+        logger.info("Loaded %d tools from endpoint %s", len(tools), endpoint_url)
+        return ToolRegistry(tools=tools)
+
+    except ValidationError as e:
+        raise ConfigurationError(f"Invalid MCP tool schema from {endpoint_url}: {e}") from e
+
+
+def load_tools_from_dict(tool_dicts: list[dict[str, Any]]) -> ToolRegistry:
+    """Load tool definitions from a list of dictionaries.
+
+    Args:
+        tool_dicts: List of tool definition dictionaries
+
+    Returns:
+        ToolRegistry with loaded tools
+
+    Raises:
+        ConfigurationError: If tool definitions are invalid
+    """
+    try:
+        tools = [ToolDefinition.model_validate(tool_dict) for tool_dict in tool_dicts]
+        return ToolRegistry(tools=tools)
+    except Exception as e:
+        raise ConfigurationError(f"Invalid tool definitions: {str(e)}") from e