qtype 0.0.12__py3-none-any.whl → 0.1.3__py3-none-any.whl

qtype/interpreter/stream/utils/callback_to_stream.py

@@ -0,0 +1,66 @@
+"""Utilities for converting callbacks to async iterators."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+async def callback_to_async_iterator(
+    task_fn: Callable[[Callable[[T], Awaitable[None]]], Awaitable[None]],
+) -> AsyncIterator[T]:
+    """
+    Convert a callback-based async function to an async iterator.
+
+    This utility bridges callback-style APIs (where you provide a callback
+    that gets called with events) to async iterator style (where you yield
+    events).
+
+    Args:
+        task_fn: Async function that accepts a callback. The callback
+            will be called with each event. The task_fn should complete
+            when done producing events.
+
+    Yields:
+        Events that were passed to the callback
+
+    Example:
+        ```python
+        async def execute_with_callback(callback):
+            await callback("event1")
+            await callback("event2")
+            # Function completes when done
+
+        async for event in callback_to_async_iterator(execute_with_callback):
+            print(event)  # Prints "event1", "event2"
+        ```
+    """
+    queue: asyncio.Queue[T | None] = asyncio.Queue()
+
+    async def callback(item: T) -> None:
+        """Queue items as they arrive."""
+        await queue.put(item)
+
+    async def run_task() -> None:
+        """Execute the task and signal completion."""
+        try:
+            await task_fn(callback)
+        finally:
+            await queue.put(None)  # Signal completion
+
+    # Start task in background
+    task = asyncio.create_task(run_task())
+
+    try:
+        # Yield items from queue until None
+        while True:
+            item = await queue.get()
+            if item is None:
+                break
+            yield item
+    finally:
+        # Ensure task completes
+        await task

qtype/interpreter/stream/utils/create_streaming_response.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+
+from fastapi.responses import StreamingResponse
+
+
+def create_streaming_response(
+    formatter: Generator[str, None, None],
+) -> StreamingResponse:
+    """
+    Wrap a formatter generator into a StreamingResponse with proper headers.
+    """
+    response = StreamingResponse(
+        formatter, media_type="text/plain; charset=utf-8"
+    )
+    response.headers["x-vercel-ai-ui-message-stream"] = "v1"
+    return response

qtype/interpreter/stream/utils/default_chat_extract_text.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from qtype.dsl.domain_types import ChatMessage
+
+
+def default_chat_extract_text(message: Any) -> str:
+    """
+    Default extractor for ChatMessage or generic objects.
+    """
+    if isinstance(message, ChatMessage):
+        return " ".join(
+            [
+                getattr(block, "content", "")
+                for block in message.blocks
+                if getattr(block, "content", "")
+            ]
+        )
+    return str(message)

qtype/interpreter/stream/utils/error_streaming_response.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from fastapi.responses import StreamingResponse
+
+from qtype.interpreter.stream.chat.vercel import ErrorChunk
+
+
+def error_streaming_response(message: str) -> StreamingResponse:
+    """
+    Create a streaming response with a single ErrorChunk.
+    """
+    error_chunk = ErrorChunk(errorText=message)
+    response = StreamingResponse(
+        [
+            f"data: {error_chunk.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+        ],
+        media_type="text/plain; charset=utf-8",
+    )
+    response.headers["x-vercel-ai-ui-message-stream"] = "v1"
+    return response

qtype/interpreter/telemetry.py

@@ -1,16 +1,143 @@
+from __future__ import annotations
+
+import base64
+
 from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
-from phoenix.otel import register as register_phoenix
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+    OTLPSpanExporter,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
+from qtype.interpreter.base.secrets import SecretManagerBase
 from qtype.semantic.model import TelemetrySink
 
 
-def register(telemetry: TelemetrySink, project_id: str | None = None) -> None:
-    """Register a telemetry instance."""
+def _setup_langfuse_otel(
+    sink: TelemetrySink,
+    project_id: str,
+    secret_manager: SecretManagerBase,
+    context: str,
+) -> TracerProvider:
+    """
+    Initializes and registers Langfuse as an OTEL trace exporter.
 
