FR: Add Freebuff as a provider

[rakheOmar]

Feature Type

New provider

Description

Add Freebuff (https://freebuff.com/) as a provider.
Has support for GLM 5.1 and Gemini 3.1 Flash Lite according to their FAQ on their website

Use Case

Would help to have all the providers routed through the proxy

Additional Context

Freebuff (& Codebuff main repo): https://github.com/CodebuffAI/codebuff/tree/main
Another repo that has already implemented this: https://github.com/quorinex/freebuff2api

Pre-submission Checklist

• I have searched existing issues to ensure this is not a duplicate

[mirrobot-agent]

@rakheOmar Thank you for submitting this issue. I am now beginning my analysis and will report back shortly.

[mirrobot-agent]

Initial Analysis Report

Summary: Feature request to add Freebuff (freebuff.com) as a provider in the proxy. No duplicates found; this would require a custom provider implementation since Freebuff is not a standard LiteLLM provider.

Issue Validation: Confirmed — this is a valid feature request with useful reference materials.

Reproducibility Assessment: Not Applicable (feature request).

Root Cause Analysis: Freebuff is not currently known to the proxy in any capacity:

• Not listed in src/rotator_library/litellm_providers.py (103 scraped LiteLLM providers)
• Not in src/rotator_library/provider_config.py (UI/credential configuration)
• No provider file exists in src/rotator_library/providers/
• No references to "freebuff" or "codebuff" exist anywhere in the codebase or git history

Suggested Labels: enhancement, new-provider

Proposed Next Steps:

This feature requires implementing a new custom provider. Based on the architecture, the implementation path depends on whether Freebuff exposes an OpenAI-compatible API or requires custom auth/handling:

1. If Freebuff has an OpenAI-compatible API: Users could use it immediately via the dynamic provider system by setting:

   • FREEBUFF_API_BASE=https://freebuff.com/api/v1 (or whatever the base URL is)
   • FREEBUFF_API_KEY=<key>
   • FREEBUFF_MODELS='["glm-5.1", "gemini-3.1-flash-lite"]'

   This requires zero code changes and would work out of the box.

2. If Freebuff requires custom auth or API handling (more likely given the freebuff2api reference repo): A full provider implementation is needed, following the pattern in CONTRIBUTING.md:

   • Create src/rotator_library/providers/freebuff_provider.py extending ProviderInterface
   • Potentially create src/rotator_library/providers/freebuff_auth_base.py if OAuth/custom auth is needed
   • Register in src/rotator_library/provider_factory.py's PROVIDER_MAP
   • Add UI config entry in src/rotator_library/provider_config.py
   • Add model definitions via FREEBUFF_MODELS env var support
   • Add URL mapping in src/proxy_app/provider_urls.py if needed
   • Update documentation in README.md and DOCUMENTATION.md

   Reference implementations to follow: nanogpt_provider.py (simpler, API key-based) or iflow_auth_base.py (complex, OAuth-based).

Missing Information:

• Authentication mechanism: Does Freebuff use API keys, OAuth, cookie-based auth, or something else? The freebuff2api reference repo suggests non-standard auth.
• API base URL and endpoint structure: What is the actual API endpoint for chat completions?
• Available models and their IDs: The issue mentions GLM 5.1 and Gemini 3.1 Flash Lite but exact model identifiers are needed.
• Rate limits/quota system: Does Freebuff have rate limits or quota tracking that the proxy should handle?

This analysis was generated by an AI assistant.

[Mirrowel]

@Mirrobot-Agent analyze the provided freebuff2api repo and implement similar provider here in a new PR.

[mirrobot-agent]

@Mirrowel, I'm on it. I'll analyze the freebuff2api reference repo, study the existing provider architecture, implement the Freebuff provider, and open a pull request. Starting now.

[mirrobot-agent]

@Mirrowel, I have successfully implemented the Freebuff provider and opened a pull request.

Summary

Analyzed the freebuff2api reference repo (a Go-based OpenAI-compatible proxy for Freebuff) and implemented equivalent functionality as a native provider in this proxy, following the existing Tier 3 (custom logic) provider pattern.

Key Changes Made

New files:

• src/rotator_library/providers/freebuff_auth_base.py — Session/run lifecycle management, model-to-agent mapping (dynamically fetched from Codebuff free-agents source with hardcoded fallback), multi-token pool state tracking with round-robin selection
• src/rotator_library/providers/freebuff_provider.py — Custom provider with acompletion() bypassing LiteLLM, codebuff_metadata injection, streaming/non-streaming response handling, automatic retry on session/run invalidation

Modified files:

• src/rotator_library/provider_factory.py — Registered FreebuffAuthBase
• src/rotator_library/provider_config.py — Added UI configuration
• .env.example — Added Freebuff environment variable documentation

Implementation Details

Freebuff uses a non-standard API requiring:

1. Free session management — Sessions must be created and may queue before becoming active
2. Agent run lifecycle — Each request requires an active "run" for the target model's agent, with 6-hour rotation
3. Metadata injection — Requests must include codebuff_metadata with run_id, cost_mode, client_id, and freebuff_instance_id
4. Model-to-agent mapping — Models are mapped to "agents" (e.g., z-ai/glm-5.1 → base2-free agent)

Supported models (auto-discovered from Codebuff source):

• z-ai/glm-5.1, minimax/minimax-m2.7
• google/gemini-2.5-flash-lite, google/gemini-3.1-flash-lite-preview

Authentication: Freebuff auth tokens from ~/.config/manicode/credentials.json or https://freebuff.llm.pm

Pull Request Created

PR #158: #158

The PR is ready for review. Manual testing with an actual Freebuff auth token is recommended to verify end-to-end functionality.

This update was generated by an AI assistant.