qtype 0.1.12__py3-none-any.whl → 0.1.14__py3-none-any.whl

qtype/application/__init__.py

@@ -3,10 +3,8 @@
 from __future__ import annotations
 
 from . import commons, converters
-from .facade import QTypeFacade
 
 __all__ = [
-    "QTypeFacade",
     "converters",
     "commons",
 ]

qtype/application/converters/tools_from_api.py

@@ -26,7 +26,7 @@ from qtype.dsl.model import (
     BearerTokenAuthProvider,
     CustomType,
     OAuth2AuthProvider,
-    ToolParameter,
+    Variable,
     VariableType,
 )
 
@@ -202,9 +202,9 @@ def create_tool_parameters_from_body(
     existing_custom_types: dict[str, CustomType],
     schema_name_map: dict[int, str],
     default_param_name: str,
-) -> dict[str, ToolParameter]:
+) -> list[Variable]:
     """
-    Convert an OpenAPI Response or RequestBody to a dictionary of ToolParameters.
+    Convert an OpenAPI Response or RequestBody to a list of Variables.
 
     If the body has only one content type with an Object schema, flatten its properties
     to individual parameters. Otherwise, create a single parameter with the body type.
@@ -216,18 +216,18 @@ def create_tool_parameters_from_body(
         default_param_name: Name to use for non-flattened parameter
 
     Returns:
-        Dictionary of parameter name to ToolParameter objects
+        List of Variable objects
     """
     # Check if we have content to analyze
     if not hasattr(oas, "content") or not oas.content:
-        return {}
+        return []
 
     content = oas.content[0]
     input_type = to_variable_type(
         content, existing_custom_types, schema_name_map
     )
 
-    # Convert CustomType to string ID for ToolParameter
+    # Convert CustomType to string ID for Variable
     input_type_value = (
         input_type.id if isinstance(input_type, CustomType) else input_type
     )
