# sup3rus3r/tensor-optix architecture

> Architecture diagram of the GitHub repository sup3rus3r/tensor-optix, 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/sup3rus3r/tensor-optix
- Repository: https://github.com/sup3rus3r/tensor-optix

## Overview

tensor-optix is a reinforcement-learning training-loop framework, with a dataset-driven ML path and optional neuroevolution. Users select or construct an agent, pair it with a pipeline, and run episodes through a controller that learns, evaluates validation performance, adapts hyperparameters, and checkpoints or rolls back weights. The README also documents distributed actor-learning and trial-level Optuna tuning. Excerpts are partial, so links among unsampled components are included only where the README or sampled code establishes their roles; uncertain call wiring is omitted.

Main entry points: [`tensor_optix/core/loop_controller.py`](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/loop_controller.py) (Loop controller), [`tensor_optix/core/base_pipeline.py`](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_pipeline.py) (Pipeline contract), [`tensor_optix/core/base_agent.py`](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_agent.py) (Agent interface), [`tensor_optix/factory.py`](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/factory.py) (Agent factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Setup"]
  node_make_agent["Agent factory<br/>[factory.py]"]
  node_optimizer_facade["Optimizer facade<br/>[optimizer.py]"]
end

subgraph group_training["Training loop"]
  node_loop["Loop controller<br/>[loop_controller.py]"]
  node_pipeline_contract["Pipeline contract<br/>[base_pipeline.py]"]
  node_batch_pipeline["Batch pipeline<br/>[batch_pipeline.py]"]
  node_vector_pipeline["Vector pipeline<br/>[vector_pipeline.py]"]
  node_live_pipeline["Live pipeline<br/>[live_pipeline.py]"]
  node_dataset_pipeline["Dataset pipeline"]
  node_episode_data["Episode data<br/>[types.py]"]
  node_evaluator["Evaluator<br/>[base_evaluator.py]"]
end

subgraph group_agents["Agents and algorithms"]
  node_agent_interface["Agent interface<br/>[base_agent.py]"]
  node_factory_adapters["Framework adapters"]
  node_algorithm_agents["RL algorithms"]
  node_ml_agent["ML agent<br/>[ml_agent.py]"]
end

subgraph group_adaptation["Adaptation and state"]
  node_optimizer["Online optimizer<br/>[base_optimizer.py]"]
  node_scheduler["Backoff scheduler"]
  node_checkpoint[("Checkpoint registry")]
  node_diagnostics["Diagnostic controller"]
  node_policy_manager["Policy manager<br/>[policy_manager.py]"]
  node_meta_controller["Meta controller<br/>[meta_controller.py]"]
end

subgraph group_extensions["Extended capabilities"]
  node_callbacks["Training callbacks"]
  node_neuroevo_agent["Graph agent<br/>[graph_agent.py]"]
  node_neuron_graph["Neuron graph<br/>[neuron_graph.py]"]
  node_topology_controller["Topology controller"]
  node_brain_network["Brain network<br/>[brain_network.py]"]
  node_hebbian["Hebbian hook<br/>[hebbian.py]"]
  node_distributed["Async learner<br/>[async_learner.py]"]
  node_trial_orchestrator["Trial orchestrator<br/>[orchestrator.py]"]
end

node_user(("Training user"))
node_environment(("Environment or stream"))
node_optuna[("Optuna study")]

node_user -->|"selects agent"| node_make_agent
node_user -->|"starts training"| node_optimizer_facade
node_make_agent -->|"constructs"| node_algorithm_agents
node_algorithm_agents -->|"uses framework"| node_factory_adapters
node_algorithm_agents -->|"implements"| node_agent_interface
node_optimizer_facade -->|"configures and runs"| node_loop
node_user -->|"provides environment"| node_batch_pipeline
node_environment -->|"steps"| node_batch_pipeline
node_environment -->|"parallel environments"| node_vector_pipeline
node_environment -->|"streams items"| node_live_pipeline
node_environment -->|"provides batches"| node_dataset_pipeline
node_batch_pipeline -->|"implements"| node_pipeline_contract
node_vector_pipeline -->|"implements"| node_pipeline_contract
node_live_pipeline -->|"implements"| node_pipeline_contract
node_dataset_pipeline -->|"implements"| node_pipeline_contract
node_pipeline_contract -->|"yields"| node_episode_data
node_loop -->|"consumes episodes"| node_pipeline_contract
node_loop -->|"calls learn"| node_agent_interface
node_loop -->|"evaluates performance"| node_evaluator
node_evaluator -->|"reads validation episodes"| node_pipeline_contract
node_loop -->|"updates hyperparameters"| node_optimizer
node_loop -->|"checks convergence state"| node_scheduler
node_loop -->|"saves and restores"| node_checkpoint
node_loop -->|"passes training signals"| node_diagnostics
node_diagnostics -->|"adjusts hyperparameters"| node_agent_interface
node_loop -->|"dispatches lifecycle events"| node_callbacks
node_loop -->|"handles dormant policy"| node_policy_manager
node_policy_manager -->|"requests decision"| node_meta_controller
node_policy_manager -->|"loads best weights"| node_checkpoint
node_make_agent -.->|"optional graph policy"| node_neuroevo_agent
node_neuroevo_agent -->|"uses graph policy"| node_neuron_graph
node_neuroevo_agent -->|"applies learning hook"| node_hebbian
node_loop -.->|"dispatches callback"| node_topology_controller
node_topology_controller -->|"mutates topology"| node_neuron_graph
node_neuron_graph -.->|"composes regions"| node_brain_network
node_user -.->|"requests tuning"| node_trial_orchestrator
node_trial_orchestrator -.->|"runs trial training"| node_loop
node_trial_orchestrator -.->|"reports trial results"| node_optuna
node_distributed -.->|"trains asynchronously"| node_agent_interface

click node_make_agent "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/factory.py"
click node_optimizer_facade "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/optimizer.py"
click node_loop "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/loop_controller.py"
click node_pipeline_contract "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_pipeline.py"
click node_batch_pipeline "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/pipeline/batch_pipeline.py"
click node_vector_pipeline "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/pipeline/vector_pipeline.py"
click node_live_pipeline "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/pipeline/live_pipeline.py"
click node_dataset_pipeline "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/ml/dataset_pipeline.py"
click node_episode_data "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/types.py"
click node_agent_interface "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_agent.py"
click node_factory_adapters "https://github.com/sup3rus3r/tensor-optix/tree/main/tensor_optix/adapters"
click node_algorithm_agents "https://github.com/sup3rus3r/tensor-optix/tree/main/tensor_optix/algorithms"
click node_ml_agent "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/ml/ml_agent.py"
click node_evaluator "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_evaluator.py"
click node_optimizer "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_optimizer.py"
click node_scheduler "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/backoff_scheduler.py"
click node_checkpoint "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/checkpoint_registry.py"
click node_diagnostics "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/diagnostic_controller.py"
click node_policy_manager "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/policy_manager.py"
click node_meta_controller "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/meta_controller.py"
click node_callbacks "https://github.com/sup3rus3r/tensor-optix/tree/main/tensor_optix/callbacks"
click node_neuroevo_agent "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/agent/graph_agent.py"
click node_neuron_graph "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/graph/neuron_graph.py"
click node_topology_controller "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/controller/topology_controller.py"
click node_brain_network "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/brain_network.py"
click node_hebbian "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/hebbian.py"
click node_distributed "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/distributed/async_learner.py"
click node_trial_orchestrator "https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/orchestrator.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_make_agent,node_optimizer_facade,node_user toneBlue
class node_loop,node_pipeline_contract,node_batch_pipeline,node_vector_pipeline,node_live_pipeline,node_dataset_pipeline,node_episode_data,node_evaluator,node_optuna toneAmber
class node_agent_interface,node_factory_adapters,node_algorithm_agents,node_ml_agent toneMint
class node_optimizer,node_scheduler,node_checkpoint,node_diagnostics,node_policy_manager,node_meta_controller toneRose
class node_callbacks,node_neuroevo_agent,node_neuron_graph,node_topology_controller,node_brain_network,node_hebbian,node_distributed,node_trial_orchestrator,node_environment toneIndigo
```

## Components

### Setup

- [Agent factory](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/factory.py): `tensor_optix/factory.py`
- [Optimizer facade](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/optimizer.py): `tensor_optix/optimizer.py`

### Training loop

- [Loop controller](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/loop_controller.py): `tensor_optix/core/loop_controller.py`
- [Pipeline contract](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_pipeline.py): `tensor_optix/core/base_pipeline.py`
- [Batch pipeline](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/pipeline/batch_pipeline.py): `tensor_optix/pipeline/batch_pipeline.py`
- [Vector pipeline](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/pipeline/vector_pipeline.py): `tensor_optix/pipeline/vector_pipeline.py`
- [Live pipeline](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/pipeline/live_pipeline.py): `tensor_optix/pipeline/live_pipeline.py`
- [Dataset pipeline](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/ml/dataset_pipeline.py): `tensor_optix/ml/dataset_pipeline.py`
- [Episode data](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/types.py): `tensor_optix/core/types.py`
- [Evaluator](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_evaluator.py): `tensor_optix/core/base_evaluator.py`

### Agents and algorithms

- [Agent interface](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_agent.py): `tensor_optix/core/base_agent.py`
- [Framework adapters](https://github.com/sup3rus3r/tensor-optix/tree/main/tensor_optix/adapters): `tensor_optix/adapters`
- [RL algorithms](https://github.com/sup3rus3r/tensor-optix/tree/main/tensor_optix/algorithms): `tensor_optix/algorithms`
- [ML agent](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/ml/ml_agent.py): `tensor_optix/ml/ml_agent.py`

### Adaptation and state

- [Online optimizer](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/base_optimizer.py): `tensor_optix/core/base_optimizer.py`
- [Backoff scheduler](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/backoff_scheduler.py): `tensor_optix/core/backoff_scheduler.py`
- [Checkpoint registry](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/checkpoint_registry.py): `tensor_optix/core/checkpoint_registry.py`
- [Diagnostic controller](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/diagnostic_controller.py): `tensor_optix/core/diagnostic_controller.py`
- [Policy manager](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/policy_manager.py): `tensor_optix/core/policy_manager.py`
- [Meta controller](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/core/meta_controller.py): `tensor_optix/core/meta_controller.py`

### Extended capabilities

- [Training callbacks](https://github.com/sup3rus3r/tensor-optix/tree/main/tensor_optix/callbacks): `tensor_optix/callbacks`
- [Graph agent](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/agent/graph_agent.py): `tensor_optix/neuroevo/agent/graph_agent.py`
- [Neuron graph](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/graph/neuron_graph.py): `tensor_optix/neuroevo/graph/neuron_graph.py`
- [Topology controller](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/controller/topology_controller.py): `tensor_optix/neuroevo/controller/topology_controller.py`
- [Brain network](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/brain_network.py): `tensor_optix/neuroevo/brain_network.py`
- [Hebbian hook](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/neuroevo/hebbian.py): `tensor_optix/neuroevo/hebbian.py`
- [Async learner](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/distributed/async_learner.py): `tensor_optix/distributed/async_learner.py`
- [Trial orchestrator](https://github.com/sup3rus3r/tensor-optix/blob/main/tensor_optix/orchestrator.py): `tensor_optix/orchestrator.py`

### Other components

- **Training user**
- **Environment or stream**
- **Optuna study**

## Connections

- Training user → Agent factory: selects agent
- Training user → Optimizer facade: starts training
- Agent factory → RL algorithms: constructs
- RL algorithms → Framework adapters: uses framework
- RL algorithms → Agent interface: implements
- Optimizer facade → Loop controller: configures and runs
- Training user → Batch pipeline: provides environment
- Environment or stream → Batch pipeline: steps
- Environment or stream → Vector pipeline: parallel environments
- Environment or stream → Live pipeline: streams items
- Environment or stream → Dataset pipeline: provides batches
- Batch pipeline → Pipeline contract: implements
- Vector pipeline → Pipeline contract: implements
- Live pipeline → Pipeline contract: implements
- Dataset pipeline → Pipeline contract: implements
- Pipeline contract → Episode data: yields
- Loop controller → Pipeline contract: consumes episodes
- Loop controller → Agent interface: calls learn
- Loop controller → Evaluator: evaluates performance
- Evaluator → Pipeline contract: reads validation episodes
- Loop controller → Online optimizer: updates hyperparameters
- Loop controller → Backoff scheduler: checks convergence state
- Loop controller → Checkpoint registry: saves and restores
- Loop controller → Diagnostic controller: passes training signals
- Diagnostic controller → Agent interface: adjusts hyperparameters
- Loop controller → Training callbacks: dispatches lifecycle events
- Loop controller → Policy manager: handles dormant policy
- Policy manager → Meta controller: requests decision
- Policy manager → Checkpoint registry: loads best weights
- Agent factory → Graph agent: optional graph policy
- Graph agent → Neuron graph: uses graph policy
- Graph agent → Hebbian hook: applies learning hook
- Loop controller → Topology controller: dispatches callback
- Topology controller → Neuron graph: mutates topology
- Neuron graph → Brain network: composes regions
- Training user → Trial orchestrator: requests tuning
- Trial orchestrator → Loop controller: runs trial training
- Trial orchestrator → Optuna study: reports trial results
- Async learner → Agent interface: trains asynchronously