UCCA Generator Overview

UCCA Generator Overview

The UCCA Generator module creates semantic graph representations of Tibetan Buddhist texts using Claude LLMs. It provides two workflow options: a simple single-pass generator and an advanced iterative refinement workflow with commentary-based evaluation.

---

🎯 Purpose

1. Parse Tibetan Buddhist texts into structured semantic graphs
2. Capture semantic relationships between concepts, participants, and processes
3. Handle implicit content that is understood but not explicitly stated
4. Provide English translations at the node level
5. Refine graphs using scholarly commentaries (advanced workflow)

---

🏗️ Architecture

Two Workflow Options

1. Simple Workflow (workflow.py + ucca_generator.py)

Input Text → LLM Generation → JSON Parsing → UCCAGraph

• Single-pass generation
• No evaluation or refinement
• Good for quick processing

2. Advanced Agent Workflow (ucca_agent.py)

                    ┌─────────────────────────────────────┐
                    │                                     │
                    ▼                                     │
┌─────────┐    ┌────────────────┐    ┌────────────────┐  │
│  START  │───▶│ ucca_generator │───▶│ ucca_evaluator │──┤
└─────────┘    └────────────────┘    └────────────────┘  │
                                            │            │
                                     ┌──────┴──────┐     │
                                     │  route_ucca │     │
                                     └──────┬──────┘     │
                                            │            │
                              ┌─────────────┼─────────────┤
                              │             │             │
                              ▼             ▼             │
                         "Accepted"   "Rejected"          │
                              │             │             │
                              ▼             └─────────────┘
                           ┌─────┐              (feedback loop)
                           │ END │
                           └─────┘

Features:

• Iterative generation-evaluation loop
• Uses scholarly commentaries for evaluation
• Structured feedback with actionable suggestions
• Quality grading (bad/okay/good/great)
• Maximum 1 refinement iteration (configurable)

---

📦 Module Structure

ucca_generator/
├── __init__.py          # Package initialization
├── models.py            # Pydantic data models
├── workflow.py          # Simple generation workflow
├── ucca_agent.py        # Advanced iterative workflow
└── ucca_generator.py    # Pipeline entry point

File Responsibilities

File	Responsibility
models.py	Defines UCCANode, UCCAGraph, State, ActionableSuggestion, StructuredFeedback
workflow.py	generate_ucca_graph_step() - single-pass LLM generation
ucca_agent.py	Full LangGraph workflow with generation, evaluation, routing, and prompts
ucca_generator.py	run_ucca_generation_pipeline() - main entry point

---

🔄 Workflow Details

Simple Workflow Flow

1. Input: Tibetan text (optionally with English translation)
2. Prompt Construction: Uses UCCA_GENERATION_PROMPT_TEMPLATE with schema
3. LLM Invocation: Claude generates JSON response
4. JSON Cleaning: Strips markdown code blocks if present
5. Validation: Parses into UCCAGraph Pydantic model
6. Output: Validated graph or error message

Advanced Agent Workflow Flow

1. Input: Tibetan source text + commentaries + Sanskrit (optional)
2. Initial Generation: Uses get_ucca_generation_prompt()
3. Evaluation: Uses get_source_ucca_refinement_prompt() with commentaries
4. Grading: LLM assigns grade (bad/okay/good/great)
5. Routing:
   • If "great" or max iterations → Accept
   • Otherwise → Generate refined version with feedback
6. Refinement: Uses feedback to improve graph
7. Output: Final UCCAGraph with feedback history

---

🤖 LLM Configuration

Simple Workflow

llm = ChatAnthropic(model="claude-3-sonnet-latest", max_tokens=8192)

Advanced Agent Workflow

llm = ChatAnthropic(model="claude-3-7-sonnet-latest", max_tokens=8000)

---

📊 State Management

Both workflows use State TypedDict to track progress:

Simple Workflow State

class State(TypedDict):
    input_text: str
    ucca_graph_json_str: Optional[str]
    ucca_graph: Optional[UCCAGraph]
    error_message: Optional[str]

Advanced Agent State

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

---

🎓 UCCA Node Types

The system recognizes these semantic node types for Tibetan Buddhist texts:

Type	Description	Example
Parallel Scenes	Multiple scenes in parallel	Lists of attributes
Scene	Self-contained situation	Individual teaching
Participant-Agent	Entity performing action	The sage explaining
Participant-Patient	Entity receiving action	Concept being analyzed
Participant-Location	Where something occurs	Place of meditation
Participant-Goal	Purpose or aim	Enlightenment sought
Process	Main action or event	Act of meditation
State	Condition or situation	State of enlightenment
Adverbial	How a process occurs	Manner of practice
Linker	Connects scenes/participants	Transition words
Relator	Relates two entities	Teacher-student relation
Elaborator	Additional information	Commentary on concept
Implicit X	Conceptually present but unstated	Implied speaker

---

🚀 Usage Examples

Simple Workflow

from ucca_generator.ucca_generator import run_ucca_generation_pipeline

result = run_ucca_generation_pipeline("མི་རྟག་པ་སྒོམ་པ།")
if result['ucca_graph']:
    for node in result['ucca_graph'].nodes:
        print(f"{node.id}: {node.type} - {node.english_text}")

Advanced Agent Workflow

from ucca_generator.ucca_agent import optimizer_workflow

initial_state = {
    "source": "མི་རྟག་པ་སྒོམ་པ།",
    "sanskrit": "",
    "language": "Tibetan",
    "feedback_history": [],
    "commentary1": "First commentary text...",
    "commentary2": "Second commentary text...",
    "commentary3": "Third commentary text...",
    "itteration": 0,
    "format_iteration": 0,
    "source_ucca": [],
    "latest_structured_suggestions": [],
    "grade": ""
}

result = optimizer_workflow.invoke(initial_state)
final_graph = result["source_ucca"][-1]

---

⚠️ Important Notes

1. Commentaries are crucial for the advanced workflow - they guide semantic evaluation
2. Implicit content should be marked with proper composite tags (e.g., "Implicit Participant-Agent")
3. Parent-child relationships must form a valid DAG (no cycles)
4. Root node must have empty string "" for parent_id
5. All node IDs in children arrays must exist in the nodes list