### Install orq-ai-sdk using uv, pip, or poetry

Source: https://github.com/orq-ai/orq-python/blob/main/README.md

This section details how to install the orq-ai-sdk using different Python package managers. It covers uv for fast installation, pip as the default, and poetry for dependency management.

```bash
uv add orq-ai-sdk
```

```bash
pip install orq-ai-sdk
```

```bash
poetry add orq-ai-sdk
```

--------------------------------

### Install orq-ai-sdk with uv

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/README.md

Installs the orq-ai-sdk package using uv, a fast Python package installer and resolver, recommended for its speed and modern tooling capabilities.

```bash
uv add orq-ai-sdk
```

--------------------------------

### Prompt Configuration Example (JSON)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/createpromptrequestbody.md

This snippet shows an example of the JSON structure for configuring a prompt. It includes the model to be used, a list of messages with roles and content, and optional parameters like temperature and max_tokens. This is a required field or `prompt_config` must be provided.

```JSON
{
"model": "openai/gpt-4o",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant"
},
{
"role": "user",
"content": "What is the weather today?"
}
],
"temperature": 0.7,
"max_tokens": 1000
}
```

--------------------------------

### Load Balancer Configuration Example

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/createchatcompletionorq.md

Defines how to configure load balancing for requests across different models. This example shows a Python list of dictionaries, where each dictionary specifies a model and its associated weight for distributing requests. Weights should sum to 1.0.

```python
[
  {
    "model": "openai/gpt-4o",
    "weight": 0.7
  },
  {
    "model": "anthropic/claude-3-5-sonnet",
    "weight": 0.3
  }
]
```

--------------------------------

### Install orq-ai-sdk with poetry

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/README.md

Installs the orq-ai-sdk package using Poetry, a modern tool for dependency management and package publishing, which uses a single pyproject.toml file.

```bash
poetry add orq-ai-sdk
```

--------------------------------

### Input Variable Example

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/createchatcompletionorq.md

Illustrates the structure for providing input variables to be used in prompt messages. These variables, defined using {{variableName}} syntax, allow for dynamic content insertion. This example shows a JSON object with customer and product details.

```json
{
  "customer_name": "John Smith",
  "product_name": "Premium Plan",
  "issue_type": "billing"
}
```

--------------------------------

### Install orq-ai-sdk with pip

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/README.md

Installs the orq-ai-sdk package using pip, the default package installer for Python, allowing easy management of packages from PyPI via the command line.

```bash
pip install orq-ai-sdk
```

--------------------------------

### Create Contact Synchronously with Orq Python SDK

Source: https://github.com/orq-ai/orq-python/blob/main/USAGE.md

This example shows how to create a new contact using the Orq Python SDK in a synchronous manner. It requires the 'orq-ai-sdk' library and an ORQ_API_KEY environment variable. The function takes a dictionary representing contact details as input and returns the API response.

```python
# Synchronous Example
from orq_ai_sdk import Orq
import os


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

    res = orq.contacts.create(request={
        "external_id": "user_12345",
        "display_name": "Jane Smith",
        "email": "jane.smith@example.com",
        "avatar_url": "https://example.com/avatars/jane-smith.jpg",
        "tags": [
            "premium",
            "beta-user",
            "enterprise",
        ],
        "metadata": {
            "department": "Engineering",
            "role": "Senior Developer",
            "subscription_tier": "premium",
            "last_login": "2024-01-15T10:30:00Z",
        },
    })

    # Handle response
    print(res)
```

--------------------------------

### Create Datasource - Python SDK Example

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/sdks/knowledge/README.md

This Python code snippet demonstrates how to use the orq-ai-sdk to create a new datasource. It requires an API key and specifies the knowledge ID as a parameter. The example shows how to instantiate the Orq client, call the `create_datasource` method, and handle the response.

```python
from orq_ai_sdk import Orq
import os


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

    res = orq.knowledge.create_datasource(knowledge_id="<id>")

    # Handle response
    print(res)

```

--------------------------------

### Create Contact Asynchronously with Orq Python SDK

Source: https://github.com/orq-ai/orq-python/blob/main/USAGE.md

This example demonstrates how to create a new contact using the Orq Python SDK asynchronously. It utilizes the 'asyncio' library and requires the 'orq-ai-sdk' and an ORQ_API_KEY. The asynchronous 'create_async' method is used for non-blocking operations.

