Metadata-Version: 2.4
Name: api-check-models
Version: 0.1.0
Summary: Thư viện kiểm tra quota và khả dụng của các models Gemini API
Author-email: Duy Hoanh <duyhoanh@example.com>
License: MIT
Project-URL: Homepage, https://github.com/duyhoanhsgu-commits/api-models
Project-URL: Repository, https://github.com/duyhoanhsgu-commits/api-models
Project-URL: Documentation, https://github.com/duyhoanhsgu-commits/api-models#readme
Keywords: gemini,api,quota,llm,models,google-ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-generativeai>=0.3.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# API Check Models - Thư viện kiểm tra quota Gemini API

Thư viện Python đơn giản và mạnh mẽ để kiểm tra quota và khả dụng của các models Gemini API.

## ✨ Tính năng

- 🔍 **Kiểm tra quota tự động** - Kiểm tra nhanh models nào còn quota khả dụng
- ⚡ **Xử lý song song** - Check nhiều models cùng lúc để tiết kiệm thời gian
- 🎯 **Dễ sử dụng** - API đơn giản, chỉ cần API key là có thể bắt đầu
- 📊 **Thống kê chi tiết** - Xem tổng quan về tình trạng các models
- 🚀 **Tối ưu cho scale lớn** - Hỗ trợ cache, retry, timeout
- 🔄 **Tự động chọn model tốt nhất** - Ưu tiên models mới và nhanh hơn

## 📦 Cài đặt

### Cách 1: Cài đặt từ PyPI (Sau khi publish)

```bash
pip install api-check-models
```

### Cách 2: Cài đặt trực tiếp từ Git

```bash
pip install git+https://github.com/duyhoanhsgu-commits/api-models.git
```

### Cách 3: Cài đặt từ source code (Local / Development)

```bash
git clone https://github.com/duyhoanhsgu-commits/api-models.git
cd api-models
pip install -e .
```

### Cách 3: Thêm vào `requirements.txt` của dự án khác

```text
git+https://github.com/yourusername/api-models.git
```

## ⚙️ Cấu hình API Key

Thư viện **tự động nạp API key** từ file `.env` hoặc biến môi trường `GEMINI_API_KEY`:

1. **Cách 1 - Dùng file `.env` (Tiện nhất):**
   Tạo file `.env` trong thư mục dự án:
   ```env
   GEMINI_API_KEY=your_gemini_api_key_here
   ```

2. **Cách 2 - Biến môi trường:**
   ```bash
   export GEMINI_API_KEY='your_gemini_api_key_here'
   ```

3. **Cách 3 - Truyền trực tiếp trong code:**
   ```python
   checker = GeminiQuotaChecker(api_key="your_gemini_api_key_here")
   ```

### 3. Interactive Test (Dễ dùng nhất)
```bash
# Giao diện tương tác với menu
python interactive_test.py
```

📖 Xem thêm: [TEST_GUIDE.md](TEST_GUIDE.md) để biết chi tiết

### Sử dụng Makefile

```bash
make quick-test      # Test nhanh
make full-test       # Test đầy đủ
make interactive     # Test tương tác
make test-json       # Export JSON
```

## 🚀 Sử dụng nhanh

### 1. Kiểm tra models còn quota

```python
from api_models import GeminiQuotaChecker

# Khởi tạo checker với API key
checker = GeminiQuotaChecker(api_key="YOUR_API_KEY")

# Lấy danh sách models còn quota
available_models = checker.get_model_names()
print(f"Models còn quota: {available_models}")
```

### 2. Lấy model tốt nhất

```python
# Tự động chọn model tốt nhất còn quota
best_model = checker.get_best_model()
if best_model:
    print(f"Model tốt nhất: {best_model.name}")
else:
    print("Không có model nào còn quota")
```

### 3. Kiểm tra một model cụ thể

```python
# Kiểm tra một model
model_info = checker.check_single_model("gemini-3.5-flash")
print(f"Available: {model_info.is_available}")
print(f"Has quota: {model_info.has_quota}")
if model_info.error_message:
    print(f"Error: {model_info.error_message}")
```

