# Phase 5 Quest System - NPC Integration Plan

## Summary

Implement a quest-centric system where quests define their NPC givers, and NPCs automatically offer eligible quests during conversations using a probability roll + AI selection approach.

## Key Design Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Data ownership | Quest-centric | Quests define `quest_giver_npc_ids`. Adding new quests doesn't touch NPC files. |
| Offer trigger | Probability + AI select | Location-based roll first, then AI naturally weaves selected quest into dialogue. |
| Lore integration | Stub service | Create `LoreService` interface with mock data now; swap to Weaviate in Phase 6. |

## Architecture Overview

```
NPC Conversation Flow with Quest Integration:

POST /api/v1/npcs/{npc_id}/talk
         │
         ▼
┌─────────────────────────────┐
│ 1. Load Context             │
│    - NPC, Character, Location│
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ 2. Quest Eligibility Check  │
│    QuestEligibilityService  │
│    - Find quests where NPC  │
│      is quest_giver         │
│    - Filter by char level,  │
│      completed, active, etc │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ 3. Probability Roll         │
│    - Town: 30%, Tavern: 35% │
│    - Wilderness: 5%         │
│    - If fail → no offer     │
└────────────┬────────────────┘
             │ (if success)
             ▼
┌─────────────────────────────┐
│ 4. Get Lore Context (stub)  │
│    LoreService.get_context()│
│    - Quest embedded lore    │
│    - Mock regional lore     │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ 5. Build AI Prompt          │
│    - NPC persona + knowledge│
│    - Quest offering context │
│    - Lore context           │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ 6. AI Generates Dialogue    │
│    Naturally weaves quest   │
│    offer into conversation  │
│    Includes [QUEST_OFFER:id]│
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ 7. Parse Response           │
│    Extract quest_offered    │
│    Return to frontend       │
└─────────────────────────────┘
```

---

## YAML Schema Designs

### Quest YAML (Quest-Centric Approach)

```yaml
# /api/app/data/quests/easy/cellar_rats.yaml
quest_id: quest_cellar_rats
name: "Rat Problem in the Cellar"
description: |
  Giant rats have infested the Rusty Anchor's cellar.
difficulty: easy

# NPC Quest Givers (quest defines this, not NPC)
quest_giver_npc_ids:
  - npc_grom_ironbeard
quest_giver_name: "Grom Ironbeard"  # Display fallback

# Location context
location_id: crossville_tavern
region_id: crossville

# Offering conditions
offering_triggers:
  location_types: ["tavern"]
  min_character_level: 1
  max_character_level: 5
  required_quests_completed: []
  probability_weights:
    tavern: 0.35
    town: 0.20

# NPC-specific offer dialogue (keyed by NPC ID)
npc_offer_dialogues:
  npc_grom_ironbeard:
    dialogue: |
      *leans in conspiratorially* Got a problem, friend. Giant rats
      in me cellar. Been scaring off customers. 50 gold for whoever
      clears 'em out.
    conditions:
      min_relationship: 30
      required_flags: []
      forbidden_flags: ["refused_rat_quest"]

# What NPCs know about this quest (for AI context)
npc_quest_knowledge:
  npc_grom_ironbeard:
    - "The rats started appearing about a week ago"
    - "They seem bigger than normal rats"
    - "Old smuggling tunnels under the cellar"

# Embedded lore (used before Weaviate exists)
lore_context:
  backstory: |
    The cellar connects to old smuggling tunnels from Captain
    Morgath's days. Recent earthquakes may have reopened them.
  world_connections:
    - "The earthquakes also disturbed the Old Mines"
  regional_hints:
    - "Smuggling was common 50 years ago in Crossville"

# Narrative hooks for natural dialogue
dialogue_templates:
  narrative_hooks:
    - "mentions unusual scratching sounds from below"
    - "complains about spoiled food supplies"
    - "nervously glances toward the cellar door"

# Objectives
objectives:
  - objective_id: kill_rats
    description: "Clear out the giant rats (0/10)"
    objective_type: kill
    required_progress: 10
    target_enemy_type: giant_rat

# Rewards
rewards:
  gold: 50
  experience: 100
  items: []
  relationship_bonuses:
    npc_grom_ironbeard: 10
  unlocks_quests: ["quest_tunnel_mystery"]

# Completion
completion_dialogue:
  npc_grom_ironbeard: |
    *actually smiles* Well done! Rats are gone, cellar's safe.
    Here's your coin. Drink's on the house tonight.
```

