Starferry

# Starferry Documentation

## Overview

Starferry is a FastAPI-based API service that generates custom bingo game items using multiple AI providers. The service accepts prompts from users and returns 25 bingo items generated by the selected AI model (OpenAI, Google's Gemini, or Gemini).

## Pypi Project

https://pypi.org/project/starferry/

## Features

- **Multi-Provider AI Integration**: Generate content using OpenAI (GPT-4o-mini), Google's Gemini (gemini-2.0-flash), or Gemini (gemini-2-latest)
- **Standardized Output Format**: Consistently delivers 25 bingo items separated by the '|' character
- **Rate Limiting**: Built-in IP-based rate limiting (10 requests per 30 minutes)
- **API-First Design**: Clean REST API with FastAPI
- **Cross-Origin Resource Sharing**: Configured with CORS support for frontend integration

## Setup

### Prerequisites

- Python 3.10+
- API keys for the AI providers you plan to use:
  - OpenAI API key
  - Google Claude API key
  - Gemini (XAI) API key

### Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/JerrySu5379/Starferry.git
   cd Starferry
   ```

2. Create and activate a virtual environment:
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

4. Configure environment variables:
   - Copy the `env.example` file to `.env`
   - Fill in your API keys and other required configuration
   ```bash
   cp env.example .env
   ```

5. Start the server:
   ```bash
   python -m src.main
   ```

### Alternative way to install and run the server

```bash
pip install starferry
```

```bash
starferry
```

The API will be available at http://localhost:8008.

## API Documentation

### Generate Bingo Items

Generates 25 bingo items based on the provided prompt using the specified AI service.

**Endpoint:** `POST /api/bingo`

**Form Parameters:**
- `prompt` (required): The prompt describing what