### Install fastapi-poe

Source: https://github.com/poe-platform/fastapi_poe/blob/main/README.md

Installs the fastapi-poe package from the Python Package Index (PyPI). This is the first step to using the library for bot development.

```bash
pip install fastapi-poe
```

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

### Run CI Checks Locally

Source: https://github.com/poe-platform/fastapi_poe/blob/main/CONTRIBUTING.md

Instructions to set up and run the project's Continuous Integration checks locally using pre-commit. This ensures code quality and consistency before committing changes.

```shell
pip install pre-commit
pre-commit run --all
```

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

### Update Version and Release

Source: https://github.com/poe-platform/fastapi_poe/blob/main/CONTRIBUTING.md

Steps to update the project's version number in pyproject.toml, create a pull request, merge it after CI passes, and then create a new release on GitHub.

```shell
# Make a PR updating the version number in pyproject.toml
# Example: https://github.com/poe-platform/fastapi_poe/pull/2
# Merge it once CI passes
# Go to https://github.com/poe-platform/fastapi_poe/releases/new and make a new release
# The tag should be of the form "0.0.X"
# Fill in the release notes with some description of what changed since the last release.
# GitHub Actions will generate the release artefacts and upload them to PyPI
# Check PyPI (https://pypi.org/project/fastapi-poe/) to verify that the release went through.
```

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

### Get Full Bot Response

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

The `fp.get_final_response` is a utility function for the Bot Query API that aggregates all streamed tokens into a single, complete response. It requires a `QueryRequest` object, the target `bot_name`, and your `api_key`. It's useful for scenarios where the full response is needed before proceeding.

```APIDOC
fp.get_final_response(
    request: QueryRequest,
    bot_name: str,
    api_key: str = ""
)
```

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

### FastAPI App Creation

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Function to create and configure a FastAPI application for serving Poe bots. Allows hosting single or multiple bots and handles access key management.

```APIDOC
fp.make_app(bot: Union[PoeBot, Sequence[PoeBot]], access_key: str = "", bot_name: str = "", api_key: str = "", allow_without_key: bool = False, app: Optional[FastAPI] = None)
  Creates an app object for your bot(s).
  Parameters:
    bot (Union[PoeBot, Sequence[PoeBot]]): A bot object or a list of bot objects.
    access_key (str): The access key to use. Reads from POE_ACCESS_KEY env var if not provided.
    bot_name (str): The name of the bot as it appears on poe.com.
    api_key (str): DEPRECATED: Use access_key instead.
    allow_without_key (bool): If True, the server starts without an access key check.
    app (Optional[FastAPI]): An existing FastAPI app instance to configure.
  Returns: FastAPI: A FastAPI app configured to serve your bot.
```

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

### Serve Poe Bot Locally

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

The `fp.run` function serves a Poe bot using a FastAPI application. It is intended for local development and uses the same parameters as `make_app`. It does not return any value.

```python
fp.run()
```

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

### Enable Bot Authentication

Source: https://github.com/poe-platform/fastapi_poe/blob/main/README.md

Shows how to enable authentication for your bot by either setting the POE_ACCESS_KEY environment variable or passing the `access_key` parameter directly to the `fp.run` function.

```python
if __name__ == "__main__":
    fp.run(EchoBot(), access_key=<key>)
```

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

### Query Bot API Entry Point

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

The `fp.stream_request` function is the primary entry point for the Bot Query API, enabling inference using other Poe bots. It requires a `QueryRequest` object, the target `bot_name`, and optionally an `api_key` for script usage. It also supports OpenAI function calling via `tools` and `tool_executables`.

```APIDOC
fp.stream_request(
    request: QueryRequest,
    bot_name: str,
    api_key: str = "",
    tools: Optional[list[ToolDefinition]] = None,
    tool_executables: Optional[list[Callable]] = None
)
```

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

### Settings Request/Response API

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

APIs for settings requests and responses. SettingsRequest currently contains no fields, while SettingsResponse represents the bot's response to a settings object.

```APIDOC
SettingsRequest:
  Request parameters for a settings request. Currently, this contains no fields but this might get updated in the future.

SettingsResponse:
  An object representing your bot's response to a settings object.
```

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

