Mornings,

am I right? ☕

For humans, a morning routine is a hazy blur of muscle memory, automated movements, and making sure you grab your keys before the front door clicks shut.

For an AI agent, it is a high-horizon control-loop minefield. Navigating four disconnected 2D matrix coordinate spaces, enforcing strict behavioral dependencies (no, you cannot dry off with a towel if you haven't taken a shower), reading dynamic external meteorological variables, and handling room-to-room transitions without trapping yourself in an infinite doorway-shuffling loop is a rigorous challenge of system stability.

This repository implements an optimized, production-grade LLM Control Harness that places an agent into a virtual household grid, successfully completing an intricate 19-stage routine from bed spawn to vehicle departure in a flawless 102-step trajectory.

---

🏗️ Architectural Topology

The control framework decouples environmental constraints from cognitive processing loop latency to maximize processing speed and system reliability:

• Cognitive Task Layer: Leverages live semantic LLM inference (llama-3.1-8b-instant via Groq) exclusively at milestone target coordinates (e.g., verifying weather bounds, slicing ingredients, changing clothing variables).
• The Reflexive Pathing Layer: Short-circuits trivial, tile-by-tile coordinate adjustments (move left, move up) using a local Breadth-First Search (BFS) grid matrix pathfinder ($O(V + E)$).
• Encapsulated Sub-Grids: Four completely decoupled room modules (BedroomModule, BathroomModule, KitchenModule, LivingRoomModule) that independently act as isolated coordinate-bound state machines.

---

⚙️ Quick Start & Execution

1. Environment & Dependencies

This framework requires a local runtime environment of Python 3.10+.

# Instantiate and enter the virtual environment shell
python3 -m venv venv
source venv/bin/activate

# Install required core packages
pip install -r requirements.txt

2. Infrastructure Configuration

Configure your API credentials inside a root .env container file:

GROQ_API_KEY=gsk_your_secured_api_key_signature

Note: An integrated local heuristic engine functions automatically if no live key string is detected, guaranteeing offline verification and testing stability.

3. Orchestration Boot

Initiate the continuous execution loop to monitor real-time pathfinding, action dispatches, and room state-machine transitions:

python3 main.py

4. Tests

Execute the test matrix containing 26 complete integration, boundary, and state-validation checks:

pytest -v