# nolane-x/nolane-hira architecture

> Architecture diagram of the GitHub repository nolane-x/nolane-hira, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nolane-x/nolane-hira
- Repository: https://github.com/nolane-x/nolane-hira

## Overview

Nolane HIRA is a research-first, non-autoregressive typed decision engine. Its documented workflow encodes a state once, compiles or reuses a decision schema, scores all logical options while preserving full-option probability mass, and refines uncertain options with a relation core. OOD authority and held-out calibration are explicit safeguards. The tree also shows research branches for typed, semantic, compositional, and transfer decisions, alongside structural and trust-region methods. Runtime wiring beyond the README’s stated design is uncertain; those links are omitted where the excerpts do not establish callers.

Main entry points: [`src/nmd/runtime.py`](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/runtime.py) (Decision runtime), [`src/nmd/semantic.py`](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/semantic.py) (Semantic encoding), [`src/nmd/schema.py`](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/schema.py) (Decision schemas), [`src/nmd/contracts.py`](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/contracts.py) (Option contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_decision["Decision workflow"]
  node_runtime["Decision runtime<br/>[runtime.py]"]
  node_schema["Decision schemas<br/>[schema.py]"]
  node_output["Typed decisions<br/>[typed_decisions.py]"]
  node_contracts["Option contracts<br/>[contracts.py]"]
end

subgraph group_model["Decision model"]
  node_semantic["Semantic encoding<br/>[semantic.py]"]
  node_sparse["Coarse scoring<br/>[sparse.py]"]
  node_competitive["Option competition<br/>[competitive.py]"]
  node_relation["Relation core<br/>[relation_cache.py]"]
end

subgraph group_trust["Reliability controls"]
  node_ood["OOD authority<br/>[ood.py]"]
  node_calibration["Calibration<br/>[calibration.py]"]
end

subgraph group_research["Research capabilities"]
  node_factorized["Factorized decisions<br/>[factorized.py]"]
  node_semantic_alignment["Semantic alignment"]
  node_semantic_transfer["Semantic transfer"]
  node_composition["Latent composition"]
  node_structure["Structural methods<br/>[structural.py]"]
  node_trust_region["Functional trust"]
end

node_user(("Requesting client"))

node_user -->|"submits request"| node_runtime
node_runtime -->|"compiles or reuses"| node_schema
node_runtime -->|"encodes state"| node_semantic
node_runtime -->|"scores options"| node_sparse
node_runtime -->|"preserves option mass"| node_competitive
node_runtime -->|"refines uncertainty"| node_relation
node_runtime -->|"checks OOD"| node_ood
node_runtime -->|"applies calibration"| node_calibration
node_runtime -->|"returns decisions"| node_output
node_contracts -->|"defines options"| node_schema
node_semantic_alignment -.->|"aligns representations"| node_semantic
node_semantic_transfer -.->|"transfers representations"| node_semantic
node_composition -.->|"composes decisions"| node_factorized
node_structure -.->|"supports repair research"| node_trust_region

click node_runtime "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/runtime.py"
click node_schema "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/schema.py"
click node_semantic "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/semantic.py"
click node_sparse "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/sparse.py"
click node_competitive "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/competitive.py"
click node_relation "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/relation_cache.py"
click node_output "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/typed_decisions.py"
click node_ood "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/ood.py"
click node_calibration "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/calibration.py"
click node_contracts "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/contracts.py"
click node_factorized "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/factorized.py"
click node_semantic_alignment "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/semantic_alignment_authority.py"
click node_semantic_transfer "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/semantic_transfer_core.py"
click node_composition "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/latent_composition_authority.py"
click node_structure "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/structural.py"
click node_trust_region "https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/functional_trust.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime,node_schema,node_output,node_contracts,node_user toneBlue
class node_semantic,node_sparse,node_competitive,node_relation toneAmber
class node_ood,node_calibration toneMint
class node_factorized,node_semantic_alignment,node_semantic_transfer,node_composition,node_structure,node_trust_region toneRose
```

## Components

### Decision workflow

- [Decision runtime](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/runtime.py): `src/nmd/runtime.py`
- [Decision schemas](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/schema.py): `src/nmd/schema.py`
- [Typed decisions](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/typed_decisions.py): `src/nmd/typed_decisions.py`
- [Option contracts](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/contracts.py): `src/nmd/contracts.py`

### Decision model

- [Semantic encoding](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/semantic.py): `src/nmd/semantic.py`
- [Coarse scoring](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/sparse.py): `src/nmd/sparse.py`
- [Option competition](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/competitive.py): `src/nmd/competitive.py`
- [Relation core](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/relation_cache.py): `src/nmd/relation_cache.py`

### Reliability controls

- [OOD authority](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/ood.py): `src/nmd/ood.py`
- [Calibration](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/calibration.py): `src/nmd/calibration.py`

### Research capabilities

- [Factorized decisions](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/factorized.py): `src/nmd/factorized.py`
- [Semantic alignment](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/semantic_alignment_authority.py): `src/nmd/semantic_alignment_authority.py`
- [Semantic transfer](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/semantic_transfer_core.py): `src/nmd/semantic_transfer_core.py`
- [Latent composition](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/latent_composition_authority.py): `src/nmd/latent_composition_authority.py`
- [Structural methods](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/structural.py): `src/nmd/structural.py`
- [Functional trust](https://github.com/nolane-x/nolane-hira/blob/main/src/nmd/functional_trust.py): `src/nmd/functional_trust.py`

### Other components

- **Requesting client**

## Connections

- Requesting client → Decision runtime: submits request
- Decision runtime → Decision schemas: compiles or reuses
- Decision runtime → Semantic encoding: encodes state
- Decision runtime → Coarse scoring: scores options
- Decision runtime → Option competition: preserves option mass
- Decision runtime → Relation core: refines uncertainty
- Decision runtime → OOD authority: checks OOD
- Decision runtime → Calibration: applies calibration
- Decision runtime → Typed decisions: returns decisions
- Option contracts → Decision schemas: defines options
- Semantic alignment → Semantic encoding: aligns representations
- Semantic transfer → Semantic encoding: transfers representations
- Latent composition → Factorized decisions: composes decisions
- Structural methods → Functional trust: supports repair research