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

docs/How To/Tools & Integration/create_tools_from_python_modules.md

@@ -0,0 +1,90 @@
+# Create Tools from Python Modules
+
+Generate QType tool definitions automatically from Python functions using `qtype convert module`, which analyzes type hints and docstrings to create properly typed tools.
+
+### Command
+
+```bash
+qtype convert module myapp.utils --output tools.qtype.yaml
+```
+
+### QType YAML
+
+**Input Python module** (`myapp/utils.py`):
+```python
+from datetime import datetime
+
+def calculate_age(birth_date: datetime, reference_date: datetime) -> int:
+    """Calculate age in years between two dates.
+    
+    Args:
+        birth_date: The birth date
+        reference_date: The date to calculate age at
+    
+    Returns:
+        Age in complete years
+    """
+    age = reference_date.year - birth_date.year
+    if (reference_date.month, reference_date.day) < (birth_date.month, birth_date.day):
+        age -= 1
+    return age
+```
+
+**Generated tool YAML** (`tools.qtype.yaml`):
+```yaml
+id: myapp.utils
+description: Tools created from Python module myapp.utils
+tools:
+  - id: myapp.utils.calculate_age
+    description: Calculate age in years between two dates.
+    type: PythonFunctionTool
+    function_name: calculate_age
+    module_path: myapp.utils
+    name: calculate_age
+    inputs:
+      birth_date:
+        type: datetime
+        optional: false
+      reference_date:
+        type: datetime
+        optional: false
+    outputs:
+      result:
+        type: int
+        optional: false
+```
+
+### Explanation
+
+- **`convert module`**: CLI subcommand that converts Python modules to tool definitions
+- **module path**: Dot-separated Python module (e.g., `myapp.utils`, `package.submodule`) - must be importable
+- **`--output`**: Target YAML file path; omit to print to stdout
+- **Type hints**: Required on all parameters and return values; converted to QType types (int, text, datetime, etc.)
+- **Optional parameters**: Detected from default values (e.g., `name: str = "default"` becomes `optional: true`)
+- **Docstrings**: First line becomes tool description; supports Google, NumPy, and reStructuredText formats
+- **Public functions only**: Functions starting with `_` are skipped
+
+### Using Generated Tools
+
+```yaml
+references:
+  - !include tools.qtype.yaml
+
+flows:
+  - id: check_age
+    steps:
+      - type: InvokeTool
+        id: calc
+        tool: myapp.utils.calculate_age
+        input_bindings:
+          birth_date: dob
+          reference_date: today
+        output_bindings:
+          result: age
+```
+
+## See Also
+
+- [Tutorial: Adding Tools to Your Application](../../Tutorials/04-tools-and-function-calling.md)
+- [InvokeTool Reference](../../components/InvokeTool.md)
+- [PythonFunctionTool Reference](../../components/PythonFunctionTool.md)

docs/Reference/cli.md

