# franck-dernoncourt/neuroner architecture

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

- Interactive diagram: https://gitdiagram.com/franck-dernoncourt/neuroner
- Repository: https://github.com/franck-dernoncourt/neuroner

## Overview

NeuroNER is a neural named-entity recognition application. Users provide CoNLL or BRAT datasets, then train a model or apply a pretrained model to test or deployment text; predictions can be evaluated and converted for BRAT use. The graph includes documented data/model fetching and format-conversion capabilities. Some orchestration and conversion wiring is inferred from documented behavior because the relevant source excerpts are partial.

Main entry points: [`neuroner/neuromodel.py`](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/neuromodel.py) (NeuroNER API), [`neuroner/train.py`](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/train.py) (Training and prediction), [`neuroner/__main__.py`](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/__main__.py) (CLI), [`neuroner/dataset.py`](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/dataset.py) (Dataset loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Entry and orchestration"]
  node_cli["CLI<br/>[__main__.py]"]
  node_orchestrator["NeuroNER API<br/>[neuromodel.py]"]
end

subgraph group_data["Dataset preparation"]
  node_dataset["Dataset loader<br/>[dataset.py]"]
  node_brat_reader["BRAT to CoNLL<br/>[brat_to_conll.py]"]
  node_conll_writer["CoNLL to BRAT<br/>[conll_to_brat.py]"]
  node_xml_converter["i2b2 XML converter<br/>[xml_to_brat.py]"]
end

subgraph group_model["NER modeling"]
  node_model["Entity LSTM<br/>[entity_lstm.py]"]
  node_trainer["Training and prediction<br/>[train.py]"]
end

subgraph group_outputs["Evaluation and artifacts"]
  node_pretrained["Pretrained models"]
  node_evaluator["Metrics and plots<br/>[evaluate.py]"]
  node_model_prep["Model sharing prep"]
  node_results["Prediction outputs"]
end

node_user(("User"))
node_tokenizer["Tokenizer services"]
node_embeddings["Pretrained embeddings"]

node_user -->|"runs"| node_cli
node_user -->|"calls API"| node_orchestrator
node_cli -->|"dispatches"| node_orchestrator
node_orchestrator -->|"loads data"| node_dataset
node_orchestrator -->|"starts training"| node_trainer
node_orchestrator -->|"builds model"| node_model
node_orchestrator -->|"fetches model"| node_pretrained
node_orchestrator -.->|"loads vectors"| node_embeddings
node_dataset -.->|"parses BRAT"| node_brat_reader
node_brat_reader -.->|"requests tokenization"| node_tokenizer
node_xml_converter -->|"writes annotations"| node_conll_writer
node_trainer -->|"trains and predicts"| node_model
node_trainer -->|"evaluates labels"| node_evaluator
node_trainer -->|"writes predictions"| node_results
node_orchestrator -.->|"exports BRAT"| node_conll_writer
node_model_prep -->|"prepares artifacts"| node_pretrained

click node_cli "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/__main__.py"
click node_orchestrator "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/neuromodel.py"
click node_dataset "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/dataset.py"
click node_brat_reader "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/brat_to_conll.py"
click node_conll_writer "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/conll_to_brat.py"
click node_xml_converter "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/data/i2b2_2014_deid/xml_to_brat.py"
click node_model "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/entity_lstm.py"
click node_trainer "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/train.py"
click node_pretrained "https://github.com/franck-dernoncourt/neuroner/tree/master/neuroner/trained_models"
click node_evaluator "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/evaluate.py"
click node_model_prep "https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/prepare_pretrained_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_cli,node_orchestrator,node_user toneBlue
class node_dataset,node_brat_reader,node_conll_writer,node_xml_converter toneAmber
class node_model,node_trainer toneMint
class node_pretrained,node_evaluator,node_model_prep,node_results toneRose
class node_tokenizer,node_embeddings toneIndigo
```

## Components

### Entry and orchestration

- [CLI](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/__main__.py): `neuroner/__main__.py`
- [NeuroNER API](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/neuromodel.py): `neuroner/neuromodel.py`

### Dataset preparation

- [Dataset loader](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/dataset.py): `neuroner/dataset.py`
- [BRAT to CoNLL](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/brat_to_conll.py): `neuroner/brat_to_conll.py`
- [CoNLL to BRAT](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/conll_to_brat.py): `neuroner/conll_to_brat.py`
- [i2b2 XML converter](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/data/i2b2_2014_deid/xml_to_brat.py): `neuroner/data/i2b2_2014_deid/xml_to_brat.py`

### NER modeling

- [Entity LSTM](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/entity_lstm.py): `neuroner/entity_lstm.py`
- [Training and prediction](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/train.py): `neuroner/train.py`

### Evaluation and artifacts

- [Pretrained models](https://github.com/franck-dernoncourt/neuroner/tree/master/neuroner/trained_models): `neuroner/trained_models`
- [Metrics and plots](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/evaluate.py): `neuroner/evaluate.py`
- [Model sharing prep](https://github.com/franck-dernoncourt/neuroner/blob/master/neuroner/prepare_pretrained_model.py): `neuroner/prepare_pretrained_model.py`
- **Prediction outputs**

### Other components

- **User**
- **Tokenizer services**
- **Pretrained embeddings**

## Connections

- User → CLI: runs
- User → NeuroNER API: calls API
- CLI → NeuroNER API: dispatches
- NeuroNER API → Dataset loader: loads data
- NeuroNER API → Training and prediction: starts training
- NeuroNER API → Entity LSTM: builds model
- NeuroNER API → Pretrained models: fetches model
- NeuroNER API → Pretrained embeddings: loads vectors
- Dataset loader → BRAT to CoNLL: parses BRAT
- BRAT to CoNLL → Tokenizer services: requests tokenization
- i2b2 XML converter → CoNLL to BRAT: writes annotations
- Training and prediction → Entity LSTM: trains and predicts
- Training and prediction → Metrics and plots: evaluates labels
- Training and prediction → Prediction outputs: writes predictions
- NeuroNER API → CoNLL to BRAT: exports BRAT
- Model sharing prep → Pretrained models: prepares artifacts