qtype 0.0.16__py3-none-any.whl → 0.1.1__py3-none-any.whl

qtype/interpreter/rich_progress.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import logging
+import threading
+from collections import deque
+from typing import Deque, Dict
+
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.progress import (
+    Progress,
+    ProgressColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+    TimeRemainingColumn,
+)
+from rich.text import Text
+
+from qtype.interpreter.types import ProgressCallback
+
+logger = logging.getLogger(__name__)
+
+
+class RateColumn(ProgressColumn):
+    """Show processing speed as '123 msg/s' based on task.speed."""
+
+    def __init__(self, unit: str = "msg") -> None:
+        super().__init__()
+        self.unit = unit
+
+    def render(self, task) -> Text:  # type: ignore[override]
+        speed = task.speed or 0.0
+
+        if speed <= 0:
+            return Text(f"- {self.unit}/s")
+
+        # Simple formatting similar-ish to tqdm
+        if speed < 1:
+            rate_str = f"{speed:.2f}"
+        elif speed < 100:
+            rate_str = f"{speed:4.1f}"
+        else:
+            rate_str = f"{speed:4.0f}"
+
+        return Text(f"{rate_str} {self.unit}/s")
+
+
+class SparklineColumn(ProgressColumn):
+    """Tiny throughput trend graph using block characters."""
+
+    def __init__(self, max_samples: int = 20) -> None:
+        super().__init__()
+        self.max_samples = max_samples
+        # Per-task speed history
+        self._history: Dict[int, Deque[float]] = {}
+
+    def render(self, task) -> Text:  # type: ignore[override]
+        speed = task.speed or 0.0
+
+        history = self._history.get(task.id)
+        if history is None:
+            history = self._history[task.id] = deque(maxlen=self.max_samples)
+
+        history.append(speed)
+
+        if not history or all(v <= 0 for v in history):
+            return Text("")
+
+        min_s = min(history)
+        max_s = max(history)
+        rng = max(max_s - min_s, 1e-9)
+
+        blocks = "▁▂▃▄▅▆▇█"
+        n_blocks = len(blocks)
+
+        chars = []
+        for v in history:
+            idx = int((v - min_s) / rng * (n_blocks - 1))
+            chars.append(blocks[idx])
+
+        return Text("".join(chars))
+
+
+class RichProgressCallback(ProgressCallback):
+    """Progress callback that uses Rich to display progress bars.
+
+    Displays a progress row for each step, updating in place.
+    Colors the step label based on error rate:
+        - Green: error rate <= 1%
+        - Yellow: 1% < error rate <= 5%
+        - Red: error rate > 5%
+
+    Attributes:
+        order: Optional list defining the order of steps progress rows.
+    """
+
+    def __init__(
+        self,
+        order: list[str] | None = None,
+    ) -> None:
+        super().__init__()
+        self.order = order or []
+        self._lock = threading.Lock()
+        self.console = Console()
+
+        # One shared Progress instance for all steps
+        # Columns: description | bar | % | rate | sparkline | ✔ | ✖ | elapsed | remaining
+        self.progress = Progress(
+            TextColumn("[progress.description]{task.description}"),
+            TaskProgressColumn(),
+            RateColumn(unit="msg"),
+            SparklineColumn(max_samples=20),
+            TextColumn("[green]✔[/green] {task.fields[succeeded]} succeeded"),
+            TextColumn("[red]✖[/red] {task.fields[errors]} errors"),
+            TextColumn("[cyan]⟳[/cyan] {task.fields[cache_hits]} hits"),
+            TextColumn(
+                "[magenta]✗[/magenta] {task.fields[cache_misses]} misses"
+            ),
+            TimeElapsedColumn(),
+            TimeRemainingColumn(),
+            console=self.console,
+            expand=True,
+        )
+
+        # Wrap progress in a panel
+        self.panel = Panel(
+            self.progress,
+            title="[bold cyan]Flow Progress[/bold cyan]",
+            border_style="bright_blue",
+            padding=(1, 2),
+        )
+
+        # Live container for the panel
+        self.live = Live(
+            self.panel,
+            console=self.console,
+            refresh_per_second=10,
+        )
+
+        # Map step_id -> Rich task id
+        self.tasks: Dict[str, int] = {}
+        self._started = False
+
+        # Pre-create tasks in the desired order if provided
+        for step_id in self.order:
+            task_id = self.progress.add_task(
+                f"Step {step_id}",
+                total=None,  # we’ll update this once we know it
+                succeeded=0,
+                errors=0,
+            )
+            self.tasks[step_id] = task_id
+
+    def _ensure_started(self) -> None:
+        if not self._started:
+            self.live.start()
+            self._started = True
+
+    def __call__(
+        self,
+        step_id: str,
+        items_processed: int,
+        items_in_error: int,
+        items_succeeded: int,
+        total_items: int | None,
+        cache_hits: int | None = None,
+        cache_misses: int | None = None,
+    ) -> None:
+        with self._lock:
+            self._ensure_started()
+
+            # Create a task lazily if we didn't pre-create it
+            if step_id not in self.tasks:
+                task_id = self.progress.add_task(
+                    f"Step {step_id}",
+                    total=total_items,
+                    succeeded=items_succeeded,
+                    errors=items_in_error,
+                    cache_hits=cache_hits,
+                    cache_misses=cache_misses,
+                )
+                self.tasks[step_id] = task_id
+
+            task_id = self.tasks[step_id]
+            color = self.compute_color(items_processed, items_in_error)
+
+            update_kwargs = {
+                "completed": items_processed,
+                "succeeded": items_succeeded,
+                "errors": items_in_error,
+                "description": f"[{color}]Step {step_id}[/{color}]",
+            }
+
+            update_kwargs["cache_hits"] = (
+                cache_hits if cache_hits is not None else "-"
+            )
+            update_kwargs["cache_misses"] = (
+                cache_misses if cache_misses is not None else "-"
+            )
+            if total_items is not None:
+                update_kwargs["total"] = total_items
+
+            self.progress.update(task_id, **update_kwargs)
+
+    def compute_color(self, items_processed: int, items_in_error: int) -> str:
+        # Avoid divide-by-zero
+        if items_processed == 0:
+            return "green"
+
+        error_rate = items_in_error / items_processed
+
+        if error_rate > 0.05:
+            return "red"
+        elif error_rate > 0.01:
+            return "yellow"
+        else:
+            return "green"
+
+    def close(self) -> None:
+        with self._lock:
+            if self._started:
+                self.live.stop()
+                self._started = False

