local-nekos-best 1.0.0
Lightning fast access to nekos.best anime gifs and images. Zero API calls, no rate limits, instant responses.
License: MIT
Requires Python: >=3.10
Keywords: anime, gifs, discord, images, neko, nekos.best

# Local Nekos Best

A lightweight, zero-dependency library that provides local access to the complete nekos.best API dataset of anime reaction GIFs and images.

## Installation

```bash
pip install local-nekos-best
```

## Quick Start

```python
from local_nekos_best import call_neko

# Get a random anime reaction
reaction = call_neko()
print(reaction["url"])
```

---

## Main Function: call_neko()

Get anime reaction GIFs and images from the local dataset.

### Basic Usage

```python
# Get one random item from any category
item = call_neko()

# Get 5 random items
items = call_neko(amount=5)
```

### With Specific Actions

```python
# Get a single hug GIF
hug = call_neko(actions="hug")

# Get 3 items from multiple actions
reactions = call_neko(
    amount=3,
    actions=["hug", "pat", "kiss"]
)
```

### Search by Name

```python
# Search for items by anime name (for GIFs) or artist name (for images)
naruto_reactions = call_neko(
    amount=5,
    search="naruto"
)

# Multiple search terms (matches any)
items = call_neko(
    search=["naruto", "one piece"]
)
```

### Filter by Type

```python
# Get only images (waifu, husbando, neko, kitsune)
images = call_neko(type="images")  # or type=1

# Get only GIFs (all other actions)
gifs = call_neko(type="gifs")  # or type=2

# Get both (default)
both = call_neko(type="both")  # or type=3
```

### Selection Modes

```python
# Random: Pick randomly from all matching items (default)
random_items = call_neko(
    amount=10,
    mode="random"  # or mode=1
)

# Distributed: Split amount evenly across actions
distributed = call_neko(
    amount=10,
    actions=["hug", "pat"],
    mode="distributed"  # or mode=2
)
# Returns 5 hugs + 5 pats

# Each: Get specified amount from EACH action
each = call_neko(
    amount=5,
    actions=["hug", "pat"],
    mode="each"  # or mode=3
)
# Returns 5 hugs + 5 pats = 10 total
```

### Allow Duplicates

```python
# By default, duplicates are prevented
unique = call_neko(amount=10)

# Allow the same item multiple times
with_dupes = call_neko(
    amount=10,
    dupe=True
)
```

### All Options

```python
call_neko(
    amount=1,           # Number of items (default: 1)
    actions=["hug"],    # String or list of actions
    search="naruto",    # String or list of search terms
    type="both",        # "images", "gifs", "both" (or 1, 2, 3)
    mode="random",      # "random", "distributed", "each" (or 1, 2, 3)
    dupe=False          # Allow duplicates (default: False)
)
```

### Response Format

```python
# Single item (when amount=1)
item = call_neko(actions="hug")
print(item)
# Output:
{
    "url": "https://nekos.best/api/v2/hug/abc123.gif",
    "action": "hug",
    "type": 2,              # 1 = image, 2 = gif
    "anime_name": "Naruto"  # For GIFs (if metadata loaded)
}

# Image example
image = call_neko(actions="waifu")
print(image)
# Output:
{
    "url": "https://nekos.best/api/v2/waifu/def456.png",
    "action": "waifu",
    "type": 1,
    "artist_name": "Artist Name",      # For images (if metadata loaded)
    "artist_href": "https://twitter.com/artist",
    "source_url": "https://pixiv.net/..."
}

# Multiple items (when amount > 1)
items = call_neko(amount=2, actions="hug")
print(items)
# Output:
[
    {"url": "https://nekos.best/api/v2/hug/abc123.gif", "action": "hug", "type": 2, "anime_name": "Naruto"},
    {"url": "https://nekos.best/api/v2/hug/xyz789.gif", "action": "hug", "type": 2, "anime_name": "One Piece"}
]
```

---

## Recommended: call_neko_intent()

**Call this FIRST** to optimize memory usage by loading only what you need.

### Why Use Intent?

- **Saves Memory**: Load only the data you'll actually use
- **One-Time Setup**: Configure once, affects all future calls
- **Cannot be Changed**: Once set, it's locked for the session

### Loading Metadata

```python
# Load all metadata (default if not specified)
call_neko_intent(metadata=1)
# or
call_neko_intent(metadata=True)

# Load no metadata (smallest memory footprint)
call_neko_intent(metadata=0)
# or
call_neko_intent(metadata=False)

# Load specific metadata fields
call_neko_intent(
    metadata=["anime_name"]  # Only load anime names
)

call_neko_intent(
    metadata=["artist_name", "artist_href", "source_url"]
)
```

**Available Metadata Fields:**
- For GIFs: `"anime_name"`
- For Images: `"artist_name"`, `"artist_href"`, `"source_url"`

### Loading by Type

```python
# Load only images (waifu, husbando, neko, kitsune)
call_neko_intent(type="images")  # or type=1

# Load only GIFs (all other actions)
call_neko_intent(type="gifs")    # or type=2

# Load both (default)
call_neko_intent(type="both")    # or type=3
```

### Combined Example

```python
# Only load GIFs with anime names
call_neko_intent(
    metadata=["anime_name"],
    type="gifs"
)

# Now all call_neko() calls only work with GIFs
gif = call_neko(actions="hug")   # ✓ Works
img = call_neko(actions="waifu") # ✗ Error - images not loaded
```

### Important Notes

- **Call before any other function**
- **Can only be called once** per session
- **Automatically filters metadata** based on type
- **Affects all functions** (call_neko, call_neko_load, call_neko_actions, call_neko_count)

---

## Extra Functions

### call_neko_actions()

Get all available action categories.

```python
actions = call_neko_actions()
print(actions)
# Output: ['angry', 'baka', 'bite', 'blush', 'bored', 'cry', 'cuddle', 'dance', ...]
```

**Respects Intent:**
```python
call_neko_intent(type="images")
actions = call_neko_actions()
print(actions)
# Output: ['husbando', 'kitsune', 'neko', 'waifu']
```

---

### call_neko_count()

Get statistics about available content.

```python
stats = call_neko_count()
print(stats)
# Output:
{
    "total": 3500,
    "categories": {
        "neko": 1500,
        "pat": 500,
        "hug": 40,
        "waifu": 200,
        # ... sorted by count (highest first)
    }
}
```

---

### call_neko_load()

Get the entire dataset with constructed URLs. Useful for caching or custom filtering.

```python
data = call_neko_load()
print(list(data.keys()))
# Output: ['angry', 'baka', 'bite', ...]

print(data["hug"][0])
# Output:
{
    "url": "https://nekos.best/api/v2/hug/abc123.gif",
    "action": "hug",
    "type": 2,
    "anime_name": "Naruto"
}
```

**Respects Intent** — only returns loaded categories.

---

## Type Hints

Full type hints included. The package is PEP 561 compliant with a `py.typed` marker.

```python
from local_nekos_best import call_neko

result: dict[str, Any] | list[dict[str, Any]] = call_neko(actions="hug")
```