### PoeBot Methods for Handling User Interaction

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

This section details the methods within the `PoeBot` class used to handle user queries, settings, feedback, and errors. These methods can be overridden to customize bot functionality. They include versions with and without request context for flexibility.

```APIDOC
PoeBot.get_response(request: QueryRequest) -> AsyncIterable[PartialResponse]
  Override this to define your bot's response given a user query.
  Parameters:
    request: An object representing the chat response request from Poe, containing chat state and other information.
  Returns:
    AsyncIterable of PartialResponse objects representing the bot's response to Poe servers, displayed to the user.
  Example usage:
    async def get_response(self, request: fp.QueryRequest) -> AsyncIterable[fp.PartialResponse]:
        last_message = request.query[-1].content
        yield fp.PartialResponse(text=last_message)

PoeBot.get_response_with_context(request: QueryRequest, context: RequestContext) -> AsyncIterable[Union[PartialResponse, ErrorResponse]]
  A version of `get_response` that also includes the request context information. By default, this will call `get_response`.
  Parameters:
    request: An object representing the chat response request from Poe.
    context: An object representing the current HTTP request.
  Returns:
    AsyncIterable of PartialResponse or ErrorResponse objects.

PoeBot.get_settings(setting: SettingsRequest) -> SettingsResponse
  Override this to define your bot's settings.
  Parameters:
    setting: An object representing the settings request.
  Returns:
    SettingsResponse object representing the bot's settings.

PoeBot.get_settings_with_context(setting: SettingsRequest, context: RequestContext) -> SettingsResponse
  A version of `get_settings` that also includes the request context information. By default, this will call `get_settings`.
  Parameters:
    setting: An object representing the settings request.
    context: An object representing the current HTTP request.
  Returns:
    SettingsResponse object representing the bot's settings.

PoeBot.on_feedback(feedback_request: ReportFeedbackRequest) -> None
  Override this to record feedback from the user.
  Parameters:
    feedback_request: An object representing the Feedback request from Poe, sent when a user provides feedback on a bot's response.
  Returns: None

PoeBot.on_feedback_with_context(feedback_request: ReportFeedbackRequest, context: RequestContext) -> None
  A version of `on_feedback` that also includes the request context information. By default, this will call `on_feedback`.
  Parameters:
    feedback_request: An object representing a feedback request from Poe.
    context: An object representing the current HTTP request.
  Returns: None

PoeBot.on_reaction_with_context(reaction_request: ReportReactionRequest, context: RequestContext) -> None
  Override this to record a reaction from the user. This also includes the request context.
  Parameters:
    reaction_request: An object representing a reaction request from Poe.
    context: An object representing the current HTTP request.
  Returns: None

PoeBot.on_error(error_request: ReportErrorRequest) -> None
  Override this to record errors from the Poe server.
  Parameters:
    error_request: An object representing an error request from Poe, sent when the Poe server encounters an issue processing a bot's response.
  Returns: None
```

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

### Poe Protocol Response Settings

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Defines configuration options for Poe protocol responses, including versioning, bot dependencies, attachment handling, message introductions, and image comprehension.

```python
response_version: int = 2
server_bot_dependencies: dict[str, int] = {}
allow_attachments: bool = True
introduction_message: str = ""
expand_text_attachments: bool = True
enable_image_comprehension: bool = False
enforce_author_role_alternation: bool = False
enable_multi_bot_chat_prompting: bool = True
parameter_controls: Optional[ParameterControls] = None
```

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

### OpenAI Tool Definitions

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Details the structures for defining and calling tools used in OpenAI function calling, including tool definitions, tool calls, and tool results.

```APIDOC
fp.ToolDefinition:
  type: str
  function: FunctionDefinition

fp.ToolCallDefinition:
  id: str
  type: str
  function: FunctionDefinition

fp.ToolResultDefinition:
  role: str
  name: str
  tool_call_id: str
  content: str
```

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

### Invoke Another Poe Bot (Async)

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

The `fp.get_bot_response` function allows invoking another Poe bot asynchronously. It takes a list of `ProtocolMessage` objects, the `bot_name`, and your `api_key`. Advanced options include `tools`, `tool_executables`, `temperature`, `skip_system_prompt`, `logit_bias`, `stop_sequences`, and `base_url`. An optional `httpx.AsyncClient` session can be provided.

