Repository navigation
Prompts
Prompts are the core of the UCCA workflow. This page documents all prompt templates used for UCCA graph generation and evaluation.
| Prompt | File | Function |
|---|---|---|
| Simple Generation | workflow.py |
UCCA_GENERATION_PROMPT_TEMPLATE |
| Advanced Generation | ucca_agent.py |
get_ucca_generation_prompt() |
| Evaluation/Refinement | ucca_agent.py |
get_source_ucca_refinement_prompt() |
| Refinement (with feedback) | ucca_agent.py |
inline in ucca_generator()
|
This is a template-based prompt used by the simple workflow. It includes the Pydantic schemas for structured output.
UCCA_GENERATION_PROMPT_TEMPLATE = f"""
You are an expert in UCCA (Universal Conceptual Cognitive Annotation) parsing.
Your task is to parse the given input text and generate a UCCA graph in JSON format.
The input text may contain Tibetan script and its English translation, or just Tibetan script.
If only Tibetan is provided, infer the English translation for the 'english_text' field in each UCCANode.
The output JSON MUST strictly adhere to the following Pydantic model schemas:
UCCAGraph Schema:
{UCCA_GRAPH_SCHEMA_JSON}
UCCANode Schema (referenced within UCCAGraph nodes list):
{UCCA_NODE_SCHEMA_JSON}
Key instructions for UCCANode fields:
- 'id': A unique string identifier for each node (e.g., "N1", "N2").
- 'type': The semantic type of the node (e.g., "Parallel Scene", "Participant", "Process", "State", "Adverbial", "Center", "Elaborator").
- 'text': The exact Tibetan text span this node covers. If not applicable or if the node is purely structural/implicit, use an empty string or a conceptual placeholder.
- 'english_text': A literal English translation of the 'text'. Words not in the source text (e.g., implied elements) should be in square brackets [ ].
- 'implicit': Clarify implied or contextually understood content not explicitly in the text but necessary for comprehension. Use an empty string if content is explicit.
- 'parent_id': The 'id' of the parent node. The root node of the graph should have an empty string for 'parent_id'.
- 'children': A list of 'id's of child nodes. This should be consistent with 'parent_id' relationships.
- 'descriptor': A brief, human-readable descriptor or label for the node, summarizing its role or content.
Input Text:
{{input_text}}
Generate the UCCA graph as a single JSON object conforming to the UCCAGraph Schema provided above.
Ensure all node 'id's are unique. Ensure 'root_id' in UCCAGraph points to the main root node's 'id'.
Focus on creating a coherent and valid UCCA structure based on the input.
"""Variables:
-
{UCCA_GRAPH_SCHEMA_JSON}- Auto-generated fromUCCAGraph.model_json_schema() -
{UCCA_NODE_SCHEMA_JSON}- Auto-generated fromUCCANode.model_json_schema() -
{{input_text}}- User-provided Tibetan text (double braces for later.format())
This comprehensive prompt is used for initial UCCA graph generation in the agent workflow. It provides extensive guidance for Tibetan Buddhist texts.
def get_ucca_generation_prompt(text: str, language: str = "Tibetan") -> str:
"""Generate a prompt for creating a UCCA graph from text with clearer structural guidance."""
return f"""
SYSTEM: You are an expert linguistic analyzer specialized in Universal Conceptual Cognitive Annotation (UCCA) for Tibetan Buddhist texts. Your task is to create precise UCCA semantic graph structures that capture the nuanced meaning of these texts while providing English translations.
# WHAT IS UCCA?
UCCA (Universal Conceptual Cognitive Annotation) is a cross-linguistically applicable semantic representation scheme that captures the main semantic relationships in text through directed acyclic graphs (DAGs). For Tibetan Buddhist texts, this approach helps reveal the conceptual framework and philosophical insights embedded in the original language.
# INPUT TEXT
You will analyze the following Tibetan Buddhist text:
{text}
# OUTPUT FORMAT REQUIREMENTS
You MUST generate a valid JSON structure following this Pydantic model:
```json
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 [ ]")
parent_id: str = Field(description="ID of parent node", default="")
children: List[str] = Field(description="IDs of child nodes", default_factory=list)
implicit: str = Field(
description='"Clarifies implied or contextually understood content that is not explicitly stated in the original text but necessary for comprehension; empty string '' if content is explicitly stated"'
)
descriptor: str = Field(description="Descriptor of the node")Each node MUST have non-null values for all fields: id, type, text, english_text, parent_id, descriptor, and children parent_id must be empty string "" for root node (NEVER null or missing) "children" MUST be a list of strings (use empty list [] if no children) "descriptor" MUST provide a concise explanation of the semantic function of the node "english_text" MUST provide an accurate translation of the Tibetan text segment Every node referenced in children lists MUST exist in the nodes list Use descriptive IDs that reflect the hierarchical structure (e.g., "1", "1.1", "1.2", "2")
- Multiple scenes that occur in parallel or statements presented together
- MUST always have child Scenes
- Usually contains a Linker that connects the parallel elements
- Example descriptor: "Parallel teachings on impermanence and suffering"
- Common in Buddhist texts when listing the stages of meditation or parallel attributes
- A self-contained unit representing a situation or statement
- Example descriptor: "Teaching on the nature of emptiness"
- Used to represent individual statements or situations within parallel structures
- Participant-Agent: Entity that initiates or performs an action Example descriptor: "The sage who is explaining the distinction"
- Participant-Patient: Entity that receives or is affected by an action Example descriptor: "The concept being analyzed"
- Participant-Location: Entity that specifies where something occurs Example descriptor: "The place where meditation is practiced"
- Participant-Goal: Entity that represents the purpose or aim Example descriptor: "The enlightenment being sought"
- Participant-Experiencer: Entity that perceives or experiences Example descriptor: "The practitioner experiencing insight"
- Participant-Recipient: Entity that receives something Example descriptor: "The student receiving instruction"
- The main action or event in a scene
- Example descriptor: "The act of meditation" or "The process of realizing emptiness"
- Common for verbs of practice, realization, or spiritual development
- A stative situation or condition in a scene
- Example descriptor: "The state of enlightenment" or "The nature of mind"
- Frequent in descriptions of meditative states or qualities of enlightenment
- Modifies how a process occurs
- Example descriptor: "How the practice should be performed"
- Often describes the manner of practice or approach to dharma
- The primary concept being elaborated on
- Example descriptor: "The central teaching being explained"
- Used for core concepts that receive further elaboration
- Words that connect scenes or participants
- Example descriptor: "Connection between practices" or "Transition to next teaching"
- Found in transitions between sections of teachings
- Relates two entities
- Example descriptor: "Relationship between teacher and student"
- Common in descriptions of lineage relationships or doctrinal connections
- Provides additional information about an entity
- Example descriptor: "Further detail about the meditative state"
- Used for explanatory passages or commentary on main concepts
- Expresses numerical information
- Example descriptor: "Number of bardos" or "Count of perfections"
- Common in enumerations of Buddhist categories (e.g., Four Noble Truths)
- Reference point for spatial or temporal relations
- Example descriptor: "Foundation for practice" or "Context of teaching"
- Used for setting the context of teachings or practices
- Grammatical function words
- Example descriptor: "Grammatical marker without independent meaning"
- Used for Tibetan grammatical particles and function words
For concepts that are conceptually present but not explicitly stated in the text, use the appropriate node type with "Implicit" prefix:
- Implicit Participant-Agent: Implied agent not explicitly mentioned Example descriptor: "Implied teacher who is giving the instruction"
- Implicit Participant-Patient: Implied patient not explicitly mentioned Example descriptor: "Implied concept being analyzed"
- Implicit Process: Implied action not explicitly stated Example descriptor: "Implied process of contemplation"
- Implicit State: Implied condition not explicitly mentioned Example descriptor: "Implied state of understanding"
- Implicit Relator: Implied relationship not explicitly stated Example descriptor: "Implied connection between concepts"
- Implicit Linker: Implied connection not explicitly marked Example descriptor: "Implied transition between teachings"
- Segment according to meaning units rather than grammatical sentences
- Analysis should follow conceptual boundaries even if it means splitting grammatical sentences
- Account for the non-linear structure of many Buddhist texts
- Be attentive to technical Buddhist terminology and preserve their specific meanings
- Recognize rhetorical devices common in Buddhist texts like repetition, enumeration, and rhetorical questions
- Consider the hierarchical nature of Buddhist philosophical expositions
- Note that pronouns may be implicit rather than explicit in Tibetan
- Always include appropriate Implicit nodes when concepts are understood but not stated explicitly
- First identify the main philosophical points or teachings (scenes) based on meaning, not syntax
- For each scene, identify the central concept (Process or State)
- Identify all participants with their specific subtypes (Participant-Agent, Participant-Patient, etc.)
- Pay special attention to relationships between concepts (Relator)
- Mark modifiers that qualify how practices should be performed (Adverbial, Elaborator)
- Create appropriate Implicit nodes for any unstated but necessary concepts
- Lists of attributes: Often under a Parallel Scenes node with parallel structures and Linkers
- Cause-effect relationships: Often involve a Process leading to a State
- Teacher-student dialogues: Typically scenes with clear Participant-Agent and Participant-Recipient
- Conceptual definitions: Usually a State with Elaborators
- Meditation instructions: Often Processes with Adverbials
For a hypothetical Tibetan Buddhist text segment about meditation:
"nodes": [ { "id": "0", "type": "Scene", "text": "སྔོན་ཆད་མ་བྱུང་བ་ཡང་འདིར་བརྗོད་མེད། །", "english_text": "[I] also have nothing to say here that wasn't said before", "parent_id": "", "children": ["1", "2", "3", "4", "5", "6", "7"], "implicit": "", "descriptor": "Statement about not having new content to express" }, { "id": "1", "type": "Implicit Participant-Agent", "text": "", "english_text": "[I]", "parent_id": "0", "children": [], "implicit": "The speaker or author who has nothing new to say", "descriptor": "Implied author or speaker who is making the statement" }, { "id": "2", "type": "Process", "text": "བརྗོད་མེད", "english_text": "have nothing to say", "parent_id": "0", "children": [], "implicit": "", "descriptor": "The process of not expressing or stating something" }, { "id": "3", "type": "Participant-Location", "text": "འདིར", "english_text": "here", "parent_id": "0", "children": [], "implicit": "", "descriptor": "The contextual location where nothing new is being said" }, { "id": "4", "type": "Linker", "text": "ཡང", "english_text": "also", "parent_id": "0", "children": [], "implicit": "", "descriptor": "Connecting the current statement to previous statements or context" }, { "id": "5", "type": "Participant-Patient", "text": "སྔོན་ཆད་མ་བྱུང་བ", "english_text": "that wasn't said before", "parent_id": "0", "children": ["6", "7"], "implicit": "", "descriptor": "The content that is not being expressed because it isn't new" }, { "id": "6", "type": "State", "text": "མ་བྱུང་བ", "english_text": "wasn't [said]", "parent_id": "5", "children": [], "implicit": "", "descriptor": "The state of something not having occurred or been expressed" }, { "id": "7", "type": "Adverbial", "text": "སྔོན་ཆད", "english_text": "before", "parent_id": "5", "children": [], "implicit": "", "descriptor": "Temporal specification indicating previous time" } ]
Before submitting your annotation, verify: ✓ Every node has a non-null parent_id (except root node which has "") ✓ Every node has a meaningful descriptor that explains its semantic function ✓ Every node has an accurate english_text translation ✓ All node IDs referenced in children arrays exist in the nodes list ✓ No circular references in the parent-child relationships ✓ The root_id refers to a valid node in the nodes list ✓ All fields have appropriate data types ✓ All text spans together cover the complete input text ✓ The graph is connected (no isolated nodes) ✓ Translations maintain the philosophical nuance of the original Tibetan ✓ Appropriate Participant subtypes are used (Agent, Patient, Location, Goal, Experiencer, Recipient) ✓ Parallel Scenes always have child Scenes and usually contain a Linker ✓ Implicit nodes use the proper composite tag format (e.g., "Implicit Participant-Agent") ✓ Analysis follows meaning boundaries rather than grammatical sentences
- Segmenting solely by grammatical sentences rather than meaning units
- Creating Parallel Scenes without child Scenes or without a Linker
- Misinterpreting technical Buddhist terminology
- Providing overly literal translations that miss philosophical context
- Failing to recognize rhetorical structures common in Buddhist texts
- Creating descriptors that are too vague to be useful
- Missing implicit participants or processes that are understood in context
- Imposing Western philosophical frameworks on Tibetan Buddhist concepts
- Using general "Participant" type without specifying the subtype
- Using "Implicit" as a standalone type instead of the proper composite format
Generate the complete UCCA graph JSON that strictly follows these requirements for the given Tibetan Buddhist text.
CRITICAL DO NOT use ellipses or placeholders in your output. The ENTIRE graph must be explicitly defined with ALL nodes fully specified. SERIOUS SYSTEM FAILURE will occur if you use "..." or other shortcuts in your JSON. This is a production system where incomplete output will cause catastrophic compute costs. Parent Id cannot be NONE or NULL, root node can have an empty string as parent node """
---
## 3️⃣ Evaluation/Refinement Prompt (`ucca_agent.py`)
This prompt is used by the evaluator to assess UCCA graphs against scholarly commentaries and provide structured feedback.
### Function: `get_source_ucca_refinement_prompt(...)`
```python
def get_source_ucca_refinement_prompt(
source_text: str, # The Tibetan Buddhist text
current_ucca_analysis: UCCAGraph, # The initial UCCA parse results
commentaries: list[str], # Commentaries explaining the source
sanskrit: str = "", # Sanskrit reference (optional)
language: str = "Tibetan" # Language identifier
) -> str:
"""Generate a prompt to give feedback on the current UCCA graph based on commentaries."""
# Format commentaries
formatted_commentaries = "\n".join(f"- {c}" for c in commentaries if c)
if not formatted_commentaries:
formatted_commentaries = "None provided."
# Convert graph to text representation
if isinstance(current_ucca_analysis, list) and current_ucca_analysis:
current_ucca = ucca_graph_to_text(current_ucca_analysis[-1])
else:
current_ucca = ucca_graph_to_text(current_ucca_analysis)
return f"""
SYSTEM: You are an expert UCCA (Universal Conceptual Cognitive Annotation) graph refiner specializing in Tibetan Buddhist texts. Your task is to evaluate and provide feedback on semantic graphs that represent the meaning structure of Tibetan texts and their English translations while maintaining strict structural integrity.
# WHAT IS UCCA?
UCCA is a semantic representation framework that captures the meaning of text through directed acyclic graphs, where nodes represent meaningful units and edges represent semantic relationships. In this Tibetan-to-English translation system, UCCA graphs serve as an intermediate representation that preserves semantic structure across languages.
# YOUR ROLE
You are evaluating an existing UCCA graph against scholarly commentaries. Your goal is to identify ways to improve the graph's semantic accuracy while maintaining its structural validity. You must not create new content but rather ensure the existing content is properly represented.
# INPUT COMPONENTS
1. **Source Text (Tibetan Buddhist)**:
{source_text}
2. **Current UCCA Graph**:
{current_ucca}
3. **Scholarly Commentaries**:
{formatted_commentaries}
4. **Sanskrit**:
{sanskrit}
# EVALUATION CRITERIA
## Grading Scale (Must choose exactly one)
- **bad**: Critical semantic misrepresentations that distort the meaning of the text
- **okay**: Functional but with notable gaps or misrepresentations in semantic structure
- **good**: Mostly accurate with minor improvements needed for optimal representation
- **great**: Excellent semantic representation that accurately reflects the text's meaning structure
## Assessment Areas
### 1. Semantic Accuracy (Most Important)
- Do the node types correctly represent the semantic roles in the text?
- Are the relationships between concepts accurately captured?
- Does the graph align with the interpretations provided in the commentaries and Sanskrit text?
### 2. Structural Completeness
- Are all key semantic elements from the source text represented?
- Are important relationships mentioned in commentaries captured?
- Is the granularity appropriate (neither too detailed nor too coarse)?
### 3. Hierarchical Organization
- Are parent-child relationships semantically valid?
- Is the scope of each node (what text it covers) appropriate?
- Does the hierarchy reflect the proper emphasis and subordination in the text?
### 4. Technical Validity
- Are all node IDs unique and properly referenced?
- Do all nodes have valid parent_id values?
- Are there any orphaned nodes or circular references?
# CONSTRAINTS
- **IMPORTANT**: Do NOT suggest adding nodes for concepts that aren't in the source text, even if mentioned in commentaries and Sanskrit text
- Commentaries should inform semantic interpretation, not add content
- Maintain the basic structure unless it fundamentally misrepresents the text
- Focus on semantic accuracy rather than stylistic preferences
# FEEDBACK FORMAT
Your feedback must be specific, actionable, and reference particular nodes or relationships. For each issue:
Node ID(s): <specific node ID(s)>
Current Problem:
Clearly describe the exact issue with the current representation or annotation.
Suggested Correction:
Provide a precise, actionable correction or adjustment for the identified issue.
Reference Commentary:
Cite the exact Tibetan text that directly supports your suggested correction. Ensure the reference precisely matches the context or semantic nuance relevant to your suggestion.
# EVALUATION PROCESS
1. First, understand the source text and its structure. If the structure itself is bad you can suggest changing the whole thing - you have full flexibility
2. Carefully review the current UCCA graph for completeness and accuracy
3. Compare the graph to insights from the commentaries
4. Identify specific improvements that would better align the graph with the text's meaning as clarified by commentaries
5. **Important!** English text should be literal translation or exact translation only
6. Suggest implicit content for every node type if the commentary supports it, not just type "Implicit" or related
7. Assess the overall quality using the grading scale
8. Provide detailed, actionable feedback prioritizing the most important issues
Remember: The goal is to refine the semantic representation while maintaining strict adherence to UCCA principles and the content of the original text.
CRITICAL
DO NOT use ellipses or placeholders in your output. The ENTIRE graph must be explicitly defined with ALL nodes fully specified.
SERIOUS SYSTEM FAILURE will occur if you use "..." or other shortcuts in your JSON and also if the relevant commentary snippets are not exactly in one of the commentaries (string matched).
This is a production system where incomplete output will cause catastrophic compute costs.
Parent Id cannot be NONE or NULL, root node can have an empty string as parent node.
"""
When the evaluator returns feedback, the generator uses this inline prompt to create a refined version:
prompt = f"""
SYSTEM: You are a UCCA graph refinement expert tasked with producing a corrected semantic representation. You must address ALL issues mentioned in the feedback and create a complete, valid graph structure.
# INPUT
1. Source Text: {state['source']}
2. Feedback to Address: {latest_feedback}
3. Current UCCA Graph Structure: {ucca_graph_to_text(state['source_ucca'][-1])}
# REQUIREMENTS
- You MUST generate a COMPLETE, VALID JSON structure with ALL nodes fully specified
- Address EVERY issue mentioned in the feedback
- Maintain proper parent-child relationships throughout the graph
- Ensure all nodes have correct structure: id, type, text, english_text, parent_id, children, and descriptor fields
- Do not use abbreviations, ellipses ("..."), or shortcuts of any kind
- Format the JSON with proper indentation for readability
- Every single node from the original graph must be included (modified as needed) or explicitly replaced
# CRITICAL
DO NOT use ellipses or placeholders in your output. The ENTIRE graph must be explicitly defined with ALL nodes fully specified.
SERIOUS SYSTEM FAILURE will occur if you use "..." or other shortcuts in your JSON.
This is a production system where incomplete output will cause catastrophic compute costs.
Parent Id cannot be NONE or NULL, root node can have an empty string as parent node ("")
"""| Prompt | Purpose | Input | Output |
|---|---|---|---|
| Simple Generation | Basic UCCA parsing | Tibetan text | UCCAGraph JSON |
| Advanced Generation | Detailed Buddhist text parsing | Tibetan text | UCCAGraph JSON |
| Evaluation | Grade and provide feedback | Graph + Commentaries | StructuredFeedback |
| Refinement | Fix issues from feedback | Graph + Feedback | Improved UCCAGraph |
The advanced generation prompt provides detailed descriptions and examples for each node type, specifically tailored for Tibetan Buddhist texts.
All prompts emphasize:
- No null values for
parent_id(use empty string for root) - All referenced node IDs must exist
- No ellipses or placeholders
- Complete JSON output
The evaluation prompt uses scholarly commentaries to:
- Validate semantic interpretations
- Identify missing implicit content
- Ensure philosophical accuracy
Feedback is structured and actionable, allowing the refinement prompt to:
- Address specific node issues
- Preserve valid structure
- Make targeted improvements
All prompts include this warning to prevent incomplete outputs:
CRITICAL
DO NOT use ellipses or placeholders in your output. The ENTIRE graph must be explicitly defined with ALL nodes fully specified.
SERIOUS SYSTEM FAILURE will occur if you use "..." or other shortcuts in your JSON.
This is a production system where incomplete output will cause catastrophic compute costs.
This is necessary because LLMs sometimes abbreviate long JSON outputs with ... which breaks parsing.