Orq AI SDK

4.7.7 · active · verified Thu Apr 16

The `orq-ai-sdk` is a Python Client SDK for the Orq API, enabling developers to build, ship, and optimize LLM applications at scale. It provides a type-safe interface for interacting with Orq.ai's platform functionalities, including prompt management, model routing, RAG (Retrieval Augmented Generation), observability, and evaluation. The SDK supports both synchronous and asynchronous operations and is actively maintained with regular updates.

Common errors

```
orq_ai_sdk.OrqError: 401 Unauthorized
```
cause The API key provided is missing, invalid, or not correctly configured for your workspace on the Orq.ai platform.

fix Ensure the `ORQ_API_KEY` environment variable is set with a valid key, or pass it directly (`api_key="your_key"`). Verify your API key in the Orq.ai dashboard (Workspace Settings -> API Keys) and ensure it has the necessary permissions.
```
orq_ai_sdk.OrqError: 429 Too Many Requests
```
cause You have exceeded the API rate limits or usage quota defined for your Orq.ai plan.

fix Review your API usage and quota limits on the Orq.ai dashboard. Consider implementing retry logic with exponential backoff in your application, or contact Orq.ai support to discuss upgrading your plan.
```
AttributeError: 'Orq' object has no attribute 'deployments'
```
cause Attempting to access a sub-resource (e.g., `client.deployments`) that either does not exist, is named differently in your SDK version, or the client was not properly initialized.

fix Ensure your `Orq` client instance is correctly initialized. Consult the official Orq.ai Python SDK documentation for the exact API structure and available resources for your installed version. Upgrade the SDK to the latest version if you expect a specific resource to be available.

Warnings

breaking The SDK is currently in beta. Breaking changes may be introduced between versions without a major version update.
Fix: Pin your usage to a specific package version (`pip install orq-ai-sdk==X.Y.Z`) to avoid unexpected breaking changes and manually review changelogs before upgrading.
gotcha Python version support policy: Once a Python version reaches its official end-of-life, a 3-month grace period is provided. After this period, the minimum supported Python version in the SDK will be updated, potentially breaking older environments.
Fix: Regularly update your Python environment to actively supported versions (>=3.10 is currently required). Monitor the Python EOL schedule and plan upgrades accordingly.
gotcha Resource management: The `Orq` client uses underlying HTTPX clients. In long-lived applications (e.g., servers), not using the client as a context manager (`with Orq(...) as client:`) can lead to unclosed HTTP connections and resource leaks.
Fix: Always initialize the `Orq` client within a `with` statement: `with Orq(...) as client:` to ensure proper closing of resources. For async operations, use `async with Orq(...) as client:`.
gotcha Debug logging can expose sensitive information (e.g., API keys) in logs if enabled in production environments.
Fix: Only enable debug logging (`debug_logger` parameter or `ORQ_DEBUG` environment variable) during local development. Never use it in production where logs might be accessible.

Install

pip install orq-ai-sdk pip
poetry add orq-ai-sdk Poetry
uv add orq-ai-sdk uv

Imports

Orq
wrong:
```
import orq_ai_sdk; client = orq_ai_sdk.Orq()
```
correct:
```
from orq_ai_sdk import Orq
```
The main client class `Orq` is directly available under the `orq_ai_sdk` package.

Quickstart

This quickstart demonstrates how to initialize the `Orq` client using an API key from an environment variable and then invoke a deployment. Ensure `ORQ_API_KEY` is set in your environment. Replace `"your-deployment-key"` with an actual deployment key from your Orq.ai workspace. The client supports context managers for proper resource management, especially in long-lived applications.

import os
from orq_ai_sdk import Orq

# Initialize the Orq client with your API key
# Get your API key from the Orq.ai dashboard (Workspace Settings -> API Keys)
# It's recommended to use environment variables for API keys.

def main():
    with Orq(
        api_key=os.environ.get("ORQ_API_KEY", ""),
        # environment="production", # Optional: specify environment
        # identity_id=123 # Optional: link requests to an identity
    ) as client:
        try:
            # Example: Invoke a deployment
            # Replace "your-deployment-key" with the actual key from your Orq.ai deployment
            generation = client.deployments.invoke(
                key="your-deployment-key",
                context={
                    "user_id": "test_user", 
                    "session_id": "session_123"
                },
                inputs={
                    "query": "What is the capital of France?"
                },
                metadata={
                    "source": "quickstart"
                },
            )
            if generation.choices:
                print("Generated content:", generation.choices[0].message.content)
            else:
                print("No content generated.")

        except Exception as e:
            print(f"An error occurred: {e}")

if __name__ == "__main__":
    main()

view raw JSON →