Metadata-Version: 2.4
Name: aitag
Version: 3.0.0
Summary: Python client for aitag.win — search, rank, and scrape AI-generated art prompts and parameters
Author: aitag contributors
License-Expression: MIT
Project-URL: Homepage, https://aitag.win
Keywords: aitag,novelai,stable-diffusion,ai-art,prompt,scraper
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Dynamic: license-file

# aitag — Python client for aitag.win

Search, rank, and scrape AI-generated art prompts & parameters from [aitag.win](https://aitag.win). Only needs `requests`.

## Install

```bash
pip install aitag
```

## Quick Start

```python
from aitag import AITagClient

client = AITagClient()

# Lấy chi tiết 1 post (tất cả ảnh + NAI JSON)
work = client.get_work(141959453)
for img in work.nai_images:
    print(img.positive_prompt)
    print(img.params.seed, img.params.steps)

# Search + lấy prompts
for img in client.get_all_images("高木さん", limit=50):
    print(img.positive_prompt[:80])

# Rank tháng này
for stub in client.iter_rank_realtime(limit=100, nai_only=True):
    print(stub.id, stub.title, stub.total_bookmarks)
```

## API Reference

### `AITagClient(delay=0.3, timeout=15)`

| Method | Trả về | Mô tả |
|--------|--------|-------|
| `get_config()` | `Config` | Config site (page_size, available_months...) |
| `get_work(id)` | `Work` | Chi tiết post + tất cả ảnh |
| `search(q, ...)` | `SearchResult` | Tìm kiếm 1 trang |
| `iter_search(q, ...)` | `Iterator[WorkStub]` | Tự động qua tất cả trang |
| `search_with_prompts(q, ...)` | `Iterator[stub, Work]` | Search + fetch work detail |
| `get_all_images(q, ...)` | `Iterator[Image]` | Search → Image trực tiếp |
| `get_rank_realtime(page)` | `RankResult` | Rank tháng hiện tại |
| `get_rank_month(period, page)` | `RankResult` | Rank tháng cụ thể |
| `iter_rank_realtime(limit)` | `Iterator[WorkStub]` | Iterator rank realtime |
| `iter_rank_month(period, limit)` | `Iterator[WorkStub]` | Iterator rank tháng |

### Search params

| Param | Mô tả | Ví dụ |
|-------|-------|-------|
| `q` | Tìm tag/title | `"高木さん"`, `"NAI"` |
| `prompt` | Tìm trong nội dung prompt | `"masterpiece"` |
| `sort` | Sắp xếp | `"new"` \| `"hot"` |
| `time_range` | Khoảng thời gian | `"all"` \| `"month"` \| `"week"` |
| `nai_only` | Chỉ lấy NAI | `True` |
| `limit` | Số lượng tối đa | `100` |

### Data models

**`Work`**
- `.id`, `.title`, `.tags`, `.create_date`, `.ai_type`
- `.images` — list `Image`
- `.nai_images` — chỉ ảnh NAI
- `.url` — link aitag.win
- `.to_dict()` — export JSON

**`Image`**
- `.positive_prompt`, `.negative_prompt`
- `.params` — `NAIParams` (steps, seed, width, height, sampler...)
- `.v4_prompt` — V4 char captions
- `.image_url` — CDN webp URL
- `.is_nai`, `.is_img2img`
- `.to_dict()` — export JSON

**`NAIParams`**
- `steps`, `width`, `height`, `scale`, `cfg_rescale`
- `seed`, `sampler`, `noise_schedule`
- `sm`, `sm_dyn`, `strength` (img2img)

## CLI

```bash
# Config
python -m aitag config

# Chi tiết post
python -m aitag work 141959453
python -m aitag work 141959453 --output post.json

# Search
python -m aitag search "高木さん" --limit 20
python -m aitag search "NAI" --sort hot --output results.json
python -m aitag search --prompt "masterpiece" --limit 50

# Rank
python -m aitag rank --realtime --limit 100
python -m aitag rank --period 2026-02 --output rank_feb.json
```

## Ví dụ thực tế

### Lưu tất cả prompts ra JSON
```python
import json
from aitag import AITagClient

client = AITagClient(delay=0.5)
results = []

for img in client.get_all_images("高木さん", limit=100):
    results.append(img.to_dict())

with open("prompts.json", "w", encoding="utf-8") as f:
    json.dump(results, f, ensure_ascii=False, indent=2)
print(f"Saved {len(results)} images")
```

### Lọc theo seed / sampler
```python
from aitag import AITagClient

client = AITagClient()
for img in client.get_all_images("NAI", limit=200):
    if img.params and img.params.sampler == "k_euler_ancestral":
        print(f"seed={img.params.seed} | {img.positive_prompt[:80]}")
```

### Lấy rank tháng trước + fetch prompts
```python
from aitag import AITagClient

client = AITagClient()
cfg = client.get_config()
last_month = cfg.available_months[1]  # tháng trước

for stub in client.iter_rank_month(last_month, limit=50, nai_only=True):
    work = client.get_work(stub.id)
    for img in work.nai_images:
        print(f"#{stub.id} rank | {img.positive_prompt[:60]}")
```
