# nama-researchlab/sema architecture

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

- Interactive diagram: https://gitdiagram.com/nama-researchlab/sema
- Repository: https://github.com/nama-researchlab/sema

## Overview

Sema is an offline Swahili understanding and speech library. Its forward workflow resolves Swahili words through the lexicon and affix rules, races parse strategies, then linearizes meaning into telegraphic English for an external model. On the return path, structured intent is synthesized into Swahili, while the render layer supports bilingual output from glosses. The CLI exposes library operations as JSON. The README documents additional capabilities whose internal wiring is not fully shown in the sampled source; those links are omitted where uncertain.

Main entry points: [`src/bin/sema_cc.rs`](https://github.com/nama-researchlab/sema/blob/main/src/bin/sema_cc.rs) (JSON CLI), [`src/lexicon.rs`](https://github.com/nama-researchlab/sema/blob/main/src/lexicon.rs) (Lexicon lookup), [`src/linearizer.rs`](https://github.com/nama-researchlab/sema/blob/main/src/linearizer.rs) (Sentence linearizer), [`src/racer.rs`](https://github.com/nama-researchlab/sema/blob/main/src/racer.rs) (Parse cascade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interfaces"]
  node_cli["JSON CLI<br/>[sema_cc.rs]"]
end

subgraph group_forward["Forward Understanding"]
  node_lexicon[("Lexicon lookup<br/>[lexicon.rs]")]
  node_racer["Parse cascade<br/>[racer.rs]"]
  node_linearizer["Sentence linearizer<br/>[linearizer.rs]"]
  node_roles["Sentence roles<br/>[linearizer.rs]"]
end

subgraph group_return["Swahili Output"]
  node_rolodex["Intent synthesis<br/>[rolodex.rs]"]
  node_backpass["Back-pass engine<br/>[backpass.rs]"]
  node_render["Bilingual renderer<br/>[render.rs]"]
end

subgraph group_data["Language Data"]
  node_affix["Affix resolver<br/>[mod.rs]"]
  node_lexdata["Distilled lexicon"]
  node_synthdata["Synthesis rules<br/>[sw.toml]"]
end

node_user(("Swahili user"))
node_model(("English model"))
node_tena["Sema-Tena engine"]

node_user -->|"submits text or intent"| node_cli
node_cli -->|"loads and queries"| node_lexicon
node_lexicon -->|"reads entries"| node_lexdata
node_lexicon -->|"tries affixes"| node_affix
node_cli -->|"races sentence"| node_racer
node_racer -->|"resolves words"| node_lexicon
node_racer -->|"decomposes verbs"| node_linearizer
node_cli -->|"linearizes sentence"| node_linearizer
node_linearizer -->|"assigns roles"| node_roles
node_linearizer -->|"returns telegram"| node_model
node_model -->|"provides structured intent"| node_cli
node_cli -->|"synthesizes intent"| node_rolodex
node_rolodex -.->|"uses synthesis"| node_backpass
node_backpass -.->|"loads rules"| node_synthdata
node_backpass -.->|"delegates synthesis"| node_tena
node_cli -->|"renders bilingual output"| node_render
node_render -->|"builds gloss index"| node_lexicon
node_render -->|"returns Swahili output"| node_user

click node_cli "https://github.com/nama-researchlab/sema/blob/main/src/bin/sema_cc.rs"
click node_lexicon "https://github.com/nama-researchlab/sema/blob/main/src/lexicon.rs"
click node_affix "https://github.com/nama-researchlab/sema/blob/main/src/affix/mod.rs"
click node_lexdata "https://github.com/nama-researchlab/sema/blob/main/data/swahili.distilled.jsonl"
click node_racer "https://github.com/nama-researchlab/sema/blob/main/src/racer.rs"
click node_linearizer "https://github.com/nama-researchlab/sema/blob/main/src/linearizer.rs"
click node_rolodex "https://github.com/nama-researchlab/sema/blob/main/src/rolodex.rs"
click node_backpass "https://github.com/nama-researchlab/sema/blob/main/src/backpass.rs"
click node_synthdata "https://github.com/nama-researchlab/sema/blob/main/src/affix/sw.toml"
click node_render "https://github.com/nama-researchlab/sema/blob/main/src/render.rs"
click node_roles "https://github.com/nama-researchlab/sema/blob/main/src/linearizer.rs"

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_user toneBlue
class node_lexicon,node_racer,node_linearizer,node_roles toneAmber
class node_rolodex,node_backpass,node_render toneMint
class node_affix,node_lexdata,node_synthdata toneRose
class node_model,node_tena toneIndigo
```

## Components

### Interfaces

- [JSON CLI](https://github.com/nama-researchlab/sema/blob/main/src/bin/sema_cc.rs): `src/bin/sema_cc.rs`

### Forward Understanding

- [Lexicon lookup](https://github.com/nama-researchlab/sema/blob/main/src/lexicon.rs): `src/lexicon.rs`
- [Parse cascade](https://github.com/nama-researchlab/sema/blob/main/src/racer.rs): `src/racer.rs`
- [Sentence linearizer](https://github.com/nama-researchlab/sema/blob/main/src/linearizer.rs): `src/linearizer.rs`
- [Sentence roles](https://github.com/nama-researchlab/sema/blob/main/src/linearizer.rs): `src/linearizer.rs`

### Swahili Output

- [Intent synthesis](https://github.com/nama-researchlab/sema/blob/main/src/rolodex.rs): `src/rolodex.rs`
- [Back-pass engine](https://github.com/nama-researchlab/sema/blob/main/src/backpass.rs): `src/backpass.rs`
- [Bilingual renderer](https://github.com/nama-researchlab/sema/blob/main/src/render.rs): `src/render.rs`

### Language Data

- [Affix resolver](https://github.com/nama-researchlab/sema/blob/main/src/affix/mod.rs): `src/affix/mod.rs`
- [Distilled lexicon](https://github.com/nama-researchlab/sema/blob/main/data/swahili.distilled.jsonl): `data/swahili.distilled.jsonl`
- [Synthesis rules](https://github.com/nama-researchlab/sema/blob/main/src/affix/sw.toml): `src/affix/sw.toml`

### Other components

- **Swahili user**
- **English model**
- **Sema-Tena engine**

## Connections

- Swahili user → JSON CLI: submits text or intent
- JSON CLI → Lexicon lookup: loads and queries
- Lexicon lookup → Distilled lexicon: reads entries
- Lexicon lookup → Affix resolver: tries affixes
- JSON CLI → Parse cascade: races sentence
- Parse cascade → Lexicon lookup: resolves words
- Parse cascade → Sentence linearizer: decomposes verbs
- JSON CLI → Sentence linearizer: linearizes sentence
- Sentence linearizer → Sentence roles: assigns roles
- Sentence linearizer → English model: returns telegram
- English model → JSON CLI: provides structured intent
- JSON CLI → Intent synthesis: synthesizes intent
- Intent synthesis → Back-pass engine: uses synthesis
- Back-pass engine → Synthesis rules: loads rules
- Back-pass engine → Sema-Tena engine: delegates synthesis
- JSON CLI → Bilingual renderer: renders bilingual output
- Bilingual renderer → Lexicon lookup: builds gloss index
- Bilingual renderer → Swahili user: returns Swahili output