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

qtype/docs/How To/Invoke Models/create_embeddings.md

@@ -0,0 +1,49 @@
+# Create Embeddings
+
+Generate vector embeddings from text using an embedding model, useful for semantic search, similarity comparisons, and RAG applications.
+
+### QType YAML
+
+```yaml
+models:
+  - type: EmbeddingModel
+    id: titan_embed
+    provider: aws-bedrock
+    model_id: amazon.titan-embed-text-v2:0
+    dimensions: 1024
+
+flows:
+  - type: Flow
+    id: main
+    steps:
+      - type: InvokeEmbedding
+        id: embed_text
+        model: titan_embed
+        inputs: [text]
+        outputs: [embedding]
+```
+
+### Explanation
+
+- **EmbeddingModel**: Defines an embedding model configuration with provider and dimensions
+- **dimensions**: Size of the embedding vector (must match model output, e.g., 1024 for Titan v2)
+- **InvokeEmbedding**: Step type that generates embeddings from input text
+- **Embedding**: Output type containing the vector array and metadata
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/invoke_models/create_embeddings.qtype.yaml"
+```
+
+Run with:
+```bash
+qtype run examples/invoke_models/create_embeddings.qtype.yaml \
+  -i '{"text": "Your text here"}'
+```
+
+## See Also
+
+- [InvokeEmbedding Reference](../../components/InvokeEmbedding.md)
+- [EmbeddingModel Reference](../../components/EmbeddingModel.md)
+- [Embedding Reference](../../components/Embedding.md)

qtype/docs/How To/Invoke Models/reuse_prompts_with_templates.md

@@ -0,0 +1,38 @@
+# Reuse Prompts with Templates
+
+Define reusable prompt templates with variable placeholders using the `PromptTemplate` step, enabling consistent prompt formatting and dynamic content substitution.
+
+### QType YAML
+
+```yaml
+steps:
+  - id: create_prompt
+    type: PromptTemplate
+    template: |
+      Analyze this product review in 1-2 sentences. Include:
+      - Overall sentiment (positive/negative/mixed)
+      - Key themes or points
+
+      Product: {product_name}
+      Rating: {rating}/5
+      Review: {review_text}
+    inputs:
+      - product_name
+      - rating
+      - review_text
+    outputs:
+      - analysis_prompt
+```
+
+### Explanation
+
+- **type: PromptTemplate**: Step that formats strings with variable placeholders using Python's `str.format()` syntax
+- **template**: String with `{variable_name}` placeholders that get replaced with actual values from inputs
+- **inputs**: Variables whose values will be substituted into the template placeholders
+- **outputs**: Single variable containing the formatted prompt string ready for LLM inference
+
+## See Also
+
+- [PromptTemplate Reference](../../components/PromptTemplate.md)
+- [Include Raw Text from Other Files](../Language%20Features/include_raw_text_from_other_files.md)
+- [Call Large Language Models](call_large_language_models.md)

qtype/docs/How To/Language Features/include_qtype_yaml.md

@@ -0,0 +1,45 @@
+# Include QType YAML
+
+Organize QType applications into reusable modules by including external YAML files using the `!include` directive, allowing you to share models, tools, authentication providers, and other resources across multiple applications.
+
+### QType YAML
+
+```yaml
+id: my_app
+
+# Include shared resources from other files
+references:
+  - !include common/auth.qtype.yaml
+  - !include common/models.qtype.yaml
+  - !include common/tools.qtype.yaml
+
+flows:
+  - id: main_flow
+    steps:
+      - type: LLMInference
+        id: generate
+        model: shared_gpt4        # References model from included file
+        prompt: "Generate a summary"
+```
+
+**common/models.qtype.yaml:**
+```yaml
+- id: shared_gpt4
+  type: Model
+  provider: openai
+  model_id: gpt-4
+  auth: shared_openai_auth
+```
+
+### Explanation
+
+- **!include**: YAML tag that loads and parses external YAML files, merging their content into the current specification
+- **Relative paths**: File paths are resolved relative to the including YAML file's location
+- **Nested includes**: Included files can include other files, creating a hierarchy of modular components
+- **Remote includes**: Supports URLs (e.g., `!include https://example.com/config.yaml`) via fsspec
+
+## See Also
+
+- [Reference Entities by ID](reference_entities_by_id.md)
+- [Include Raw Text from Other Files](include_raw_text_from_other_files.md)
+- [Application Reference](../../components/Application.md)

qtype/docs/How To/Language Features/include_raw_text_from_other_files.md

