Workflow System

Workflow System

The Workflow System provides a flexible, combo-key based approach to running translation workflows with different combinations of inputs (UCCA, Gloss, commentaries, Sanskrit).

---

🎯 Overview

The workflow system allows you to:

1. Select inputs via a combo-key (e.g., source+ucca+gloss)
2. Provide optional context (commentaries, Sanskrit parallels)
3. Use custom prompts with placeholder substitution
4. Get translations optimized for the available context

---

🔑 Combo-Key System

What is a Combo-Key?

A combo-key is a +-separated string that specifies which inputs are available for translation. It determines the prompt template used.

Available Tokens

Token	Description	Required
source	Source Tibetan text	Always required
ucca	UCCA semantic graph	Optional
gloss	Gloss analysis	Optional
sanskrit	Sanskrit parallel text	Optional
commentaries0	No commentaries	Optional
commentaries1	One commentary	Optional
commentaries2	Two commentaries	Optional
commentaries3	Three commentaries	Optional

Combo-Key Examples

source                          → Basic translation (source only)
source+ucca                     → With UCCA semantic structure
source+gloss                    → With gloss analysis
source+ucca+gloss               → Full linguistic context
source+ucca+gloss+commentaries2 → With two commentaries
source+sanskrit                 → Cross-reference with Sanskrit
source+ucca+gloss+sanskrit+commentaries3 → Maximum context

Order Independence

Combo-keys are order-independent. These are all equivalent:

source+ucca+gloss
gloss+source+ucca
ucca+gloss+source

The system automatically canonicalizes (sorts) the key.

---

📝 Workflow Input

WorkflowInput Schema

class WorkflowInput(BaseModel):
    source: str                    # Required: Tibetan source text
    ucca: Optional[dict] = None    # UCCA graph JSON
    gloss: Optional[dict] = None   # Gloss analysis JSON
    commentaries: Optional[List[str]] = None  # Up to 3 commentaries
    sanskrit: Optional[str] = None # Sanskrit parallel
    target_language: Optional[str] = None     # Target language
    model: Optional[str] = None    # Model override

Example Request

{
  "combo_key": "source+ucca+gloss+commentaries2",
  "input": {
    "source": "བྱང་ཆུབ་སེམས་དཔའ་སེམས་ཅན་ཐམས་ཅད་ལ་སྙིང་རྗེ་བསྐྱེད།",
    "ucca": {
      "scenes": [
        {
          "process": "generate",
          "participants": ["bodhisattva", "all sentient beings"],
          "modifier": "compassion"
        }
      ]
    },
    "gloss": {
      "glossary": {
        "བྱང་ཆུབ་སེམས་དཔའ": "bodhisattva",
        "སྙིང་རྗེ": "compassion"
      }
    },
    "commentaries": [
      "This verse describes the bodhisattva's practice of generating compassion.",
      "The term 'all sentient beings' includes all forms of life without exception."
    ],
    "target_language": "english"
  },
  "model_name": "claude-sonnet-4-20250514"
}

---

🎨 Custom Prompts

Template Placeholders

You can provide a custom prompt template with these placeholders:

Placeholder	Description
{source}	Source text (required in custom prompts)
{ucca}	UCCA graph JSON
{gloss}	Gloss analysis JSON
{commentary1}	First commentary
{commentary2}	Second commentary
{commentary3}	Third commentary
{commentaries}	All commentaries as block
{sanskrit}	Sanskrit parallel text
{target_language}	Target language

Custom Prompt Example

{
  "combo_key": "source+gloss+sanskrit",
  "input": {
    "source": "བྱང་ཆུབ་སེམས",
    "gloss": {"glossary": {"བྱང་ཆུབ་སེམས": "bodhicitta"}},
    "sanskrit": "bodhicitta",
    "target_language": "english"
  },
  "custom_prompt": "You are an expert Buddhist translator.\n\nSource Text:\n{source}\n\nSanskrit Reference:\n{sanskrit}\n\nGlossary:\n{gloss}\n\nTranslate into {target_language}. Use the glossary for standardized terms. Return only the translation."
}

Validation

• {source} is required in custom prompts
• Other placeholders are optional
• Missing placeholders are replaced with empty strings

---

🔄 Workflow Flow

Request Processing

┌─────────────────────────────────────────────────────────────────┐
│                    Workflow Request                              │
│  combo_key: "source+ucca+gloss"                                 │
│  input: { source, ucca, gloss, ... }                            │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Canonicalize Combo-Key                          │
│  "source+ucca+gloss" → "gloss+source+ucca" (sorted)             │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Validate Inputs                               │
│  • source present? ✓                                            │
│  • ucca in key → ucca input provided? ✓                         │
│  • gloss in key → gloss input provided? ✓                       │
│  • commentaries count matches? ✓                                │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Build Prompt                                   │
│  • Use custom_prompt if provided                                │
│  • Otherwise build default prompt from inputs                   │
│  • Add translation guidelines                                    │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Invoke LLM                                    │
│  model.ainvoke(combined_prompt)                                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Return Response                               │
│  { "combo_key": "gloss+source+ucca", "translation": "..." }     │
└─────────────────────────────────────────────────────────────────┘

