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

{docs → qtype/docs}/Gallery/research_assistant.md

@@ -59,7 +59,7 @@ qtype validate examples/research_assistant/research_assistant.qtype.yaml
 
 # Run directly
 qtype run -i '{"topic":"Latest developments in retrieval augmented generation"}' \
-  examples/research_assistant/research_assistant.qtype.yaml
+  --show-output examples/research_assistant/research_assistant.qtype.yaml
 ```
 
 ### Example Output
@@ -92,7 +92,6 @@ When running with the topic "Latest developments in retrieval augmented generati
 
 ## Learn More
 
-- How-To: [Create Tools from OpenAPI Specifications](../How%20To/Tools%20%26%20Integration/create_tools_from_openapi_specifications.md)
-- How-To: [Bind Tool Inputs and Outputs](../How%20To/Tools%20%26%20Integration/bind_tool_inputs_and_outputs.md)
-- How-To: [Include QType YAML](../How%20To/Language%20Features/include_qtype_yaml.md)
-- How-To: [Call Large Language Models](../How%20To/Invoke%20Models/call_large_language_models.md)
+- [Create Tools from OpenAPI Specifications](../How%20To/Tools%20%26%20Integration/create_tools_from_openapi_specifications.md)
+- [Bind Tool Inputs and Outputs](../How%20To/Tools%20%26%20Integration/bind_tool_inputs_and_outputs.md)
+- [Call Large Language Models](../How%20To/Invoke%20Models/call_large_language_models.md)

{docs → qtype/docs}/Gallery/simple_chatbot.md

@@ -33,4 +33,6 @@ qtype serve examples/conversational_ai/simple_chatbot.qtype.yaml
 
 ## Learn More
 
-- Tutorial: [Building a Stateful Chatbot](../../Tutorials/02_conversational_chat.md)
+- [Tutorial: Conversational Chatbot](../Tutorials/02-conversational-chatbot.md)
+- [Use Conversational Interfaces](../How%20To/Qtype%20Server/use_conversational_interfaces.md)
+- [ChatMessage Reference](../components/ChatMessage.md)

{docs → qtype/docs}/How To/Authentication/configure_aws_authentication.md

@@ -55,6 +55,6 @@ models:
 ## See Also
 
 - [AWSAuthProvider Reference](../../components/AWSAuthProvider.md)
+- [Use API Key Authentication](use_api_key_authentication.md)
+- [Call Large Language Models](../Invoke%20Models/call_large_language_models.md)
 - [Model Reference](../../components/Model.md)
-- [How-To: Use API Key Authentication](use_api_key_authentication.md)
-- [How-To: Manage Secrets with Secret Manager](../Authentication/manage_secrets.md)

{docs → qtype/docs}/How To/Authentication/use_api_key_authentication.md

@@ -36,5 +36,5 @@ models:
 
 - [APIKeyAuthProvider Reference](../../components/APIKeyAuthProvider.md)
 - [Use Environment Variables](../Language%20Features/use_environment_variables.md)
-- [Model Reference](../../components/Model.md)
-- [Tutorial: Your First QType Application](../../Tutorials/your_first_qtype_application.md)
+- [Configure AWS Authentication](configure_aws_authentication.md)
+- [Tutorial: Your First QType Application](../../Tutorials/01-first-qtype-application.md)

{docs → qtype/docs}/How To/Command Line Usage/load_multiple_inputs_from_files.md

@@ -10,8 +10,8 @@ qtype run app.qtype.yaml --input-file inputs.csv
 
 ### Supported File Formats
 
-- **CSV**: Columns map to input variable names
-- **JSON**: Array of objects or records format
+- **CSV**: Columns map to input variable names (best for primitive types)
+- **JSON**: Array of objects or records format (best for nested/complex types)
 - **Parquet**: Efficient columnar format for large datasets
 - **Excel**: `.xlsx` or `.xls` files
 
@@ -19,10 +19,25 @@ qtype run app.qtype.yaml --input-file inputs.csv
 
 When you provide `--input-file`, QType:
 1. Reads the file into a pandas DataFrame
-2. Each row becomes one execution of the flow
-3. Column names must match flow input variable IDs
-4. Processes rows with configured concurrency
-5. Returns results as a DataFrame (can be saved with `--output`)
+2. Automatically converts data to match input variable types
+3. Each row becomes one execution of the flow
+4. Column names must match flow input variable IDs
+5. Processes rows with configured concurrency
+6. Returns results as a DataFrame (can be saved with `--output`)
+
+### Type Conversion
+
+QType automatically converts file data to match your flow's input types:
+
+- **Primitive types** (`int`, `float`, `bool`, `text`): Converted from file values
+- **Custom types**: Validated and instantiated from dict/object columns (use JSON format)
+- **Domain types**: Built-in types like `ChatMessage` or `SearchResult` (use JSON format)
+
+**Format Selection Guide:**
+
+- Use **CSV** for simple data with primitive types (strings, numbers, booleans)
+- Use **JSON** for complex data with custom types, nested objects, or domain types
+- Use **Parquet** for large datasets with mixed types and efficient storage
 
 ## Complete Example
 
@@ -57,6 +72,6 @@ qtype run batch_processing.qtype.yaml \
 
 ## See Also
 
-<!-- - [Adjust Concurrency](adjust_concurrency.md) -->
-<!-- - [FileSource Reference](../../components/FileSource.md) -->
-- [Example: Dataflow Pipeline](../../Gallery/Data%20Processing/dataflow_pipelines.md)
+- [Pass Inputs On The CLI](pass_inputs_on_the_cli.md)
+- [Adjust Concurrency](../Data%20Processing/adjust_concurrency.md)
+- [Gallery: Dataflow Pipelines](../../Gallery/dataflow_pipelines.md)

{docs → qtype/docs}/How To/Command Line Usage/pass_inputs_on_the_cli.md

@@ -2,6 +2,8 @@
 
 Provide input values to your QType flows directly from the command line using JSON-formatted input data, enabling dynamic parameterization of applications without modifying YAML files.
 
+**Note:** Inputs are optional. Flows with source steps (like `DocumentSource` or `SQLSource`) can run without any inputs, as these steps generate their own data.
+
 ### CLI Usage
 
 ```bash
