Deployments SDK Reference - Orq.ai Documentation

Deployments

Invoke a Deployment

Invoke a deployment with a given payload

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.deployments.invoke(key="<key>", stream=False, identity={
        "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "display_name": "Jane Doe",
        "email": "jane.doe@example.com",
        "metadata": [
            {
                "department": "Engineering",
                "role": "Senior Developer",
            },
        ],
        "logo_url": "https://example.com/avatars/jane-doe.jpg",
        "tags": [
            "hr",
            "engineering",
        ],
    }, documents=[
        {
            "text": "The refund policy allows customers to return items within 30 days of purchase for a full refund.",
            "metadata": {
                "file_name": "refund_policy.pdf",
                "file_type": "application/pdf",
                "page_number": 1,
            },
        },
        {
            "text": "Premium members receive free shipping on all orders over $50.",
            "metadata": {
                "file_name": "membership_benefits.md",
                "file_type": "text/markdown",
            },
        },
    ])

    assert res is not None

    # Handle response
    print(res)

Show Parameters

{
    "key": str,  # required
    "stream": Optional[bool],
    "inputs": Dict[str, Any],
    "context": Dict[str, Any],
    "prefix_messages": Union[SystemMessage, DeveloperMessage, UserMessage, AssistantMessage, ToolMessage],
    "messages": Union[MessagesSystemMessage, MessagesDeveloperMessage, MessagesUserMessage, MessagesAssistantMessage, MessagesToolMessage],
    "identity": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],
        "logo_url": Optional[str],
        "tags": List[str],
    },
    "file_ids": List[str],
    "metadata": Dict[str, Any],
    "extra_params": Dict[str, Any],
    "documents": {  # optional
        "text": str,  # required
        "metadata": {  # optional
            "file_name": Optional[str],
            "file_type": Optional[str],
            "page_number": Optional[float],
        },
    },
    "invoke_options": {  # optional
        "include_retrievals": Optional[bool],
        "include_usage": Optional[bool],
        "mock_response": Optional[str],
    },
    "thread": {  # optional
        "id": str,  # required
        "tags": List[str],
    },
    "knowledge_filter": Union[Dict[str, KnowledgeFilter1], And, Or],
}

Show Response

{
    "id": str,
    "created": date,
    "object": Literal["chat", "completion", "image"],
    "model": str,
    "provider": Literal["openai", "groq", "cohere", "azure", "aws", "google", "google-ai", "huggingface", "togetherai", "perplexity", "anthropic", "leonardoai", "fal", "nvidia", "jina", "elevenlabs", "cerebras", "openailike", "bytedance", "mistral", "deepseek", "contextualai", "moonshotai", "zai", "minimax", "xai", "alibaba", "tensorix", "scaleway", "hcompany", "inceptron", "wafer", "slack", "orq"],
    "is_final": bool,
    "integration_id": Optional[str],
    "telemetry": {
        "trace_id": str,
        "span_id": str,
    },
    "finalized": date,
    "system_fingerprint": OptionalNullable[str],
    "retrievals": {  # optional
        "document": str,
        "metadata": {
            "file_name": str,
            "page_number": Nullable[float],
            "file_type": str,
            "rerank_score": Optional[float],
            "search_score": float,
        },
    },
    "provider_response": Optional[Any],
    "usage": {  # optional
        "total_tokens": Optional[float],
        "prompt_tokens": Optional[float],
        "completion_tokens": Optional[float],
        "prompt_tokens_details": {  # optional
            "cached_tokens": OptionalNullable[float],
        },
        "completion_tokens_details": {  # optional
            "reasoning_tokens": OptionalNullable[float],
        },
    },
    "choices": {
        "index": float,
        "message": Union[Message1, Message2, Message3],
        "finish_reason": OptionalNullable[str],
    },
}

List Deployments

Returns a list of your deployments. The deployments are returned sorted by creation date, with the most recent deployments appearing first.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.deployments.list(limit=10)

    # Handle response
    print(res)

Show Parameters

{
    "limit": Optional[int],
    "starting_after": Optional[str],
    "ending_before": Optional[str],
}

Show Response

