How snailyp/gemini-balance works
Gemini Balance is a FastAPI proxy and load balancer for Gemini, with Gemini and OpenAI-compatible interfaces. The main path is a client request through routing and authentication, key selection, chat/embedding/image services, and an upstream API call; administration and monitoring provide parallel workflows. README capability statements cover features whose route or implementation details were not sampled. Edges below are limited to relationships explicit in excerpts, the SOURCE INDEX, or README; unsampled subsystems have no speculative wiring.
Main entry points: openai_routes.py OpenAI endpoints · key_manager.py Key rotation · gemini_routes.py Gemini endpoints · routes.py Route registration
Components 26
Runtime & access
- Application lifecycle
app/core/application.py - Route registration
app/router/routes.py - Token authentication
app/core/security.py - Runtime configuration
app/config/config.py
API protocols
- Gemini endpoints
app/router/gemini_routes.py - OpenAI endpoints
app/router/openai_routes.py - HF compatibility
app/router/openai_compatiable_routes.py - Vertex Express API
app/router/vertex_express_routes.py
Proxy services
- Gemini chat
app/service/chat/gemini_chat_service.py - OpenAI chat
app/service/chat/openai_chat_service.py - Embeddings
app/service/embedding/gemini_embedding_service.py - Image generation
app/service/image/image_create_service.py - Gemini API client
app/service/client/api_client.py - Key rotation
app/service/key/key_manager.py - File handling
app/service/files/files_service.py - Image hosting
app/utils/uploader.py
Administration & monitoring
- Configuration & keys
app/router/config_routes.py - Key status
app/router/key_routes.py - Model maintenance
app/service/model/model_service.py - Scheduled tasks
app/scheduler/scheduled_tasks.py - Usage statistics
app/service/stats/stats_service.py - Error logs
app/service/error_log/error_log_service.py
Persistence & logs
- Data access
app/database/services.py - Application database
app/database/connection.py - Retry handling
app/handler/retry_handler.py
Other components
- API client
Connections 39
- API client → Gemini endpoints: sends Gemini requests
README.md - API client → OpenAI endpoints: sends OpenAI requests
README.md - API client → HF compatibility: uses HF API
README.md - Application lifecycle → Route registration: registers routes
app/core/application.py - Application lifecycle → Runtime configuration: syncs settings
app/core/application.py - Application lifecycle → Scheduled tasks: starts scheduler
app/core/application.py - Route registration → Gemini endpoints: registers
app/router/routes.py - Route registration → OpenAI endpoints: registers
app/router/routes.py - Route registration → HF compatibility: registers
app/router/routes.py - Route registration → Vertex Express API: registers
app/router/routes.py - Gemini endpoints → Token authentication: authenticates
app/router/gemini_routes.py - OpenAI endpoints → Token authentication: authenticates
app/router/openai_routes.py - Vertex Express API → Token authentication: authenticates
app/router/vertex_express_routes.py - Gemini endpoints → Key rotation: selects key
app/router/gemini_routes.py - OpenAI endpoints → Key rotation: selects key
app/router/openai_routes.py - Vertex Express API → Key rotation: selects key
app/router/vertex_express_routes.py - Gemini endpoints → Gemini chat: dispatches chat
app/router/gemini_routes.py - OpenAI endpoints → OpenAI chat: dispatches chat
app/router/openai_routes.py - OpenAI endpoints → Image generation: dispatches images
app/router/openai_routes.py - OpenAI endpoints → Embeddings: dispatches embeddings
app/router/openai_routes.py - Gemini endpoints → Retry handling: decorates requests
app/router/gemini_routes.py - OpenAI endpoints → Retry handling: decorates requests
app/router/openai_routes.py - Gemini chat → Gemini API client: calls API
app/service/chat/gemini_chat_service.py - OpenAI chat → Gemini API client: calls API
app/service/chat/openai_chat_service.py - Embeddings → Gemini API client: calls API
app/service/embedding/gemini_embedding_service.py - Gemini chat → Key rotation: uses selected key
app/service/chat/gemini_chat_service.py - OpenAI chat → Key rotation: uses selected key
app/service/chat/openai_chat_service.py - Embeddings → Key rotation: uses selected key
app/service/embedding/gemini_embedding_service.py - Image generation → Image hosting: uploads output
app/service/image/image_create_service.py - File handling → Gemini API client: uses API client
app/service/files/files_service.py - File handling → Key rotation: uses keys
app/service/files/files_service.py - Configuration & keys → Runtime configuration: updates configuration
- Key status → Key rotation: reports key status
- Scheduled tasks → Key rotation: checks keys
app/scheduler/scheduled_tasks.py - Scheduled tasks → Model maintenance: maintains models
- Usage statistics → Application database: queries statistics
app/service/stats/stats_service.py - Error logs → Data access: records and reads logs
app/service/error_log/error_log_service.py - Data access → Application database: executes queries
app/database/services.py - Runtime configuration → Application database: syncs settings
app/config/config.py