HTI v0.1 Implementation Guide
This skill helps you implement the HTI (Hierarchical Temporal Intelligence) v0.1 demo harness following strict Python implementation guidelines.
What This Skill Does
Guides implementation of a hierarchical temporal control system with:
Multi-band architecture (Semantics, Control, Reflex)Safety shield with intervention loggingDual-output event logging (JSON + console)Strict invariant testingZero external dependencies (stdlib only)Implementation Instructions
1. Environment Constraints
**Python Version:**
Target: Python 3.11Must work on Python 3.10+No Python 3.12+ exclusive featuresType hints: Use `dict[str, float]` (3.10+ style), not `Dict[str, float]`**Dependencies:**
Standard library ONLYNo external packages (no numpy, pandas, pytest plugins)Allowed: `dataclasses`, `time`, `json`, `pathlib`, `unittest`Dev dependency: `pytest` (optional for testing)2. Code Style Requirements
When writing code, enforce:
Simple and readable - prioritize clarity over clevernessExplicit over implicit - make data flows obviousMinimal magic - no metaclasses, descriptors, or advanced decoratorsType hints on all public interfacesBrief docstrings for all public classes and functions3. Event Logging System (Critical)
Implement **dual output** logging:
**JSON Log File (event_log.jsonl):**
Format: JSONL (one event per line)Location: Current working directorySchema: EventPack dataclass as JSONUse `dataclasses.asdict()` + `json.dumps()`Write immediately (no buffering)Example line:
```json
{"timestamp": 0.42, "tick": 42, "band": "SafetyShield", "obs_before": {"x": 0.5, "x_target": 0.8}, "action_proposed": 0.1, "action_final": 0.05, "reason": "clip_out_of_bounds", "metadata": {}}
```
**Console Summary:**
During run: Progress indicatorAfter run: Summary with total events, breakdown by reason, first/last events, timing stats4. File Structure
Enforce this exact structure:
```
hti_v0_demo/
__init__.py
env.py # ToyEnv class
shared_state.py # SharedState, SemanticsAdvice, ReflexFlags
event_log.py # EventPack, EventLogger classes
bands/
__init__.py
semantics.py # SemanticsBand
control.py # ControlBand
reflex.py # ReflexBand
shield.py # SafetyShield
scheduler.py # run_episode() and TimingStats
run_demo.py # main entry point
tests/
test_invariants.py # All invariant tests
```
5. Implementation Order
Follow this sequence to minimize rework:
1. Data structures (`shared_state.py`, `event_log.py`)
2. Environment (`env.py`)
3. Bands (`bands/*.py`) - stub logic initially
4. Shield (`shield.py`) - core safety logic
5. Scheduler (`scheduler.py`)
6. Tests (`tests/test_invariants.py`)
7. Demo runner (`run_demo.py`)
8. Refine band logic
6. Critical Pitfalls to Avoid
**Never:**
Let bands maintain internal state (must be pure functions of SharedState)Use wall-clock time for control flow (use `state.tick` and `state.t`)Make Shield optional (must always run)Buffer event logs (write immediately for crash preservation)Over-engineer (this is a demo)7. Testing Requirements
Write tests matching concrete examples from SPEC.mdUse simple assertions, no complex fixturesEach test runnable independentlyTests must be deterministic (seed any randomness)All tests in `test_invariants.py` must pass8. Success Criteria
Implementation complete when:
`python -m hti_v0_demo.run_demo` runs without errorsConsole shows human-readable summary with timing stats`event_log.jsonl` contains valid JSON linesAll tests in `test_invariants.py` passCode works on Python 3.10 and 3.11Usage Examples
**Example 1: Starting implementation**
User: "Help me implement HTI v0.1"
Create file structureImplement data structures firstAdd type hints to all classesEnsure Python 3.10+ compatibility**Example 2: Reviewing event logging**
User: "Review my event logger"
Check for JSONL format (one event per line)Verify immediate writing (no buffering)Ensure console summary is implementedValidate EventPack schema matches spec**Example 3: Adding a new band**
User: "Add a new control band"
Ensure it's a pure function of SharedStateNo internal state allowedAdd type hintsPlace in `bands/` directoryAdd timing instrumentationImportant Notes
This is safety-critical code - Shield must ALWAYS runRefer to SPEC.md for architecture details (this skill covers Python implementation only)When ambiguous, choose: "Simplest thing that demonstrates the pattern"Event logs must survive crashes - write immediatelyNo external dependencies means truly ZERO - not even pytest in production