# ayanalammoon/neuroswarmautoml architecture

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

- Interactive diagram: https://gitdiagram.com/ayanalammoon/neuroswarmautoml
- Repository: https://github.com/ayanalammoon/neuroswarmautoml
- Video tour (about a minute): https://gitdiagram.com/ayanalammoon/neuroswarmautoml/video

## Overview

NeuroSwarm-AutoML searches for hardware-suitable neural architectures: the CLI initializes a dataset and search, then coordinates topology and hyperparameter evolution, surrogate screening, distributed model training, and fitness feedback. Winning candidates can be profiled, exported, reported, served for inference, or converted by the separate agent-context bridge into embeddings forwarded to Cortexta. The principal flow and named capabilities follow the README; some utility and service internals were not sampled, so their wiring is limited to documented behavior.

Main entry points: [`src/neuroswarm/main.py`](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/main.py) (Search CLI), [`src/neuroswarm/optimizers/bilevel_engine.py`](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/optimizers/bilevel_engine.py) (Bi-level engine), [`src/neuroswarm/core/runner.py`](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/core/runner.py) (Distributed runner), [`src/neuroswarm/utils/benchmark.py`](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/benchmark.py) (Hardware benchmarks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_search["Search Control"]
  node_main["Search CLI<br/>[main.py]"]
  node_engine["Bi-level engine<br/>[bilevel_engine.py]"]
  node_ga["Topology GA<br/>[ga_topology.py]"]
  node_pso["PSO-DE"]
  node_surrogate["GP surrogate<br/>[gp_estimator.py]"]
end

subgraph group_models["Architecture Models"]
  node_candidate["Candidate state<br/>[candidate.py]"]
  node_dag["DAG search space<br/>[dag_space.py]"]
  node_builder["Dynamic network builder<br/>[dynamic_builder.py]"]
  node_embedder["Graph embedder<br/>[graph_embedder.py]"]
end

subgraph group_evaluation["Training Evaluation"]
  node_runner["Distributed runner<br/>[runner.py]"]
  node_data["Dataset loaders<br/>[main.py]"]
  node_benchmark["Hardware benchmarks<br/>[benchmark.py]"]
  node_ptbench["PyTorch benchmark<br/>[benchmark_pt.py]"]
  node_trtbench["TensorRT benchmark<br/>[benchmark_trt.py]"]
  node_metrics["Metrics and Pareto<br/>[metrics.py]"]
  node_report["Experiment reporter<br/>[reporter.py]"]
end

subgraph group_deployment["Export Serving"]
  node_export["Model export<br/>[export.py]"]
  node_quantize["FP16 quantizer<br/>[quantize.py]"]
  node_trtexport["TensorRT exporter<br/>[trt_exporter.py]"]
  node_server["Inference API and UI<br/>[server.py]"]
end

subgraph group_context["Context Bridge"]
  node_contextapi["Context API<br/>[context_service.py]"]
  node_encoder["Pretrained encoder<br/>[context_service.py]"]
end

node_user(("Search user"))
node_client(("Inference client"))
node_cortexta["Cortexta daemon"]

node_user -->|"starts search"| node_main
node_main -->|"loads data"| node_data
node_main -->|"runs generations"| node_engine
node_engine -->|"updates hyperparameters"| node_pso
node_engine -->|"evolves topology"| node_ga
node_engine -->|"scores candidates"| node_surrogate
node_engine -->|"requests evaluations"| node_runner
node_ga -->|"mutates candidates"| node_candidate
node_pso -->|"updates candidates"| node_candidate
node_runner -->|"builds network"| node_builder
node_runner -->|"evaluates candidate"| node_candidate
node_runner -->|"trains against"| node_data
node_surrogate -->|"featurizes graphs"| node_embedder
node_main -->|"exports models"| node_export
node_main -->|"extracts Pareto results"| node_metrics
node_main -->|"generates report"| node_report
node_main -->|"profiles hardware"| node_benchmark
node_benchmark -->|"benchmarks PyTorch"| node_ptbench
node_benchmark -->|"benchmarks TensorRT"| node_trtbench
node_export -.->|"quantizes TorchScript"| node_quantize
node_export -.->|"builds TensorRT engine"| node_trtexport
node_client -->|"submits inference"| node_server
node_contextapi -->|"encodes context"| node_encoder
node_contextapi -.->|"forwards context"| node_cortexta

click node_main "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/main.py"
click node_engine "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/optimizers/bilevel_engine.py"
click node_ga "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/optimizers/ga_topology.py"
click node_pso "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/optimizers/pso_de_continuous.py"
click node_surrogate "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/surrogates/gp_estimator.py"
click node_candidate "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/core/candidate.py"
click node_dag "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/search_space/dag_space.py"
click node_builder "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/search_space/dynamic_builder.py"
click node_embedder "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/surrogates/graph_embedder.py"
click node_runner "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/core/runner.py"
click node_data "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/main.py"
click node_benchmark "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/benchmark.py"
click node_ptbench "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/benchmark_pt.py"
click node_trtbench "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/benchmark_trt.py"
click node_metrics "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/metrics.py"
click node_report "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/reporter.py"
click node_export "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/export.py"
click node_quantize "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/quantize.py"
click node_trtexport "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/trt_exporter.py"
click node_server "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/server.py"
click node_contextapi "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/context_service.py"
click node_encoder "https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/context_service.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_main,node_engine,node_ga,node_pso,node_surrogate,node_user,node_client toneBlue
class node_candidate,node_dag,node_builder,node_embedder toneAmber
class node_runner,node_data,node_benchmark,node_ptbench,node_trtbench,node_metrics,node_report toneMint
class node_export,node_quantize,node_trtexport,node_server toneRose
class node_contextapi,node_encoder,node_cortexta toneIndigo
```

## Components

### Search Control

- [Search CLI](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/main.py): `src/neuroswarm/main.py`
- [Bi-level engine](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/optimizers/bilevel_engine.py): `src/neuroswarm/optimizers/bilevel_engine.py`
- [Topology GA](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/optimizers/ga_topology.py): `src/neuroswarm/optimizers/ga_topology.py`
- [PSO-DE](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/optimizers/pso_de_continuous.py): `src/neuroswarm/optimizers/pso_de_continuous.py`
- [GP surrogate](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/surrogates/gp_estimator.py): `src/neuroswarm/surrogates/gp_estimator.py`

### Architecture Models

- [Candidate state](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/core/candidate.py): `src/neuroswarm/core/candidate.py`
- [DAG search space](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/search_space/dag_space.py): `src/neuroswarm/search_space/dag_space.py`
- [Dynamic network builder](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/search_space/dynamic_builder.py): `src/neuroswarm/search_space/dynamic_builder.py`
- [Graph embedder](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/surrogates/graph_embedder.py): `src/neuroswarm/surrogates/graph_embedder.py`

### Training Evaluation

- [Distributed runner](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/core/runner.py): `src/neuroswarm/core/runner.py`
- [Dataset loaders](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/main.py): `src/neuroswarm/main.py`
- [Hardware benchmarks](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/benchmark.py): `src/neuroswarm/utils/benchmark.py`
- [PyTorch benchmark](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/benchmark_pt.py): `src/neuroswarm/utils/benchmark_pt.py`
- [TensorRT benchmark](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/benchmark_trt.py): `src/neuroswarm/utils/benchmark_trt.py`
- [Metrics and Pareto](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/metrics.py): `src/neuroswarm/utils/metrics.py`
- [Experiment reporter](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/reporter.py): `src/neuroswarm/utils/reporter.py`

### Export Serving

- [Model export](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/export.py): `src/neuroswarm/utils/export.py`
- [FP16 quantizer](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/quantize.py): `src/neuroswarm/utils/quantize.py`
- [TensorRT exporter](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/trt_exporter.py): `src/neuroswarm/utils/trt_exporter.py`
- [Inference API and UI](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/utils/server.py): `src/neuroswarm/utils/server.py`

### Context Bridge

- [Context API](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/context_service.py): `src/neuroswarm/context_service.py`
- [Pretrained encoder](https://github.com/ayanalammoon/neuroswarmautoml/blob/main/src/neuroswarm/context_service.py): `src/neuroswarm/context_service.py`

### Other components

- **Search user**
- **Inference client**
- **Cortexta daemon**

## Connections

- Search user → Search CLI: starts search
- Search CLI → Dataset loaders: loads data
- Search CLI → Bi-level engine: runs generations
- Bi-level engine → PSO-DE: updates hyperparameters
- Bi-level engine → Topology GA: evolves topology
- Bi-level engine → GP surrogate: scores candidates
- Bi-level engine → Distributed runner: requests evaluations
- Topology GA → Candidate state: mutates candidates
- PSO-DE → Candidate state: updates candidates
- Distributed runner → Dynamic network builder: builds network
- Distributed runner → Candidate state: evaluates candidate
- Distributed runner → Dataset loaders: trains against
- GP surrogate → Graph embedder: featurizes graphs
- Search CLI → Model export: exports models
- Search CLI → Metrics and Pareto: extracts Pareto results
- Search CLI → Experiment reporter: generates report
- Search CLI → Hardware benchmarks: profiles hardware
- Hardware benchmarks → PyTorch benchmark: benchmarks PyTorch
- Hardware benchmarks → TensorRT benchmark: benchmarks TensorRT
- Model export → FP16 quantizer: quantizes TorchScript
- Model export → TensorRT exporter: builds TensorRT engine
- Inference client → Inference API and UI: submits inference
- Context API → Pretrained encoder: encodes context
- Context API → Cortexta daemon: forwards context