703e095ba6
- Generate GENOME.md for timmy-academy - Add complete codebase analysis - Include architecture, API surface, and test coverage Addresses issue #678: Codebase Genome: timmy-academy — Full Analysis GENOME.md includes: - Project overview and architecture - Entry points and data flow - Key abstractions - API surface and commands - Test coverage gaps - Security considerations - Dependencies and deployment - Future development plans Repository: Timmy_Foundation/timmy-academy Description: Evennia MUD world for agent training and crisis response
172 lines
5.9 KiB
Markdown
172 lines
5.9 KiB
Markdown
# 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
|
|
```bash
|
|
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* |