{
    "object": Literal["list"],
    "data": {
        "id": str,
        "created": str,
        "updated": str,
        "key": str,
        "description": str,
        "prompt_config": {
            "tools": {
                "display_name": Optional[str],
                "type": Literal["function"],
                "function": {
                    "name": str,
                    "description": Optional[str],
                    "strict": Optional[bool],
                    "parameters": {
                        "type": DeploymentsDeploymentsResponseType,
                        "properties": Dict[str, Any],
                        "required": List[str],
                        "additional_properties": Optional[Literal[False]],
                    },
                },
                "id": Optional[float],
            },
            "model": str,
            "model_type": Literal["chat", "completion", "embedding", "image", "tts", "stt", "rerank", "ocr", "moderation", "vision"],
            "model_parameters": {
                "temperature": Optional[float],
                "max_tokens": Optional[float],
                "top_k": Optional[float],
                "top_p": Optional[float],
                "frequency_penalty": Optional[float],
                "presence_penalty": Optional[float],
                "num_images": Optional[float],
                "seed": Optional[float],
                "format_": Optional[Literal["url", "b64_json", "text", "json_object"]],
                "dimensions": Optional[str],
                "quality": Optional[str],
                "style": Optional[str],
                "response_format": Union[DeploymentsResponseFormat1, DeploymentsResponseFormat2, DeploymentsResponseFormat3, DeploymentsResponseFormat4, DeploymentsResponseFormat5, DeploymentsResponseFormat6],
                "photo_real_version": Optional[Literal["v1", "v2"]],
                "encoding_format": Optional[Literal["float", "base64"]],
                "reasoning_effort": Optional[Literal["none", "disable", "minimal", "low", "medium", "high"]],
                "budget_tokens": Optional[float],
                "verbosity": Optional[Literal["low", "medium", "high"]],
                "thinking_level": Optional[Literal["low", "medium", "high"]],
            },
            "provider": Literal["openai", "groq", "cohere", "azure", "aws", "google", "google-ai", "huggingface", "togetherai", "perplexity", "anthropic", "leonardoai", "fal", "nvidia", "jina", "elevenlabs", "cerebras", "openailike", "bytedance", "mistral", "deepseek", "contextualai", "moonshotai", "zai", "minimax", "xai", "alibaba", "tensorix", "scaleway", "hcompany", "inceptron", "wafer", "slack", "orq"],
            "messages": {
                "role": Literal["system", "developer", "assistant", "user", "exception", "tool", "prompt", "correction", "expected_output"],
                "content": Union[str, List[DeploymentsContent2]],
                "tool_calls": {  # optional
                    "id": Optional[str],
                    "index": Optional[float],
                    "type": Literal["function"],
                    "function": {
                        "name": str,
                        "arguments": str,
                    },
                },
                "tool_call_id": OptionalNullable[str],
            },
        },
        "version": str,
    },
    "has_more": bool,
}

Get Config

Retrieve the deployment configuration

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.deployments.get_config(key="<key>", identity={
        "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "display_name": "Jane Doe",
        "email": "jane.doe@example.com",
        "metadata": [
            {
                "department": "Engineering",
                "role": "Senior Developer",
            },
        ],
        "logo_url": "https://example.com/avatars/jane-doe.jpg",
        "tags": [
            "hr",
            "engineering",
        ],
    }, documents=[
        {
            "text": "The refund policy allows customers to return items within 30 days of purchase for a full refund.",
            "metadata": {
                "file_name": "refund_policy.pdf",
                "file_type": "application/pdf",
                "page_number": 1,
            },
        },
        {
            "text": "Premium members receive free shipping on all orders over $50.",
            "metadata": {
                "file_name": "membership_benefits.md",
                "file_type": "text/markdown",
            },
        },
    ])

    assert res is not None

    # Handle response
    print(res)

Show Parameters

{
    "key": str,  # required
    "inputs": Dict[str, Any],
    "context": Dict[str, Any],
    "prefix_messages": Union[PrefixMessagesSystemMessage, PrefixMessagesDeveloperMessage, PrefixMessagesUserMessage, PrefixMessagesAssistantMessage, PrefixMessagesToolMessage],
    "messages": Union[DeploymentGetConfigMessagesSystemMessage, DeploymentGetConfigMessagesDeveloperMessage, DeploymentGetConfigMessagesUserMessage, DeploymentGetConfigMessagesAssistantMessage, DeploymentGetConfigMessagesToolMessage],
    "identity": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],
        "logo_url": Optional[str],
        "tags": List[str],
    },
    "file_ids": List[str],
    "metadata": Dict[str, Any],
    "extra_params": Dict[str, Any],
    "documents": {  # optional
        "text": str,  # required
        "metadata": {  # optional
            "file_name": Optional[str],
            "file_type": Optional[str],
            "page_number": Optional[float],
        },
    },
    "invoke_options": {  # optional
        "include_retrievals": Optional[bool],
        "include_usage": Optional[bool],
        "mock_response": Optional[str],
    },
    "thread": {  # optional
        "id": str,  # required
        "tags": List[str],
    },
    "knowledge_filter": Union[Dict[str, DeploymentGetConfigKnowledgeFilter1], DeploymentGetConfigKnowledgeFilterAnd, DeploymentGetConfigKnowledgeFilterOr],
}