@@ -20,10 +22,11 @@ qtype run -f analyze_data -i '{"threshold":0.85}' app.qtype.yaml
 
 ### Explanation
 
-- **`-i`, `--input`**: Accepts a JSON blob containing key-value pairs where keys match variable names declared in your flow's `inputs` field
+- **`-i`, `--input`**: Accepts a JSON blob containing key-value pairs where keys match variable names declared in your flow's `inputs` field (optional - omit for flows with source steps)
 - **JSON format**: Must be valid JSON with double quotes for strings, properly escaped special characters
 - **Flow inputs**: The variables must match those declared in the flow's `inputs` list or the application's `inputs` list
 - **`-f`, `--flow`**: Specifies which flow to run when your application contains multiple flows (defaults to first flow if omitted)
+- **Source steps**: Flows containing source steps like `DocumentSource`, `SQLSource`, or `FileSource` can run without inputs, as these steps generate data independently
 
 ## Complete Example
 
@@ -47,6 +50,6 @@ flows:
 
 ## See Also
 
-- [Load Multiple Inputs from Files](load_inputs_from_files.md)
-- [Use Session Inputs for Sticky Variables](../Language%20Features/use_session_inputs.md)
-- [Example: LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md)
+- [Load Multiple Inputs from Files](load_multiple_inputs_from_files.md)
+- [CLI Reference](../../Reference/cli.md)
+- [Gallery: Dataflow Pipelines](../../Gallery/dataflow_pipelines.md)

{docs → qtype/docs}/How To/Command Line Usage/serve_with_auto_reload.md

@@ -22,5 +22,6 @@ qtype serve --reload -p 8080 examples/tutorials/01_hello_world.qtype.yaml
 
 ## See Also
 
