Skip to content

Data Models

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

Data Models

This page documents all Pydantic models and TypedDicts used in the UCCA Generator module.

📍 Location

Models are defined in:

  • ucca_generator/models.py - Core shared models
  • ucca_generator/ucca_agent.py - Extended State for agent workflow

🧩 Core Models

UCCANode

Represents a single node in the UCCA semantic graph.

class UCCANode(BaseModel):
    id: str = Field(
        description="Unique identifier for the node"
    )
    type: str = Field(
        description="Node type (e.g., Parallel Scenes, Participants, Process, etc.)"
    )
    text: str = Field(
        description="Text span covered by this node"
    )
    english_text: str = Field(
        description="Literal English translation of the node, "
                    "Words not in the source text are put in square brackets [ ]"
    )
    implicit: str = Field(
        description='Clarifies implied or contextually understood content that is not '
                    'explicitly stated in the original text but necessary for comprehension; '
                    'use an empty string if content is explicitly stated.'
    )
    parent_id: str = Field(
        description="ID of parent node", 
        default=""
    )
    children: List[str] = Field(
        description="IDs of child nodes", 
        default_factory=list
    )
    descriptor: str = Field(
        description="Descriptor of the node"
    )

Field Details

Field Type Required Description
id str ✅ Unique identifier (e.g., "1", "1.1", "N1")
type str ✅ Semantic type (see Node Types below)
text str ✅ Original Tibetan text span
english_text str ✅ English translation with [implied words] in brackets
implicit str ✅ Explanation of implied content, or empty string
parent_id str ❌ Parent node ID; empty "" for root
children List[str] ❌ List of child node IDs
descriptor str ✅ Human-readable description of node's role

Valid Node Types

Primary Types:

  • Parallel Scenes - Multiple parallel scenes (must have child Scenes)
  • Scene - Self-contained situation
  • Process - Action or event
  • State - Condition or situation
  • Adverbial - Modifier of how process occurs
  • Center - Primary concept being elaborated
  • Linker - Connects scenes or participants
  • Relator - Relates two entities
  • Elaborator - Additional information
  • Quantity - Numerical information
  • Ground - Reference point
  • Function - Grammatical function words

Participant Subtypes:

  • Participant-Agent - Performs action
  • Participant-Patient - Receives action
  • Participant-Location - Where something occurs
  • Participant-Goal - Purpose or aim
  • Participant-Experiencer - Perceives or experiences
  • Participant-Recipient - Receives something

Implicit Types (prefix any type with "Implicit"):

  • Implicit Participant-Agent
  • Implicit Process
  • Implicit State
  • etc.

UCCAGraph

Container for a complete UCCA graph.

class UCCAGraph(BaseModel):
    nodes: List[UCCANode] = Field(
        description="List of UCCA nodes in the graph"
    )
    root_id: str = Field(
        description="ID of the root node"
    )

Validation Rules

  1. root_id must reference an existing node in nodes
  2. All children IDs must reference existing nodes
  3. No circular references allowed
  4. Root node must have parent_id = ""
  5. Graph must be connected (no orphaned nodes)

📝 Feedback Models

ActionableSuggestion

Represents a specific improvement suggestion for the UCCA graph.

class ActionableSuggestion(BaseModel):
    suggestion_type: str = Field(
        description="Type of corrective action suggested "
                    "(e.g., 'SPLIT_NODE', 'MERGE_NODES', 'CHANGE_NODE_TYPE', "
                    "'ADD_RELATION', 'MODIFY_RELATION_LABEL', 'ADD_IMPLICIT_CONTENT')"
    )
    target_node_ids: Optional[List[str]] = Field(
        default_factory=list, 
        description="IDs of the UCCA nodes primarily affected by this suggestion. "
                    "Can be empty if the suggestion is general."
    )
    description: str = Field(
        description="Detailed explanation of the suggestion and its rationale."
    )
    relevant_commentary_snippets: Optional[List[str]] = Field(
        default_factory=list, 
        description="List of exact text spans copied verbatim from the commentary "
                    "that directly support this suggestion. These must match the "
                    "commentary word-for-word without modification."
    )

Suggestion Types

