Skip to content

Translator Models

Jump to bottom
TenzinGayche edited this page Dec 17, 2025 · 1 revision

Translator Models

This page documents all Pydantic models and TypedDicts used in tibetan_translator and tibetan_translator_v2.

📍 Location

Models are defined in tibetan_translator/models.py (shared by both versions).

🧩 Core Models

CommentaryVerification

Verifies translation against commentary.

class CommentaryVerification(BaseModel):
    matches_commentary: bool = Field(
        description="Whether the translation fully aligns with all key points from the commentary"
    )
    missing_concepts: str = Field(
        description="List of concepts from commentary that are missing or incorrectly translated"
    )
    misinterpretations: str = Field(
        description="List of any concepts that were translated in ways that contradict the commentary"
    )
    context_accuracy: str = Field(
        description="Verification of key contextual elements mentioned in commentary"
    )

Usage: Returned by verify_against_commentary() function.

GlossaryEntry

Single glossary term.

class GlossaryEntry(BaseModel):
    tibetan_term: str = Field(
        description="Original Tibetan term"
    )
    translation: str = Field(
        description="Exact translation used in the target language"
    )
    context: str = Field(
        description="Context or usage notes in the target language"
    )
    entity_category: str = Field(
        description="Entity category (e.g., person, place, etc.) in the target language, if not entity then leave it blank"
    )
    commentary_reference: str = Field(
        description="Reference to commentary explanation in the target language"
    )
    category: str = Field(
        description="Term category (philosophical, technical, etc.) in the target language"
    )

Example:

entry = GlossaryEntry(
    tibetan_term="བྱང་ཆུབ་སེམས",
    translation="bodhicitta",
    context="The mind of enlightenment, the aspiration to attain Buddhahood",
    entity_category="",
    commentary_reference="From Śāntideva's Bodhicaryāvatāra",
    category="philosophical"
)

GlossaryExtraction

Container for extracted glossary.

class GlossaryExtraction(BaseModel):
    entries: List[GlossaryEntry] = Field(
        description="List of extracted glossary entries"
    )
    
    @field_validator('entries', mode='before')
    @classmethod
    def validate_entries(cls, v: Any) -> List[GlossaryEntry]:
        """Validator to handle string inputs for entries field.
        
        Important for Chinese and other non-Latin languages where
        JSON parsing might return a string instead of a list.
        """
        if isinstance(v, list):
            return v
        if isinstance(v, str):
            parsed = json.loads(v)
            if isinstance(parsed, list):
                return parsed
            raise ValueError(f"Expected a list, got {type(parsed)}")
        raise ValueError(f"entries must be a list or JSON string")

LanguageCheck

Verifies target language.

class LanguageCheck(BaseModel):
    is_target_language: bool = Field(
        description="Whether the translation is actually in the specified target language"
    )
    language_issues: str = Field(
        description="Description of any issues with the target language if not in target language",
        default=""
    )

Feedback

Comprehensive evaluation feedback.

class Feedback(BaseModel):
    is_target_language: bool = Field(
        description="Whether the translation is actually in the specified target language",
        default=True
    )
    language_issues: str = Field(
        description="Description of any issues with the target language if not in target language",
        default=""
    )
    grade: Literal["bad", "okay", "good", "great"] = Field(
        description="Evaluate translation quality based on accuracy and commentary alignment"
    )
    feedback: str = Field(
        description="Detailed feedback on improving translation based on commentary interpretation"
    )
    format_matched: bool = Field(
        description="Whether the translation structure matches the source structure (line count, verse form, paragraph breaks)",
        default=False
    )
    format_issues: str = Field(
        description="Specific formatting issues to address (if any)",
        default=""
    )

Grading Scale:

Grade Meaning
great Perfect alignment, correct formatting, natural fluency
good Minor deviations in content OR minor issues
okay Several misalignments, structural issues, or awkward language
bad Major divergence in content, structure, or poor fluency

Translation_extractor

Extracts translation from LLM response.

class Translation_extractor(BaseModel):
    extracted_translation: str = Field(
        "extracted translation with exact format from the Response"
    )

Translation

Translation with format information.

class Translation(BaseModel):
    format_matched: bool = Field(
        description="Evaluate if translation preserves source text's formatting such as linebreaks"
    )
    extracted_translation: str = Field(
        description="The translation maintaining all original formatting"
    )
    feedback_format: str = Field(
        description="Detailed guidance on matching source text formatting and only the formatting"
    )

KeyPoint

Single key point from commentary.

class KeyPoint(BaseModel):
    concept: str = Field(
        description="Core concept or interpretation"
    )
    terminology: List[str] = Field(
        description="Required terminology"
    )
    context: str = Field(
        description="Required contextual information"
    )
    implications: List[str] = Field(
        description="Philosophical implications"
    )

