# facebookresearch/sonar architecture

> Architecture diagram of the GitHub repository facebookresearch/sonar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/sonar
- Repository: https://github.com/facebookresearch/sonar

## Overview

##### Main components
- TextToEmbeddingModelPipeline (entry point)
- Tokenizer module (SentencePiece)
- Encoder Handler (wrapper around the Fairseq2 model)
- Encoder Model (the actual neural network)
- Card / Config loader (reads the YAML card describing default paths and hyperparameters)
- External dependencies: Fairseq2, sentencepiece

##### Relationships and data flow
1. User supplies List[str] to the TextToEmbeddingModelPipeline
2. Pipeline invokes the Card/Config loader to fetch default settings for both tokenizer and encoder (default card = “text_sonar_basic_encoder”)
3. Pipeline instantiates:
- A SentencePiece tokenizer (using model path from the card)
- An Encoder Handler (using the card’s model checkpoint path)
– Handler leverages the Factory to load the Encoder Model
– Factory uses the Config object (in code) to set architecture parameters
– Handler wraps the raw Fairseq2 model to expose a simple `.predict()` or `.forward()` method returning embeddings
4. Pipeline runs text → tokens → model.forward → pooling → final fixed‐size tensor

##### Architectural patterns
- Pipeline pattern (pre-processing, model inference, post-processing)
- Config‐driven component loading (YAML cards + factory)
- Clear separation between logic (Handler), data (Config/Card), and model (Fairseq2)

4. Default configuration for “text_sonar_basic_encoder” card (located in sonar/cards/text_sonar_basic_encoder.yaml)
- name: text_sonar_basic_encoder
- type: text_encoder
- tokenizer:
– type: sentencepiece
– model_path: sentencepiece.source.256000.model
- encoder:
– checkpoint_path: sonar_text_encoder.pt
– embedding_size: 1024
– max_seq_len: 512
– pooling: mean
– framework: fairseq2 (v0.4.5)
- device: cpu (unless overridden)
- dtype: float32

##### Nested modules (show inside Encoder Handler)
- Config (sonar.models.sonar_text.config)
- Factory (sonar.models.sonar_text.factory)
- Model class (sonar.models.sonar_text.model)
- Loader / Handler (sonar.models.sonar_text.handler)

##### Putting it all together
[TextToEmbeddingModelPipeline]
|
v
[Card/Config Loader (“text_sonar_basic_encoder”)]
├─ provides ─> tokenizer settings
└─ provides ─> encoder checkpoint & hyperparameters
|
v
[SentencePiece Tokenizer]──(token IDs)──>
|
v
[Encoder Handler] (contains Config, Factory, Model)
|
v
[Fairseq2 Encoder Model]──(hidden states + pooling)──>
|
v
[Final 1024-d Embedding Tensor]

## Diagram (Mermaid)

```mermaid
flowchart TD
    TextToEmbeddingModelPipeline["TextToEmbeddingModelPipeline\n(default: text_sonar_basic_encoder)"]:::core
    CardLoader["Card/Config Loader\n(text_sonar_basic_encoder)"]:::config
    extCards["YAML Cards Directory"]:::config
    YAMLCard["text_sonar_basic_encoder.yaml\n(tokenizer:model=sentencepiece.source.256000.model\ncheckpoint: sonar_text_encoder.pt\nembedding_size:1024\nmax_seq_len:512\npooling:mean\ndevice:cpu\ndtype:float32)"]:::config
    Tokenizer["SentencePiece Tokenizer\n(model_path: sentencepiece.source.256000.model)"]:::core
    subgraph "Encoder Handler"
        Handler["Handler\n(.predict()/.forward())"]:::core
        Config["Config\n(embedding_size=1024\nmax_seq_len=512\npooling=mean\ndevice=cpu\ndtype=float32)"]:::core
        Factory["Factory\n(configure architecture)"]:::core
        ModelClass["Model Class\n(neural network)"]:::core
        EncoderLoader["EncoderModel Loader"]:::core
    end
    FinalEmbed["Final 1024-d Embedding Tensor"]:::core
    sentencepiece["sentencepiece lib"]:::external
    fairseq2["fairseq2 lib"]:::external

    TextToEmbeddingModelPipeline -->|"raw text"| CardLoader
    CardLoader -->|"provides settings"| Tokenizer
    CardLoader -->|"provides settings"| Handler
    CardLoader -.-> YAMLCard
    CardLoader -.-> extCards
    Tokenizer -->|"token IDs"| Handler
    Handler -->|"forward()"| ModelClass
    ModelClass -->|"pooled vector"| FinalEmbed
    Tokenizer -.-> sentencepiece
    ModelClass -.-> fairseq2
    Handler --> Config
    Handler --> Factory
    Handler --> EncoderLoader
    Handler --> ModelClass

    click TextToEmbeddingModelPipeline "https://github.com/facebookresearch/sonar/blob/main/sonar/inference_pipelines/text.py"
    click CardLoader "https://github.com/facebookresearch/sonar/blob/main/sonar/cards/text_sonar_basic_encoder.yaml"
    click extCards "https://github.com/facebookresearch/sonar/tree/main/sonar/cards/"
    click Tokenizer "https://github.com/facebookresearch/sonar/blob/main/sonar/models/sonar_text/handler.py"
    click Handler "https://github.com/facebookresearch/sonar/blob/main/sonar/models/sonar_text/handler.py"
    click Config "https://github.com/facebookresearch/sonar/blob/main/sonar/models/sonar_text/config.py"
    click Factory "https://github.com/facebookresearch/sonar/blob/main/sonar/models/sonar_text/factory.py"
    click ModelClass "https://github.com/facebookresearch/sonar/blob/main/sonar/models/sonar_text/model.py"
    click EncoderLoader "https://github.com/facebookresearch/sonar/blob/main/sonar/models/encoder_model.py"

    classDef core fill:#DCEEFB,stroke:#1E3A8A,color:#1E3A8A
    classDef config fill:#FEF3C7,stroke:#92400E,color:#92400E
    classDef external fill:#DCFCE7,stroke:#166534,color:#166534
```
