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

docs/How To/Language Features/reference_entities_by_id.md

@@ -0,0 +1,51 @@
+# Reference Entities by ID
+
+Use QType's "define once, reference by ID" pattern to eliminate duplication and improve maintainability by assigning unique IDs to components and referencing them throughout your application.
+
+### QType YAML
+
+```yaml
+# Define components with unique IDs
+auths:
+  - type: api_key
+    id: openai_auth
+    api_key: ${OPENAI_KEY}
+
+models:
+  - type: Model
+    id: gpt4
+    provider: openai
+    model_id: gpt-4o
+    auth: openai_auth  # Reference auth by ID
+
+memories:
+  - id: conversation_memory
+    token_limit: 10000
+
+flows:
+  - type: Flow
+    id: chat_flow
+    steps:
+      - type: LLMInference
+        model: gpt4             # Reference model by ID
+        memory: conversation_memory  # Reference memory by ID
+```
+
+### Explanation
+
+- **`id` field**: Assigns a unique identifier to any component (models, auths, tools, variables, etc.)
+- **Reference by string**: Use the ID string wherever the component is needed
+- **Automatic resolution**: QType's linker automatically resolves ID references to actual objects during validation
+- **Reusability**: The same component can be referenced multiple times throughout the application
+
+## Complete Example
+
+```yaml
+!include ../../examples/conversational_ai/simple_chatbot.qtype.yaml
+```
+
+## See Also
+
+- [Tutorial: Your First QType Application](../../Tutorials/01-first-qtype-application.md)
+- [Model Reference](../../components/Model.md)
+- [APIKeyAuthProvider Reference](../../components/APIKeyAuthProvider.md)

docs/How To/Language Features/use_environment_variables.md

@@ -0,0 +1,47 @@
+# Use Environment Variables
+
+Keep sensitive credentials and environment-specific configuration out of your YAML files by using environment variable substitution with `${VAR_NAME}` syntax.
+
+### QType YAML
+
+```yaml
+auths:
+  - type: api_key
+    id: openai_auth
+    api_key: ${OPENAI_KEY}        # Required variable
+    host: https://api.openai.com
+
+models:
+  - type: Model
+    id: gpt4
+    provider: openai
+    model_id: ${MODEL_NAME:-gpt-4}  # Optional with default
+    auth: openai_auth
+```
+
+### Explanation
+
+- **`${VAR_NAME}`**: Substitutes the value of environment variable `VAR_NAME`; raises error if not set
+- **`${VAR_NAME:-default}`**: Substitutes the value of `VAR_NAME` or uses `default` if not set
+- **Environment variable resolution**: Happens during YAML loading, before validation and execution
+- **Works everywhere**: Can be used in any string value throughout the YAML specification
+
+## Setting Environment Variables
+
+```bash
+# Export before running
+export OPENAI_KEY="sk-..."
+qtype run app.qtype.yaml
+
+# Or set inline
+OPENAI_KEY="sk-..." uv run qtype run app.qtype.yaml
+
+# Or in a .env file (automatically loaded via the loader)
+echo 'OPENAI_KEY="sk-..."' >> .env
+qtype run app.qtype.yaml
+```
+
+## See Also
+
+- [Tutorial: Your First QType Application](../../Tutorials/01-first-qtype-application.md)
+- [APIKeyAuthProvider Reference](../../components/APIKeyAuthProvider.md)

docs/How To/Language Features/use_qtype_mcp.md