### 4. Xem thống kê tổng quan

```python
# Lấy thống kê chi tiết
summary = checker.get_summary(refresh=True)
print(f"Tổng số models: {summary['total_models']}")
print(f"Models khả dụng: {summary['available_models']}")
print(f"Models còn quota: {summary['models_with_quota']}")
```

## 📖 API Documentation

### GeminiQuotaChecker

Class chính để kiểm tra quota models.

#### `__init__(api_key, timeout=10.0, max_workers=5, retry_count=1)`

Khởi tạo checker.

**Parameters:**
- `api_key` (str): API key của Google AI Studio
- `timeout` (float): Thời gian timeout cho mỗi request (giây)
- `max_workers` (int): Số threads tối đa để check song song
- `retry_count` (int): Số lần thử lại nếu gặp lỗi tạm thời

#### `check_single_model(model_name, update_cache=True)`

Kiểm tra một model cụ thể.

**Returns:** `ModelInfo` - Thông tin model với trạng thái cập nhật

#### `check_all_models(models=None, parallel=True, progress_callback=None)`

Kiểm tra tất cả models hoặc danh sách models được chỉ định.

**Parameters:**
- `models` (List[str], optional): Danh sách tên models. Nếu None, check tất cả
- `parallel` (bool): Chạy song song hay tuần tự
- `progress_callback` (Callable): Callback nhận (model_name, current, total)

**Returns:** `List[ModelInfo]` - Danh sách models đã kiểm tra

#### `get_available_models(refresh=False, with_quota_only=True)`

Lấy danh sách models khả dụng.

**Parameters:**
- `refresh` (bool): Kiểm tra lại hay dùng cache
- `with_quota_only` (bool): Chỉ lấy models còn quota

**Returns:** `List[ModelInfo]` - Danh sách models khả dụng

#### `get_model_names(refresh=False, with_quota_only=True)`

Lấy danh sách tên models khả dụng.

**Returns:** `List[str]` - Danh sách tên models

#### `get_best_model(prefer_flash=True, refresh=False)`

Lấy model tốt nhất còn quota.

**Parameters:**
- `prefer_flash` (bool): Ưu tiên các model flash (nhanh hơn)
- `refresh` (bool): Kiểm tra lại hay dùng cache

**Returns:** `ModelInfo` hoặc `None`

#### `get_summary(refresh=False)`

Lấy tổng quan về tình trạng các models.

**Returns:** `Dict` - Thống kê chi tiết

## 📝 Ví dụ nâng cao

### Sử dụng callback để theo dõi tiến trình

```python
def progress_callback(model_name, current, total):
    print(f"[{current}/{total}] Checking {model_name}...")

checker = GeminiQuotaChecker(api_key="YOUR_API_KEY")
models = checker.check_all_models(progress_callback=progress_callback)
```

### Check models theo thế hệ

```python
from api_models import GEMINI_MODELS, ModelGeneration

# Lấy models thế hệ 3.5
gemini_35_models = [
    m.name for m in GEMINI_MODELS 
    if m.generation == ModelGeneration.GEMINI_3_5
]

# Check chỉ các models này
checker = GeminiQuotaChecker(api_key="YOUR_API_KEY")
results = checker.check_all_models(models=gemini_35_models)
```

### Tích hợp với retry logic

```python
# Cấu hình với retry và timeout cao hơn
checker = GeminiQuotaChecker(
    api_key="YOUR_API_KEY",
    timeout=30.0,      # Timeout 30 giây
    max_workers=10,    # Check 10 models song song
    retry_count=3      # Thử lại 3 lần nếu lỗi
)

available = checker.get_model_names(refresh=True)
```

### Sử dụng cache để tối ưu

```python
checker = GeminiQuotaChecker(api_key="YOUR_API_KEY")

# Lần đầu - check tất cả models
models = checker.get_available_models(refresh=True)

# Các lần sau - dùng cache (nhanh hơn)
models = checker.get_available_models(refresh=False)

# Xóa cache khi cần
checker.clear_cache()
```

## 🎯 Use Cases

