AI Development Index¶
Purpose¶
This document serves as a master reference for AI agents during development of The Path (AI-Pi). It indexes essential resources and documentation across the project.
Project Resources¶
Repository Structure¶
Root_Directories:
docs: "Documentation and specifications"
src: "Source code"
tests: "Test files"
scripts: "Build and utility scripts"
images: "Project images and assets"
Documentation_Structure:
overview: "High-level project documentation"
technical: "Technical specifications and APIs"
implementation: "Implementation details and planning"
meta:
logs: "Development logs"
social: "Social media updates"
contributing: "Contribution guidelines"
character_classes: "Game character specifications"
Core Documentation¶
Project_Overview:
documentation_site: "https://materdev.github.io/thepath-ai_pi/"
project_scope: "docs/overview/project-scope.md"
research_objectives: "docs/overview/research-objectives.md"
development_logs: "docs/meta/logs/index.md"
social_updates: "docs/meta/social/index.md"
Development_Guidelines:
contributing: "docs/meta/contributing.md"
style_guide: "docs/meta/style-guide.md"
setup_guide: "docs/meta/implementation/setup/project-setup.md"
Documentation Standards¶
Log_Format:
structure:
- Session overview with YAML metadata
- Focus areas
- Changes made
- Technical details
- Challenges and solutions
- Resources
location: "docs/meta/logs/*.md"
Social_Updates:
structure:
- YAML frontmatter (date, platform, type, hashtags)
- Content in code blocks
- Hashtags
location: "docs/meta/social/linkedin/*.md"
Development Workflow¶
Documentation:
automated_updates:
- Log navigation
- Social media posts
- Site deployment
tools:
- MkDocs Material theme
- GitHub Pages
- GitHub Actions
Version_Control:
branch_strategy:
main: "Primary development branch"
commit_conventions:
- "docs: Documentation updates"
- "feat: New features"
- "fix: Bug fixes"
- "chore: Maintenance"
Technical Requirements¶
Development:
python: "3.11+"
raspberry_pi: "5"
make: "Required for build scripts"
Documentation:
mkdocs: "Latest"
mkdocs_material: "Latest"
mkdocs_awesome_pages: "Latest"
python_yaml: "Latest"
Project Phases¶
Phase_1:
focus: "Core Systems"
status: "In Progress"
tracking: "docs/overview/project-scope.md"
Phase_2:
focus: "Game Features"
status: "Planned"
tracking: "docs/overview/project-scope.md"
Phase_3:
focus: "Polish & Launch"
status: "Planned"
tracking: "docs/overview/project-scope.md"
Resources¶
External_Links:
mkdocs: "https://www.mkdocs.org/"
mkdocs_material: "https://squidfunk.github.io/mkdocs-material/"
github_pages: "https://docs.github.com/en/pages"
github_actions: "https://docs.github.com/en/actions"
Core Specifications¶
Performance Requirements¶
AI:
response_time_max: 100ms
memory_limit: 512MB
difficulty_range: [0.2, 0.95]
Server:
update_time_max: 50ms
concurrent_games: 4
websocket_protocol: true
Client:
frame_time_max: 16ms
react_redux: true
typescript: true
Hardware:
platform: "Raspberry Pi 5"
ram: "8GB"
accelerator: "AI HAT+"
cooling: "Active"
Critical Paths¶
Documentation:
overview: "docs/overview/"
technical: "docs/technical/"
implementation: "docs/implementation/"
meta: "docs/meta/"
Source:
server: "server/"
client: "client/"
ai: "ai/"
scripts: "scripts/"
Documentation Map¶
Key Documents¶
Architecture:
system: "docs/overview/system-architecture.md"
server: "docs/implementation/server/architecture.md"
client: "docs/implementation/client/architecture.md"
ai: "docs/implementation/ai/architecture.md"
APIs:
endpoints: "docs/technical/api/endpoints.md"
websocket: "docs/technical/api/endpoints.md#websocket-events"
rest: "docs/technical/api/endpoints.md#rest-endpoints"
Data:
schemas: "docs/technical/data-schemas/"
game_state: "docs/technical/data-schemas/game-state.md"
ai_models: "docs/technical/data-schemas/ai-models.md"
Setup:
project: "docs/implementation/setup/project-setup.md"
dependencies: "docs/technical/dependencies.md"
Game Mechanics Reference¶
Combat System¶
Turn_Based:
order: "Speed-based probability"
actions_per_turn: 1
reaction_system: true
Actions:
attack:
targeting: "Single/AOE"
damage_types: ["Physical", "Magical", "True"]
defend:
duration: "Until next turn"
bonus: "50% damage reduction"
ability:
cooldown: true
resource_cost: true
targeting: "Varied"
item:
inventory_limit: 6
use_time: "1 action"
Status_Effects:
duration: "1-5 turns"
stacking: "Some effects"
cleansing: "Specific abilities"
Character System¶
Classes:
warrior:
focus: "Physical damage/Tank"
difficulty: 0.3
mage:
focus: "Magical damage/Control"
difficulty: 0.7
rogue:
focus: "Speed/Critical hits"
difficulty: 0.8
support:
focus: "Healing/Buffs"
difficulty: 0.6
Stats:
primary:
- health
- attack
- defense
- speed
secondary:
- critical_chance
- dodge
- resistance
- accuracy
Character Classes¶
Classes:
Conjuror:
doc: "docs/character_classes/conjuror_bio.yml"
role: "Damage/Control"
theme: "Arcane manipulation and energy control"
combat_style: "Mid-range spell weaver"
difficulty: "Medium"
Crystal_Vanguard:
doc: "docs/character_classes/crystal_vanguard_bio.yml"
role: "Tank/Support"
theme: "Crystal-based defense and protection"
combat_style: "Frontline protector"
difficulty: "Low"
Zealot:
doc: "docs/character_classes/zealot_bio.yml"
role: "Damage/Mobility"
theme: "Fanatical combat prowess"
combat_style: "Aggressive skirmisher"
difficulty: "High"
Wraithwood_Seer:
doc: "docs/character_classes/wraithwood_seer_bio.yml"
role: "Support/Control"
theme: "Natural magic and foresight"
combat_style: "Tactical support"
difficulty: "Medium"
Primal_Shifter:
doc: "docs/character_classes/primal_shifter_bio.yml"
role: "Tank/Damage"
theme: "Bestial transformation"
combat_style: "Adaptable warrior"
difficulty: "High"
The_Blessed:
doc: "docs/character_classes/the_blessed_bio.yml"
role: "Support/Utility"
theme: "Divine blessings and protection"
combat_style: "Strategic enabler"
difficulty: "Medium"
Class_System:
doc_root: "docs/character_classes/"
balance_considerations:
- Each class must have clear strengths and weaknesses
- Roles should complement each other in team composition
- Difficulty ratings affect AI behavior adaptation
- Combat styles should enable diverse strategies
class_relationships:
strong_against:
Conjuror: ["The_Blessed", "Wraithwood_Seer"]
Crystal_Vanguard: ["Conjuror", "Zealot"]
Zealot: ["The_Blessed", "Primal_Shifter"]
Wraithwood_Seer: ["Primal_Shifter", "Crystal_Vanguard"]
Primal_Shifter: ["Conjuror", "The_Blessed"]
The_Blessed: ["Crystal_Vanguard", "Wraithwood_Seer"]
AI Behavior Patterns¶
Personality Types¶
Aggressive:
attack_priority: 0.8
defense_priority: 0.2
risk_taking: 0.7
Defensive:
attack_priority: 0.3
defense_priority: 0.8
risk_taking: 0.2
Balanced:
attack_priority: 0.5
defense_priority: 0.5
risk_taking: 0.5
Strategic:
attack_priority: 0.6
defense_priority: 0.6
risk_taking: 0.4
Learning Parameters¶
Adaptation:
rate: 0.1
window_size: 10
metrics:
- player_health
- damage_dealt
- survival_time
- objective_completion
Pattern_Recognition:
features:
- action_sequences
- resource_management
- positioning
- target_selection
Response_Adjustment:
confidence_threshold: 0.7
exploration_rate: 0.2
memory_length: 50
Testing Requirements¶
Unit Tests¶
Coverage:
server: ">= 80%"
client: ">= 75%"
ai: ">= 85%"
Critical_Paths:
- State management
- Action validation
- AI decisions
- Network handling
Integration Tests¶
Scenarios:
- Full game flow
- AI adaptation
- Network resilience
- State synchronization
Performance_Tests:
- Response times
- Memory usage
- Concurrent games
- Hardware utilization
User Acceptance¶
Criteria:
- Response time feels instant
- AI behavior feels natural
- UI is intuitive
- Game is engaging
Metrics:
- User session length
- Return rate
- Completion rate
- Difficulty satisfaction
Development Workflow¶
Feature Implementation¶
Steps:
1: Review specifications
2: Update documentation
3: Implement tests
4: Develop feature
5: Validate performance
6: Update AI index
Validation:
- Performance requirements
- API consistency
- Documentation alignment
- Test coverage
Code Review Process¶
Checklist:
- Documentation updated
- Tests added
- Performance validated
- API consistency
- Error handling
- Security checks
Priority:
critical:
- State management
- AI behavior
- Network code
high:
- UI components
- Game logic
- Data handling
Security Considerations¶
Data Protection¶
Sensitive_Data:
- Player credentials
- Game statistics
- AI training data
- Performance metrics
Encryption:
websocket: "TLS 1.3"
storage: "AES-256"
api: "HTTPS only"
Access Control¶
Authentication:
method: "JWT"
expiry: "24h"
refresh: true
Authorization:
roles:
- player
- admin
- system
scope_based: true
Error Recovery¶
Failure Modes¶
Network:
- Connection loss
- High latency
- Packet loss
- State desync
Hardware:
- Memory exhaustion
- CPU throttling
- Storage limits
- Temperature limits
Recovery:
- State restoration
- Graceful degradation
- Auto-reconnect
- Data consistency
Monitoring¶
Metrics:
- Response times
- Error rates
- Resource usage
- User engagement
Alerts:
performance:
ai_response: "> 100ms"
server_update: "> 50ms"
client_frame: "> 16ms"
hardware:
memory: "> 80%"
cpu: "> 80%"
temperature: "> 80°C"
Quick Reference¶
Critical Limits¶
AI:
response: 100ms
memory: 512MB
difficulty: [0.2, 0.95]
Server:
updates: 50ms
memory: 512MB
concurrent: 4
Client:
frames: 16ms
memory: 256MB