# Phase 4: AI Integration + Story Progression + Quest System
## Implementation Plan
> **Note:** This document contains detailed implementation tasks for developers building the API backend.
> For high-level project roadmap and progress tracking, see [/docs/ROADMAP.md](../../docs/ROADMAP.md).
**Document Version:** 1.2
**Created:** November 16, 2025
**Last Updated:** November 23, 2025
**Status:** In Progress
**Duration:** 3 weeks (21 days)
**Total Tasks:** 45 tasks
**Completed Tasks:** 22/45 (49%)
---
### Next Tasks
- Task 8.29: Create story gameplay template with HTMX
---
## Overview
Phase 4 delivers the core single-player gameplay experience for Code of Conquest. This phase integrates AI narrative generation via Replicate (Llama-3 and Claude models), implements turn-based story progression with button-based actions, and creates a context-aware quest system.
> **Architecture Note:** All AI models (Llama-3, Claude Haiku/Sonnet/Opus) are accessed through the Replicate API for unified billing and management.
**Key Deliverables:**
- AI narrative generation with tier-based model selection
- Turn-based story progression system
- YAML-driven quest system with context-aware offering
- Cost tracking and usage limits
- Complete solo gameplay loop
**Development Approach:**
- Tasks are moderately granular (4 hours each)
- Testing bundled into implementation tasks
- Verification checkpoints after major features
- YAML data created inline with features
---
## Week 8: Story Progression System (Days 8-14)
**Goal:** Implement turn-based story progression with button-based actions
### Task Group 8: Story UI & Integration (Tasks 29-31)
#### Task 8.29: Create story gameplay template with HTMX
**Duration:** 5 hours
**File:** `templates/game/story.html`
**Implementation:**
- Create main story gameplay page layout:
- Header: Character info, turn count, location
- Left sidebar: Quest tracker (placeholder for Week 9)
- Main area: Latest DM response
- Action panel: Available action buttons
- Footer: Custom input (if Premium/Elite)
- Right sidebar: Conversation history (collapsible)
- Add HTMX for dynamic updates:
- Action buttons trigger `hx-post="/api/v1/sessions/{id}/action"`
- Poll job status with `hx-trigger="every 2s"`
- Update content when job completes
- Add loading spinner during AI processing
- Style with dark fantasy theme (match existing CSS)
- Add responsive design (mobile-friendly)
- Write Flask route to render template
- Test UI rendering
**Dependencies:** Tasks 8.25-8.28 (API endpoints)
**Deliverable:** Story gameplay UI template
**Key HTMX Patterns:**
```html
Processing...
```
---
#### Task 8.30: Build action button UI with tier filtering
**Duration:** 4 hours
**File:** `templates/game/story.html` (extend), `app/routes/game.py`
**Implementation:**
- Create Jinja2 macro for rendering action buttons
- Filter actions based on user tier (passed from backend)
- Show locked actions with upgrade prompt for higher tiers
- Add tooltips with action descriptions
- Implement custom text input area:
- Only visible for Premium/Elite
- Character counter (250 for Premium, 500 for Elite)
- Submit button with validation
- Add HTMX for seamless submission
- Style buttons with RPG aesthetic (icons optional)
- Disable buttons during AI processing
- Write Flask route to provide available actions
**Dependencies:** Task 8.29 (Story template)
**Deliverable:** Dynamic action button system
**Jinja2 Macro:**
```jinja
{% macro render_action(action, user_tier, locked=False) %}
{% endmacro %}
```
---
#### Task 8.31: ✅ CHECKPOINT - Full story turn integration test
**Duration:** 4 hours
**Verification Steps:**
1. Create a new session via UI
2. Click an action button
3. Verify loading state appears
4. Wait for AI response
5. Verify DM response displayed
6. Check conversation history updated
7. Verify turn number incremented
8. Test with different action buttons
9. Test custom text input (Premium tier)
10. Verify tier restrictions enforced (Free can't use Premium actions)
11. Test rate limiting
12. Verify Realtime updates work
**Success Criteria:**
- Full story turn loop works end-to-end
- UI updates smoothly with HTMX
- AI responses are coherent and relevant
- Tier filtering works correctly
- Rate limits enforced
- No errors in browser console or server logs
---
## Week 9: Quest System (Days 15-21)
**Goal:** Implement YAML-driven quest system with context-aware offering
### Task Group 9: Quest Data Models (Tasks 32-34)
#### Task 9.32: Create Quest dataclasses
**Duration:** 5 hours
**File:** `app/models/quest.py`
**Implementation:**
- Create `QuestObjective` dataclass:
- `objective_id`, `description`, `objective_type` (enum)
- `required_progress`, `current_progress`, `completed`
- Create `QuestReward` dataclass:
- `gold`, `experience`, `items` (List[Item])
- `reputation` (optional, for future use)
- Create `Quest` dataclass:
- `quest_id`, `name`, `description`, `quest_giver`
- `difficulty` (enum: EASY, MEDIUM, HARD, EPIC)
- `objectives` (List[QuestObjective])
- `rewards` (QuestReward)
- `offering_triggers` (QuestTriggers)
- `narrative_hooks` (List[str])
- `status` (enum: AVAILABLE, ACTIVE, COMPLETED, FAILED)
- Implement methods:
- `is_complete()` - Check if all objectives done
- `get_next_objective()` - Get first incomplete objective
- `update_progress(objective_id, amount)` - Increment progress
- Add to_dict() / from_dict() serialization
- Write unit tests for all methods
**Dependencies:** None
**Deliverable:** Quest data models
**Example:**
```python
quest = Quest(
quest_id="quest_goblin_cave",
name="Clear the Goblin Cave",
description="A nearby cave is infested with goblins...",
quest_giver="Village Elder",
difficulty=QuestDifficulty.EASY,
objectives=[
QuestObjective(
objective_id="kill_goblins",
description="Defeat 5 goblins",
objective_type=ObjectiveType.KILL,
required_progress=5,
current_progress=0
)
],
rewards=QuestReward(gold=50, experience=100, items=[])
)
quest.update_progress("kill_goblins", 1)
quest.is_complete() # False (4 more goblins needed)
```
---
#### Task 9.33: Create QuestTriggers with offering logic
**Duration:** 4 hours
**File:** `app/models/quest.py` (extend)
**Implementation:**
- Create `QuestTriggers` dataclass:
- `location_types` (List[LocationType]) - Where quest can be offered
- `specific_locations` (List[str]) - Optional specific location names
- `min_character_level`, `max_character_level` (int)
- `required_quests_completed` (List[str]) - Quest prerequisites
- `probability_weights` (Dict[LocationType, float]) - Offer chance by location
- Implement methods:
- `can_offer(character_level, completed_quests)` - Check eligibility
- `get_offer_probability(location_type)` - Get chance for location
- Add validation (probabilities 0.0-1.0)
- Write unit tests for offering logic
- Document trigger system in docstrings
**Dependencies:** Task 9.32 (Quest model)
**Deliverable:** Quest offering trigger system
**Example:**
```python
triggers = QuestTriggers(
location_types=[LocationType.TOWN, LocationType.TAVERN],
min_character_level=1,
max_character_level=5,
probability_weights={
LocationType.TOWN: 0.30,
LocationType.TAVERN: 0.35
}
)
triggers.can_offer(character_level=3, completed_quests=[]) # True
triggers.get_offer_probability(LocationType.TAVERN) # 0.35 (35% chance)
```
---
#### Task 9.34: ✅ CHECKPOINT - Verify quest model serialization
**Duration:** 2 hours
**Verification Steps:**
1. Create sample quest with all fields
2. Convert to dict with to_dict()
3. Serialize to JSON
4. Deserialize from JSON
5. Recreate quest with from_dict()
6. Verify all fields match original
7. Test quest methods (is_complete, update_progress)
8. Test trigger methods (can_offer, get_offer_probability)
9. Test edge cases (invalid progress, level requirements)
**Success Criteria:**
- Quest serialization round-trips correctly
- All methods work as expected
- Offering logic accurate
- No data loss during serialization
---
### Task Group 10: Quest Content & Loading (Tasks 35-38)
#### Task 9.35: Create quest YAML schema
**Duration:** 3 hours
**File:** `app/data/quests/schema.yaml` (documentation), update `docs/QUEST_SYSTEM.md`
**Implementation:**
- Document YAML structure for quests
- Define all required and optional fields
- Provide examples for each objective type
- Document narrative_hooks usage
- Create template quest file
- Add validation rules
- Update QUEST_SYSTEM.md with schema details
**Dependencies:** Task 9.32 (Quest models)
**Deliverable:** Quest YAML schema documentation
**Schema Example:**
```yaml
quest_id: quest_goblin_cave
name: Clear the Goblin Cave
description: |
A nearby cave has been overrun by goblins who are raiding nearby farms.
The village elder asks you to clear them out.
quest_giver: Village Elder
difficulty: EASY
objectives:
- objective_id: kill_goblins
description: Defeat 5 goblins
objective_type: KILL
required_progress: 5
rewards:
gold: 50
experience: 100
items: []
offering_triggers:
location_types: [TOWN, TAVERN]
min_character_level: 1
max_character_level: 5
probability_weights:
TOWN: 0.30
TAVERN: 0.35
narrative_hooks:
- "The village elder looks worried about recent goblin attacks"
- "You hear farmers complaining about lost livestock"
- "A town guard mentions a cave to the north"
```
---
#### Task 9.36: Write 10 example quests
**Duration:** 5 hours
**Files:** `app/data/quests/easy/*.yaml`, `app/data/quests/medium/*.yaml`, etc.
**Implementation:**
- Create quest files organized by difficulty:
- **Easy (4 quests):** Levels 1-3, simple objectives
1. Clear Goblin Cave (kill 5 goblins)
2. Gather Healing Herbs (collect 10 herbs)
3. Deliver Message to Town (travel to location)
4. Find Lost Cat (discover location)
- **Medium (3 quests):** Levels 3-7, multi-objective
5. Investigate Bandit Camp (kill + collect + discover)
6. Rescue Kidnapped Villager (travel + interact)
7. Ancient Artifact Recovery (discover + collect)
- **Hard (2 quests):** Levels 7-10, complex chains
8. Stop the Necromancer (multi-step with prerequisites)
9. Dragon's Hoard (discover + kill boss + collect)
- **Epic (1 quest):** Level 10+, multi-chapter
10. The Demon Lord's Return (epic multi-objective chain)
- Include rich narrative_hooks for each quest
- Vary reward amounts by difficulty
- Add location variety
- Ensure proper level gating
**Dependencies:** Task 9.35 (YAML schema)
**Deliverable:** 10 complete quest YAML files
---
#### Task 9.37: Implement QuestService with YAML loader
**Duration:** 5 hours
**File:** `app/services/quest_service.py`
**Implementation:**
- Create `QuestService` class
- Implement `load_quests_from_yaml(directory)` method
- Parse all YAML files in quest directory
- Convert to Quest objects
- Validate quest structure and fields
- Cache loaded quests in memory
- Implement methods:
- `get_quest_by_id(quest_id)`
- `get_eligible_quests(character_level, location_type, completed_quests)`
- `filter_by_difficulty(difficulty)`
- `get_all_quests()`
- Add error handling for malformed YAML
- Write unit tests with sample quests
- Add logging for quest loading
**Dependencies:** Task 9.36 (Quest YAML files)
**Deliverable:** Quest loading and filtering service
**Usage:**
```python
service = QuestService()
service.load_quests_from_yaml("app/data/quests/")
# Get eligible quests
eligible = service.get_eligible_quests(
character_level=3,
location_type=LocationType.TAVERN,
completed_quests=[]
)
# Returns: [Quest(...), Quest(...)]
```
---
#### Task 9.38: ✅ CHECKPOINT - Verify quest loading and validation
**Duration:** 2 hours
**Verification Steps:**
1. Load all 10 quests from YAML files
2. Verify all quests parsed correctly
3. Check quest filtering by level works
4. Test filtering by location type
5. Verify offering probability calculations
6. Test get_eligible_quests() with various inputs
7. Verify error handling for invalid YAML
8. Check quest caching works
**Success Criteria:**
- All 10 quests load without errors
- Filtering logic accurate
- Offering probabilities correct
- No performance issues loading quests
- Error handling graceful
---
### Task Group 11: Quest Offering & Management (Tasks 39-42)
#### Task 9.39: Implement context-aware quest offering logic
**Duration:** 5 hours
**File:** `app/services/quest_offering_service.py`
**Implementation:**
- Create `QuestOfferingService` class
- Implement two-stage offering:
1. **Location probability roll:**
- Get location type probability from triggers
- Roll random 0.0-1.0, check if < probability
- If fail, no quest offered
2. **Context-aware AI selection:**
- Get eligible quests from QuestService
- Build AI prompt with narrative_hooks
- Ask AI to select most contextually relevant quest
- Parse AI response to get selected quest_id
- Implement `should_offer_quest(location_type)` method (probability roll)
- Implement `select_quest_for_context(eligible_quests, game_context)` method (AI selection)
- Implement main `offer_quest(session_id)` method (full flow)
- Add validation (max 2 active quests)
- Write integration tests with mocked AI
- Add logging for quest offerings
**Dependencies:** Tasks 7.10 (NarrativeGenerator), 9.37 (QuestService)
**Deliverable:** Context-aware quest offering system
**Flow:**
```python
offering_service = QuestOfferingService()
# Called after each story turn
if offering_service.should_offer_quest(LocationType.TAVERN):
eligible = quest_service.get_eligible_quests(...)
selected_quest = offering_service.select_quest_for_context(
eligible_quests=eligible,
game_context={
"location": "The Rusty Anchor",
"recent_actions": ["talked to locals", "rested"],
"active_quests": []
}
)
# Returns: Quest object or None
```
---
#### Task 9.40: Integrate quest offering into story turns
**Duration:** 4 hours
**File:** `app/tasks/ai_tasks.py` (extend generate_dm_response job)
**Implementation:**
- Update `generate_dm_response()` RQ job
- After AI narrative generated and before saving:
1. Check if quest should be offered (probability roll)
2. If yes, get eligible quests
3. Call AI to select contextually relevant quest
4. Add quest offering to response data
5. Store offered quest in session state (pending acceptance)
- Add quest offering to conversation entry:
```python
{
"turn": 5,
"action": "...",
"dm_response": "...",
"quest_offered": {
"quest_id": "quest_goblin_cave",
"quest_name": "Clear the Goblin Cave"
}
}
```
- Update API response format to include quest offering
- Write integration tests for offering flow
- Add logging for quest offerings
**Dependencies:** Task 9.39 (Quest offering logic)
**Deliverable:** Integrated quest offering in story turns
**Updated Response:**
```json
{
"status": 200,
"result": {
"dm_response": "As you chat with the locals...",
"quest_offered": {
"quest_id": "quest_goblin_cave",
"name": "Clear the Goblin Cave",
"description": "...",
"rewards": {"gold": 50, "experience": 100}
}
}
}
```
---
#### Task 9.41: Implement quest accept endpoint
**Duration:** 4 hours
**File:** `app/routes/quests.py` (new file)
**Implementation:**
- Create `POST /api/v1/quests/accept` endpoint
- Validate request body:
```json
{
"session_id": "sess_789",
"quest_id": "quest_goblin_cave"
}
```
- Validate quest is currently offered to session
- Check max 2 active quests limit
- Add quest to session's active_quests
- Initialize quest with status ACTIVE
- Store quest state in character (or session)
- Return accepted quest details
- Add @require_auth decorator
- Write integration tests
- Document in API_REFERENCE.md
**Dependencies:** Task 9.39 (Quest offering)
**Deliverable:** Quest acceptance endpoint
**Response:**
```json
{
"status": 200,
"result": {
"quest_id": "quest_goblin_cave",
"status": "ACTIVE",
"objectives": [
{
"objective_id": "kill_goblins",
"description": "Defeat 5 goblins",
"progress": "0/5"
}
]
}
}
```
---
#### Task 9.42: Implement quest complete endpoint with rewards
**Duration:** 5 hours
**File:** `app/routes/quests.py` (extend)
**Implementation:**
- Create `POST /api/v1/quests/complete` endpoint
- Validate request body:
```json
{
"session_id": "sess_789",
"quest_id": "quest_goblin_cave"
}
```
- Verify quest is active for session
- Check all objectives completed
- Grant rewards:
- Add gold to character
- Add experience to character
- Add items to inventory
- Check for level up
- Update quest status to COMPLETED
- Remove from active_quests
- Add to completed_quests list
- Return completion details with level up info
- Add @require_auth decorator
- Write integration tests
- Document in API_REFERENCE.md
**Dependencies:** Task 9.41 (Quest accept)
**Deliverable:** Quest completion and reward system
**Response:**
```json
{
"status": 200,
"result": {
"quest_id": "quest_goblin_cave",
"status": "COMPLETED",
"rewards_granted": {
"gold": 50,
"experience": 100,
"items": []
},
"level_up": {
"leveled_up": true,
"new_level": 4,
"skill_points_gained": 1
}
}
}
```
---
### Task Group 12: Quest UI & Final Testing (Tasks 43-45)
#### Task 9.43: Create quest tracker sidebar UI
**Duration:** 4 hours
**File:** `templates/game/story.html` (extend left sidebar)
**Implementation:**
- Add quest tracker to left sidebar
- Display active quests (max 2)
- Show quest name and description
- Display objective progress (X/Y format)
- Add "View Details" button for each quest
- Style with RPG theme
- Add HTMX for dynamic updates when objectives progress
- Show "No active quests" message when empty
- Add quest complete notification (toast/modal)
- Test UI rendering
**Dependencies:** Tasks 9.41-9.42 (Quest endpoints)
**Deliverable:** Quest tracker sidebar UI
**UI Structure:**
```html