# kvsabhiram/anuvaad-sentence-generation-agent architecture

> Architecture diagram of the GitHub repository kvsabhiram/anuvaad-sentence-generation-agent, 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/kvsabhiram/anuvaad-sentence-generation-agent
- Repository: https://github.com/kvsabhiram/anuvaad-sentence-generation-agent

## Overview

Anuvaad Forge builds an English–Indic parallel training corpus in two independently resumable phases: generate and quality-gate English sentences for vocabulary, then translate and quality-gate them. The graph shows the documented handoff and principal runtime stages. Orchestrators and some agent implementations were only partially sampled, so uncertain internal calls are omitted; documented capabilities are retained where their modules are identified by the tree.

Main entry points: [`sentence_generation/pipeline/orchestrator.py`](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/pipeline/orchestrator.py) (Generation orchestrator), [`sentence_translation/pipeline/orchestrator.py`](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/pipeline/orchestrator.py) (Translation orchestrator), [`sentence_generation/main.py`](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/main.py) (Generation CLI), [`sentence_generation/agents/generator.py`](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/agents/generator.py) (Sentence generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Sentence generation"]
  node_gen_cli["Generation CLI<br/>[main.py]"]
  node_gen_orch["Generation orchestrator<br/>[orchestrator.py]"]
  node_word_reader["Vocabulary reader<br/>[excel.py]"]
  node_sentence_generator["Sentence generator<br/>[generator.py]"]
  node_sentence_judge["Sentence judge<br/>[judge.py]"]
end

subgraph group_translation["Sentence translation"]
  node_translation_cli["Translation CLI<br/>[main.py]"]
  node_translation_orch["Translation orchestrator<br/>[orchestrator.py]"]
  node_tier1["Tier 1 translator"]
  node_tier2["Tier 2 escalation"]
end

subgraph group_quality["Quality checks"]
  node_gen_validation["Sentence validation<br/>[validation.py]"]
  node_gen_dedup["Embedding dedup<br/>[similarity.py]"]
  node_gen_model["Embedding model<br/>[model.py]"]
  node_rule_checks["Translation rule checks<br/>[validation.py]"]
  node_translation_judge["Translation judge"]
  node_semantic_check["Semantic and dedup checks<br/>[similarity.py]"]
  node_translation_model["Cross-lingual model<br/>[model.py]"]
end

subgraph group_persistence["State and outputs"]
  node_gen_state[("Generation checkpoints<br/>[state.py]")]
  node_gen_output["Accepted sentences<br/>[jsonl.py]"]
  node_translation_state[("Translation checkpoints<br/>[state.py]")]
  node_translation_output["Parallel corpus<br/>[jsonl.py]"]
end

node_vocabulary["Vocabulary list"]
node_gen_provider{{"Generation LLMs"}}
node_translation_input["English sentences"]
node_gemini{{"Gemini service"}}
node_corpus_user(("Corpus consumer"))

node_vocabulary -->|"provides words"| node_gen_cli
node_gen_cli -->|"starts run"| node_gen_orch
node_gen_orch -->|"reads vocabulary"| node_word_reader
node_gen_orch -->|"requests candidates"| node_sentence_generator
node_sentence_generator -.->|"calls provider"| node_gen_provider
node_gen_orch -->|"validates candidates"| node_gen_validation
node_gen_orch -->|"filters duplicates"| node_gen_dedup
node_gen_dedup -->|"embeds sentences"| node_gen_model
node_gen_orch -->|"requests evaluations"| node_sentence_judge
node_sentence_judge -.->|"calls provider"| node_gen_provider
node_gen_orch -->|"checkpoints progress"| node_gen_state
node_gen_orch -->|"exports accepted"| node_gen_output
node_gen_output -->|"provides sentences"| node_translation_input
node_translation_input -->|"supplies input"| node_translation_cli
node_translation_cli -->|"starts run"| node_translation_orch
node_translation_orch -->|"requests translation"| node_tier1
node_tier1 -->|"submits batch"| node_gemini
node_translation_orch -->|"checks translations"| node_rule_checks
node_translation_orch -->|"requests evaluation"| node_translation_judge
node_translation_judge -->|"calls model"| node_gemini
node_translation_orch -->|"escalates failures"| node_tier2
node_tier2 -->|"calls model"| node_gemini
node_translation_orch -->|"checks meaning and duplicates"| node_semantic_check
node_semantic_check -->|"embeds text"| node_translation_model
node_translation_orch -->|"checkpoints progress"| node_translation_state
node_translation_orch -->|"exports accepted pairs"| node_translation_output
node_translation_output -->|"delivers corpus"| node_corpus_user

click node_gen_cli "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/main.py"
click node_gen_orch "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/pipeline/orchestrator.py"
click node_word_reader "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/storage/excel.py"
click node_sentence_generator "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/agents/generator.py"
click node_gen_validation "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/pipeline/validation.py"
click node_gen_dedup "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/embedding/similarity.py"
click node_gen_model "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/embedding/model.py"
click node_sentence_judge "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/agents/judge.py"
click node_gen_state "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/pipeline/state.py"
click node_gen_output "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/storage/jsonl.py"
click node_translation_cli "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/main.py"
click node_translation_orch "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/pipeline/orchestrator.py"
click node_tier1 "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/agents/translator_gemini.py"
click node_tier2 "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/agents/translator_gemini.py"
click node_rule_checks "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/pipeline/validation.py"
click node_translation_judge "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/agents/judge_translation_gemini.py"
click node_semantic_check "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/embedding/similarity.py"
click node_translation_model "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/embedding/model.py"
click node_translation_state "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/pipeline/state.py"
click node_translation_output "https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/storage/jsonl.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_gen_cli,node_gen_orch,node_word_reader,node_sentence_generator,node_sentence_judge toneBlue
class node_translation_cli,node_translation_orch,node_tier1,node_tier2 toneAmber
class node_gen_validation,node_gen_dedup,node_gen_model,node_rule_checks,node_translation_judge,node_semantic_check,node_translation_model toneMint
class node_gen_state,node_gen_output,node_translation_state,node_translation_output toneRose
class node_vocabulary,node_gen_provider,node_translation_input,node_gemini,node_corpus_user toneIndigo
```

## Components

### Sentence generation

- [Generation CLI](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/main.py): `sentence_generation/main.py`
- [Generation orchestrator](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/pipeline/orchestrator.py): `sentence_generation/pipeline/orchestrator.py`
- [Vocabulary reader](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/storage/excel.py): `sentence_generation/storage/excel.py`
- [Sentence generator](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/agents/generator.py): `sentence_generation/agents/generator.py`
- [Sentence judge](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/agents/judge.py): `sentence_generation/agents/judge.py`

### Sentence translation

- [Translation CLI](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/main.py): `sentence_translation/main.py`
- [Translation orchestrator](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/pipeline/orchestrator.py): `sentence_translation/pipeline/orchestrator.py`
- [Tier 1 translator](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/agents/translator_gemini.py): `sentence_translation/agents/translator_gemini.py`
- [Tier 2 escalation](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/agents/translator_gemini.py): `sentence_translation/agents/translator_gemini.py`

### Quality checks

- [Sentence validation](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/pipeline/validation.py): `sentence_generation/pipeline/validation.py`
- [Embedding dedup](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/embedding/similarity.py): `sentence_generation/embedding/similarity.py`
- [Embedding model](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/embedding/model.py): `sentence_generation/embedding/model.py`
- [Translation rule checks](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/pipeline/validation.py): `sentence_translation/pipeline/validation.py`
- [Translation judge](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/agents/judge_translation_gemini.py): `sentence_translation/agents/judge_translation_gemini.py`
- [Semantic and dedup checks](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/embedding/similarity.py): `sentence_translation/embedding/similarity.py`
- [Cross-lingual model](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/embedding/model.py): `sentence_translation/embedding/model.py`

### State and outputs

- [Generation checkpoints](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/pipeline/state.py): `sentence_generation/pipeline/state.py`
- [Accepted sentences](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_generation/storage/jsonl.py): `sentence_generation/storage/jsonl.py`
- [Translation checkpoints](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/pipeline/state.py): `sentence_translation/pipeline/state.py`
- [Parallel corpus](https://github.com/kvsabhiram/anuvaad-sentence-generation-agent/blob/main/sentence_translation/storage/jsonl.py): `sentence_translation/storage/jsonl.py`

### Other components

- **Vocabulary list**
- **Generation LLMs**
- **English sentences**
- **Gemini service**
- **Corpus consumer**

## Connections

- Vocabulary list → Generation CLI: provides words
- Generation CLI → Generation orchestrator: starts run
- Generation orchestrator → Vocabulary reader: reads vocabulary
- Generation orchestrator → Sentence generator: requests candidates
- Sentence generator → Generation LLMs: calls provider
- Generation orchestrator → Sentence validation: validates candidates
- Generation orchestrator → Embedding dedup: filters duplicates
- Embedding dedup → Embedding model: embeds sentences
- Generation orchestrator → Sentence judge: requests evaluations
- Sentence judge → Generation LLMs: calls provider
- Generation orchestrator → Generation checkpoints: checkpoints progress
- Generation orchestrator → Accepted sentences: exports accepted
- Accepted sentences → English sentences: provides sentences
- English sentences → Translation CLI: supplies input
- Translation CLI → Translation orchestrator: starts run
- Translation orchestrator → Tier 1 translator: requests translation
- Tier 1 translator → Gemini service: submits batch
- Translation orchestrator → Translation rule checks: checks translations
- Translation orchestrator → Translation judge: requests evaluation
- Translation judge → Gemini service: calls model
- Translation orchestrator → Tier 2 escalation: escalates failures
- Tier 2 escalation → Gemini service: calls model
- Translation orchestrator → Semantic and dedup checks: checks meaning and duplicates
- Semantic and dedup checks → Cross-lingual model: embeds text
- Translation orchestrator → Translation checkpoints: checkpoints progress
- Translation orchestrator → Parallel corpus: exports accepted pairs
- Parallel corpus → Corpus consumer: delivers corpus