@@ -0,0 +1,338 @@
+# Command Line Interface
+
+The QType CLI lets you run applications, validate specifications, serve web interfaces, and generating resources.
+
+## Installation
+
+The QType CLI is installed with the qtype package. Run commands with:
+
+```bash
+qtype [command] [options]
+```
+
+## Global Options
+
+```
+--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+    Set the logging level (default: INFO)
+```
+
+## Commands
+
+### run
+
+Execute a QType application locally.
+
+```bash
+qtype run [options] spec
+```
+
+#### Arguments
+
+- **`spec`** - Path to the QType YAML spec file
+
+#### Options
+
+- **`-f FLOW, --flow FLOW`** - The name of the flow to run. If not specified, runs the first flow found
+- **`-i INPUT, --input INPUT`** - JSON blob of input values for the flow (default: `{}`)
+- **`-I INPUT_FILE, --input-file INPUT_FILE`** - Path to a file (e.g., CSV, JSON, Parquet) with input data for batch processing
+- **`-o OUTPUT, --output OUTPUT`** - Path to save output data. If input is a DataFrame, output will be saved as parquet. If single result, saved as JSON
+- **`--progress`** - Show progress bars during flow execution
+
+#### Examples
+
+Run a simple application:
+```bash
+qtype run app.qtype.yaml
+```
+
+Run with inline JSON inputs:
+```bash
+qtype run app.qtype.yaml -i '{"question": "What is AI?"}'
+```
+
+Run a specific flow:
+```bash
+qtype run app.qtype.yaml --flow process_data
+```
+
+Batch process data from a file:
+```bash
+qtype run app.qtype.yaml --input-file inputs.csv --output results.parquet
+```
+
+#### See Also
+
+- [How To: Pass Inputs On The CLI](../How%20To/Command%20Line%20Usage/pass_inputs_on_the_cli.md)
+- [How To: Load Multiple Inputs from Files](../How%20To/Command%20Line%20Usage/load_multiple_inputs_from_files.md)
+- [Tutorial: Your First QType Application](../Tutorials/01-first-qtype-application.md)
+
+---
+
+### validate
+
+Validate a QType YAML spec against the schema and semantic rules.
+
+```bash
+qtype validate [options] spec
+```
+
+#### Arguments
+
+- **`spec`** - Path to the QType YAML spec file
+
+#### Options
+
+- **`-p, --print`** - Print the spec after validation (default: False)
+
+#### Examples
+
+Validate a specification:
+```bash
+qtype validate app.qtype.yaml
+```
+
+Validate and print the parsed spec:
+```bash
+qtype validate app.qtype.yaml --print
+```
+
+#### See Also
+
+- [How To: Validate QType YAML](../How%20To/Observability%20&%20Debugging/validate_qtype_yaml.md)
+- [Reference: Semantic Validation Rules](semantic-validation-rules.md)
+
+---
+
+### serve
+
+Serve a web experience for a QType application with an interactive UI.
+
+```bash
+qtype serve [options] spec
+```
+
+#### Arguments
+
+- **`spec`** - Path to the QType YAML spec file
+
+#### Options
+
+- **`-p PORT, --port PORT`** - Port to run the server on (default: 8080)
+- **`-H HOST, --host HOST`** - Host to bind the server to (default: 0.0.0.0)
+- **`--reload`** - Enable auto-reload on code changes (default: False)
+
+#### Examples
+
+Serve an application:
+```bash
+qtype serve app.qtype.yaml
+```
+
+Serve on a specific port:
+```bash
+qtype serve app.qtype.yaml --port 3000
+```
+
+Serve with auto-reload for development:
+```bash
+qtype serve app.qtype.yaml --reload
+```
+
+#### See Also
+
+- [How To: Serve Flows as APIs](../How%20To/Qtype%20Server/serve_flows_as_apis.md)
+- [How To: Serve Flows as UI](../How%20To/Qtype%20Server/serve_flows_as_ui.md)
+- [How To: Use Conversational Interfaces](../How%20To/Qtype%20Server/use_conversational_interfaces.md)
+- [How To: Serve Applications with Auto-Reload](../How%20To/Qtype%20Server/serve_applications_with_auto_reload.md)
+- [Tutorial: Building a Stateful Chatbot](../Tutorials/02-conversational-chatbot.md)
+
+---
+
+### mcp
+
+Start the QType Model Context Protocol (MCP) server for AI agent integration.
+
+```bash
+qtype mcp [options]
+```
+
+#### Options
+
+- **`-t TRANSPORT, --transport TRANSPORT`** - Transport protocol to use: `stdio`, `sse`, or `streamable-http` (default: stdio)
+- **`--host HOST`** - Host to bind to for HTTP/SSE transports (default: 0.0.0.0)
+- **`-p PORT, --port PORT`** - Port to bind to for HTTP/SSE transports (default: 8000)
+
+#### Examples
+
+Start MCP server with stdio transport (default, for local AI agents):
+```bash
+qtype mcp
+```
+
+Start with Server-Sent Events transport:
+```bash
+qtype mcp --transport sse --port 8000
+```
+
+Start with streamable HTTP transport on a specific host and port:
+```bash
+qtype mcp --transport streamable-http --host 127.0.0.1 --port 3000
+```
+
+#### Description
+
+The MCP server exposes QType functionality to AI agents and assistants through the Model Context Protocol. It provides tools for:
+
+- Converting API specifications to QType tools
+- Converting Python modules to QType tools
+- Validating QType YAML specifications
+- Visualizing QType architectures
+- Accessing QType documentation and component schemas
+
+The stdio transport is ideal for local AI agent integration, while SSE and streamable-http transports are suitable for network-based integrations.
+
+---
+
+### visualize
+
+Generate a visual diagram of your QType application architecture.
+
+```bash
+qtype visualize [options] spec
+```
+
+#### Arguments
+
+- **`spec`** - Path to the QType YAML file
+
+#### Options
+
+- **`-o OUTPUT, --output OUTPUT`** - If provided, write the mermaid diagram to this file
+- **`-nd, --no-display`** - If set, don't display the diagram in a browser (default: False)
+
+#### Examples
+
+Visualize and open in browser:
+```bash
+qtype visualize app.qtype.yaml
+```
+
+Save to file without displaying:
+```bash
+qtype visualize app.qtype.yaml --output diagram.mmd --no-display
+```
+
+Generate and save diagram:
+```bash
+qtype visualize app.qtype.yaml --output architecture.mmd
+```
+
+#### See Also
+
+- [How To: Visualize Application Architecture](../How%20To/Observability%20&%20Debugging/visualize_application_architecture.md)
+
+---
+
+### convert
+
+Create QType tool definitions from external sources.
+
+```bash
+qtype convert {module,api} [options]
+```
+
+#### Subcommands
+
+##### convert module
+
+Convert a Python module to QType tools format.
+
+```bash
+qtype convert module [options] module_path
+```
+
+**Arguments:**
+
+- **`module_path`** - Path to the Python module to convert
+
+**Options:**
+
+- **`-o OUTPUT, --output OUTPUT`** - Output file path. If not specified, prints to stdout
+
+**Examples:**
+
+Convert a Python module:
+```bash
+qtype convert module myapp.utils --output tools.qtype.yaml
+```
+
+Print to stdout:
+```bash
+qtype convert module myapp.utils
+```
+
+**See Also:**
+
+- [How To: Create Tools from Python Modules](../How%20To/Tools%20&%20Integration/create_tools_from_python_modules.md)
+- [Tutorial: Adding Tools to Your Application](../Tutorials/04-tools-and-function-calling.md)
+
+##### convert api
+
+Convert an OpenAPI/Swagger specification to QType format.
+
+```bash
+qtype convert api [options] api_spec
+```
+
+**Arguments:**
+
+- **`api_spec`** - Path to the API specification file (supports local files or URLs)
+
+**Options:**
+
+- **`-o OUTPUT, --output OUTPUT`** - Output file path. If not specified, prints to stdout
+
+**Examples:**
+
+Convert an OpenAPI spec:
+```bash
+qtype convert api spec.oas.yaml --output api_tools.qtype.yaml
+```
+
+Convert from a URL:
+```bash
+qtype convert api https://petstore3.swagger.io/api/v3/openapi.json --output petstore.qtype.yaml
+```
+
+**See Also:**
+
+- [How To: Create Tools from OpenAPI Specifications](../How%20To/Tools%20&%20Integration/create_tools_from_openapi_specifications.md)
+- [Tutorial: Adding Tools to Your Application](../Tutorials/04-tools-and-function-calling.md)
+
+---
+
+### generate
+
+Generate QType project resources (primarily for internal development).
+
+```bash
+qtype generate {commons,schema,dsl-docs,semantic-model} [options]
+```
+
+This command is primarily used for QType development and maintenance.
+
+#### Subcommands
+
+- **`commons`** - Generates the commons library tools from `tools.py`
+- **`schema`** - Generates the JSON schema for the QType DSL from `model.py`
+- **`dsl-docs`** - Generates markdown documentation for the QType DSL classes from `model.py`
+- **`semantic-model`** - Generates the semantic model from QType DSL (See [Contributing](../Contributing/))
+
+---
+
+## Exit Codes
+
+- **0** - Success
+- **1** - Error (validation failure, runtime error, etc.)
+

