Developer Guide

This chapter is for HABIT contributors and developers building extensions. It is the entry point for understanding HABIT at the architectural and implementation levels. Researchers who only want to use the software should start with Installation.

The chapter follows three stages: understand the system, locate the relevant code, and extend or contribute to the project.

1. Understand HABIT (design and mental model)

• Design Philosophy
  • Research constraints
  • Five design pillars
  • Trade-offs
  • See also
• Core Concepts and Mental Model
  • Global mental model
  • Domain concepts
  • Engineering roles
  • Workflow and Runner
  • Configuration to execution
• Architecture
  • Design principles
  • Layered architecture
  • Configuration-to-execution chain
  • Key components
  • Subsystems
  • CLI-to-core mapping
• Complete Request Lifecycle
  • Seven stages
  • Stage 1: CLI entry
  • Stage 2: command layer
  • Stage 3: loading and validation
  • Stage 4: core API
  • Stage 5: assembly
  • Stage 6: execution
  • Stage 7: artifacts

2. Code organization (where to look)

• Code Map
  • Repository root
  • habit/ package structure
  • Top-level package responsibilities
  • Shared utilities: habit/utils/
  • Cross-subsystem contract files
  • Where to start when changing X
• Configuration System
  • Overview
  • Loading and path resolution
  • Schema layers
  • Parameter registry and validation
  • Domain configurators
  • Summary
• Subsystems
  • Habitat analysis
  • Machine learning

3. Extensions and contributions (how to work)

• Extension and Plugin Guide
  • Core extension contracts
  • Example 1: Custom preprocessing step (ClassRegistry)
  • Example 2: Custom feature selector (CallableRegistry)
  • Example 3: Custom machine-learning model (ModelFactory)
  • Extension point reference
• Invariants and Architecture Contracts
  • Scientific correctness
  • Configuration rules
  • Registry contracts
  • Orchestrator contracts
  • Engineering conventions
  • See also
• Contributor Workflow
  • Environment setup
  • Code conventions
  • Testing
  • Scenario 1: Add a CLI command
  • Scenario 2: Add a configuration-step schema
  • Scenario 3: Web GUI and bridge
• Contributing
  • How to contribute
  • Code style
  • Documentation
  • Development setup
  • Pull requests
  • Code of conduct

Recommended reading order

New to HABIT

1. Design Philosophy — The five design principles and their trade-offs.

2. Core Concepts and Mental Model — Core terminology and the system mental model.

3. Architecture — Layers, configuration assembly, and CLI-to-core mapping.

4. Complete Request Lifecycle — Follow one command through the complete request lifecycle.

Changing the code

5. Code Map — Where each type of code lives and where to start.

6. Configuration System — The YAML → Schema → Configurator → runtime object pipeline.

7. Subsystems — Internal execution flows for habitat analysis and machine learning.

Extending or contributing

8. Extension and Plugin Guide — The eight extension points and their registration mechanisms.

9. Invariants and Architecture Contracts — Rules that must not be broken before changing code.

10. Contributor Workflow — Environment setup, tests, and implementation steps.

11. Contributing — Pull-request and coding conventions.

Note

This chapter focuses on architecture and mechanisms. Complete, copy-ready component templates are available in Customization and Extension Guide.

Environment summary: Python 3.10, pip install -e ., and pytest tests/.

See the Developer sidebar for the API and third-party library references.