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 Grok).

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 Grok (grok-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 Gemini API key
  • Grok (XAI) API key

Installation

1. Clone the repository:

   git clone https://github.com/JerrySu5379/Starferry.git
   cd Starferry
   

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   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

   cp env.example .env
   

5. Start the server:

   python -m src.main
   

Alternative way to install and run the server

pip install starferry

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 kind of bingo items to generate
• service (required): The AI service to use (options: "openai", "gemini", "grok")

Response:

{
  "items": "Item 1|Item 2|Item 3|...|Item 25",
  "error": null
}

Rate Limiting: The API is limited to 10 requests per IP address per 30-minute window.

Project Structure

starferry/
├── .env                # Environment variables (API keys, configuration)
├── env.example         # Example environment file
├── requirements.txt    # Python dependencies
├── README.md           # Project documentation
├── src/
│   ├── main.py         # FastAPI application entry point
│   ├── routers/
│   │   └── bingo.py    # Bingo generation API endpoint
│   ├── services/
│   │   ├── openai_service.py    # OpenAI integration
│   │   ├── gemini_service.py    # Google Gemini integration
│   │   └── grok_service.py      # Grok integration
│   └── utils/
│       └── ip_tracker.py        # IP-based rate limiting
└── tests/              # Test suite

Architecture

Starferry follows a clean architecture pattern with distinct layers:

1. API Layer (routers): Handles HTTP requests and responses
2. Service Layer (services): Manages AI provider integrations
3. Utility Layer (utils): Provides supporting functionality like rate limiting

The application is designed to be extensible, making it easy to add new AI providers or additional functionality in the future.

Environment Variables

License

MIT

Contributing

• Name: JerrySu5379
• Email: jerrysu5379@gmail.com