# xvado00/aiq architecture

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

- Interactive diagram: https://gitdiagram.com/xvado00/aiq
- Repository: https://github.com/xvado00/aiq

## Overview

AIQ evaluates a chosen agent by running episodes in programs drawn from a reference-machine sample, then estimates performance across strata. The README also documents sample generation, resumable runs, log-based analysis, and several agent families. The graph reflects the sampled runtime code and those documented capabilities; unsampled subsystem links are limited to what the README supports.

Main entry points: [`AIQ.py`](https://github.com/xvado00/aiq/blob/master/AIQ.py) (AIQ runner), [`agents`](https://github.com/xvado00/aiq/tree/master/agents) (Learning agents), [`refmachines/BF.py`](https://github.com/xvado00/aiq/blob/master/refmachines/BF.py) (BF machine), [`agents/Agent.py`](https://github.com/xvado00/aiq/blob/master/agents/Agent.py) (Agent base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_evaluation["AIQ evaluation"]
  node_aiq["AIQ runner<br/>[AIQ.py]"]
  node_resume["Log restoration"]
end

subgraph group_environments["Reference machines"]
  node_refbase["Machine base"]
  node_bf["BF machine<br/>[BF.py]"]
end

subgraph group_agents["Agent implementations"]
  node_agentbase["Agent base<br/>[Agent.py]"]
  node_learning["Learning agents"]
  node_otheragents["Other agents"]
  node_encoder["Observation encoder"]
  node_epsilon["Epsilon decay<br/>[epsilon_decay.py]"]
  node_mc["MC-AIXI wrapper<br/>[MC_AIXI.py]"]
end

subgraph group_analysis["Sampling and analysis"]
  node_sampler["BF sampler<br/>[BF_sampler.py]"]
  node_sample["Program samples"]
  node_logs["Run logs"]
  node_compute["Log analysis<br/>[ComputeFromLog.py]"]
end

node_user(("Evaluator"))
node_mcaixi["mc-aixi executable"]
node_result["AIQ estimate"]

node_user -->|"configures"| node_aiq
node_aiq -->|"constructs agent"| node_agentbase
node_aiq -->|"constructs environment"| node_bf
node_aiq -->|"reads programs"| node_sample
node_aiq -->|"writes results"| node_logs
node_aiq -->|"estimates AIQ"| node_result
node_learning -->|"extends base"| node_agentbase
node_learning -->|"encodes observations"| node_encoder
node_learning -->|"decays exploration"| node_epsilon
node_otheragents -->|"agent interface"| node_agentbase
node_bf -->|"implements"| node_refbase
node_sampler -->|"tests programs"| node_bf
node_sampler -->|"generates samples"| node_sample
node_aiq -->|"loads prior results"| node_resume
node_resume -->|"reads"| node_logs
node_compute -->|"reads"| node_logs
node_compute -->|"reports statistics"| node_result
node_mc -.->|"invokes"| node_mcaixi

click node_aiq "https://github.com/xvado00/aiq/blob/master/AIQ.py"
click node_agentbase "https://github.com/xvado00/aiq/blob/master/agents/Agent.py"
click node_learning "https://github.com/xvado00/aiq/tree/master/agents"
click node_otheragents "https://github.com/xvado00/aiq/tree/master/agents"
click node_encoder "https://github.com/xvado00/aiq/blob/master/agents/utils/observation_encoder.py"
click node_epsilon "https://github.com/xvado00/aiq/blob/master/agents/utils/epsilon_decay.py"
click node_refbase "https://github.com/xvado00/aiq/blob/master/refmachines/ReferenceMachine.py"
click node_bf "https://github.com/xvado00/aiq/blob/master/refmachines/BF.py"
click node_sampler "https://github.com/xvado00/aiq/blob/master/refmachines/BF_sampler.py"
click node_resume "https://github.com/xvado00/aiq/blob/master/AIQ_continue_from_log.py"
click node_compute "https://github.com/xvado00/aiq/blob/master/ComputeFromLog.py"
click node_mc "https://github.com/xvado00/aiq/blob/master/agents/MC_AIXI.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_aiq,node_resume toneBlue
class node_refbase,node_bf toneAmber
class node_agentbase,node_learning,node_otheragents,node_encoder,node_epsilon,node_mc toneMint
class node_sampler,node_sample,node_logs,node_compute toneRose
class node_user,node_mcaixi,node_result toneIndigo
```

## Components

### AIQ evaluation

- [AIQ runner](https://github.com/xvado00/aiq/blob/master/AIQ.py): `AIQ.py`
- [Log restoration](https://github.com/xvado00/aiq/blob/master/AIQ_continue_from_log.py): `AIQ_continue_from_log.py`

### Reference machines

- [Machine base](https://github.com/xvado00/aiq/blob/master/refmachines/ReferenceMachine.py): `refmachines/ReferenceMachine.py`
- [BF machine](https://github.com/xvado00/aiq/blob/master/refmachines/BF.py): `refmachines/BF.py`

### Agent implementations

- [Agent base](https://github.com/xvado00/aiq/blob/master/agents/Agent.py): `agents/Agent.py`
- [Learning agents](https://github.com/xvado00/aiq/tree/master/agents): `agents`
- [Other agents](https://github.com/xvado00/aiq/tree/master/agents): `agents`
- [Observation encoder](https://github.com/xvado00/aiq/blob/master/agents/utils/observation_encoder.py): `agents/utils/observation_encoder.py`
- [Epsilon decay](https://github.com/xvado00/aiq/blob/master/agents/utils/epsilon_decay.py): `agents/utils/epsilon_decay.py`
- [MC-AIXI wrapper](https://github.com/xvado00/aiq/blob/master/agents/MC_AIXI.py): `agents/MC_AIXI.py`

### Sampling and analysis

- [BF sampler](https://github.com/xvado00/aiq/blob/master/refmachines/BF_sampler.py): `refmachines/BF_sampler.py`
- **Program samples**
- **Run logs**
- [Log analysis](https://github.com/xvado00/aiq/blob/master/ComputeFromLog.py): `ComputeFromLog.py`

### Other components

- **Evaluator**
- **mc-aixi executable**
- **AIQ estimate**

## Connections

- Evaluator → AIQ runner: configures
- AIQ runner → Agent base: constructs agent
- AIQ runner → BF machine: constructs environment
- AIQ runner → Program samples: reads programs
- AIQ runner → Run logs: writes results
- AIQ runner → AIQ estimate: estimates AIQ
- Learning agents → Agent base: extends base
- Learning agents → Observation encoder: encodes observations
- Learning agents → Epsilon decay: decays exploration
- Other agents → Agent base: agent interface
- BF machine → Machine base: implements
- BF sampler → BF machine: tests programs
- BF sampler → Program samples: generates samples
- AIQ runner → Log restoration: loads prior results
- Log restoration → Run logs: reads
- Log analysis → Run logs: reads
- Log analysis → AIQ estimate: reports statistics
- MC-AIXI wrapper → mc-aixi executable: invokes