PDF Translate Agent

Local-first PDF paper translation agent with:

• direct CLI translation
• MCP tool server (stdio + http)
• agent-to-agent parameter contract (preflight_validate, build_pipeline_invocation, run_local_translate_agent)

1) Quick Start (Clone -> Run)

Prerequisites

• Python 3.10+
• A local OpenAI-compatible LLM endpoint (default: http://127.0.0.1:5000/v1)

Bootstrap

Windows (PowerShell):

.\scripts\bootstrap.ps1

Linux / WSL:

bash ./scripts/bootstrap.sh

This creates .venv and installs dependencies from requirements.txt.

Quick Smoke Check

PowerShell:

.\scripts\smoke_check.ps1

PowerShell (CI-compatible, no local vLLM):

.\scripts\smoke_check.ps1 -SkipLlmCheck

Linux / WSL:

bash ./scripts/smoke_check.sh

Linux / WSL (CI-compatible, no local vLLM):

bash ./scripts/smoke_check.sh http://127.0.0.1:5000/v1 true

Command Prompt:

scripts\smoke_check.bat

Command Prompt (CI-compatible):

scripts\smoke_check.bat http://127.0.0.1:5000/v1 true

2) Prepare Input PDF

Put your PDF in papers_repo/, for example:

• papers_repo/sample.pdf

3) Run Translation (Local, One Command)

PowerShell:

.\scripts\run_translate_agent.ps1 -PdfPath ".\papers_repo\sample.pdf" -SkipCompile

Command Prompt (.bat, no execution-policy change needed):

scripts\run_translate_agent.bat papers_repo\sample.pdf artifacts\agent_sample http://127.0.0.1:5000/v1 auto true

Output artifacts are written under artifacts/....

4) Run Through MCP

Start MCP HTTP server:

python .\paper_translate_agent.py --mode mcp-http --mcp-host 127.0.0.1 --mcp-port 8787

Call one-shot tool (run_local_translate_agent) via script:

.\scripts\mcp_run_translate_agent.ps1 -PdfPath "papers_repo/sample.pdf" -SkipCompile

Or via .bat:

scripts\mcp_run_translate_agent.bat papers_repo\sample.pdf artifacts\mcp_sample http://127.0.0.1:8787 http://127.0.0.1:5000/v1

5) Verify Local LLM Connectivity

Invoke-RestMethod -Uri "http://127.0.0.1:5000/v1/models" -Method GET
python -m app.debug_tools.diagnose --profile quick --base-url "http://127.0.0.1:5000/v1"

6) For Other Agents (Contract)

tools/list exposes machine-readable fields:

• description
• parameter_contract
• examples
• missing_info_protocol

Core MCP helpers:

• preflight_validate: checks missing/invalid params before execution
• build_pipeline_invocation: returns deterministic preflight->run->artifacts workflow bundle
• run_local_translate_agent: one-shot local execution entrypoint (enforces local base URL by default)

7) Tests

python -m unittest discover -s tests -v

CI-compatible diagnose command:

python -m app.debug_tools.diagnose --profile quick --skip-llm-check

8) Contributing & CI

• Contribution guide: CONTRIBUTING.md
• PR template: .github/pull_request_template.md
• GitHub Actions workflow: .github/workflows/ci.yml

CI matrix:

• ubuntu-latest with Python 3.10, 3.11
• windows-latest with Python 3.10

CI runs:

1. python -m pip install -r requirements.txt
2. python -m unittest discover -s tests -v
3. python -m app.debug_tools.diagnose --profile quick --skip-llm-check

Why --skip-llm-check in CI:

• CI should be reproducible and must not depend on a private/local endpoint like http://127.0.0.1:5000/v1.

9) Project Structure

• app/: pipeline, MCP registry/server, debug tools
• scripts/: bootstrap and run scripts (.ps1, .sh, .bat)
• config/agent.defaults.yaml: default params and missing-info mode
• papers_repo/: place input PDFs
• artifacts/: generated outputs
• docs/USAGE_AND_ACCESS.md: detailed usage and calling guide