```python
# Asynchronous Example
import asyncio
from orq_ai_sdk import Orq
import os

async def main():

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

        res = await orq.contacts.create_async(request={
            "external_id": "user_12345",
            "display_name": "Jane Smith",
            "email": "jane.smith@example.com",
            "avatar_url": "https://example.com/avatars/jane-smith.jpg",
            "tags": [
                "premium",
                "beta-user",
                "enterprise",
            ],
            "metadata": {
                "department": "Engineering",
                "role": "Senior Developer",
                "subscription_tier": "premium",
                "last_login": "2024-01-15T10:30:00Z",
            },
        })

        # Handle response
        print(res)

asyncio.run(main())
```

--------------------------------

### Define Assistant Message in Python

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/deploymentstreammessages.md

This example shows the Python syntax for defining an assistant message using `models.DeploymentStreamMessagesAssistantMessage`. The placeholder comment guides where to input the message data.

```python
value: models.DeploymentStreamMessagesAssistantMessage = /* values here */
```

--------------------------------

### Run Agent using Orq Python SDK

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/sdks/agents/README.md

Demonstrates how to initialize the Orq client and run an agent with specified parameters. It includes details on setting the API key, agent key, model, role, instructions, message content (including file URIs), thread details, and knowledge bases. The response from the agent is then printed.

```python
from orq_ai_sdk import Orq
import os


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

    res = orq.agents.run(key="<key>", model="F-150", role="<value>", instructions="<value>", message={
        "role": "tool",
        "parts": [
            {
                "kind": "file",
                "file": {
                    "uri": "https://front-pecan.info",
                },
            },
        ],
    }, path="Default", settings={{}}, fallback_models=[
        "<value>",
    ], contact={
        "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",
        ],
    }, thread={
        "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "tags": [
            "customer-support",
            "priority-high",
        ],
    }, knowledge_bases=[
        {
            "knowledge_id": "customer-knowledge-base",
        },
    ])

    # Handle response
    print(res)

```

--------------------------------

### Get Deployment Configuration with Python SDK

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/sdks/deployments/README.md

Demonstrates how to use the orq-python SDK to retrieve deployment configuration. It initializes the Orq client with an API key and then calls the `get_config` method with sample documents. The response is then printed. Ensure the ORQ_API_KEY environment variable is set.

```python
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>", 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)

```

--------------------------------

### ResponseStartedEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a ResponseStartedEvent. This event signifies the beginning of a response stream.

```python
value: models.ResponseStartedEvent = /* values here */
```

--------------------------------

### ResponseDoneEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a ResponseDoneEvent. This event indicates that a response stream has successfully completed.

```python
value: models.ResponseDoneEvent = /* values here */
```

--------------------------------

### Configure Deployment Documents in Python

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/models/deploymentgetconfigrequestbody.md

This snippet demonstrates how to configure the 'documents' parameter for deployment. It accepts a list of document objects, each containing text and metadata. This context is used for model responses, and can be leveraged by evaluators and guardrails for assessment. The provided example includes documents with file names, types, and page numbers.

```python
from typing import List, Optional
from orq_python.models import DeploymentGetConfigDocuments, DeploymentGetConfigInvokeOptions

def configure_deployment_documents(documents: List[DeploymentGetConfigDocuments]) -> None:
    # This is a placeholder function to illustrate the usage of the documents parameter.
    # In a real scenario, these documents would be passed to a deployment configuration.
    print(f"Configuring deployment with {len(documents)} documents.")
    for doc in documents:
        print(f"- Document: {doc.text[:50]}... (Metadata: {doc.metadata})")

# Example usage:
documents_list = [
    {
        "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"
        }
    }
]

# Assuming DeploymentGetConfigDocuments can be instantiated from a dictionary
parsed_documents = [DeploymentGetConfigDocuments(**doc) for doc in documents_list]
configure_deployment_documents(parsed_documents)

```

--------------------------------

### ToolFailedEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a ToolFailedEvent. This event is used when an error occurs during a tool's execution.

```python
value: models.ToolFailedEvent = /* values here */
```

--------------------------------

### ToolDoneEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a ToolDoneEvent. This event indicates the successful completion of a tool's execution.

```python
value: models.ToolDoneEvent = /* values here */
```

--------------------------------

### Stream Deployment Generation using Python

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/sdks/deployments/README.md