-- [Serve Command Reference](../../Reference/CLI.md#serve)
-- [Tutorial: Hello World](../../Tutorials/01_hello_world.md)
+- [Serve Flows as APIs](../Qtype%20Server/serve_flows_as_apis.md)
+- [Serve Flows as UI](../Qtype%20Server/serve_flows_as_ui.md)
+- [CLI Reference](../../Reference/cli.md)

{docs → qtype/docs}/How To/Data Processing/adjust_concurrency.md

@@ -35,7 +35,6 @@ The following step types support `concurrency_config`:
 
 ## See Also
 
-- [LLMInference Reference](../../components/LLMInference.md)
-- [InvokeEmbedding Reference](../../components/InvokeEmbedding.md)
-- [DocumentEmbedder Reference](../../components/DocumentEmbedder.md)
-- [LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md)
+- [Step Reference](../../components/Step.md)
+- [Cache Step Results](cache_step_results.md)
+- [Gallery: Dataflow Pipelines](../../Gallery/dataflow_pipelines.md)

{docs → qtype/docs}/How To/Data Processing/cache_step_results.md

@@ -66,6 +66,6 @@ qtype run examples/data_processing/cache_step_results.qtype.yaml  --progress -i
 
 ## See Also
 
-- [LLMInference Reference](../../components/LLMInference.md)
+- [Step Reference](../../components/Step.md)
 - [Adjust Concurrency](adjust_concurrency.md)
-- [Tutorial: Your First QType Application](../../Tutorials/your_first_qtype_application.md)
+- [Tutorial: Your First QType Application](../../Tutorials/01-first-qtype-application.md)

{docs → qtype/docs}/How To/Data Processing/decode_json_xml.md

@@ -21,4 +21,4 @@ Parse string data in JSON or XML format into structured outputs. This is particu
 
 - [Decoder Reference](../../components/Decoder.md)
 - [CustomType Reference](../../components/CustomType.md)
-- [Tutorial: Working with Types and Structured Data](../../Tutorials/structured_data.md)
+- [Tutorial: Structured Data](../../Tutorials/03-structured-data.md)

{docs → qtype/docs}/How To/Data Processing/explode_collections.md

@@ -35,6 +35,6 @@ qtype run examples/data_processing/explode_items.qtype.yaml \
 
 ## See Also
 
-- [Aggregate Data using Collect](./aggregate_data.md)
+- [Gather Results into a List](gather_results.md)
 - [Explode Reference](../../components/Explode.md)
-- [Adjust Concurrency](./adjust_concurrency.md)
+- [Adjust Concurrency](adjust_concurrency.md)

{docs → qtype/docs}/How To/Data Processing/gather_results.md

@@ -22,8 +22,8 @@ steps:
 
 - **Collect**: Gathers all input values from multiple messages into a single list output
 - **Common ancestors**: Only variables that have the exact same value across ALL input messages are preserved in the output message
-- **Fan-out pattern**: Typically used after `Explode` to reverse the fan-out and aggregate results
-- **Single output**: Always produces exactly one output message containing the aggregated list
+- **Fan-out pattern**: Typically used after `Explode` to reverse the fan-out and accumulate results
+- **Single output**: Always produces exactly one output message containing the accumulate list
 
 ### Understanding Common Ancestors
 
@@ -63,6 +63,6 @@ all_processed: ['Processed: Phone', 'Processed: Laptop', 'Processed: Tablet']
 
 ## See Also
 
-- [Explode Collections for Fan-Out Processing](explode_collections.md)
+- [Explode Collections](explode_collections.md)
 - [Collect Reference](../../components/Collect.md)
-- [Explode Reference](../../components/Explode.md)
+- [Aggregate Reference](../../components/Aggregate.md)

qtype/docs/How To/Data Processing/invoke_other_flows.md

@@ -0,0 +1,71 @@
+# Invoke Other Flows
+
+Reuse flows as composable building blocks by invoking them from other flows with input and output bindings.
+
+### QType YAML
+
+```yaml
+flows:
+  # Define reusable flow
+  - type: Flow
+    id: summarize_text
+    variables:
+      - id: input_text
+        type: text
+      - id: output_summary
+        type: text
+    inputs: [input_text]
+    outputs: [output_summary]
+    steps:
+      - type: LLMInference
+        id: summarizer
+        model: my_model
+        inputs: [input_text]
+        outputs: [output_summary]
+
+  # Main flow invokes the reusable flow
+  - type: Flow
+    id: main
+    variables:
+      - id: article
+        type: text
+      - id: summary
+        type: text
+    inputs: [article]
+    outputs: [summary]
+    steps:
+      - type: InvokeFlow
+        id: get_summary
+        flow: summarize_text           # Reference to flow by ID
+        input_bindings:
+          input_text: article          # Map flow input to step variable
+        output_bindings:
+          output_summary: summary      # Map flow output to step variable
+```
+
+### Explanation
+
+- **InvokeFlow**: Step type that executes another flow with variable mapping
+- **flow**: ID of the flow to invoke (must be defined in the application)
+- **input_bindings**: Maps flow input variables to the invoking step's variables (format: `flow_input_name: step_variable_name`)
+- **output_bindings**: Maps flow output variables to the invoking step's variables (format: `flow_output_name: step_variable_name`)
+- **Reusability**: Flows can be invoked multiple times with different bindings
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/invoke_other_flows.qtype.yaml"
+```
+
+**Run it:**
+```bash
+qtype run examples/data_processing/invoke_other_flows.qtype.yaml \
+  --flow main \
+  --input '{"article_text": "Your article text here..."}'
+```
+
+## See Also
+
+- [InvokeFlow Reference](../../components/InvokeFlow.md)
+- [Flow Reference](../../components/Flow.md)
+- [Use Agent Skills](../Language%20Features/use_agent_skills.md)

qtype/docs/How To/Data Processing/load_data_from_athena.md

@@ -0,0 +1,49 @@
+# Load Data from Athena
+
+Query AWS Athena databases using standard SQL with the `SQLSource` step, which supports Athena through SQLAlchemy connection strings and AWS authentication.
+
+### QType YAML
+
+```yaml
+flows:
+  - id: query-athena
+    steps:
+      - type: SQLSource
+        id: load_sales
+        connection: "awsathena+rest://:@athena.us-east-1.amazonaws.com:443/sales_db?s3_staging_dir=s3://my-results-bucket/athena-results/&work_group=primary&catalog_name=some_catalog"
+        query: |
+          SELECT
+            product_id,
+            product_name,
+            total_sales
+          FROM product_sales
+          WHERE total_sales >= :min_sales
+          ORDER BY total_sales DESC
+        inputs:
+          - min_sales
+        outputs:
+          - product_id
+          - product_name
+          - total_sales
+```
+
+### Explanation
+
+- **awsathena+rest**: PyAthena SQLAlchemy dialect for accessing Athena via REST API
+- **Connection string format**: `awsathena+rest://:@athena.{REGION}.amazonaws.com:443/{DATABASE}?s3_staging_dir={S3_PATH}&work_group={WORKGROUP}&catalog_name={CATALOG}"`
+- **s3_staging_dir**: S3 location where Athena writes query results (required by Athena)
+- **work_group**: Athena workgroup name (e.g., `primary`)
+- **auth**: Reference to AWSAuthProvider for AWS credentials
+- **query**: Standard SQL query with parameter substitution using `:parameter_name` syntax
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/athena_query.qtype.yaml"
+```
+
+## See Also
+
+- [SQLSource Reference](../../components/SQLSource.md)
+- [Configure AWS Authentication](../Authentication/configure_aws_authentication.md)
+- [Read Data from SQL Databases](read_sql_databases.md)

qtype/docs/How To/Data Processing/load_documents.md

@@ -0,0 +1,74 @@
+# Load Documents
+
+Load documents from files, directories, or external systems using LlamaIndex readers with DocumentSource.
+
+**Note:** DocumentSource is a source step that generates data independently, so flows using it typically require no inputs.
+
+### QType YAML
+
+```yaml
+steps:
+  - type: DocumentSource
+    id: load_docs
+    reader_module: llama_index.core.SimpleDirectoryReader
+    args:
+      input_dir: ./data
+      required_exts: [".md", ".txt"]
+      recursive: true
+    loader_args:
+      num_workers: 4
+    outputs:
+      - document
+```
+
+### Explanation
+
+- **reader_module**: Python module path to a class that inherits from `llama_index.core.readers.base.BaseReader` (most common: `llama_index.core.SimpleDirectoryReader`)
+- **args**: Arguments passed to the reader class constructor (e.g., `input_dir`, `required_exts`, `recursive`, `file_extractor`)
+- **loader_args**: Arguments passed to the reader's `load_data()` method (e.g., `num_workers` for parallel processing)
+- **outputs**: Variable to store loaded documents (type: `RAGDocument`) - DocumentSource fans out, emitting one message per document
+- **Critical distinction**: Constructor args configure the reader instance; `load_data` args control how documents are loaded
+
+### Common Reader Modules
+
+**SimpleDirectoryReader** (`llama_index.core.SimpleDirectoryReader`):
+- Constructor args: `input_dir`, `input_files`, `required_exts`, `exclude`, `recursive`, `file_extractor`, `file_metadata`, `encoding`
+- Loader args: `num_workers` (parallel processing)
+- Supports 15+ file types including PDF, DOCX, CSV, Markdown, images, audio/video
+- [Full documentation](https://developers.llamaindex.ai/python/framework/module_guides/loading/simpledirectoryreader/)
+
+**JSONReader** (`llama_index.readers.json.JSONReader`):
+- Constructor args: `levels_back`, `collapse_length`, `ensure_ascii`, `is_jsonl`, `clean_json`
+- Loader args: `input_file`, `extra_info`
+- Supports both JSON and JSONL (JSON Lines) formats
+- [Full documentation](https://developers.llamaindex.ai/typescript/framework/modules/data/readers/json/)
+
+### Dynamic Arguments
+
+You can pass flow variables as constructor arguments by including them in `args`. At runtime, QType merges message variables with the configured args:
+
+```yaml
+variables:
+  - id: data_path
+    type: text
+
+steps:
+  - type: DocumentSource
+    id: load_docs
+    reader_module: llama_index.core.SimpleDirectoryReader
+    args:
+      input_dir: data_path    # References variable from message
+    inputs: [data_path]
+```
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/load_documents.qtype.yaml"
+```
+
+## See Also
+
+- [DocumentSource Reference](../../components/DocumentSource.md)
+- [DocumentSplitter How-To](chunk_documents.md)
+- [RAG Tutorial](../../Tutorials/rag_tutorial.md)

qtype/docs/How To/Data Processing/read_data_from_files.md

@@ -0,0 +1,61 @@
+# Read Data from Files
+
+Load structured data from files using FileSource, which supports CSV, JSON, JSONL, and Parquet formats with automatic format detection and type conversion.
+
+### QType YAML
+
+```yaml
+steps:
+  - id: read_data
+    type: FileSource
+    path: batch_inputs.csv
+    outputs:
+      - query
+      - topic
+```
+
+### Explanation
+
+- **FileSource**: Step that reads structured data from files using fsspec-compatible URIs
+- **path**: File path (relative to YAML file or absolute), supports local files and cloud storage (s3://, gs://, etc.)
+- **outputs**: Column names from the file to extract as variables (must match actual column names)
+- **Format detection**: Automatically determined by file extension (.csv, .json, .jsonl, .parquet)
+- **Type conversion**: Automatically converts data to match variable types (primitives, domain types, custom types)
+- **Streaming**: Emits one FlowMessage per row, enabling downstream steps to process data in parallel
+
+### Automatic Type Conversion
+
+FileSource automatically converts data from files to match your variable types:
+
+- **Primitive types** (`int`, `float`, `bool`, `text`): Direct conversion from file data
+- **Domain types** (`ChatMessage`, `SearchResult`, etc.): Validated from dict/object columns
+- **Custom types**: Your defined types are validated and instantiated from dict/object columns
+
+**Format Recommendations:**
+
+- **CSV**: Best for simple primitive types (strings, numbers, booleans)
+- **JSON/JSONL**: Recommended for nested objects, custom types, and domain types
+- **Parquet**: Best for large datasets with mixed types and efficient storage
+
+**Example with Custom Types (JSON format):**
+
+```json
+[
+  {"person": {"name": "Alice", "age": 30}, "score": 95},
+  {"person": {"name": "Bob", "age": 25}, "score": 87}
+]
+```
+
+JSON preserves nested objects, making it ideal for complex types. CSV stores everything as strings, requiring nested objects to be serialized as JSON strings within the CSV.
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/read_file.qtype.yaml"
+```
+
+## See Also
+
+- [FileSource Reference](../../components/FileSource.md)
+- [Load Multiple Inputs from Files](../Command%20Line%20Usage/load_multiple_inputs_from_files.md)
+- [Write Data to File](write_data_to_file.md)

{docs → qtype/docs}/How To/Data Processing/read_sql_databases.md

@@ -2,6 +2,8 @@
 
 Query relational databases and process results row-by-row using the `SQLSource` step, which supports any database accessible via SQLAlchemy connection strings.
 
+**Note:** SQLSource is a source step that generates data from database queries, so flows using it typically require no inputs.
+
 ### QType YAML
 
 ```yaml
@@ -42,6 +44,5 @@ steps:
 ## See Also
 
 - [SQLSource Reference](../../components/SQLSource.md)
-- [FileSource Reference](../../components/FileSource.md)
-- [Tutorial: Working with Types and Structured Data](../../Tutorials/working_with_types_and_structured_data.md)
-- [Example: Dataflow Pipeline](../../Gallery/Data%20Processing/dataflow_pipelines.md)
+- [Load Data from Athena](load_data_from_athena.md)
+- [Read Data from Files](read_data_from_files.md)

{docs → qtype/docs}/How To/Data Processing/write_data_to_file.md

@@ -36,5 +36,4 @@ See the [LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md) gallery
 
 - [FileWriter Reference](../../components/FileWriter.md)
 - [Read Data from Files](read_data_from_files.md)
-- [Read SQL Databases](read_sql_databases.md)
-- [LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md)
+- [Gallery: Dataflow Pipelines](../../Gallery/dataflow_pipelines.md)

{docs → qtype/docs}/How To/Invoke Models/call_large_language_models.md

@@ -48,4 +48,4 @@ qtype run simple_llm_call.qtype.yaml --input '{"text": "What is the capital of F
 
 - [LLMInference Reference](../../components/LLMInference.md)
 - [Model Reference](../../components/Model.md)
-- [Tutorial: Build a Conversational Interface](../../Tutorials/conversational_interface.md)
+- [Tutorial: Conversational Chatbot](../../Tutorials/02-conversational-chatbot.md)

{docs → qtype/docs}/How To/Invoke Models/create_embeddings.md

@@ -46,4 +46,4 @@ qtype run examples/invoke_models/create_embeddings.qtype.yaml \
 
 - [InvokeEmbedding Reference](../../components/InvokeEmbedding.md)
 - [EmbeddingModel Reference](../../components/EmbeddingModel.md)
-- [Tutorial: Build a RAG System](../../Tutorials/building_rag_system.md)
+- [Embedding Reference](../../components/Embedding.md)

{docs → qtype/docs}/How To/Invoke Models/reuse_prompts_with_templates.md

@@ -34,6 +34,5 @@ steps:
 ## See Also
 
 - [PromptTemplate Reference](../../components/PromptTemplate.md)
-- [How-To: Include Raw Text from Other Files](../../How%20To/Language%20Features/include_raw_text.md)
-- [How-To: Invoke LLMs with System Messages](invoke_llms_with_system_messages.md)
-- [Tutorial: Your First QType Application](../../Tutorials/your_first_qtype_application.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)

{docs → qtype/docs}/How To/Language Features/include_raw_text_from_other_files.md

@@ -44,4 +44,5 @@ qtype run include_raw.qtype.yaml -i '{"theme":"a robot learning to paint","tone"
 ## See Also
 
 - [PromptTemplate Reference](../../components/PromptTemplate.md)
-- [Reference Entities by ID](../../How%20To/Language%20Features/reference_entities_by_id.md)
+- [Include QType YAML](include_qtype_yaml.md)
+- [Reuse Prompts with Templates](../Invoke%20Models/reuse_prompts_with_templates.md)

{docs → qtype/docs}/How To/Language Features/reference_entities_by_id.md

@@ -46,6 +46,6 @@ flows:
 
 ## See Also
 
+- [Include QType YAML](include_qtype_yaml.md)
 - [Tutorial: Your First QType Application](../../Tutorials/01-first-qtype-application.md)
-- [Model Reference](../../components/Model.md)
-- [APIKeyAuthProvider Reference](../../components/APIKeyAuthProvider.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)

{docs → qtype/docs}/How To/Language Features/use_environment_variables.md

@@ -43,5 +43,6 @@ 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)
-- [APIKeyAuthProvider Reference](../../components/APIKeyAuthProvider.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)

{docs → qtype/docs}/How To/Language Features/use_qtype_mcp.md

@@ -41,7 +41,7 @@ Add the QType MCP server to your workspace's `.vscode/mcp.json`:
 ```json
 {
   "servers": {
-    "qtype": {
+    "qtype-mcp": {
       "type": "stdio",
       "command": "qtype",
       "cwd": "${workspaceFolder}",
@@ -54,6 +54,6 @@ Add the QType MCP server to your workspace's `.vscode/mcp.json`:
 
 ## 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/)
+- [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)

{docs → qtype/docs}/How To/Observability & Debugging/trace_calls_with_open_telemetry.md

@@ -46,4 +46,4 @@ Then open `http://localhost:6006` in your browser to see the traced execution.
 
 - [Application Reference](../../components/Application.md)
 - [Validate QType YAML](validate_qtype_yaml.md)
-- [Visualize Application Architecture](visualize_application_architecture.md)
+- [CLI Reference](../../Reference/cli.md)