how_it_works.md

### Step by step

**1. Input**
The pipeline takes chords directly as text. Alternatively, an audio file can be uploaded which is then converted into
the text using [chord-extractor](https://github.com/ohollo/chord-extractor).

**2. Preprocess**
The chord sequence is sent to an internal API which first performs custom 
preprocessing (this includes making the chords independent of key).

**3. Embed**
A private model is applied to perform the embedding. This is currently a Transformer model trained on the 
[lmd_chords](https://huggingface.co/datasets/ohollo/lmd_chords) dataset.

**4. Search**
Both eventual outputs rely on comparing that vector is against a prebuilt index of chord sequences and sub-sequences of the songs 
forming the above lmd_chords dataset. 

**5. Score**
By analysing vector similarity and specifically the number of songs within different radii of similarity, a score is 
derived to show the originality (between 0 and 1 with 1 being most original, i.e. with no neighbours found in any radius used).
A scaler is used to aid the scorer cope with different lengths of sequence, pretrained on the contents of the embeddings index.

**6. Neighbours**
The IDs of the closest matching vectors (within a minimum radius) are cross-referenced with the lmd_chords dataset to get 
song names and artists, so that the user can see the details of what songs appear similar to the model. 


### APIs, MCPs and Hooking up to Agents

Furthermore, this space can easily be used as an API or plugged into your AI agent via MCP. This opens up the possibility
of using the tool to feedback on loose song ideas (e.g. try asking it to "Create the chords of a simple song using a 
I-V-vi-IV progression and analyze it for uniqueness"). Click below on "Use via API or MCP" to find out how to connect.