qtype 0.0.1__py3-none-any.whl

qtype/interpreter/exceptions.py

@@ -0,0 +1,10 @@
+from typing import Any
+
+
+class InterpreterError(Exception):
+    """Base exception class for ProtoGen interpreter errors."""
+
+    def __init__(self, message: str, details: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details

qtype/interpreter/flow.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from qtype.interpreter.exceptions import InterpreterError
+from qtype.interpreter.step import execute_step
+from qtype.semantic.model import Flow, Variable
+
+logger = logging.getLogger(__name__)
+
+
+def execute_flow(flow: Flow, **kwargs: dict[Any, Any]) -> list[Variable]:
+    """Execute a flow based on the provided arguments.
+
+    Args:
+        flow: The flow to execute.
+        inputs: The input variables for the flow.
+        **kwargs: Additional keyword arguments.
+    """
+    logger.debug(f"Executing step: {flow.id} with kwargs: {kwargs}")
+
+    unset_inputs = [input for input in flow.inputs if not input.is_set()]
+    if unset_inputs:
+        raise InterpreterError(
+            f"The following inputs are required but have no values: {', '.join([input.id for input in unset_inputs])}"
+        )
+
+    for step in flow.steps:
+        execute_step(step, **kwargs)
+
+    unset_outputs = [output for output in flow.outputs if not output.is_set()]
+    if unset_outputs:
+        raise InterpreterError(
+            f"The following outputs are required but have no values: {', '.join([output.id for output in unset_outputs])}"
+        )
+    return flow.outputs

qtype/interpreter/resource_cache.py

@@ -0,0 +1,37 @@
+import functools
+import os
+from typing import Any, Callable
+
+from cachetools import LRUCache
+
+# Global LRU cache with a reasonable default size
+_RESOURCE_CACHE_MAX_SIZE = int(os.environ.get("RESOURCE_CACHE_MAX_SIZE", 128))
+_GLOBAL_RESOURCE_CACHE = LRUCache(maxsize=_RESOURCE_CACHE_MAX_SIZE)
+
+
+def cached_resource(func: Callable[..., Any]) -> Callable[..., Any]:
+    """
+    Decorator to cache function results using a global LRU cache.
+
+    Args:
+        func: The function to cache.
+
+    Returns:
+        The wrapped function with caching.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        cache_key = (
+            func.__module__,
+            func.__qualname__,
+            args,
+            tuple(sorted(kwargs.items())),
+        )
+        if cache_key in _GLOBAL_RESOURCE_CACHE:
+            return _GLOBAL_RESOURCE_CACHE[cache_key]
+        result = func(*args, **kwargs)
+        _GLOBAL_RESOURCE_CACHE[cache_key] = result
+        return result
+
+    return wrapper

qtype/interpreter/step.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from qtype.interpreter.exceptions import InterpreterError
+from qtype.interpreter.steps import (
+    agent,
+    condition,
+    decoder,
+    llm_inference,
+    prompt_template,
+    search,
+    tool,
+)
+from qtype.semantic.model import (
+    Agent,
+    Condition,
+    Decoder,
+    Flow,
+    LLMInference,
+    PromptTemplate,
+    Search,
+    Step,
+    Tool,
+    Variable,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def execute_step(step: Step, **kwargs: dict[str, Any]) -> list[Variable]:
+    """Execute a single step within a flow.
+
+    Args:
+        step: The step to execute.
+        **kwargs: Additional keyword arguments.
+    """
+    logger.debug(f"Executing step: {step.id} with kwargs: {kwargs}")
+
+    unset_inputs = [input for input in step.inputs if not input.is_set()]
+    if unset_inputs:
+        raise InterpreterError(
+            f"The following inputs are required but have no values: {', '.join([input.id for input in unset_inputs])}"
+        )
+
+    if isinstance(step, Agent):
+        return agent.execute(step=step, **kwargs)  # type: ignore[arg-type]
+    elif isinstance(step, Condition):
+        return condition.execute(condition=step, **kwargs)
+    elif isinstance(step, Decoder):
+        return decoder.execute(step=step, **kwargs)  # type: ignore[arg-type]
+    elif isinstance(step, Flow):
+        from .flow import execute_flow
+
+        return execute_flow(step, **kwargs)  # type: ignore[arg-type]
+    elif isinstance(step, LLMInference):
+        return llm_inference.execute(step, **kwargs)  # type: ignore[arg-type]
+    elif isinstance(step, PromptTemplate):
+        return prompt_template.execute(step, **kwargs)  # type: ignore[arg-type]
+    elif isinstance(step, Search):
+        return search.execute(step, **kwargs)  # type: ignore[arg-type]
+    elif isinstance(step, Tool):
+        return tool.execute(step, **kwargs)  # type: ignore[arg-type]
+    else:
+        # Handle other step types if necessary
+        raise InterpreterError(f"Unsupported step type: {type(step).__name__}")

qtype/interpreter/steps/agent.py

@@ -0,0 +1,114 @@
+import asyncio
+import importlib
+import logging
+from typing import Any
+
+from llama_index.core.agent.workflow import ReActAgent
+from llama_index.core.base.llms.types import ChatMessage as LlamaChatMessage
+from llama_index.core.tools import AsyncBaseTool, FunctionTool
+from llama_index.core.workflow import Context
+from llama_index.core.workflow.handler import WorkflowHandler  # type: ignore
+
+from qtype.dsl.domain_types import ChatMessage
+from qtype.interpreter.conversions import (
+    from_chat_message,
+    to_chat_message,
+    to_llm,
+    to_memory,
+)
+from qtype.interpreter.exceptions import InterpreterError
+from qtype.semantic.model import Agent, APITool, PythonFunctionTool, Variable
+
+logger = logging.getLogger(__name__)
+
+
+def to_llama_tool(tool: PythonFunctionTool) -> AsyncBaseTool:
+    """Convert a qtype Tool to a LlamaIndex Tool."""
+    # We want to get the function named by the tool -- get ".tools.<tool_name>"
+    # This assumes the tool name matches a function in the .tools module
+    module = importlib.import_module(tool.module_path)
+    function = getattr(module, tool.function_name, None)
+    if function is None:
+        raise ValueError(
+            f"Tool function '{tool.function_name}' not found in module '{tool.module_path}'."
+        )
+
+    return FunctionTool.from_defaults(
+        fn=function, name=tool.name, description=tool.description
+    )
+
+
+def execute(agent: Agent, **kwargs: dict[str, Any]) -> list[Variable]:
+    """Execute an agent step.
+
+    Args:
+        agent: The agent step to execute.
+        **kwargs: Additional keyword arguments.
+    """
+    logger.debug(f"Executing agent step: {agent.id}")
+    if len(agent.outputs) != 1:
+        raise InterpreterError(
+            "LLMInference step must have exactly one output variable."
+        )
+    output_variable = agent.outputs[0]
+
+    # prepare the input for the agent
+    if len(agent.inputs) != 1:
+        # TODO: Support multiple inputs by shoving it into the chat history?
+        raise InterpreterError(
+            "Agent step must have exactly one input variable."
+        )
+
+    input_variable = agent.inputs[0]
+    if input_variable.type == ChatMessage:
+        input: LlamaChatMessage | str = to_chat_message(input_variable.value)  # type: ignore
+    else:
+        input: LlamaChatMessage | str = input_variable.value  # type: ignore
+
+    # Pepare the tools
+    # TODO: support api tools
+    if any(isinstance(tool, APITool) for tool in agent.tools):
+        raise NotImplementedError(
+            "APITool is not supported in the current implementation. Please use PythonFunctionTool."
+        )
+    tools = [
+        to_llama_tool(tool)  # type: ignore
+        for tool in (agent.tools if agent.tools else [])
+    ]
+
+    # prep memory
+    # Note to_memory is a cached resource so this will get existing memory if available
+    memory = (
+        to_memory(kwargs.get("session_id"), agent.memory)
+        if agent.memory
+        else None
+    )
+
+    # Run the agent
+    async def run_agent() -> WorkflowHandler:
+        logger.debug(
+            f"Starting agent '{agent.id}' execution with input length: {len(str(input))} (ReAct mode)"
+        )
+        re_agent = ReActAgent(
+            name=agent.id,
+            tools=tools,  # type: ignore
+            system_prompt=agent.system_message,
+            llm=to_llm(agent.model, agent.system_message),  # type: ignore
+        )
+        ctx = Context(re_agent)  # type: ignore
+        # TODO: implement checkpoint_callback to call stream_fn?
+        handler = re_agent.run(input, chat_memory=memory, ctx=ctx)
+        result = await handler
+        logger.debug(
+            f"Agent '{agent.id}' execution completed successfully (ReAct mode)"
+        )
+        return result
+
+    result = asyncio.run(run_agent())
+
+    if output_variable.type == ChatMessage:
+        output_variable.value = from_chat_message(result.response)  # type: ignore
+    else:
+        output_variable.value = result.response.content  # type: ignore
+
+    return agent.outputs

qtype/interpreter/steps/condition.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from qtype.semantic.model import Condition, Variable
+
+
+def execute(condition: Condition, **kwargs: dict[str, Any]) -> list[Variable]:
+    """Execute a condition step.
+
+    Args:
+        condition: The condition step to execute.
+
+    Returns:
+        A list of variables that are set based on the condition evaluation.
+    """
+    from qtype.interpreter.step import execute_step
+
+    if not condition.inputs:
+        raise ValueError(
+            "Condition step requires at least one input variable."
+        )
+
+    if len(condition.inputs) != 1:
+        raise ValueError(
+            f"Condition step {condition.id} must have exactly one input, found {len(condition.inputs)}."
+        )
+    input_var = condition.inputs[0]
+    if condition.equals.value == input_var.value:  # type: ignore
+        # If the condition is met, return the outputs
+        return execute_step(condition.then, **kwargs)
+    elif condition.else_:
+        return execute_step(condition.else_, **kwargs)
+    else:
+        # If no else branch is defined, return an empty list
+        return []

qtype/interpreter/steps/decoder.py

@@ -0,0 +1,84 @@
+import json
+import xml.etree.ElementTree as ET
+from typing import Any
+
+from qtype.dsl.model import DecoderFormat
+from qtype.semantic.model import Decoder, Variable
+
+
+def parse_json(input: str) -> dict[str, Any]:
+    """Parse a JSON string into a Python object."""
+    try:
+        cleaned_response = input.strip()
+        if cleaned_response.startswith("```json"):
+            cleaned_response = cleaned_response[7:]
+        if cleaned_response.endswith("```"):
+            cleaned_response = cleaned_response[:-3]
+        cleaned_response = cleaned_response.strip()
+
+        # Parse the JSON
+        parsed = json.loads(cleaned_response)
+        if not isinstance(parsed, dict):
+            raise ValueError(f"Parsed JSON is not an object: {parsed}")
+        return parsed
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON input: {e}")
+
+
+def parse_xml(input: str) -> dict[str, Any]:
+    """Parse an XML string into a Python object."""
+    try:
+        cleaned_response = input.strip()
+        if cleaned_response.startswith("```xml"):
+            cleaned_response = cleaned_response[6:]
+        if cleaned_response.endswith("```"):
+            cleaned_response = cleaned_response[:-3]
+        cleaned_response = cleaned_response.strip()
+
+        cleaned_response = cleaned_response.replace("&", "&")
+        tree = ET.fromstring(cleaned_response)
+        result = {c.tag: c.text for c in tree}
+
+        return result
+    except Exception as e:
+        raise ValueError(f"Invalid XML input: {e}")
+
+
+def execute(decoder: Decoder, **kwargs: dict[str, Any]) -> list[Variable]:
+    """Execute a decoder step with the provided arguments.
+
+    Args:
+        decoder: The decoder step to execute.
+        **kwargs: Additional keyword arguments.
+    """
+
+    if len(decoder.inputs) != 1:
+        raise ValueError(
+            f"Decoder step {decoder.id} must have exactly one input, found {len(decoder.inputs)}."
+        )
+
+    # get the string value to decode
+    input = decoder.inputs[0].value
+    if not isinstance(input, str):
+        raise ValueError(
+            f"Input to decoder step {decoder.id} must be a string, found {type(input).__name__}."
+        )
+
+    if decoder.format == DecoderFormat.json:
+        result_dict = parse_json(input)
+    elif decoder.format == DecoderFormat.xml:
+        result_dict = parse_xml(input)
+    else:
+        raise ValueError(
+            f"Unsupported decoder format: {decoder.format}. Supported formats are: {DecoderFormat.json}, {DecoderFormat.xml}."
+        )
+
+    # Set the output variables with the parsed results
+    for output in decoder.outputs:
+        if output.id in result_dict:
+            output.value = result_dict[output.id]
+        else:
+            raise ValueError(
+                f"Output variable {output.id} not found in decoded result: {result_dict}"
+            )
+    return decoder.outputs

qtype/interpreter/steps/llm_inference.py

@@ -0,0 +1,127 @@
+import logging
+from typing import Any, Callable
+
+from llama_index.core.base.llms.types import ChatResponse, CompletionResponse
+
+from qtype.dsl.domain_types import ChatMessage, Embedding
+from qtype.interpreter.conversions import (
+    from_chat_message,
+    to_chat_message,
+    to_embedding_model,
+    to_llm,
+    to_memory,
+)
+from qtype.interpreter.exceptions import InterpreterError
+from qtype.semantic.model import EmbeddingModel, LLMInference, Variable
+
+logger = logging.getLogger(__name__)
+
+
+def execute(
+    li: LLMInference,
+    stream_fn: Callable | None = None,
+    **kwargs: dict[Any, Any],
+) -> list[Variable]:
+    """Execute a LLM inference step.
+
+    Args:
+        li: The LLM inference step to execute.
+        **kwargs: Additional keyword arguments.
+    """
+    logger.debug(f"Executing LLM inference step: {li.id}")
+
+    # Ensure we only have one output variable set.
+    if len(li.outputs) != 1:
+        raise InterpreterError(
+            "LLMInference step must have exactly one output variable."
+        )
+    output_variable = li.outputs[0]
+
+    # Determine if this is a chat session, completion, or embedding inference
+    if output_variable.type == Embedding:
+        if not isinstance(li.model, EmbeddingModel):
+            raise InterpreterError(
+                f"LLMInference step with Embedding output must use an embedding model, got {type(li.model)}"
+            )
+        if len(li.inputs) != 1:
+            raise InterpreterError(
+                "LLMInference step for completion must have exactly one input variable."
+            )
+
+        input = li.inputs[0].value
+        model = to_embedding_model(li.model)
+        result = model.get_text_embedding(text=input)
+        output_variable.value = Embedding(
+            vector=result,
+            source_text=input if isinstance(input, str) else None,
+            metadata=None,
+        )
+    elif output_variable.type == ChatMessage:
+        model = to_llm(li.model, li.system_message)
+
+        if not all(
+            isinstance(input.value, ChatMessage) for input in li.inputs
+        ):
+            raise InterpreterError(
+                f"LLMInference step with ChatMessage output must have ChatMessage inputs. Got {li.inputs}"
+            )
+        inputs = [
+            to_chat_message(input.value)  # type: ignore
+            for input in li.inputs
+        ]  # type: ignore
+
+        # prepend the inputs with memory chat history if available
+        if li.memory:
+            # Note that the memory is cached in the resource cache, so this should persist for a while...
+            memory = to_memory(kwargs.get("session_id"), li.memory)
+            inputs = memory.get(inputs)
+        else:
+            memory = None
+
+        if stream_fn:
+            generator = model.stream_chat(
+                messages=inputs,
+                **(
+                    li.model.inference_params
+                    if li.model.inference_params
+                    else {}
+                ),
+            )
+            for chatResult in generator:
+                stream_fn(li, from_chat_message(chatResult.message))
+        else:
+            chatResult: ChatResponse = model.chat(
+                messages=inputs,
+                **(
+                    li.model.inference_params
+                    if li.model.inference_params
+                    else {}
+                ),
+            )
+        output_variable.value = from_chat_message(chatResult.message)
+        if memory:
+            memory.put([chatResult.message])
+    else:
+        model = to_llm(li.model, li.system_message)
+
+        if len(li.inputs) != 1:
+            raise InterpreterError(
+                "LLMInference step for completion must have exactly one input variable."
+            )
+
+        input = li.inputs[0].value
+        if not isinstance(input, str):
+            logger.warning(
+                f"Input to LLMInference step {li.id} is not a string, converting: {input}"
+            )
+            input = str(input)
+
+        if stream_fn:
+            generator = model.stream_complete(prompt=input)
+            for completeResult in generator:
+                stream_fn(li, completeResult.delta)
+        else:
+            completeResult: CompletionResponse = model.complete(prompt=input)
+        output_variable.value = completeResult.text
+
+    return li.outputs  # type: ignore[return-value]

qtype/interpreter/steps/prompt_template.py

@@ -0,0 +1,54 @@
+import logging
+import string
+from typing import Any
+
+from qtype.interpreter.exceptions import InterpreterError
+from qtype.semantic.model import PromptTemplate, Variable
+
+logger = logging.getLogger(__name__)
+
+
+def get_format_arguments(format_string: str) -> set[str]:
+    formatter = string.Formatter()
+    arguments = []
+    for literal_text, field_name, format_spec, conversion in formatter.parse(
+        format_string
+    ):
+        if field_name:
+            arguments.append(field_name)
+    return set(arguments)
+
+
+def execute(step: PromptTemplate, **kwargs: dict[str, Any]) -> list[Variable]:
+    """Execute a prompt template step.
+
+    Args:
+        step: The prompt template step to execute.
+        **kwargs: Additional keyword arguments.
+    """
+
+    logger.debug(
+        f"Executing prompt template step: {step.id} with kwargs: {kwargs}"
+    )
+
+    format_args = get_format_arguments(step.template)
+    input_map = {
+        var.id: var.value
+        for var in step.inputs
+        if var.is_set() and var.id in format_args
+    }
+    missing = format_args - input_map.keys()
+    if missing:
+        raise InterpreterError(
+            f"The following fields are in the prompt template but not in the inputs: {missing}"
+        )
+    # Drop inputs that are not in format_args
+    result = step.template.format(**input_map)
+
+    if len(step.outputs) != 1:
+        raise InterpreterError(
+            f"PromptTemplate step {step.id} must have exactly one output variable."
+        )
+    step.outputs[0].value = result
+
+    return step.outputs  # type: ignore[return-value]

qtype/interpreter/steps/search.py

@@ -0,0 +1,24 @@
+import logging
+from typing import Any
+
+from qtype.semantic.model import Search, Variable
+
+logger = logging.getLogger(__name__)
+
+
+def execute(search: Search, **kwargs: dict[str, Any]) -> list[Variable]:
+    """Execute a search step.
+
+    Args:
+        search: The search step to execute.
+
+    Returns:
+        A list of variables that are set based on the search results.
+    """
+    logger.info("Executing Search on: %s", search.index.id)
+    # TODO: implement search execution logic
+    raise NotImplementedError(
+        "Search execution is not yet implemented. This will be handled in a future update."
+    )
+
+    return []  # Return an empty list for now

qtype/interpreter/steps/tool.py

@@ -0,0 +1,53 @@
+import importlib
+import logging
+
+from qtype.interpreter.exceptions import InterpreterError
+from qtype.semantic.model import PythonFunctionTool, Tool, Variable
+
+logger = logging.getLogger(__name__)
+
+
+def execute(tool: Tool, **kwargs: dict) -> list[Variable]:
+    """Execute a tool step.
+
+    Args:
+        tool: The tool step to execute.
+        **kwargs: Additional keyword arguments.
+    """
+    logger.debug(f"Executing tool step: {tool.id} with kwargs: {kwargs}")
+
+    if isinstance(tool, PythonFunctionTool):
+        # import the function dynamically
+        module = importlib.import_module(tool.module_path)
+        function = getattr(module, tool.function_name, None)
+        if function is None:
+            raise InterpreterError(
+                f"Function {tool.function_name} not found in {tool.module_path}"
+            )
+        # Call the function with the provided arguments
+        if any(not inputs.is_set() for inputs in tool.inputs):
+            raise InterpreterError(
+                f"Tool {tool.id} requires all inputs to be set. Missing inputs: {[var.id for var in tool.inputs if not var.is_set()]}"
+            )
+        inputs = {var.id: var.value for var in tool.inputs if var.is_set()}
+        results = function(**inputs)
+    else:
+        # TODO: support api tools
+        raise InterpreterError(f"Unsupported tool type: {type(tool).__name__}")
+
+    if isinstance(results, dict) and len(tool.outputs) > 1:
+        for var in tool.outputs:
+            if var.id in results:
+                var.value = results[var.id]
+            else:
+                raise InterpreterError(
+                    f"Output variable {var.id} not found in function results."
+                )
+    elif len(tool.outputs) == 1:
+        tool.outputs[0].value = results
+    else:
+        raise InterpreterError(
+            f"The returned value {results} could not be assigned to outputs {[var.id for var in tool.outputs]}."
+        )
+
+    return tool.outputs  # type: ignore[return-value]

qtype/interpreter/telemetry.py

@@ -0,0 +1,16 @@
+from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
+from phoenix.otel import register as register_phoenix
+
+from qtype.semantic.model import TelemetrySink
+
+
+def register(telemetry: TelemetrySink, project_id: str | None = None) -> None:
+    """Register a telemetry instance."""
+
+    # 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,
+    )
+    LlamaIndexInstrumentor().instrument(tracer_provider=tracer_provider)