lingua-proxy 0.1.0__py3-none-any.whl

lingua_proxy/__init__.py

@@ -0,0 +1,5 @@
+"""lingua-proxy: translate non-English LLM traffic to English to cut token costs."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

lingua_proxy/bench.py

@@ -0,0 +1,185 @@
+"""Measure whether the proxy actually saves money.
+
+The premise of this project is a claim about cost, so it ships with the means
+to check that claim against a real upstream, on a corpus that deliberately
+includes workloads where translation is expected to *lose*: three-word prompts
+whose translation fee dwarfs the request, and code-heavy payloads that barely
+compress.
+
+Savings are reported in dollars rather than tokens, because the translator
+runs on a cheap model and the request on an expensive one. A verdict of
+``loses`` is a valid, expected result for some categories.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from dataclasses import dataclass, field
+
+from rich.console import Console
+from rich.table import Table
+
+CORPUS_PATH = pathlib.Path(__file__).with_name("bench_corpus.jsonl")
+
+#: A category has to clear this to count as worth using.
+PAYS_OFF = 0.25
+
+
+def load_corpus(path: pathlib.Path | None = None) -> list[dict]:
+    """Read the bundled prompt corpus."""
+    target = path or CORPUS_PATH
+    rows = []
+    for line in target.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line:
+            rows.append(json.loads(line))
+    return rows
+
+
+def verdict_for(ratio: float) -> str:
+    if ratio >= PAYS_OFF:
+        return "pays off"
+    if ratio > 0:
+        return "marginal"
+    return "loses"
+
+
+@dataclass
+class BenchResult:
+    """One prompt's measurement."""
+
+    id: str
+    lang: str
+    category: str
+    baseline_cost: float = 0.0
+    proxied_cost: float = 0.0
+    translator_cost: float = 0.0
+    latency_ms: float = 0.0
+    error: str | None = None
+    detail: dict = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+    @property
+    def dollars_saved(self) -> float:
+        return self.baseline_cost - self.proxied_cost
+
+
+def _bucket(results: list[BenchResult]) -> dict:
+    baseline = sum(r.baseline_cost for r in results)
+    proxied = sum(r.proxied_cost for r in results)
+    translator = sum(r.translator_cost for r in results)
+    ratio = (baseline - proxied) / baseline if baseline > 0 else 0.0
+    return {
+        "n": len(results),
+        "baseline_cost": round(baseline, 6),
+        "proxied_cost": round(proxied, 6),
+        "translator_cost": round(translator, 6),
+        "dollars_saved": round(baseline - proxied, 6),
+        "savings_ratio": round(ratio, 4),
+        "verdict": verdict_for(ratio) if results else "no data",
+    }
+
+
+def build_report(results: list[BenchResult]) -> dict:
+    """Aggregate per-category and overall figures."""
+    good = [r for r in results if r.ok]
+
+    categories: dict[str, list[BenchResult]] = {}
+    for result in good:
+        categories.setdefault(result.category, []).append(result)
+
+    return {
+        "overall": _bucket(good),
+        "categories": {name: _bucket(rows) for name, rows in sorted(categories.items())},
+        "errors": sum(1 for r in results if not r.ok),
+        # A truncated reply pins both runs to the same output length and hides
+        # real savings, so the count is surfaced rather than buried.
+        "truncated": sum(1 for r in good if r.detail.get("truncated")),
+    }
+
+
+def exit_code_for(report: dict, *, min_savings: float) -> int:
+    """Non-zero when the headline claim does not hold on real traffic."""
+    chat = report["categories"].get("chat")
+    if not chat or chat["n"] == 0:
+        return 0
+    return 0 if chat["savings_ratio"] >= min_savings else 1
+
+
+def render(report: dict, console: Console | None = None) -> None:
+    console = console or Console()
+    table = Table(title="lingua-proxy savings benchmark")
+    table.add_column("Category")
+    table.add_column("n", justify="right")
+    table.add_column("Without proxy", justify="right")
+    table.add_column("With proxy", justify="right")
+    table.add_column("Saved", justify="right")
+    table.add_column("Verdict")
+
+    for name, bucket in report["categories"].items():
+        colour = {"pays off": "green", "marginal": "yellow", "loses": "red"}.get(
+            bucket["verdict"], "white"
+        )
+        table.add_row(
+            name,
+            str(bucket["n"]),
+            f"${bucket['baseline_cost']:.5f}",
+            f"${bucket['proxied_cost']:.5f}",
+            f"{bucket['savings_ratio'] * 100:.1f}%",
+            f"[{colour}]{bucket['verdict']}[/{colour}]",
+        )
+
+    overall = report["overall"]
+    table.add_section()
+    table.add_row(
+        "[bold]overall[/bold]",
+        str(overall["n"]),
+        f"${overall['baseline_cost']:.5f}",
+        f"${overall['proxied_cost']:.5f}",
+        f"{overall['savings_ratio'] * 100:.1f}%",
+        overall["verdict"],
+    )
+    console.print(table)
+
+    if report["errors"]:
+        console.print(f"[yellow]{report['errors']} prompt(s) failed and were excluded.[/yellow]")
+
+    if report.get("truncated"):
+        console.print(
+            f"[yellow]{report['truncated']} reply/replies hit the token ceiling.[/yellow] "
+            "Truncated replies understate savings, because both runs are forced to the "
+            "same output length. Raise max_tokens for a cleaner measurement."
+        )
+
+
+def run_bench(*, mode: str = "estimate", min_savings: float = 0.30, as_json: bool = False) -> int:
+    """Run the benchmark against a configured upstream.
+
+    Requires an explicit upstream: silently defaulting to the public API would
+    spend the user's money without asking.
+    """
+    import os
+
+    console = Console()
+    upstream = os.environ.get("LINGUA_BENCH_BASE_URL")
+    if not upstream:
+        console.print(
+            "[red]No benchmark upstream configured.[/red]\n"
+            "Set LINGUA_BENCH_BASE_URL (and LINGUA_BENCH_AUTH if it needs a credential).\n"
+            "This command sends real requests and spends real money, so it will not "
+            "guess an endpoint for you."
+        )
+        return 2
+
+    from lingua_proxy.bench_runner import run_live_bench
+
+    report = run_live_bench(upstream=upstream, mode=mode)
+    if as_json:
+        print(json.dumps(report, indent=2))
+    else:
+        render(report, console)
+    return exit_code_for(report, min_savings=min_savings)

