qtype 0.0.1__py3-none-any.whl

qtype/cli.py

@@ -0,0 +1,73 @@
+"""
+QType CLI entry point for generating schemas and validating QType specs.
+"""
+
+import argparse
+import importlib
+import logging
+from pathlib import Path
+
+
+def _discover_commands(subparsers: argparse._SubParsersAction) -> None:
+    """Automatically discover and register command modules.
+
+    Args:
+        subparsers: The subparsers object to add commands to.
+    """
+    commands_dir = Path(__file__).parent / "commands"
+
+    for py_file in commands_dir.glob("*.py"):
+        # Skip __init__.py and other private files
+        if py_file.name.startswith("_"):
+            continue
+
+        module_name = f"qtype.commands.{py_file.stem}"
+        try:
+            module = importlib.import_module(module_name)
+            # Call the parser function to set up the subparser
+            if hasattr(module, "parser"):
+                module.parser(subparsers)
+            else:
+                logging.warning(
+                    f"Command module {module_name} does not have a 'parser' function"
+                )
+        except Exception as e:
+            logging.error(
+                f"Failed to load command module {module_name}: {e}",
+                exc_info=True,
+            )
+
+
+def main() -> None:
+    """
+    Main entry point for the QType CLI.
+    Sets up argument parsing and dispatches to the appropriate subcommand.
+    """
+    parser = argparse.ArgumentParser(
+        description="QType CLI: Generate schema, validate, or run QType specs."
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Set the logging level (default: INFO)",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # Auto-discover and register commands
+    _discover_commands(subparsers)
+
+    args = parser.parse_args()
+
+    # Set logging level based on user input
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(levelname)s: %(message)s",
+    )
+
+    # Dispatch to the selected subcommand
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

qtype/commands/__init__.py

@@ -0,0 +1,5 @@
+"""qtype.commands package initialization."""
+
+# This package contains command modules that are auto-discovered by the CLI.
+# Each module should have a `parser(subparsers)` function to set up its subcommand
+# and a `main(args)` function to handle execution.

qtype/commands/convert.py

@@ -0,0 +1,76 @@
+import argparse
+import logging
+
+from pydantic_yaml import to_yaml_str
+
+from qtype.commons.generate import _write_yaml_file
+from qtype.converters.tools_from_module import tools_from_module
+from qtype.dsl.model import ToolList
+
+logger = logging.getLogger(__name__)
+
+
+def convert_api(args: argparse.Namespace) -> None:
+    raise NotImplementedError("API conversion is not implemented yet.")
+
+
+def convert_module(args: argparse.Namespace) -> None:
+    """Convert Python module tools to qtype format."""
+    tools = ToolList(tools_from_module(args.module_path))  # type: ignore
+    if not tools:
+        raise ValueError(f"No tools found in the module: {args.module_path}")
+
+    if args.output:
+        _write_yaml_file(tools, args.output)
+        logger.info("Resulting yaml written to %s", args.output)
+    else:
+        logger.info(
+            "Resulting yaml:\n%s",
+            to_yaml_str(tools, exclude_unset=True, exclude_none=True),
+        )
+
+
+def parser(subparsers: argparse._SubParsersAction) -> None:
+    """Set up the converter subcommand parser."""
+    cmd_parser = subparsers.add_parser(
+        "convert", help="Creates qtype files from different sources."
+    )
+
+    # Create a new subparser for "convert api", "convert module", etc.
+    convert_subparsers = cmd_parser.add_subparsers(
+        dest="convert_command", required=True
+    )
+
+    convert_module_parser = convert_subparsers.add_parser(
+        "module", help="Converts module specifications to qtype format."
+    )
+    convert_module_parser.add_argument(
+        "module_path",
+        type=str,
+        help="Path to the Python module to convert.",
+    )
+    convert_module_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default=None,
+        help="Where to save the converted YAML file. If not specified, it is just printed to stdout.",
+    )
+    convert_module_parser.set_defaults(func=convert_module)
+
+    convert_api_parser = convert_subparsers.add_parser(
+        "api", help="Converts API specifications to qtype format."
+    )
+    convert_api_parser.add_argument(
+        "openapi_spec",
+        type=str,
+        help="URL of the OpenAPI specification.",
+    )
+    convert_api_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default=None,
+        help="Where to save the converted YAML file. If not specified, it is just printed to stdout.",
+    )
+    convert_api_parser.set_defaults(func=convert_api)

