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

qtype/docs/Reference/plugins.md

@@ -0,0 +1,99 @@
+# Extending QType CLI
+
+QType supports third-party CLI plugins through Python entry points. This allows developers to extend the QType CLI with custom commands without modifying the core codebase.
+
+## Creating a Plugin
+
+### 1. Define Your Command Function
+
+Create a module with a parser function that takes a subparsers object and registers your command:
+
+```python
+# my_package/qtype_commands.py
+import argparse
+
+def my_command_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the 'my-command' subcommand."""
+    parser = subparsers.add_parser(
+        'my-command',
+        help='My custom QType command'
+    )
+    parser.add_argument(
+        '--option',
+        help='An example option'
+    )
+    # Set the function to call when this command is invoked
+    parser.set_defaults(func=my_command_handler)
+
+def my_command_handler(args: argparse.Namespace) -> None:
+    """Handle the 'my-command' subcommand."""
+    print(f"Running my-command with option: {args.option}")
+```
+
+### 2. Register the Entry Point
+
+Add the entry point to your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."qtype.commands"]
+my-command = "my_package.qtype_commands:my_command_parser"
+```
+
+Or if using `setup.py`:
+
+```python
+from setuptools import setup
+
+setup(
+    name="my-qtype-plugin",
+    # ... other setup parameters
+    entry_points={
+        "qtype.commands": [
+            "my-command = my_package.qtype_commands:my_command_parser",
+        ],
+    },
+)
+```
+
+### 3. Install and Test
+
+After installing your package, the command will be automatically available:
+
+```bash
+pip install my-qtype-plugin
+qtype my-command --option "test"
+```
+
+## Best Practices
+
+1. **Naming**: Use descriptive command names and avoid conflicts with built-in commands
+2. **Error Handling**: Handle errors gracefully and provide helpful error messages
+3. **Documentation**: Include help text for your commands and arguments
+4. **Dependencies**: Declare any additional dependencies your plugin requires
+5. **Testing**: Test your plugin with different versions of QType
+
+## Debugging Plugins
+
+To see debug information about plugin loading, run QType with debug logging:
+
+```bash
+qtype --log-level DEBUG my-command
+```
+
+This will show which plugins are being loaded and any errors that occur during the loading process.
+
+## Example Plugin Structure
+
+```
+my-qtype-plugin/
+├── pyproject.toml
+├── my_package/
+│   ├── __init__.py
+│   └── qtype_commands.py
+└── tests/
+    └── test_plugin.py
+```
+
+## See Also
+
+- [CLI Reference](cli.md)

qtype/docs/Reference/semantic-validation-rules.md

@@ -0,0 +1,184 @@
+# Semantic Validation Rules
+
+Semantic validation happens after loading your yaml. You should expect to see these even if the yaml is validated by the spec.
+
+You can validate any qtype file with:
+```
+qtype validate you_file.qtype.yaml
+```
+
+This document lists all semantic validation rules enforced by QType. These rules are checked after YAML parsing and reference resolution.
+
+---
+
+## Agent
+
+- Must have exactly 1 input
+- Must have exactly 1 output
+- Input must be type `text` or `ChatMessage`
+- Output type must match input type
+
+---
+
+## Application
+
+- If using `SecretReference`, must configure `secret_manager`
+- For `AWSSecretManager`, auth must be `AWSAuthProvider`
+
+---
+
+## AWSAuthProvider
+
+- Must specify at least one authentication method:
+  - Access keys (`access_key_id` + `secret_access_key`)
+  - Profile name (`profile_name`)
+  - Role ARN (`role_arn`)
+- If assuming a role, must provide base credentials (access keys or profile)
+
+---
+
+## BedrockReranker
+
+- Must have exactly 2 inputs
+- One input must be type `text` (query)
+- One input must be type `list[SearchResult]` (results to rerank)
+- Must have exactly 1 output of type `list[SearchResult]`
+
+---
+
+## Collect
+
+- Must have exactly 1 input -- any type `T`
+- Must have exactly 1 output of type `list[T]`
+- Output list element type must match input type
+
+---
+
+## Construct
+
+- Must have at least 1 input
+- Must have exactly 1 output
+- Output type must be a Pydantic BaseModel (Custom type or Domain type)
+
+---
+
+## Decoder
+
+- Must have exactly 1 input of type `text`
+- Must have at least 1 output
+
+---
+
+## DocToTextConverter
+
+- Must have exactly 1 input of type `RAGDocument`
+- Must have exactly 1 output of type `RAGDocument`
+
+---
+
+## DocumentEmbedder
+
+- Must have exactly 1 input of type `RAGChunk`
+- Must have exactly 1 output of type `RAGChunk`
+
+---
+
+## DocumentSearch
+
+- Must have exactly 1 input of type `text`
+- Must have exactly 1 output of type `list[SearchResult]`
+
+---
+
+## DocumentSource
+
+- Must have exactly 1 output of type `RAGDocument`
+
+---
+
+## DocumentSplitter
+
+- Must have exactly 1 input of type `RAGDocument`
+- Must have exactly 1 output of type `RAGChunk`
+
+---
+
+## Echo
+
+- Input and output variable IDs must match (order can differ)
+
+---
+
+## Explode
+
+- Must have exactly 1 input of type `list[T]`
+- Must have exactly 1 output of type `T`
+- Output type must match input list element type
+
+---
+
+## FieldExtractor
+
+- Must have exactly 1 input
+- Must have exactly 1 output
+- `json_path` must be non-empty
+
+---
+
+## Flow
+
+**General:**
+- Must have at least 1 step
+- All step inputs must be fulfilled by flow inputs or previous step outputs
+
+**Conversational Interface:**
+- Must have exactly 1 `ChatMessage` input
+- All non-ChatMessage inputs must be listed in `session_inputs`
+- Must have exactly 1 `ChatMessage` output
+
+**Complete Interface:**
+- Must have exactly 1 input of type `text`
+- Must have exactly 1 output of type `text`
+
+---
+
+## IndexUpsert
+
+**For Vector Index:**
+- Must have exactly 1 input
+- Input must be type `RAGChunk` or `RAGDocument`
+
+**For Document Index:**
+- Must have at least 1 input
+
+---
+
+## LLMInference
+
+- Must have exactly 1 output
+- Output must be type `text` or `ChatMessage`
+
+---
+
+## PromptTemplate
+
+- Must have exactly 1 output
+- Output must be type `text`
+
+---
+
+## SQLSource
+
+- Must have at least 1 output
+
+---
+
+## VectorSearch
+
+- Must have exactly 1 input of type `text`
+- Must have exactly 1 output of type `list[RAGSearchResult]`
+
+## See Also
+
+- [Validate QType YAML](../How%20To/Observability%20%26%20Debugging/validate_qtype_yaml.md)
+- [CLI Reference](cli.md)

qtype/docs/Tutorials/.pages

@@ -0,0 +1 @@
+title: Tutorials

qtype/docs/Tutorials/01-first-qtype-application.md

@@ -0,0 +1,249 @@
+# Your First QType Application 
+
+**Time:** 15 minutes  
+**Prerequisites:** None  
+**Example:** [`01_hello_world.qtype.yaml`](https://github.com/bazaarvoice/qtype/blob/main/examples/tutorials/01_hello_world.qtype.yaml)
+
+**What you'll learn:** Build a working AI-powered question-answering application and understand the core concepts of QType.
+
+**What you'll build:** A simple app that takes a question, sends it to an AI model, and returns an answer.
+
+---
+
+## Part 1: Your First QType File (5 minutes)
+
+### Create the File
+
+Create a new file called `01_hello_world.qtype.yaml` and add:
+
+```yaml
+id: 01_hello_world
+description: My first QType application
+```
+
+**What this means:**
+
+- Every QType application starts with an `id` - a unique name for your app
+- The `description` helps you remember what the app does (optional but helpful)
+
+---
+
+### Add Your AI Model
+
+Add these lines to your file:
+
+```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
+    inference_params:
+      temperature: 0.7
+
+```
+
+**What this means:**
+
+- `auths:` - different authorization credentials you will use for model invocation (if any)
+- `api_key: ${OPENAI_KEY}` - the api key is read from the environment variable `OPENAI_KEY`
+- `models:` - Where you configure which AI to use
+- `id: gpt-4` - A nickname you'll use to refer to this model
+- `model_id` - The provider's model id.
+- `provider: openai` - Which AI service to use
+- `temperature: 0.7` - Controls creativity (0 = focused, 1 = creative)
+
+**Check your work:**
+
+1. Save the file
+2. Run: `qtype validate 01_hello_world.qtype.yaml`
+4. You should see: `✅ Validation successful`
+
+
+**Using AWS Bedrock instead?** Replace the models section with:
+```yaml
+models:
+  - type: Model
+    id: nova
+    provider: aws-bedrock
+    model_id: amazon.nova-lite-v1:0
+```
+
+And ensure your AWS credentials are configured (`aws configure`).
+
+---
+
+## Part 2: Add Processing Logic (5 minutes)
+
+### Create a Flow
+
+A "flow" is where you define what your app actually does. Add this to your file:
+
+```yaml
+flows:
+  - type: Flow
+    id: simple_example
+    variables:
+      - id: question
+        type: text
+      - id: formatted_prompt
+        type: text
+      - id: answer
+        type: text
+    inputs:
+      - question
+    outputs:
+      - answer
+```
+
+**What this means:**
+
+- `flows:` - The processing logic section
+- `variables:` - Declares the data your app uses:
+  - `question` - What the user asks
+  - `formatted_prompt` - The formatted prompt for the AI
+  - `answer` - What the AI responds
+- `inputs:` and `outputs:` - Which variables go in and out
+
+**Check your work:**
+
+1. Validate again: `qtype validate 01_hello_world.qtype.yaml`
+2. Still should see: `✅ Validation successful`
+
+---
+
+### Add Processing Steps
+
+Now tell QType what to do with the question. Add this inside your flow (after `outputs:`):
+
+```yaml
+    steps:
+      - id: format_prompt
+        type: PromptTemplate
+        template: "You are a helpful assistant. Answer the following question:\n{question}\n"
+        inputs:
+          - question
+        outputs:
+          - formatted_prompt
+
+      - id: llm_step
+        type: LLMInference
+        model: gpt-4
+        inputs:
+          - formatted_prompt
+        outputs:
+          - answer
+```
+
+**What this means:**
+
+- `steps:` - The actual processing instructions
+- **Step 1: PromptTemplate** - Formats your question into a proper prompt
+  - `template:` - Text with placeholders like `{question}`
+  - Takes the user's `question` and creates `formatted_prompt`
+- **Step 2: LLMInference** - Sends the prompt to the AI
+  - `model: gpt-4` - Use the model we defined earlier
+  - Takes `formatted_prompt` and returns `answer`
+
+**Why two steps?** Separating prompt formatting from AI inference makes your app more maintainable and testable.
+
+**Check your work:**
+
+1. Validate: `qtype validate 01_hello_world.qtype.yaml`
+2. Should still pass ✅
+
+---
+
+## Part 3: Run Your Application (5 minutes)
+
+### Set Up Authentication
+
+Create a file called `.env` in the same folder:
+
+```
+OPENAI_KEY=sk-your-key-here
+```
+
+Replace `sk-your-key-here` with your actual OpenAI API key.
+
+---
+
+### Test It!
+
+Run your application:
+
+```bash
+qtype run -i '{"question":"What is 2+2?"}' 01_hello_world.qtype.yaml
+```
+
+**What you should see:**
+```json
+{
+  "answer": "2+2 equals 4."
+}
+```
+
+**Troubleshooting:**
+
+- **"Authentication error"** → Check your API key in `.env`
+- **"Model not found"** → Verify you have access to the model
+- **"Variable not found"** → Check your indentation in the YAML file
+
+---
+
+### Try It With Different Questions
+
+```bash
+# Simple math
+qtype run -i '{"question":"What is the capital of France?"}' 01_hello_world.qtype.yaml
+
+# More complex
+qtype run -i '{"question":"Explain photosynthesis in one sentence"}' 01_hello_world.qtype.yaml
+```
+
+---
+
+## What You've Learned
+
+Congratulations! You've learned:
+
+✅ **Application structure** - Every QType app has an `id`  
+✅ **Models** - How to configure AI providers  
+✅ **Flows** - Where processing logic lives  
+✅ **Variables** - How data moves through your app  
+✅ **Steps** - Individual processing units (PromptTemplate, LLMInference)  
+✅ **Validation** - How to check your work before running  
+
+---
+
+## Next Steps
+
+**Reference the complete example:**
+
+- [`01_hello_world.qtype.yaml`](https://github.com/bazaarvoice/qtype/blob/main/examples/tutorials/01_hello_world.qtype.yaml) - Full working example
+
+**Learn more:**
+
+- [Tutorial: Conversational Chatbot](02-conversational-chatbot.md)
+- [Tutorial: Structured Data](03-structured-data.md)
+- [Call Large Language Models](../How%20To/Invoke%20Models/call_large_language_models.md)
+
+---
+
+## Common Questions
+
+**Q: Why do I need to declare variables?**  
+A: It makes data flow explicit and helps QType validate your app before running it.
+
+**Q: Can I use multiple models in one app?**  
+A: Yes! Define multiple models in the `models:` section and reference them by their `id` in steps.
+
+**Q: My validation passed but I get errors when running. Why?**  
+A: Validation checks structure, but runtime errors often involve authentication or model access. Check your API keys and model permissions.