Skip to content

Agentic Translation Engine

A powerful and intelligent translation system using advanced language models for high-quality, context-aware translations.

Architecture

agentic-translation-engines/
├── core/                  # Core infrastructure
│   ├── config.py          # pydantic-settings configuration
│   ├── errors.py          # Custom exception hierarchy
│   └── logging.py         # Structured logging (structlog)
│
├── helpers/               # Utility modules
│   └── retry.py           # @with_retry decorator
│
├── llm/                   # LLM abstraction layer
│   ├── models.py          # LLMResponse, LLMMessage
│   └── router.py          # LLMRouter with fallback chain
│
├── agents/                # Agent implementations
│   ├── llm_client_agent.py
│   ├── translator_agent.py
│   ├── quality_checker_agent.py
│   ├── orchestrator_agent.py
│   └── file_engine_client.py
│
├── models/                # Pydantic data models
├── prompts/               # LLM prompt templates
├── middleware/            # FastAPI middleware (auth)
└── tests/                 # Test suite

Quick Start

  1. Install Dependencies: 

    pip install -r requirements.txt

  2. Configure Environment: Copy .env.sample to .env and set your variables: 

    LLM_MODEL=gpt-4o
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://api.makakoo.com/ma-llm-proxy-ms/v1/api

  3. Run the API: 

    uvicorn api:app --reload

  4. Run Tests: 

    pytest tests/ -v

Features

  • Multi-Language Support: 20+ languages
  • File Format Support: JSON, CSV, Markdown, PDF, Images
  • Integrated OCR: Automatic text extraction
  • Quality Assurance: Built-in quality checking with self-correction
  • Agentic Workflow: Intelligent orchestration with iterative improvement
  • Fallback Chain: Automatic model fallback on failures
  • Structured Logging: JSON logs with trace IDs
  • Retry Logic: Exponential backoff for resilience

Core Components

Error Handling (core/errors.py)

Custom exception hierarchy: - AgenticError - Base exception - LLMError, TranslationError, FileEngineError

Configuration (core/config.py)

Type-safe settings: 

from core.config import settings
print(settings.default_model)

LLM Router (llm/router.py)

Unified LLM access with fallback: 

from llm.router import get_llm_router
router = get_llm_router()
response = await router.complete(messages)

External Dependencies

This service relies on critical external components:

  • File Engine Service (ma-file-engine-ms): 🔴 Hard Dependency. Handles file storage, OCR, and document intelligence. Cannot be easily replaced.
  • Traylinx Auth Service (traylinx-auth-ms): Handles user authentication.
  • Traylinx Sentinel: Handles agent-to-agent (A2A) authentication.

See External Dependencies for details.

Authentication

This API supports two authentication methods:

Option 1: User Authentication (Human API)

For human users accessing via UI or apps:

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user_token>" \
  -d '{"text": "Hello", "target_language": "es"}'
Header Value Description
Authorization Bearer <token> User token validated against Auth Service

Option 2: Agent Authentication (A2A / Machine-to-Machine)

For other agents or services calling this API:

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Secret-Token: <agent_token>" \
  -H "X-Agent-User-Id: <agent_id>" \
  -d '{"text": "Hello", "target_language": "es"}'
Header Value Description
X-Agent-Secret-Token Agent's secret token Obtained from Traylinx Sentinel
X-Agent-User-Id Agent's UUID Agent identifier registered with Sentinel

Authentication Flow

Request arrives
    │
    ├─ Has X-Agent-Secret-Token? ──→ AGENT MODE (validate via Sentinel)
    │
    └─ Has Authorization: Bearer? ─→ USER MODE (validate via Auth Service)

Note: Agent authentication headers take precedence over Bearer token if both are provided.

Documentation

License

Private - Traylinx