humanloop 0.7.35
Client for Humanloop API
License: MIT
Requires Python: <4.0,>=3.8

<div align="center">

[![Visit Humanloop](https://raw.githubusercontent.com/humanloop/humanloop-python/HEAD/header.png)](https://humanloop.com)

# Humanloop<a id="humanloop"></a>


[![PyPI](https://img.shields.io/badge/PyPI-v0.7.35-blue)](https://pypi.org/project/humanloop/0.7.35)
[![README.md](https://img.shields.io/badge/README-Click%20Here-green)](https://github.com/humanloop/humanloop-python#readme)

</div>

> [!WARNING]
> This SDK has breaking changes in `>= 0.6.0` versions.
> All methods now return Pydantic models.
>
> ### Before (`< 0.6.0`)
>
> Previously, you had to use the `[]` syntax to access response values. This
> required a little more code for every property access.
>
> ```python
> chat_response = humanloop.chat(
>         # parameters
>     )
> print(chat_response.body["project_id"])
> ```
>
> ### After (`>= 0.6.0`)
>
> With Pydantic-based response values, you can use the `.` syntax to access. This
> is slightly less verbose and looks more Pythonic.
>
> ```python
> chat_response = humanloop.chat(
>         # parameters
>     )
> print(chat_response.project_id)
> ```
>
> To reuse existing implementations from `< 0.6.0`, use the `.raw` namespace as specified in the [Raw HTTP Response](#raw-http-response) section.

## Table of Contents<a id="table-of-contents"></a>

<!-- toc -->

- [Requirements](#requirements)
- [Installation](#installation)
- [Getting Started](#getting-started)
- [Async](#async)
- [Raw HTTP Response](#raw-http-response)
- [Streaming](#streaming)
- [Reference](#reference)
  * [`humanloop.chat`](#humanloopchat)
  * [`humanloop.chat_deployed`](#humanloopchat_deployed)
  * [`humanloop.chat_model_config`](#humanloopchat_model_config)
  * [`humanloop.complete`](#humanloopcomplete)
  * [`humanloop.complete_deployed`](#humanloopcomplete_deployed)
  * [`humanloop.complete_model_configuration`](#humanloopcomplete_model_configuration)
  * [`humanloop.datapoints.delete`](#humanloopdatapointsdelete)
  * [`humanloop.datapoints.get`](#humanloopdatapointsget)
  * [`humanloop.datapoints.update`](#humanloopdatapointsupdate)
  * [`humanloop.datasets.create`](#humanloopdatasetscreate)
  * [`humanloop.datasets.create_datapoint`](#humanloopdatasetscreate_datapoint)
  * [`humanloop.datasets.delete`](#humanloopdatasetsdelete)
  * [`humanloop.datasets.get`](#humanloopdatasetsget)
  * [`humanloop.datasets.list`](#humanloopdatasetslist)
  * [`humanloop.datasets.list_all_for_project`](#humanloopdatasetslist_all_for_project)
  * [`humanloop.datasets.list_datapoints`](#humanloopdatasetslist_datapoints)
  * [`humanloop.datasets.update`](#humanloopdatasetsupdate)
  * [`humanloop.evaluations.add_evaluators`](#humanloopevaluationsadd_evaluators)
  * [`humanloop.evaluations.create`](#humanloopevaluationscreate)
  * [`humanloop.evaluations.get`](#humanloopevaluationsget)
  * [`humanloop.evaluations.list`](#humanloopevaluationslist)
  * [`humanloop.evaluations.list_all_for_project`](#humanloopevaluationslist_all_for_project)
  * [`humanloop.evaluations.list_datapoints`](#humanloopevaluationslist_datapoints)
  * [`humanloop.evaluations.log`](#humanloopevaluationslog)
  * [`humanloop.evaluations.result`](#humanloopevaluationsresult)
  * [`humanloop.evaluations.update_status`](#humanloopevaluationsupdate_status)
  * [`humanloop.evaluators.create`](#humanloopevaluatorscreate)
  * [`humanloop.evaluators.delete`](#humanloopevaluatorsdelete)
  * [`humanloop.evaluators.get`](#humanloopevaluatorsget)
  * [`humanloop.evaluators.list`](#humanloopevaluatorslist)
  * [`humanloop.evaluators.update`](#humanloopevaluatorsupdate)
  * [`humanloop.feedback`](#humanloopfeedback)
  * [`humanloop.logs.delete`](#humanlooplogsdelete)
  * [`humanloop.logs.get`](#humanlooplogsget)
  * [`humanloop.logs.list`](#humanlooplogslist)
  * [`humanloop.log`](#humanlooplog)
  * [`humanloop.logs.update`](#humanlooplogsupdate)
  * [`humanloop.logs.update_by_ref`](#humanlooplogsupdate_by_ref)
  * [`humanloop.model_configs.deserialize`](#humanloopmodel_configsdeserialize)
  * [`humanloop.model_configs.export`](#humanloopmodel_configsexport)
  * [`humanloop.model_configs.get`](#humanloopmodel_configsget)
  * [`humanloop.model_configs.register`](#humanloopmodel_configsregister)
  * [`humanloop.model_configs.serialize`](#humanloopmodel_configsserialize)
  * [`humanloop.projects.create`](#humanloopprojectscreate)
  * [`humanloop.projects.create_feedback_type`](#humanloopprojectscreate_feedback_type)
  * [`humanloop.projects.deactivate_config`](#humanloopprojectsdeactivate_config)
  * [`humanloop.projects.delete`](#humanloopprojectsdelete)
  * [`humanloop.projects.delete_deployed_config`](#humanloopprojectsdelete_deployed_config)
  * [`humanloop.projects.deploy_config`](#humanloopprojectsdeploy_config)
  * [`humanloop.projects.export`](#humanloopprojectsexport)
  * [`humanloop.projects.get`](#humanloopprojectsget)
  * [`humanloop.projects.get_active_config`](#humanloopprojectsget_active_config)
  * [`humanloop.projects.list`](#humanloopprojectslist)
  * [`humanloop.projects.list_configs`](#humanloopprojectslist_configs)
  * [`humanloop.projects.list_deployed_configs`](#humanloopprojectslist_deployed_configs)
  * [`humanloop.projects.update`](#humanloopprojectsupdate)
  * [`humanloop.projects.update_feedback_types`](#humanloopprojectsupdate_feedback_types)
  * [`humanloop.sessions.create`](#humanloopsessionscreate)
  * [`humanloop.sessions.get`](#humanloopsessionsget)
  * [`humanloop.sessions.list`](#humanloopsessionslist)

<!-- tocstop -->

## Requirements<a id="requirements"></a>

Python >=3.7

## Installation<a id="installation"></a>

```sh
pip install humanloop==0.7.35
```

## Getting Started<a id="getting-started"></a>

```python
from pprint import pprint
from humanloop import Humanloop, ApiException

humanloop = Humanloop(
    api_key="YOUR_API_KEY",
    openai_api_key="YOUR_OPENAI_API_KEY",
    anthropic_api_key="YOUR_ANTHROPIC_API_KEY",
)

try:
    # Chat
    chat_response = humanloop.chat(
        project="sdk-example",
        messages=[
            {
                "role": "user",
                "content": "Explain asynchronous programming.",
            }
        ],
        model_config={
            "model": "gpt-3.5-turbo",
            "max_tokens": -1,
            "temperature": 0.7,
            "chat_template": [
                {
                    "role": "system",
                    "content": "You are a helpful assistant who replies in the style of {{persona}}.",
                },
            ],
        },
        inputs={
            "persona": "the pirate Blackbeard",
        },
        stream=False,
    )
    print(chat_response)
except ApiException as e:
    print("Exception when calling .chat: %s\n" % e)
    pprint(e.body)
    if e.status == 422:
        pprint(e.body["detail"])
    pprint(e.headers)
    pprint(e.status)
    pprint(e.reason)
    pprint(e.round_trip_time)

try:
    # Complete
    complete_response = humanloop.complete(
        project="sdk-example",
        inputs={
            "text": "Llamas that are well-socialized and trained to halter and lead after weaning and are very friendly and pleasant to be around. They are extremely curious and most will approach people easily. However, llamas that are bottle-fed or over-socialized and over-handled as youth will become extremely difficult to handle when mature, when they will begin to treat humans as they treat each other, which is characterized by bouts of spitting, kicking and neck wrestling.[33]",
        },
        model_config={
            "model": "gpt-3.5-turbo",
            "max_tokens": -1,
            "temperature": 0.7,
            "prompt_template": "Summarize this for a second-grade student:\n\nText:\n{{text}}\n\nSummary:\n",
        },
        stream=False,
    )
    print(complete_response)
except ApiException as e:
    print("Exception when calling .complete: %s\n" % e)
    pprint(e.body)
    if e.status == 422:
        pprint(e.body["detail"])
    pprint(e.headers)
    pprint(e.status)
    pprint(e.reason)
    pprint(e.round_trip_time)

try:
    # Feedback
    feedback_response = humanloop.feedback(
        type="rating",
        value="good",
        data_id="data_[...]",
        user="user@example.com",
    )
    print(feedback_response)
except ApiException as e:
    print("Exception when calling .feedback: %s\n" % e)
    pprint(e.body)
    if e.status == 422:
        pprint(e.body["detail"])
    pprint(e.headers)
    pprint(e.status)
    pprint(e.reason)
    pprint(e.round_trip_time)

try:
    # Log
    log_response = humanloop.log(
        project="sdk-example",
        inputs={
            "text": "Llamas that are well-socialized and trained to halter and lead after weaning and are very friendly and pleasant to be around. They are extremely curious and most will approach people easily. However, llamas that are bottle-fed or over-socialized and over-handled as youth will become extremely difficult to handle when mature, when they will begin to treat humans as they treat each other, which is characterized by bouts of spitting, kicking and neck wrestling.[33]",
        },
        output="Llamas can be friendly and curious if they are trained to be around people, but if they are treated too much like pets when they are young, they can become difficult to handle when they grow up. This means they might spit, kick, and wrestle with their necks.",
        source="sdk",
        config={
            "model": "gpt-3.5-turbo",
            "max_tokens": -1,
            "temperature": 0.7,
            "prompt_template": "Summarize this for a second-grade student:\n\nText:\n{{text}}\n\nSummary:\n",
            "type": "model",
        },
    )
    print(log_response)
except ApiException as e:
    print("Exception when calling .log: %s\n" % e)
    pprint(e.body)
    if e.status == 422:
        pprint(e.body["detail"])
    pprint(e.headers)
    pprint(e.status)
    pprint(e.reason)
    pprint(e.round_trip_time)
```

## Async<a id="async"></a>

`async` support is available by prepending `a` to any method.

```python
import asyncio
from pprint import pprint
from humanloop import Humanloop, ApiException

humanloop = Humanloop(
    api_key="YOUR_API_KEY",
    openai_api_key="YOUR_OPENAI_API_KEY",
    anthropic_api_key="YOUR_ANTHROPIC_API_KEY",
)


async def main():
    try:
        complete_response = await humanloop.acomplete(
            project="sdk-example",
            inputs={
                "text": "Llamas that are well-socialized and trained to halter and lead after weaning and are very friendly and pleasant to be around. They are extremely curious and most will approach people easily. However, llamas that are bottle-fed or over-socialized and over-handled as youth will become extremely difficult to handle when mature, when they will begin to treat humans as they treat each other, which is characterized by bouts of spitting, kicking and neck wrestling.[33]",
            },
            model_config={
                "model": "gpt-3.5-turbo",
                "max_tokens": -1,
                "temperature": 0.7,
                "prompt_template": "Summarize this for a second-grade student:\n\nText:\n{{text}}\n\nSummary:\n",
            },
            stream=False,
        )
        print(complete_response)
    except ApiException as e:
        print("Exception when calling .complete: %s\n" % e)
        pprint(e.body)
        if e.status == 422:
            pprint(e.body["detail"])
        pprint(e.headers)
        pprint(e.status)
        pprint(e.reason)
        pprint(e.round_trip_time)


asyncio.run(main())
```

## Raw HTTP Response<a id="raw-http-response"></a>

To access raw HTTP response values, use the `.raw` namespace.

```python
from pprint import pprint
from humanloop import Humanloop, ApiException

humanloop = Humanloop(
    openai_api_key="OPENAI_API_KEY",
    openai_azure_api_key="OPENAI_AZURE_API_KEY",
    openai_azure_endpoint_api_key="OPENAI_AZURE_ENDPOINT_API_KEY",
    anthropic_api_key="ANTHROPIC_API_KEY",
    cohere_api_key="COHERE_API_KEY",
    api_key="YOUR_API_KEY",
)

try:
    # Chat
    create_response = humanloop.chats.raw.create(
        messages=[
            {
                "role": "user",
            }
        ],
        model_config={
            "provider": "openai",
            "model": "model_example",
            "max_tokens": -1,
            "temperature": 1,
            "top_p": 1,
            "presence_penalty": 0,
            "frequency_penalty": 0,
            "endpoint": "complete",
        },
        project="string_example",
        project_id="string_example",
        session_id="string_example",
        session_reference_id="string_example",
        parent_id="string_example",
        parent_reference_id="string_example",
        inputs={},
        source="string_example",
        metadata={},
        save=True,
        source_datapoint_id="string_example",
        provider_api_keys={},
        num_samples=1,
        stream=False,
        user="string_example",
        seed=1,
        return_inputs=True,
        tool_choice="string_example",
        tool_call="string_example",
        response_format={
            "type": "string_example",
        },
    )
    pprint(create_response.body)
    pprint(create_response.body["data"])
    pprint(create_response.body["provider_responses"])
    pprint(create_response.body["project_id"])
    pprint(create_response.body["num_samples"])
    pprint(create_response.body["logprobs"])
    pprint(create_response.body["suffix"])
    pprint(create_response.body["user"])
    pprint(create_response.body["usage"])
    pprint(create_response.body["metadata"])
    pprint(create_response.body["provider_request"])
    pprint(create_response.body["session_id"])
    pprint(create_response.body["tool_choice"])
    pprint(create_response.headers)
    pprint(create_response.status)
    pprint(create_response.round_trip_time)
except ApiException as e:
    print("Exception when calling ChatsApi.create: %s\n" % e)
    pprint(e.body)
    if e.status == 422:
        pprint(e.body["detail"])
    pprint(e.headers)
    pprint(e.status)
    pprint(e.reason)
    pprint(e.round_trip_time)
```


## Streaming<a id="streaming"></a>

Streaming support is available by suffixing a `chat` or `complete` method with `_stream`.

```python
import asyncio
from humanloop import Humanloop

humanloop = Humanloop(
    api_key="YOUR_API_KEY",
    openai_api_key="YOUR_OPENAI_API_KEY",
    anthropic_api_key="YOUR_ANTHROPIC_API_KEY",
)


async def main():
    response = await humanloop.chat_stream(
        project="sdk-example",
        messages=[
            {
                "role": "user",
                "content": "Explain asynchronous programming.",
            }
        ],
        model_config={
            "model": "gpt-3.5-turbo",
            "max_tokens": -1,
            "temperature": 0.7,
            "chat_template": [
                {
                    "role": "system",
                    "content": "You are a helpful assistant who replies in the style of {{persona}}.",
                },
            ],
        },
        inputs={
            "persona": "the pirate Blackbeard",
        },
    )
    async for token in response.content:
        print(token)


asyncio.run(main())
```


## Reference<a id="reference"></a>
### `humanloop.chat`<a id="humanloopchat"></a>

Get a chat response by providing details of the model configuration in the request.

#### 🛠️ Usage<a id="🛠️-usage"></a>

```python
create_response = humanloop.chat(
    messages=[
        {
            "role": "user",
        }
    ],
    model_config={
        "provider": "openai",
        "model": "model_example",
        "max_tokens": -1,
        "temperature": 1,
        "top_p": 1,
        "presence_penalty": 0,
        "frequency_penalty": 0,
        "endpoint": "complete",
    },
    project="string_example",
    project_id="string_example",
    session_id="string_example",
    session_reference_id="string_example",
    parent_id="string_example",
    parent_reference_id="string_example",
    inputs={},
    source="string_example",
    metadata={},
    save=True,
    source_datapoint_id="string_example",
    provider_api_keys={},
    num_samples=1,
    stream=False,
    user="string_example",
    seed=1,
    return_inputs=True,
    tool_choice="string_example",
    tool_call="string_example",
    response_format={
        "type": "string_example",
    },
)
```

#### ⚙️ Parameters<a id="⚙️-parameters"></a>

##### messages: List[`ChatMessageWithToolCall`]<a id="messages-listchatmessagewithtoolcall"></a>

The messages passed to the to provider chat endpoint.

##### model_config: [`ModelConfigChatRequest`](./humanloop/type/model_config_chat_request.py)<a id="model_config-modelconfigchatrequesthumanlooptypemodel_config_chat_requestpy"></a>


The model configuration used to create a chat response.

##### project: `str`<a id="project-str"></a>

Unique project name. If no project exists with this name, a new project will be created.

##### project_id: `str`<a id="project_id-str"></a>

Unique ID of a project to associate to the log. Either this or `project` must be provided.

##### session_id: `str`<a id="session_id-str"></a>

ID of the session to associate the datapoint.

##### session_reference_id: `str`<a id="session_reference_id-str"></a>

A unique string identifying the session to associate the datapoint to. Allows you to log multiple datapoints to a session (using an ID kept by your internal systems) by passing the same `session_reference_id` in subsequent log requests. Specify at most one of this or `session_id`.

##### parent_id: `str`<a id="parent_id-str"></a>

ID associated to the parent datapoint in a session.

##### parent_reference_id: `str`<a id="parent_reference_id-str"></a>

A unique string identifying the previously-logged parent datapoint in a session. Allows you to log nested datapoints with your internal system IDs by passing the same reference ID as `parent_id` in a prior log request. Specify at most one of this or `parent_id`. Note that this cannot refer to a datapoint being logged in the same request.

##### inputs: `Dict[str, Union[bool, date, datetime, dict, float, int, list, str, None]]`<a id="inputs-dictstr-unionbool-date-datetime-dict-float-int-list-str-none"></a>

The inputs passed to the prompt template.

##### source: `str`<a id="source-str"></a>

Identifies where the model was called from.

##### metadata: `Dict[str, Union[bool, date, datetime, dict, float, int, list, str, None]]`<a id="metadata-dictstr-unionbool-date-datetime-dict-float-int-list-str-none"></a>

Any additional metadata to record.

##### save: `bool`<a id="save-bool"></a>

Whether the request/response payloads will be stored on Humanloop.

##### source_datapoint_id: `str`<a id="source_datapoint_id-str"></a>

ID of the source datapoint if this is a log derived from a datapoint in a dataset.

##### provider_api_keys: [`ProviderApiKeys`](./humanloop/type/provider_api_keys.py)<a id="provider_api_keys-providerapikeyshumanlooptypeprovider_api_keyspy"></a>


API keys required by each provider to make API calls. The API keys provided here are not stored by Humanloop. If not specified here, Humanloop will fall back to the key saved to your organization.

##### num_samples: `int`<a id="num_samples-int"></a>

The number of generations.

##### stream: `bool`<a id="stream-bool"></a>

If true, tokens will be sent as data-only server-sent events. If num_samples > 1, samples are streamed back independently.

##### user: `str`<a id="user-str"></a>

End-user ID passed through to provider call.

##### seed: `int`<a id="seed-int"></a>

Deprecated field: the seed is instead set as part of the request.config object.

##### return_inputs: `bool`<a id="return_inputs-bool"></a>

Whether to return the inputs in the response. If false, the response will contain an empty dictionary under inputs. This is useful for reducing the size of the response. Defaults to true.

##### tool_choice: Union[`str`, `str`, `str`, `ToolChoice`]<a id="tool_choice-unionstr-str-str-toolchoice"></a>


Controls how the model uses tools. The following options are supported: 'none' forces the model to not call a tool; the default when no tools are provided as part of the model config. 'auto' the model can decide to call one of the provided tools; the default when tools are provided as part of the model config. Providing {'type': 'function', 'function': {name': <TOOL_NAME>}} forces the model to use the named function.

##### tool_call: Union[`str`, [`Dict[str, str]`](./humanloop/type/typing_dict_str_str.py)]<a id="tool_call-unionstr-dictstr-strhumanlooptypetyping_dict_str_strpy"></a>


NB: Deprecated with new tool_choice. Controls how the model uses tools. The following options are supported: 'none' forces the model to not call a tool; the default when no tools are provided as part of the model config. 'auto' the model can decide to call one of the provided tools; the default when tools are provided as part of the model config. Providing {'name': <TOOL_NAME>} forces the model to use the provided tool of the same name.

##### response_format: [`ResponseFormat`](./humanloop/type/response_format.py)<a id="response_format-responseformathumanlooptyperesponse_formatpy"></a>


The format of the response. Only type json_object is currently supported for chat.

#### ⚙️ Request Body<a id="⚙️-request-body"></a>

[`ChatRequest`](./humanloop/type/chat_request.py)
#### 🔄 Return<a id="🔄-return"></a>

[`ChatResponse`](./humanloop/pydantic/chat_response.py)

#### 🌐 Endpoint<a id="🌐-endpoint"></a>

`/chat` `post`

[🔙 **Back to Table of Contents**](#table-of-contents)

---

### `humanloop.chat_deployed`<a id="humanloopchat_deployed"></a>

Get a chat response using the project's active deployment.

The active deployment can be a specific model configuration.

#### 🛠️ Usage<a id="🛠️-usage"></a>

```python
create_deployed_response = humanloop.chat_deployed(
    messages=[
        {
            "role": "user",
        }
    ],
    project="string_example",
    project_id="string_example",
    session_id="string_example",
    session_reference_id="string_example",
    parent_id="string_example",
    parent_reference_id="string_example",
    inputs={},
    source="string_example",
    metadata={},
    save=True,
    source_datapoint_id="string_example",
    provider_api_keys={},
    num_samples=1,
    stream=False,
    user="string_example",
    seed=1,
    return_inputs=True,
    tool_choice="string_example",
    tool_call="string_example",
    response_format={
        "type": "string_example",
    },
    environment="string_example",
)
```

#### ⚙️ Parameters<a id="⚙️-parameters"></a>

##### messages: List[`ChatMessageWithToolCall`]<a id="messages-listchatmessagewithtoolcall"></a>

The messages passed to the to provider chat endpoint.

##### project: `str`<a id="project-str"></a>

Unique project name. If no project exists with this name, a new project will be created.

##### project_id: `str`<a id="project_id-str"></a>

Unique ID of a project to associate to the log. Either this or `project` must be provided.

##### session_id: `str`<a id="session_id-str"></a>

ID of the session to associate the datapoint.

##### session_reference_id: `str`<a id="session_reference_id-str"></a>

A unique string identifying the session to associate the datapoint to. Allows you to log multiple datapoints to a session (using an ID kept by your internal systems) by passing the same `session_reference_id` in subsequent log requests. Specify at most one of this or `session_id`.

##### parent_id: `str`<a id="parent_id-str"></a>

ID associated to the parent datapoint in a session.

##### parent_reference_id: `str`<a id="parent_reference_id-str"></a>

A unique string identifying the previously-logged parent datapoint in a session. Allows you to log nested datapoints with your internal system IDs by passing the same reference ID as `parent_id` in a prior log request. Specify at most one of this or `parent_id`. Note that this cannot refer to a datapoint being logged in the same request.

##### inputs: `Dict[str, Union[bool, date, datetime, dict, float, int, list, str, None]]`<a id="inputs-dictstr-unionbool-date-datetime-dict-float-int-list-str-none"></a>

The inputs passed to the prompt template.

##### source: `str`<a id="source-str"></a>

Identifies where the model was called from.

##### metadata: `Dict[str, Union[bool, date, datetime, dict, float, int, list, str, None]]`<a id="metadata-dictstr-unionbool-date-datetime-dict-float-int-list-str-none"></a>

Any additional metadata to record.

##### save: `bool`<a id="save-bool"></a>

Whether the request/response payloads will be stored on Humanloop.

##### source_datapoint_id: `str`<a id="source_datapoint_id-str"></a>

ID of the source datapoint if this is a log derived from a datapoint in a dataset.

##### provider_api_keys: [`ProviderApiKeys`](./humanloop/type/provider_api_keys.py)<a id="provider_api_keys-providerapikeyshumanlooptypeprovider_api_keyspy"></a>


API keys required by each provider to make API calls. The API keys provided here are not stored by Humanloop. If not specified here, Humanloop will fall back to the key saved to your organization.

##### num_samples: `int`<a id="num_samples-int"></a>

The number of generations.

##### stream: `bool`<a id="stream-bool"></a>

If true, tokens will be sent as data-only server-sent events. If num_samples > 1, samples are streamed back independently.

##### user: `str`<a id="user-str"></a>

End-user ID passed through to provider call.

##### seed: `int`<a id="seed-int"></a>

Deprecated field: the seed is instead set as part of the request.config object.

##### return_inputs: `bool`<a id="return_inputs-bool"></a>

Whether to return the inputs in the response. If false, the response will contain an empty dictionary under inputs. This is useful for reducing the size of the response. Defaults to true.

##### tool_choice: Union[`str`, `str`, `str`, `ToolChoice`]<a id="tool_choice-unionstr-str-str-toolchoice"></a>


Controls how the model uses tools. The following options are supported: 'none' forces the model to not call a tool; the default when no tools are provided as part of the model config. 'auto' the model can decide to call one of the provided tools; the default when tools are provided as part of the model config. Providing {'type': 'function', 'function': {name': <TOOL_NAME>}} forces the model to use the named function.

##### tool_call: Union[`str`, [`Dict[str, str]`](./humanloop/type/typing_dict_str_str.py)]<a id="tool_call-unionstr-dictstr-strhumanlooptypetyping_dict_str_strpy"></a>


NB: Deprecated with new tool_choice. Controls how the model uses tools. The following options are supported: 'none' forces the model to not call a tool; the default when no tools are provided as part of the model config. 'auto' the model can decide to call one of the provided tools; the default when tools are provided as part of the model config. Providing {'name': <TOOL_NAME>} forces the model to use the provided tool of the same name.

##### response_format: [`ResponseFormat`](./humanloop/type/response_format.py)<a id="response_format-responseformathumanlooptyperesponse_formatpy"></a>


The format of the response. Only type json_object is currently supported for chat.

##### environment: `str`<a id="environment-str"></a>

The environment name used to create a chat response. If not specified, the default environment will be used.

#### ⚙️ Request Body<a id="⚙️-request-body"></a>

[`ChatDeployedRequest`](./humanloop/type/chat_deployed_request.py)
#### 🔄 Return<a id="🔄-return"></a>

[`ChatResponse`](./humanloop/pydantic/chat_response.py)

#### 🌐 Endpoint<a id="🌐-endpoint"></a>

`/chat-deployed` `post`

[🔙 **Back to Table of Contents**](#table-of-contents)

---

### `humanloop.chat_model_config`<a id="humanloopchat_model_config"></a>

Get chat response for a specific model configuration.

#### 🛠️ Usage<a id="🛠️-usage"></a>

```python
create_model_config_response = humanloop.chat_model_config(
    messages=[
        {
            "role": "user",
        }
    ],
    model_config_id="string_example",
    project="string_example",
    project_id="string_example",
    session_id="string_example",
    session_reference_id="string_example",
    parent_id="string_example",
    parent_reference_id="string_example",
    inputs={},
    source="string_example",
    metadata={},
    save=True,
    source_datapoint_id="string_example",
    provider_api_keys={},
    num_samples=1,
    stream=False,
    user="string_example",
    seed=1,
    return_inputs=True,
    tool_choice="string_example",
    tool_call="string_example",
    response_format={
        "type": "string_example",
    },
)
```

#### ⚙️ Parameters<a id="⚙️-parameters"></a>

##### messages: List[`ChatMessageWithToolCall`]<a id="messages-listchatmessagewithtoolcall"></a>

The messages passed to the to provider chat endpoint.

##### model_config_id: `str`<a id="model_config_id-str"></a>

Identifies the model configuration used to create a chat response.

##### project: `str`<a id="project-str"></a>

Unique project name. If no project exists with this name, a new project will be created.

##### project_id: `str`<a id="project_id-str"></a>

Unique ID of a project to associate to the log. Either this or `project` must be provided.

##### session_id: `str`<a id="session_id-str"></a>

ID of the session to associate the datapoint.

##### session_reference_id: `str`<a id="session_reference_id-str"></a>

A unique string identifying the session to associate the datapoint to. Allows you to log multiple datapoints to a session (using an ID kept by your internal systems) by passing the same `session_reference_id` in subsequent log requests. Specify at most one of this or `session_id`.

##### parent_id: `str`<a id="parent_id-str"></a>

ID associated to the parent datapoint in a session.

##### parent_reference_id: `str`<a id="parent_reference_id-str"></a>

A unique string identifying the previously-logged parent datapoint in a session. Allows you to log nested datapoints with your internal system IDs by passing the same reference ID as `parent_id` in a prior log request. Specify at most one of this or `parent_id`. Note that this cannot refer to a datapoint being logged in the same request.

##### inputs: `Dict[str, Union[bool, date, datetime, dict, float, int, list, str, None]]`<a id="inputs-dictstr-unionbool-date-datetime-dict-float-int-list-str-none"></a>

The inputs passed to the prompt template.

##### source: `str`<a id="source-str"></a>

Identifies where the model was called from.

##### metadata: `Dict[str, Union[bool, date, datetime, dict, float, int, list, str, None]]`<a id="metadata-dictstr-unionbool-date-datetime-dict-float-int-list-str-none"></a>

Any additional metadata to record.

##### save: `bool`<a id="save-bool"></a>

Whether the request/response payloads will be stored on Humanloop.

##### source_datapoint_id: `str`<a id="source_datapoint_id-str"></a>

ID of the source datapoint if this is a log derived from a datapoint in a dataset.

##### provider_api_keys: [`ProviderApiKeys`](./humanloop/type/provider_api_keys.py)<a id="provider_api_keys-providerapikeyshumanlooptypeprovider_api_keyspy"></a>


API keys required by each provider to make API calls. The API keys provided here are not stored by Humanloop. If not specified here, Humanloop will fall back to the key saved to your organization.

##### num_samples: `int`<a id="num_samples-int"></a>

The number of generations.

##### stream: `bool`<a id="stream-bool"></a>

If true, tokens will be sent as data-only server-sent events. If num_samples > 1, samples are streamed back independently.

##### user: `str`<a id="user-str"></a>

End-user ID passed through to provider call.

##### seed: `int`<a id="seed-int"></a>

Deprecated field: the seed is instead set as part of the request.config object.

##### return_inputs: `bool`<a id="return_inputs-bool"></a>

Whether to return the inputs in the response. If false, the response will contain an empty dictionary under inputs. This is useful for reducing the size of the response. Defaults to true.

##### tool_choice: Union[`str`, `str`, `str`, `ToolChoice`]<a id="tool_choice-unionstr-str-str-toolchoice"></a>


Controls how the model uses tools. The following options are supported: 'none' forces the model to not call a tool; the default when no tools are provided as part of the model config. 'auto' the model can decide to call one of the provided tools; the default when tools are provided as part of the model config. Providing {'type': 'function', 'function': {name': <TOOL_NAME>}} forces the model to use the named function.

##### tool_call: Union[`str`, [`Dict[str, str]`](./humanloop/type/typing_dict_str_str.py)]<a id="tool_call-unionstr-dictstr-strhumanlooptypetyping_dict_str_strpy"></a>


NB: Deprecated with new tool_choice. Controls how the model uses tools. The following options are supported: 'none' forces the model to not call a tool; the default when no tools are provided as part of the model config. 'auto' the model can decide to call one of the provided tools; the default when tools are provided as part of the model config. Providing {'name': <TOOL_NAME>} forces the model to use the provided tool of the same name.

##### response_format: [`ResponseFormat`](./humanloop/type/response_format.py)<a id="response_format-responseformathumanlooptyperesponse_formatpy"></a>


The format of the response. Only type json_object is currently supported for chat.

#### ⚙️ Request Body<a id="⚙️-request-body"></a>

[`ChatModelConfigRequest`](./humanloop/type/chat_model_config_request.py)
#### 🔄 Return<a id="🔄-return"></a>

[`ChatResponse`](./humanloop/pydantic/chat_response.py)

#### 🌐 Endpoint<a id="🌐-endpoint"></a>

`/chat-model-config` `post`

[🔙 **Back to Table of Contents**](#table-of-contents)

---

### `humanloop.complete`<a id="humanloopcomplete"></a>

Create a completion by providing details of the model configuration in the request.

#### 🛠️ Usage<a id="🛠️-usage"></a>

```python
create_response = humanloop.complete(
    model_config={
        "provider": "openai",
        "model": "model_example",
        "max_tokens": -1,
        "temperature": 1,
        "top_p": 1,
        "presence_penalty": 0,
        "frequency_penalty": 0,
        "endpoint": "complete",
        "prompt_template": "{{question}}",
    },
    project="string_example",
    project_id="string_example",
    session_id="string_example",
    session_reference_id="string_example",
    parent_id="string_example",
    parent_reference_id="string_example",
    inputs={},
    source="string_example",
    metadata={},
    save=True,
    source_datapoint_id="string_example",
    provider_api_keys={},
    num_samples=1,
    stream=False,
    user="string_example",
    seed=1,
    return_inputs=True,
    logprobs=1,
    suffix="string_example",
)
```

#### ⚙️ Parameters<a id="⚙️-parameters"></a>

##### model_config: [`ModelConfigCompletionRequest`](./humanloop/type/model_config_completion_request.py)<a id="model_config-modelconfigcompletionrequesthumanlooptypemodel_config_completion_requestpy"></a>


The model configuration used to generate.

##### project: `str`<a id="project-str"></a>

Unique project name. If no project exists with this name, a new project will be created.

##### project_id: `str`<a id="project_id-str"></a>

Unique ID of a project to associate to the log. Either this or `project` must be provided.

##### session_id: `str`<a id="session_id-str"></a>

ID of the session to associate the datapoint.

##### session_reference_id: `str`<a id="session_reference_id-str"></a>

A unique string identifying the session to associate the datapoint to. Allows you to log multiple datapoints to a session (using an ID kept by your internal systems) by passing the same `session_reference_id` in subsequent log requests. Specify at most one of this or `session_id`.

##### parent_id: `str`<a id="parent_id-str"></a>

ID associated to the parent datapoint in a session.

##### parent_reference_id: `str`<a id="parent_reference_id-str"></a>

A unique string identifying the previously-logged parent datapoint in a session. Allows you to log nested datapoints with your internal system IDs by passing the same reference ID as `parent_id` in a prior log request. Specify at most one of this or `parent_id`. Note that this cannot refer to a datapoint being logged in the same request.

##### inputs: `Dict[str, Union[bool, date, datetime, dict, float, int, list, str, None]]`<a id="inputs-dictstr-unionbool-date-datetime-dict-float-int-list-str-none"></a>

The inputs passed to the prompt template.

##### source: `str`<a id="source-str"></a>

Identifies where the model was called from.

##### metadata: `Dict[str, Union[bool, date, datetime, dict, float, int, list, str, None]]`<a id="metadata-dictstr-unionbool-date-datetime-dict-float-int-list-str-none"></a>

Any additional metadata to record.

##### save: `bool`<a id="save-bool"></a>

Whether the request/response payloads will be stored on Humanloop.

##### source_datapoint_id: `str`<a id="source_datapoint_id-str"></a>

ID of the source datapoint if this is a log derived from a datapoint in a dataset.

##### provider_api_keys: [`ProviderApiKeys`](./humanloop/type/provider_api_keys.py)<a id="provider_api_keys-providerapikeyshumanlooptypeprovider_api_keyspy"></a>


API keys required by each provider to make API calls. The API keys provided here are not stored by Humanloop. If not specified here, Humanloop will fall back to the key saved to your organization.

##### num_samples: `int`<a id="num_samples-int"></a>

The number of generations.

##### stream: `bool`<a id="stream-bool"></a>

If true, tokens will be sent as data-only server-sent events. If num_samples > 1, samples are streamed back independently.

##### user: `str`<a id="user-str"></a>

End-user ID passed through to provider call.

##### seed: `int`<a id="seed-int"></a>

Deprecated field: the seed is instead set as part of the request.config object.

##### return_inputs: `bool`<a id="return_inputs-bool"></a>

Whether to return the inputs in the response. If false, the response will contain an empty dictionary under inputs. This is useful for reducing the size of the response. Defaults to true.

##### logprobs: `int`<a id="logprobs-int"></a>

Include the log probabilities of the top n tokens in the provider_response

##### suffix: `str`<a id="suffix-str"></a>

The suffix that comes after a completion of inserted text. Useful for completions that act like inserts.

#### ⚙️ Request Body<a id="⚙️-request-body"></a>

[`CompletionRequest`](./humanloop/type/completion_request.py)
#### 🔄 Return<a id="🔄-return"></a>

[`CompletionResponse`](./humanloop/pydantic/completion_response.py)

#### 🌐 Endpoint<a id="🌐-endpoint"></a>

`/completion` `post`

[🔙 **Back to Table of Contents**](#table-of-contents)

---

### `humanloop.complete_deployed`<a id="humanloopcomplete_deployed"></a>

Create a completion using the project's active deployment.

The active deployment can be a specific model configuration.

#### 🛠️ Usage<a id="🛠️-usage"></a>

```python
create_deployed_response = humanloop.complete_deployed(
    project="string_example",
    project_id="string_example",
    session_id="string_example",
    session_reference_id="string_example",
    parent_id="string_example",
    parent_reference_id="string_example",
    inputs={},
    source="string_example",
    metadata={},
    save=True,
    source_datapoint_id="string_example",
    provider_api_keys={},
    num_samples=1,
    stream=False,
    user="string_example",
    seed=1,
    return_inputs=True,
    logprobs=1,
    suffix="string_example",
    environment="string_example",
)
```

#### ⚙️ Parameters<a id="⚙️-parameters"></a>

##### project: `str`<a id="project-str"></a>

Unique project name. If no project exists with this name, a new project will be created.

##