@@ -0,0 +1,48 @@
+# Include Raw Text from Other Files
+
+Load external text files into your YAML configuration using the `!include_raw` directive, useful for keeping prompts, templates, and long text content in separate files.
+
+### QType YAML
+
+```yaml
+steps:
+  - id: generate_story
+    type: PromptTemplate
+    template: !include_raw story_prompt.txt
+    inputs:
+      - theme
+      - tone
+    outputs:
+      - story
+```
+
+**story_prompt.txt:**
+```txt
+--8<-- "../examples/language_features/story_prompt.txt"
+```
+
+### Explanation
+
+- **!include_raw**: YAML tag that loads the contents of an external file as a raw string
+- **Relative paths**: File paths are resolved relative to the YAML file's location
+- **Template substitution**: The loaded text can contain variable placeholders (e.g., `{theme}`, `{tone}`) that are substituted at runtime
+- **Use cases**: Prompt templates, system messages, documentation, or any text content you want to manage separately
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/language_features/include_raw.qtype.yaml"
+```
+
+
+
+**Run it:**
+```bash
+qtype run include_raw.qtype.yaml -i '{"theme":"a robot learning to paint","tone":"inspirational"}'
+```
+
+## See Also
+
+- [PromptTemplate Reference](../../components/PromptTemplate.md)
+- [Include QType YAML](include_qtype_yaml.md)
+- [Reuse Prompts with Templates](../Invoke%20Models/reuse_prompts_with_templates.md)

qtype/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
+
+- [Include QType YAML](include_qtype_yaml.md)
+- [Tutorial: Your First QType Application](../../Tutorials/01-first-qtype-application.md)
+- [Application Reference](../../components/Application.md)

qtype/docs/How To/Language Features/use_agent_skills.md

@@ -0,0 +1,29 @@
+# Use QType Agent Skills
+
+Enhance GitHub Copilot or Claude Code with domain-specific QType expertise by loading pre-built agent skills that help you architect your vision faster.
+
+**Requires:** Active `qtype-mcp` MCP server
+
+### Generate Skills
+
+Simply:
+```
+qtype generate skills
+```
+
+and the skills will be written `.claude` for you.
+
+## Available QType Skills
+
+### QType Architect
+
+Expert assistant for designing and building AI applications using QType's declarative YAML language.
+
+**Capabilities:**
+- Designs flows from requirements to implementation
+- Generates architecture visualizations in VSCode
+
+## See Also
+
+- [Use QType MCP](use_qtype_mcp.md)
+- [Invoke Other Flows](../Data%20Processing/invoke_other_flows.md)

qtype/docs/How To/Language Features/use_environment_variables.md

@@ -0,0 +1,48 @@
+# 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
+
+- [Use API Key Authentication](../Authentication/use_api_key_authentication.md)
+- [Configure AWS Authentication](../Authentication/configure_aws_authentication.md)
+- [Tutorial: Your First QType Application](../../Tutorials/01-first-qtype-application.md)

qtype/docs/How To/Language Features/use_optional_variables.md

@@ -0,0 +1,42 @@
+# Use Optional Variables
+
+Mark variables as optional to handle cases where data may be missing or unset, allowing your flow to continue gracefully instead of failing.
+
+### QType YAML
+
+```yaml
+variables:
+  - id: email
+    type: text?           # Optional text variable
+```
+
+### Explanation
+
+- **`?` suffix**: Shorthand syntax to mark a variable as optional
+- **Optional variables**: Can be `None` or set to a value
+- **FieldExtractor**: Returns `None` for optional output variables when JSONPath finds no matches, instead of raising an error. If you make the variable non-optional, it will raise an error.
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/language_features/optional_variables.qtype.yaml"
+```
+
+**Run it:**
+```bash
+# When email field exists
+qtype run examples/language_features/optional_variables.qtype.yaml -i '{"user_profile": {"email":"hello@domain.com"}}'
+# Results:                                                                                          
+# email: hello@domain.com
+
+# When email field is missing
+qtype run examples/language_features/optional_variables.qtype.yaml -i '{"user_profile": "just text"}'
+# Results:                                                                                          
+# email: None  
+```
+
+## See Also
+
+- [Variable Reference](../../components/Variable.md)
+- [FieldExtractor Reference](../../components/FieldExtractor.md)
+- [Tutorial: Structured Data](../../Tutorials/03-structured-data.md)

qtype/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-mcp": {
+      "type": "stdio",
+      "command": "qtype",
+      "cwd": "${workspaceFolder}",
+      "args": ["mcp", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+
+## See Also
+
+- [Use QType Agent Skills](use_agent_skills.md)
+- [Validate QType YAML](../Observability%20%26%20Debugging/validate_qtype_yaml.md)
+- [Visualize Application Architecture](../Observability%20%26%20Debugging/visualize_application_architecture.md)

qtype/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)
+- [CLI Reference](../../Reference/cli.md)

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

@@ -0,0 +1,36 @@
+# 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
+
+- [CLI Reference](../../Reference/cli.md)
+- [Semantic Validation Rules](../../Reference/semantic-validation-rules.md)
+- [Visualize Application Architecture](visualize_application_architecture.md)

qtype/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)
+- [CLI Reference](../../Reference/cli.md)
+- [Flow Reference](../../components/Flow.md)

qtype/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

qtype/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
+
+- [Serve Flows as UI](serve_flows_as_ui.md)
+- [CLI Reference](../../Reference/cli.md)
+- [Serve with Auto-Reload](../Command%20Line%20Usage/serve_with_auto_reload.md)

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

@@ -0,0 +1,41 @@
+# 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)
+- [Use Conversational Interfaces](use_conversational_interfaces.md)
+- [Tutorial: Conversational Chatbot](../../Tutorials/02-conversational-chatbot.md)