{"id":8388,"library":"orq-ai-sdk","title":"Orq AI SDK","description":"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.","status":"active","version":"4.7.7","language":"en","source_language":"en","source_url":"https://github.com/orq-ai/orq-python","tags":["AI","LLM","API Client","Generative AI","Orchestration","MLOps"],"install":[{"cmd":"pip install orq-ai-sdk","lang":"bash","label":"pip"},{"cmd":"poetry add orq-ai-sdk","lang":"bash","label":"Poetry"},{"cmd":"uv add orq-ai-sdk","lang":"bash","label":"uv"}],"dependencies":[{"reason":"Required Python version for the SDK.","package":"python","version":">=3.10"}],"imports":[{"note":"The main client class `Orq` is directly available under the `orq_ai_sdk` package.","wrong":"import orq_ai_sdk; client = orq_ai_sdk.Orq()","symbol":"Orq","correct":"from orq_ai_sdk import Orq"}],"quickstart":{"code":"import os\nfrom orq_ai_sdk import Orq\n\n# Initialize the Orq client with your API key\n# Get your API key from the Orq.ai dashboard (Workspace Settings -> API Keys)\n# It's recommended to use environment variables for API keys.\n\ndef main():\n    with Orq(\n        api_key=os.environ.get(\"ORQ_API_KEY\", \"\"),\n        # environment=\"production\", # Optional: specify environment\n        # identity_id=123 # Optional: link requests to an identity\n    ) as client:\n        try:\n            # Example: Invoke a deployment\n            # Replace \"your-deployment-key\" with the actual key from your Orq.ai deployment\n            generation = client.deployments.invoke(\n                key=\"your-deployment-key\",\n                context={\n                    \"user_id\": \"test_user\", \n                    \"session_id\": \"session_123\"\n                },\n                inputs={\n                    \"query\": \"What is the capital of France?\"\n                },\n                metadata={\n                    \"source\": \"quickstart\"\n                },\n            )\n            if generation.choices:\n                print(\"Generated content:\", generation.choices[0].message.content)\n            else:\n                print(\"No content generated.\")\n\n        except Exception as e:\n            print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    main()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The SDK is currently in beta. Breaking changes may be introduced between versions without a major version update.","severity":"breaking","affected_versions":"<5.0.0"},{"fix":"Regularly update your Python environment to actively supported versions (>=3.10 is currently required). Monitor the Python EOL schedule and plan upgrades accordingly.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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:`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Debug logging can expose sensitive information (e.g., API keys) in logs if enabled in production environments.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The API key provided is missing, invalid, or not correctly configured for your workspace on the Orq.ai platform.","error":"orq_ai_sdk.OrqError: 401 Unauthorized"},{"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.","cause":"You have exceeded the API rate limits or usage quota defined for your Orq.ai plan.","error":"orq_ai_sdk.OrqError: 429 Too Many Requests"},{"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.","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.","error":"AttributeError: 'Orq' object has no attribute 'deployments'"}]}