```APIDOC
fp.get_bot_response(
    messages: list[ProtocolMessage],
    bot_name: str,
    api_key: str,
    tools: Optional[list[ToolDefinition]] = None,
    tool_executables: Optional[list[Callable]] = None,
    temperature: Optional[float] = None,
    skip_system_prompt: Optional[bool] = None,
    logit_bias: Optional[dict[str, float]] = None,
    stop_sequences: Optional[list[str]] = None,
    base_url: str = "https://api.poe.com/bot/",
    session: Optional[httpx.AsyncClient] = None
)
```

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

### Create a Basic Echo Bot

Source: https://github.com/poe-platform/fastapi_poe/blob/main/README.md

Demonstrates how to create a simple bot that echoes the last message received. It inherits from `fp.PoeBot` and implements the `get_response` method to yield partial responses.

```python
import fastapi_poe as fp

class EchoBot(fp.PoeBot):
    async def get_response(self, request: fp.QueryRequest):
        last_message = request.query[-1].content
        yield fp.PartialResponse(text=last_message)

if __name__ == "__main__":
    fp.run(EchoBot(), allow_without_key=True)
```

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

### PoeBot Prompt Formatting

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Utilities for formatting message prompts, specifically for concatenating messages from the same author to ensure role alternation.

```APIDOC
PoeBot.make_prompt_author_role_alternated(protocol_messages: Sequence[ProtocolMessage])
  Concatenates consecutive messages from the same author into a single message.
  Parameters:
    protocol_messages (Sequence[ProtocolMessage]): The messages to make alternated.
  Returns: Sequence[ProtocolMessage]: The modified messages.
```

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

### PoeBot Cost Management

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Methods for capturing and authorizing costs associated with monetized bot creators. Provides functionality to track and manage financial aspects of bot usage.

```APIDOC
PoeBot.capture_cost(request: QueryRequest, amounts: Union[list[CostItem], CostItem])
  Captures variable costs for monetized bot creators.
  Parameters:
    request (QueryRequest): The currently handled QueryRequest object.
    amounts (Union[list[CostItem], CostItem]): The amounts to be captured.
  Returns: None
```

```APIDOC
PoeBot.authorize_cost(request: QueryRequest, amounts: Union[list[CostItem], CostItem])
  Authorizes a cost for monetized bot creators.
  Parameters:
    request (QueryRequest): The currently handled QueryRequest object.
    amounts (Union[list[CostItem], CostItem]): The amounts to be authorized.
  Returns: None
```

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

### Query Request API

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

API for making query requests to a Poe bot. Includes parameters for the query, user and conversation identifiers, access key, temperature, and other settings. Used to represent the current state of the chat.

```APIDOC
QueryRequest:
  Fields:
  - `query` (`list[ProtocolMessage]`): list of message representing the current state of the chat.
  - `user_id` (`Identifier`): an anonymized identifier representing a user. This is persistent for subsequent requests from that user.
  - `conversation_id` (`Identifier`): an identifier representing a chat. This is persistent for subsequent request for that chat.
  - `message_id` (`Identifier`): an identifier representing a message.
  - `access_key` (`str = "<missing>"`): contains the access key defined when you created your bot on Poe.
  - `temperature` (`float | None = None`): Temperature input to be used for model inference.
  - `skip_system_prompt` (`bool = False`): Whether to use any system prompting or not.
  - `logit_bias` (`dict[str, float] = {}`)
  - `stop_sequences` (`list[str] = []`)
  - `language_code` (`str = "en"`): BCP 47 language code of the user's client.
  - `bot_query_id` (`str = ""`): an identifier representing a bot query.
```

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

### fastapi_poe PoeBot Class Overview

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

The `PoeBot` class is the core component for defining bot behavior in the fastapi_poe library. It allows customization of bot responses, settings, and feedback handling. Key parameters include the bot's serving path, an optional access key for security, and flags to control attachment processing.

