# julian-b-smith/tonality architecture

> Architecture diagram of the GitHub repository julian-b-smith/tonality, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/julian-b-smith/tonality
- Repository: https://github.com/julian-b-smith/tonality

## Overview

Tonality is a local-first, deterministic music-theory engine for software and AI callers. The principal workflow is to submit musical material through Python or the MCP tool surface, derive ranked, evidence-bearing analysis, and return structured results. MIDI and temporal analysis extend that workflow with key, meter, rhythm, and modulation stages; separate branches cover rulesets and style modeling, generation, search, and render-agnostic representations. Edges follow the excerpts, SOURCE INDEX references, or README claims; unsampled internals are represented at subsystem level, and their unverified connections are omitted.

Main entry points: [`mts/mcp/tools.py`](https://github.com/julian-b-smith/tonality/blob/main/mts/mcp/tools.py) (MCP tools), [`mts/temporal/sequence.py`](https://github.com/julian-b-smith/tonality/blob/main/mts/temporal/sequence.py) (Musical sequence), [`mts/core/bitmask.py`](https://github.com/julian-b-smith/tonality/blob/main/mts/core/bitmask.py) (Pitch and set primitives), [`mts/io/midi.py`](https://github.com/julian-b-smith/tonality/blob/main/mts/io/midi.py) (MIDI ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Theory primitives"]
  node_primitives["Pitch and set primitives<br/>[bitmask.py]"]
  node_pitch["Pitch model<br/>[pitch.py]"]
  node_realization["Registered realization<br/>[realization.py]"]
  node_scale["Scale model<br/>[scale.py]"]
  node_theory["Derived functions<br/>[functions.py]"]
end

subgraph group_analysis["Harmonic analysis"]
  node_naming["Naming and context<br/>[naming.py]"]
  node_keyinduction["Key induction<br/>[key_induction.py]"]
  node_analysisresults["Ranked results<br/>[results.py]"]
end

subgraph group_time["Temporal analysis"]
  node_sequence["Musical sequence<br/>[sequence.py]"]
  node_keytracking["Key tracking<br/>[key_tracking.py]"]
  node_chromatic["Chromatic events<br/>[chromatic.py]"]
end

subgraph group_style["Rules and style"]
  node_rules["Rules and evaluation<br/>[schema.py]"]
  node_induction["Rule induction<br/>[induction.py]"]
  node_transitions["Style transitions<br/>[transition.py]"]
end

subgraph group_surface["Access and outputs"]
  node_mcp["MCP tools<br/>[tools.py]"]
  node_server["MCP server<br/>[server.py]"]
  node_loaders["Data loaders<br/>[loaders.py]"]
  node_midi["MIDI ingestion<br/>[midi.py]"]
  node_pipelines["Analysis pipelines<br/>[pipelines.py]"]
  node_dataset["Dataset builders<br/>[builders.py]"]
  node_representations["Visual descriptions<br/>[keyboard.py]"]
  node_generation["Music generation<br/>[modal.py]"]
  node_search["Voicing search<br/>[voicings.py]"]
end

node_caller(("Music software / agent"))

node_caller -->|"queries tools"| node_mcp
node_server -->|"registers tools"| node_mcp
node_mcp -->|"calls analysis"| node_naming
node_mcp -->|"calls analysis"| node_keyinduction
node_mcp -->|"calls search"| node_search
node_mcp -->|"calls views"| node_representations
node_mcp -->|"calls rules"| node_rules
node_mcp -->|"calls transforms"| node_generation
node_mcp -->|"calls pipelines"| node_pipelines
node_pitch -->|"uses pitch classes"| node_primitives
node_scale -->|"builds masks"| node_primitives
node_realization -->|"reduces to mask"| node_primitives
node_theory -->|"derives from masks"| node_primitives
node_loaders -->|"loads priors"| node_keyinduction
node_midi -->|"creates pitches"| node_pitch
node_midi -->|"creates sequences"| node_sequence
node_sequence -->|"reads sounding pitches"| node_realization
node_sequence -->|"tracks key regions"| node_keytracking
node_chromatic -->|"names chords"| node_naming
node_chromatic -->|"segments sequence"| node_sequence
node_keyinduction -->|"returns candidates"| node_analysisresults
node_pipelines -->|"builds dataset"| node_dataset
node_induction -->|"evaluates rules"| node_rules
node_caller -->|"supplies MIDI"| node_midi
node_caller -->|"defines constraints"| node_rules
node_caller -->|"uses style model"| node_transitions
node_caller -->|"consumes descriptors"| node_representations
node_caller -->|"requests generation"| node_generation

click node_mcp "https://github.com/julian-b-smith/tonality/blob/main/mts/mcp/tools.py"
click node_server "https://github.com/julian-b-smith/tonality/blob/main/mts/mcp/server.py"
click node_loaders "https://github.com/julian-b-smith/tonality/blob/main/mts/io/loaders.py"
click node_midi "https://github.com/julian-b-smith/tonality/blob/main/mts/io/midi.py"
click node_primitives "https://github.com/julian-b-smith/tonality/blob/main/mts/core/bitmask.py"
click node_pitch "https://github.com/julian-b-smith/tonality/blob/main/mts/core/pitch.py"
click node_realization "https://github.com/julian-b-smith/tonality/blob/main/mts/core/realization.py"
click node_scale "https://github.com/julian-b-smith/tonality/blob/main/mts/core/scale.py"
click node_theory "https://github.com/julian-b-smith/tonality/blob/main/mts/theory/functions.py"
click node_naming "https://github.com/julian-b-smith/tonality/blob/main/mts/analysis/naming.py"
click node_keyinduction "https://github.com/julian-b-smith/tonality/blob/main/mts/analysis/key_induction.py"
click node_analysisresults "https://github.com/julian-b-smith/tonality/blob/main/mts/analysis/results.py"
click node_sequence "https://github.com/julian-b-smith/tonality/blob/main/mts/temporal/sequence.py"
click node_keytracking "https://github.com/julian-b-smith/tonality/blob/main/mts/temporal/key_tracking.py"
click node_chromatic "https://github.com/julian-b-smith/tonality/blob/main/mts/temporal/chromatic.py"
click node_pipelines "https://github.com/julian-b-smith/tonality/blob/main/mts/dataset/pipelines.py"
click node_dataset "https://github.com/julian-b-smith/tonality/blob/main/mts/dataset/builders.py"
click node_rules "https://github.com/julian-b-smith/tonality/blob/main/mts/rules/schema.py"
click node_induction "https://github.com/julian-b-smith/tonality/blob/main/mts/rules/induction.py"
click node_transitions "https://github.com/julian-b-smith/tonality/blob/main/mts/rules/transition.py"
click node_representations "https://github.com/julian-b-smith/tonality/blob/main/mts/representation/keyboard.py"
click node_generation "https://github.com/julian-b-smith/tonality/blob/main/mts/generate/modal.py"
click node_search "https://github.com/julian-b-smith/tonality/blob/main/mts/search/voicings.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_primitives,node_pitch,node_realization,node_scale,node_theory toneBlue
class node_naming,node_keyinduction,node_analysisresults toneAmber
class node_sequence,node_keytracking,node_chromatic toneMint
class node_rules,node_induction,node_transitions toneRose
class node_mcp,node_server,node_loaders,node_midi,node_pipelines,node_dataset,node_representations,node_generation,node_search,node_caller toneIndigo
```

## Components

### Theory primitives

- [Pitch and set primitives](https://github.com/julian-b-smith/tonality/blob/main/mts/core/bitmask.py): `mts/core/bitmask.py`
- [Pitch model](https://github.com/julian-b-smith/tonality/blob/main/mts/core/pitch.py): `mts/core/pitch.py`
- [Registered realization](https://github.com/julian-b-smith/tonality/blob/main/mts/core/realization.py): `mts/core/realization.py`
- [Scale model](https://github.com/julian-b-smith/tonality/blob/main/mts/core/scale.py): `mts/core/scale.py`
- [Derived functions](https://github.com/julian-b-smith/tonality/blob/main/mts/theory/functions.py): `mts/theory/functions.py`

### Harmonic analysis

- [Naming and context](https://github.com/julian-b-smith/tonality/blob/main/mts/analysis/naming.py): `mts/analysis/naming.py`
- [Key induction](https://github.com/julian-b-smith/tonality/blob/main/mts/analysis/key_induction.py): `mts/analysis/key_induction.py`
- [Ranked results](https://github.com/julian-b-smith/tonality/blob/main/mts/analysis/results.py): `mts/analysis/results.py`

### Temporal analysis

- [Musical sequence](https://github.com/julian-b-smith/tonality/blob/main/mts/temporal/sequence.py): `mts/temporal/sequence.py`
- [Key tracking](https://github.com/julian-b-smith/tonality/blob/main/mts/temporal/key_tracking.py): `mts/temporal/key_tracking.py`
- [Chromatic events](https://github.com/julian-b-smith/tonality/blob/main/mts/temporal/chromatic.py): `mts/temporal/chromatic.py`

### Rules and style

- [Rules and evaluation](https://github.com/julian-b-smith/tonality/blob/main/mts/rules/schema.py): `mts/rules/schema.py`
- [Rule induction](https://github.com/julian-b-smith/tonality/blob/main/mts/rules/induction.py): `mts/rules/induction.py`
- [Style transitions](https://github.com/julian-b-smith/tonality/blob/main/mts/rules/transition.py): `mts/rules/transition.py`

### Access and outputs

- [MCP tools](https://github.com/julian-b-smith/tonality/blob/main/mts/mcp/tools.py): `mts/mcp/tools.py`
- [MCP server](https://github.com/julian-b-smith/tonality/blob/main/mts/mcp/server.py): `mts/mcp/server.py`
- [Data loaders](https://github.com/julian-b-smith/tonality/blob/main/mts/io/loaders.py): `mts/io/loaders.py`
- [MIDI ingestion](https://github.com/julian-b-smith/tonality/blob/main/mts/io/midi.py): `mts/io/midi.py`
- [Analysis pipelines](https://github.com/julian-b-smith/tonality/blob/main/mts/dataset/pipelines.py): `mts/dataset/pipelines.py`
- [Dataset builders](https://github.com/julian-b-smith/tonality/blob/main/mts/dataset/builders.py): `mts/dataset/builders.py`
- [Visual descriptions](https://github.com/julian-b-smith/tonality/blob/main/mts/representation/keyboard.py): `mts/representation/keyboard.py`
- [Music generation](https://github.com/julian-b-smith/tonality/blob/main/mts/generate/modal.py): `mts/generate/modal.py`
- [Voicing search](https://github.com/julian-b-smith/tonality/blob/main/mts/search/voicings.py): `mts/search/voicings.py`

### Other components

- **Music software / agent**

## Connections

- Music software / agent → MCP tools: queries tools (evidence: `README.md`)
- MCP server → MCP tools: registers tools (evidence: `mts/mcp/server.py`)
- MCP tools → Naming and context: calls analysis (evidence: `mts/mcp/tools.py`)
- MCP tools → Key induction: calls analysis (evidence: `mts/mcp/tools.py`)
- MCP tools → Voicing search: calls search (evidence: `mts/mcp/tools.py`)
- MCP tools → Visual descriptions: calls views (evidence: `mts/mcp/tools.py`)
- MCP tools → Rules and evaluation: calls rules (evidence: `mts/mcp/tools.py`)
- MCP tools → Music generation: calls transforms (evidence: `mts/mcp/tools.py`)
- MCP tools → Analysis pipelines: calls pipelines (evidence: `mts/dataset/pipelines.py`)
- Pitch model → Pitch and set primitives: uses pitch classes (evidence: `mts/core/pitch.py`)
- Scale model → Pitch and set primitives: builds masks (evidence: `mts/core/scale.py`)
- Registered realization → Pitch and set primitives: reduces to mask (evidence: `mts/core/realization.py`)
- Derived functions → Pitch and set primitives: derives from masks (evidence: `mts/theory/functions.py`)
- Data loaders → Key induction: loads priors (evidence: `mts/analysis/key_induction.py`)
- MIDI ingestion → Pitch model: creates pitches (evidence: `mts/io/midi.py`)
- MIDI ingestion → Musical sequence: creates sequences (evidence: `mts/io/midi.py`)
- Musical sequence → Registered realization: reads sounding pitches (evidence: `mts/temporal/sequence.py`)
- Musical sequence → Key tracking: tracks key regions (evidence: `mts/temporal/key_tracking.py`)
- Chromatic events → Naming and context: names chords (evidence: `mts/temporal/chromatic.py`)
- Chromatic events → Musical sequence: segments sequence (evidence: `mts/temporal/chromatic.py`)
- Key induction → Ranked results: returns candidates (evidence: `mts/analysis/key_induction.py`)
- Analysis pipelines → Dataset builders: builds dataset (evidence: `mts/dataset/pipelines.py`)
- Rule induction → Rules and evaluation: evaluates rules (evidence: `mts/rules/induction.py`)
- Music software / agent → MIDI ingestion: supplies MIDI (evidence: `README.md`)
- Music software / agent → Rules and evaluation: defines constraints (evidence: `README.md`)
- Music software / agent → Style transitions: uses style model (evidence: `README.md`)
- Music software / agent → Visual descriptions: consumes descriptors (evidence: `README.md`)
- Music software / agent → Music generation: requests generation (evidence: `README.md`)