### 1. Auto-fallback khi model hết quota

```python
from api_models import GeminiQuotaChecker
import google.generativeai as genai

def get_working_model(api_key):
    checker = GeminiQuotaChecker(api_key=api_key)
    best_model = checker.get_best_model()
    if best_model:
        return best_model.name
    raise Exception("Không có model nào còn quota")

# Sử dụng
api_key = "YOUR_API_KEY"
model_name = get_working_model(api_key)
genai.configure(api_key=api_key)
model = genai.GenerativeModel(model_name)
```

### 2. Monitoring quota

```python
import time
from api_models import GeminiQuotaChecker

checker = GeminiQuotaChecker(api_key="YOUR_API_KEY")

while True:
    summary = checker.get_summary(refresh=True)
    print(f"[{time.strftime('%H:%M:%S')}] Còn {summary['models_with_quota']} models")
    
    if summary['models_with_quota'] == 0:
        print("⚠️  Tất cả models đã hết quota!")
        break
    
    time.sleep(60)  # Check mỗi phút
```

### 3. Load balancing giữa nhiều API keys

```python
from api_models import GeminiQuotaChecker

api_keys = ["KEY_1", "KEY_2", "KEY_3"]

for api_key in api_keys:
    checker = GeminiQuotaChecker(api_key=api_key)
    available = checker.get_model_names()
    
    if available:
        print(f"API Key {api_key[:8]}... có {len(available)} models")
        # Sử dụng API key này
        break
```

## 🔧 Danh sách Models được hỗ trợ

Thư viện hỗ trợ kiểm tra các models Gemini sau:

### Thế hệ 3.6 & 3.5 (Khuyên dùng)
- `gemini-3.6-flash` (Mới nhất, nhanh và thông minh nhất)
- `gemini-3.5-flash` (Rất ổn định)
- `gemini-3.5-flash-lite` (Siêu nhẹ và tiết kiệm)

### Thế hệ 3.1 & 3.0
- `gemini-3.1-flash-lite`
- `gemini-3.1-pro-preview`
- `gemini-3-flash-preview`

### Phiên bản Latest Aliases
- `gemini-flash-latest` (Tự động trỏ về Flash mới nhất)
- `gemini-flash-lite-latest` (Tự động trỏ về Flash Lite mới nhất)

### Thế hệ 2.0 & 2.5
- `gemini-2.0-flash`
- `gemini-2.0-flash-lite`
- `gemini-2.5-pro`

## ⚙️ Cấu hình nâng cao

### Tùy chỉnh timeout và retry

```python
checker = GeminiQuotaChecker(
    api_key="YOUR_API_KEY",
    timeout=20.0,        # Timeout 20 giây
    max_workers=8,       # 8 threads song song
    retry_count=2        # Retry 2 lần
)
```

### Sequential checking (không dùng parallel)

```python
# Hữu ích khi muốn tránh rate limit
checker = GeminiQuotaChecker(api_key="YOUR_API_KEY")
models = checker.check_all_models(parallel=False)
```

## 🐛 Xử lý lỗi

```python
from api_models import GeminiQuotaChecker
from api_models.exceptions import (
    InvalidAPIKeyError,
    APIConnectionError
)

try:
    checker = GeminiQuotaChecker(api_key="YOUR_API_KEY")
    models = checker.get_available_models()
except InvalidAPIKeyError:
    print("API key không hợp lệ")
except APIConnectionError:
    print("Không thể kết nối đến API")
except Exception as e:
    print(f"Lỗi: {e}")
```

## 📋 Requirements

- Python >= 3.8
- google-generativeai >= 0.3.0
- requests >= 2.31.0

## 🤝 Đóng góp

Contributions, issues và feature requests đều được chào đón!

## 📄 License

MIT License

## 👤 Tác giả

Your Name - your.email@example.com

## 🙏 Acknowledgments

- Google Generative AI team cho Gemini API
- Python community

---

**Note:** Thư viện này kiểm tra quota bằng cách gửi request test đến API. Mỗi lần check sẽ tiêu tốn một ít quota của model đó.
# api-models