```APIDOC
PoeBot:
  __init__(path: str = "/", access_key: Optional[str] = None, should_insert_attachment_messages: bool = True, concat_attachments_to_message: bool = False)
    path: The path at which your bot is served. Defaults to "/". Useful for serving multiple bots.
    access_key: Access key for bot validation. Must match the key provided in Poe bot creation. If None, certain features like file output will be unavailable.
    should_insert_attachment_messages: Flag to parse content from attachments and insert as messages. Defaults to True. Recommended to keep enabled for bot comprehension of attachments.
    concat_attachments_to_message: DEPRECATED: Use `should_insert_attachment_messages` instead.
```

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

### Invoke Another Poe Bot (Sync)

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

The `fp.get_bot_response_sync` function provides a synchronous wrapper for the asynchronous `fp.get_bot_response`. It's suitable for direct use in synchronous contexts, returning partial responses. Parameters are identical to the async version, including `messages`, `bot_name`, `api_key`, function calling support (`tools`, `tool_executables`), and generation parameters.

```APIDOC
fp.get_bot_response_sync(
    messages: list[ProtocolMessage],
    bot_name: str,
    api_key: str,
    tools: Optional[list[ToolDefinition]] = None,
    tool_executables: Optional[list[Callable]] = None,
    temperature: Optional[float] = None,
    skip_system_prompt: Optional[bool] = None,
    logit_bias: Optional[dict[str, float]] = None,
    stop_sequences: Optional[list[str]] = None,
    base_url: str = "https://api.poe.com/bot/",
    session: Optional[httpx.AsyncClient] = None
)
```

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

### Bot Response APIs (Partial, Error, Meta, Data)

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

APIs for different types of bot responses: PartialResponse for streaming text, ErrorResponse for communicating errors, MetaResponse for meta events, and DataResponse for attaching arbitrary data to the response.

```APIDOC
PartialResponse:
  Fields:
  - `text` (`str`): The actual text you want to display to the user. Note that this should solely be the text in the next token since Poe will automatically concatenate all tokens before displaying the response to the user.
  - `data` (`Optional[dict[str, Any]]`): Used to send arbitrary json data to Poe. This is currently only used for OpenAI function calling.
  - `is_suggested_reply` (`bool = False`): Setting this to true will create a suggested reply with the provided text value.
  - `is_replace_response` (`bool = False`): Setting this to true will clear out the previously displayed text to the user and replace it with the provided text value.

ErrorResponse:
  Fields:
  - `allow_retry` (`bool = False`): Whether or not to allow a user to retry on error.
  - `error_type` (`Optional[ErrorType] = None`): An enum indicating what error to display.

MetaResponse:
  Fields:
  - `suggested_replies` (`bool = False`): Whether or not to enable suggested replies.
  - `content_type` (`ContentType = "text/markdown"`): Used to describe the format of the response. The currently supported values are `text/plain` and `text/markdown`.
  - `refetch_settings` (`bool = False`): Used to trigger a settings fetch request from Poe. A more robust way to trigger this is documented at: https://creator.poe.com/docs/server-bots-functional-guides#updating-bot-settings

DataResponse:
  Fields:
  - `metadata` (`str`): String of data to attach to the bot response.
```

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

### Poe Feedback and Reaction Request Parameters

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Specifies the data structures for reporting feedback, reactions, and errors within the Poe protocol. These include message, user, and conversation identifiers, along with feedback types and optional reasons.

```APIDOC
fp.ReportFeedbackRequest:
  message_id: Identifier
  user_id: Identifier
  conversation_id: Identifier
  feedback_type: FeedbackType

fp.ReportReactionRequest:
  message_id: Identifier
  user_id: Identifier
  conversation_id: Identifier
  reaction: str

fp.ReportErrorRequest:
  message: str
  metadata: dict[str, Any]

fp.MessageFeedback:
  type: FeedbackType
  reason: Optional[str]
```

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

### File Upload API

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

API for uploading files to Poe. Includes parameters for file data, URL, and name, along with API key authentication. Returns an Attachment object representing the uploaded file.

```APIDOC
Parameters:
  - `file` (`Optional[Union[bytes, BinaryIO]] = None`): The file to upload.
  - `file_url` (`Optional[str] = None`): The URL of the file to upload.
  - `file_name` (`Optional[str] = None`): The name of the file to upload. Required if `file` is provided as raw bytes.
  - `api_key` (`str = ""`): Your Poe API key, available at poe.com/api_key. This can also be the `access_key` if called from a Poe server bot.

Returns:
  - `Attachment`: An Attachment object representing the uploaded file.

Methods:
  - `fp.upload_file_sync`: Synchronous wrapper around the async `upload_file`.
```

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

