Langraph API for Pecha AI studio

[TenzinGayche]

LangGraph Translation API - Documentation Card

Type: Documentation
Status: ✅ Complete
Priority: High
Related Feature: Tibetan Buddhist Text Translation Pipeline

---

📋 Summary

Comprehensive documentation created for the LangGraph Translation API - a sophisticated, multi-stage pipeline for translating, analyzing, and standardizing Tibetan Buddhist texts. Built with FastAPI and LangGraph, featuring streaming-first architecture with multi-model support (Anthropic, Google, OpenAI, Dharmamitra).

---

📚 Documentation Deliverables

Document	Location	Description
Home	Wiki	Overview, quick start, navigation
Architecture	Wiki/Architecture	LangGraph workflow, system diagrams, data flow
Concepts & Terminology	Wiki/Concepts-and-Terminology	Buddhist terms, UCCA, Gloss, combo-keys
API Reference	Wiki/API-Reference	All 25+ endpoints, SSE streaming, schemas
Model Router	Wiki/Model-Router	Multi-provider LLM configuration
Workflow System	Wiki/Workflow-System	Combo-key based translation workflows
Streaming Guide	Wiki/Streaming-Guide	SSE patterns, client implementations
Installation	Wiki/Installation	Setup, Docker, cloud deployment
Usage Guide	Wiki/Usage-Guide	Examples, tutorials, best practices

---

🎯 Documentation Coverage

Buddhist/Translation Terminology Documented

• Kangyur (བཀའ་འགྱུར) - Buddha's direct teachings
• Tengyur (བསྟན་འགྱུར) - Commentaries and treatises
• Pecha (དཔེ་ཆ) - Traditional Tibetan book format
• Shad (།) - Tibetan punctuation mark
• Tsheg (་) - Tibetan syllable separator
• UCCA semantic annotation
• Gloss word-by-word analysis
• Glossary extraction concepts
• Standardization workflow

Technical Concepts Documented

• LangGraph state machine workflow
• Multi-stage decoupled pipeline
• Batch processing with caching
• SSE (Server-Sent Events) streaming
• Multi-model routing architecture
• Combo-key based prompt selection
• Structured output with Pydantic
• Translation/Glossary caching system
• Thinking models (Gemini)

Architecture Documented

• High-level system architecture diagram
• LangGraph workflow state machine
• Data flow from request to response
• Three-stage pipeline (Translation → Glossary → Standardization)
• Model router with provider abstraction
• Cache management system
• Streaming architecture diagram

API Endpoints Documented

Translation Endpoints

• POST /translate - Batch text translation
• POST /translate/single - Single text translation
• POST /translate/stream - Streaming translation (SSE)
• POST /translate/single/stream - Single text streaming

Glossary Endpoints

• POST /glossary/extract - Extract glossary from translations
• POST /glossary/extract/stream - Streaming glossary extraction

Standardization Endpoints

• POST /standardize/analyze - Find inconsistent terms
• POST /standardize/apply - Apply standardization rules
• POST /standardize/apply/stream - Streaming standardization

UCCA Endpoints

• POST /ucca/generate - Generate single UCCA graph
• POST /ucca/generate/batch - Batch UCCA generation
• POST /ucca/generate/stream - Streaming UCCA generation

Gloss Endpoints

• POST /gloss/generate - Generate single gloss analysis
• POST /gloss/generate/batch - Batch gloss generation
• POST /gloss/generate/stream - Streaming gloss generation

Workflow Endpoints

• POST /workflow/run - Run combo-key based workflow
• POST /workflow/run/batch - Batch workflow execution

Editor Endpoints

• POST /editor/comment - Generate grounded commentary
• POST /editor/comment/stream - Streaming commentary

Proxy Endpoints (Dharmamitra)

• POST /dharmamitra/knn-translate-mitra - KNN Translate (SSE)
• POST /dharmamitra/knn-translate-gemini-no-stream - Gemini proxy

System Endpoints

• GET /health - Health check
• GET /models - List available models
• POST /system/clear-cache - Clear server cache

Pipeline Endpoint

• POST /pipeline/run - Multi-stage pipeline execution

SSE Event Types Documented

• batch_completed - Translation batch complete
• completion - Final completion event
• glossary_batch_completed - Glossary extraction batch
• retranslation_completed - Standardization update
• ucca_item_completed - UCCA graph generated
• gloss_item_completed - Gloss generated
• comment_delta - Streaming comment tokens
• initialization - Editor comment init
• error - Error events

Request/Response Schemas Documented

• TranslationAPIRequest / TranslationAPIResponse
• SingleTranslationRequest
• GlossaryExtractionRequest / Glossary
• AnalysisRequest / AnalysisResponse
• StandardizationRequest / StandardizationResponse
• UCCARequest / UCCAResponse
• GlossRequest / GlossResponse
• WorkflowRunRequest / WorkflowResponse
• EditorCommentRequest / EditorCommentResponse
• PipelineRequest / PipelineResponse