Show Response

{
    "id": str,
    "provider": str,
    "model": str,
    "type": Optional[Literal["chat", "completion", "embedding", "image", "tts", "stt", "rerank", "ocr", "moderation", "vision"]],
    "version": str,
    "messages": {
        "role": Literal["system", "developer", "assistant", "user", "exception", "tool", "prompt", "correction", "expected_output"],
        "content": Union[str, List[DeploymentGetConfigContentDeploymentsResponse2]],
        "tool_calls": {  # optional
            "id": Optional[str],
            "index": Optional[float],
            "type": Literal["function"],
            "function": {
                "name": str,
                "arguments": str,
            },
        },
        "tool_call_id": OptionalNullable[str],
    },
    "parameters": {
        "temperature": Optional[float],
        "max_tokens": Optional[float],
        "top_k": Optional[float],
        "top_p": Optional[float],
        "frequency_penalty": Optional[float],
        "presence_penalty": Optional[float],
        "num_images": Optional[float],
        "seed": Optional[float],
        "format_": Optional[Literal["url", "b64_json", "text", "json_object"]],
        "dimensions": Optional[str],
        "quality": Optional[str],
        "style": Optional[str],
        "response_format": Union[ResponseFormat1, ResponseFormat2, ResponseFormat3, ResponseFormat4, ResponseFormat5, ResponseFormat6],
        "photo_real_version": Optional[Literal["v1", "v2"]],
        "encoding_format": Optional[Literal["float", "base64"]],
        "reasoning_effort": Optional[Literal["none", "disable", "minimal", "low", "medium", "high"]],
        "budget_tokens": Optional[float],
        "verbosity": Optional[Literal["low", "medium", "high"]],
        "thinking_level": Optional[Literal["low", "medium", "high"]],
    },
    "tools": {  # optional
        "type": Literal["function"],
        "function": {
            "name": str,
            "description": Optional[str],
            "parameters": Dict[str, Any],
        },
    },
}

Stream a Deployment

Stream deployment generation. Only supported for completions and chat completions.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.deployments.stream(key="<key>", identity={
        "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "display_name": "Jane Doe",
        "email": "jane.doe@example.com",
        "metadata": [
            {
                "department": "Engineering",
                "role": "Senior Developer",
            },
        ],
        "logo_url": "https://example.com/avatars/jane-doe.jpg",
        "tags": [
            "hr",
            "engineering",
        ],
    }, documents=[
        {
            "text": "The refund policy allows customers to return items within 30 days of purchase for a full refund.",
            "metadata": {
                "file_name": "refund_policy.pdf",
                "file_type": "application/pdf",
                "page_number": 1,
            },
        },
        {
            "text": "Premium members receive free shipping on all orders over $50.",
            "metadata": {
                "file_name": "membership_benefits.md",
                "file_type": "text/markdown",
            },
        },
    ])

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)

Show Parameters

{
    "key": str,  # required
    "inputs": Dict[str, Any],
    "context": Dict[str, Any],
    "prefix_messages": Union[DeploymentStreamPrefixMessagesSystemMessage, DeploymentStreamPrefixMessagesDeveloperMessage, DeploymentStreamPrefixMessagesUserMessage, DeploymentStreamPrefixMessagesAssistantMessage, DeploymentStreamPrefixMessagesToolMessage],
    "messages": Union[DeploymentStreamMessagesSystemMessage, DeploymentStreamMessagesDeveloperMessage, DeploymentStreamMessagesUserMessage, DeploymentStreamMessagesAssistantMessage, DeploymentStreamMessagesToolMessage],
    "identity": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],
        "logo_url": Optional[str],
        "tags": List[str],
    },
    "file_ids": List[str],
    "metadata": Dict[str, Any],
    "extra_params": Dict[str, Any],
    "documents": {  # optional
        "text": str,  # required
        "metadata": {  # optional
            "file_name": Optional[str],
            "file_type": Optional[str],
            "page_number": Optional[float],
        },
    },
    "invoke_options": {  # optional
        "include_retrievals": Optional[bool],
        "include_usage": Optional[bool],
        "mock_response": Optional[str],
    },
    "thread": {  # optional
        "id": str,  # required
        "tags": List[str],
    },
    "knowledge_filter": Union[Dict[str, DeploymentStreamKnowledgeFilter1], DeploymentStreamKnowledgeFilterAnd, DeploymentStreamKnowledgeFilterOr],
}

​Deployments

​Invoke a Deployment

​List Deployments

​Get Config

​Stream a Deployment

Deployments

Invoke a Deployment

List Deployments

Get Config

Stream a Deployment