Demonstrates how to stream deployment generation using the orq-python SDK. This functionality is specifically for completions and chat completions. It requires an Orq client instance initialized with environment, contact ID, and API key. The input consists of a list of documents with text and associated metadata. The output is a stream of events.

```python
from orq_ai_sdk import Orq
import os


with Orq(
    environment="<value>",
    contact_id="<id>",
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.deployments.stream(key="<key>", 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)


```

--------------------------------

### ResponseFailedEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a ResponseFailedEvent. This event is used when an error occurs during the response streaming process.

```python
value: models.ResponseFailedEvent = /* values here */
```

--------------------------------

### Manage Datasets and Datapoints with Orq Python SDK

Source: https://context7.com/orq-ai/orq-python/llms.txt

Illustrates how to create datasets and datapoints, perform bulk creation, list, retrieve, update, and delete datapoints, and clear entire datasets using the Orq Python SDK. Requires ORQ_API_KEY environment variable.

```python
from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    # Create a dataset
    dataset = orq.datasets.create(request={
        "display_name": "Customer Support Test Cases",
        "key": "support-test-dataset",
        "path": "Default/Datasets",
        "description": "Evaluation dataset for support agent quality",
        "metadata": {"version": "1.0", "category": "evaluation"}
    })
    print(f"Created dataset: {dataset.id}")

    # Create datapoints
    datapoint = orq.datasets.create_datapoint(
        dataset_id=dataset.id,
        request={
            "inputs": {
                "customer_query": "How do I upgrade my plan?",
                "customer_tier": "basic"
            },
            "expected_output": {
                "response": "To upgrade your plan, visit Account Settings > Billing > Change Plan.",
                "tone": "helpful",
                "cited_sources": True
            },
            "metadata": {"difficulty": "easy", "category": "billing"}
        }
    )

    # Bulk create datapoints
    for i in range(10):
        orq.datasets.create_datapoint(
            dataset_id=dataset.id,
            request={
                "inputs": {"customer_query": f"Test query {i}", "context": f"Test context {i}"},
                "expected_output": {"response": f"Test response {i}"},
                "metadata": {"test_case": i}
            }
        )

    # List datapoints
    datapoints = orq.datasets.list_datapoints(
        dataset_id=dataset.id,
        limit=50
    )
    print(f"Total datapoints: {len(datapoints.data)}")

    # Retrieve specific datapoint
    dp = orq.datasets.retrieve_datapoint(
        dataset_id=dataset.id,
        datapoint_id=datapoint.id
    )

    # Update datapoint
    updated_dp = orq.datasets.update_datapoint(
        dataset_id=dataset.id,
        datapoint_id=datapoint.id,
        expected_output={
            "response": "Updated: Visit Settings > Subscription to upgrade.",
            "tone": "helpful",
            "cited_sources": True
        }
    )

    # Delete specific datapoint
    orq.datasets.delete_datapoint(
        dataset_id=dataset.id,
        datapoint_id=datapoint.id
    )

    # Clear all datapoints from dataset
    orq.datasets.clear(dataset_id=dataset.id)
```

--------------------------------

### PartDoneEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a PartDoneEvent. This event signifies the completion of a specific part within a response stream.

```python
value: models.PartDoneEvent = /* values here */
```

--------------------------------

### Project Creation and Configuration

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/models/json.md

Defines the structure for creating and configuring projects, including setting entity storage paths and keys.

```APIDOC
## POST /projects

### Description
Creates a new project with specified configuration.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **path** (str) - Required - Entity storage path in the format: `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.
- **description** (Optional[str]) - Optional - A description for the project.
- **key** (str) - Required - A unique key for the project.

### Request Example
```json
{
  "path": "my_project/data/raw",
  "description": "Raw data storage for my project",
  "key": "project_abc_123"
}
```

### Response
#### Success Response (201 Created)
- **id** (str) - The unique identifier of the created project.
- **path** (str) - The configured entity storage path.
- **description** (str) - The description of the project.
- **key** (str) - The unique key of the project.

