DOCSEARCHbyAlgolia
Submit Docs

fastapi_poe

repository·main·Indexed 42 days ago

https://github.com/poe-platform/fastapi_poe

A Python framework for building bots that implement the Poe protocol using the FastAPI web framework. It provides the PoeBot class for defining bot behavior, tools for streaming responses via PartialResponse, and utilities like make_app for creating production-ready FastAPI applications. The framework supports authentication via POE_ACCESS_KEY, file attachments, and the ability to invoke other Poe bots using stream_request and get_bot_response.

Tokens
10.2K
Snippets
38
Records
52
Agent score
52%

What's inside fastapi_poe

  1. Communicate bot responses using `PartialResponse`

    main

    When implementing a bot, yield fp.PartialResponse objects to communicate with Poe. Poe automatically concatenates the text fields.

    Fields:

    • text (str): The next chunk of text to display. Note: This should be the next token/chunk, as Poe handles concatenation.
    • data (Optional[dict[str, Any]]): Arbitrary JSON data, primarily used for OpenAI function calling.
    • is_suggested_reply (bool): If True, creates a suggested reply button with the provided text.
    • is_replace_response (bool): If True, clears previously displayed text and replaces it with this value.
    # Inside a bot implementation
async def get_response(self, ...):
    yield fp.PartialResponse(text="Hello")
    yield fp.PartialResponse(text=" world!")
    yield fp.PartialResponse(text=" How can I help?", is_suggested_reply=True)

  2. Define bot behavior with `fp.PoeBot`

    main

    The fp.PoeBot class is the core abstraction used to define how your bot responds to users. You implement your logic by overriding its methods and then pass an instance of this class to fp.make_app to create a FastAPI application.

    Key Parameters for PoeBot initialization:

    • path (str): The URL path where the bot is served (default: /). Useful for hosting multiple bots on one server.
    • access_key (Optional[str]): The access key used to validate requests from Poe. This must match the key provided at poe.com/create_bot. Providing this enables features like file output.
    • should_insert_attachment_messages (bool): If True (default), the bot automatically parses user attachments and inserts them as messages into the conversation context.
    import fastapi_poe as fp

class MyBot(fp.PoeBot):
    # Implementation goes here
    pass

# Pass to make_app to create the FastAPI app
app = fp.make_app(bot=MyBot(access_key="YOUR_KEY"))

  4. Enable authentication for Poe requests

    main

    Poe servers validate requests using an Authorization HTTP header in the format Bearer <access_key>. To ensure your bot only responds to authorized Poe requests, you must provide the access key configured in your Poe bot settings.

    You can enable authentication in two ways:

    1. Set the POE_ACCESS_KEY environment variable.
    2. Pass the access_key parameter directly to the fp.run() function.
    if __name__ == "__main__":
    fp.run(EchoBot(), access_key=<key>)

  5. Create a custom bot by inheriting from PoeBot

    main

    To build a custom bot, inherit from the fp.PoeBot class and implement the get_response method. The get_response method is an asynchronous generator that receives a fp.QueryRequest and yields fp.PartialResponse objects. This allows for streaming responses back to the Poe platform.

    To run the bot locally for development, use fp.run() with your bot instance. Setting allow_without_key=True allows you to run the server without providing a valid Poe access key during local testing.

    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)

  6. Implement a custom PoeBot

    main

    To create a bot, subclass PoeBot and override its core methods to define your bot's behavior. The most important method to override is get_response, which handles user queries. You can also override get_settings for bot configuration, and various on_* methods to handle user feedback, reactions, or errors.

    Core Methods to Override

    • get_response(request: QueryRequest): Define how your bot responds to a user query. It must return an AsyncIterable of response objects (like PartialResponse or ServerSentEvent).
    • get_response_with_context(request: QueryRequest, context: RequestContext): A version of get_response that provides access to the underlying HTTP RequestContext.
    • get_settings(setting: SettingsRequest): Define the settings available for your bot.
    • on_feedback(feedback_request: ReportFeedbackRequest): Handle user feedback.
    • on_reaction(reaction_request: ReportReactionRequest): Handle user reactions.
    • on_error(error_request: ReportErrorRequest): Handle errors reported by the Poe server.
    import fastapi_poe as fp