Example:

key_point = KeyPoint(
    concept="Impermanence as foundation of practice",
    terminology=["impermanence", "anicca", "mi rtag pa"],
    context="In the context of the four foundations of mindfulness",
    implications=[
        "Liberation from attachment",
        "Understanding of suffering"
    ]
)

CommentaryPoints

Container for key points.

class CommentaryPoints(BaseModel):
    points: List[KeyPoint] = Field(
        description="List of key points from commentary"
    )

📊 State TypedDict

The main workflow state.

class State(TypedDict):
    # === Translations ===
    translation: List[str]              # History of translation attempts
    plaintext_translation: str          # Plain text version
    
    # === Source ===
    source: str                         # Tibetan source text
    sanskrit: str                       # Sanskrit reference
    language: str                       # Target language (e.g., "English", "Chinese")
    
    # === Commentaries ===
    commentary1: str                    # First input commentary
    commentary2: str                    # Second input commentary
    commentary3: str                    # Third input commentary
    commentary1_translation: str        # Translated commentary 1
    commentary2_translation: str        # Translated commentary 2
    commentary3_translation: str        # Translated commentary 3
    combined_commentary: str            # Unified commentary/analysis
    commentary_source: str              # "traditional" or "source_analysis"
    
    # === Analysis ===
    key_points: List[KeyPoint]          # Key points from commentary
    glossary: List[GlossaryEntry]       # Extracted glossary terms
    
    # === Feedback ===
    feedback_history: List[str]         # All feedback from evaluations
    format_feedback_history: List[str]  # Format-specific feedback
    
    # === Control ===
    itteration: int                     # Translation iteration count
    format_iteration: int               # Format correction iteration
    formated: bool                      # Format status

V2 Additional State Fields

V2 extends the State with semantic analysis fields:

# Additional fields in V2
ucca: str                    # UCCA graph analysis
word_by_word: str            # Word-by-word translation
multilevel_summary: str      # Multi-level summary

📐 Example Instances

Full State Example

from tibetan_translator.models import State

initial_state: State = {
    # Source
    "source": "བོད་ཀྱི་བསྡུད་མ་འདུག",
    "sanskrit": "Buddhist text in Sanskrit",
    "language": "English",
    
    # Commentaries (V1)
    "commentary1": "First commentary text...",
    "commentary2": "Second commentary text...",
    "commentary3": "Third commentary text...",
    "commentary1_translation": "",
    "commentary2_translation": "",
    "commentary3_translation": "",
    "combined_commentary": "",
    "commentary_source": "",
    
    # Translations
    "translation": [],
    "plaintext_translation": "",
    
    # Analysis
    "key_points": [],
    "glossary": [],
    
    # Feedback
    "feedback_history": [],
    "format_feedback_history": [],
    
    # Control
    "itteration": 0,
    "format_iteration": 0,
    "formated": False,
}

Feedback Example

from tibetan_translator.models import Feedback

feedback = Feedback(
    is_target_language=True,
    language_issues="",
    grade="good",
    feedback="The translation captures the main meaning but could improve the phrasing in the second verse. Consider using 'impermanence' instead of 'non-permanence' for better fluency.",
    format_matched=True,
    format_issues=""
)

GlossaryEntry Example

from tibetan_translator.models import GlossaryEntry

entries = [
    GlossaryEntry(
        tibetan_term="བྱང་ཆུབ་སེམས",
        translation="bodhicitta",
        context="The mind of enlightenment",
        entity_category="",
        commentary_reference="From Śāntideva's explanation",
        category="philosophical"
    ),
    GlossaryEntry(
        tibetan_term="ཤེས་རབ",
        translation="wisdom",
        context="Transcendent understanding",
        entity_category="",
        commentary_reference="In context of perfections",
        category="philosophical"
    )
]

🔗 Model Relationships

State (TypedDict)
    │
    ├── translation: List[str]
    ├── key_points: List[KeyPoint]
    │                    │
    │                    └── concept, terminology, context, implications
    │
    └── glossary: List[GlossaryEntry]
                       │
                       └── tibetan_term, translation, context, 
                           commentary_reference, category, entity_category

Feedback (BaseModel)
    │
    └── Used by llm_call_evaluator()
        Returns: grade, feedback, format_matched, etc.

CommentaryVerification (BaseModel)
    │
    └── Used by verify_against_commentary()
        Returns: matches_commentary, missing_concepts, etc.

GlossaryExtraction (BaseModel)
    │
    └── Used by generate_glossary()
        Returns: entries: List[GlossaryEntry]

🔗 Related Pages

Clone this wiki locally