qtype/interpreter/stream/chat/__init__.py

@@ -0,0 +1,15 @@
+"""
+Stream and chat utilities for QType interpreter.
+
+This package provides conversions between QType's internal streaming
+events and external chat protocols like Vercel AI SDK.
+"""
+
+from __future__ import annotations
+
+from qtype.interpreter.stream.chat.converter import (
+    StreamEventConverter,
+    format_stream_events_as_sse,
+)
+
+__all__ = ["StreamEventConverter", "format_stream_events_as_sse"]

qtype/interpreter/stream/chat/converter.py

@@ -0,0 +1,391 @@
+"""
+Converter for transforming StreamEvents to Vercel AI SDK UIMessageChunks.
+
+This module provides a stateful converter that transforms internal StreamEvent
+types (emitted by step executors) into Vercel AI SDK UIMessageChunk types
+suitable for streaming to the frontend via SSE.
+
+Usage:
+    converter = StreamEventConverter()
+    for event in stream_events:
+        for chunk in converter.convert(event):
+            # Send chunk to frontend
+            yield f"data: {chunk.model_dump_json(by_alias=True)}\n\n"
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from qtype.interpreter.stream.chat.vercel import (
+    ErrorChunk,
+    FinishChunk,
+    FinishStepChunk,
+    MessageMetadataChunk,
+    ReasoningDeltaChunk,
+    ReasoningEndChunk,
+    ReasoningStartChunk,
+    StartChunk,
+    StartStepChunk,
+    TextDeltaChunk,
+    TextEndChunk,
+    TextStartChunk,
+    ToolInputAvailableChunk,
+    ToolInputDeltaChunk,
+    ToolInputStartChunk,
+    ToolOutputAvailableChunk,
+    ToolOutputErrorChunk,
+    UIMessageChunk,
+)
+from qtype.interpreter.types import (
+    ErrorEvent,
+    ReasoningStreamDeltaEvent,
+    ReasoningStreamEndEvent,
+    ReasoningStreamStartEvent,
+    StatusEvent,
+    StepEndEvent,
+    StepStartEvent,
+    StreamEvent,
+    TextStreamDeltaEvent,
+    TextStreamEndEvent,
+    TextStreamStartEvent,
+    ToolExecutionEndEvent,
+    ToolExecutionErrorEvent,
+    ToolExecutionStartEvent,
+)
+
+
+class StreamEventConverter:
+    """
+    Converts internal StreamEvents to Vercel AI SDK UIMessageChunks.
+
+    This converter maintains state to track active text streams and generates
+    appropriate Vercel chunks for each event type. Some events map to multiple
+    chunks (e.g., StatusEvent becomes a wrapped step with text chunks).
+
+    Example:
+        ```python
+        converter = StreamEventConverter()
+
+        # Convert a status message
+        event = StatusEvent(step=step, message="Processing...")
+        for chunk in converter.convert(event):
+            # Yields: StartStepChunk, TextStartChunk, TextDeltaChunk,
+            #         TextEndChunk, FinishStepChunk
+            send_to_client(chunk)
+
+        # Convert text streaming
+        start_event = TextStreamStartEvent(step=step, stream_id="s1")
+        for chunk in converter.convert(start_event):
+            # Yields: TextStartChunk
+            send_to_client(chunk)
+
+        delta_event = TextStreamDeltaEvent(
+            step=step, stream_id="s1", delta="Hello"
+        )
+        for chunk in converter.convert(delta_event):
+            # Yields: TextDeltaChunk
+            send_to_client(chunk)
+        ```
+    """
+
+    def __init__(self) -> None:
+        """Initialize the converter with empty state."""
+        # Map stream_id to Vercel chunk_id for all streams (text, reasoning, etc.)
+        self._active_streams: dict[str, str] = {}
+
+    def convert(self, event: StreamEvent) -> Iterator[UIMessageChunk]:
+        """
+        Convert a StreamEvent to one or more Vercel UIMessageChunks.
+
+        Args:
+            event: The StreamEvent to convert
+
+        Yields:
+            One or more UIMessageChunk instances
+        """
+        # Use pattern matching for clean dispatch
+        match event.type:
+            case "text_stream_start":
+                yield from self._convert_text_stream_start(event)  # type: ignore[arg-type]
+            case "text_stream_delta":
+                yield from self._convert_text_stream_delta(event)  # type: ignore[arg-type]
+            case "text_stream_end":
+                yield from self._convert_text_stream_end(event)  # type: ignore[arg-type]
+            case "reasoning_stream_start":
+                yield from self._convert_reasoning_stream_start(event)  # type: ignore[arg-type]
+            case "reasoning_stream_delta":
+                yield from self._convert_reasoning_stream_delta(event)  # type: ignore[arg-type]
+            case "reasoning_stream_end":
+                yield from self._convert_reasoning_stream_end(event)  # type: ignore[arg-type]
+            case "status":
+                yield from self._convert_status(event)  # type: ignore[arg-type]
+            case "step_start":
+                yield from self._convert_step_start(event)  # type: ignore[arg-type]
+            case "step_end":
+                yield from self._convert_step_end(event)  # type: ignore[arg-type]
+            case "tool_execution_start":
+                yield from self._convert_tool_execution_start(event)  # type: ignore[arg-type]
+            case "tool_execution_end":
+                yield from self._convert_tool_execution_end(event)  # type: ignore[arg-type]
+            case "tool_execution_error":
+                yield from self._convert_tool_execution_error(event)  # type: ignore[arg-type]
+            case "error":
+                yield from self._convert_error(event)  # type: ignore[arg-type]
+            case _:
+                # Unknown event type - log warning but don't fail
+                pass
+
+    def _convert_text_stream_start(
+        self, event: TextStreamStartEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert TextStreamStartEvent to TextStartChunk.
+
+        Registers the stream_id and creates a new Vercel chunk ID.
+        """
+        chunk_id = str(uuid.uuid4())
+        self._active_streams[event.stream_id] = chunk_id
+        yield TextStartChunk(id=chunk_id)
+
+    def _convert_text_stream_delta(
+        self, event: TextStreamDeltaEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert TextStreamDeltaEvent to TextDeltaChunk.
+
+        Uses the chunk ID registered during text_stream_start.
+        """
+        chunk_id = self._active_streams.get(event.stream_id)
+        if chunk_id:
+            yield TextDeltaChunk(id=chunk_id, delta=event.delta)
+
+    def _convert_reasoning_stream_delta(
+        self, event: ReasoningStreamDeltaEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert ReasoningStreamDeltaEvent to ReasoningDeltaChunk.
+
+        Uses the chunk ID registered during text_stream_start.
+        """
+        chunk_id = self._active_streams.get(event.stream_id)
+        if chunk_id:
+            yield ReasoningDeltaChunk(id=chunk_id, delta=event.delta)
+
+    def _convert_text_stream_end(
+        self, event: TextStreamEndEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert TextStreamEndEvent to TextEndChunk.
+
+        Cleans up the stream_id registration.
+        """
+        chunk_id = self._active_streams.pop(event.stream_id, None)
+        if chunk_id:
+            yield TextEndChunk(id=chunk_id)
+
+    def _convert_reasoning_stream_start(
+        self, event: ReasoningStreamStartEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert ReasoningStreamStartEvent to ReasoningStartChunk.
+
+        Registers the stream_id and creates a new Vercel chunk ID for reasoning.
+        """
+        chunk_id = str(uuid.uuid4())
+        self._active_streams[event.stream_id] = chunk_id
+        yield ReasoningStartChunk(id=chunk_id)
+
+    def _convert_reasoning_stream_delta(
+        self, event: ReasoningStreamDeltaEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert ReasoningStreamDeltaEvent to ReasoningDeltaChunk.
+
+        Uses the chunk ID registered during reasoning_stream_start.
+        """
+        chunk_id = self._active_streams.get(event.stream_id)
+        if chunk_id:
+            yield ReasoningDeltaChunk(id=chunk_id, delta=event.delta)
+
+    def _convert_reasoning_stream_end(
+        self, event: ReasoningStreamEndEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert ReasoningStreamEndEvent to ReasoningEndChunk.
+
+        Cleans up the stream_id registration.
+        """
+        chunk_id = self._active_streams.pop(event.stream_id, None)
+        if chunk_id:
+            yield ReasoningEndChunk(id=chunk_id)
+
+    def _convert_status(self, event: StatusEvent) -> Iterator[UIMessageChunk]:
+        """
+        Convert StatusEvent to MessageMetadataChunk.
+
+        Status messages are sent as message metadata with the 'statusMessage'
+        key, allowing the frontend to display them separately from content.
+        """
+        yield MessageMetadataChunk(
+            messageMetadata={"statusMessage": event.message}
+        )
+
+    def _convert_step_start(
+        self, event: StepStartEvent
+    ) -> Iterator[UIMessageChunk]:
+        """Convert StepStartEvent to StartStepChunk."""
+        yield StartStepChunk()
+        yield MessageMetadataChunk(messageMetadata={"step_id": event.step.id})
+
+    def _convert_step_end(
+        self, event: StepEndEvent
+    ) -> Iterator[UIMessageChunk]:
+        """Convert StepEndEvent to FinishStepChunk."""
+        yield FinishStepChunk()
+
+    def _convert_tool_execution_start(
+        self, event: ToolExecutionStartEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert ToolExecutionStartEvent to proper tool input sequence.
+
+        Following Vercel's protocol:
+        1. ToolInputStartChunk - Begin receiving tool input
+        2. ToolInputDeltaChunk - Incremental input text (JSON being parsed)
+        3. ToolInputAvailableChunk - Complete input ready, tool can execute
+        """
+        # 1. Start tool input streaming
+        yield ToolInputStartChunk(
+            toolCallId=event.tool_call_id,
+            toolName=event.tool_name,
+            providerExecuted=True,  # Tools are executed on the server
+        )
+
+        # 2. Stream the input as JSON text delta
+        import json
+
+        input_json = json.dumps(event.tool_input)
+        yield ToolInputDeltaChunk(
+            toolCallId=event.tool_call_id,
+            inputTextDelta=input_json,
+        )
+
+        # 3. Signal input is complete and ready for execution
+        yield ToolInputAvailableChunk(
+            toolCallId=event.tool_call_id,
+            toolName=event.tool_name,
+            input=event.tool_input,
+            providerExecuted=True,  # Tools are executed on the server
+        )
+
+    def _convert_tool_execution_end(
+        self, event: ToolExecutionEndEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert ToolExecutionEndEvent to ToolOutputAvailableChunk.
+
+        Signals successful tool completion with output.
+        """
+        yield ToolOutputAvailableChunk(
+            toolCallId=event.tool_call_id,
+            output=event.tool_output,
+            providerExecuted=True,  # Tools are executed on the server
+        )
+
+    def _convert_tool_execution_error(
+        self, event: ToolExecutionErrorEvent
+    ) -> Iterator[UIMessageChunk]:
+        """
+        Convert ToolExecutionErrorEvent to ToolOutputErrorChunk.
+
+        Signals tool execution failure with error message.
+        """
+        yield ToolOutputErrorChunk(
+            toolCallId=event.tool_call_id,
+            errorText=event.error_message,
+            providerExecuted=True,  # Tools are executed on the server
+        )
+
+    def _convert_error(self, event: ErrorEvent) -> Iterator[UIMessageChunk]:
+        """
+        Convert ErrorEvent to ErrorChunk.
+
+        General error that occurred during execution.
+        """
+        yield ErrorChunk(errorText=event.error_message)
+
+
+async def format_stream_events_as_sse(
+    event_stream: AsyncIterator[StreamEvent | None],
+    message_id: str | None = None,
+    output_metadata: dict[str, Any] | None = None,
+) -> AsyncIterator[str]:
+    """
+    Convert a stream of StreamEvents to SSE-formatted strings.
+
+    This function orchestrates the conversion of StreamEvents to
+    UIMessageChunks and formats them as Server-Sent Events for
+    the Vercel AI SDK protocol.
+
+    Args:
+        event_stream: Async iterator yielding StreamEvents (None signals end)
+        message_id: Optional message ID (generated if not provided)
+        output_metadata: Optional dict to include in FinishChunk metadata
+
+    Yields:
+        SSE formatted strings (data: {json}\\n\\n)
+
+    Example:
+        ```python
+        async def stream_events():
+            yield StatusEvent(step=step, message="Processing...")
+            yield TextStreamStartEvent(step=step, stream_id="s1")
+            yield TextStreamDeltaEvent(step=step, stream_id="s1", delta="Hi")
+            yield TextStreamEndEvent(step=step, stream_id="s1")
+            yield None  # Signal completion
+
+        async for sse_line in format_stream_events_as_sse(
+            stream_events(),
+            output_metadata={"result": "success"}
+        ):
+            # Send to client via StreamingResponse
+            pass
+        ```
+    """
+    # Start message with unique ID
+    if message_id is None:
+        message_id = str(uuid.uuid4())
+
+    start_chunk = StartChunk(messageId=message_id)  # type: ignore[arg-type]
+    yield (
+        f"data: "
+        f"{start_chunk.model_dump_json(by_alias=True, exclude_none=True)}"
+        f"\n\n"
+    )
+
+    # Create converter for stateful event-to-chunk conversion
+    converter = StreamEventConverter()
+
+    # Process events and convert to chunks
+    async for event in event_stream:
+        if event is None:
+            break  # End of stream
+
+        # Convert event to chunks and yield as SSE
+        for chunk in converter.convert(event):
+            yield (
+                f"data: "
+                f"{chunk.model_dump_json(by_alias=True, exclude_none=True)}"
+                f"\n\n"
+            )
+
+    # End message stream with optional metadata
+    finish_chunk = FinishChunk(messageMetadata=output_metadata)  # type: ignore[arg-type]
+    yield (
+        f"data: "
+        f"{finish_chunk.model_dump_json(by_alias=True, exclude_none=True)}"
+        f"\n\n"
+    )

qtype/interpreter/{chat → stream/chat}/file_conversions.py

@@ -1,9 +1,8 @@
 import base64
 
-import magic
 import requests
 
-from qtype.dsl.base_types import PrimitiveTypeEnum
+from qtype.base.types import PrimitiveTypeEnum
 from qtype.dsl.domain_types import ChatContent
 
 
@@ -17,6 +16,7 @@ def file_to_content(url: str) -> ChatContent:
     Returns:
         A ChatContent block with type 'file' and the file URL as content.
     """
+    import magic
 
     # Get the bytes from the url.
     if url.startswith("data:"):