qtype 0.0.5__tar.gz → 0.0.7__tar.gz

{qtype-0.0.5/qtype.egg-info → qtype-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qtype
-Version: 0.0.5
+Version: 0.0.7
 Summary: DSL for Generative AI Prototyping
 Author-email: Lou Kratz <lou.kratz+qtype@bazaarvoice.com>
 License-Expression: Apache-2.0
@@ -15,6 +15,8 @@ Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: openai>=1.93.0
 Requires-Dist: fsspec>=2025.5.1
 Requires-Dist: pydantic-yaml>=1.5.1
+Requires-Dist: mkdocs-awesome-pages-plugin>=2.10.1
+Requires-Dist: mermaid-py>=0.8.0
 Provides-Extra: interpreter
 Requires-Dist: arize-phoenix-otel>=0.12.1; extra == "interpreter"
 Requires-Dist: boto3>=1.34.0; extra == "interpreter"
@@ -24,8 +26,9 @@ Requires-Dist: llama-index-embeddings-openai>=0.3.1; extra == "interpreter"
 Requires-Dist: llama-index-llms-bedrock-converse>=0.7.4; extra == "interpreter"
 Requires-Dist: llama-index-llms-bedrock>=0.3.8; extra == "interpreter"
 Requires-Dist: llama-index>=0.12.45; extra == "interpreter"
-Requires-Dist: openinference-instrumentation-llama-index>=4.3.1; extra == "interpreter"
+Requires-Dist: openinference-instrumentation-llama-index>=4.3.4; extra == "interpreter"
 Requires-Dist: psycopg2-binary>=2.9.10; extra == "interpreter"
+Requires-Dist: python-magic>=0.4.27; extra == "interpreter"
 Requires-Dist: uvicorn[standard]>=0.35.0; extra == "interpreter"
 Dynamic: license-file
 
@@ -44,15 +47,17 @@ Install QType:
 pip install qtype[interpreter]
 ```
 
-Create a file `hello_world.qtype.yaml` that executes a single chat question:
+Create a file `hello_world.qtype.yaml` that answers a question:
 ```yaml
 id: hello_world
 flows:
-  - id: simple_qa_flow
+  - id: chat_example
+    description: A simple chat flow with OpenAI
+    mode: Chat
     steps:
       - id: llm_inference_step
         model: 
-          id: gpt-4o
+          id: gpt-4
           provider: openai
           auth: 
             id: openai_auth
@@ -61,11 +66,11 @@ flows:
         system_message: |
           You are a helpful assistant.
         inputs:
-          - id: prompt
-            type: text
+          - id: user_message
+            type: ChatMessage
         outputs:
-          - id: response_message
-            type: text
+          - id: response
+            type: ChatMessage
 ```
 
 Put your openai api key into your `.env` file:
@@ -73,12 +78,14 @@ Put your openai api key into your `.env` file:
 echo "OPENAI_KEY=sk...." >> .env
 ```
 
-Validate that the file matches the spec:
-```
-qtype validate hello_world.qtype.yaml
+Validate it's semantic correctness:
+
+```bash
+qtype validate hello_world.qtype.yaml 
 ```
 
 You should see:
+
 ```
 INFO: ✅ Schema validation successful.
 INFO: ✅ Model validation successful.
@@ -86,23 +93,24 @@ INFO: ✅ Language validation successful
 INFO: ✅ Semantic validation successful
 ```
 
-Finally,execute the flow.
-```
-qtype run flow '{"prompt":"What is the airspeed of a laden swallow?"}' hello_world.qtype.yaml 
+Launch the interpreter:
+
+```bash
+qtype serve hello_world.qtype.yaml`
 ```
 
-You should see (something similar to):
 
-```
-INFO: Executing flow: simple_qa_flow
+And go to [http://localhost:8000/ui](http://localhost:8000/ui) to see the user interface for your application:
+
+![Example UI](docs/example_ui.png)
 
-The airspeed of a laden swallow is a humorous reference from the movie "Monty Python and the Holy Grail." In the film, the question is posed as "What is the airspeed velocity of an unladen swallow?" The joke revolves around the absurdity and specificity of the question, and it doesn't have a straightforward answer. However, if you're curious about the real-life airspeed of a swallow, the European Swallow (Hirundo rustica) typically flies at around 11 meters per second, or 24 miles per hour, when unladen. The concept of a "laden" swallow is part of the humor, as it would depend on what the swallow is carrying and is not a standard measurement.
-```
 
 ---
 
 See the [full docs](https://bazaarvoice.github.io/qtype/) for more examples and guides.
 
+
+
 ## 🤝 Contributing
 
 Contributions welcome! Please follow the instructions in the [contribution guide](https://bazaarvoice.github.io/qtype/contributing/).

{qtype-0.0.5 → qtype-0.0.7}/README.md

@@ -13,15 +13,17 @@ Install QType:
 pip install qtype[interpreter]
 ```
 
-Create a file `hello_world.qtype.yaml` that executes a single chat question:
+Create a file `hello_world.qtype.yaml` that answers a question:
 ```yaml
 id: hello_world
 flows:
-  - id: simple_qa_flow
+  - id: chat_example
+    description: A simple chat flow with OpenAI
+    mode: Chat
     steps:
       - id: llm_inference_step
         model: 
-          id: gpt-4o
+          id: gpt-4
           provider: openai
           auth: 
             id: openai_auth
@@ -30,11 +32,11 @@ flows:
         system_message: |
           You are a helpful assistant.
         inputs:
-          - id: prompt
-            type: text
+          - id: user_message
+            type: ChatMessage
         outputs:
-          - id: response_message
-            type: text
+          - id: response
+            type: ChatMessage
 ```
 
 Put your openai api key into your `.env` file:
@@ -42,12 +44,14 @@ Put your openai api key into your `.env` file:
 echo "OPENAI_KEY=sk...." >> .env
 ```
 
-Validate that the file matches the spec:
-```
-qtype validate hello_world.qtype.yaml
+Validate it's semantic correctness:
+
+```bash
+qtype validate hello_world.qtype.yaml 
 ```
 
 You should see:
+
 ```
 INFO: ✅ Schema validation successful.
 INFO: ✅ Model validation successful.
@@ -55,23 +59,24 @@ INFO: ✅ Language validation successful
 INFO: ✅ Semantic validation successful
 ```
 
-Finally,execute the flow.
-```
-qtype run flow '{"prompt":"What is the airspeed of a laden swallow?"}' hello_world.qtype.yaml 
+Launch the interpreter:
+
+```bash
+qtype serve hello_world.qtype.yaml`
 ```
 
-You should see (something similar to):
 
-```
-INFO: Executing flow: simple_qa_flow
+And go to [http://localhost:8000/ui](http://localhost:8000/ui) to see the user interface for your application:
+
+![Example UI](docs/example_ui.png)
 
-The airspeed of a laden swallow is a humorous reference from the movie "Monty Python and the Holy Grail." In the film, the question is posed as "What is the airspeed velocity of an unladen swallow?" The joke revolves around the absurdity and specificity of the question, and it doesn't have a straightforward answer. However, if you're curious about the real-life airspeed of a swallow, the European Swallow (Hirundo rustica) typically flies at around 11 meters per second, or 24 miles per hour, when unladen. The concept of a "laden" swallow is part of the humor, as it would depend on what the swallow is carrying and is not a standard measurement.
-```
 
 ---
 
 See the [full docs](https://bazaarvoice.github.io/qtype/) for more examples and guides.
 
+
+
 ## 🤝 Contributing
 
 Contributions welcome! Please follow the instructions in the [contribution guide](https://bazaarvoice.github.io/qtype/contributing/).

{qtype-0.0.5 → qtype-0.0.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qtype"
-version = "0.0.5"
+version = "0.0.7"
 description = "DSL for Generative AI Prototyping"
 authors = [{ name="Lou Kratz", email="lou.kratz+qtype@bazaarvoice.com" }]
 readme = "README.md"
@@ -12,7 +12,9 @@ dependencies = [
     "python-dotenv>=1.0.0",
     "openai>=1.93.0",
     "fsspec>=2025.5.1",
-    "pydantic-yaml>=1.5.1"
+    "pydantic-yaml>=1.5.1",
+    "mkdocs-awesome-pages-plugin>=2.10.1",
+    "mermaid-py>=0.8.0",
 ]
 license = "APACHE-2.0"
 license-files = ["LICEN[CS]E*"]
@@ -30,8 +32,9 @@ interpreter = [
     "llama-index-llms-bedrock-converse>=0.7.4",
     "llama-index-llms-bedrock>=0.3.8",
     "llama-index>=0.12.45",
-    "openinference-instrumentation-llama-index>=4.3.1",
+    "openinference-instrumentation-llama-index>=4.3.4",
     "psycopg2-binary>=2.9.10",
+    "python-magic>=0.4.27",
     "uvicorn[standard]>=0.35.0",
 ]
 
@@ -42,7 +45,7 @@ dev = [
     "coverage>=7.0.0",
     "ipython>=8.37.0",
     "isort>=5.13.0",
-    "mkdocs-exclude>=1.0.2",
+    "mkdocs-awesome-pages-plugin>=2.10.1",
     "mkdocs-material>=9.6.15",
     "mkdocs>=1.6.1",
     "mkdocstrings-python>=1.16.12",
@@ -77,6 +80,9 @@ qtype = "qtype.cli:main"
 include = ["qtype*"]
 exclude = ["tests*"]
 
+[tool.setuptools.package-data]
+"qtype.interpreter" = ["ui/**/*"]
+
 # Tool configurations
 [tool.ruff]
 line-length = 79

{qtype-0.0.5 → qtype-0.0.7}/qtype/commands/convert.py

@@ -3,9 +3,7 @@ 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
+from qtype.dsl.model import Application
 
 logger = logging.getLogger(__name__)
 
@@ -16,12 +14,27 @@ def convert_api(args: argparse.Namespace) -> None:
 
 def convert_module(args: argparse.Namespace) -> None:
     """Convert Python module tools to qtype format."""
-    tools = ToolList(tools_from_module(args.module_path))  # type: ignore
+
+    from qtype.commons.generate import _write_yaml_file
+    from qtype.converters.tools_from_module import tools_from_module
+    from qtype.dsl.model import ToolList
+
+    tools, types = tools_from_module(args.module_path)  # type: ignore
     if not tools:
         raise ValueError(f"No tools found in the module: {args.module_path}")
+    
+    if types:
+        doc = Application(
+            id=args.module_path,
+            description=f"Tools created from Python module {args.module_path}",
+            tools=list(tools),
+            types=types,
+        )
+    else:
+        doc = ToolList(root=list(tools))
 
     if args.output:
-        _write_yaml_file(tools, args.output)
+        _write_yaml_file(doc, args.output)
         logger.info("Resulting yaml written to %s", args.output)
     else:
         logger.info(

{qtype-0.0.5 → qtype-0.0.7}/qtype/commands/generate.py

@@ -4,13 +4,23 @@ 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 run_dump_commons_library(args: argparse.Namespace) -> None:
+    from qtype.commons.generate import dump_commons_library
+
+    dump_commons_library(args)
+
+
+def run_generate_documentation(args: argparse.Namespace) -> None:
+    from qtype.dsl.document import generate_documentation
+
+    generate_documentation(Path(args.output))
+
+
 def generate_schema(args: argparse.Namespace) -> None:
     """Generate and output the JSON schema for Document.
 
@@ -51,7 +61,7 @@ def parser(subparsers: argparse._SubParsersAction) -> None:
         default="./common/",
         help="Output prefix for the YAML file (default: ./common/)",
     )
-    commons_parser.set_defaults(func=dump_commons_library)
+    commons_parser.set_defaults(func=run_dump_commons_library)
 
     # Parser for generating the json schema
     schema_parser = generate_subparsers.add_parser(
@@ -74,12 +84,10 @@ def parser(subparsers: argparse._SubParsersAction) -> None:
         "-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))
+        default="docs/components/",
+        help="Output directory for the DSL documentation (default: docs/components/)",
     )
+    dsl_parser.set_defaults(func=run_generate_documentation)
 
     # Parser for generating the semantic model
     # only add this if networkx and ruff are installed

{qtype-0.0.5 → qtype-0.0.7}/qtype/commands/run.py

@@ -47,46 +47,13 @@ def _telemetry(spec: Application) -> None:
         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)
+    spec, _ = load(args.spec)
 
     flow = _get_flow(spec, args.flow)
     logger.info(f"Executing flow: {flow.id}")
@@ -127,17 +94,6 @@ def run_flow(args: Any) -> None:
         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.
 
@@ -145,56 +101,23 @@ def parser(subparsers: argparse._SubParsersAction) -> None:
         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", help="Executes a QType Application locally"
     )
-
-    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(
+    cmd_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(
+    cmd_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."
     )
+
+    cmd_parser.set_defaults(func=run_flow)

qtype-0.0.7/qtype/commands/serve.py

@@ -0,0 +1,73 @@
+"""
+Command-line interface for running QType YAML spec files.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import Any
+
+import uvicorn
+
+from qtype.commands.run import _telemetry
+from qtype.loader import load
+
+logger = logging.getLogger(__name__)
+
+
+def serve(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, ui_enabled=not args.disable_ui
+    )
+
+    uvicorn.run(
+        fastapi_app,
+        host=args.host,
+        port=args.port,
+        log_level="info",
+    )
+
+
+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(
+        "serve", help="Serve a web experience for a QType application"
+    )
+
+    cmd_parser.add_argument("-p", "--port", type=int, default=8000)
+    cmd_parser.add_argument("-H", "--host", type=str, default="localhost")
+    cmd_parser.add_argument(
+        "--disable-ui",
+        action="store_true",
+        help="Disable the UI for the QType application.",
+    )
+    cmd_parser.set_defaults(func=serve)
+
+    cmd_parser.add_argument(
+        "spec", type=str, help="Path to the QType YAML spec file."
+    )

{qtype-0.0.5 → qtype-0.0.7}/qtype/commands/validate.py

@@ -10,8 +10,13 @@ from typing import Any
 from pydantic import ValidationError
 
 from qtype import dsl
+from qtype.dsl.custom_types import build_dynamic_types
 from qtype.dsl.validator import QTypeValidationError, validate
-from qtype.loader import _resolve_root, load_yaml
+from qtype.loader import (
+    _list_dynamic_types_from_document,
+    _resolve_root,
+    load_yaml,
+)
 from qtype.semantic.errors import SemanticResolutionError
 from qtype.semantic.resolver import resolve
 
@@ -30,29 +35,34 @@ def main(args: Any) -> None:
     """
     try:
         yaml_data = load_yaml(args.spec)
+        dynamic_types_lists = _list_dynamic_types_from_document(yaml_data)
+        dynamic_types_registry = build_dynamic_types(dynamic_types_lists)
         logging.info("✅ Schema validation successful.")
-        document = dsl.Document.model_validate(yaml_data)
+
+        document = dsl.Document.model_validate(
+            yaml_data, context={"custom_types": dynamic_types_registry}
+        )
         logging.info("✅ Model validation successful.")
-        document = _resolve_root(document)
-        if not isinstance(document, dsl.Application):
+        root = _resolve_root(document)
+        if not isinstance(root, dsl.Application):
             logging.warning(
                 "🟨 Spec is not an Application, skipping semantic resolution."
             )
         else:
-            document = validate(document)
+            root = validate(root)
             logger.info("✅ Language validation successful")
-            document = resolve(document)
+            app = resolve(root)
             logger.info("✅ Semantic validation successful")
         if args.print:
             logger.info(
-                document.model_dump_json(  # type: ignore
+                (app if "app" in locals() else root).model_dump_json(  # type: ignore
                     indent=2,
                     exclude_none=True,
                 )
             )
 
     except ValidationError as exc:
-        logger.error("❌ Schema validation failed:\n%s", exc)
+        logger.error("❌ Validation failed:\n%s", exc)
         sys.exit(1)
     except QTypeValidationError as exc:
         logger.error("❌ DSL validation failed:\n%s", exc)

qtype-0.0.7/qtype/commands/visualize.py

@@ -0,0 +1,87 @@
+"""
+Command-line interface for visualizing QType YAML spec files.
+"""
+
+import argparse
+import logging
+import tempfile
+import webbrowser
+from typing import Any
+
+from qtype.loader import load
+from qtype.semantic.visualize import visualize_application
+
+logger = logging.getLogger(__name__)
+
+
+def main(args: Any) -> None:
+    """
+    visualize 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.
+    """
+    import mermaid as md
+
+    application, _ = load(args.spec)
+
+    diagram = visualize_application(application)
+
+    render = None
+    if args.output:
+        if args.output.endswith(".mmd") or args.output.endswith(".mermaid"):
+            with open(args.output, "w") as f:
+                f.write(diagram)
+            logger.info(f"Mermaid diagram written to {args.output}")
+        elif args.output.endswith(".svg"):
+            render = md.Mermaid(diagram)
+            render.to_svg(args.output)
+            logger.info(f"SVG diagram written to {args.output}")
+
+        elif args.output.endswith(".png"):
+            render = md.Mermaid(diagram)
+            render.to_png(args.output)
+            logger.info(f"PNG diagram written to {args.output}")
+
+    if not args.no_display:
+        if not render:
+            render = md.Mermaid(diagram)
+
+        html_content = render._repr_html_()
+        # Create a temporary HTML file to display the diagram
+        with tempfile.NamedTemporaryFile(
+            delete=False, suffix=".html"
+        ) as temp_file:
+            temp_file.write(html_content.encode("utf-8"))
+            webbrowser.open(temp_file.name)
+
+
+def parser(subparsers: argparse._SubParsersAction) -> None:
+    """Set up the visualize subcommand parser.
+
+    Args:
+        subparsers: The subparsers object to add the command to.
+    """
+    cmd_parser = subparsers.add_parser(
+        "visualize", help="Visualize a QType Application."
+    )
+    cmd_parser.add_argument(
+        "spec", type=str, help="Path to the QType YAML file."
+    )
+    cmd_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default=None,
+        help="If provided, write the mermaid diagram to this file.",
+    )
+    cmd_parser.add_argument(
+        "-nd",
+        "--no-display",
+        action="store_true",
+        help="If set don't display the diagram in a browser (default: False).",
+    )
+    cmd_parser.set_defaults(func=main)