qtype/commands/generate.py

@@ -0,0 +1,107 @@
+import argparse
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+from qtype.commons.generate import dump_commons_library
+from qtype.dsl.document import generate_documentation
+from qtype.dsl.model import Document
+
+logger = logging.getLogger(__name__)
+
+
+def generate_schema(args: argparse.Namespace) -> None:
+    """Generate and output the JSON schema for Document.
+
+    Args:
+        args (argparse.Namespace): Command-line arguments with an optional
+            'output' attribute specifying the output file path.
+    """
+    schema = Document.model_json_schema()
+    # Add the $schema property to indicate JSON Schema version
+    schema["$schema"] = "http://json-schema.org/draft-07/schema#"
+    output = json.dumps(schema, indent=2)
+    output_path: Optional[str] = getattr(args, "output", None)
+    if output_path:
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(output)
+        logger.info(f"Schema written to {output_path}")
+    else:
+        logger.info("Schema is:\n%s", output)
+
+
+def parser(subparsers: argparse._SubParsersAction) -> None:
+    """Set up the generate subcommand parser."""
+    cmd_parser = subparsers.add_parser(
+        "generate", help="Generates qtype files from different sources."
+    )
+    generate_subparsers = cmd_parser.add_subparsers(
+        dest="generate_target", required=True
+    )
+
+    # Parse for generating commons library tools
+    commons_parser = generate_subparsers.add_parser(
+        "commons", help="Generates the commons library tools."
+    )
+    commons_parser.add_argument(
+        "-p",
+        "--prefix",
+        type=str,
+        default="./common/",
+        help="Output prefix for the YAML file (default: ./common/)",
+    )
+    commons_parser.set_defaults(func=dump_commons_library)
+
+    # Parser for generating the json schema
+    schema_parser = generate_subparsers.add_parser(
+        "schema", help="Generates the schema for the QType DSL."
+    )
+    schema_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        help="Output file for the schema (default: stdout)",
+    )
+    schema_parser.set_defaults(func=generate_schema)
+
+    # Parser for generating the DSL documentation
+    dsl_parser = generate_subparsers.add_parser(
+        "dsl-docs",
+        help="Generates markdown documentation for the QType DSL classes.",
+    )
+    dsl_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default="docs/DSL-Reference/",
+        help="Output directory for the DSL documentation (default: docs/DSL-Reference/)",
+    )
+    dsl_parser.set_defaults(
+        func=lambda args: generate_documentation(Path(args.output))
+    )
+
+    # Parser for generating the semantic model
+    # only add this if networkx and ruff are installed
+    try:
+        import networkx  # noqa: F401
+        import ruff  # noqa: F401
+
+        from qtype.semantic.generate import generate_semantic_model
+
+        semantic_parser = generate_subparsers.add_parser(
+            "semantic-model",
+            help="Generates the semantic model (i.e., qtype/semantic/model.py) from QType DSL.",
+        )
+        semantic_parser.add_argument(
+            "-o",
+            "--output",
+            type=str,
+            default="qtype/semantic/model.py",
+            help="Output file for the semantic model (default: stdout)",
+        )
+        semantic_parser.set_defaults(func=generate_semantic_model)
+    except ImportError:
+        logger.debug(
+            "NetworkX or Ruff is not installed. Skipping semantic model generation."
+        )

qtype/commands/run.py