Supported Models Documented

• Anthropic: claude-sonnet-4-20250514, claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001, claude-3-5-haiku-20241022, claude-3-opus-20240229
• Google: gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-thinking
• OpenAI: gpt-4, gpt-4-turbo, gpt-3.5-turbo
• Dharmamitra: dharamitra (translation-only)

Code Documentation

• api.py - Full API walkthrough
• graph.py - LangGraph workflow implementation
• model_router.py - Multi-provider model routing
• translation_state.py - Workflow state management
• streaming.py - SSE streaming helpers
• ucca.py / gloss.py - UCCA/Gloss generation
• cache.py - Translation/Glossary caching
• config.py - Environment configuration

Frontend Documentation

• Web UI HTML structure (static/index.html)
• Editor interface (static/editor.html)
• JavaScript streaming implementation
• Model selection interface

Usage Examples Provided

• cURL commands for all endpoints
• Python client examples (sync & async)
• JavaScript/TypeScript client examples
• Full pipeline workflow examples
• Combo-key usage patterns
• Custom prompt templates
• Streaming client implementations

---

🔗 Quick Links

Resource	URL
Wiki Home	https://github.com/OpenPecha/langraph-api/wiki
Repository	https://github.com/OpenPecha/langraph-api
Swagger Docs	http://localhost:8001/docs
OpenPecha	https://openpecha.org

---

🛠️ Technology Stack Documented

Component	Technology
Backend	FastAPI
Orchestration	LangGraph (LangChain)
LLM Providers	Anthropic Claude, Google Gemini, OpenAI GPT, Dharmamitra
Streaming	SSE (sse-starlette)
Validation	Pydantic v2
HTTP Client	httpx
Caching	In-memory (custom)
Frontend	Vanilla HTML/CSS/JavaScript
Deployment	Docker, Uvicorn, Render.com, Railway, Fly.io

---

📝 Notes

• Documentation excludes all credentials/secrets (security best practice)
• All code examples are copy-paste ready
• Architecture diagrams use ASCII art for portability
• Wiki supports GitHub-flavored Markdown
• Tibetan script examples (བོད་སྐད་) included throughout
• Combo-key system fully documented with validation rules
• Thinking model configuration documented for Gemini

---

✅ Acceptance Criteria - Documentation

Criteria	Status
LangGraph workflow explained	✅
Multi-stage pipeline documented	✅
All API endpoints documented	✅
SSE streaming patterns explained	✅
Request/response schemas defined	✅
Model router documented	✅
Combo-key system explained	✅
UCCA/Gloss concepts defined	✅
Setup instructions with troubleshooting	✅
Usage examples for all endpoints	✅
Frontend implementation explained	✅
Caching strategy documented	✅
Docker deployment documented	✅
Cloud deployment options	✅
No credentials exposed	✅

---

📊 Documentation Statistics

Metric	Count
Wiki pages created	11
Total lines of documentation	4,360+
Code examples	40+
Architecture diagrams	8+
Buddhist terms defined	15+
Technical concepts explained	20+
API endpoints documented	25+
Supported models documented	10+

---

📅 Timeline

Date	Action
Dec 15, 2025	Documentation created and published to GitHub Wiki

---

📁 Wiki Structure

langraph-api.wiki/
├── Home.md                       # Main landing page
├── Architecture.md               # System architecture + LangGraph
├── Concepts-and-Terminology.md   # Buddhist terms, UCCA, Gloss
├── API-Reference.md              # All endpoints documentation
├── Model-Router.md               # Multi-provider LLM configuration
├── Workflow-System.md            # Combo-key workflows
├── Streaming-Guide.md            # SSE patterns and events
├── Installation.md               # Setup and deployment guide
├── Usage-Guide.md                # Examples and tutorials
├── _Sidebar.md                   # Navigation menu
└── _Footer.md                    # Footer links

---

🔧 Key Features Documented

1. Three-Stage Decoupled Pipeline

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────────┐
│   Translation   │ →  │    Glossary     │ →  │  Standardization    │
│    Service      │    │    Service      │    │     Service         │
└─────────────────┘    └─────────────────┘    └─────────────────────┘

2. LangGraph Workflow Nodes

initialize → process_batch → (loop) → extract_glossaries_in_parallel → finalize

3. Combo-Key System

combo_key: "source+ucca+gloss+commentaries2"
→ Dynamically selects prompt template based on available inputs

4. Multi-Model Router

┌──────────┬──────────┬──────────┬────────────┐
│Anthropic │  Google  │  OpenAI  │ Dharmamitra│
│  Claude  │  Gemini  │   GPT    │   Mitra    │
└──────────┴──────────┴──────────┴────────────┘

5. Streaming Architecture

Client ──POST──▶ FastAPI ──LLM──▶ Provider
       ◀──SSE──         ◀────────

---

Documentation maintained in: GitHub Wiki