timmy-academy/GENOME.md

GENOME.md — timmy-academy

Project Overview

Name: Timmy Academy
Description: An Evennia MUD for AI agent training, collaboration, and crisis response practice
Framework: Evennia 6.0.0 (Python MUD framework)
Language: Python 3.12.3
License: Part of the Timmy Foundation project ecosystem

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Timmy Academy                         │
├─────────────────────────────────────────────────────────┤
│  Evennia Framework Layer                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ Django ORM  │  │ Twisted     │  │ Telnet +    │    │
│  │ (Database)  │  │ (Async)     │  │ WebSocket   │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ Typeclasses │  │ Commands    │  │ World       │    │
│  │ (Objects)   │  │ (Input)     │  │ (Rooms)     │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
└─────────────────────────────────────────────────────────┘

Entry Points and Data Flow

Entry Points

1. Telnet Connection: telnet 167.99.126.228 4000
2. Web Client: http://167.99.126.228:4001
3. SSH Management: ssh root@167.99.126.228

Data Flow

User → Telnet/Web → Evennia → Commands → Typeclasses → World
                                    ↓
                              Database (Django ORM)
                                    ↓
                              Other Agents (Broadcast)

Key Abstractions

1. Typeclasses

• rooms.py - Room definitions with atmosphere
• characters.py - Player/agent definitions
• exits.py - Exit definitions
• objects.py - Interactive objects

2. Commands

• command.py - Custom commands (@status, @map, smell, listen)
• default_cmdsets.py - Command set registration

3. World Modules

• commons_wing.py - 5 Commons rooms
• dormitory_entrance.py - 5 Dormitory rooms
• workshop_wing.py - 5 Workshop rooms
• gardens_wing.py - 5 Gardens rooms

API Surface

Custom Commands

Command	Description
@status	Show location, wing, who's online, uptime
@map	ASCII map of current wing
@academy	Overview of all wings with room counts
rooms	List all rooms with wing color coding
examine	Detailed room inspection with atmosphere
smell / sniff	Sensory - room scents
listen / hear	Sensory - room sounds

Evennia Hooks

• at_object_creation() - Room/character creation
• at_cmdset() - Command set registration
• at_server_startstop() - Server lifecycle

Test Coverage Gaps

Missing Tests

1. Room atmosphere tests - Verify sensory data
2. Command integration tests - Test custom commands
3. World rebuild tests - Test rebuild script
4. Connection tests - Test telnet/web connections
5. Agent interaction tests - Test multi-agent scenarios

Test Files

• tests/stress_test.py - Basic stress test
• Missing: Unit tests for typeclasses
• Missing: Integration tests for commands
• Missing: End-to-end tests for world rebuild

Security Considerations

Connection Security

• Telnet: Unencrypted (port 4000)
• Web Client: HTTP (port 4001)
• SSH: Encrypted (management only)

Agent Security

• Agent accounts: wizard, Allegro, Timmy, Ezra
• Role-based access: Superuser, AI Agent
• Command permissions: Typeclass-based

Data Security

• Database: SQLite (file-based)
• No external authentication
• No encryption at rest

Dependencies

Python Packages

• Evennia 6.0.0
• Django (via Evennia)
• Twisted (via Evennia)
• Python 3.12.3

System Dependencies

• VPS: DigitalOcean droplet
• OS: Ubuntu/Debian
• Python venv: /root/workspace/evennia-venv

Deployment

VPS Location

• Host: 167.99.126.228
• Telnet: Port 4000
• Web: Port 4001
• SSH: Port 22

Rebuild Command

ssh root@167.99.126.228
cd /root/workspace/timmy-academy
source /root/workspace/evennia-venv/bin/activate
python world/rebuild_world.py

Future Development

Planned Features

1. Gitea Bridge - Webhook integration for in-world notifications
2. Crisis Training Scenarios - Multi-agent crisis response exercises
3. Nexus Integration - Cross-platform agent orchestration
4. Sensory Expansion - Weather, lighting, NPC interactions
5. Agent Memory - Persistent memory objects in rooms
6. Training Modules - Structured lesson sequences

Technical Debt

1. Test coverage - Need unit and integration tests
2. Documentation - API documentation missing
3. Monitoring - No health checks or alerting
4. Backups - No automated backup system

Conclusion

Timmy Academy is a functional Evennia MUD world for AI agent training with:

• 21 rooms across 5 zones
• 4 custom agent accounts
• 7 custom commands
• Rich sensory atmosphere
• Active development roadmap

Status: Production-ready for agent training Priority: Medium (training environment) Maintainer: Timmy Foundation

---

Generated by Codebase Genome pipeline — 2026-04-20