@@ -0,0 +1,200 @@
+"""
+Command-line interface for running QType YAML spec files.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import Any
+
+from qtype.dsl.domain_types import ChatMessage
+from qtype.interpreter.flow import execute_flow
+from qtype.interpreter.typing import create_input_type_model
+from qtype.loader import load
+from qtype.semantic.model import Application, Flow, Step
+
+logger = logging.getLogger(__name__)
+
+
+def _get_flow(app: Application, flow_id: str | None) -> Flow:
+    if len(app.flows) == 0:
+        raise ValueError(
+            "No flows found in the application."
+            " Please ensure the spec contains at least one flow."
+        )
+
+    if flow_id is not None:
+        # find the first flow in the list with the given flow_id
+        flow = next((f for f in app.flows if f.id == flow_id), None)
+        if flow is None:
+            raise ValueError(f"Flow not found: {flow_id}")
+
+    else:
+        flow = app.flows[0]
+
+    return flow
+
+
+def _telemetry(spec: Application) -> None:
+    if spec.telemetry:
+        logger.info(
+            f"Telemetry enabled with endpoint: {spec.telemetry.endpoint}"
+        )
+        # Register telemetry if needed
+        from qtype.interpreter.telemetry import register
+
+        register(spec.telemetry, spec.id)
+
+
+def run_api(args: Any) -> None:
+    """Run a QType YAML spec file as an API.
+
+    Args:
+        args: Arguments passed from the command line or calling context.
+    """
+    spec = load(args.spec)
+    logger.info(f"Running API for spec: {args.spec}")
+    from qtype.interpreter.api import APIExecutor
+
+    # Get the name from the spec filename.
+    # so if filename is tests/specs/full_application_test.qtype.yaml, name should be "Full Application Test"
+    name = (
+        args.spec.split("/")[-1]
+        .replace(".qtype.yaml", "")
+        .replace("_", " ")
+        .title()
+    )
+
+    _telemetry(spec)
+    api_executor = APIExecutor(spec)
+    fastapi_app = api_executor.create_app(name=name)
+
+    import uvicorn
+
+    uvicorn.run(
+        fastapi_app,
+        host=args.host,
+        port=args.port,
+        log_level="info",
+    )
+
+
+def run_flow(args: Any) -> None:
+    """Run a QType YAML spec file by executing its flows.
+
+    Args:
+        args: Arguments passed from the command line or calling context.
+    """
+    spec = load(args.spec)
+
+    flow = _get_flow(spec, args.flow)
+    logger.info(f"Executing flow: {flow.id}")
+    input_type = create_input_type_model(flow)
+    inputs = input_type.model_validate_json(args.input)
+    for var in flow.inputs:
+        # Get the value from the request using the variable ID
+        inputs_dict = inputs.model_dump()  # type: ignore
+        if var.id in inputs_dict:
+            var.value = getattr(inputs, var.id)
+    _telemetry(spec)
+
+    was_streamed = False
+    previous: str = ""
+
+    def stream_fn(step: Step, msg: ChatMessage | str) -> None:
+        """Stream function to handle step outputs."""
+        nonlocal was_streamed, previous
+        if step == flow.steps[-1]:
+            was_streamed = True
+            if isinstance(msg, ChatMessage):
+                content = " ".join(
+                    [m.content for m in msg.blocks if m.content]
+                )
+                # Note: streaming chat messages accumulate the content...
+                content = content.removeprefix(previous)
+                print(content, end="", flush=True)
+                previous += content
+            else:
+                print(msg, end="", flush=True)
+
+    result = execute_flow(flow, stream_fn=stream_fn)  # type: ignore
+    if not was_streamed:
+        logger.info(
+            f"Flow execution result: {', '.join([f'{var.id}: {var.value}' for var in result])}"
+        )
+    else:
+        print("\n")
+
+
+def run_ui(args: Any) -> None:
+    """Run a QType YAML spec file by executing its flows in a UI.
+
+    Args:
+        args: Arguments passed from the command line or calling context.
+    """
+    # Placeholder for actual implementation
+    logger.info(f"Running UI for spec: {args.spec}")
+    # Here you would implement the logic to run the flow in a UI context
+
+
+def parser(subparsers: argparse._SubParsersAction) -> None:
+    """Set up the run subcommand parser.
+
+    Args:
+        subparsers: The subparsers object to add the command to.
+    """
+    cmd_parser = subparsers.add_parser(
+        "run", help="Run a QType YAML spec by executing its flows."
+    )
+
+    run_subparsers = cmd_parser.add_subparsers(
+        dest="run_method", required=True
+    )
+
+    # Parse for generating API runner
+    api_runner_parser = run_subparsers.add_parser(
+        "api", help="Serves the qtype file as an API."
+    )
+    api_runner_parser.add_argument(
+        "-H", "--host", type=str, default="localhost"
+    )
+    api_runner_parser.add_argument("-p", "--port", type=int, default=8000)
+    api_runner_parser.set_defaults(func=run_api)
+
+    # Parse for running a flow
+    flow_parser = run_subparsers.add_parser(
+        "flow", help="Runs a QType YAML spec file by executing its flows."
+    )
+    flow_parser.add_argument(
+        "-f",
+        "--flow",
+        type=str,
+        default=None,
+        help="The name of the flow to run. If not specified, runs the first flow found.",
+    )
+    flow_parser.add_argument(
+        "input",
+        type=str,
+        help="JSON blob of input values for the flow.",
+    )
+
+    flow_parser.set_defaults(func=run_flow)
+
+    # Run a user interface for the spec
+    ui_parser = run_subparsers.add_parser(
+        "ui",
+        help="Runs a QType YAML spec file by executing its flows in a UI.",
+    )
+    ui_parser.add_argument(
+        "-f",
+        "--flow",
+        type=str,
+        default=None,
+        help="The name of the flow to run in the UI. If not specified, runs the first flow found.",
+    )
+    ui_parser.set_defaults(func=run_ui)
+
+    cmd_parser.add_argument(
+        "spec", type=str, help="Path to the QType YAML spec file."
+    )

qtype/commands/validate.py

@@ -0,0 +1,83 @@
+"""
+Command-line interface for validating QType YAML spec files.
+"""
+
+import argparse
+import logging
+import sys
+from typing import Any
+
+from pydantic import ValidationError
+
+from qtype import dsl
+from qtype.dsl.validator import QTypeValidationError, validate
+from qtype.loader import _resolve_root, load_yaml
+from qtype.semantic.errors import SemanticResolutionError
+from qtype.semantic.resolver import resolve
+
+logger = logging.getLogger(__name__)
+
+
+def main(args: Any) -> None:
+    """
+    Validate a QType YAML spec file against the QTypeSpec schema and semantics.
+
+    Args:
+        args: Arguments passed from the command line or calling context.
+
+    Exits:
+        Exits with code 1 if validation fails.
+    """
+    try:
+        yaml_data = load_yaml(args.spec)
+        logging.info("✅ Schema validation successful.")
+        document = dsl.Document.model_validate(yaml_data)
+        logging.info("✅ Model validation successful.")
+        document = _resolve_root(document)
+        if not isinstance(document, dsl.Application):
+            logging.warning(
+                "🟨 Spec is not an Application, skipping semantic resolution."
+            )
+        else:
+            document = validate(document)
+            logger.info("✅ Language validation successful")
+            document = resolve(document)
+            logger.info("✅ Semantic validation successful")
+        if args.print:
+            logger.info(
+                document.model_dump_json(  # type: ignore
+                    indent=2,
+                    exclude_none=True,
+                )
+            )
+
+    except ValidationError as exc:
+        logger.error("❌ Schema validation failed:\n%s", exc)
+        sys.exit(1)
+    except QTypeValidationError as exc:
+        logger.error("❌ DSL validation failed:\n%s", exc)
+        sys.exit(1)
+    except SemanticResolutionError as exc:
+        logger.error("❌ Semantic resolution failed:\n%s", exc)
+        sys.exit(1)
+
+
+def parser(subparsers: argparse._SubParsersAction) -> None:
+    """Set up the validate subcommand parser.
+
+    Args:
+        subparsers: The subparsers object to add the command to.
+    """
+    cmd_parser = subparsers.add_parser(
+        "validate", help="Validate a QType YAML spec against the schema."
+    )
+    cmd_parser.add_argument(
+        "spec", type=str, help="Path to the QType YAML spec file."
+    )
+    cmd_parser.add_argument(
+        "-p",
+        "--print",
+        action="store_true",
+        help="Print the spec after validation (default: False)",
+    )
+    cmd_parser.set_defaults(func=main)

qtype/commons/generate.py

@@ -0,0 +1,88 @@
+import argparse
+import logging
+
+from pydantic import BaseModel
+from pydantic_yaml import to_yaml_str
+
+from qtype.converters.tools_from_module import tools_from_module
+from qtype.dsl.model import Model, ModelList, ToolList
+
+logger = logging.getLogger(__name__)
+
+
+def _write_yaml_file(data: BaseModel, output_path: str) -> None:
+    """
+    Write a Pydantic model to a YAML file.
+
+    Args:
+        data: The Pydantic model instance to write.
+        output_path: The path where the YAML file will be saved.
+    """
+    result = to_yaml_str(data, exclude_unset=True, exclude_none=True)
+    with open(output_path, "w") as f:
+        f.write(result)
+    logger.info(f"Data exported to {output_path}")
+
+
+def dump_built_in_tools(args: argparse.Namespace) -> None:
+    tools = tools_from_module("qtype.commons.tools")
+    if not tools:
+        logger.error("No tools found in the commons library.")
+        return
+
+    tool_list = ToolList(root=tools)  # type: ignore
+    output_path = f"{args.prefix}/tools.qtype.yaml"
+    _write_yaml_file(tool_list, output_path)
+    logging.info(f"Built-in tools exported to {output_path}")
+
+
+def dump_aws_bedrock_models(args: argparse.Namespace) -> None:
+    """
+    Export AWS Bedrock models to a YAML file.
+
+    Args:
+        args: Command line arguments containing the output prefix.
+    """
+    try:
+        import boto3
+
+        client = boto3.client("bedrock")
+        models = client.list_foundation_models()
+
+        # generate a model list from the AWS Bedrock models
+        # the return type of list_foundation_models is
+
+        model_list = ModelList(
+            [
+                Model(
+                    id=model_summary["modelId"],
+                    provider="aws-bedrock",
+                )
+                for model_summary in models.get("modelSummaries", [])
+            ]
+        )
+        output_path = f"{args.prefix}/aws.bedrock.models.qtype.yaml"
+        _write_yaml_file(model_list, output_path)
+        logging.info(f"AWS Bedrock Models exported to {output_path}")
+
+        logger.info("Exporting AWS Bedrock models...")
+        # Placeholder for actual implementation
+        # This function should gather AWS Bedrock models and export them similarly to dump_built_in_tools
+        logger.info("AWS Bedrock models exported successfully.")
+    except ImportError:
+        logger.error(
+            "boto3 is not installed. Please install it to use AWS Bedrock model export."
+        )
+
+
+def dump_commons_library(args: argparse.Namespace) -> None:
+    """
+    Export the commons library tools to a YAML file.
+
+    Args:
+        args: Command line arguments containing the output prefix.
+    """
+    logger.info("Exporting commons library tools...")
+    dump_built_in_tools(args)
+    dump_aws_bedrock_models(args)
+    logger.info("Commons library tools export complete.")