# harqer/iq architecture

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

- Interactive diagram: https://gitdiagram.com/harqer/iq
- Repository: https://github.com/harqer/iq

## Overview

IQ is an experimental hybrid reasoning language model, with a separate agent harness and a canonical weight-transfer package. Its main runtime path combines token-time Mamba state mixing, long-context attention, routed experts, and depth residuals, then supports multimodal input and optional iterative reasoning before language-model output and MTP. Transfer remaps donor capabilities into an IQ checkpoint; training and the harness provide adjacent workflows. Edges are limited to relationships stated in the README or visible in the supplied source index and excerpts; unsampled internals are not inferred.

Main entry points: [`iq_model/hybrid.py`](https://github.com/harqer/iq/blob/main/iq_model/hybrid.py) (Hybrid Backbone), [`iq_harness/runtime.py`](https://github.com/harqer/iq/blob/main/iq_harness/runtime.py) (Agent Runtime), [`iq_transfer/complete_transplant.py`](https://github.com/harqer/iq/blob/main/iq_transfer/complete_transplant.py) (Weight Transfer), [`iq_model/model.py`](https://github.com/harqer/iq/blob/main/iq_model/model.py) (IQ Language Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backbone["Hybrid Backbone"]
  node_iq_model["IQ Language Model<br/>[model.py]"]
  node_hybrid["Hybrid Backbone<br/>[hybrid.py]"]
  node_mamba["Mamba-3 MIMO<br/>[mamba3.py]"]
  node_context["CSA/HCA Context<br/>[compressed.py]"]
  node_dense_context["Dense Attention Control<br/>[context_dense.py]"]
  node_latent_moe["Stable LatentMoE<br/>[latent_moe.py]"]
  node_situ["SiTU Activation<br/>[situ.py]"]
  node_attnres["Block AttnRes<br/>[attnres.py]"]
  node_mhc["mHC Ablation<br/>[mhc.py]"]
  node_multimodal["Multimodal Pathway<br/>[multimodal.py]"]
end

subgraph group_reasoning["Reasoning and Output"]
  node_recurrence["Reasoning Recurrence<br/>[recurrence.py]"]
  node_verifier["Reasoning Verifier<br/>[verifier.py]"]
  node_critic["Energy Critic<br/>[critic.py]"]
  node_mtp["MTP Objective<br/>[mtp.py]"]
end

subgraph group_transfer["Weight Transfer"]
  node_mamba_donor["Mamba Checkpoint"]
  node_glm_donor["GLM-5.3 Weights"]
  node_transfer["Weight Transfer"]
  node_mamba_transport["Mamba Widening<br/>[mamba3_direct.py]"]
  node_glm_transport["GLM Remapping<br/>[glm53.py]"]
  node_checkpoint["IQ Checkpoint"]
end

subgraph group_runtime["Training and Harness"]
  node_training["Pretraining<br/>[pretraining.py]"]
  node_harness["Agent Runtime<br/>[runtime.py]"]
  node_session[("Conversation Session<br/>[session.py]")]
  node_skills["Agent Skills<br/>[skills.py]"]
  node_tools["Agent Tools<br/>[tools.py]"]
  node_model_adapter["Model Adapter<br/>[model.py]"]
end

node_user(("Model User"))
node_harness_user(("Agent User"))

node_user -->|"requests generation"| node_iq_model
node_iq_model -->|"runs backbone"| node_hybrid
node_hybrid -->|"mixes token states"| node_mamba
node_hybrid -->|"addresses long context"| node_context
node_hybrid -->|"routes experts"| node_latent_moe
node_latent_moe -->|"uses activation"| node_situ
node_hybrid -->|"mixes depth residuals"| node_attnres
node_hybrid -.->|"retains ablation"| node_mhc
node_hybrid -.->|"offers control path"| node_dense_context
node_hybrid -->|"accepts visual input"| node_multimodal
node_multimodal -->|"processes visual stream"| node_mamba
node_hybrid -->|"refines reasoning state"| node_recurrence
node_recurrence -.->|"may request evidence"| node_verifier
node_verifier -.->|"supports EBM backend"| node_critic
node_hybrid -->|"predicts future tokens"| node_mtp
node_mamba_donor -->|"supplies foundation"| node_mamba_transport
node_glm_donor -->|"supplies capabilities"| node_glm_transport
node_mamba_transport -->|"widens weights"| node_transfer
node_glm_transport -->|"remaps capabilities"| node_transfer
node_transfer -->|"assembles checkpoint"| node_checkpoint
node_checkpoint -.->|"provides model weights"| node_training
node_harness_user -->|"starts agent run"| node_harness
node_harness -->|"loads and appends"| node_session
node_harness -->|"uses skills"| node_skills
node_harness -->|"dispatches tools"| node_tools
node_harness -->|"requests model turn"| node_model_adapter

click node_iq_model "https://github.com/harqer/iq/blob/main/iq_model/model.py"
click node_hybrid "https://github.com/harqer/iq/blob/main/iq_model/hybrid.py"
click node_mamba "https://github.com/harqer/iq/blob/main/iq_model/state/mamba3.py"
click node_context "https://github.com/harqer/iq/blob/main/iq_model/attention/compressed.py"
click node_dense_context "https://github.com/harqer/iq/blob/main/iq_model/attention/context_dense.py"
click node_latent_moe "https://github.com/harqer/iq/blob/main/iq_model/mlp/latent_moe.py"
click node_situ "https://github.com/harqer/iq/blob/main/iq_model/mlp/situ.py"
click node_attnres "https://github.com/harqer/iq/blob/main/iq_model/residual/attnres.py"
click node_mhc "https://github.com/harqer/iq/blob/main/iq_model/residual/mhc.py"
click node_multimodal "https://github.com/harqer/iq/blob/main/iq_model/multimodal.py"
click node_recurrence "https://github.com/harqer/iq/blob/main/iq_model/reasoning/recurrence.py"
click node_verifier "https://github.com/harqer/iq/blob/main/iq_model/reasoning/verifier.py"
click node_critic "https://github.com/harqer/iq/blob/main/iq_model/energy/critic.py"
click node_mtp "https://github.com/harqer/iq/blob/main/iq_model/objectives/mtp.py"
click node_transfer "https://github.com/harqer/iq/blob/main/iq_transfer/complete_transplant.py"
click node_mamba_transport "https://github.com/harqer/iq/blob/main/iq_transfer/mamba3_direct.py"
click node_glm_transport "https://github.com/harqer/iq/blob/main/iq_transfer/glm53.py"
click node_checkpoint "https://github.com/harqer/iq/blob/main/iq_transfer/complete_transplant.py"
click node_training "https://github.com/harqer/iq/blob/main/iq_training/pretraining.py"
click node_harness "https://github.com/harqer/iq/blob/main/iq_harness/runtime.py"
click node_session "https://github.com/harqer/iq/blob/main/iq_harness/session.py"
click node_skills "https://github.com/harqer/iq/blob/main/iq_harness/skills.py"
click node_tools "https://github.com/harqer/iq/blob/main/iq_harness/tools.py"
click node_model_adapter "https://github.com/harqer/iq/blob/main/iq_harness/model.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_iq_model,node_hybrid,node_mamba,node_context,node_dense_context,node_latent_moe,node_situ,node_attnres,node_mhc,node_multimodal,node_user,node_harness_user toneBlue
class node_recurrence,node_verifier,node_critic,node_mtp toneAmber
class node_mamba_donor,node_glm_donor,node_transfer,node_mamba_transport,node_glm_transport,node_checkpoint toneMint
class node_training,node_harness,node_session,node_skills,node_tools,node_model_adapter toneRose
```

## Components

### Hybrid Backbone

- [IQ Language Model](https://github.com/harqer/iq/blob/main/iq_model/model.py): `iq_model/model.py`
- [Hybrid Backbone](https://github.com/harqer/iq/blob/main/iq_model/hybrid.py): `iq_model/hybrid.py`
- [Mamba-3 MIMO](https://github.com/harqer/iq/blob/main/iq_model/state/mamba3.py): `iq_model/state/mamba3.py`
- [CSA/HCA Context](https://github.com/harqer/iq/blob/main/iq_model/attention/compressed.py): `iq_model/attention/compressed.py`
- [Dense Attention Control](https://github.com/harqer/iq/blob/main/iq_model/attention/context_dense.py): `iq_model/attention/context_dense.py`
- [Stable LatentMoE](https://github.com/harqer/iq/blob/main/iq_model/mlp/latent_moe.py): `iq_model/mlp/latent_moe.py`
- [SiTU Activation](https://github.com/harqer/iq/blob/main/iq_model/mlp/situ.py): `iq_model/mlp/situ.py`
- [Block AttnRes](https://github.com/harqer/iq/blob/main/iq_model/residual/attnres.py): `iq_model/residual/attnres.py`
- [mHC Ablation](https://github.com/harqer/iq/blob/main/iq_model/residual/mhc.py): `iq_model/residual/mhc.py`
- [Multimodal Pathway](https://github.com/harqer/iq/blob/main/iq_model/multimodal.py): `iq_model/multimodal.py`

### Reasoning and Output

- [Reasoning Recurrence](https://github.com/harqer/iq/blob/main/iq_model/reasoning/recurrence.py): `iq_model/reasoning/recurrence.py`
- [Reasoning Verifier](https://github.com/harqer/iq/blob/main/iq_model/reasoning/verifier.py): `iq_model/reasoning/verifier.py`
- [Energy Critic](https://github.com/harqer/iq/blob/main/iq_model/energy/critic.py): `iq_model/energy/critic.py`
- [MTP Objective](https://github.com/harqer/iq/blob/main/iq_model/objectives/mtp.py): `iq_model/objectives/mtp.py`

### Weight Transfer

- **Mamba Checkpoint**
- **GLM-5.3 Weights**
- [Weight Transfer](https://github.com/harqer/iq/blob/main/iq_transfer/complete_transplant.py): `iq_transfer/complete_transplant.py`
- [Mamba Widening](https://github.com/harqer/iq/blob/main/iq_transfer/mamba3_direct.py): `iq_transfer/mamba3_direct.py`
- [GLM Remapping](https://github.com/harqer/iq/blob/main/iq_transfer/glm53.py): `iq_transfer/glm53.py`
- [IQ Checkpoint](https://github.com/harqer/iq/blob/main/iq_transfer/complete_transplant.py): `iq_transfer/complete_transplant.py`

### Training and Harness

- [Pretraining](https://github.com/harqer/iq/blob/main/iq_training/pretraining.py): `iq_training/pretraining.py`
- [Agent Runtime](https://github.com/harqer/iq/blob/main/iq_harness/runtime.py): `iq_harness/runtime.py`
- [Conversation Session](https://github.com/harqer/iq/blob/main/iq_harness/session.py): `iq_harness/session.py`
- [Agent Skills](https://github.com/harqer/iq/blob/main/iq_harness/skills.py): `iq_harness/skills.py`
- [Agent Tools](https://github.com/harqer/iq/blob/main/iq_harness/tools.py): `iq_harness/tools.py`
- [Model Adapter](https://github.com/harqer/iq/blob/main/iq_harness/model.py): `iq_harness/model.py`

### Other components

- **Model User**
- **Agent User**

## Connections

- Model User → IQ Language Model: requests generation
- IQ Language Model → Hybrid Backbone: runs backbone
- Hybrid Backbone → Mamba-3 MIMO: mixes token states
- Hybrid Backbone → CSA/HCA Context: addresses long context
- Hybrid Backbone → Stable LatentMoE: routes experts
- Stable LatentMoE → SiTU Activation: uses activation (evidence: `iq_model/mlp/latent_moe.py`)
- Hybrid Backbone → Block AttnRes: mixes depth residuals
- Hybrid Backbone → mHC Ablation: retains ablation
- Hybrid Backbone → Dense Attention Control: offers control path
- Hybrid Backbone → Multimodal Pathway: accepts visual input (evidence: `iq_model/hybrid.py`)
- Multimodal Pathway → Mamba-3 MIMO: processes visual stream
- Hybrid Backbone → Reasoning Recurrence: refines reasoning state
- Reasoning Recurrence → Reasoning Verifier: may request evidence (evidence: `iq_model/reasoning/recurrence.py`)
- Reasoning Verifier → Energy Critic: supports EBM backend (evidence: `iq_model/energy/critic.py`)
- Hybrid Backbone → MTP Objective: predicts future tokens
- Mamba Checkpoint → Mamba Widening: supplies foundation
- GLM-5.3 Weights → GLM Remapping: supplies capabilities
- Mamba Widening → Weight Transfer: widens weights (evidence: `iq_transfer/complete_transplant.py`)
- GLM Remapping → Weight Transfer: remaps capabilities
- Weight Transfer → IQ Checkpoint: assembles checkpoint (evidence: `iq_transfer/complete_transplant.py`)
- IQ Checkpoint → Pretraining: provides model weights
- Agent User → Agent Runtime: starts agent run (evidence: `iq_harness/runtime.py`)
- Agent Runtime → Conversation Session: loads and appends (evidence: `iq_harness/runtime.py`)
- Agent Runtime → Agent Skills: uses skills (evidence: `iq_harness/runtime.py`)
- Agent Runtime → Agent Tools: dispatches tools (evidence: `iq_harness/runtime.py`)
- Agent Runtime → Model Adapter: requests model turn (evidence: `iq_harness/runtime.py`)
