# Bio Generator Usage Examples

## Basic Usage

### Generate a bio for a person

```python
from dating.bio_generator import generate_dating_bio

# Using a person object
person = {
    'firstname': 'Sarah',
    'ageYears': 26,
    'sex': 'Female',
    'occupation': 'Marketing Manager',
    'likes': ['traveling', 'photography', 'yoga']
}

bio = generate_dating_bio(person)
print(bio)
# Output: "I'm passionate about capturing moments through my lens and exploring new destinations.
#          As a marketing manager by day, I love bringing creative ideas to life!"
```

### Get or generate bio with caching

```python
from dating.bio_generator import get_or_generate_bio
from functions import get_database_connection

db = get_database_connection()

# First call generates and caches bio
bio = get_or_generate_bio(person_id=123, db_connection=db)

# Second call within 30 days returns cached bio (no API call)
bio = get_or_generate_bio(person_id=123, db_connection=db)

# Force regeneration
bio = get_or_generate_bio(person_id=123, db_connection=db, force_regenerate=True)
```

### Regenerate bio on life events

```python
from dating.bio_generator import regenerate_bio_on_life_change

# Triggers regeneration for major events
new_bio = regenerate_bio_on_life_change(
    person_id=123,
    db_connection=db,
    event_type='job_change'  # or 'graduation', 'promotion', 'breakup', 'marriage'
)

# Returns None for minor events (no regeneration)
result = regenerate_bio_on_life_change(
    person_id=123,
    db_connection=db,
    event_type='ate_food'  # Minor event - no regeneration
)
```

### Batch generation with rate limiting

```python
from dating.bio_generator import batch_generate_bios

person_ids = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# Generate up to 10 bios (respects rate limits)
results = batch_generate_bios(
    person_ids=person_ids,
    db_connection=db,
    max_api_calls=10
)

for person_id, bio in results.items():
    if bio:
        print(f"Person {person_id}: {bio}")
    else:
        print(f"Person {person_id}: Failed to generate")
```

## Integration with Game Events

### On character creation

```python
from dating.bio_generator import generate_dating_bio, save_bio_to_database

def on_character_created(person):
    """Generate bio when NPC is created"""
    bio = generate_dating_bio(person)
    save_bio_to_database(person.id, bio, db)
    person.bio = bio
```

### On job change event

```python
def on_job_change(person_id):
    """Update bio when character changes jobs"""
    new_bio = regenerate_bio_on_life_change(
        person_id=person_id,
        db_connection=db,
        event_type='job_change'
    )
    if new_bio:
        print(f"Bio updated: {new_bio}")
```

### On dating profile view

```python
def show_dating_profile(person_id):
    """Show dating profile with cached or generated bio"""
    bio = get_or_generate_bio(person_id, db)

    # Display in UI
    return {
        'bio': bio,
        'last_updated': get_last_update_time(person_id)
    }
```

## Error Handling

The bio generator includes automatic fallbacks:

```python
# If OpenAI API fails, returns a simple fallback bio
bio = generate_dating_bio(person)
# Always returns a bio, never None

# Example fallback:
# "I'm Sarah, a 26-year-old marketing manager who enjoys traveling, photography, yoga.
#  Looking to meet new people!"
```

## Configuration

Ensure your `.env` file includes:

```bash
OPENAI_API_KEY=sk-proj-your-key-here
OPENAI_MAX_REQUESTS_PER_HOUR=60
```

## Caching Strategy

- Bios are cached for **30 days** after generation
- Cached bios avoid unnecessary API calls and costs
- Cache is automatically invalidated on:
  - Force regeneration
  - Bio older than 30 days
  - Major life events (job change, graduation, etc.)

## Testing

Run the comprehensive test suite:

```bash
cd ws
python -m pytest tests/test_bio_generation.py -v
```

All OpenAI API calls are mocked in tests - no real API calls are made.