-    # Only llama_index and phoenix are supported for now
-    # TODO: Add support for langfues and llamatrace
-    tracer_provider = register_phoenix(
-        endpoint=telemetry.endpoint,
-        project_name=project_id if project_id else telemetry.id,
+    Langfuse supports OpenTelemetry via its OTLP-compatible endpoint at
+    /api/public/otel. This function configures an OTLP exporter with
+    Basic Auth credentials to send traces to Langfuse.
+
+    Args:
+        sink: TelemetrySink with Langfuse endpoint and credentials
+        project_id: Project identifier for grouping traces in Langfuse
+        secret_manager: For resolving secret references
+        context: Context string for error messages
+
+    Returns:
+        Configured OpenTelemetry TracerProvider
+    """
+    # 1. Resolve secrets for Langfuse from args
+    # Langfuse requires public_key and secret_key in args
+    args = sink.args | {"host": sink.endpoint}
+    args = secret_manager.resolve_secrets_in_dict(
+        args, f"telemetry sink '{sink.id}' args"
     )
+
+    public_key = args.get("public_key")
+    secret_key = args.get("secret_key")
+
+    if not public_key or not secret_key:
+        msg = (
+            f"Langfuse telemetry sink '{sink.id}' requires "
+            "'public_key' and 'secret_key' in args. "
+            f"Got keys: {list(args.keys())}"
+        )
+        raise ValueError(msg)
+
+    # 2. Resolve the endpoint (host)
+    host = args["host"]
+
+    # 3. Build OTLP endpoint for Langfuse
+    # Langfuse OTLP ingestion endpoint
+    endpoint = f"{host.rstrip('/')}/api/public/otel"
+
+    # 4. Create Basic Auth header
+    # Langfuse uses Basic Auth with public_key:secret_key
+    auth_string = f"{public_key}:{secret_key}"
+    b64_auth = base64.b64encode(auth_string.encode()).decode()
+    headers = {"Authorization": f"Basic {b64_auth}"}
+
+    # 5. Setup OTEL Provider and Exporter
+    # Set service.name resource, which maps to project_id in Langfuse
+    resource = Resource(attributes={"service.name": project_id})
+    tracer_provider = TracerProvider(resource=resource)
+
+    # Create the OTLP exporter configured for Langfuse
+    exporter = OTLPSpanExporter(endpoint=endpoint, headers=headers)
+    tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
+
+    # Set as the global tracer provider
+    trace.set_tracer_provider(tracer_provider)
+
+    return tracer_provider
+
+
+def register(
+    telemetry: TelemetrySink,
+    secret_manager: SecretManagerBase,
+    project_id: str | None = None,
+) -> TracerProvider:
+    """
+    Register and configure telemetry for the QType runtime.
+
+    This function sets up telemetry collection by:
+    1. Resolving any SecretReferences in the telemetry endpoint
+    2. Registering with the Phoenix OTEL provider
+    3. Instrumenting LlamaIndex for automatic tracing
+
+    Args:
+        telemetry: TelemetrySink configuration with endpoint and auth
+        project_id: Optional project identifier for telemetry grouping.
+            If not provided, uses telemetry.id
+        secret_manager: Optional secret manager for resolving endpoint URLs
+            that are stored as SecretReferences. If None, uses NoOpSecretManager
+            which will raise an error if secrets are needed.
+
+    Returns:
+        TracerProvider instance for managing telemetry lifecycle.
+
+    Note:
+        Supports Phoenix and Langfuse telemetry providers.
+        Phoenix is the default.
+    """
+
+    # Only llama_index and phoenix are supported for now
+
+    project_id = project_id if project_id else telemetry.id
+
+    if telemetry.provider == "Phoenix":
+        from phoenix.otel import register as register_phoenix
+
+        args = {
+            "endpoint": telemetry.endpoint,
+            "project_name": project_id,
+        } | telemetry.args
+
+        args = secret_manager.resolve_secrets_in_dict(
+            args, f"telemetry sink '{telemetry.id}'"
+        )
+        tracer_provider = register_phoenix(**args)
+    elif telemetry.provider == "Langfuse":
+        tracer_provider = _setup_langfuse_otel(
+            sink=telemetry,
+            project_id=project_id,
+            secret_manager=secret_manager,
+            context=f"telemetry sink '{telemetry.id}'",
+        )
+    else:
+        raise ValueError(
+            f"Unsupported telemetry provider: {telemetry.provider}"
+        )
     LlamaIndexInstrumentor().instrument(tracer_provider=tracer_provider)
+    return tracer_provider

qtype/interpreter/tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tools module for QType interpreter."""
+
+from qtype.interpreter.tools.function_tool_helper import FunctionToolHelper
+
+__all__ = ["FunctionToolHelper"]

qtype/interpreter/tools/function_tool_helper.py

@@ -0,0 +1,265 @@
+"""Helper mixin for creating LlamaIndex FunctionTools from QType definitions."""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from typing import Any
+
+from llama_index.core.bridge.pydantic import BaseModel
+from llama_index.core.bridge.pydantic import Field as PydanticField
+from llama_index.core.tools import FunctionTool, ToolMetadata
+from pydantic import create_model
+
+from qtype.base.types import PrimitiveTypeEnum
+from qtype.dsl.model import ListType
+from qtype.dsl.types import PRIMITIVE_TO_PYTHON_TYPE
+from qtype.semantic.model import APITool, PythonFunctionTool, ToolParameter
+
+logger = logging.getLogger(__name__)
+
+
+class FunctionToolHelper:
+    """Mixin providing utilities for creating LlamaIndex FunctionTools.
+
+    This mixin provides methods to convert QType tool definitions
+    (APITool, PythonFunctionTool) into LlamaIndex FunctionTool instances
+    with proper metadata and Pydantic schemas.
+    """
+
+    @staticmethod
+    def _qtype_type_to_python_type(
+        param: ToolParameter,
+    ) -> type:
+        """Convert QType ToolParameter type to Python type for Pydantic.
+
+        The param.type has already been resolved during semantic model
+        creation, so we just need to convert it to the appropriate Python
+        type:
+        - Primitive types → Python type via PRIMITIVE_TO_PYTHON_TYPE
+        - BaseModel subclasses (domain/custom types) → pass through
+        - List types → list[element_type] (recursively resolved)
+        - Unknown → str
+
+        Args:
+            param: The QType ToolParameter to convert.
+
+        Returns:
+            Python type suitable for Pydantic field annotation.
+        """
+        # Handle primitive types
+        if isinstance(param.type, PrimitiveTypeEnum):
+            return PRIMITIVE_TO_PYTHON_TYPE[param.type]
+
+        # Handle list types - recursively resolve element type
+        if isinstance(param.type, ListType):
+            # Create a mock parameter with the element type to recursively
+            # resolve it
+            element_param = ToolParameter(
+                type=param.type.element_type,
+                optional=False,
+            )
+            element_python_type = (
+                FunctionToolHelper._qtype_type_to_python_type(element_param)
+            )
+            return list[element_python_type]  # type: ignore[valid-type]
+
+        # Handle domain/custom types (BaseModel subclasses)
+        if isinstance(param.type, type) and issubclass(param.type, BaseModel):
+            return param.type
+
+        # For unresolved string references or unknown types, default to str
+        return str
+
+    @staticmethod
+    def _create_fn_schema(
+        tool_name: str,
+        inputs: dict[str, ToolParameter],
+    ) -> type[BaseModel] | None:
+        """Create a Pydantic model from QType tool input parameters.
+
+        Args:
+            tool_name: Name of the tool (used for model name).
+            inputs: Dictionary of input parameter names to ToolParameter.
+
+        Returns:
+            Pydantic BaseModel class representing the tool's input schema.
+            Returns an empty BaseModel if there are no inputs (required by
+            LlamaIndex ReActAgent).
+        """
+        # Build field definitions for Pydantic model
+        # Each field is a tuple of (type_annotation, field_info)
+        field_definitions: dict[str, Any] = {}
+
+        for param_name, param in inputs.items():
+            python_type = FunctionToolHelper._qtype_type_to_python_type(param)
+
+            # Create field with optional annotation
+            if param.optional:
+                field_definitions[param_name] = (
+                    python_type | None,  # type: ignore[valid-type]
+                    PydanticField(default=None),
+                )
+            else:
+                field_definitions[param_name] = (
+                    python_type,
+                    PydanticField(...),
+                )
+
+        # Create dynamic Pydantic model
+        model_name = f"{tool_name.replace('-', '_').replace('.', '_')}_Input"
+        return create_model(model_name, **field_definitions)  # type: ignore[call-overload]
+
+    @staticmethod
+    def _create_tool_metadata(
+        tool: APITool | PythonFunctionTool,
+    ) -> ToolMetadata:
+        """Create ToolMetadata from a QType tool definition.
+
+        Args:
+            tool: The QType tool (API or Python function).
+
+        Returns:
+            ToolMetadata for use with FunctionTool.
+        """
+        # Create Pydantic schema from tool inputs
+        fn_schema = FunctionToolHelper._create_fn_schema(
+            tool.name, tool.inputs
+        )
+
+        return ToolMetadata(
+            name=tool.name,
+            description=tool.description,
+            fn_schema=fn_schema,
+            return_direct=False,
+        )
+
+    def _create_python_function_tool(
+        self, tool: PythonFunctionTool
+    ) -> FunctionTool:
+        """Create a FunctionTool for a Python function.
+
+        For Python functions, we import and wrap the actual function,
+        allowing LlamaIndex to access its signature while routing
+        execution through our wrapper for consistent error handling,
+        logging, and telemetry across all tool invocations.
+
+        Args:
+            tool: The Python function tool definition.
+
+        Returns:
+            LlamaIndex FunctionTool wrapping the Python function.
+
+        Raises:
+            ValueError: If the function cannot be imported.
+        """
+        try:
+            # Import the actual Python function
+            module = importlib.import_module(tool.module_path)
+            function = getattr(module, tool.function_name, None)
+            if function is None:
+                raise ValueError(
+                    (
+                        f"Function '{tool.function_name}' not found in "
+                        f"module '{tool.module_path}'"
+                    )
+                )
+
+            # Create metadata from QType tool definition
+            metadata = FunctionToolHelper._create_tool_metadata(tool)
+
+            # Create wrapper that validates inputs using Pydantic schema
+            # before calling the function through execution
+            # This maintains consistent error handling and hooks
+            async def wrapped_fn(**kwargs: Any) -> Any:
+                # Keep original kwargs for streaming events (JSON-compatible)
+                original_kwargs = kwargs.copy()
+
+                # Validate and parse inputs using the Pydantic schema
+                if metadata.fn_schema is not None:
+                    validated_inputs = metadata.fn_schema(**kwargs)
+                    # Convert Pydantic model to dict with Python native types
+                    # (datetime objects, etc.)
+                    kwargs = validated_inputs.model_dump(mode="python")
+
+                # Pass both the validated kwargs and original for streaming
+                return await self.execute_python_tool(  # type: ignore[attr-defined]
+                    tool, kwargs, original_inputs=original_kwargs
+                )
+
+            return FunctionTool(
+                fn=None,
+                async_fn=wrapped_fn,
+                metadata=metadata,
+            )
+
+        except (ImportError, AttributeError) as e:
+            raise ValueError(
+                (
+                    f"Failed to import Python function "
+                    f"'{tool.function_name}' "
+                    f"from '{tool.module_path}': {e}"
+                )
+            ) from e
+
+    def _create_api_tool(self, tool: APITool) -> FunctionTool:
+        """Create a FunctionTool for an API endpoint.
+
+        Wraps the API tool execution in a function that can be called
+        by LlamaIndex agents, handling authentication, request formatting,
+        and error handling consistently.
+
+        Args:
+            tool: The API tool definition.
+
+        Returns:
+            LlamaIndex FunctionTool wrapping the API tool execution.
+        """
+        # Create metadata from QType tool definition
+        metadata = FunctionToolHelper._create_tool_metadata(tool)
+
+        async def api_wrapper(**kwargs: Any) -> Any:
+            """Wrapper function that executes the API tool."""
+            # Keep original kwargs for streaming events (JSON-compatible)
+            original_kwargs = kwargs.copy()
+
+            # Validate and parse inputs using the Pydantic schema
+            if metadata.fn_schema is not None:
+                validated_inputs = metadata.fn_schema(**kwargs)
+                # Convert Pydantic model to dict for execution
+                kwargs = validated_inputs.model_dump(mode="python")
+
+            # Pass both the validated kwargs and original for streaming
+            return await self.execute_api_tool(  # type: ignore[attr-defined]
+                tool, kwargs, original_inputs=original_kwargs
+            )
+
+        return FunctionTool(
+            fn=None,
+            async_fn=api_wrapper,
+            metadata=metadata,
+        )
+
+    def _create_function_tool(
+        self, tool: APITool | PythonFunctionTool
+    ) -> FunctionTool:
+        """Create a LlamaIndex FunctionTool from a QType tool definition.
+
+        Dispatches to specialized methods based on tool type for optimal
+        handling while maintaining consistent metadata generation.
+
+        Args:
+            tool: The QType tool (API or Python function).
+
+        Returns:
+            LlamaIndex FunctionTool wrapping the tool execution.
+
+        Raises:
+            ValueError: If the tool type is unsupported.
+        """
+        if isinstance(tool, PythonFunctionTool):
+            return self._create_python_function_tool(tool)
+        elif isinstance(tool, APITool):
+            return self._create_api_tool(tool)
+        else:
+            raise ValueError(f"Unsupported tool type: {type(tool)}")