lingua_proxy/bench_corpus.jsonl

@@ -0,0 +1,21 @@
+{"id": "chat-ko-1", "lang": "ko", "category": "chat", "prompt": "파이썬에서 리스트와 튜플의 차이가 뭔지 설명해 주고, 각각 어떤 상황에서 쓰는 게 좋은지 예시와 함께 알려줘."}
+{"id": "chat-ko-2", "lang": "ko", "category": "chat", "prompt": "우리 서비스 응답 속도가 최근에 느려졌는데, 원인을 찾으려면 어떤 지표부터 확인해야 할까? 순서대로 알려줘."}
+{"id": "chat-ko-3", "lang": "ko", "category": "chat", "prompt": "데이터베이스 인덱스를 추가하면 항상 빨라지는 건 아니라고 들었어. 어떤 경우에 오히려 느려지는지 설명해 줘."}
+{"id": "chat-ja-1", "lang": "ja", "category": "chat", "prompt": "非同期処理と並行処理の違いを、実際のコード例を交えながら初心者にも分かるように説明してください。"}
+{"id": "chat-ja-2", "lang": "ja", "category": "chat", "prompt": "チームでコードレビューを導入したいのですが、最初に決めておくべきルールを優先度順に教えてください。"}
+{"id": "chat-ja-3", "lang": "ja", "category": "chat", "prompt": "本番環境で発生した障害の原因調査を行う際、ログのどこから見ていくのが効率的でしょうか。"}
+{"id": "chat-zh-1", "lang": "zh", "category": "chat", "prompt": "请解释一下什么是数据库事务的隔离级别，以及在实际项目中应该如何选择合适的级别。"}
+{"id": "chat-zh-2", "lang": "zh", "category": "chat", "prompt": "我们的接口偶尔会超时，但重试之后就正常了。请分析可能的原因并给出排查思路。"}
+{"id": "chat-zh-3", "lang": "zh", "category": "chat", "prompt": "微服务架构相比单体架构有哪些代价？请从团队规模和运维成本的角度说明。"}
+{"id": "chat-ar-1", "lang": "ar", "category": "chat", "prompt": "اشرح لي الفرق بين التخزين المؤقت على مستوى التطبيق والتخزين المؤقت على مستوى قاعدة البيانات، ومتى أستخدم كل منهما."}
+{"id": "chat-ar-2", "lang": "ar", "category": "chat", "prompt": "ما هي أفضل الممارسات لتأمين واجهة برمجة التطبيقات العامة؟ اذكرها مرتبة حسب الأهمية."}
+{"id": "chat-ar-3", "lang": "ar", "category": "chat", "prompt": "أواجه بطئاً في تحميل الصفحة الرئيسية لموقعي. ما الخطوات التي يجب أن أتبعها لتشخيص المشكلة؟"}
+{"id": "short-ko-1", "lang": "ko", "category": "short", "prompt": "이거 고쳐줘"}
+{"id": "short-ja-1", "lang": "ja", "category": "short", "prompt": "これを直して"}
+{"id": "short-zh-1", "lang": "zh", "category": "short", "prompt": "帮我修一下"}
+{"id": "long-ko-1", "lang": "ko", "category": "long_form", "prompt": "우리 팀이 새로 도입할 코드 리뷰 프로세스에 대한 문서를 작성해 줘. 배경, 목표, 단계별 절차, 예외 상황 처리, 그리고 도입 후 3개월 시점에 점검할 지표까지 포함해서 자세히 써 줘."}
+{"id": "long-ja-1", "lang": "ja", "category": "long_form", "prompt": "新しいメンバー向けのオンボーディング資料を作成してください。開発環境の構築手順、コードベースの全体像、レビュー文化、よくあるつまずきポイントとその対処法を含めて、詳しく書いてください。"}
+{"id": "long-zh-1", "lang": "zh", "category": "long_form", "prompt": "请为我们的服务撰写一份完整的故障应急预案文档，包括故障分级标准、各级别的响应流程、责任人分工、对外沟通模板，以及事后复盘的具体步骤。"}
+{"id": "code-ko-1", "lang": "ko", "category": "code_heavy", "prompt": "이 함수 성능을 개선해줘:\n\n```python\ndef process_records(records, threshold):\n    results = []\n    seen = set()\n    for record in records:\n        key = record.get(\"id\")\n        if key in seen:\n            continue\n        seen.add(key)\n        score = 0\n        for field in (\"alpha\", \"beta\", \"gamma\"):\n            value = record.get(field)\n            if value is None:\n                continue\n            score += value * WEIGHTS[field]\n        if score > threshold:\n            results.append({\"id\": key, \"score\": score})\n    results.sort(key=lambda item: item[\"score\"], reverse=True)\n    return results\n```"}
+{"id": "code-ja-1", "lang": "ja", "category": "code_heavy", "prompt": "この関数のバグを見つけてください:\n\n```javascript\nexport function buildIndex(documents) {\n  const index = new Map();\n  for (const doc of documents) {\n    const tokens = doc.text.toLowerCase().split(/\\W+/);\n    for (const token of tokens) {\n      if (!token) continue;\n      if (!index.has(token)) index.set(token, new Set());\n      index.get(token).add(doc.id);\n    }\n  }\n  return index;\n}\n```"}
+{"id": "code-zh-1", "lang": "zh", "category": "code_heavy", "prompt": "请帮我优化这个查询:\n\n```sql\nSELECT u.id, u.email, COUNT(o.id) AS order_count, SUM(o.total) AS lifetime_value\nFROM users u\nLEFT JOIN orders o ON o.user_id = u.id AND o.status = 'completed'\nWHERE u.created_at >= NOW() - INTERVAL '90 days'\nGROUP BY u.id, u.email\nHAVING COUNT(o.id) > 3\nORDER BY lifetime_value DESC\nLIMIT 100;\n```"}