#### Response Example
```json
{
  "id": "proj_12345",
  "path": "my_project/data/raw",
  "description": "Raw data storage for my project",
  "key": "project_abc_123"
}
```
```

--------------------------------

### ToolReviewDoneEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a ToolReviewDoneEvent. This event indicates that the review of a tool's output or execution is complete.

```python
value: models.ToolReviewDoneEvent = /* values here */
```

--------------------------------

### Create Image using ORQ Python SDK

Source: https://github.com/orq-ai/orq-python/blob/main/docs/sdks/router/README.md

This snippet demonstrates how to create an image using the ORQ Python SDK. It includes configuration for retries, fallbacks, contact details, caching, load balancing, and timeouts. The `Orq` client is initialized with an API key from environment variables.

```python
from orq_ai_sdk import Orq
import os


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

    res = orq.router.images_generate(prompt="<value>", model="2", n=1, orq={
        "retry": {
            "on_codes": [
                429,
                500,
                502,
                503,
                504,
            ],
        },
        "fallbacks": [
            {
                "model": "openai/gpt-4o-mini",
            },
        ],
        "contact": {
            "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",
            ],
        },
        "cache": {
            "ttl": 3600,
            "type": "exact_match",
        },
        "load_balancer": [
            {
                "type": "weight_based",
                "model": "openai/gpt-4o",
                "weight": 0.7,
            },
            {
                "type": "weight_based",
                "model": "openai/gpt-4o",
                "weight": 0.7,
            },
        ],
        "timeout": {
            "call_timeout": 30000,
        },
    })

    # Handle response
    print(res)

```

--------------------------------

### ToolReviewRequestedEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a ToolReviewRequestedEvent. This event signifies a request for review of a tool's output or execution.

```python
value: models.ToolReviewRequestedEvent = /* values here */
```

--------------------------------

### Project Creation

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/createevalrequestbodyhttp.md

This endpoint allows you to create a new project or configure an existing one. You must provide a unique key for the project and can optionally specify a description and a storage path.

```APIDOC
## POST /projects

### Description
Creates or updates a project configuration.

### Method
POST

### Endpoint
/projects

### Parameters
#### Request Body
- **path** (str) - Required - Entity storage path in the format: `project/folder/subfolder/...`
- **description** (Optional[str]) - Optional - A description for the project.
- **key** (str) - Required - A unique identifier for the project.

### Request Example
{
  "path": "my-project/data/raw",
  "description": "Raw data storage for my project",
  "key": "unique-project-key"
}

### Response
#### Success Response (200)
- **message** (str) - Confirmation message of project creation or update.
```

--------------------------------

### ToolStartedEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a ToolStartedEvent. This event signifies the initiation of a tool execution within the streaming process.

```python
value: models.ToolStartedEvent = /* values here */
```

--------------------------------

### Update Prompt Response Format (Example)

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/models/updatepromptresponseformatprompts4.md

This section details an example of updating a prompt's response format and lists the supported audio file types.

```APIDOC
## PUT /orq-ai/orq-python/prompts/{prompt_id}/response_format

### Description
Updates the response format for a specific prompt. This endpoint allows clients to specify the desired audio format for the prompt's output.

### Method
PUT

### Endpoint
`/orq-ai/orq-python/prompts/{prompt_id}/response_format`

### Parameters
#### Path Parameters
- **prompt_id** (string) - Required - The unique identifier of the prompt to update.

#### Query Parameters
None

#### Request Body
- **response_format** (string) - Required - The desired audio format for the prompt's response. Accepted values are MP3, OPUS, AAC, FLAC, WAV, PCM.

### Request Example
```json
{
  "response_format": "MP3"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the response format has been updated.

#### Response Example
```json
{
  "message": "Prompt response format updated successfully to MP3."
}
```

## Supported Audio Formats

### Description
This section lists the supported audio formats for prompt responses.

### Method
GET

### Endpoint
`/orq-ai/orq-python/supported_formats/audio`

### Parameters
None

### Request Example
```
GET /orq-ai/orq-python/supported_formats/audio
```

### Response
#### Success Response (200)
- **formats** (object) - An object containing key-value pairs of supported audio formats.
  - **MP3** (string) - mp3
  - **OPUS** (string) - opus
  - **AAC** (string) - aac
  - **FLAC** (string) - flac
  - **WAV** (string) - wav
  - **PCM** (string) - pcm

#### Response Example
```json
{
  "formats": {
    "MP3": "mp3",
    "OPUS": "opus",
    "AAC": "aac",
    "FLAC": "flac",
    "WAV": "wav",
    "PCM": "pcm"
  }
}
```
```

--------------------------------

### Configuration

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/modelconfigurationparameters.md

This section details how to configure the ORQ Python client, including verbosity settings.

```APIDOC
## Configuration

### Description
Configuration options for the ORQ Python client, including verbosity levels for responses.

### Method
Not applicable (configuration is typically set at initialization or through environment variables).

### Endpoint
Not applicable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from orq import ORQ

# Initialize with custom verbosity
client = ORQ(verbosity='high') 
```

