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

docs/legacy_how_tos/Configuration/telemetry-setup.md

@@ -0,0 +1,259 @@
+# Observe with Telemetry
+
+QType supports telemetry for all applications out of the box -- simply add the [Telemetry](../../Concepts/Core/telemetry.md) field to your application.
+
+QType integrates with popular observability platforms to help you understand, debug, and optimize your LLM applications. This guide covers how to set up telemetry with Phoenix and Langfuse.
+
+## Supported Providers
+
+- **Phoenix** - Open-source LLM observability from Arize AI (default)
+- **Langfuse** - Open-source LLM engineering platform with tracing and analytics
+
+## Phoenix Integration
+
+[Arize Phoenix](https://phoenix.arize.com/) is an open-source platform for LLM observability that runs locally or in the cloud.
+
+### Setting up Phoenix
+First, ensure you have installed the qtype `interpreter`:
+```bash
+pip install qtype[interpreter]
+```
+
+Next, install [Arize Phoenix](https://phoenix.arize.com/):
+```bash
+pip install arize-phoenix
+```
+
+and launch it:
+```bash
+phoenix serve
+```
+
+This launches Phoenix on your local machine and listens for trace data at `http://localhost:6006/v1/traces`.
+
+### Adding Phoenix Telemetry
+
+Add telemetry to your QType application:
+```yaml
+
+```yaml
+id: hello_world
+telemetry:
+  id: hello_world_telemetry
+  endpoint: http://localhost:6006/v1/traces
+flows:
+  - id: simple_chat_example
+    description: A simple stateful chat flow with OpenAI
+    mode: Chat
+    steps:
+      - id: llm_inference_step
+        memory: 
+          id: chat_memory
+        model: 
+          id: gpt-4
+          provider: openai
+          auth: 
+            id: openai_auth
+            type: api_key
+            api_key: ${OPENAI_KEY}
+        system_message: |
+          You are a helpful assistant.
+        inputs:
+          - id: user_message
+            type: ChatMessage
+        outputs:
+          - id: response_message
+            type: ChatMessage
+```
+
+Notice the `telemetry` field with the Phoenix endpoint. The `provider` defaults to `"Phoenix"` so you don't need to specify it.
+
+### Viewing Phoenix Traces
+
+1. Start your application:
+   ```bash
+   qtype serve your-app.qtype.yaml
+   ```
+
+2. Navigate to `http://localhost:8000/ui` and have a conversation
+
+3. View traces at [http://localhost:6006](http://localhost:6006). You'll see a project whose name matches your application id:
+
+   ![Phoenix Projects](./phoenix_projects.png)
+
+4. Click on the project to see the traces of your conversation:
+
+   ![Phoenix Traces](./phoenix_traces.png)
+
+Now you'll have a complete record of all LLM calls and interactions!
+
+## Langfuse Integration
+
+[Langfuse](https://langfuse.com) is an open-source LLM engineering platform that provides tracing, analytics, prompt management, and evaluation capabilities.
+
+### Getting Langfuse Credentials
+
+1. Sign up for [Langfuse Cloud](https://cloud.langfuse.com) or deploy self-hosted
+2. Create a new project
+3. Navigate to Settings → API Keys
+4. Generate a new API key pair (public_key and secret_key)
+5. Store credentials in environment variables:
+   ```bash
+   export LANGFUSE_PUBLIC_KEY="pk-lf-..."
+   export LANGFUSE_SECRET_KEY="sk-lf-..."
+   ```
+
+### Adding Langfuse Telemetry
+
+Configure Langfuse as your telemetry provider:
+
+```yaml
+telemetry:
+  id: langfuse_telemetry
+  provider: Langfuse
+  endpoint: https://cloud.langfuse.com
+  args:
+    public_key: ${LANGFUSE_PUBLIC_KEY}
+    secret_key: ${LANGFUSE_SECRET_KEY}
+```
+
+**Required fields:**
+- **provider**: Must be set to `"Langfuse"`
+- **endpoint**: Langfuse host URL
+  - Cloud: `https://cloud.langfuse.com`
+  - Self-hosted: Your instance URL
+- **args.public_key**: Your Langfuse public key
+- **args.secret_key**: Your Langfuse secret key
+
+### Complete Langfuse Example
+
+```yaml
+id: hello_world_langfuse
+description: A simple chat flow with Langfuse telemetry
+models:
+  - type: Model
+    id: gpt4
+    provider: openai
+    model_id: gpt-4
+    inference_params:
+      temperature: 0.7
+      max_tokens: 512
+    auth: openai_auth
+auths:
+  - type: api_key
+    id: openai_auth
+    api_key: ${OPENAI_KEY}
+memories:
+  - id: chat_memory
+    token_limit: 10000
+flows:
+  - type: Flow
+    id: chat_example
+    interface:
+      type: Conversational
+    variables:
+      - id: user_message
+        type: ChatMessage
+      - id: response
+        type: ChatMessage
+    inputs:
+      - user_message
+    outputs:
+      - response
+    steps:
+      - type: LLMInference
+        id: llm_inference_step
+        model: gpt4
+        memory: chat_memory
+        system_message: "You are a helpful assistant."
+        inputs:
+          - user_message
+        outputs:
+          - response
+telemetry:
+  id: langfuse_telemetry
+  provider: Langfuse
+  endpoint: https://cloud.langfuse.com
+  args:
+    public_key: ${LANGFUSE_PUBLIC_KEY}
+    secret_key: ${LANGFUSE_SECRET_KEY}
+```
+
+### Viewing Langfuse Traces
+
+1. Run your application:
+   ```bash
+   qtype serve examples/chat_with_langfuse.qtype.yaml
+   ```
+
+2. Interact with your application at http://localhost:8000/ui
+
+3. View traces in Langfuse:
+   - Go to https://cloud.langfuse.com
+   - Navigate to your project
+   - View traces in the Tracing tab
+
+### How Langfuse Integration Works
+
+QType integrates with Langfuse via OpenTelemetry's OTLP protocol:
+
+1. Creates an OpenTelemetry TracerProvider with your project name as the service name
+2. Configures an OTLP HTTP exporter that sends spans to Langfuse's `/api/public/otel` endpoint
+3. Uses Basic Authentication with your public_key:secret_key credentials
+4. Automatically instruments LlamaIndex to capture all LLM interactions
+
+All LLM calls, steps, and flows are automatically traced and sent to Langfuse.
+
+## Using AWS Secrets Manager
+
+Both Phoenix and Langfuse support storing credentials in AWS Secrets Manager:
+
+```yaml
+secret_manager:
+  type: aws
+  region: us-east-1
+
+telemetry:
+  id: langfuse_telemetry
+  provider: Langfuse
+  endpoint: https://cloud.langfuse.com
+  args:
+    public_key:
+      secret: langfuse-credentials
+      key: public_key
+    secret_key:
+      secret: langfuse-credentials
+      key: secret_key
+```
+
+## Troubleshooting
+
+### No traces appearing
+
+**Phoenix:**
+- Verify Phoenix is running on the correct port (default: 6006)
+- Check the endpoint URL in your telemetry configuration
+- Ensure no firewall is blocking the connection
+
+**Langfuse:**
+- Verify your credentials are correct (public_key starts with `pk-lf-`, secret_key starts with `sk-lf-`)
+- Check the endpoint URL (should NOT include `/api/public/otel` - this is added automatically)
+- Ensure your Langfuse project exists
+- Check application logs for authentication errors
+- Verify no extra whitespace in credentials
+
+### Self-hosted Langfuse
+
+If using self-hosted Langfuse, set the endpoint to your instance URL:
+```yaml
+telemetry:
+  provider: Langfuse
+  endpoint: https://langfuse.yourcompany.com
+```
+
+## Learn More
+
+- [Phoenix Documentation](https://phoenix.arize.com/)
+- [Langfuse Documentation](https://langfuse.com/docs)
+- [Langfuse OpenTelemetry Integration](https://langfuse.com/docs/integrations/opentelemetry)
+- [QType Telemetry Concepts](../../Concepts/Core/telemetry.md)

docs/legacy_how_tos/Data Types/custom-types.md

@@ -0,0 +1,52 @@
+# Create Custom Types
+
+QType allows you to create custom types for variable inputs and outputs. 
+
+Custom types must be defined the in `types` list in your Application. They _can not_ be defined in-line in variables.
+
+Internally, custom types are mapped to pydantic objects.
+
+--8<-- "components/CustomType.md"
+
+## A Simple Example
+
+The following example illustrates the key features of custom types:
+
+* The custom types `Arthor` and `Book` are defined. Those terms can be used as a `type` in any variable.
+* All fields of the custom types should be other custom types, primitive types, or [domain types](./domain-types.md)
+* A `?` can be used after the type to indicate it is optional. In this case, it will be `None` if not provided.
+* A `list[type]` can be used to indicate a list.
+* Forward references are allowed -- `Book` references `Arthor` which is defined later
+
+
+
+```yaml
+id: valid_custom_type
+types:
+  - id: Book
+    properties:
+      title: text
+      author: Author # <-- this is a forward reference
+      year: int?
+      tags: "list[text]"
+      published: boolean
+  - id: Author
+    properties:
+      id: int
+      name: text
+flows:
+  - id: my_person_flow
+    mode: Complete
+    steps:
+      - id: prompt_template
+        template: >
+          You are a helpful assistant. Please provide information about the following book:
+          {book}
+        inputs:
+          - id: book
+            type: Book
+        outputs:
+          - id: prompt_format
+            type: text
+```
+

docs/legacy_how_tos/Data Types/domain-types.md

@@ -0,0 +1,113 @@
+# Use Domain Types
+
+QType provides several built-in domain types that represent common AI and chat application data structures. 
+
+## Overview of Domain Types
+
+QType includes these key domain types:
+
+- **`ChatMessage`** - Structured chat messages with roles and content blocks
+- **`ChatContent`** - Individual content blocks (text, images, etc.) within messages  
+- **`Embedding`** - Vector embeddings with metadata
+- **`MessageRole`** - Enumeration of message sender roles
+
+These types help you build robust AI applications with proper data structure and validation.
+
+## ChatMessage: The Foundation of Conversational AI
+
+--8<-- "components/ChatMessage.md"
+
+### Understanding ChatMessage Structure
+
+`ChatMessage` is a composite type that represents a single message in a conversation:
+
+```yaml
+# Basic chat message structure
+variables:
+  - id: user_input
+    type: ChatMessage
+    # Will contain: role + list of content blocks
+    
+  - id: ai_response  
+    type: ChatMessage
+    # AI's response with assistant role
+```
+
+### Message Roles
+
+--8<-- "components/MessageRole.md"
+
+The `MessageRole` enum defines who sent the message:
+
+- **`user`** - End user input
+- **`assistant`** - AI model response  
+- **`system`** - System instructions/context
+- **`tool`** - Tool execution results
+- **`function`** - Function call results (legacy)
+- **`developer`** - Developer notes/debugging
+- **`model`** - Direct model output
+- **`chatbot`** - Chatbot-specific role
+
+### Content Blocks
+
+--8<-- "components/ChatContent.md"
+
+Each `ChatMessage` contains one or more `ChatContent` blocks:
+
+## Practical Examples
+
+### Basic Chat Flow
+
+The following creates a simple chat experience that is multi-modal: since `ChatMessage` contains mupltiple blocks, the blocks can be of different multimedia types.
+
+```yaml
+id: simple_chat
+flows:
+  - id: chat_conversation
+    mode: Chat
+    steps:
+      - id: llm_step
+        model:
+          id: gpt-4o
+          provider: openai
+          auth:
+            id: openai_auth
+            type: api_key
+            api_key: ${OPENAI_KEY}
+        system_message: |
+          You are a helpful AI assistant.
+        inputs:
+          - id: user_message
+            type: ChatMessage  # User's input message
+        outputs:
+          - id: assistant_response
+            type: ChatMessage  # AI's response message
+```
+
+## Working with Embeddings
+
+--8<-- "components/Embedding.md"
+
+### Basic Embedding Usage
+
+```yaml
+id: embedding_example
+models:
+  - id: text_embedder
+    provider: openai
+    model_id: text-embedding-3-large
+    dimensions: 3072
+    auth: openai_auth
+
+flows:
+  - id: create_embeddings
+    steps:
+      - id: embed_step
+        model: text_embedder
+        inputs:
+          - id: source_text
+            type: text
+        outputs:
+          - id: text_embedding
+            type: Embedding  # Vector + metadata
+```

docs/legacy_how_tos/Debugging/visualize-apps.md

@@ -0,0 +1,147 @@
+# Visualize Application Architecture
+
+QType includes a  visualization feature that automatically generates Mermaid flowchart diagrams from your QType specifications. These visual diagrams help you understand the structure and flow of your AI applications at a glance.
+
+## The `qtype visualize` Command
+
+The `visualize` command analyzes your QType YAML specification and generates a comprehensive Mermaid diagram showing:
+
+- **Flows** and their execution steps
+- **Shared resources** like models, indexes, authentication, and memory
+- **Connections** between components
+- **Telemetry** and observability configuration
+
+## Basic Usage
+
+To generate a visualization of your QType application:
+
+```bash
+qtype visualize your_application.qtype.yaml
+```
+
+This will:
+1. Load and validate your QType specification
+2. Generate a Mermaid diagram
+3. Open the diagram in your default browser for viewing
+
+## Output Formats
+
+The `visualize` command supports multiple output formats:
+
+### Display in Browser (Default)
+```bash
+qtype visualize examples/chat_with_telemetry.qtype.yaml
+```
+Opens the diagram directly in your browser for immediate viewing.
+
+### Save as Mermaid Source
+```bash
+qtype visualize examples/chat_with_telemetry.qtype.yaml -o diagram.mmd
+```
+Saves the raw Mermaid markup to a `.mmd` or `.mermaid` file.
+
+### Export as SVG
+```bash
+qtype visualize examples/chat_with_telemetry.qtype.yaml -o diagram.svg
+```
+Generates a scalable vector graphics file perfect for documentation.
+
+### Export as PNG
+```bash
+qtype visualize examples/chat_with_telemetry.qtype.yaml -o diagram.png
+```
+Creates a raster image file for presentations or embedding.
+
+### Save Without Opening Browser
+```bash
+qtype visualize examples/chat_with_telemetry.qtype.yaml -o diagram.svg --no-display
+```
+Use the `--no-display` flag to save files without opening the browser.
+
+## Example: Chat with Telemetry
+
+Let's look at a practical example using the `chat_with_telemetry.qtype.yaml` file:
+
+```yaml
+id: hello_world
+flows:
+  - id: chat_example
+    description: A simple chat flow with OpenAI
+    mode: Chat
+    steps:
+      - id: llm_inference_step
+        model: 
+          id: gpt-4
+          provider: openai
+          auth: 
+            id: openai_auth
+            type: api_key
+            api_key: ${OPENAI_KEY}
+        system_message: |
+          You are a helpful assistant.
+        inputs:
+          - id: user_message
+            type: ChatMessage
+        outputs:
+          - id: response
+            type: ChatMessage
+telemetry:
+  id: hello_world_telemetry
+  endpoint: http://localhost:6006/v1/traces
+```
+
+Running the visualization command:
+
+```bash
+qtype visualize examples/chat_with_telemetry.qtype.yaml -o chat_with_telemetry.mermaid
+```
+
+Generates this Mermaid diagram:
+
+
+## Understanding the Diagram
+
+The generated diagram uses intuitive icons and colors to represent different components:
+
+### Application Structure
+- **📱 Application**: The outermost container showing your application ID
+- **💬 Chat Flows** / **🔄 Flows**: Individual flows with their descriptions
+- **✨ Steps**: Individual steps within flows (with different shapes for different step types)
+
+### Shared Resources
+- **🔐 Authentication**: API keys, OAuth, and other auth providers
+- **✨ Models**: LLM models with their providers (OpenAI, Bedrock, etc.)
+- **🗂️ Indexes**: Vector and document indexes for retrieval
+- **🧠 Memory**: Conversation memory stores
+- **🔧 Tools**: API tools, Python functions, and other capabilities
+
+### Observability
+- **📊 Telemetry**: OpenTelemetry tracing endpoints
+- **📡 Telemetry Sink**: Where traces and metrics are sent
+
+### Connections
+- **Solid arrows** (`-->`) show data flow between steps
+- **Dotted arrows** (`-.->`) show resource dependencies and relationships
+
+## Command Reference
+
+```
+qtype visualize [OPTIONS] SPEC_FILE
+
+Arguments:
+  SPEC_FILE    Path to the QType YAML file to visualize
+
+Options:
+  -o, --output PATH     Save diagram to file (.mmd, .mermaid, .svg, .png)
+  -nd, --no-display     Don't open diagram in browser (default: False)
+  -h, --help           Show help message
+```
+
+
+## Tips for Better Visualizations
+
+1. **Use descriptive IDs**: Clear, descriptive IDs for flows and steps make diagrams more readable
+2. **Add descriptions**: Flow descriptions appear in the diagram and provide valuable context
+3. **Group related functionality**: Organize steps logically within flows
+4. **Keep flows focused**: Smaller, focused flows are easier to understand than large, complex ones
+

docs/legacy_how_tos/Tools/api-tools.md

@@ -0,0 +1,29 @@
+# Create Tools from OpenAPI Spec
+
+QType allows you to automatically convert openapi specs to tools. This lets you make arbitrary calls in your flows, or connect them to agents.
+
+This tutorial will walk you through creating convertting an openapi spec into QType specification that can be used in your applications.
+
+## Prerequisites
+
+Before following this tutorial, make sure you understand:
+
+- [Variables and types](../../Concepts/Core/variable.md) in QType
+- [Primitive types](../../components/PrimitiveTypeEnum.md) 
+- [Domain types](../Data%20Types/domain-types.md)
+- [Custom types](../Data%20Types/custom-types.md)
+
+## Overview
+
+The `qtype convert api` command creates [tools](../../Concepts/Core/tool.md), [AuthorizationProvider](../../Concepts/Core/authorization-provider.md), and [Custom types](../Data%20Types/custom-types.md) for each endpoint in the api.
+
+
+## Converting the API to QType Tools
+
+Via the QType  CLI:
+
+```bash
+qtype convert api spec.oas.yaml -o api_tools.qtype.yaml
+```
+
+