Skip to content

Agentic Upload Engine

A specialized service for intelligent file ingestion, OCR processing, multi-language translation, and content extraction using an agentic architecture.

Architecture

agentic-upload-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: Create a .env file with: 

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

  3. Run the API: 

    uvicorn api:app --reload

  4. Run Tests: 

    pytest tests/ -v

Features

  • Intelligent File Processing: Automatic file type detection and OCR
  • Multi-Agent Translation: Orchestrated translation with quality checking
  • Fallback Chain: Automatic model fallback on failures
  • Structured Logging: JSON logs with trace IDs for observability
  • Retry Logic: Exponential backoff for resilience
  • Type-Safe Config: pydantic-settings for validated configuration

Core Components

Error Handling (core/errors.py)

Custom exception hierarchy for better error categorization: - AgenticError - Base exception - LLMError, LLMTimeoutError, LLMAllFailedError - TranslationError, QualityCheckError - FileEngineError, OCRProcessingError

Configuration (core/config.py)

Type-safe settings using pydantic-settings: 

from core.config import settings

print(settings.default_model)
print(settings.llm_base_url)

LLM Router (llm/router.py)

Unified LLM access with fallback support: 

from llm.router import get_llm_router

router = get_llm_router()
response = await router.complete(messages, model="gpt-4o")

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/upload" \
  -H "Authorization: Bearer <user_token>" \
  -F "file=@document.pdf"
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/upload" \
  -H "X-Agent-Secret-Token: <agent_token>" \
  -H "X-Agent-User-Id: <agent_id>" \
  -F "file=@document.pdf"
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