### Upload File to Poe

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

The `fp.upload_file` function enables uploading files to Poe, either directly via bytes or through a URL. It returns an `Attachment` object, which can be used in bot responses or stored for future use.

```python
fp.upload_file(file_content: Union[bytes, str])
```

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

### PoeBot Message Attachment Handling

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Methods for handling attachments in bot messages. This includes posting attachments with various options and inserting attachment content into message bodies.

```APIDOC
PoeBot.post_message_attachment(message_id: Identifier, download_url: Optional[str] = None, download_filename: Optional[str] = None, file_data: Optional[Union[bytes, BinaryIO]] = None, filename: Optional[str] = None, access_key: str)
  Parameters:
    message_id (Identifier): The message id associated with the current QueryRequest.
    download_url (Optional[str]): A url to the file to be attached.
    download_filename (Optional[str]): A filename for the downloaded attachment.
    file_data (Optional[Union[bytes, BinaryIO]]): The contents of the file to be uploaded.
    filename (Optional[str]): The name of the file to be attached.
    access_key (str): DEPRECATED: Use bot object's access_key instead.
  Returns: AttachmentUploadResponse
  Note: Provide either download_url or both file_data and filename.
```

```APIDOC
PoeBot.concat_attachment_content_to_message_body(query_request: QueryRequest)
  DEPRECATED: Use insert_attachment_messages instead.
  Concatenates received attachment file content into the message body.
  Parameters:
    query_request (QueryRequest): The request object from Poe.
  Returns: QueryRequest: The request object after attachments are unpacked.
```

```APIDOC
PoeBot.insert_attachment_messages(query_request: QueryRequest)
  Inserts messages containing attachment contents before the last user message.
  Parameters:
    query_request (QueryRequest): The request object from Poe.
  Returns: QueryRequest: The request object after attachments are unpacked.
```

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

### PoeBot Error Handling

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Handles errors that occur during bot processing, optionally including request context. By default, it calls the base `on_error` method.

```APIDOC
PoeBot.on_error_with_context(error_request: ReportErrorRequest, context: RequestContext)
  Parameters:
    error_request (ReportErrorRequest): An object representing an error request from Poe.
    context (RequestContext): An object representing the current HTTP request.
  Returns: None
```

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

### Protocol Message API

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

API for defining messages used in the Poe protocol. Includes fields for role, sender ID, content, parameters, content type, timestamp, message ID, feedback, attachments, and metadata.

```APIDOC
ProtocolMessage:
  Fields:
  - `role` (`Literal["system", "user", "bot"]`)
  - `sender_id` (`Optional[str]`)
  - `content` (`str`)
  - `parameters` (`dict[str, Any] = {}`)
  - `content_type` (`ContentType="text/markdown"`)
  - `timestamp` (`int = 0`)
  - `message_id` (`str = ""`)
  - `feedback` (`list[MessageFeedback] = []`)
  - `attachments` (`list[Attachment] = []`)
  - `metadata` (`Optional[str] = None`)
```

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

### Attachment Upload Response API

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

API for the result of a post_message_attachment request. Includes the URL, MIME type, and inline reference of the attachment.

```APIDOC
AttachmentUploadResponse:
  Fields:
  - `attachment_url` (`Optional[str]`): The URL of the attachment.
  - `mime_type` (`Optional[str]`): The MIME type of the attachment.
  - `inline_ref` (`Optional[str]`): The inline reference of the attachment. if post_message_attachment is called with is_inline=False, this will be None.
```

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

### Poe Attachment Structure

Source: https://github.com/poe-platform/fastapi_poe/blob/main/docs/api_reference.md

Defines the structure for attachments within Poe protocol messages, including URL, content type, name, and optional inline referencing and parsed content.

```APIDOC
fp.Attachment:
  url: str
  content_type: str
  name: str
  inline_ref: Optional[str] = None
  parsed_content: Optional[str] = None
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.