### Response
#### Success Response (200)
Not applicable for configuration.

#### Response Example
Not applicable for configuration.

## Verbosity Setting

### Description
Adjusts the level of detail in the API's responses. Lower verbosity results in more concise answers, while higher verbosity provides more detailed information.

### Method
Configuration parameter (typically set during client initialization).

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Example of setting verbosity during ORQ client initialization
from orq import ORQ

# Possible values: 'low', 'medium', 'high' (or specific string values depending on implementation)
client_low_verbosity = ORQ(verbosity='low')
client_high_verbosity = ORQ(verbosity='high')
```

### Response
#### Success Response (200)
N/A - This is a configuration parameter.

#### Response Example
N/A - This is a configuration parameter.
```

--------------------------------

### CreatePromptResponseFormat4 Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/models/createpromptpromptsresponseresponseformat.md

Provides an example of using models.CreatePromptResponseFormat4 to configure the response format. This type is supported by the CreatePromptPromptsResponseResponseFormat object for structured outputs.

```python
value: models.CreatePromptResponseFormat4 = /* values here */
```

--------------------------------

### CreatePromptPromptConfig

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/models/createpromptpromptconfig.md

This endpoint allows you to create a prompt configuration. It supports various optional parameters for model selection, provider, and integration, and requires a list of messages.

```APIDOC
## POST /orq-ai/orq-python/create_prompt

### Description
Allows the creation of a prompt configuration compatible with the OpenAI schema. Supports various optional model and integration settings.

### Method
POST

### Endpoint
/orq-ai/orq-python/create_prompt

### Parameters
#### Request Body
- **stream** (Optional[bool]) - Whether to stream the response.
- **model** (Optional[str]) - The name of the model to use.
- **model_db_id** (OptionalNullable[str]) - The ID of the model in the database.
- **model_type** (OptionalNullable[models.CreatePromptModelType]) - The modality of the model.
- **model_parameters** (Optional[models.CreatePromptModelParameters]) - Parameters specific to the model.
- **provider** (Optional[models.CreatePromptProvider]) - The model provider.
- **integration_id** (OptionalNullable[str]) - The ID of the integration to use.
- **version** (Optional[str]) - The version of the model or service.
- **messages** (List[models.CreatePromptPromptsResponseMessages]) - Required. A list of messages compatible with the OpenAI schema.

### Request Example
```json
{
  "stream": false,
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ]
}
```

### Response
#### Success Response (200)
- **N/A** - The exact success response structure is not detailed in the provided text, but it is assumed to confirm the creation of the prompt configuration.

#### Response Example
```json
{
  "message": "Prompt configuration created successfully."
}
```
```

--------------------------------

### PartDeltaEvent Example (Python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/responsestreamingevent.md

Example demonstrating the structure of a PartDeltaEvent. This event represents a partial update or chunk of data within a response part.

```python
value: models.PartDeltaEvent = /* values here */
```

--------------------------------

### Project Configuration

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/models/requestbody1.md

Configure retrieval settings and entity storage paths for a project.