### NPC YAML (Simplified - No Quest Lists)

NPCs no longer need `quest_giver_for` since quests define their givers.

```yaml
# /api/app/data/npcs/crossville/npc_grom_ironbeard.yaml
npc_id: npc_grom_ironbeard
name: Grom Ironbeard
role: bartender
location_id: crossville_tavern
image_url: /static/images/npcs/crossville/grom_ironbeard.png

# All other existing fields remain unchanged
personality: { ... }
appearance: { ... }
knowledge: { ... }
dialogue_hooks: { ... }
# NO quest_giver_for field needed
```

---

## Implementation Tasks

### Group 1: Quest Data Models (3 tasks)

| ID | Task | File | Notes |
|----|------|------|-------|
| 5.1 | Create Quest dataclass | `/api/app/models/quest.py` | Include all fields from YAML schema |
| 5.2 | Create QuestObjective, QuestReward, QuestTriggers | `/api/app/models/quest.py` | Objective types: kill, collect, travel, interact, discover |
| 5.3 | Add `to_dict()`/`from_dict()` serialization | `/api/app/models/quest.py` | Test round-trip JSON serialization |

### Group 2: Quest Loading Service (3 tasks)

| ID | Task | File | Notes |
|----|------|------|-------|
| 5.4 | Create `/api/app/data/quests/` directory structure | directories | `easy/`, `medium/`, `hard/`, `epic/` |
| 5.5 | Implement QuestService (loader) | `/api/app/services/quest_service.py` | Follow `npc_loader.py` pattern with caching |
| 5.6 | Write 5 example quests | `/api/app/data/quests/*.yaml` | 2 easy, 2 medium, 1 hard |

### Group 3: Quest Eligibility Service (3 tasks)

| ID | Task | File | Notes |
|----|------|------|-------|
| 5.7 | Create QuestEligibilityService | `/api/app/services/quest_eligibility_service.py` | Core eligibility logic |
| 5.8 | Implement `get_quests_for_npc()` | same file | Find quests where NPC is quest_giver |
| 5.9 | Implement probability roll + filtering | same file | Location-based weights, level check, status check |

### Group 4: Lore Service Stub (2 tasks)

| ID | Task | File | Notes |
|----|------|------|-------|
| 5.10 | Create LoreService interface | `/api/app/services/lore_service.py` | Abstract interface for Phase 6 |
| 5.11 | Implement MockLoreService | same file | Returns quest's embedded lore_context |

### Group 5: AI Prompt Integration (3 tasks)

| ID | Task | File | Notes |
|----|------|------|-------|
| 5.12 | Add quest offering section to template | `/api/app/ai/templates/npc_dialogue.j2` | Quest context + natural weaving instructions |
| 5.13 | Add lore context section to template | same file | Filtered lore for NPC knowledge |
| 5.14 | Implement quest offer parsing | `/api/app/ai/response_parser.py` | Extract `[QUEST_OFFER:quest_id]` markers |

### Group 6: NPC API Integration (4 tasks)

| ID | Task | File | Notes |
|----|------|------|-------|
| 5.15 | Integrate eligibility check into `talk_to_npc` | `/api/app/api/npcs.py` | Check before building AI context |
| 5.16 | Add quest context to AI task | `/api/app/tasks/ai_tasks.py` | Modify `_process_npc_dialogue_task` |
| 5.17 | Handle quest_offered in response | `/api/app/api/npcs.py` | Parse and include in API response |
| 5.18 | Remove `quest_giver_for` from NPC model | `/api/app/models/npc.py` | Clean up old field if exists |

### Group 7: Quest Accept/Manage Endpoints (4 tasks)

