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

**Response:**
```json
{
  "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