Type Description
SPLIT_NODE Divide one node into multiple
MERGE_NODES Combine multiple nodes
CHANGE_NODE_TYPE Change semantic type
ADD_RELATION Add new relationship
MODIFY_RELATION_LABEL Change relationship type
ADD_IMPLICIT_CONTENT Add implicit node

StructuredFeedback

Complete evaluation result with grade and suggestions.

class StructuredFeedback(BaseModel):
    grade: Literal["bad", "okay", "good", "great"] = Field(
        description="Overall quality grade of the UCCA graph."
    )
    overall_summary: str = Field(
        description="A brief textual summary of the evaluation, "
                    "highlighting key strengths and weaknesses."
    )
    specific_suggestions: List[ActionableSuggestion] = Field(
        default_factory=list,
        description="A list of specific, actionable suggestions for improvement. "
                    "This list can be empty if the grade is 'great' or no specific "
                    "changes are needed."
    )

Grading Scale

Grade Meaning
bad Critical semantic misrepresentations
okay Functional but notable gaps
good Mostly accurate, minor improvements needed
great Excellent representation, ready to accept

🔄 State Models

Simple Workflow State

Used by workflow.py and ucca_generator.py:

class State(TypedDict):
    input_text: str                      # Input Tibetan text
    ucca_graph_json_str: Optional[str]   # Raw JSON from LLM
    ucca_graph: Optional[UCCAGraph]      # Parsed graph
    error_message: Optional[str]         # Error if any

Agent Workflow State

Used by ucca_agent.py for iterative refinement:

class State(TypedDict):
    source: str                          # Tibetan source text
    sanskrit: str                        # Sanskrit reference (optional)
    language: str                        # Language identifier
    feedback_history: List[str]          # All feedback from evaluations
    commentary1: str                     # First scholarly commentary
    commentary2: str                     # Second scholarly commentary
    commentary3: str                     # Third scholarly commentary
    itteration: int                      # Current iteration count
    format_iteration: int                # Format correction iteration
    source_ucca: List[UCCAGraph]         # History of all generated graphs
    latest_structured_suggestions: List[ActionableSuggestion]
    grade: str                           # Latest quality grade

State Field Details

Field Purpose
source The Tibetan Buddhist text to analyze
sanskrit Optional Sanskrit reference for evaluation
commentary1/2/3 Scholarly commentaries for semantic guidance
feedback_history Accumulated feedback strings from all iterations
source_ucca List of graphs; latest is source_ucca[-1]
itteration Tracks refinement cycles (max 1 by default)
grade Current quality assessment

📐 Example Instances

UCCANode Example

node = UCCANode(
    id="1",
    type="Process",
    text="བརྗོད་མེད",
    english_text="have nothing to say",
    implicit="",
    parent_id="0",
    children=[],
    descriptor="The process of not expressing or stating something"
)

UCCAGraph Example

graph = UCCAGraph(
    nodes=[
        UCCANode(
            id="0",
            type="Scene",
            text="སྔོན་ཆད་མ་བྱུང་བ་ཡང་འདིར་བརྗོད་མེད།",
            english_text="[I] also have nothing to say here that wasn't said before",
            implicit="",
            parent_id="",
            children=["1", "2", "3"],
            descriptor="Statement about not having new content"
        ),
        UCCANode(
            id="1",
            type="Implicit Participant-Agent",
            text="",
            english_text="[I]",
            implicit="The speaker or author who has nothing new to say",
            parent_id="0",
            children=[],
            descriptor="Implied author making the statement"
        ),
        # ... more nodes
    ],
    root_id="0"
)

StructuredFeedback Example

feedback = StructuredFeedback(
    grade="okay",
    overall_summary="The graph captures the main semantic structure but misses "
                    "the implicit agent and has incorrect participant subtypes.",
    specific_suggestions=[
        ActionableSuggestion(
            suggestion_type="ADD_IMPLICIT_CONTENT",
            target_node_ids=["0"],
            description="Add implicit speaker/author as Participant-Agent",
            relevant_commentary_snippets=["The author speaks in first person..."]
        ),
        ActionableSuggestion(
            suggestion_type="CHANGE_NODE_TYPE",
            target_node_ids=["2"],
            description="Change from 'Participant' to 'Participant-Location'",
            relevant_commentary_snippets=[]
        )
    ]
)

Clone this wiki locally