class MyBot(fp.PoeBot):
    async def get_response(self, request: fp.QueryRequest) -> AsyncIterable[fp.PartialResponse]:
        last_message = request.query[-1].content
        yield fp.PartialResponse(text=f"You said: {last_message}")

  7. Invoke another Poe bot with `get_bot_response`

    main

    Use fp.get_bot_response to call another Poe bot asynchronously from your own script or shell. This is useful for building bots that act as orchestrators or use other bots as tools.

    Parameters:

    • messages (list[ProtocolMessage]): The conversation history.
    • bot_name (str): The name of the bot to invoke.
    • api_key (str): Your Poe API key (from poe.com/api_key).
    • tools (Optional[list[ToolDefinition]]): Tool definitions for OpenAI function calling.
    • tool_executables (Optional[list[Callable]]): Functions corresponding to the tools.
    • temperature (Optional[float]): Inference temperature.
    • skip_system_prompt (Optional[bool]): Whether to skip the system prompt.
    • logit_bias (Optional[dict[str, float]]): Logit bias configuration.
    • stop_sequences (Optional[list[str]]): Stop sequences.
    • base_url (str): Defaults to https://api.poe.com/bot/.
    import fastapi_poe as fp

# Example usage (conceptual)
async for chunk in fp.get_bot_response(
    messages=[...],
    bot_name="target_bot",
    api_key="YOUR_API_KEY"
):
    print(chunk.text)

  8. Handle user feedback and reactions

    main

    You can override several methods to react to user interactions with your bot's responses:

    • on_feedback(feedback_request): Triggered when a user provides feedback on a response.
    • on_reaction_with_context(reaction_request, context): Triggered when a user reacts to a response. This version provides the RequestContext.
    • on_error(error_request): Triggered when the Poe server encounters an issue processing your bot's response.

    All these methods return None and are used for side effects like logging or updating databases.

  9. Upload files to Poe with `upload_file`

    main

    Upload raw bytes or a file via URL to Poe. This returns an Attachment object that can be sent back in a bot response or stored for later.

    Parameters:

    • file (Optional[Union[bytes, BinaryIO]]): The file content.
    • file_url (Optional[str]): The URL of the file to upload.
    • file_name (Optional[str]): Required if file is provided as raw bytes.
    • api_key (str): Your Poe API key or the access_key if running on a Poe server bot.

    Use fp.upload_file_sync for a synchronous version.

    import fastapi_poe as fp

# Uploading via URL
attachment = await fp.upload_file(file_url="https://example.com/image.png", api_key="...")

# Uploading via bytes
attachment = await fp.upload_file(file=b"content", file_name="file.txt", api_key="...")

  11. Invoke other Poe bots with `fp.stream_request`

    main

    The fp.stream_request function is the entry point for the Bot Query API, allowing your bot to use other bots on Poe for inference (functional calling/agentic behavior).

    Parameters:

    • request (QueryRequest): The incoming query from Poe.
    • bot_name (str): The name of the target bot you want to invoke.
    • api_key (str): Your Poe API key (from poe.com/api_key).
    • tools (Optional[list[ToolDefinition]]): Definitions for OpenAI-style function calling.
    • tool_executables (Optional[list[Callable]]): The actual Python functions to run when a tool is suggested. If provided, the LLM-suggested tools run automatically before the final response is returned.

  12. Get the full response with `get_final_response`

    main

    A helper function for the bot query API that waits for all tokens to be generated and concatenates them into a single full response before returning. This is useful when you don't need streaming behavior.

    Parameters:

    • request (QueryRequest): The query request object from Poe.
    • bot_name (str): The bot to invoke.
    • api_key (str): Your Poe API key. Note: if provided, compute points are charged to the account associated with this key.