Minecraft Agent Skeleton

This repository contains the phase-one engineering skeleton for a Minecraft agent project. The current scope is limited to project structure, module boundaries, schemas, abstract interfaces, CLI entry points, configuration files, and test scaffolding.

No core algorithm, training logic, prediction logic, or business logic is implemented in this phase.

Module Boundaries

• common: shared schemas, protocols, configuration loading, logging, exceptions, and reusable types.
• vision: vision-side contracts and placeholders for dataset, model, training, evaluation, and prediction.
• language: language-side contracts and placeholders for parsing, dataset, model, training, and evaluation.
• fusion: contracts for combining vision and language outputs into a shared decision representation.
• demo: orchestration-only entry points that wire modules together without embedding business logic.
• tools: utility CLI and helper scripts for data conversion and sample generation.
• tests: contract-oriented tests for schemas, interfaces, CLI wiring, and demo composition.

How Modules Connect

All modules communicate through explicit schemas and protocols defined under src/common/.

• Request and response payloads use dataclasses in src/common/schemas/.
• Cross-module dependencies use abstract base classes and protocols from src/common/protocols/.
• Module implementations should depend on shared schemas, not on another module's private internals.

Directory Tree

minecraft/
├─ README.md
├─ pyproject.toml
├─ pytest.ini
├─ .gitignore
├─ AGENT.md
├─ configs/
├─ docs/
├─ data/
├─ examples/
├─ src/
│  ├─ common/
│  ├─ vision/
│  ├─ language/
│  ├─ fusion/
│  ├─ demo/
│  └─ tools/
└─ tests/

Phase-One Deliverables

• project structure and module directories
• configuration files
• schema definitions
• abstract interfaces and placeholder services
• CLI skeleton
• test skeleton
• architecture and dataset documentation

Later Integration

Future implementation work should follow these rules:

1. Replace placeholder classes with concrete implementations behind existing interfaces.
2. Keep schema compatibility stable across module boundaries.
3. Add training and prediction internals inside the existing module files or adjacent implementation packages.
4. Extend CLI commands without bypassing shared configuration and schemas.

Placeholder Policy

Files such as model.py, train.py, eval.py, predict.py, service.py, and strategy.py intentionally contain only:

• interface definitions
• docstrings
• TODO markers
• raise NotImplementedError

Minimal Validation

After creating the skeleton, the repository should support:

python -m src.common.cli --help
pytest