docs/Reference/plugins.md

@@ -0,0 +1,95 @@
+# Extending QType CLI
+
+QType supports third-party CLI plugins through Python entry points. This allows developers to extend the QType CLI with custom commands without modifying the core codebase.
+
+## Creating a Plugin
+
+### 1. Define Your Command Function
+
+Create a module with a parser function that takes a subparsers object and registers your command:
+
+```python
+# my_package/qtype_commands.py
+import argparse
+
+def my_command_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the 'my-command' subcommand."""
+    parser = subparsers.add_parser(
+        'my-command',
+        help='My custom QType command'
+    )
+    parser.add_argument(
+        '--option',
+        help='An example option'
+    )
+    # Set the function to call when this command is invoked
+    parser.set_defaults(func=my_command_handler)
+
+def my_command_handler(args: argparse.Namespace) -> None:
+    """Handle the 'my-command' subcommand."""
+    print(f"Running my-command with option: {args.option}")
+```
+
+### 2. Register the Entry Point
+
+Add the entry point to your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."qtype.commands"]
+my-command = "my_package.qtype_commands:my_command_parser"
+```
+
+Or if using `setup.py`:
+
+```python
+from setuptools import setup
+
+setup(
+    name="my-qtype-plugin",
+    # ... other setup parameters
+    entry_points={
+        "qtype.commands": [
+            "my-command = my_package.qtype_commands:my_command_parser",
+        ],
+    },
+)
+```
+
+### 3. Install and Test
+
+After installing your package, the command will be automatically available:
+
+```bash
+pip install my-qtype-plugin
+qtype my-command --option "test"
+```
+
+## Best Practices
+
+1. **Naming**: Use descriptive command names and avoid conflicts with built-in commands
+2. **Error Handling**: Handle errors gracefully and provide helpful error messages
+3. **Documentation**: Include help text for your commands and arguments
+4. **Dependencies**: Declare any additional dependencies your plugin requires
+5. **Testing**: Test your plugin with different versions of QType
+
+## Debugging Plugins
+
+To see debug information about plugin loading, run QType with debug logging:
+
+```bash
+qtype --log-level DEBUG my-command
+```
+
+This will show which plugins are being loaded and any errors that occur during the loading process.
+
+## Example Plugin Structure
+
+```
+my-qtype-plugin/
+├── pyproject.toml
+├── my_package/
+│   ├── __init__.py
+│   └── qtype_commands.py
+└── tests/
+    └── test_plugin.py
+```

docs/Reference/semantic-validation-rules.md

@@ -0,0 +1,179 @@
+# Semantic Validation Rules
+
+Semantic validation happens after loading your yaml. You should expect to see these even if the yaml is validated by the spec.
+
+You can validate any qtype file with:
+```
+qtype validate you_file.qtype.yaml
+```
+
+This document lists all semantic validation rules enforced by QType. These rules are checked after YAML parsing and reference resolution.
+
+---
+
+## Agent
+
+- Must have exactly 1 input
+- Must have exactly 1 output
+- Input must be type `text` or `ChatMessage`
+- Output type must match input type
+
+---
+
+## Application
+
+- If using `SecretReference`, must configure `secret_manager`
+- For `AWSSecretManager`, auth must be `AWSAuthProvider`
+
+---
+
+## AWSAuthProvider
+
+- Must specify at least one authentication method:
+  - Access keys (`access_key_id` + `secret_access_key`)
+  - Profile name (`profile_name`)
+  - Role ARN (`role_arn`)
+- If assuming a role, must provide base credentials (access keys or profile)
+
+---
+
+## BedrockReranker
+
+- Must have exactly 2 inputs
+- One input must be type `text` (query)
+- One input must be type `list[SearchResult]` (results to rerank)
+- Must have exactly 1 output of type `list[SearchResult]`
+
+---
+
+## Collect
+
+- Must have exactly 1 input -- any type `T`
+- Must have exactly 1 output of type `list[T]`
+- Output list element type must match input type
+
+---
+
+## Construct
+
+- Must have at least 1 input
+- Must have exactly 1 output
+- Output type must be a Pydantic BaseModel (Custom type or Domain type)
+
+---
+
+## Decoder
+
+- Must have exactly 1 input of type `text`
+- Must have at least 1 output
+
+---
+
+## DocToTextConverter
+
+- Must have exactly 1 input of type `RAGDocument`
+- Must have exactly 1 output of type `RAGDocument`
+
+---
+
+## DocumentEmbedder
+
+- Must have exactly 1 input of type `RAGChunk`
+- Must have exactly 1 output of type `RAGChunk`
+
+---
+
+## DocumentSearch
+
+- Must have exactly 1 input of type `text`
+- Must have exactly 1 output of type `list[SearchResult]`
+
+---
+
+## DocumentSource
+
+- Must have exactly 1 output of type `RAGDocument`
+
+---
+
+## DocumentSplitter
+
+- Must have exactly 1 input of type `RAGDocument`
+- Must have exactly 1 output of type `RAGChunk`
+
+---
+
+## Echo
+
+- Input and output variable IDs must match (order can differ)
+
+---
+
+## Explode
+
+- Must have exactly 1 input of type `list[T]`
+- Must have exactly 1 output of type `T`
+- Output type must match input list element type
+
+---
+
+## FieldExtractor
+
+- Must have exactly 1 input
+- Must have exactly 1 output
+- `json_path` must be non-empty
+
+---
+
+## Flow
+
+**General:**
+- Must have at least 1 step
+- All step inputs must be fulfilled by flow inputs or previous step outputs
+
+**Conversational Interface:**
+- Must have exactly 1 `ChatMessage` input
+- All non-ChatMessage inputs must be listed in `session_inputs`
+- Must have exactly 1 `ChatMessage` output
+
+**Complete Interface:**
+- Must have exactly 1 input of type `text`
+- Must have exactly 1 output of type `text`
+
+---
+
+## IndexUpsert
+
+**For Vector Index:**
+- Must have exactly 1 input
+- Input must be type `RAGChunk` or `RAGDocument`
+
+**For Document Index:**
+- Must have at least 1 input
+
+---
+
+## LLMInference
+
+- Must have exactly 1 output
+- Output must be type `text` or `ChatMessage`
+
+---
+
+## PromptTemplate
+
+- Must have exactly 1 output
+- Output must be type `text`
+
+---
+
+## SQLSource
+
+- Must have at least 1 output
+
+---
+
+## VectorSearch
+
+- Must have exactly 1 input of type `text`
+- Must have exactly 1 output of type `list[RAGSearchResult]`