# carter-py

## Prerequisites

In order to use `carter-py` you'll need to sign up to sign up to [CarterAPI](https://www.carterapi.com/) and create an agent. CarterAPI has excellent documentation.

## Installation

*`pip install carter-py`*

## The Carter Object

The main component of `carter-py` is the `Carter` class. This class provides a set of methods to interact with your carter agent.

```python
from carterpy import Carter


# Replace YOUR_API_KEY with your actual API key

carter = Carter("YOUR_API_KEY")

# Send a message to the API

response = carter.say("Hello, world!", "player123")

# Print the response text

print(response.output_text)
```

Pass in the apiKey of your specific agent - remember to keep this secret while developing and in production as this will allow anyone access to your agent.

### Async

`carter-py` is compatible with asynchronous code through importing the async version of the class.

```python
import asyncio
from carterpy import AsyncCarter

async def main():
    async_carter = AsyncCarter("YOUR_API_KEY)

    # with carter object already created
    interaction = await async_carter.say("hello", "player123")
    personalise = await async_carter.personalise("Hello, world!", "player_id")
    opener = await async_carter.opener("player123")
    print(interaction.output_text)

asyncio.run(main())
```

### Speak

When using any of the following methods, the output audio will not be returned by default as this currently introduces significant latency on the API end. If you want to receive the audio you have two options. You can set the `speak` parameter to `True`when creating the Carter object, or you can set it to `True`when calling the method. When calling a function `carter-py` will first check if the `speak` parameter has been overridden in the function call, if it hasn't, it will use the class default.

```python
    carter = Carter('your-api-key') 
    # False by default

    interaction = carter.say("Hello, world!", "player123") 
    # No audio will be returned, because you have not overridden the default on the class

    interaction = carter.say("Hello, world!", "player123", speak=True) 
    # Audio will be returned, because you have overridden the default on the class
```

Documentation on `say()` is included in further sections.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lazylyrics.gitbook.io/carter-py-v1/carter-py.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.