AI Director

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service File: backend/src/services/asoDirector.service.ts, backend/src/services/aso.service.ts

---

Overview

The AI Director is a "Game Master" system that empowers the ASO to be an active director of the story, not just a passive respondent. It uses an advanced prompt to access a "Toolbox" of special JSON commands that enable story orchestration.

---

Architecture

AI Director Flow

---

Director Prompt

Toolbox Access

The AI Director prompt gives the ASO access to a "Toolbox" of JSON commands:

Available Commands:

• {"offerQuest": {"questId": 123}} - Offer quest to player
• {"completeQuest": {"questId": 123}} - Complete quest
• {"modifyInventory": {"itemId": 1, "quantity": 5}} - Grant/consume items
• {"modifyCurrency": {"amount": 100}} - Grant/consume currency
• {"choices": ["Option 1", "Option 2", "Option 3"]} - Present choices
• {"setRelationshipFlag": {"flag": "milestone", "value": true}} - Set relationship flag
• {"configureAso": {...}} - Update ASO config (legacy)

---

Command Execution

Process

1. Prompt Building:

   • Director prompt includes toolbox documentation
   • Tool definitions injected into prompt
   • Protocol-specific rules applied

2. LLM Response:

   • LLM generates response with JSON commands
   • Commands parsed from response
   • Tool execution triggered

3. Command Execution:

   • Each command executed via tool system
   • Results collected
   • Final spoken response generated

4. Response Delivery:

   • Spoken response includes action results
   • Timeline events created
   • Memory updated

---

Available Commands

Quest Commands

offerQuest

• Offers a quest to the player
• Checks prerequisites
• Creates UserQuest record
• Sets status to in_progress

completeQuest

• Marks quest as completed
• Grants rewards automatically
• Updates timeline

Inventory Commands

modifyInventory

• Adds or removes items
• Updates user inventory
• Creates timeline event

modifyCurrency

• Modifies energy coins
• Updates user balance
• Creates timeline event

Choice Commands

choices

• Presents multiple choice options
• Player selects option
• Choice impacts narrative

Relationship Commands

setRelationshipFlag

• Sets relationship milestone flag
• Stores in ASO state
• Creates timeline event

Config Commands

configureAso (Legacy)

• Updates ASO persona/config
• Merges JSON into state
• Updates behavior

---

Director Service

Service File

File: backend/src/services/asoDirector.service.ts

Key Functions:

decideGroupChatResponse(conversationId, lastMessage, participants, recentMessages)

• Decides if Yexian should respond in group chat
• Analyzes conversation context
• Returns response decision with reasoning

Response Styles:

• natural - Full access (CSO-only or trusted groups)
• supportive - Trusted groups, be helpful but mindful
• minimal - Public groups, only respond when needed

---

Integration with ASO Service

Main Orchestration

File: backend/src/services/aso.service.ts

Function: handleNpcConversationTurn()

Process:

1. Builds director prompt with toolbox
2. Sends to LLM
3. Parses JSON commands from response
4. Executes commands via tool system
5. Generates final spoken response

---

Data Flow

---

Source Files

Primary Sources:

• backend/src/services/asoDirector.service.ts - Director logic
• backend/src/services/aso.service.ts - Main orchestration
• backend/src/services/toolExecutor.service.ts - Command execution

---

Related Documentation

• Quest System - Quest commands and management
• Inventory System - Inventory commands
• Choices System - Choice generation commands
• Relationship Milestones - Relationship flag commands
• Tool System - Tool execution framework
• Prompt System - Director prompt composition
• 06-ARCHITECTURE/Data-Flow.md - AI Director flow
• 00-OVERVIEW.md - Complete system overview