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

qtype/docs/How To/Qtype Server/use_conversational_interfaces.md

@@ -0,0 +1,56 @@
+# Use Conversational Interfaces
+
+The `Conversational` interface tells the QType UI to render a chat instead of just an "execute flow" button.
+
+Note that, if you set the interface to Conversational, QType will validate that the input and outputs are of type `ChatMessage`. If you set the interface to Conversational and this is not true, and error will be thrown.
+
+### QType YAML
+
+```yaml
+flows:
+  - type: Flow
+    id: simple_chat_example
+    interface:
+      type: Conversational
+    variables:
+      - id: user_message
+        type: ChatMessage
+      - id: response_message
+        type: ChatMessage
+    inputs:
+      - user_message
+    outputs:
+      - response_message
+```
+
+### Web UI
+
+When you serve a conversational flow with `qtype serve`, the UI renders a chat interface:
+
+![Chat interface showing conversation with memory](../../Tutorials/example_chat.png)
+
+
+### Explanation
+
+- **interface.type: Conversational**: Configures the flow to be served as a chat interface in the web UI rather than a simple form
+- **ChatMessage type**: Domain type that structures messages with content blocks, role metadata, and conversation context
+- **Reset on refresh**: Starting a new browser session creates a new conversation with fresh memory
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/tutorials/02_conversational_chat.qtype.yaml"
+```
+
+**Start the chat interface:**
+```bash
+qtype serve 02_conversational_chat.qtype.yaml
+```
+
+Visit [http://localhost:8000/ui](http://localhost:8000/ui) to interact with the chatbot.
+
+## See Also
+
+- [Serve Flows as UI](serve_flows_as_ui.md)
+- [Tutorial: Conversational Chatbot](../../Tutorials/02-conversational-chatbot.md)
+- [ChatMessage Reference](../../components/ChatMessage.md)

qtype/docs/How To/Qtype Server/use_variables_with_ui_hints.md

@@ -0,0 +1,48 @@
+# Use Variables with UI Hints
+
+Customize how input variables are displayed in the web UI using the `ui` field on variable definitions.
+
+### QType YAML
+
+```yaml
+flows:
+  - type: Flow
+    id: generate_story
+    
+    variables:
+      # Use textarea widget for multi-line text input
+      - id: story_prompt
+        type: text
+        ui:
+          widget: textarea
+      
+      # Use file upload widget with mime type filtering
+      - id: document
+        type: file
+        ui:
+          accept: "application/pdf"
+      
+      # Variables without ui hints use default widgets
+      - id: max_length
+        type: int
+```
+
+### Explanation
+
+- **ui.widget**: For `text` variables, controls input style (`text` for single-line, `textarea` for multi-line)
+- **ui.accept**: For `file` variables, specifies accepted mime types (e.g., `"application/pdf"`, `"image/*"`, `"*/*"`)
+- **Default widgets**: Variables without `ui` hints automatically use appropriate widgets based on their type
+
+**Note**: UI hints are currently limited to text and file input customization. Other variable types use standard widgets.
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/language_features/ui_hints.qtype.yaml"
+```
+
+## See Also
+
+- [Serve Flows as UI](serve_flows_as_ui.md)
+- [Variable Reference](../../components/Variable.md)
+- [Use Optional Variables](../Language%20Features/use_optional_variables.md)

qtype/docs/How To/Tools & Integration/bind_tool_inputs_and_outputs.md

