How mrjwj34/hagemi works
Project Type and Purpose
• This project is a backend API proxy built using FastAPI. It serves as a translation layer between clients using OpenAI-compatible API calls and Google’s Gemini model API.
• The proxy handles API key management (rotating through multiple Gemini API keys), password protection, and rate limiting. It is designed for deployment (for example on Hugging Face Spaces) as well as potential local execution.
Analyzing the File Structure
• Top-Level Files:
• Dockerfile: Indicates containerization support.
• readme.md: Contains project description and deployment instructions.
• requirements.txt: Lists the dependencies needed by the application.
• The “app” directory contains the core application code:
• __init__.py: Likely sets up packages.
• main.py: The entry point that creates and configures the FastAPI app and routes.
• gemini.py: Likely contains the logic to convert OpenAI-style requests into Gemini API requests and handle API key rotation.
• models.py: Contains data models perhaps for request/response validation.
• utils.py: Contains helper functions that support various parts of the application.
Key System Components
a. Client Layer:
• Represents any client sending requests in OpenAI format.
• Indicates the endpoint /v1/chat/completions and the model list interface request.
b. FastAPI Web Server (Backend API):
• Encompasses the FastAPI instance defined in app/main.py.
• Contains the routing handlers that map the incoming HTTP requests to their respective business logic.
c. Authentication and Request Validation Module:
• Represents the password protection mechanisms that check access via the environment-variable configured PASSWORD.
• Illustrates request validation and rate limiting (using environment variables for MAX_REQUESTS_PER_MINUTE and MAX_REQUESTS_PER_DAY_PER_IP).
d. Gemini API Conversion Module:
• Shown as a component within the backend that uses gemini.py and possibly parts of models.py.
• Converts incoming OpenAI-format requests into the required Gemini API format.
• Manages API key rotation (using the configured GEMINI_API_KEYS provided as an environment variable).
e. External Gemini API:
• Depicts the external Gemini model endpoint which is called by the Gemini API conversion module.
f. Supporting Utilities:
• Modules in utils.py which could include logging, error handling, and other ancillary functions.
g. Docker Container:
• That the entire application is containerized using the Dockerfile.
h. Deployment Environment (e.g., Hugging Face Spaces):
• Cloud service environment where the app is deployed and managed via secrets and automatic build/deployment.
Architectural Patterns and Design Principles
• Separation of Concerns: Distinguish between the API gateway (FastAPI server), authentication/rate limiting middleware, and the business logic of converting requests.
• Modular Architecture: Each file (gemini.py, models.py, utils.py) represents a modular component that focuses on a single responsibility.
• API Compatibility: The design preserves the OpenAI API request/response patterns while adapting them to Gemini’s requirements.