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

docs/Contributing/roadmap.md

@@ -0,0 +1,81 @@
+# Roadmap
+
+This document outlines the planned features, improvements, and milestones for the QType project.
+
+## Current Status
+
+- ✅ Core DSL implementation
+- ✅ Basic validation and semantic resolution
+- ✅ CLI interface with convert, generate, run, and validate commands
+- ✅ AWS Bedrock model integration
+
+## Upcoming Milestones
+
+
+### v0.1.0
+#### Documentation
+- [x] Documentation setup with mkdocs
+- [ ] Examples showroom illustrating use cases
+- [x] Page for each concecpt and examples thereof
+- [x] Document how to add to the dsl
+- [ ] Document how to use DSL in visual studio code
+- [ ] Docunment how to use includes, anchors, and references.
+
+
+## Future Work
+
+### DSL
+- [ ] Add a new flow type for state machines. It will have a list of states, each being a flow themselves, and transitions consisting of conditions and steps that deterimine if the condition has been met.
+- [ ] Add support for vectorstores and sql chat stores
+- [ ] Add support for more complex conditions
+- [ ] Expand Authorization types into abstract classes for different ways to authorize
+- [ ] Add support for vectorstores and sql chat stores
+- [ ] Add support for DocumentIndexes.
+- [ ] Add feedbnack types and steps
+- [ ] Add conversation storage
+
+### Tools
+- [ ] Add support for importing tools from API
+- [ ] Refine the type abstractions for tool importing from mdoules
+
+### Exended Capabilities
+- [ ] (Interpreter) - User Interface
+- [ ] (Interpreter) - Support other model providers
+- [ ] (Interpreter) - Store memory and session info in a cache to enable this kind of stateful communication.
+- [ ] (Interpreter) - Refine Agent interpreter for greater tool support and chat history
+- [ ] (Interpreter) - Run as MCP server
+- [ ] (Interpreter) - Set UI to have limit on number of messages if chat flow llm has memory
+
+### Advanced AI Capabilities
+- [ ] Multi-modal support (text, image, audio)
+- [ ] Agent-based architectures
+- [ ] RAG OOTB
+- [ ] Workflows for measuring workflows
+
+## Feature Requests & Community Input
+
+We welcome community feedback and feature requests! Please:
+
+1. Check existing [GitHub Issues](https://github.com/bazaarvoice/qtype/issues) before submitting
+2. Use the appropriate issue templates
+3. Participate in [Discussions](https://github.com/bazaarvoice/qtype/discussions) for broader topics
+4. Consider contributing via pull requests
+
+## Contributing to the Roadmap
+
+This roadmap is a living document that evolves based on:
+- Community feedback and usage patterns
+- Technical feasibility assessments
+- Business priorities and partnerships
+- Emerging AI/ML trends and capabilities
+
+For significant roadmap suggestions, please:
+1. Open a GitHub Discussion with the "roadmap" label
+2. Provide clear use cases and benefits
+3. Consider implementation complexity
+4. Engage with the community for feedback
+
+---
+
+*Last updated: July 28, 2025*
+*For the most current information, see [GitHub Issues](https://github.com/bazaarvoice/qtype/issues) 

docs/Decisions/ADR-001-Chat-vs-Completion-Endpoint-Features.md

@@ -0,0 +1,56 @@
+# ADR 001: Separation of Features Between Chat and Completion Endpoints
+
+* **Status:** Accepted
+* **Date:** 2025-11-04
+* **Approved by:** Lou Kratz
+
+---
+
+## Context
+
+We offer two primary LLM endpoints: `/chat` and `/completion`, both with streaming and non-streaming (REST) variants. We needed to decide where to return advanced features (like `reasoning`, `tool_calls`, etc.) versus simple text-deltas.
+
+The `/completion` endpoint was beginning to accumulate complex features, which conflicts with its intended simple (prompt-in, text-out) purpose. This created friction with frontend libraries like Vercel's AI SDK, whose `useCompletion` hook is designed to handle only a simple string/text-delta stream.
+
+## Decision
+
+We will strictly separate the concerns of the two endpoints to align with industry best practices and simplify their use:
+
+1.  **`/chat` (Stream):** This will be the **only** endpoint that returns advanced features (e.g., `reasoning`, `tool_calls`, and other non-text metadata).
+2.  **`/completion` (Stream & REST):** These endpoints will **only** return simple text. The stream will only contain text-deltas, and the REST endpoint will return the final completed text string.
+3.  **`/chat` (REST):** This endpoint will also return simple text responses, consistent with the other REST endpoints.
+
+All advanced functionality will be removed from the `/completion` endpoints and the non-streaming `/chat` endpoint.
+
+---
+
+## Consequences
+
+### Positive
+
+* **Simplicity & Alignment:** This aligns the `/completion` endpoint with its intended purpose as a simple Q&A/generation tool. It matches the pattern set by major libraries (like Vercel's SDK), which treat "completion" as a simple string.
+* **Improved FE Integration:** Our UIs can now use the standard `useCompletion` hook directly without any workarounds.
+* **Clear API Contract:** 3rd-party developers have a clear choice:
+    * Use `/completion` for simple text generation.
+    * Use `/chat` (stream) for complex, stateful, or tool-enabled interactions.
+* **Long-Term Maintainability:** We only need to build, test, and maintain advanced features in a single endpoint (the chat stream), reducing complexity.
+
+### Negative
+
+* (None identified; this decision is considered a simplification and correction of a previous design.)
+
+---
+
+## Options Considered
+
+### Option 1: Keep `useCompletion` and Manually Parse Data
+
+* **Details:** Keep using the Vercel `useCompletion` hook in the frontend but change our stream protocol to `text` (from the default). We would then manually embed JSON for `reasoning`/`tools` within the text stream and parse it on the client.
+* **Rejected Because:** This requires complex, brittle, and manual handling of stream states and data extraction in the frontend, defeating the purpose of using the simple hook.
+
+### Option 2: Use `useChat` for the Completion UI
+
+* **Details:** Have our simple "completion" UI use the `/chat` endpoint and Vercel's `useChat` hook, but always send an empty message array.
+* **Rejected Because:**
+    1.  **Poor FE Experience:** It complicates the frontend logic, requiring us to manually clear Vercel's `messages` state after every single request.
+    2.  **Poor API Experience:** It forces 3rd-party users (who just want to send a simple prompt) to use the more complex `/chat` object format instead of the simple `/completion` string format.

docs/Gallery/dataflow_pipelines.md

@@ -0,0 +1,80 @@
+# LLM Processing Pipelines
+
+## Overview
+
+An automated data processing pipeline that reads product reviews from a SQLite database and analyzes each review's sentiment using an LLM. This example demonstrates QType's dataflow capabilities with database sources, parallel LLM processing, and streaming results without requiring batch operations.
+
+## Architecture
+
+```mermaid
+--8<-- "Gallery/dataflow_pipelines.mermaid"
+```
+
+## Complete Code
+
+```yaml
+--8<-- "../examples/data_processing/dataflow_pipelines.qtype.yaml"
+```
+
+## Key Features
+
+- **SQLSource Step**: Database source that executes SQL queries using SQLAlchemy connection strings and emits one message per result row, enabling parallel processing of database records through downstream steps
+- **PromptTemplate Step**: Template engine with curly-brace variable substitution (`{product_name}`, `{rating}`) that dynamically generates prompts from message variables for each review
+- **LLMInference Step**: Processes each message independently through the language model with automatic parallelization, invoking AWS Bedrock inference for all reviews concurrently
+- **Multi-record Flow**: Each database row becomes an independent FlowMessage flowing through the pipeline in parallel, carrying variables (review_id, product_name, rating, review_text) and accumulating new fields (llm_analysis) at each step
+- **Message Sink**: The final step accumulates all records and writes them to an output file.
+
+## Running the Example
+
+### Setup
+
+First, create the sample database with product reviews:
+
+```bash
+python examples/data_processing/create_sample_db.py
+```
+
+This generates a SQLite database with 10 sample product reviews covering various products and sentiments.
+
+### Run the Pipeline
+
+Process all reviews and generate the analysis with real-time progress monitoring:
+
+```bash
+qtype run -i '{"output_path":"results.parquet"}' --progress examples/data_processing/dataflow_pipelines.qtype.yaml
+```
+
+The `--progress` flag displays a live dashboard showing:
+- Message throughput for each step (msg/s)
+- Success/error counts
+- Processing duration with visual progress bars
+
+Example output:
+```
+╭─────────────────────────────────────────────────────────────────────────────── Flow Progress ───────────────────────────────────────────────────────────────────────────────╮
+│                                                                                                                                                                             │
+│  Step load_reviews                      1.6 msg/s       ▁▁▁▁▃▃▃▃▅▅▅▅████████            ✔ 10 succeeded         ✖ 0 errors       ⟳ - hits      ✗ - misses      0:00:06       │
+│  Step create_prompt                     1.6 msg/s       ▁▁▁▁▃▃▃▃▅▅▅▅████████            ✔ 10 succeeded         ✖ 0 errors       ⟳ - hits      ✗ - misses      0:00:06       │
+│  Step analyze_sentiment                 2.0 msg/s       ▄▄▄▄▆▆▆▆▅▅▅▅███████▁            ✔ 10 succeeded         ✖ 0 errors       ⟳ - hits      ✗ - misses      0:00:04       │
+│  Step write_results                    - msg/s                                          ✔ 1 succeeded          ✖ 0 errors       ⟳ - hits      ✗ - misses      0:00:00       │
+│                                                                                                                                                                             │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+```
+
+You'll notice that the output shows 1 message for `write_results` and 10 for the others. That is because it is reporting the number of messages _emitted_ from each step, and `write_results` is a sink that collects all messages.
+
+The final message of the output will be the result file where the data are written:
+
+```
+2026-01-16 11:23:35,151 - INFO: ✅ Flow execution completed successfully
+2026-01-16 11:23:35,151 - INFO: Processed 1 em
+2026-01-16 11:23:35,152 - INFO: 
+Results:
+result_file: results.parquet
+```
+
+## Learn More
+
+- Tutorial: [Your First QType Application](../../Tutorials/01_hello_world.md)
+- Example: [Simple Chatbot](./simple_chatbot.md)

docs/Gallery/dataflow_pipelines.mermaid

@@ -0,0 +1,45 @@
+flowchart TD
+    subgraph APP ["📱 review_analysis_pipeline"]
+        direction TB
+
+    subgraph FLOW_0 ["🔄 analyze_reviews"]
+        direction TB
+        FLOW_0_START@{shape: circle, label: "▶️ Start"}
+        FLOW_0_S0@{shape: rect, label: "⚙️ load_reviews"}
+        FLOW_0_S1@{shape: doc, label: "📄 create_prompt"}
+        FLOW_0_S2@{shape: rounded, label: "✨ analyze_sentiment"}
+        FLOW_0_S3@{shape: rect, label: "⚙️ write_results"}
+        FLOW_0_S0 -->|product_name| FLOW_0_S1
+        FLOW_0_S0 -->|rating| FLOW_0_S1
+        FLOW_0_S0 -->|review_text| FLOW_0_S1
+        FLOW_0_S1 -->|analysis_prompt| FLOW_0_S2
+        FLOW_0_S0 -->|review_id| FLOW_0_S3
+        FLOW_0_S0 -->|product_name| FLOW_0_S3
+        FLOW_0_S0 -->|rating| FLOW_0_S3
+        FLOW_0_S0 -->|review_text| FLOW_0_S3
+        FLOW_0_S2 -->|llm_analysis| FLOW_0_S3
+        FLOW_0_START -->|output_path| FLOW_0_S3
+    end
+
+    subgraph RESOURCES ["🔧 Shared Resources"]
+        direction LR
+        MODEL_NOVA_LITE@{shape: rounded, label: "✨ nova_lite (aws-bedrock)" }
+    end
+
+    end
+
+    FLOW_0_S2 -.->|uses| MODEL_NOVA_LITE
+
+    %% 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/Gallery/research_assistant.md

@@ -0,0 +1,98 @@
+# Research Assistant
+
+## Overview
+
+A minimal “web research assistant” that takes a single input topic, searches the
+web using Tavily, and then synthesizes an answer with an LLM call. This example
+demonstrates how to reuse OpenAPI-generated tools via `references` and bind tool
+outputs into an LLM prompt.
+
+## Architecture
+
+```mermaid
+--8<-- "Gallery/research_assistant.mermaid"
+```
+
+## Complete Code
+
+```yaml
+--8<-- "../examples/research_assistant/research_assistant.qtype.yaml"
+```
+
+## Key Features
+
+- **`references` (Application)**: Imports external QType documents (here, the Tavily
+  tool library) so you can reference tools like `search` by ID
+- **`BearerTokenAuthProvider.token`**: Stores the Tavily API key as a bearer token,
+  loaded via `${TAVILY-API_BEARER}` environment-variable substitution
+- **APITool**: Represents the Tavily HTTP endpoints (like `/search`) as typed tools
+  with declared `inputs` and `outputs`
+- **InvokeTool Step**: Calls the `search` tool and maps flow variables to tool
+  parameters via `input_bindings`/`output_bindings`
+- **PromptTemplate Step**: Builds the synthesis prompt by combining the user topic
+  and the Tavily search results
+- **LLMInference Step**: Produces the final `answer` by running model inference
+  using the prompt produced by `PromptTemplate`
+
+## Running the Example
+
+### 1) Create a Tavily account + API key
+
+Create an account at Tavily and generate an API key.
+
+### 2) Set the Tavily token in a `.env`
+
+Create a `.env` file next to `examples/research_assistant/research_assistant.qtype.yaml`:
+
+```bash
+TAVILY-API_BEARER=tvly-...
+```
+
+QType automatically loads a `.env` file from the spec’s directory when you run
+`qtype run`.
+
+### 3) Run
+
+```bash
+# Validate the YAML
+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
+```
+
+### Example Output
+
+When running with the topic "Latest developments in retrieval augmented generation", the research assistant produces:
+
+> #### Latest Developments in Retrieval-Augmented Generation
+>
+> Retrieval-Augmented Generation (RAG) has seen significant advancements, particularly in enhancing the accuracy and
+> factual grounding of AI-generated content. Recent developments focus on improving the retrieval–generation
+> pipeline, reducing hallucinations, and increasing performance metrics. For instance, performance improvements from
+> 68% to 73% have been reported, with notable reductions in hallucinations and stronger factual grounding.
+>
+> Key areas of progress include:
+>
+> - **Enhanced Retrieval Mechanisms:** Improved algorithms for retrieving relevant information from large datasets.
+> - **Stronger Factual Grounding:** Techniques that ensure generated content is more accurate and grounded in factual
+> data.
+> - **Reduction of Hallucinations:** Methods to minimize the generation of incorrect or misleading information.
+> - **Targeted Enhancements:** Specific improvements across different stages of the retrieval–generation process.
+>
+> These advancements are expected to have a substantial impact on various applications, including natural language
+> processing, content creation, and information retrieval systems.
+>
+> **Sources:**
+>
+> - [Latest Developments in Retrieval-Augmented Generation - CelerData](https://celerdata.com/glossary/latest-developments-in-retrieval-augmented-generation)
+> - [Advancements in RAG [Retrieval-Augmented Generation] Systems by Mid-2025](https://medium.com/@martinagrafsvw25/advancements-in-rag-retrieval-augmented-generation-systems-by-mid-2025-935a39c15ae9)
+> - [Retrieval-Augmented Generation: A Comprehensive Survey - arXiv](https://arxiv.org/html/2506.00054v1)
+
+## 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)

docs/Gallery/research_assistant.mermaid

@@ -0,0 +1,42 @@
+flowchart TD
+    subgraph APP ["📱 research_assistant"]
+        direction TB
+
+    subgraph FLOW_0 ["🔄 research"]
+        direction TB
+        FLOW_0_START@{shape: circle, label: "▶️ Start"}
+        FLOW_0_S0@{shape: rect, label: "⚙️ search_web"}
+        FLOW_0_S1@{shape: doc, label: "📄 build_prompt"}
+        FLOW_0_S2@{shape: rounded, label: "✨ synthesize"}
+        FLOW_0_START -->|topic| FLOW_0_S0
+        FLOW_0_START -->|topic| FLOW_0_S1
+        FLOW_0_S0 -->|tavily_results| FLOW_0_S1
+        FLOW_0_S1 -->|synthesis_prompt| FLOW_0_S2
+    end
+
+    subgraph RESOURCES ["🔧 Shared Resources"]
+        direction LR
+        AUTH_TAVILY_API_BEARERAUTH_TOKEN@{shape: hex, label: "🔐 tavily-api_bearerauth_token (BEARER_TOKEN)"}
+        MODEL_NOVA_LITE@{shape: rounded, label: "✨ nova_lite (aws-bedrock)" }
+        TOOL_SEARCH["⚡ search (POST)"]
+        TOOL_SEARCH -.->|uses| AUTH_TAVILY_API_BEARERAUTH_TOKEN
+    end
+
+    end
+
+    FLOW_0_S0 -.->|uses| TOOL_SEARCH
+    FLOW_0_S2 -.->|uses| MODEL_NOVA_LITE
+
+    %% 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/Gallery/simple_chatbot.md

@@ -0,0 +1,36 @@
+# Simple Chatbot
+
+## Overview
+
+A friendly conversational chatbot with memory that maintains context across multiple conversation turns. This example demonstrates the minimal setup needed to create a stateful chatbot using AWS Bedrock, perfect for getting started with conversational AI applications.
+
+## Architecture
+
+```mermaid
+--8<-- "Gallery/simple_chatbot.mermaid"
+```
+
+## Complete Code
+
+```yaml
+--8<-- "../examples/conversational_ai/simple_chatbot.qtype.yaml"
+```
+
+## Key Features
+
+- **Conversational Interface**: This instructs the front-end to create a conversational user experience. 
+- **Memory**: Conversation history buffer with `token_limit` (10,000) that stores messages and automatically flushes oldest content when limit is exceeded
+- **ChatMessage Type**: Built-in domain type with `role` field (user/assistant/system) and `blocks` list for structured multi-modal content
+- **LLMInference Step**: Executes model inference with optional `system_message` prepended to conversation and `memory` reference for persistent context across turns
+- **Model Configuration**: Model resource with provider-specific `inference_params` including `temperature` (randomness) and `max_tokens` (response length limit)
+
+## Running the Example
+
+```bash
+# Start the chatbot server
+qtype serve examples/conversational_ai/simple_chatbot.qtype.yaml
+```
+
+## Learn More
+
+- Tutorial: [Building a Stateful Chatbot](../../Tutorials/02_conversational_chat.md)

docs/Gallery/simple_chatbot.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/Authentication/configure_aws_authentication.md

@@ -0,0 +1,60 @@
+# Configure AWS Authentication
+
+AWS Bedrock and other AWS services require authentication, which can be configured using access keys, AWS profiles, or role assumption.
+
+### QType YAML
+
+```yaml
+auths:
+  # Method 1: AWS Profile (recommended)
+  - type: aws
+    id: aws_profile
+    profile_name: default
+    region: us-east-1
+  
+  # Method 2: Access Keys (for CI/CD)
+  - type: aws
+    id: aws_keys
+    access_key_id: AKIAIOSFODNN7EXAMPLE
+    secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+    region: us-east-1
+  
+  # Method 3: Role Assumption
+  - type: aws
+    id: aws_role
+    profile_name: base_profile
+    role_arn: arn:aws:iam::123456789012:role/MyRole
+    role_session_name: qtype-session
+    region: us-east-1
+
+models:
+  - type: Model
+    id: nova
+    provider: aws-bedrock
+    model_id: us.amazon.nova-micro-v1:0
+    auth: aws_profile
+```
+
+### Explanation
+
+- **type: aws**: Declares an AWS authentication provider
+- **profile_name**: Uses credentials from `~/.aws/credentials` (recommended for local development)
+- **access_key_id / secret_access_key**: Explicit credentials (use environment variables or secret manager)
+- **session_token**: Temporary credentials for AWS STS sessions
+- **role_arn**: ARN of IAM role to assume (requires base credentials via profile or keys)
+- **role_session_name**: Session identifier when assuming a role
+- **external_id**: External ID for cross-account role assumption
+- **region**: AWS region for API calls (e.g., `us-east-1`, `us-west-2`)
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/authentication/aws_authentication.qtype.yaml"
+```
+
+## See Also
+
+- [AWSAuthProvider Reference](../../components/AWSAuthProvider.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/How To/Authentication/use_api_key_authentication.md

@@ -0,0 +1,40 @@
+# Use API Key Authentication
+
+Authenticate with model providers like OpenAI using API keys, either from environment variables or stored in secret managers.
+
+### QType YAML
+
+```yaml
+auths:
+  - type: api_key
+    id: openai_auth
+    api_key: ${OPENAI_KEY}
+    host: https://api.openai.com
+
+models:
+  - type: Model
+    id: gpt-4
+    provider: openai
+    model_id: gpt-4-turbo
+    auth: openai_auth
+```
+
+### Explanation
+
+- **type: api_key**: Specifies this is an API key-based authentication provider
+- **api_key**: The API key value, typically loaded from an environment variable using `${VAR_NAME}` syntax
+- **host**: Base URL or domain of the provider (optional, some providers infer this)
+- **auth**: Reference to the auth provider by its ID when configuring models
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/tutorials/01_hello_world.qtype.yaml"
+```
+
+## See Also
+
+- [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)

docs/How To/Command Line Usage/load_multiple_inputs_from_files.md

@@ -0,0 +1,62 @@
+# Load Multiple Inputs from Files
+
+Process multiple inputs in batch by loading data from CSV, JSON, Parquet, or Excel files using the `--input-file` CLI flag, enabling bulk processing without manual JSON construction.
+
+### CLI Command
+
+```bash
+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
+- **Parquet**: Efficient columnar format for large datasets
+- **Excel**: `.xlsx` or `.xls` files
+
+### How It Works
+
+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`)
+
+## Complete Example
+
+**batch_inputs.csv:**
+```csv
+--8<-- "../examples/data_processing/batch_inputs.csv"
+```
+
+**Application:**
+```yaml
+--8<-- "../examples/data_processing/batch_processing.qtype.yaml"
+```
+
+**Run the batch:**
+```bash
+# Process all rows from CSV
+qtype run batch_processing.qtype.yaml --input-file batch_inputs.csv
+
+# Save results to Parquet
+qtype run batch_processing.qtype.yaml \
+  --input-file batch_inputs.csv \
+  --output results.parquet
+```
+
+### Explanation
+
+- **--input-file (-I)**: Path to file containing input data (CSV, JSON, Parquet, Excel)
+- **Column mapping**: CSV column names must match flow input variable IDs exactly
+- **Batch processing**: Each row is processed as a separate flow execution
+- **--output (-o)**: Optional path to save results as Parquet file
+- **Parallel processing**: Steps that support concurrency will process multiple rows in parallel
+
+## See Also
+
+<!-- - [Adjust Concurrency](adjust_concurrency.md) -->
+<!-- - [FileSource Reference](../../components/FileSource.md) -->
+- [Example: Dataflow Pipeline](../../Gallery/Data%20Processing/dataflow_pipelines.md)