@@ -0,0 +1,47 @@
+# Bind Tool Inputs and Outputs
+
+Map flow variables to tool parameters and capture tool results using `input_bindings` and `output_bindings` in the InvokeTool step.
+
+### QType YAML
+
+```yaml
+steps:
+  # Tool with no inputs, only output binding
+  - type: InvokeTool
+    id: get_current_time
+    tool: qtype.application.commons.tools.get_current_timestamp
+    input_bindings: {}
+    output_bindings:
+      result: current_time
+    outputs: [current_time]
+
+  # Tool with multiple input bindings
+  - type: InvokeTool
+    id: add_days
+    tool: qtype.application.commons.tools.timedelta
+    input_bindings:
+      timestamp: current_time      # Tool param ← flow variable
+      days: days_until_due          # Tool param ← flow variable
+    output_bindings:
+      result: deadline_time         # Tool output → flow variable
+    outputs: [deadline_time]
+```
+
+### Explanation
+
+- **input_bindings**: Maps tool parameter names (left) to flow variable names (right)
+- **output_bindings**: Maps tool output names (left) to flow variable names (right)
+- **outputs**: Lists flow variables this step produces (must match output_bindings values)
+- **Chaining**: Output variables from one tool become input variables for the next tool
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/tutorials/04_tools_and_function_calling.qtype.yaml"
+```
+
+## See Also
+
+- [Tutorial: Tools and Function Calling](../../Tutorials/04-tools-and-function-calling.md)
+- [InvokeTool Reference](../../components/InvokeTool.md)
+- [Create Tools from Python Modules](create_tools_from_python_modules.md)

qtype/docs/How To/Tools & Integration/create_tools_from_openapi_specifications.md

@@ -0,0 +1,85 @@
+# Create Tools from OpenAPI Specifications
+
+Generate QType tool definitions automatically from OpenAPI/Swagger specifications using `qtype convert api`, which parses API endpoints, parameters, and schemas to create properly typed API tools.
+
+### Command
+
+```bash
+# Convert from a URL (or use a local file path)
+qtype convert api https://petstore3.swagger.io/api/v3/openapi.json --output petstore_tools.qtype.yaml
+```
+
+This creates the `petstore_tools.qtype.yaml` qtype file you can import into your application.
+
+### QType YAML
+
+**Generated tool YAML** (`petstore_tools.qtype.yaml`):
+```yaml
+id: swagger-petstore---openapi-30
+description: Tools created from API specification petstore_api.json
+
+auths:
+  - id: swagger-petstore---openapi-30_api_key_api_key
+    type: api_key
+    api_key: your_api_key_here
+
+tools:
+  - id: getPetById
+    name: Find pet by ID.
+    description: Returns a single pet.
+    type: APITool
+    method: GET
+    endpoint: /api/v3/pet/{petId}
+    auth: swagger-petstore---openapi-30_api_key_api_key
+    inputs:
+      - id: petId
+        type: int
+    outputs:
+      - id: id
+        type: int?
+      - id: name
+        type: text
+      - id: status
+        type: text?
+    parameters: []
+```
+
+### Explanation
+
+- **`convert api`**: CLI subcommand that converts OpenAPI specifications to tool definitions
+- **OpenAPI spec**: JSON or YAML file following OpenAPI 3.0+ or Swagger 2.0 format
+- **`--output`**: Target YAML file path; omit to print to stdout
+- **operationId**: Becomes the tool ID (e.g., `getPetById`)
+- **parameters**: Path, query, and header parameters become tool `parameters`
+- **responses**: Response schema properties become tool `outputs`
+- **servers**: Base URL is combined with path to create full endpoint
+- **method**: HTTP method (GET, POST, PUT, DELETE, etc.)
+- **securitySchemes**: Generates auth providers (API key, OAuth2, Bearer token)
+
+### Using Generated Tools
+
+```yaml
+references:
+  - !include petstore_tools.qtype.yaml
+
+flows:
+  - id: fetch_pet
+    steps:
+      - type: InvokeTool
+        id: get_pet
+        tool: getPetById
+        input_bindings:
+          petId: pet_id
+        output_bindings:
+          name: pet_name
+          status: pet_status
+```
+
+See [Tutorial: Adding Tools to Your Application](../../Tutorials/04-tools-and-function-calling.md) for a detailed usage.
+
+
+## See Also
+
+- [Tutorial: Tools and Function Calling](../../Tutorials/04-tools-and-function-calling.md)
+- [Create Tools from Python Modules](create_tools_from_python_modules.md)
+- [APITool Reference](../../components/APITool.md)

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

@@ -0,0 +1,87 @@
+# 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:
+      - id: birth_date
+        type: datetime
+      - id: reference_date
+        type: datetime
+    outputs:
+      - id: calculate_age_result
+        type: int
+```
+
+### 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: Tools and Function Calling](../../Tutorials/04-tools-and-function-calling.md)
+- [Create Tools from OpenAPI Specifications](create_tools_from_openapi_specifications.md)
+- [PythonFunctionTool Reference](../../components/PythonFunctionTool.md)

qtype/docs/Reference/cli.md

@@ -0,0 +1,336 @@
+# 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
+
+- [Pass Inputs On The CLI](../How%20To/Command%20Line%20Usage/pass_inputs_on_the_cli.md)
+- [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
+
+- [Validate QType YAML](../How%20To/Observability%20%26%20Debugging/validate_qtype_yaml.md)
+- [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
+
+- [Serve Flows as APIs](../How%20To/Qtype%20Server/serve_flows_as_apis.md)
+- [Serve Flows as UI](../How%20To/Qtype%20Server/serve_flows_as_ui.md)
+- [Tutorial: Conversational 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
+
+- [Visualize Application Architecture](../How%20To/Observability%20%26%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:**
+
+- [Create Tools from Python Modules](../How%20To/Tools%20%26%20Integration/create_tools_from_python_modules.md)
+- [Tutorial: Tools and Function Calling](../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:**
+
+- [Create Tools from OpenAPI Specifications](../How%20To/Tools%20%26%20Integration/create_tools_from_openapi_specifications.md)
+- [Tutorial: Tools and Function Calling](../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/index.md))
+
+---
+
+## Exit Codes
+
+- **0** - Success
+- **1** - Error (validation failure, runtime error, etc.)
+