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

Variable	Description
OPENAI_API_KEY	API key for OpenAI services
GEMINI_API_KEY	API key for Google's Gemini services
XAI_API_KEY	API key for Grok services
SURREAL_DB_URL	SurrealDB connection URL
SURREAL_DB_USER	SurrealDB username
SURREAL_PASSWORD	SurrealDB password
SURREAL_NS	SurrealDB namespace
SURREAL_DB	SurrealDB database name

License

MIT

Contributing

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