---

📋 Default Guidelines

When no custom prompt is provided, the system generates guidelines based on the combo-key:

Token	Generated Guideline
source	"Translate into {target_language}."
ucca	"Use UCCA structure to disambiguate roles; don't include UCCA in output."
gloss	"Use Gloss for standardized term choices and respect notes."
commentaries*	"Leverage commentaries to resolve ambiguity; don't cite explicitly."
sanskrit	"Use Sanskrit to validate terms and transliterations."

Default Prompt Structure

You are a professional translator for Buddhist literature.

### Instructions
- Translate into {target_language}.
- Do not add content beyond the source.
- Preserve meaning, nuance, and accuracy.
- Use UCCA structure to disambiguate roles...
- Use Gloss for standardized term choices...

### Source
{source_text}

### Commentaries (up to 3)
{commentaries}

### UCCA
{ucca_json}

### Gloss
{gloss_json}

### Sanskrit
{sanskrit_text}

Return only the translated text with no additional commentary.

---

🔀 Batch Workflow

Endpoint

POST /workflow/run/batch

Request

{
  "combo_key": "source+ucca",
  "items": [
    {
      "source": "First text...",
      "ucca": {"scenes": [...]}
    },
    {
      "source": "Second text...",
      "ucca": {"scenes": [...]}
    }
  ],
  "model_name": "claude-sonnet-4-20250514",
  "model_params": {}
}

Response

[
  {
    "index": 0,
    "translation": "First translation..."
  },
  {
    "index": 1,
    "translation": "Second translation..."
  }
]

Error Handling

[
  {
    "index": 0,
    "translation": "Successful translation..."
  },
  {
    "index": 1,
    "error": "Missing required 'ucca' input"
  }
]

---

⚠️ Validation Rules

Required Inputs

Combo-Key Token	Required Input
source	input.source (always required)
ucca	input.ucca
gloss	input.gloss
sanskrit	input.sanskrit
commentaries1+	input.commentaries (non-empty)

Commentaries Limit

Maximum 3 commentaries allowed:

{
  "input": {
    "commentaries": ["Com 1", "Com 2", "Com 3", "Com 4"]  // ERROR!
  }
}

→ Returns: 400 Bad Request: "At most 3 commentaries are allowed"

---

💡 Use Cases

Basic Translation

{
  "combo_key": "source",
  "input": {
    "source": "བྱང་ཆུབ་སེམས",
    "target_language": "english"
  }
}

With UCCA for Disambiguation

{
  "combo_key": "source+ucca",
  "input": {
    "source": "བྱང་ཆུབ་སེམས་དཔའ་སེམས་ཅན་ཐམས་ཅད་ལ་སྙིང་རྗེ་བསྐྱེད།",
    "ucca": {
      "scenes": [{
        "process": "generate",
        "agent": "bodhisattva",
        "patient": "compassion",
        "beneficiary": "all sentient beings"
      }]
    },
    "target_language": "english"
  }
}

With Standardized Glossary

{
  "combo_key": "source+gloss",
  "input": {
    "source": "བྱང་ཆུབ་སེམས་བསྐྱེད",
    "gloss": {
      "glossary": {
        "བྱང་ཆུབ་སེམས": "bodhicitta",
        "བསྐྱེད": "generate"
      }
    },
    "target_language": "english"
  }
}

Full Context Translation

{
  "combo_key": "source+ucca+gloss+commentaries2+sanskrit",
  "input": {
    "source": "བྱང་ཆུབ་སེམས་དཔའ་སེམས་ཅན་ཐམས་ཅད་ལ་སྙིང་རྗེ་བསྐྱེད།",
    "ucca": {"scenes": [...]},
    "gloss": {"glossary": {...}},
    "commentaries": [
      "This verse teaches the generation of compassion...",
      "The phrase 'all sentient beings' is universal..."
    ],
    "sanskrit": "bodhisattvaḥ sarvasattvān prati karuṇāṃ utpādayati",
    "target_language": "english"
  }
}

---

📊 Response Format

Success

{
  "combo_key": "gloss+source+ucca",
  "translation": "The bodhisattva generates compassion for all sentient beings."
}

LLM Error (Soft Failure)

{
  "combo_key": "gloss+source+ucca",
  "translation": null
}

Note: The endpoint returns 200 even if LLM fails; check translation for null.

---

🔗 See Also

• Concepts & Terminology - UCCA, Gloss explained
• API Reference - Full endpoint docs
• Usage Guide - More examples