lingua_proxy/bench_runner.py

@@ -0,0 +1,109 @@
+"""Live benchmark execution.
+
+Each corpus prompt is sent twice through the proxy: once normally, and once
+with ``x-lingua-bypass`` so the model answers in the original language. That
+gives a measured baseline instead of an estimated one, which matters because
+an estimate is exactly the thing a sceptical reader would not trust.
+
+Every request costs money, so this is opt-in and never runs by default.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+import httpx
+
+from lingua_proxy.bench import BenchResult, build_report, load_corpus
+from lingua_proxy.codecs import AnthropicMessagesCodec
+from lingua_proxy.config import Settings
+from lingua_proxy.cost_log import price_for
+from lingua_proxy.proxy import create_app
+
+DEFAULT_MODEL = "claude-sonnet-4-6"
+# Generous enough that ordinary replies finish naturally. If a reply is cut
+# off at the ceiling, both runs produce identical output token counts and the
+# measurement understates savings, because output is where most cost lives.
+MAX_TOKENS = 4096
+
+
+def _auth_headers() -> dict[str, str]:
+    headers = {"anthropic-version": "2023-06-01", "content-type": "application/json"}
+    token = os.environ.get("LINGUA_BENCH_AUTH")
+    if token:
+        if token.startswith("sk-"):
+            headers["x-api-key"] = token
+        else:
+            headers["authorization"] = f"Bearer {token}"
+    return headers
+
+
+async def _one(
+    client: httpx.AsyncClient,
+    row: dict,
+    model: str,
+    codec: AnthropicMessagesCodec,
+) -> BenchResult:
+    body = {
+        "model": model,
+        "max_tokens": MAX_TOKENS,
+        "temperature": 0,
+        "messages": [{"role": "user", "content": row["prompt"]}],
+    }
+    headers = _auth_headers()
+    price = price_for(model)
+
+    started = time.monotonic()
+    try:
+        # Baseline: the model answers in the original language.
+        native = await client.post(
+            "/v1/messages", json=body, headers={**headers, "x-lingua-bypass": "true"}, timeout=120
+        )
+        native.raise_for_status()
+        baseline_usage = codec.usage(native.json())
+
+        # Proxied: translated in and back out.
+        proxied = await client.post("/v1/messages", json=body, headers=headers, timeout=180)
+        proxied.raise_for_status()
+        proxied_usage = codec.usage(proxied.json())
+    except Exception as exc:  # noqa: BLE001 - one bad prompt must not end the run
+        return BenchResult(row["id"], row["lang"], row["category"], error=str(exc)[:200])
+
+    return BenchResult(
+        id=row["id"],
+        lang=row["lang"],
+        category=row["category"],
+        baseline_cost=price.cost(baseline_usage),
+        proxied_cost=price.cost(proxied_usage),
+        latency_ms=(time.monotonic() - started) * 1000,
+        detail={
+            "baseline_input": baseline_usage.input_tokens,
+            "baseline_output": baseline_usage.output_tokens,
+            "proxied_input": proxied_usage.input_tokens,
+            "proxied_output": proxied_usage.output_tokens,
+            "truncated": native.json().get("stop_reason") == "max_tokens"
+            or proxied.json().get("stop_reason") == "max_tokens",
+        },
+    )
+
+
+def run_live_bench(*, upstream: str, mode: str = "estimate", model: str | None = None) -> dict:
+    """Run every corpus prompt through an in-process proxy against ``upstream``."""
+    import asyncio
+
+    model = model or os.environ.get("LINGUA_BENCH_MODEL", DEFAULT_MODEL)
+    settings = Settings(upstream_anthropic_url=upstream, memo_persist=False)
+    app = create_app(settings)
+    codec = AnthropicMessagesCodec()
+
+    async def go() -> list[BenchResult]:
+        results = []
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app), base_url="http://bench.test"
+        ) as client:
+            for row in load_corpus():
+                results.append(await _one(client, row, model, codec))
+        return results
+
+    return build_report(asyncio.run(go()))

lingua_proxy/cli.py

@@ -0,0 +1,301 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+
+import click
+import httpx
+from rich.console import Console
+from rich.table import Table
+
+from lingua_proxy import __version__
+from lingua_proxy.config import (
+    Settings,
+    default_config_path,
+    lingua_home,
+    resolve_anthropic_upstream,
+    resolve_openai_upstream,
+)
+from lingua_proxy.cost_log import CostLog, summarize
+from lingua_proxy.doctor import run_checks
+from lingua_proxy.wrap import (
+    WrapError,
+    apply_wrap,
+    clear_marker,
+    find_claude_binary,
+    load_marker,
+    restore_wrap,
+)
+
+console = Console()
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="lingua-proxy")
+def main() -> None:
+    """Translate non-English LLM traffic to English to cut token costs."""
+
+
+# -- proxy --------------------------------------------------------------
+
+
+@main.command()
+@click.option("--host", default=None, help="Bind address (loopback by default).")
+@click.option("--port", type=int, default=None, help="Port to listen on.")
+@click.option("--upstream", default=None, help="Anthropic-format upstream base URL.")
+@click.option("--openai-upstream", default=None, help="OpenAI-format upstream base URL.")
+@click.option("--translator-model", default=None, help="Model used for translation.")
+def proxy(
+    host: str | None,
+    port: int | None,
+    upstream: str | None,
+    openai_upstream: str | None,
+    translator_model: str | None,
+) -> None:
+    """Run the translating proxy."""
+    import uvicorn
+
+    from lingua_proxy.proxy import create_app
+
+    settings = Settings(
+        upstream_anthropic_url=resolve_anthropic_upstream(upstream),
+        upstream_openai_url=resolve_openai_upstream(openai_upstream),
+    )
+    if host:
+        settings.host = host
+    if port:
+        settings.port = port
+    if translator_model:
+        settings.translator_model = translator_model
+
+    console.print(f"[bold]lingua-proxy[/bold] {__version__}")
+    console.print(f"  listening on  http://{settings.host}:{settings.port}")
+    console.print(f"  upstream      {settings.upstream_anthropic_url}")
+    console.print(f"  translator    {settings.translator_model}")
+
+    uvicorn.run(create_app(settings), host=settings.host, port=settings.port, log_level="warning")
+
+
+# -- wrap ---------------------------------------------------------------
+
+
+def _proxy_is_up(port: int) -> bool:
+    try:
+        response = httpx.get(f"http://127.0.0.1:{port}/healthz", timeout=1.0)
+        return response.json().get("service") == "lingua-proxy"
+    except Exception:
+        return False
+
+
+def _persist_upstream(url: str) -> None:
+    """Remember the resolved upstream so proxy/doctor/bench agree."""
+    path = default_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existing = path.read_text() if path.exists() else ""
+    lines = [ln for ln in existing.splitlines() if not ln.startswith("upstream_anthropic_url")]
+    lines.append(f'upstream_anthropic_url = "{url}"')
+    path.write_text("\n".join(lines).strip() + "\n")
+
+
+@main.group()
+def wrap() -> None:
+    """Run a client with its traffic routed through lingua-proxy."""
+
+
+@wrap.command("claude")
+@click.option("--port", type=int, default=8787, show_default=True)
+@click.option("--upstream", default=None, help="Override the detected upstream.")
+@click.option("--no-proxy", is_flag=True, help="Assume the proxy is already running.")
+@click.option("--dry-run", is_flag=True, help="Show what would change, then restore.")
+@click.option("--keep-patched", is_flag=True, hidden=True, help="Testing aid: skip restore.")
+@click.argument("claude_args", nargs=-1, type=click.UNPROCESSED)
+def wrap_claude(
+    port: int,
+    upstream: str | None,
+    no_proxy: bool,
+    dry_run: bool,
+    keep_patched: bool,
+    claude_args: tuple[str, ...],
+) -> None:
+    """Launch Claude Code pointed at the proxy, then restore your settings."""
+    if os.environ.get("LINGUA_PROXY_WRAPPED"):
+        raise click.ClickException(
+            "This session is already wrapped by lingua-proxy. Nesting would loop traffic."
+        )
+
+    resolved = resolve_anthropic_upstream(upstream)
+    proxy_url = f"http://127.0.0.1:{port}"
+    if resolved.rstrip("/") == proxy_url:
+        raise click.ClickException(
+            "The detected upstream is lingua-proxy itself, which would loop. "
+            "Pass --upstream to name the real API or gateway."
+        )
+
+    binary = None
+    if not dry_run and not keep_patched:
+        try:
+            binary = find_claude_binary()
+        except WrapError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    _persist_upstream(resolved)
+
+    try:
+        state = apply_wrap(proxy_url, port)
+    except WrapError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    console.print("[bold]lingua-proxy[/bold] wrapping Claude Code")
+    console.print(f"  proxy      {proxy_url}")
+    console.print(f"  upstream   {resolved}")
+    console.print(f"  patched    {state.settings_path}")
+
+    if not no_proxy and not _proxy_is_up(port):
+        console.print(
+            f"  [yellow]note[/yellow]  no proxy answering on port {port}; "
+            f"start one with 'lingua-proxy proxy --port {port}'"
+        )
+
+    if keep_patched:
+        return
+
+    if dry_run:
+        restore_wrap(state)
+        clear_marker()
+        console.print("  [green]dry run[/green] settings restored")
+        return
+
+    try:
+        # Set the base URL on the child too. The settings file is what Claude
+        # Code actually reads, but leaving a stale shell variable pointing
+        # elsewhere is confusing and would apply to anything else it launches.
+        child_env = {
+            **os.environ,
+            "ANTHROPIC_BASE_URL": proxy_url,
+            "LINGUA_PROXY_WRAPPED": "1",
+        }
+        result = subprocess.run([binary, *claude_args], env=child_env)
+        code = result.returncode
+    finally:
+        restore_wrap(state)
+        clear_marker()
+        console.print("  settings restored")
+
+    raise SystemExit(code)
+
+
+@main.group()
+def unwrap() -> None:
+    """Undo a wrap that did not clean up after itself."""
+
+
+@unwrap.command("claude")
+@click.option("--no-stop-proxy", is_flag=True, help="Leave a running proxy alone.")
+def unwrap_claude(no_stop_proxy: bool) -> None:
+    """Restore client settings after a crashed wrap."""
+    state = load_marker()
+    if state is None:
+        console.print("Nothing to undo: no lingua-proxy wrap is recorded for this directory.")
+        return
+
+    restore_wrap(state)
+    clear_marker()
+    console.print(f"Restored {state.settings_path}")
+
+
+# -- doctor -------------------------------------------------------------
+
+
+@main.command()
+@click.option("--port", type=int, default=8787, show_default=True)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def doctor(port: int, as_json: bool) -> None:
+    """Check that everything is wired up correctly."""
+    checks = run_checks(port=port)
+    worst = max((c.severity for c in checks), default=0)
+
+    if as_json:
+        click.echo(
+            json.dumps(
+                {
+                    "version": __version__,
+                    "exit_code": worst,
+                    "checks": [c.to_json() for c in checks],
+                },
+                indent=2,
+            )
+        )
+        raise SystemExit(worst)
+
+    table = Table(title=f"lingua-proxy {__version__}", show_lines=False)
+    table.add_column("")
+    table.add_column("Check")
+    table.add_column("Result")
+    for check in checks:
+        table.add_row(check.glyph, check.name, check.summary)
+    console.print(table)
+
+    for check in checks:
+        if check.hint and check.severity:
+            console.print(f"[yellow]hint[/yellow] {check.name}: {check.hint}")
+
+    raise SystemExit(worst)
+
+
+# -- dashboard ----------------------------------------------------------
+
+
+@main.command()
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def dashboard(as_json: bool) -> None:
+    """Show measured token savings."""
+    log = CostLog(path=lingua_home() / "cost_log.jsonl")
+    summary = summarize(log.rows())
+
+    if as_json:
+        click.echo(json.dumps(summary.to_json(), indent=2))
+        return
+
+    if summary.requests == 0:
+        console.print(
+            "No requests recorded yet. Start the proxy, send some traffic, then check back."
+        )
+        return
+
+    table = Table(title="lingua-proxy savings")
+    table.add_column("Metric")
+    table.add_column("Value", justify="right")
+    table.add_row("Requests", str(summary.requests))
+    table.add_row("Translated", str(summary.translated))
+    table.add_row("Passed through", str(summary.passthrough))
+    table.add_row("Cost with proxy", f"${summary.dollars_proxied:.4f}")
+    table.add_row("Cost without", f"${summary.dollars_baseline:.4f}")
+    table.add_row("Saved", f"${summary.dollars_saved:.4f}")
+    table.add_row("Savings", f"{summary.savings_ratio * 100:.1f}%")
+    table.add_row("Translator cost", f"${summary.translator_dollars:.4f}")
+    console.print(table)
+
+    if summary.by_language:
+        langs = Table(title="By language")
+        langs.add_column("Language")
+        langs.add_column("Requests", justify="right")
+        for lang, count in sorted(summary.by_language.items(), key=lambda kv: -kv[1]):
+            langs.add_row(lang, str(count))
+        console.print(langs)
+
+
+# -- bench --------------------------------------------------------------
+
+
+@main.command()
+@click.option("--mode", type=click.Choice(["estimate", "ab"]), default="estimate")
+@click.option("--min-savings", type=float, default=0.30, show_default=True)
+@click.option("--json", "as_json", is_flag=True)
+def bench(mode: str, min_savings: float, as_json: bool) -> None:
+    """Measure real savings against your own upstream."""
+    from lingua_proxy.bench import run_bench
+
+    raise SystemExit(run_bench(mode=mode, min_savings=min_savings, as_json=as_json))