| ID | Task | File | Notes |
|----|------|------|-------|
| 5.19 | Create quests blueprint | `/api/app/api/quests.py` | Register in `__init__.py` |
| 5.20 | Implement `POST /api/v1/quests/accept` | same file | Add to active_quests, update relationship |
| 5.21 | Implement `POST /api/v1/quests/decline` | same file | Set `refused_{quest_id}` flag |
| 5.22 | Implement `GET /api/v1/characters/{id}/quests` | same file | List active and completed quests |

### Group 8: Testing & Validation (3 tasks)

| ID | Task | File | Notes |
|----|------|------|-------|
| 5.23 | Unit tests for Quest models | `/api/tests/test_quest_models.py` | Serialization, validation |
| 5.24 | Unit tests for QuestEligibilityService | `/api/tests/test_quest_eligibility.py` | Filtering logic |
| 5.25 | Integration test: full quest offer flow | `/api/tests/test_quest_integration.py` | NPC talk → offer → accept |

---

## Critical Files to Read Before Implementation

| File | Reason |
|------|--------|
| `/api/app/services/npc_loader.py` | Pattern for YAML loading with caching |
| `/api/app/models/npc.py` | Current NPC dataclass structure |
| `/api/app/api/npcs.py` | Current `talk_to_npc` endpoint implementation |
| `/api/app/tasks/ai_tasks.py` | `_process_npc_dialogue_task` function (lines 667-795) |
| `/api/app/ai/templates/npc_dialogue.j2` | Current prompt template structure |
| `/api/app/models/character.py` | `active_quests`, `completed_quests` fields |

---

## Data Flow Summary

```
1. Player talks to NPC → POST /api/v1/npcs/{npc_id}/talk

2. Backend:
   a. QuestService.get_quests_for_npc(npc_id)
      → Find quests where npc_id in quest_giver_npc_ids

   b. QuestEligibilityService.filter_eligible(quests, character)
      → Remove: already active, completed, wrong level, flags block

   c. Probability roll based on location
      → 35% chance in tavern, 5% in wilderness, etc.

   d. If roll succeeds + eligible quests exist:
      → Pick quest (first eligible or AI-selected if multiple)
      → Build QuestOfferContext with dialogue + lore

   e. Add quest context to AI prompt

   f. AI generates dialogue, naturally mentions quest
      → Includes [QUEST_OFFER:quest_cellar_rats] if offering

3. Parse response, return to frontend:
   {
     "dialogue": "NPC's natural dialogue...",
     "quest_offered": {
       "quest_id": "quest_cellar_rats",
       "name": "Rat Problem",
       "description": "...",
       "rewards": {...}
     }
   }

4. Frontend shows quest offer UI
   → Player clicks Accept

5. POST /api/v1/quests/accept
   → Add to character.active_quests
   → Update NPC relationship (+5)
   → Return acceptance dialogue
```

---

## Phase 6 Integration Points

When implementing Phase 6 (Weaviate lore), these touchpoints enable integration:

1. **LoreService interface** - Replace `MockLoreService` with `WeaviateLoreService`
2. **Quest.lore_context** - Supplement embedded lore with Weaviate queries
3. **NPC dialogue template** - Lore section already prepared
4. **Knowledge filtering** - `LoreService.filter_for_npc()` method exists

---

## NPC YAML Migration

Existing NPC files need these changes:

**Remove (if exists):**
- `quest_giver_for: [...]` - No longer needed

**Keep unchanged:**
- `location_id` - Required
- `image_url` - Required
- All other fields - Unchanged

The `quest_giver_for` field in `npc_mayor_aldric.yaml` will be removed since quests now define their givers.

---

## Success Criteria

- [ ] Quest YAML schema implemented and validated
- [ ] QuestService loads quests from YAML with caching
- [ ] QuestEligibilityService filters correctly by all conditions
- [ ] Probability roll works per location type
- [ ] AI prompt includes quest context when offering
- [ ] AI naturally weaves quest offers into dialogue
- [ ] Quest offer parsing extracts `[QUEST_OFFER:id]` correctly
- [ ] Accept endpoint adds quest to active_quests
- [ ] Max 2 active quests enforced
- [ ] Relationship bonus applied on quest completion
- [ ] LoreService stub returns embedded lore_context