@@ -240,7 +240,7 @@ def create_tool_parameters_from_body(
         custom_type = existing_custom_types[input_type.id]
 
         # Flatten the custom type properties to individual parameters
-        flattened_parameters = {}
+        flattened_parameters = []
         for prop_name, prop_type_str in custom_type.properties.items():
             # Check if the property is optional (has '?' suffix)
             is_optional = prop_type_str.endswith("?")
@@ -248,8 +248,10 @@ def create_tool_parameters_from_body(
                 prop_type_str.rstrip("?") if is_optional else prop_type_str
             )
 
-            flattened_parameters[prop_name] = ToolParameter(
-                type=clean_type, optional=is_optional
+            flattened_parameters.append(
+                Variable.model_construct(
+                    id=prop_name, type=clean_type, optional=is_optional
+                )
             )
 
         # remove the type from existing_custom_types to avoid confusion
@@ -258,11 +260,11 @@ def create_tool_parameters_from_body(
         return flattened_parameters
 
     # If not flattening, create a single parameter (e.g., for simple types or arrays)
-    return {
-        default_param_name: ToolParameter(
-            type=input_type_value, optional=False
+    return [
+        Variable.model_construct(
+            id=default_param_name, type=input_type_value, optional=False
         )
-    }
+    ]
 
 
 def to_api_tool(
@@ -297,7 +299,7 @@ def to_api_tool(
     ).replace("\n", " ")
 
     # Process inputs from request body and parameters
-    inputs = {}
+    inputs = []
     if operation.request_body and operation.request_body.content:
         # Create input parameters from request body using the new function
         input_params = create_tool_parameters_from_body(
@@ -306,27 +308,31 @@ def to_api_tool(
             schema_name_map,
             default_param_name="request",
         )
-        inputs.update(input_params)
+        inputs.extend(input_params)
 
     # Add path and query parameters as inputs
-    parameters = {}
+    parameters = []
     for param in operation.parameters:
         if param.schema:
             param_type = _schema_to_qtype_type(
                 param.schema, existing_custom_types, schema_name_map
             )
-            # Convert to appropriate type for ToolParameter
+            # Convert to appropriate type for Variable
             param_type_value = (
                 param_type.id
                 if isinstance(param_type, CustomType)
                 else param_type
             )
-            parameters[param.name] = ToolParameter(
-                type=param_type_value, optional=not param.required
+            parameters.append(
+                Variable.model_construct(
+                    id=param.name,
+                    type=param_type_value,
+                    optional=not param.required,
+                )
             )
 
     # Process outputs from responses
-    outputs = {}
+    outputs = []
     # Find the success response (200-299 status codes) or default response
     success_response = next(
         (r for r in operation.responses if r.code and 200 <= r.code < 300),
@@ -339,9 +345,9 @@ def to_api_tool(
             success_response,
             existing_custom_types,
             schema_name_map,
-            default_param_name="response",
+            default_param_name=f"{tool_id}_response",
         )
-        outputs.update(output_params)
+        outputs.extend(output_params)
 
     return APITool(
         id=tool_id,

qtype/application/converters/tools_from_module.py

@@ -10,7 +10,7 @@ from qtype.dsl.model import (
     CustomType,
     ListType,
     PythonFunctionTool,
-    ToolParameter,
+    Variable,
     VariableType,
 )
 
@@ -43,14 +43,19 @@ def tools_from_module(
                 f"No public functions found in module '{module_path}'"
             )
 
-        custom_types: dict[str, CustomType] = {}
+        # Registry of actual Pydantic classes for validation
+        custom_type_registry: dict[str, Type[BaseModel]] = {}
+        # CustomType instances for YAML output
+        custom_type_models: dict[str, CustomType] = {}
 
         # Create Tool instances from functions
         tools = [
-            _create_tool_from_function(func_name, func_info, custom_types)
+            _create_tool_from_function(
+                func_name, func_info, custom_type_registry, custom_type_models
+            )
             for func_name, func_info in functions.items()
         ]
-        return (tools, list(custom_types.values()))
+        return (tools, list(custom_type_models.values()))
     except ImportError as e:
         raise ImportError(f"Cannot import module '{module_path}': {e}") from e
 
@@ -116,7 +121,8 @@ def _get_module_functions(
 def _create_tool_from_function(
     func_name: str,
     func_info: dict[str, Any],
-    custom_types: dict[str, CustomType],
+    custom_type_registry: dict[str, Type[BaseModel]],
+    custom_type_models: dict[str, CustomType],
 ) -> PythonFunctionTool:
     """
     Convert function metadata into a Tool instance.
@@ -135,29 +141,38 @@ def _create_tool_from_function(
         else f"Function {func_name}"
     )
 
-    # Create input parameters from function parameters
-    inputs = {
-        p["name"]: ToolParameter(
-            type=_map_python_type_to_variable_type(p["type"], custom_types),
-            optional=p["default"] != inspect.Parameter.empty,
+    # Create input parameters as list of Variables
+    inputs = [
+        Variable.model_validate(
+            {
+                "id": p["name"],
+                "type": _map_python_type_to_variable_type(
+                    p["type"], custom_type_registry, custom_type_models
+                ),
+                "optional": p["default"] != inspect.Parameter.empty,
+            },
+            context={"custom_types": custom_type_registry},
         )
         for p in func_info["parameters"]
-    }
-
-    # # quick hack
-    # for k, v in inputs.items():
-    #     if inspect.isclass(v.type) and issubclass(v.type, BaseModel):
-    #         v.type = str(v.type.__name__)
+    ]
 
     # Create output parameter based on return type
     tool_id = func_info["module"] + "." + func_name
 
     output_type = _map_python_type_to_variable_type(
-        func_info["return_type"], custom_types
+        func_info["return_type"], custom_type_registry, custom_type_models
     )
 
-    outputs = {"result": ToolParameter(type=output_type, optional=False)}
-    # outputs['result'].type =
+    outputs = [
+        Variable.model_validate(
+            {
+                "id": f"{func_name}_result",
+                "type": output_type,
+                "optional": False,
+            },
+            context={"custom_types": custom_type_registry},
+        )
+    ]
 
     return PythonFunctionTool(
         id=tool_id,
@@ -172,7 +187,8 @@ def _create_tool_from_function(
 
 def _pydantic_to_custom_types(
     model_cls: Type[BaseModel],
-    custom_types: dict[str, CustomType],
+    custom_type_registry: dict[str, Type[BaseModel]],
+    custom_type_models: dict[str, CustomType],
 ) -> str:
     """
     Converts a Pydantic BaseModel class into a QType CustomType.
@@ -184,15 +200,20 @@ def _pydantic_to_custom_types(
 
     Args:
         model_cls: The Pydantic model class to convert.
+        custom_type_registry: Registry of actual Pydantic classes for validation
+        custom_type_models: Dictionary of CustomType models for YAML output
 
     Returns:
-        A dictionary mapping field names to their corresponding CustomType definitions.
+        The model name as a string type reference
     """
     properties = {}
     model_name = model_cls.__name__
-    if model_name in custom_types:
+    if model_name in custom_type_registry:
         return model_name  # Already processed
 
+    # Register the actual class for validation
+    custom_type_registry[model_name] = model_cls
+
     for field_name, field_info in model_cls.model_fields.items():
         # Use the annotation (the type hint) for the field
         field_type = field_info.annotation
@@ -202,22 +223,27 @@ def _pydantic_to_custom_types(
             )
         elif get_origin(field_type) is Union:
             # Assume the union means it's optional
+            # TODO: support proper unions
             field_type = [
                 t for t in get_args(field_type) if t is not type(None)
             ][0]
-            rv = _map_python_type_to_type_str(field_type, custom_types)
+            rv = _map_python_type_to_type_str(
+                field_type, custom_type_registry, custom_type_models
+            )
             properties[field_name] = f"{rv}?"
         elif get_origin(field_type) is list:
             inner_type = get_args(field_type)[0]
-            rv = _map_python_type_to_type_str(inner_type, custom_types)
+            rv = _map_python_type_to_type_str(
+                inner_type, custom_type_registry, custom_type_models
+            )
             properties[field_name] = f"list[{rv}]"
         else:
             properties[field_name] = _map_python_type_to_type_str(
-                field_type, custom_types
+                field_type, custom_type_registry, custom_type_models
             )
 
-    # Add the custom type to the list
-    custom_types[model_name] = CustomType(
+    # Add the CustomType model for YAML output
+    custom_type_models[model_name] = CustomType(
         id=model_name,
         properties=properties,
         description=model_cls.__doc__ or f"Custom type for {model_name}",
@@ -227,7 +253,8 @@ def _pydantic_to_custom_types(
 
 def _map_python_type_to_variable_type(
     python_type: Any,
-    custom_types: dict[str, CustomType],
+    custom_type_registry: dict[str, Type[BaseModel]],
+    custom_type_models: dict[str, CustomType],
 ) -> str | VariableType:
     """
     Map Python type annotations to QType VariableType.
@@ -248,7 +275,9 @@ def _map_python_type_to_variable_type(
             element_type_annotation = args[0]
             # Recursively map the element type
             element_type = _map_python_type_to_variable_type(
-                element_type_annotation, custom_types
+                element_type_annotation,
+                custom_type_registry,
+                custom_type_models,
             )
             # Support lists of both primitive types and custom types
             if isinstance(element_type, PrimitiveTypeEnum):
@@ -281,7 +310,9 @@ def _map_python_type_to_variable_type(
         return python_type.__name__
     elif inspect.isclass(python_type) and issubclass(python_type, BaseModel):
         # If it's a Pydantic model, create or retrieve its CustomType definition
-        return _pydantic_to_custom_types(python_type, custom_types)
+        return _pydantic_to_custom_types(
+            python_type, custom_type_registry, custom_type_models
+        )
     raise ValueError(
         f"Unsupported Python type '{python_type}' for VariableType mapping"
     )
@@ -289,9 +320,12 @@ def _map_python_type_to_variable_type(
 
 def _map_python_type_to_type_str(
     python_type: Any,
-    custom_types: dict[str, CustomType],
+    custom_type_registry: dict[str, Type[BaseModel]],
+    custom_type_models: dict[str, CustomType],
 ) -> str:
-    var_type = _map_python_type_to_variable_type(python_type, custom_types)
+    var_type = _map_python_type_to_variable_type(
+        python_type, custom_type_registry, custom_type_models
+    )
     if isinstance(var_type, PrimitiveTypeEnum):
         return var_type.value
     elif inspect.isclass(python_type):

qtype/base/__init__.py

@@ -3,12 +3,18 @@
 from __future__ import annotations
 
 from .exceptions import QTypeError, ValidationError
-from .logging import get_logger
+from .resources import (
+    ResourceDirectory,
+    get_docs_resource,
+    get_examples_resource,
+)
 from .types import JSONValue
 
 __all__ = [
     "QTypeError",
     "ValidationError",
-    "get_logger",
     "JSONValue",
+    "ResourceDirectory",
+    "get_docs_resource",
+    "get_examples_resource",
 ]

qtype/base/logging.py

@@ -5,23 +5,6 @@ from __future__ import annotations
 import logging
 
 
-def get_logger(name: str) -> logging.Logger:
-    """Get a logger with the given name and consistent formatting."""
-    logger = logging.getLogger(f"qtype.{name}")
-
-    # Only configure if not already configured
-    if not logger.handlers:
-        handler = logging.StreamHandler()
-        formatter = logging.Formatter(
-            "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-        )
-        handler.setFormatter(formatter)
-        logger.addHandler(handler)
-        logger.setLevel(logging.INFO)
-
-    return logger
-
-
 def configure_logging(
     level: str = "INFO", format_string: str | None = None
 ) -> None:

qtype/base/resources.py

@@ -0,0 +1,193 @@
+"""Resource directory access utilities for QType package resources."""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from importlib.resources import files
+from pathlib import Path
+
+# Regex for pymdownx snippets: --8<-- "path/to/file"
+SNIPPET_REGEX = re.compile(r'--8<--\s+"([^"]+)"')
+
+
+class ResourceDirectory:
+    """Abstraction for accessing resource directories (docs, examples, etc.)."""
+
+    def __init__(
+        self, name: str, file_extension: str, resolve_snippets: bool = False
+    ):
+        """Initialize a resource directory.
+
+        Args:
+            name: Directory name (e.g., "docs", "examples")
+            file_extension: File extension to search for (e.g., ".md", ".yaml")
+            resolve_snippets: Whether to resolve MkDocs snippets in file content
+        """
+        self.name = name
+        self.file_extension = file_extension
+        self.resolve_snippets = resolve_snippets
+        self._path_cache: Path | None = None
+
+    def get_path(self) -> Path:
+        """Get the path to this resource directory.
+
+        Returns:
+            Path to the resource directory, trying installed package first,
+            then falling back to development path.
+        """
+        if self._path_cache is not None:
+            return self._path_cache
+
+        try:
+            # Try to get from installed package
+            resource_root = files("qtype") / self.name
+            # Check if it exists by trying to iterate
+            list(resource_root.iterdir())
+            self._path_cache = Path(str(resource_root))
+        except (FileNotFoundError, AttributeError, TypeError):
+            # Fall back to development path
+            self._path_cache = Path(__file__).parent.parent.parent / self.name
+
+        return self._path_cache
+
+    def get_file(self, file_path: str) -> str:
+        """Get the content of a specific file.
+
+        Args:
+            file_path: Relative path to the file from the resource root.
+
+        Returns:
+            The full content of the file.
+
+        Raises:
+            FileNotFoundError: If the specified file doesn't exist.
+            ValueError: If the path tries to access files outside the directory.
+        """
+        resource_path = self.get_path()
+
+        # Resolve the requested file path
+        requested_file = (resource_path / file_path).resolve()
+
+        # Security check: ensure the resolved path is within resource directory
+        try:
+            requested_file.relative_to(resource_path.resolve())
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid path: '{file_path}' is outside {self.name} directory"
+            ) from e
+
+        if not requested_file.exists():
+            raise FileNotFoundError(
+                (
+                    f"{self.name.capitalize()} file not found: '{file_path}'. "
+                    f"Use list_{self.name} to see available files."
+                )
+            )
+
+        if not requested_file.is_file():
+            raise ValueError(f"Path is not a file: '{file_path}'")
+
+        content = requested_file.read_text(encoding="utf-8")
+
+        # Apply snippet resolution if enabled
+        if self.resolve_snippets:
+            content = _resolve_snippets(content, requested_file, self)
+
+        return content
+
+    def list_files(self) -> list[str]:
+        """List all files in this resource directory.
+
+        Returns:
+            Sorted list of relative paths to all files with the configured extension.
+
+        Raises:
+            FileNotFoundError: If the resource directory doesn't exist.
+        """
+        resource_path = self.get_path()
+
+        if not resource_path.exists():
+            raise FileNotFoundError(
+                (
+                    f"{self.name.capitalize()} directory not found: "
+                    f"{resource_path}"
+                )
+            )
+
+        # Find all files with the configured extension
+        pattern = f"*{self.file_extension}"
+        files_list = []
+        for file in resource_path.rglob(pattern):
+            # Get relative path from resource root
+            rel_path = file.relative_to(resource_path)
+            files_list.append(str(rel_path))
+
+        return sorted(files_list)
+
+
+def _resolve_snippets(
+    content: str, base_path: Path, docs_resource: ResourceDirectory
+) -> str:
+    """Recursively resolve MkDocs snippets in markdown content.
+
+    Mimics the behavior of pymdownx.snippets.
+
+    Args:
+        content: The markdown content to process
+        base_path: Path to the file being processed (for resolving relative paths)
+        docs_resource: The docs ResourceDirectory for resolving snippet paths
+
+    Returns:
+        Content with all snippets resolved
+    """
+    docs_root = docs_resource.get_path()
+    project_root = docs_root.parent
+
+    def replace_match(match: re.Match) -> str:
+        snippet_path = match.group(1)
+
+        # pymdownx logic: try relative to current file, then docs, then project
+        candidates = [
+            base_path.parent / snippet_path,  # Relative to the doc file
+            docs_root / snippet_path,  # Relative to docs root
+            project_root / snippet_path,  # Relative to project root
+        ]
+
+        for candidate in candidates:
+            if candidate.exists() and candidate.is_file():
+                # Recursively resolve snippets inside the included file
+                return _resolve_snippets(
+                    candidate.read_text(encoding="utf-8"),
+                    candidate,
+                    docs_resource,
+                )
+
+        return f"> [!WARNING] Could not resolve snippet: {snippet_path}"
+
+    return SNIPPET_REGEX.sub(replace_match, content)
+
+
+# Initialize singleton resource directories
+_docs_resource = ResourceDirectory("docs", ".md", resolve_snippets=True)
+_examples_resource = ResourceDirectory("examples", ".yaml")
+
+
+@lru_cache(maxsize=1)
+def get_docs_resource() -> ResourceDirectory:
+    """Get the singleton docs resource directory.
+
+    Returns:
+        ResourceDirectory instance for documentation files.
+    """
+    return _docs_resource
+
+
+@lru_cache(maxsize=1)
+def get_examples_resource() -> ResourceDirectory:
+    """Get the singleton examples resource directory.
+
+    Returns:
+        ResourceDirectory instance for example files.
+    """
+    return _examples_resource

qtype/cli.py

@@ -7,9 +7,9 @@ import importlib
 import logging
 from pathlib import Path
 
-from qtype.base.logging import get_logger
+from qtype.base.logging import configure_logging
 
-logger = get_logger("application.facade")
+logger = logging.getLogger(__name__)
 
 try:
     from importlib.metadata import entry_points
@@ -59,9 +59,8 @@ def _discover_local_commands(subparsers: argparse._SubParsersAction) -> None:
                     f"Built-in command module {module_name} does not have a 'parser' function"
                 )
         except Exception as e:
-            logging.error(
-                f"Failed to load built-in command module {module_name}: {e}",
-                exc_info=True,
+            logging.debug(
+                f"Failed to load built-in command module {module_name}: {e} -- you may need the mcp or interpreter extras."
             )
 
 
@@ -133,10 +132,7 @@ def main() -> None:
     args = parser.parse_args()
 
     # Set logging level based on user input
-    logging.basicConfig(
-        level=getattr(logging, args.log_level),
-        format="%(asctime)s - %(levelname)s: %(message)s",
-    )
+    configure_logging(level=args.log_level)
 
     # Dispatch to the selected subcommand
     args.func(args)