# jxsh341/artificial-learning-system architecture

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

- Interactive diagram: https://gitdiagram.com/jxsh341/artificial-learning-system
- Repository: https://github.com/jxsh341/artificial-learning-system

## Overview

Artificial Learning System is a research platform for controlled experiments on hybrid graph-and-temporal neural models. The main workflow is to prepare graph tasks, run cue-learning or graph-classification episodes through an environment and trainer, then evaluate learning, retention, reversal, generalization, and state-mediated computation. Experiments also probe ablations and state-to-readout coupling. The graph preserves the documented benchmark and diagnostic branches; some runner relationships are supported by the source index rather than inspected implementation excerpts.

Main entry points: [`src/artificial_system/data/schema.py`](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/schema.py) (GraphData interface), [`src/artificial_system/evaluation/graph_classification.py`](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/graph_classification.py) (Graph classification probes), [`src/artificial_system/experiments/runner.py`](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/experiments/runner.py) (Experiment runner), [`src/artificial_system/models/gnn_ssm.py`](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/gnn_ssm.py) (Hybrid model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Graph data"]
  node_adapters["Data adapters<br/>[adapters.py]"]
  node_graph_tasks["Graph task generation<br/>[graph_tasks.py]"]
  node_schema["GraphData interface<br/>[schema.py]"]
  node_perturbations["Graph perturbations<br/>[perturbations.py]"]
end

subgraph group_tasks["Task environments"]
  node_cue_env["Cue environment<br/>[cue_environment.py]"]
  node_graph_env["Graph environment"]
end

subgraph group_model["Hybrid model"]
  node_gnn["GNN encoder<br/>[gnn.py]"]
  node_ssm["State-space model<br/>[ssm.py]"]
  node_readout["Pooling and readout<br/>[readout.py]"]
  node_hybrid["Hybrid model<br/>[gnn_ssm.py]"]
end

subgraph group_runtime["Training and experiments"]
  node_trainer["Episode trainer<br/>[trainer.py]"]
  node_losses["Training losses<br/>[losses.py]"]
  node_runner["Experiment runner<br/>[runner.py]"]
end

subgraph group_analysis["Evaluation and diagnostics"]
  node_arrg["Cue-task evaluation<br/>[metrics.py]"]
  node_graph_eval["Graph classification probes"]
  node_state_content["State-content analysis<br/>[state_content.py]"]
  node_geometry["Readout geometry"]
  node_coupling["Coupling experiments<br/>[coupling_rescue.py]"]
  node_oscillation["Oscillation diagnostics"]
  node_state_budget["State-budget experiments"]
end

node_researcher(("Researcher"))

node_researcher -.->|"configures runs"| node_runner
node_adapters -->|"creates data"| node_schema
node_graph_tasks -->|"builds graphs"| node_schema
node_perturbations -->|"transforms graphs"| node_schema
node_cue_env -->|"emits observations"| node_schema
node_graph_env -->|"uses datasets"| node_graph_tasks
node_graph_env -->|"emits observations"| node_schema
node_gnn -->|"encodes graphs"| node_schema
node_hybrid -->|"encodes nodes"| node_gnn
node_hybrid -->|"pools and predicts"| node_readout
node_hybrid -->|"updates state"| node_ssm
node_hybrid -->|"accepts GraphData"| node_schema
node_trainer -->|"resets environment"| node_graph_env
node_trainer -->|"steps model"| node_hybrid
node_trainer -->|"computes loss"| node_losses
node_runner -->|"configures benchmark"| node_cue_env
node_runner -->|"configures benchmark"| node_graph_env
node_runner -->|"runs probes"| node_graph_eval
node_runner -->|"runs measures"| node_arrg
node_graph_eval -->|"evaluates instances"| node_graph_tasks
node_graph_eval -->|"tests controls"| node_perturbations
node_state_content -->|"uses graph probes"| node_graph_eval
node_geometry -->|"analyzes probes"| node_graph_eval
node_coupling -->|"evaluates checkpoints"| node_graph_eval
node_coupling -->|"measures state"| node_state_content
node_oscillation -->|"measures state"| node_state_content
node_oscillation -->|"uses experiments"| node_coupling
node_state_budget -->|"measures state"| node_state_content
node_state_budget -->|"uses experiment tools"| node_coupling

click node_adapters "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/adapters.py"
click node_graph_tasks "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/graph_tasks.py"
click node_schema "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/schema.py"
click node_perturbations "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/perturbations.py"
click node_cue_env "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/environment/cue_environment.py"
click node_graph_env "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/environment/graph_environment.py"
click node_gnn "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/gnn.py"
click node_ssm "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/ssm.py"
click node_readout "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/readout.py"
click node_hybrid "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/gnn_ssm.py"
click node_trainer "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/training/trainer.py"
click node_losses "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/training/losses.py"
click node_runner "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/experiments/runner.py"
click node_arrg "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/metrics.py"
click node_graph_eval "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/graph_classification.py"
click node_state_content "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/state_content.py"
click node_geometry "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/readout_geometry.py"
click node_coupling "https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/experiments/coupling_rescue.py"
click node_oscillation "https://github.com/jxsh341/artificial-learning-system/blob/main/scripts/run_oscillation_mechanism.py"
click node_state_budget "https://github.com/jxsh341/artificial-learning-system/blob/main/scripts/run_state_budget.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_adapters,node_graph_tasks,node_schema,node_perturbations toneBlue
class node_cue_env,node_graph_env toneAmber
class node_gnn,node_ssm,node_readout,node_hybrid toneMint
class node_trainer,node_losses,node_runner toneRose
class node_arrg,node_graph_eval,node_state_content,node_geometry,node_coupling,node_oscillation,node_state_budget,node_researcher toneIndigo
```

## Components

### Graph data

- [Data adapters](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/adapters.py): `src/artificial_system/data/adapters.py`
- [Graph task generation](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/graph_tasks.py): `src/artificial_system/data/graph_tasks.py`
- [GraphData interface](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/schema.py): `src/artificial_system/data/schema.py`
- [Graph perturbations](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/data/perturbations.py): `src/artificial_system/data/perturbations.py`

### Task environments

- [Cue environment](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/environment/cue_environment.py): `src/artificial_system/environment/cue_environment.py`
- [Graph environment](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/environment/graph_environment.py): `src/artificial_system/environment/graph_environment.py`

### Hybrid model

- [GNN encoder](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/gnn.py): `src/artificial_system/models/gnn.py`
- [State-space model](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/ssm.py): `src/artificial_system/models/ssm.py`
- [Pooling and readout](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/readout.py): `src/artificial_system/models/readout.py`
- [Hybrid model](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/models/gnn_ssm.py): `src/artificial_system/models/gnn_ssm.py`

### Training and experiments

- [Episode trainer](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/training/trainer.py): `src/artificial_system/training/trainer.py`
- [Training losses](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/training/losses.py): `src/artificial_system/training/losses.py`
- [Experiment runner](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/experiments/runner.py): `src/artificial_system/experiments/runner.py`

### Evaluation and diagnostics

- [Cue-task evaluation](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/metrics.py): `src/artificial_system/evaluation/metrics.py`
- [Graph classification probes](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/graph_classification.py): `src/artificial_system/evaluation/graph_classification.py`
- [State-content analysis](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/state_content.py): `src/artificial_system/evaluation/state_content.py`
- [Readout geometry](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/evaluation/readout_geometry.py): `src/artificial_system/evaluation/readout_geometry.py`
- [Coupling experiments](https://github.com/jxsh341/artificial-learning-system/blob/main/src/artificial_system/experiments/coupling_rescue.py): `src/artificial_system/experiments/coupling_rescue.py`
- [Oscillation diagnostics](https://github.com/jxsh341/artificial-learning-system/blob/main/scripts/run_oscillation_mechanism.py): `scripts/run_oscillation_mechanism.py`
- [State-budget experiments](https://github.com/jxsh341/artificial-learning-system/blob/main/scripts/run_state_budget.py): `scripts/run_state_budget.py`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment runner: configures runs
- Data adapters → GraphData interface: creates data (evidence: `src/artificial_system/data/adapters.py`)
- Graph task generation → GraphData interface: builds graphs (evidence: `src/artificial_system/data/graph_tasks.py`)
- Graph perturbations → GraphData interface: transforms graphs (evidence: `src/artificial_system/data/perturbations.py`)
- Cue environment → GraphData interface: emits observations (evidence: `src/artificial_system/environment/cue_environment.py`)
- Graph environment → Graph task generation: uses datasets (evidence: `src/artificial_system/environment/graph_environment.py`)
- Graph environment → GraphData interface: emits observations (evidence: `src/artificial_system/environment/graph_environment.py`)
- GNN encoder → GraphData interface: encodes graphs (evidence: `src/artificial_system/models/gnn.py`)
- Hybrid model → GNN encoder: encodes nodes (evidence: `src/artificial_system/models/gnn_ssm.py`)
- Hybrid model → Pooling and readout: pools and predicts (evidence: `src/artificial_system/models/gnn_ssm.py`)
- Hybrid model → State-space model: updates state (evidence: `src/artificial_system/models/gnn_ssm.py`)
- Hybrid model → GraphData interface: accepts GraphData (evidence: `src/artificial_system/models/gnn_ssm.py`)
- Episode trainer → Graph environment: resets environment (evidence: `src/artificial_system/training/trainer.py`)
- Episode trainer → Hybrid model: steps model (evidence: `src/artificial_system/training/trainer.py`)
- Episode trainer → Training losses: computes loss (evidence: `src/artificial_system/training/trainer.py`)
- Experiment runner → Cue environment: configures benchmark (evidence: `src/artificial_system/experiments/runner.py`)
- Experiment runner → Graph environment: configures benchmark (evidence: `src/artificial_system/experiments/runner.py`)
- Experiment runner → Graph classification probes: runs probes (evidence: `src/artificial_system/experiments/runner.py`)
- Experiment runner → Cue-task evaluation: runs measures (evidence: `src/artificial_system/experiments/runner.py`)
- Graph classification probes → Graph task generation: evaluates instances (evidence: `src/artificial_system/evaluation/graph_classification.py`)
- Graph classification probes → Graph perturbations: tests controls (evidence: `src/artificial_system/evaluation/graph_classification.py`)
- State-content analysis → Graph classification probes: uses graph probes (evidence: `src/artificial_system/evaluation/state_content.py`)
- Readout geometry → Graph classification probes: analyzes probes (evidence: `src/artificial_system/evaluation/readout_geometry.py`)
- Coupling experiments → Graph classification probes: evaluates checkpoints (evidence: `src/artificial_system/experiments/coupling_rescue.py`)
- Coupling experiments → State-content analysis: measures state (evidence: `src/artificial_system/experiments/coupling_rescue.py`)
- Oscillation diagnostics → State-content analysis: measures state (evidence: `scripts/run_oscillation_mechanism.py`)
- Oscillation diagnostics → Coupling experiments: uses experiments (evidence: `scripts/run_oscillation_mechanism.py`)
- State-budget experiments → State-content analysis: measures state (evidence: `scripts/run_state_budget.py`)
- State-budget experiments → Coupling experiments: uses experiment tools (evidence: `scripts/run_state_budget.py`)
