# tarne75/sorethumb architecture

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

## Overview

sorethumb is a local-first tabular anomaly ranker and review shortlist generator. The principal workflow is CLI or Python invocation → source loading → column profiling and feature preparation → detector ensemble scoring → original-column explanations → persisted run history and reports. The pipeline module is documented as the sole subsystem sequencer; source excerpts confirm several internal responsibilities, but not every call site, so uncertain links are omitted. The graph also preserves the documented score-forward and resumable-history capabilities.

Main entry points: [`src/sorethumb/_pipeline.py`](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/_pipeline.py) (Run pipeline), [`src/sorethumb/cli.py`](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/cli.py) (CLI), [`src/sorethumb/io/source.py`](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/io/source.py) (Source resolution), [`src/sorethumb/io/readers.py`](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/io/readers.py) (Format readers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_cli["CLI<br/>[cli.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_pipeline["Run pipeline<br/>[_pipeline.py]"]
end

subgraph group_data["Data preparation"]
  node_source["Source resolution<br/>[source.py]"]
  node_readers["Format readers<br/>[readers.py]"]
  node_profiling["Column profiling<br/>[profile.py]"]
  node_planning["Feature planning<br/>[plan.py]"]
  node_features["Feature construction<br/>[build.py]"]
end

subgraph group_detection["Detection and explanations"]
  node_detectors["Detector suite"]
  node_calibration["Score calibration<br/>[calibrate.py]"]
  node_ensemble["Ensemble ranking<br/>[combine.py]"]
  node_explanations["Record explanations"]
end

subgraph group_history["History and reporting"]
  node_store[("SQLite store<br/>[db.py]")]
  node_models["Models and results<br/>[models.py]"]
  node_ledger["Run ledger<br/>[ledger.py]"]
  node_periods["Period backfill<br/>[periods.py]"]
  node_contrast["History contrast<br/>[contrast.py]"]
  node_reports["Reports"]
end

node_user(("Analyst"))
node_dataset["Dataset"]
node_remote(("HTTP source"))
node_output["Ranked results"]

node_user -->|"invokes"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"runs or scores"| node_pipeline
node_user -.->|"calls API"| node_pipeline
node_pipeline -->|"resolves source"| node_source
node_source -.->|"downloads"| node_remote
node_dataset -->|"provides URI"| node_source
node_pipeline -->|"reads data"| node_readers
node_readers -->|"loads records"| node_dataset
node_pipeline -->|"profiles columns"| node_profiling
node_pipeline -->|"plans treatments"| node_planning
node_pipeline -->|"builds features"| node_features
node_pipeline -->|"fits and scores"| node_detectors
node_pipeline -->|"calibrates scores"| node_calibration
node_pipeline -->|"combines scores"| node_ensemble
node_pipeline -->|"explains records"| node_explanations
node_pipeline -->|"persists artifacts"| node_models
node_pipeline -->|"records run"| node_store
node_pipeline -->|"tracks completion"| node_ledger
node_ledger -->|"reads and writes"| node_store
node_pipeline -->|"selects periods"| node_periods
node_pipeline -->|"compares history"| node_contrast
node_pipeline -->|"renders report"| node_reports
node_reports -->|"writes report"| node_output
node_pipeline -->|"returns ranking"| node_output

click node_cli "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/cli.py"
click node_config "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/config.py"
click node_pipeline "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/_pipeline.py"
click node_source "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/io/source.py"
click node_readers "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/io/readers.py"
click node_profiling "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/profiling/profile.py"
click node_planning "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/profiling/plan.py"
click node_features "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/features/build.py"
click node_detectors "https://github.com/tarne75/sorethumb/tree/main/src/sorethumb/detectors"
click node_calibration "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/scoring/calibrate.py"
click node_ensemble "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/scoring/combine.py"
click node_explanations "https://github.com/tarne75/sorethumb/tree/main/src/sorethumb/explain"
click node_store "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/store/db.py"
click node_models "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/store/models.py"
click node_ledger "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/history/ledger.py"
click node_periods "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/history/periods.py"
click node_contrast "https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/analysis/contrast.py"
click node_reports "https://github.com/tarne75/sorethumb/tree/main/src/sorethumb/report"

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_config,node_pipeline toneBlue
class node_source,node_readers,node_profiling,node_planning,node_features toneAmber
class node_detectors,node_calibration,node_ensemble,node_explanations toneMint
class node_store,node_models,node_ledger,node_periods,node_contrast,node_reports toneRose
class node_user,node_dataset,node_remote,node_output toneIndigo
```

## Components

### Entry and orchestration

- [CLI](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/cli.py): `src/sorethumb/cli.py`
- [Configuration](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/config.py): `src/sorethumb/config.py`
- [Run pipeline](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/_pipeline.py): `src/sorethumb/_pipeline.py`

### Data preparation

- [Source resolution](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/io/source.py): `src/sorethumb/io/source.py`
- [Format readers](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/io/readers.py): `src/sorethumb/io/readers.py`
- [Column profiling](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/profiling/profile.py): `src/sorethumb/profiling/profile.py`
- [Feature planning](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/profiling/plan.py): `src/sorethumb/profiling/plan.py`
- [Feature construction](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/features/build.py): `src/sorethumb/features/build.py`

### Detection and explanations

- [Detector suite](https://github.com/tarne75/sorethumb/tree/main/src/sorethumb/detectors): `src/sorethumb/detectors`
- [Score calibration](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/scoring/calibrate.py): `src/sorethumb/scoring/calibrate.py`
- [Ensemble ranking](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/scoring/combine.py): `src/sorethumb/scoring/combine.py`
- [Record explanations](https://github.com/tarne75/sorethumb/tree/main/src/sorethumb/explain): `src/sorethumb/explain`

### History and reporting

- [SQLite store](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/store/db.py): `src/sorethumb/store/db.py`
- [Models and results](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/store/models.py): `src/sorethumb/store/models.py`
- [Run ledger](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/history/ledger.py): `src/sorethumb/history/ledger.py`
- [Period backfill](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/history/periods.py): `src/sorethumb/history/periods.py`
- [History contrast](https://github.com/tarne75/sorethumb/blob/main/src/sorethumb/analysis/contrast.py): `src/sorethumb/analysis/contrast.py`
- [Reports](https://github.com/tarne75/sorethumb/tree/main/src/sorethumb/report): `src/sorethumb/report`

### Other components

- **Analyst**
- **Dataset**
- **HTTP source**
- **Ranked results**

## Connections

- Analyst → CLI: invokes
- CLI → Configuration: loads settings
- CLI → Run pipeline: runs or scores
- Analyst → Run pipeline: calls API
- Run pipeline → Source resolution: resolves source
- Source resolution → HTTP source: downloads
- Dataset → Source resolution: provides URI
- Run pipeline → Format readers: reads data
- Format readers → Dataset: loads records
- Run pipeline → Column profiling: profiles columns
- Run pipeline → Feature planning: plans treatments
- Run pipeline → Feature construction: builds features
- Run pipeline → Detector suite: fits and scores
- Run pipeline → Score calibration: calibrates scores
- Run pipeline → Ensemble ranking: combines scores
- Run pipeline → Record explanations: explains records
- Run pipeline → Models and results: persists artifacts
- Run pipeline → SQLite store: records run
- Run pipeline → Run ledger: tracks completion
- Run ledger → SQLite store: reads and writes
- Run pipeline → Period backfill: selects periods
- Run pipeline → History contrast: compares history
- Run pipeline → Reports: renders report
- Reports → Ranked results: writes report
- Run pipeline → Ranked results: returns ranking