```APIDOC
## POST /projects/{project_id}/config

### Description
This endpoint allows you to configure various settings for a project, including retrieval strategies and entity storage paths.

### Method
POST

### Endpoint
`/projects/{project_id}/config`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

#### Request Body
- **retrieval_settings** (models.RetrievalSettings, optional) - The retrieval settings for the knowledge base. If not provided, Hybrid Search will be used as a default query strategy.
- **path** (string) - Required - Entity storage path in the format: `project/folder/subfolder/...`

### Request Example
```json
{
  "retrieval_settings": {
    "strategy": "vector_search"
  },
  "path": "my-project/data/entities"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful configuration.

#### Response Example
```json
{
  "message": "Project configuration updated successfully."
}
```
```

--------------------------------

### Create Dataset using Python SDK

Source: https://github.com/orq-ai/orq-python/blob/main/docs/sdks/datasets/README.md

Demonstrates how to create a new dataset within a project using the orq-python SDK. It requires an API key for authentication and takes a dictionary with 'display_name' and 'path' as input. The response contains details of the created dataset or an APIError.

```python
from orq_ai_sdk import Orq
import os


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

    res = orq.datasets.create(request={
        "display_name": "Neva.Raynor10",
        "path": "Default",
    })

    # Handle response
    print(res)

```

--------------------------------

### GET /v2/files/{file_id}

Source: https://github.com/orq-ai/orq-python/blob/main/docs/sdks/files/README.md

Retrieves the details of an existing file object. Provide a unique file ID to get the corresponding file object.

```APIDOC
## GET /v2/files/{file_id}

### Description
Retrieves the details of an existing file object. After you supply a unique file ID, orq.ai returns the corresponding file object.

### Method
GET

### Endpoint
/v2/files/{file_id}

### Parameters
#### Path Parameters
- **file_id** (string) - Required - The unique identifier of the file.

#### Query Parameters
- **starting_after** (Optional[str]) - Optional - A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `after=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the next page of the list.
- **ending_before** (Optional[str]) - Optional - A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `before=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the previous page of the list.
- **retries** (Optional[utils.RetryConfig]) - Optional - Configuration to override the default retry behavior of the client.

### Request Example
```python
# Example usage for file retrieval
res = orq.files.get(file_id="<id>")
```

### Response
#### Success Response (200)
- **File List Response Body** (models.FileListResponseBody) - The details of the file object.

#### Response Example
```json
{
  "example": "response body for file details"
}
```

### Errors
| Error Type |
| --- |
| models.APIError | 4XX, 5XX | */* |
```

--------------------------------

### Get All Prompts (GET /orq-ai/orq-python)

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/getallprompts23.md

Retrieves a list of all prompts available in the Orq AI system. The response includes details about each prompt's type and associated file information.

```APIDOC
## GET /orq-ai/orq-python

### Description
Retrieves a list of all prompts available in the Orq AI system. The response includes details about each prompt's type and associated file information.

### Method
GET

### Endpoint
/orq-ai/orq-python

### Parameters
#### Query Parameters
N/A

#### Request Body
N/A

### Response
#### Success Response (200)
- **type** (models.GetAllPrompts2PromptsResponseType) - Required - The type of the content part. Always `file`.
- **file** (models.GetAllPrompts2File) - Required - N/A

#### Response Example
```json
{
  "type": {
    "type": "file"
  },
  "file": {
    "file_id": "file-123",
    "content": "This is the prompt content."
  }
}
```
```

--------------------------------

### POST /orq-ai/orq-python/createprompt2

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/createprompt23.md

This endpoint is used to create a new prompt. It requires specific fields for content type and file information.

```APIDOC
## POST /orq-ai/orq-python/createprompt2

### Description
This endpoint is used to create a new prompt. It requires specific fields for content type and file information.

### Method
POST

### Endpoint
/orq-ai/orq-python/createprompt2

### Parameters
#### Request Body
- **type** (models.CreatePrompt2PromptsResponse200ApplicationJSONType) - Required - The type of the content part. Always `file`.
- **file** (models.CreatePrompt2PromptsFile) - Required - Represents the file associated with the prompt.

### Request Example
```json
{
  "type": "file",
  "file": {
    "file_id": "string",
    "content": "string"
  }
}
```

### Response
#### Success Response (200)
- **type** (models.CreatePrompt2PromptsResponse200ApplicationJSONType) - The type of the content part. Always `file`.
- **file** (models.CreatePrompt2PromptsFile) - N/A

#### Response Example
```json
{
  "type": "file",
  "file": {
    "file_id": "string",
    "content": "string"
  }
}
```
```

--------------------------------

### ChunkingConfiguration1 Example - Python

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/chunkingconfiguration.md

Demonstrates the usage of models.ChunkingConfiguration1 for chunking configuration. This requires the 'models' module to be imported.

```python
value: models.ChunkingConfiguration1 = /* values here */
```

--------------------------------

### Agent Started Streaming Event Parts

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/agentstartedstreamingeventparts.md

This section describes the different types of parts that can be streamed when an agent starts sending its response. These include text, data, file, and tool-related parts.

```APIDOC
## Agent Started Streaming Event Parts

### Description
This section details the various types of parts that can be streamed as part of an agent's response.

### Supported Types

#### `models.TextPart`

This part represents a chunk of text.

*   **Type**: `models.TextPart`
*   **Description**: A string value containing the text content.

```json
{
  "value": "This is a text chunk."
}
```

#### `models.DataPart`

This part represents a chunk of arbitrary data.

*   **Type**: `models.DataPart`
*   **Description**: A byte string containing the raw data.

```json
{
  "value": "binary_data_here"
}
```

#### `models.FilePart`

This part represents a file being streamed.

*   **Type**: `models.FilePart`
*   **Description**: Contains information about the file, such as its name and content (which could be streamed separately or embedded).

```json
{
  "filename": "example.txt",
  "content": "file_content_here"
}
```

#### `models.ToolCallPart`

This part indicates that the agent is making a call to a tool.

*   **Type**: `models.ToolCallPart`
*   **Description**: Contains the details of the tool to be called, including its name and arguments.

```json
{
  "tool_name": "calculator",
  "arguments": {
    "expression": "2 + 2"
  }
}
```

#### `models.ToolResultPart`

This part represents the result received from a tool execution.

*   **Type**: `models.ToolResultPart`
*   **Description**: Contains the name of the tool and the result of its execution.

```json
{
  "tool_name": "calculator",
  "result": "4"
}
```

```

--------------------------------

### Python Agent Started Streaming Event Model

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/streamagentdata.md

Defines the structure for the AgentStartedStreamingEvent in Python. This event indicates that an agent has successfully started and is available for operations within the StreamAgentData framework.

```python
value: models.AgentStartedStreamingEvent = /* values here */
```

--------------------------------

### Agent Configuration Parameters

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/models/runagentrequestbody.md

Details the optional parameters for configuring an Orq Python agent, specifically `description` and `system_prompt`.

```APIDOC
## Agent Configuration Parameters

### Description
This section outlines the optional parameters available when configuring an Orq Python agent. These parameters allow for customization of the agent's behavior and presentation.

### Method
N/A (Configuration parameters, not an API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **description** (*Optional[str]*) - A brief summary of the agent's purpose.
- **system_prompt** (*Optional[str]*) - A custom system prompt template for the agent. If omitted, the default template is used.

### Request Example
```json
{
  "description": "A sophisticated agent for analyzing financial markets.",
  "system_prompt": "You are a financial analyst AI. Analyze the provided data and generate a concise market report."
}
```

### Response
#### Success Response (N/A - Configuration)
N/A

#### Response Example
N/A
```

--------------------------------

### Python Agent Execution Started Streaming Event Model

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/streamagentdata.md

Defines the structure for the AgentExecutionStartedStreamingEvent in Python. This event signifies the start of an agent's execution and is part of the broader StreamAgentData models.

```python
value: models.AgentExecutionStartedStreamingEvent = /* values here */
```

--------------------------------

### Model Parameters JSON Example

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/promptconfiguration.md

An example of the JSON structure for optional model parameters. This includes settings like 'temperature' for controlling randomness and 'maxTokens' for limiting output length. These parameters are optional and can be used to fine-tune model behavior.

```json
{
  "temperature": 0.7,
  "maxTokens": 1000
}
```

--------------------------------

### Invoke Deployments with Orq AI SDK

Source: https://context7.com/orq-ai/orq-python/llms.txt

Shows how to invoke AI model deployments using the Orq AI SDK, including standard and streaming responses. It supports various configurations like inputs, context, messages, and metadata. Authentication requires an ORQ_API_KEY, and optional parameters like environment and contact_id can be provided.

```python
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
    environment="production",
    contact_id="user_12345"
) as orq:
    # Standard deployment invocation
    response = orq.deployments.invoke(
        key="customer-support-agent",
        stream=False,
        inputs={
            "customer_name": "John Smith",
            "product_id": "PRD-12345",
            "issue_category": "billing"
        },
        context={
            "customer_tier": "premium",
            "account_status": "active"
        },
        messages=[
            {"role": "user", "content": "I have a question about my recent invoice."}
        ],
        metadata={
            "session_id": "sess_abc123",
            "channel": "web-chat"
        },
        documents=[
            {
                "id": "doc_001",
                "content": "Invoice #12345 dated 2024-01-15 for $150.00",
                "metadata": {"type": "invoice"}
            }
        ],
        knowledge_filter={
            "metadata": {"category": "billing"}
        }
    )
    print(f"Response: {response}")

    # Streaming deployment
    stream_response = orq.deployments.stream(
        key="content-generator",
        inputs={"topic": "AI trends", "length": "medium"},
        messages=[
            {"role": "system", "content": "You are a technical writer."},
            {"role": "user", "content": "Write about recent AI developments."}
        ]
    )

    with stream_response as event_stream:
        for event in event_stream:
            print(event, flush=True)

    # Get deployment configuration
    config = orq.deployments.get_config(key="customer-support-agent")
    print(f"Model: {config.model}, Settings: {config.settings}")
```

--------------------------------

### Prompt Inputs and Context

Source: https://github.com/orq-ai/orq-python/blob/main/packages/orq-rc/docs/models/invokedeploymentrequest.md

Explains the 'inputs' and 'context' dictionaries used for prompt variable replacement. 'inputs' are for key-value pairs to replace in prompts, using defaults if not provided. 'context' contains key-value pairs that match your data model and fields in the deployment routing configuration.

```APIDOC
## Prompt Variables

### Description
This section describes the parameters used to provide variables for prompt templating. These include `inputs` for direct variable replacement and `context` for data model and routing configuration matching.

### Parameters
#### Request Body
- **inputs** (Dict[str, *Any]) - Optional - Key-value pairs for variable replacement in prompts. If a variable defined in the prompt is not provided, default variables are used.
- **context** (Dict[str, *Any]) - Optional - Key-value pairs that match your data model and fields declared in your deployment routing configuration.
```

--------------------------------

### Python Type Hinting for DeploymentsResponseFormat Models

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/deploymentsresponseformat.md

Demonstrates Python type hinting for various DeploymentsResponseFormat types. These examples show how to declare variables with specific response format types, typically used when configuring model output.

```python
value: models.DeploymentsResponseFormat1 = /* values here */
```

```python
value: models.DeploymentsResponseFormat2 = /* values here */
```

```python
value: models.DeploymentsResponseFormat3 = /* values here */
```

```python
value: models.DeploymentsResponseFormat4 = /* values here */
```

```python
value: models.DeploymentsResponseFormat5 = /* values here */
```

```python
value: models.DeploymentsResponseFormat6 = /* values here */
```

--------------------------------

### Run Agent with Python SDK

Source: https://github.com/orq-ai/orq-python/blob/main/docs/sdks/agents/README.md

This snippet shows how to initialize the Orq SDK client and call the `agents.run` method. It includes parameters for agent key, model, role, instructions, message content, thread, contact details, and knowledge bases. The code requires the 'orq-python-sdk' package and an ORQ_API_KEY environment variable.

```python
from orq_ai_sdk import Orq
import os


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

    res = orq.agents.run(key="<key>", model="F-150", role="<value>", instructions="<value>", message={
        "role": "tool",
        "parts": [
            {
                "kind": "text",
                "text": "<value>",
            },
        ],
    }, path="Default", settings={}, contact={
        "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",
        ],
    }, thread={
        "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "tags": [
            "customer-support",
            "priority-high",
        ],
    }, knowledge_bases=[
        {
            "knowledge_id": "customer-knowledge-base",
        },
    ])

    # Handle response
    print(res)

