Metadata-Version: 2.4
Name: cat-enrichment
Version: 0.1.0
Summary: Cat behavioral enrichment data, research statistics, and home assessment tools. 고양이 행동풍부화 데이터 및 평가 도구.
Project-URL: Homepage, https://playcat.xyz
Project-URL: Repository, https://github.com/playcatkorea/cat-behavior-enrichment
Project-URL: Dataset, https://huggingface.co/datasets/playcat/playcat-cat-behavior-new-data-set
Project-URL: Documentation, https://playcat.xyz/cat-enrichment
Author-email: PlayCat Research <playcatkr@gmail.com>
License: MIT
License-File: LICENSE
Keywords: behavior,behavioral-science,cat,enrichment,feline,pet-care,welfare,고양이,행동풍부화
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: Korean
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
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# cat-enrichment

**Research-backed cat behavioral enrichment data, assessment tools, and recommendations.**

고양이 행동풍부화 데이터, 평가 도구 및 추천 시스템 — PlayCat Research (플레이캣)

[![PyPI version](https://badge.fury.io/py/cat-enrichment.svg)](https://pypi.org/project/cat-enrichment/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

## What is cat-enrichment?

`cat-enrichment` is a Python library that provides:

- **30+ research-backed enrichment methods** for indoor cats, with bilingual descriptions (English/Korean)
- **Home assessment tool** that scores your home's enrichment level and provides actionable recommendations
- **Research statistics database** with citations from peer-reviewed veterinary journals
- **Personalized recommendation engine** based on your home assessment, budget, and experience level
- **Structured enrichment plans** for beginners, intermediate, and advanced cat guardians

Environmental enrichment reduces stress in indoor cats by up to 37% and decreases problem behaviors by 52%, according to published research in the Journal of Feline Medicine and Surgery.

## Installation

```bash
pip install cat-enrichment
```

## Quick Start

### Assess Your Home

```python
from cat_enrichment import assess_home

result = assess_home(
    vertical_spaces=2,   # Cat trees, shelves
    scratchers=3,         # Scratching posts
    hiding_spots=2,       # Boxes, covered beds
    play_minutes=20,      # Daily interactive play
    window_access=True,   # Window perch available
    cats=1,               # Number of cats
    puzzle_feeders=1,     # Puzzle feeders
    toys=8,               # Available toys
)

print(result)
# Cat Home Enrichment Assessment
# Overall Score: 82/100 (Grade: B+)
# Level: Very Good
```

### Get Research Statistics

```python
from cat_enrichment import research_stats, get_stat

# Get a specific statistic
stat = get_stat("cortisol_reduction")
print(f"{stat['value']} - {stat['metric']}")
# 37% - Reduction in cortisol levels with adequate enrichment

# Browse all statistics
for key, stat in research_stats.items():
    print(f"{stat['value']:>15s}  {stat['metric']}")
```

### Get Personalized Recommendations

```python
from cat_enrichment import get_recommendations

recs = get_recommendations(
    vertical_spaces=0,
    scratchers=1,
    play_minutes=5,
    budget="low",
    max_recommendations=3,
)

for rec in recs:
    print(f"[{rec['priority'].upper()}] {rec['name']}")
    print(f"  → {rec['reason']}")
    print()
```

### Browse Enrichment Methods

```python
from cat_enrichment import enrichment_methods, CATEGORIES
from cat_enrichment.data import get_top_methods, get_methods_by_category

# See all categories
for key, name in CATEGORIES.items():
    print(name)

# Get top 5 most effective methods
for key, method in get_top_methods(5):
    print(f"{method['effectiveness']:.0%} - {method['name']} ({method['name_ko']})")

# Get methods in a specific category
play_methods = get_methods_by_category("play")
for key, method in play_methods.items():
    print(f"  {method['name']}: {method['description']}")
```

### Generate an Enrichment Plan

```python
from cat_enrichment.recommendations import enrichment_plan

plan = enrichment_plan(cats=1, experience="beginner", lang="en")
for week, details in plan["weeks"].items():
    print(f"\n{week}: {details['focus']}")
    for task in details["tasks"]:
        print(f"  - {task}")
```

### Korean Language Support (한국어 지원)

```python
from cat_enrichment.recommendations import quick_wins, enrichment_plan
from cat_enrichment.statistics import summary

# 한국어로 빠른 성과 얻기
wins = quick_wins(lang="ko")
for w in wins:
    print(f"{w['name']}: {w['description']}")

# 한국어 통계 요약
print(summary(lang="ko"))

# 한국어 풍부화 계획
plan = enrichment_plan(experience="beginner", lang="ko")
```

## Key Research Statistics

| Finding | Value | Source |
|---------|-------|--------|
| Cortisol reduction with enrichment | **37%** | J. Feline Med. Surg., 2023 |
| Problem behavior reduction | **52%** | Appl. Anim. Behav. Sci., 2022 |
| Obesity risk reduction | **40%** | J. Vet. Intern. Med., 2023 |
| Cats preferring elevated spots | **85%** | Animal Cognition, 2021 |
| Cats using proper scratchers when provided | **93%** | J. Feline Med. Surg., 2022 |
| Stress reduction with multi-modal enrichment | **60%** | Animals (MDPI), 2023 |
| Cat-owner bond improvement with daily play | **45%** | Anthrozoös, 2023 |

Indoor cats with proper enrichment live healthier, longer lives. The minimum recommended interactive play time is 15-20 minutes per day, split into 2-3 sessions.

## About PlayCat (플레이캣)

PlayCat is a cat welfare research initiative providing open-source data and tools for improving indoor cat quality of life. All enrichment recommendations are based on peer-reviewed veterinary research.

- **Website**: [playcat.xyz](https://playcat.xyz)
- **GitHub**: [playcatkorea/cat-behavior-enrichment](https://github.com/playcatkorea/cat-behavior-enrichment)
- **Dataset**: [playcat/playcat-cat-behavior-new-data-set](https://huggingface.co/datasets/playcat/playcat-cat-behavior-new-data-set) on Hugging Face
- **Contact**: playcatkr@gmail.com

## Citation

If you use this library in research, please cite:

```
PlayCat Research (2026). cat-enrichment: A Python library for cat behavioral
enrichment data and assessment tools. https://pypi.org/project/cat-enrichment/
```

## License

MIT License. See [LICENSE](LICENSE) for details.

---

*Every indoor cat deserves an enriched environment. Start with just 15 minutes of play per day.*

*모든 실내 고양이는 풍부한 환경을 누릴 자격이 있습니다. 하루 15분의 놀이부터 시작하세요.*
