mirror of
https://github.com/xtekky/gpt4free.git
synced 2025-12-24 13:07:53 +08:00
Add comprehensive GitHub Copilot instructions for gpt4free repository
Co-authored-by: hlohaus <983577+hlohaus@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
137
.github/copilot-instructions.md
vendored
Normal file
137
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,137 @@
|
||||
# gpt4free - Python Library for AI Provider Access
|
||||
|
||||
gpt4free is a Python 3.10+ library that provides unified access to 108+ AI providers for text generation, image generation, audio processing, and video generation. It offers a CLI, API server with web GUI, and Python library interface.
|
||||
|
||||
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
|
||||
|
||||
## Working Effectively
|
||||
|
||||
### Bootstrap and Install Dependencies
|
||||
- Install Python 3.10+ (3.12 recommended): Project requires Python 3.10 or higher
|
||||
- Clone repository: `git clone https://github.com/xtekky/gpt4free.git && cd gpt4free`
|
||||
- Install minimal requirements: `pip install -r requirements-min.txt` -- takes 30-60 seconds. NEVER CANCEL.
|
||||
- Install full requirements: `pip install -r requirements.txt` -- takes 2-5 minutes. NEVER CANCEL. Set timeout to 600+ seconds.
|
||||
- Remove nodriver (CI requirement): `pip uninstall -y nodriver`
|
||||
- Install in editable mode: `pip install -e .` -- takes 30 seconds. NEVER CANCEL.
|
||||
|
||||
### Testing and Validation
|
||||
- Run unit tests: `python -m etc.unittest` -- takes 3-5 seconds. NEVER CANCEL.
|
||||
- Expected results: ~41 tests, 1-2 failures expected (network isolation), 5-8 skipped tests
|
||||
- Time unit tests: `time python -m etc.unittest` for precise timing
|
||||
- Individual test scripts available in `etc/testing/` but may have outdated model references
|
||||
|
||||
### Running the Application
|
||||
- **CLI Help**: `g4f --help` or `python -m g4f --help`
|
||||
- **Client CLI**: `g4f client --help` for interactive text generation
|
||||
- **API Server**: `python -m g4f --port 8080` -- starts FastAPI server with web GUI on http://localhost:8080
|
||||
- **API Server Only**: `python -m g4f --port 8080 --no-gui` (if supported)
|
||||
- **Python Library**:
|
||||
```python
|
||||
from g4f.client import Client
|
||||
client = Client()
|
||||
response = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "Hello"}])
|
||||
print(response.choices[0].message.content)
|
||||
```
|
||||
|
||||
## Validation Scenarios
|
||||
|
||||
Always test these scenarios after making changes:
|
||||
|
||||
### Basic Functionality Test
|
||||
1. **Import Test**: `python -c "from g4f.client import Client; client = Client(); print('Success')"`
|
||||
2. **CLI Test**: `g4f --help` should show available commands without errors
|
||||
3. **Unit Tests**: `python -m etc.unittest` should complete without hanging
|
||||
4. **API Server Test**: Start server `python -m g4f --port 8080`, then `curl -I http://localhost:8080` should return 200 OK
|
||||
|
||||
### Manual Validation Requirements
|
||||
- ALWAYS test complete user workflows, not just imports
|
||||
- Test both CLI and Python library interfaces when making provider changes
|
||||
- Test API server startup and basic HTTP response
|
||||
- Verify no new import errors or dependency conflicts
|
||||
|
||||
## Critical Timing and Build Information
|
||||
|
||||
- **NEVER CANCEL** long-running operations. Builds may take several minutes.
|
||||
- **Requirements Installation**:
|
||||
- Minimal (`requirements-min.txt`): 30-60 seconds. Set timeout to 120+ seconds.
|
||||
- Full (`requirements.txt`): 2-5 minutes. Set timeout to 600+ seconds.
|
||||
- **Unit Tests**: 3-5 seconds. Set timeout to 30+ seconds.
|
||||
- **Package Installation**: 30-60 seconds. Set timeout to 120+ seconds.
|
||||
- **Warning**: `pydub` will show ffmpeg warning - this is expected and harmless
|
||||
|
||||
## Key Development Info
|
||||
|
||||
### Project Structure
|
||||
- `g4f/` - Main library code
|
||||
- `Provider/` - AI provider implementations (108+ providers)
|
||||
- `client/` - Client interfaces
|
||||
- `api/` - FastAPI server implementation
|
||||
- `gui/` - Web GUI components
|
||||
- `cli/` - Command line interfaces
|
||||
- `etc/` - Testing and development tools
|
||||
- `unittest/` - Unit test suite
|
||||
- `testing/` - Integration tests (may have outdated references)
|
||||
- `examples/` - Usage examples
|
||||
- `docs/` - Documentation
|
||||
- `docker/` - Docker configuration files
|
||||
|
||||
### Provider System
|
||||
- 108+ AI providers supported including OpenAI, Anthropic, Google, Meta, etc.
|
||||
- Each provider in `g4f/Provider/` directory
|
||||
- Working providers listed in CLI help: `g4f --help`
|
||||
- Test provider availability: Network-dependent, many may fail in isolated environments
|
||||
|
||||
### Common Commands Reference
|
||||
```bash
|
||||
# Development workflow
|
||||
git clone https://github.com/xtekky/gpt4free.git
|
||||
cd gpt4free
|
||||
pip install -r requirements-min.txt # Basic deps
|
||||
pip install -r requirements.txt # Full deps
|
||||
pip uninstall -y nodriver # CI requirement
|
||||
pip install -e . # Editable install
|
||||
python -m etc.unittest # Run tests
|
||||
|
||||
# Usage examples
|
||||
g4f client "Hello world" # CLI chat
|
||||
python -m g4f --port 8080 # Start server
|
||||
python etc/examples/messages.py # Example script
|
||||
```
|
||||
|
||||
### Installation Alternatives
|
||||
- **PyPI**: `pip install -U g4f[all]` (external, not for development)
|
||||
- **Docker**: Use provided docker-compose.yml for containerized deployment
|
||||
- **Partial installs**: See `/docs/requirements.md` for component-specific installs
|
||||
|
||||
### Known Issues and Workarounds
|
||||
- **ffmpeg warning**: Expected from pydub library, does not affect functionality
|
||||
- **Network timeouts**: Expected for many providers in isolated environments
|
||||
- **Model availability**: Provider-dependent, some models may not be accessible
|
||||
- **nodriver removal**: Required for CI compatibility, remove after full install
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Making Changes
|
||||
- Always run unit tests before and after changes: `python -m etc.unittest`
|
||||
- Test both minimal and full installations when adding dependencies
|
||||
- Validate CLI commands work: `g4f --help`, `g4f client --help`
|
||||
- Test Python import: `python -c "import g4f; print('OK')"`
|
||||
- For provider changes, test basic client creation and simple completions
|
||||
|
||||
### Before Committing
|
||||
- Run full test suite: `python -m etc.unittest`
|
||||
- Verify no new dependency conflicts
|
||||
- Test installation from scratch in clean environment when possible
|
||||
- Ensure backwards compatibility with Python 3.10+
|
||||
|
||||
### Timeout Guidelines
|
||||
- Use 600+ second timeouts for `pip install -r requirements.txt`
|
||||
- Use 120+ second timeouts for basic pip installations
|
||||
- Use 30+ second timeouts for unit tests
|
||||
- NEVER use default timeouts for package installations - they will fail
|
||||
|
||||
### Entry Points
|
||||
- **CLI Binary**: `g4f` (installed via setuptools entry_points)
|
||||
- **Module**: `python -m g4f`
|
||||
- **Client Module**: `python -m g4f.client`
|
||||
- **Python Import**: `import g4f` or `from g4f.client import Client`
|
||||
Reference in New Issue
Block a user