@@ -0,0 +1,59 @@
+# Use QType MCP
+
+QType's Model Context Protocol (MCP) server enables AI assistants like GitHub Copilot to lookup schemas and documentation, validate and visualize qtype files, and convert python modules or apis to tools directly from your AI workflow.
+
+## Command Line Usage
+
+Start the MCP server manually for debugging or other tools:
+
+```bash
+# Stdio transport (for VS Code, Claude Desktop, etc.)
+qtype mcp --transport stdio
+
+# HTTP/SSE transport (for web-based tools)
+qtype mcp --transport sse --host 0.0.0.0 --port 8000
+```
+
+### Transport Options
+
+- **stdio**: Standard input/output (default, for desktop tools)
+- **sse**: Server-Sent Events over HTTP
+- **streamable-http**: HTTP streaming protocol
+
+## Available MCP Tools
+
+The QType MCP server provides these capabilities to AI assistants:
+
+- **convert_api_to_tools**: Convert OpenAPI specs to QType tool definitions
+- **convert_python_to_tools**: Convert Python modules to QType tools
+- **get_component_schema**: Retrieve JSON Schema for any QType component
+- **get_documentation**: Fetch specific documentation files
+- **list_components**: List all available QType component types
+- **list_documentation**: Browse available documentation
+- **validate_qtype_yaml**: Validate QType YAML syntax and semantics
+- **visualize_qtype_architecture**: Generate Mermaid diagrams from QType apps
+
+
+## VS Code Configuration
+
+Add the QType MCP server to your workspace's `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "qtype": {
+      "type": "stdio",
+      "command": "qtype",
+      "cwd": "${workspaceFolder}",
+      "args": ["mcp", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+
+## See Also
+
+- [MCP Server Implementation](../../components/MCP.md)
+- [GitHub Copilot Documentation](https://code.visualstudio.com/docs/copilot/copilot-chat)
+- [Model Context Protocol](https://modelcontextprotocol.io/)

docs/How To/Observability & Debugging/trace_calls_with_open_telemetry.md

@@ -0,0 +1,49 @@
+# Trace Calls with OpenTelemetry
+
+Enable distributed tracing for your QType applications using OpenTelemetry to monitor LLM calls, execution times, and data flow through Phoenix or other observability platforms.
+
+### QType YAML
+
+```yaml
+telemetry:
+  id: phoenix_trace
+  provider: Phoenix
+  endpoint: http://localhost:6006/v1/traces
+```
+
+### Explanation
+
+- **telemetry**: Top-level application configuration for observability
+- **id**: Unique identifier for the telemetry sink
+- **provider**: Telemetry backend (`Phoenix` or `Langfuse`)
+- **endpoint**: URL where OpenTelemetry traces are sent
+
+### Starting Phoenix
+
+Before running your application, start the Phoenix server:
+
+```bash
+python3 -m phoenix.server.main serve
+```
+
+Phoenix will start on `http://localhost:6006` where you can view traces and spans in real-time.
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/observability_debugging/trace_with_opentelemetry.qtype.yaml"
+```
+
+Run the example:
+
+```bash
+qtype run examples/observability_debugging/trace_with_opentelemetry.qtype.yaml --text "I love this product!"
+```
+
+Then open `http://localhost:6006` in your browser to see the traced execution.
+
+## See Also
+
+- [Application Reference](../../components/Application.md)
+- [Validate QType YAML](validate_qtype_yaml.md)
+- [Visualize Application Architecture](visualize_application_architecture.md)

docs/How To/Observability & Debugging/validate_qtype_yaml.md

@@ -0,0 +1,35 @@
+# Validate QType YAML
+
+Check your QType YAML files for syntax errors, schema violations, reference issues, and semantic problems before running them.
+
+### Command Line
+
+```bash
+# Basic validation
+qtype validate path/to/app.qtype.yaml
+
+# Validate and print the parsed document
+qtype validate path/to/app.qtype.yaml --print
+```
+
+### Validation Checks
+
+- **YAML Syntax**: Verifies valid YAML structure and syntax
+- **Schema Validation**: Ensures all fields match the QType schema (Pydantic validation)
+- **Reference Resolution**: Checks that all ID references (models, steps, variables) exist
+- **Duplicate Detection**: Identifies duplicate component IDs
+- **Semantic Validation**: Validates flow logic, type compatibility, and business rules
+
+### Options
+
+- **`--print` / `-p`**: Print the validated document with resolved references and defaults applied
+
+### Exit Codes
+
+- **0**: Validation successful
+- **1**: Validation failed (error details printed to stderr)
+
+## See Also
+
+- [Application Reference](../../components/Application.md)
+- [Semantic Validation Rules](../../Concepts/semantic_validation_rules.md)

docs/How To/Observability & Debugging/visualize_application_architecture.md

@@ -0,0 +1,61 @@
+# Visualize Application Architecture
+
+Generate interactive diagrams showing your application's flows, steps, and data dependencies to understand structure and debug issues.
+
+## Example Visualization
+
+Here's what a visualization looks like for a conversational chatbot application:
+
+```mermaid
+--8<-- "How To/Observability & Debugging/visualize_example.mermaid"
+```
+
+This diagram shows:
+
+- **Flow structure**: The conversational flow with its interface and steps
+- **Data flow**: How variables (user_message, context, response) flow between steps
+- **Shared resources**: The LLM model and memory used by the application
+- **Step types**: Different icons for templates (📄), LLM inference (✨), and other components
+
+## Command Line
+
+```bash
+# Generate and open diagram in browser
+qtype visualize path/to/app.qtype.yaml
+
+# Save Mermaid diagram to file
+qtype visualize path/to/app.qtype.yaml --output diagram.mmd
+
+# Save without opening browser
+qtype visualize path/to/app.qtype.yaml --output diagram.mmd --no-display
+```
+
+## Prerequisites
+
+Visualization requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli) to be installed:
+
+```bash
+npm install -g @mermaid-js/mermaid-cli
+```
+
+## How It Works
+
+- **Generates Mermaid diagram**: Creates a flowchart showing flows, steps, and variable connections
+- **Converts to SVG**: Uses `mmdc` to render the diagram as a scalable vector graphic
+- **Opens in browser**: Displays the interactive diagram automatically (unless `--no-display` is set)
+
+## Options
+
+- **`--output` / `-o`**: Save the Mermaid diagram source to a file (`.mmd` format)
+- **`--no-display` / `-nd`**: Skip opening the diagram in browser (useful for CI/CD)
+
+## Exit Codes
+
+- **0**: Visualization successful
+- **1**: Visualization failed (invalid YAML or missing mmdc)
+
+## See Also
+
+- [Validate QType YAML](validate_qtype_yaml.md)
+- [Application Reference](../../components/Application.md)
+- [Flow Reference](../../components/Flow.md)

docs/How To/Observability & Debugging/visualize_example.mermaid

@@ -0,0 +1,35 @@
+flowchart TD
+    subgraph APP ["📱 simple_chatbot"]
+        direction TB
+
+    subgraph FLOW_0 ["🔄 chat_flow"]
+        direction LR
+        FLOW_0_START@{shape: circle, label: "▶️ Start"}
+        FLOW_0_S0@{shape: rounded, label: "✨ generate_response"}
+        FLOW_0_START -->|user_message| FLOW_0_S0
+    end
+
+    subgraph RESOURCES ["🔧 Shared Resources"]
+        direction LR
+        MODEL_NOVA_LITE@{shape: rounded, label: "✨ nova_lite (aws-bedrock)" }
+        MEM_CONVERSATION_MEMORY@{shape: win-pane, label: "🧠 conversation_memory (10KT)"}
+    end
+
+    end
+
+    FLOW_0_S0 -.->|uses| MODEL_NOVA_LITE
+    FLOW_0_S0 -.->|stores| MEM_CONVERSATION_MEMORY
+
+    %% Styling
+    classDef appBox fill:none,stroke:#495057,stroke-width:3px
+    classDef flowBox fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
+    classDef llmNode fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
+    classDef modelNode fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
+    classDef authNode fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
+    classDef telemetryNode fill:#fce4ec,stroke:#c2185b,stroke-width:2px
+    classDef resourceBox fill:#f5f5f5,stroke:#616161,stroke-width:1px
+
+    class APP appBox
+    class FLOW_0 flowBox
+    class RESOURCES resourceBox
+    class TELEMETRY telemetryNode

docs/How To/Qtype Server/serve_flows_as_apis.md

@@ -0,0 +1,40 @@
+# Serve Flows as APIs
+
+Expose your QType flows as HTTP REST endpoints with automatically generated OpenAPI documentation using the `qtype serve` command.
+
+### Command
+
+```bash
+qtype serve <file.qtype.yaml> [--host HOST] [--port PORT] [--reload]
+```
+
+### Explanation
+
+- **Swagger UI**: Interactive API documentation available at `http://localhost:8000/docs`
+- **ReDoc**: Alternative API documentation at `http://localhost:8000/redoc`
+- **REST Endpoints**: Each flow is available at `POST /invoke/{flow_id}`
+- **Streaming Endpoints**: Flows with UI interfaces get `POST /stream/{flow_id}` for Server-Sent Events
+- **Interactive UI**: Web interface at `http://localhost:8000/ui` (redirects from root)
+- **--reload**: Auto-reload on file changes during development
+- **--host/--port**: Override default host (localhost) and port (8000)
+
+### Example
+
+```bash
+qtype serve examples/tutorials/01_hello_world.qtype.yaml
+```
+
+Then visit `http://localhost:8000/docs` to explore and test your API endpoints.
+
+### Available Endpoints
+
+- **`GET /flows`**: List all flows with metadata (inputs, outputs, interface type)
+- **`POST /flows/{flow_id}`**: Execute a specific flow (e.g., `POST /flows/simple_example`)
+
+Each flow endpoint accepts JSON input matching the flow's input schema and returns structured results with `outputs` and `errors` arrays.
+
+## See Also
+
+- [Application Reference](../../components/Application.md)
+- [Flow Reference](../../components/Flow.md)
+- [FlowInterface Reference](../../components/FlowInterface.md)

docs/How To/Qtype Server/serve_flows_as_ui.md

@@ -0,0 +1,42 @@
+# Serve Flows as UI
+
+Expose your QType flows through an interactive web interface using the `qtype serve` command.
+
+### Command
+
+```bash
+qtype serve <file.qtype.yaml> [--host HOST] [--port PORT] [--reload]
+```
+
+### Explanation
+
+- **Interactive UI**: Web interface at `http://localhost:8000/ui` (redirects from root `/`)
+- **Complete Flows**: Display as forms with input fields and output display
+- **Conversational Flows**: Display as chat interfaces with message history
+- **Auto-generated**: UI is automatically created based on flow inputs/outputs
+- **--reload**: Auto-reload on file changes during development
+- **--host/--port**: Override default host (localhost) and port (8000)
+
+### Example
+
+```bash
+qtype serve examples/tutorials/01_hello_world.qtype.yaml
+```
+
+Then visit `http://localhost:8000/ui` to interact with your flow through the web interface.
+
+![Flow UI Screenshot](flow_as_ui.png)
+
+The UI automatically generates:
+
+- Input fields based on variable types
+- Submit button to execute the flow
+- Output display for results
+- Error messages if execution fails
+
+## See Also
+
+- [Serve Flows as APIs](serve_flows_as_apis.md)
+- [Flow Reference](../../components/Flow.md)
+- [FlowInterface Reference](../../components/FlowInterface.md)
+- [Tutorial: Build a Conversational Chatbot](../../Tutorials/02-conversational-chatbot.md)

docs/How To/Qtype Server/use_conversational_interfaces.md

@@ -0,0 +1,59 @@
+# 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: Build a Conversational Chatbot](../../Tutorials/02-conversational-chatbot.md)
+- [Flow Reference](../../components/Flow.md)
+- [FlowInterface Reference](../../components/FlowInterface.md)
+- [ChatMessage Reference](../../components/ChatMessage.md)
+- [Memory Concept](../../Concepts/Core/memory.md)

docs/How To/Qtype Server/use_variables_with_ui_hints.md

@@ -0,0 +1,47 @@
+# 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](../../How%20To/Qtype%20Server/serve_flows_as_ui.md)
+- [Flow Reference](../../components/Flow.md)

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

@@ -0,0 +1,48 @@
+# 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: Adding Tools to Your Application](../../Tutorials/04-tools-and-function-calling.md)
+- [InvokeTool Reference](../../components/InvokeTool.md)
+- [Create Tools from Python Modules](create_tools_from_python_modules.md)
+- [Create Tools from OpenAPI Specifications](create_tools_from_openapi_specifications.md)

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

@@ -0,0 +1,89 @@
+# 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
+    parameters:
+      petId:
+        type: int
+        optional: false
+    outputs:
+      id:
+        type: int
+        optional: true
+      name:
+        type: text
+        optional: false
+      status:
+        type: text
+        optional: true
+```
+
+### 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: Adding Tools to Your Application](../../Tutorials/04-tools-and-function-calling.md)
+- [How-To: Create Tools from Python Modules](create_tools_from_python_modules.md)
+- [InvokeTool Reference](../../components/InvokeTool.md)
+- [APITool Reference](../../components/APITool.md)