```

--------------------------------

### ChunkingConfiguration2 Example - Python

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/chunkingconfiguration.md

Illustrates how to use models.ChunkingConfiguration2 for data chunking. Ensure the 'models' module is accessible for this configuration.

```python
value: models.ChunkingConfiguration2 = /* values here */
```

--------------------------------

### Get Prompt Version Response Format

Source: https://github.com/orq-ai/orq-python/blob/main/docs/models/getpromptversionmodelparameters.md

Describes the optional `response_format` object for the Get Prompt Version API. This object allows specifying output formats like JSON Schema for structured outputs or JSON mode for generating valid JSON.

```APIDOC
## Get Prompt Version Response Format

### Description
This section details the `response_format` field, which is an optional object that specifies the desired output format for the model's response. It supports two main modes: JSON Schema for structured outputs and JSON mode for generating valid JSON.

### Method
GET

### Endpoint
`/orq-ai/orq-python/prompt/versions/{version_id}` (Assumed endpoint based on context)

### Parameters
#### Query Parameters
- **response_format** (OptionalNullable[models.GetPromptVersionResponseFormat]) - Optional - An object specifying the format that the model must output.

### Request Body
N/A

### Response
#### Success Response (200)
- **response_format** (models.GetPromptVersionResponseFormat) - An object specifying the format that the model must output.

#### Response Example
```json
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "type": "object",
      "properties": {
        "key1": {
          "type": "string"
        }
      }
    }
  }
}
```

**Notes on `response_format`:**
- Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema.
- Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
- **Important:** When using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason`="length", which indicates the generation exceeded `max_tokens` or the conversation exceeded the `max_context` length.
```