vertex-proxy 0.2.0__py3-none-any.whl

vertex_proxy/__init__.py

@@ -0,0 +1,3 @@
+"""vertex-proxy: Anthropic + Gemini proxy for Vertex AI."""
+
+__version__ = "0.2.0"

vertex_proxy/__main__.py

@@ -0,0 +1,68 @@
+"""Entry point: `python -m vertex_proxy` or `vertex-proxy` CLI."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+import uvicorn
+
+from .config import load_settings
+from .main import build_app
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="vertex-proxy",
+        description="Anthropic + Gemini proxy for Google Cloud Vertex AI",
+    )
+    parser.add_argument("--host", help="bind host (default: 127.0.0.1)")
+    parser.add_argument("--port", type=int, help="bind port (default: 8787)")
+    parser.add_argument("--credentials", help="path to GCP service-account JSON")
+    parser.add_argument("--project-id", help="GCP project ID (inferred from creds if unset)")
+    parser.add_argument(
+        "--log-level",
+        default=None,
+        help="uvicorn log level (default: info)",
+    )
+    args = parser.parse_args()
+
+    # Merge CLI into environment so Settings picks them up.
+    if args.host:
+        _set_env("VERTEX_PROXY_HOST", args.host)
+    if args.port:
+        _set_env("VERTEX_PROXY_PORT", str(args.port))
+    if args.credentials:
+        _set_env("VERTEX_PROXY_CREDENTIALS_PATH", str(Path(args.credentials).expanduser()))
+    if args.project_id:
+        _set_env("VERTEX_PROXY_PROJECT_ID", args.project_id)
+    if args.log_level:
+        _set_env("VERTEX_PROXY_LOG_LEVEL", args.log_level)
+
+    cfg = load_settings()
+    logging.basicConfig(
+        level=getattr(logging, cfg.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    app = build_app(cfg)
+    uvicorn.run(
+        app,
+        host=cfg.host,
+        port=cfg.port,
+        log_level=cfg.log_level,
+        access_log=True,
+    )
+    return 0
+
+
+def _set_env(key: str, val: str) -> None:
+    import os
+
+    os.environ[key] = val
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vertex_proxy/auth.py

@@ -0,0 +1,134 @@
+"""GCP service-account auth with background token refresh.
+
+Vertex AI uses short-lived OAuth access tokens (60-minute TTL) derived from a
+service-account JSON key. This module handles the refresh loop so callers
+always see a valid token.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from pathlib import Path
+
+from google.auth.transport.requests import Request as GoogleAuthRequest
+from google.oauth2 import service_account
+
+logger = logging.getLogger(__name__)
+
+# Vertex AI only needs cloud-platform scope.
+SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]
+
+
+class TokenManager:
+    """Holds a refreshing GCP access token.
+
+    Call ``start()`` once at app startup. Access the current token via
+    ``token`` or ``await get_token()``. Call ``stop()`` at shutdown.
+    """
+
+    def __init__(
+        self,
+        credentials_path: Path | None,
+        refresh_seconds: int = 3000,
+    ) -> None:
+        self._credentials_path = credentials_path
+        self._refresh_seconds = refresh_seconds
+        self._credentials: service_account.Credentials | None = None
+        self._project_id: str | None = None
+        self._refresh_task: asyncio.Task[None] | None = None
+        self._stop_event = asyncio.Event()
+        self._last_refresh: float = 0.0
+
+    @property
+    def project_id(self) -> str | None:
+        """GCP project ID extracted from the service-account key."""
+        return self._project_id
+
+    @property
+    def token(self) -> str:
+        """Current access token. Raises if uninitialised."""
+        if self._credentials is None or self._credentials.token is None:
+            raise RuntimeError("TokenManager not initialised; call start() first")
+        return self._credentials.token
+
+    async def start(self) -> None:
+        """Load credentials and kick off the background refresh loop."""
+        if self._credentials is not None:
+            return
+
+        if self._credentials_path is None:
+            # Fall back to Application Default Credentials
+            import google.auth
+
+            creds, project = google.auth.default(scopes=SCOPES)
+            self._credentials = creds  # type: ignore[assignment]
+            self._project_id = project
+            logger.info("loaded Application Default Credentials; project=%s", project)
+        else:
+            path = Path(self._credentials_path).expanduser()
+            self._credentials = service_account.Credentials.from_service_account_file(
+                str(path), scopes=SCOPES
+            )
+            self._project_id = self._credentials.project_id
+            logger.info(
+                "loaded service-account key from %s; project=%s",
+                path,
+                self._project_id,
+            )
+
+        # Initial refresh; blocks until we have a token.
+        await self._do_refresh()
+        self._refresh_task = asyncio.create_task(self._refresh_loop(), name="token-refresh")
+
+    async def stop(self) -> None:
+        """Signal the refresh loop to stop and await it."""
+        self._stop_event.set()
+        if self._refresh_task is not None:
+            self._refresh_task.cancel()
+            try:
+                await self._refresh_task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+    async def get_token(self) -> str:
+        """Return a valid access token, refreshing if needed."""
+        if self._credentials is None:
+            raise RuntimeError("TokenManager not initialised")
+        # If the token is close to expiry, force a refresh now.
+        if self._credentials.expired or self._credentials.token is None:
+            await self._do_refresh()
+        return self._credentials.token or ""
+
+    # --- internal ----------------------------------------------------------
+
+    async def _do_refresh(self) -> None:
+        """Run the blocking google-auth refresh in a worker thread."""
+        if self._credentials is None:
+            raise RuntimeError("no credentials loaded")
+
+        def _sync_refresh() -> None:
+            request = GoogleAuthRequest()
+            assert self._credentials is not None
+            self._credentials.refresh(request)
+
+        await asyncio.get_running_loop().run_in_executor(None, _sync_refresh)
+        self._last_refresh = time.time()
+        expiry = getattr(self._credentials, "expiry", None)
+        logger.info("refreshed access token; expires=%s", expiry)
+
+    async def _refresh_loop(self) -> None:
+        """Background task: refresh the token every N seconds until stopped."""
+        while not self._stop_event.is_set():
+            try:
+                await asyncio.wait_for(self._stop_event.wait(), timeout=self._refresh_seconds)
+                # If we got here without timeout, stop was requested.
+                return
+            except TimeoutError:
+                # Normal path: time to refresh.
+                try:
+                    await self._do_refresh()
+                except Exception as exc:  # noqa: BLE001
+                    logger.error("token refresh failed: %s", exc, exc_info=True)
+                    # Don't crash the loop; try again next interval.

vertex_proxy/config.py

@@ -0,0 +1,104 @@
+"""Configuration loaded from environment variables."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime configuration for vertex-proxy."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="VERTEX_PROXY_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # --- GCP ---
+    # Path to service-account JSON. Uses GOOGLE_APPLICATION_CREDENTIALS if unset.
+    credentials_path: Path | None = None
+    project_id: str | None = None
+    # Region for Claude (Anthropic) models. us-east5 is the primary serving region.
+    anthropic_region: str = "us-east5"
+    # Region for Gemini models. us-central1 has the widest coverage.
+    gemini_region: str = "us-central1"
+
+    # --- Server ---
+    host: str = "127.0.0.1"
+    port: int = 8787
+    log_level: str = "info"
+
+    # Optional bearer-token auth on the proxy itself. When set, every request
+    # must include `Authorization: Bearer <this value>`. Leave unset for
+    # localhost-only deploys (the default). Set it if you expose the proxy on
+    # a LAN or reverse-proxy it to the internet.
+    api_key: str | None = None
+
+    # Prometheus-format metrics endpoint. Adds request counters + token
+    # counters by model and provider. Off by default to keep the footprint
+    # minimal; enable by setting VERTEX_PROXY_METRICS_ENABLED=true.
+    metrics_enabled: bool = False
+
+    # --- Auth refresh ---
+    # Access tokens live 60 minutes. Refresh at this interval to stay ahead.
+    token_refresh_seconds: int = 3000  # 50 minutes
+
+    # --- Model aliases ---
+    # Map canonical Anthropic model names → Vertex publisher model IDs.
+    # Keep this list explicit; we want to know exactly what we're routing.
+    # Hermes/Claude-Code typically request `claude-sonnet-4-5-20250929`; Vertex
+    # uses `claude-sonnet-4-5@20250929`. The proxy translates.
+    anthropic_model_aliases: dict[str, str] = {
+        # Sonnet 4.5
+        "claude-sonnet-4-5": "claude-sonnet-4-5@20250929",
+        "claude-sonnet-4-5-20250929": "claude-sonnet-4-5@20250929",
+        # Opus 4.5
+        "claude-opus-4-5": "claude-opus-4-5@20250929",
+        "claude-opus-4-5-20250929": "claude-opus-4-5@20250929",
+        # Haiku 4.5
+        "claude-haiku-4-5": "claude-haiku-4-5@20250929",
+        "claude-haiku-4-5-20250929": "claude-haiku-4-5@20250929",
+    }
+
+    # Map canonical Gemini model names → Vertex publisher model IDs.
+    gemini_model_aliases: dict[str, str] = {
+        "gemini-2.5-pro": "gemini-2.5-pro",
+        "gemini-2.5-flash": "gemini-2.5-flash",
+        "gemini-2.0-flash": "gemini-2.0-flash-001",
+    }
+
+    # Region for Vertex MaaS (Model as a Service) open-source partner models:
+    # Kimi K2.5, GLM 5, MiniMax-M2.5, Qwen 3.5, Grok 4.20, etc.
+    # Vertex typically serves these via the global endpoint or us-central1.
+    maas_region: str = "us-central1"
+
+    # Map canonical MaaS model names → Vertex publisher/model path fragments.
+    # Path shape on Vertex MaaS is:
+    #   publishers/{PUBLISHER}/models/{MODEL_ID}
+    # We store the full path fragment so different publishers can coexist.
+    # Check each model's "How to use" tab in Model Garden for the exact shape.
+    maas_model_aliases: dict[str, str] = {
+        # Moonshot (Kimi)
+        "kimi-k2.5": "publishers/moonshotai/models/kimi-k2.5",
+        "kimi-k2": "publishers/moonshotai/models/kimi-k2",
+        # Zhipu (GLM)
+        "glm-5": "publishers/zhipu/models/glm-5",
+        "glm-5.1": "publishers/zhipu/models/glm-5.1",
+        "glm-4.6": "publishers/zhipu/models/glm-4.6",
+        # MiniMax
+        "minimax-m2.5": "publishers/minimax/models/minimax-m2.5",
+        "minimax-m1": "publishers/minimax/models/minimax-m1",
+        # Alibaba (Qwen)
+        "qwen3.5": "publishers/qwen/models/qwen3.5",
+        "qwen-3": "publishers/qwen/models/qwen-3",
+        # xAI (Grok on Vertex)
+        "grok-4.20": "publishers/xai/models/grok-4.20",
+        "grok-4.1-fast": "publishers/xai/models/grok-4.1-fast",
+    }
+
+
+def load_settings() -> Settings:
+    return Settings()

vertex_proxy/main.py

@@ -0,0 +1,604 @@
+"""vertex-proxy FastAPI app.
+
+Exposes:
+  - POST /anthropic/v1/messages                    : Anthropic-compatible, forwards to Vertex.
+  - POST /gemini/v1beta/models/{m}:generateContent : Gemini-compatible, forwards to Vertex.
+  - GET  /health                                   : liveness + token status.
+  - GET  /v1/models                                : list routable models.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from collections import Counter
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse, PlainTextResponse, StreamingResponse
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from . import __version__
+from .auth import TokenManager
+from .config import Settings, load_settings
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_HTTP_TIMEOUT = httpx.Timeout(120.0, connect=10.0)
+# Vertex streaming responses can legitimately go quiet for longer than the
+# default read window while the model is thinking. Keep connect/write/pool
+# bounded, but do not abort a live stream just because no chunk arrived.
+STREAM_HTTP_TIMEOUT = httpx.Timeout(connect=10.0, read=None, write=120.0, pool=120.0)
+
+
+# --- Metrics (Prometheus-format, tiny in-memory counters) -------------------
+# We deliberately don't pull in prometheus_client to keep the dep footprint
+# minimal. This is good enough for a local proxy; use a real metrics library
+# for production multi-instance deployments.
+
+
+class _Metrics:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._requests: Counter[tuple[str, str, str]] = Counter()
+        self._tokens_in: Counter[str] = Counter()
+        self._tokens_out: Counter[str] = Counter()
+        self._started_at = time.time()
+
+    def record_request(self, route: str, model: str, status: int) -> None:
+        with self._lock:
+            self._requests[(route, model, str(status))] += 1
+
+    def record_tokens(self, model: str, prompt: int, completion: int) -> None:
+        with self._lock:
+            self._tokens_in[model] += prompt
+            self._tokens_out[model] += completion
+
+    def render(self) -> str:
+        """Render Prometheus exposition format."""
+        lines = [
+            "# HELP vertex_proxy_uptime_seconds Seconds since proxy start",
+            "# TYPE vertex_proxy_uptime_seconds gauge",
+            f"vertex_proxy_uptime_seconds {time.time() - self._started_at:.0f}",
+            "# HELP vertex_proxy_requests_total Total requests by route, model, and status",
+            "# TYPE vertex_proxy_requests_total counter",
+        ]
+        with self._lock:
+            for (route, model, status), count in self._requests.items():
+                lines.append(
+                    f'vertex_proxy_requests_total{{route="{route}",model="{model}",status="{status}"}} {count}'
+                )
+            lines.append("# HELP vertex_proxy_tokens_in_total Prompt tokens forwarded")
+            lines.append("# TYPE vertex_proxy_tokens_in_total counter")
+            for model, count in self._tokens_in.items():
+                lines.append(f'vertex_proxy_tokens_in_total{{model="{model}"}} {count}')
+            lines.append("# HELP vertex_proxy_tokens_out_total Completion tokens returned")
+            lines.append("# TYPE vertex_proxy_tokens_out_total counter")
+            for model, count in self._tokens_out.items():
+                lines.append(f'vertex_proxy_tokens_out_total{{model="{model}"}} {count}')
+        return "\n".join(lines) + "\n"
+
+
+_METRICS = _Metrics()
+
+
+# --- app factory ------------------------------------------------------------
+
+
+def build_app(settings: Settings | None = None) -> FastAPI:
+    cfg = settings or load_settings()
+    token_mgr = TokenManager(
+        credentials_path=cfg.credentials_path,
+        refresh_seconds=cfg.token_refresh_seconds,
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+        await token_mgr.start()
+        # Resolve project ID from credentials if not explicitly configured.
+        if cfg.project_id is None:
+            cfg.project_id = token_mgr.project_id
+        if not cfg.project_id:
+            raise RuntimeError(
+                "no GCP project_id: set VERTEX_PROXY_PROJECT_ID "
+                "or use a service-account key that includes project_id"
+            )
+        logger.info("vertex-proxy ready; project=%s", cfg.project_id)
+        app.state.token_mgr = token_mgr
+        app.state.cfg = cfg
+        app.state.http = httpx.AsyncClient(timeout=DEFAULT_HTTP_TIMEOUT)
+        try:
+            yield
+        finally:
+            await app.state.http.aclose()
+            await token_mgr.stop()
+
+    app = FastAPI(
+        title="vertex-proxy",
+        description="Anthropic + Gemini API-compatible proxy for Google Cloud Vertex AI",
+        version=__version__,
+        lifespan=lifespan,
+    )
+
+    # --- optional bearer-token auth on the proxy itself ------------------------
+    # When VERTEX_PROXY_API_KEY is set, every non-health route requires it.
+    # Use when exposing the proxy on a LAN or reverse-proxying to the internet.
+    bearer = HTTPBearer(auto_error=False)
+
+    async def require_api_key(
+        creds: HTTPAuthorizationCredentials | None = Depends(bearer),  # noqa: B008
+    ) -> None:
+        if not cfg.api_key:
+            return  # auth not required
+        if creds is None or creds.credentials != cfg.api_key:
+            raise HTTPException(
+                status_code=401,
+                detail="missing or invalid bearer token",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+    # --- health ----------------------------------------------------------------
+
+    @app.get("/health")
+    async def health() -> dict[str, Any]:
+        try:
+            # Try to get a token; proves auth is working.
+            await token_mgr.get_token()
+            return {"status": "ok", "project": cfg.project_id}
+        except Exception as exc:  # noqa: BLE001
+            return JSONResponse(
+                status_code=503,
+                content={"status": "unhealthy", "error": str(exc)},
+            )
+
+    # --- metrics (Prometheus, opt-in) ----------------------------------------
+
+    @app.get("/metrics")
+    async def metrics() -> PlainTextResponse:
+        if not cfg.metrics_enabled:
+            raise HTTPException(
+                status_code=404,
+                detail="metrics disabled; set VERTEX_PROXY_METRICS_ENABLED=true to enable",
+            )
+        return PlainTextResponse(_METRICS.render(), media_type="text/plain; version=0.0.4")
+
+    @app.get("/v1/models", dependencies=[Depends(require_api_key)])
+    async def list_models() -> dict[str, Any]:
+        return {
+            "object": "list",
+            "data": [
+                {
+                    "id": alias,
+                    "object": "model",
+                    "vertex_model_id": real,
+                    "provider": "anthropic-vertex",
+                    "region": cfg.anthropic_region,
+                }
+                for alias, real in cfg.anthropic_model_aliases.items()
+            ]
+            + [
+                {
+                    "id": alias,
+                    "object": "model",
+                    "vertex_model_id": real,
+                    "provider": "gemini-vertex",
+                    "region": cfg.gemini_region,
+                }
+                for alias, real in cfg.gemini_model_aliases.items()
+            ]
+            + [
+                {
+                    "id": alias,
+                    "object": "model",
+                    "vertex_model_id": path,
+                    "provider": "maas-vertex",
+                    "region": cfg.maas_region,
+                }
+                for alias, path in cfg.maas_model_aliases.items()
+            ],
+        }
+
+    # --- Anthropic routes ------------------------------------------------------
+
+    @app.post("/anthropic/v1/messages", dependencies=[Depends(require_api_key)])
+    async def anthropic_messages(request: Request) -> Any:
+        return await _handle_anthropic(request, cfg, token_mgr)
+
+    # Also accept /v1/messages directly (some clients won't let you override path).
+    @app.post("/v1/messages", dependencies=[Depends(require_api_key)])
+    async def anthropic_messages_root(request: Request) -> Any:
+        return await _handle_anthropic(request, cfg, token_mgr)
+
+    # --- Gemini routes ---------------------------------------------------------
+    # Gemini SDK hits /v1beta/models/{model}:generateContent and :streamGenerateContent.
+    # We pass-through both.
+
+    @app.post(
+        "/gemini/v1beta/models/{model_and_action:path}", dependencies=[Depends(require_api_key)]
+    )
+    async def gemini_generate(model_and_action: str, request: Request) -> Any:
+        return await _handle_gemini(model_and_action, request, cfg, token_mgr)
+
+    @app.post("/v1beta/models/{model_and_action:path}", dependencies=[Depends(require_api_key)])
+    async def gemini_generate_root(model_and_action: str, request: Request) -> Any:
+        return await _handle_gemini(model_and_action, request, cfg, token_mgr)
+
+    # --- OpenAI-compatible route for Vertex MaaS models ------------------------
+    # Kimi K2.5, GLM 5, MiniMax-M2.5, Qwen 3.5, Grok 4.20, etc.
+    # Vertex exposes these through an OpenAI Chat Completions-compatible
+    # endpoint at /v1beta1/.../endpoints/openapi/chat/completions.
+
+    @app.post("/openai/v1/chat/completions", dependencies=[Depends(require_api_key)])
+    async def openai_chat_completions(request: Request) -> Any:
+        return await _handle_openai(request, cfg, token_mgr)
+
+    @app.post("/v1/chat/completions", dependencies=[Depends(require_api_key)])
+    async def openai_chat_completions_root(request: Request) -> Any:
+        return await _handle_openai(request, cfg, token_mgr)
+
+    # Some OpenAI clients (notably Hermes's internal one) drop the /v1 prefix
+    # when you set base_url to the server root. Accept that shape too.
+    @app.post("/chat/completions", dependencies=[Depends(require_api_key)])
+    async def openai_chat_completions_bare(request: Request) -> Any:
+        return await _handle_openai(request, cfg, token_mgr)
+
+    # /v1/models/{model}: some clients probe for a specific model's existence
+    # before dispatching. Return minimal metadata so they don't bail.
+    @app.get("/v1/models/{model_id:path}")
+    async def get_model(model_id: str) -> dict[str, Any]:
+        if (
+            model_id in cfg.anthropic_model_aliases
+            or model_id in cfg.gemini_model_aliases
+            or model_id in cfg.maas_model_aliases
+            or model_id.startswith("google/")
+        ):
+            return {"id": model_id, "object": "model", "owned_by": "vertex-proxy"}
+        raise HTTPException(status_code=404, detail=f"model '{model_id}' not found")
+
+    # --- OpenAI-client URL tolerance ------------------------------------------
+    # OpenAI-style clients construct their final URL by appending a fixed suffix
+    # ("/chat/completions" for inference, "/models" or "/v1/models" for model
+    # discovery) onto whatever base_url the user configured. A user who wants
+    # Gemini traffic naturally sets base_url to ".../gemini", but that prefix is
+    # the *native* generateContent route, so the appended "/chat/completions"
+    # would 404 (see issue #1). Gemini is reachable through Vertex's OpenAI-compat
+    # endpoint inside _handle_openai, which keys off the request body's `model`
+    # and ignores the URL prefix entirely. So we mount the OpenAI-compat handler
+    # (and the discovery endpoints) under the "/gemini" and "/openai" prefixes as
+    # well as the bare root, letting any reasonable base_url choice work.
+    _chat_alias_paths = (
+        "/openai/chat/completions",
+        "/gemini/v1/chat/completions",
+        "/gemini/chat/completions",
+    )
+    for _path in _chat_alias_paths:
+        app.add_api_route(
+            _path,
+            openai_chat_completions,
+            methods=["POST"],
+            dependencies=[Depends(require_api_key)],
+        )
+
+    # Model-catalog discovery under the same prefixes. Clients probe these before
+    # dispatching; a 404 produces noisy logs and "could not fetch models" warnings
+    # (and a few clients refuse to proceed). Mirror /v1/models everywhere a client
+    # is likely to look.
+    _models_list_alias_paths = (
+        "/models",
+        "/openai/v1/models",
+        "/openai/models",
+        "/gemini/v1/models",
+        "/gemini/models",
+        "/api/v1/models",
+        "/openai/api/v1/models",
+        "/gemini/api/v1/models",
+    )
+    for _path in _models_list_alias_paths:
+        app.add_api_route(
+            _path,
+            list_models,
+            methods=["GET"],
+            dependencies=[Depends(require_api_key)],
+        )
+
+    _model_probe_alias_paths = (
+        "/openai/v1/models/{model_id:path}",
+        "/gemini/v1/models/{model_id:path}",
+    )
+    for _path in _model_probe_alias_paths:
+        app.add_api_route(_path, get_model, methods=["GET"])
+
+    return app
+
+
+# --- Anthropic handler ------------------------------------------------------
+
+
+async def _handle_anthropic(request: Request, cfg: Settings, tm: TokenManager) -> Any:
+    try:
+        body = await request.json()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail="request body must be JSON") from exc
+
+    requested_model = (body.get("model") or "").strip()
+    if not requested_model:
+        raise HTTPException(status_code=400, detail="missing 'model' in request body")
+
+    # Alias resolution.
+    vertex_model = cfg.anthropic_model_aliases.get(requested_model, requested_model)
+    if "@" not in vertex_model:
+        # Accept a bare name only if it's an exact match; otherwise fail loud.
+        raise HTTPException(
+            status_code=400,
+            detail=f"unknown anthropic model '{requested_model}'. "
+            f"known aliases: {sorted(cfg.anthropic_model_aliases.keys())}",
+        )
+
+    # Anthropic-on-Vertex wants `anthropic_version` and removes `model`.
+    upstream_body = {k: v for k, v in body.items() if k != "model"}
+    upstream_body.setdefault("anthropic_version", "vertex-2023-10-16")
+
+    streaming = bool(body.get("stream"))
+    # Vertex endpoint: :streamRawPredict for streaming, :rawPredict for one-shot.
+    action = "streamRawPredict" if streaming else "rawPredict"
+    url = (
+        f"https://{cfg.anthropic_region}-aiplatform.googleapis.com/v1/projects/"
+        f"{cfg.project_id}/locations/{cfg.anthropic_region}/publishers/anthropic/"
+        f"models/{vertex_model}:{action}"
+    )
+
+    token = await tm.get_token()
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    }
+
+    logger.info(
+        "anthropic: model=%s → vertex_model=%s streaming=%s",
+        requested_model,
+        vertex_model,
+        streaming,
+    )
+
+    http: httpx.AsyncClient = request.app.state.http
+    if streaming:
+        _METRICS.record_request("anthropic", requested_model, 200)
+        return StreamingResponse(
+            _stream_bytes(http, url, headers, upstream_body),
+            media_type="text/event-stream",
+        )
+
+    try:
+        resp = await http.post(url, headers=headers, json=upstream_body)
+    except httpx.HTTPError as exc:
+        logger.error("anthropic upstream error: %s", exc)
+        raise HTTPException(status_code=502, detail=f"upstream error: {exc}") from exc
+
+    return _passthrough_response(resp, route="anthropic", model=requested_model)
+
+
+# --- Gemini handler ---------------------------------------------------------
+
+
+async def _handle_gemini(
+    model_and_action: str, request: Request, cfg: Settings, tm: TokenManager
+) -> Any:
+    # model_and_action is like "gemini-2.5-pro:generateContent" or
+    # "gemini-2.5-flash:streamGenerateContent".
+    if ":" not in model_and_action:
+        raise HTTPException(
+            status_code=400,
+            detail="gemini path must include action (e.g., ':generateContent')",
+        )
+    requested_model, action = model_and_action.rsplit(":", 1)
+    vertex_model = cfg.gemini_model_aliases.get(requested_model, requested_model)
+    streaming = "stream" in action.lower()
+
+    try:
+        body = await request.json()
+    except Exception:
+        body = {}
+
+    url = (
+        f"https://{cfg.gemini_region}-aiplatform.googleapis.com/v1/projects/"
+        f"{cfg.project_id}/locations/{cfg.gemini_region}/publishers/google/"
+        f"models/{vertex_model}:{action}"
+    )
+    # Pass through query params (e.g., alt=sse).
+    if request.url.query:
+        url = f"{url}?{request.url.query}"
+
+    token = await tm.get_token()
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    }
+
+    logger.info(
+        "gemini: model=%s action=%s streaming=%s",
+        requested_model,
+        action,
+        streaming,
+    )
+
+    http: httpx.AsyncClient = request.app.state.http
+    if streaming:
+        _METRICS.record_request("gemini", requested_model, 200)
+        return StreamingResponse(
+            _stream_bytes(http, url, headers, body),
+            media_type="text/event-stream",
+        )
+
+    try:
+        resp = await http.post(url, headers=headers, json=body)
+    except httpx.HTTPError as exc:
+        logger.error("gemini upstream error: %s", exc)
+        raise HTTPException(status_code=502, detail=f"upstream error: {exc}") from exc
+
+    return _passthrough_response(resp, route="gemini", model=requested_model)
+
+
+# --- OpenAI-compatible (Vertex MaaS) handler -------------------------------
+
+
+async def _handle_openai(request: Request, cfg: Settings, tm: TokenManager) -> Any:
+    """Forward OpenAI Chat Completions requests to Vertex AI MaaS models.
+
+    Supports Moonshot (Kimi), Zhipu (GLM), MiniMax, Alibaba (Qwen), xAI (Grok).
+    """
+    try:
+        body = await request.json()
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail="request body must be JSON") from exc
+
+    requested_model = (body.get("model") or "").strip()
+    if not requested_model:
+        raise HTTPException(status_code=400, detail="missing 'model' in request body")
+
+    streaming = bool(body.get("stream"))
+    token = await tm.get_token()
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    }
+
+    # --- routing: Gemini via Vertex OpenAI-compat, or MaaS partner model. ---
+    if requested_model in cfg.gemini_model_aliases or requested_model.startswith("google/"):
+        # Gemini models through Vertex's OpenAI-compat endpoint.
+        # See: https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/call-gemini-using-openai-library
+        bare_model = requested_model.removeprefix("google/")
+        vertex_model = cfg.gemini_model_aliases.get(bare_model, bare_model)
+        url = (
+            f"https://{cfg.gemini_region}-aiplatform.googleapis.com/v1beta1/projects/"
+            f"{cfg.project_id}/locations/{cfg.gemini_region}/endpoints/openapi/chat/completions"
+        )
+        upstream_body = dict(body)
+        upstream_body["model"] = f"google/{vertex_model}"
+        logger.info(
+            "openai→gemini: model=%s → %s streaming=%s",
+            requested_model,
+            upstream_body["model"],
+            streaming,
+        )
+    else:
+        # MaaS partner models (Kimi, GLM, MiniMax, Qwen, Grok).
+        path_fragment = cfg.maas_model_aliases.get(requested_model)
+        if path_fragment is None:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"unknown MaaS model '{requested_model}'. "
+                    f"known aliases: {sorted(cfg.maas_model_aliases.keys())} "
+                    f"or gemini: {sorted(cfg.gemini_model_aliases.keys())}"
+                ),
+            )
+        url = (
+            f"https://{cfg.maas_region}-aiplatform.googleapis.com/v1beta1/projects/"
+            f"{cfg.project_id}/locations/{cfg.maas_region}/{path_fragment}/chat/completions"
+        )
+        upstream_body = dict(body)
+        upstream_body["model"] = path_fragment.rsplit("/", 1)[-1]
+        logger.info(
+            "openai→maas: model=%s → path=%s streaming=%s",
+            requested_model,
+            path_fragment,
+            streaming,
+        )
+
+    http: httpx.AsyncClient = request.app.state.http
+    if streaming:
+        _METRICS.record_request("openai", requested_model, 200)
+        return StreamingResponse(
+            _stream_bytes(http, url, headers, upstream_body),
+            media_type="text/event-stream",
+        )
+
+    try:
+        resp = await http.post(url, headers=headers, json=upstream_body)
+    except httpx.HTTPError as exc:
+        logger.error("maas upstream error: %s", exc)
+        raise HTTPException(status_code=502, detail=f"upstream error: {exc}") from exc
+
+    return _passthrough_response(resp, route="openai", model=requested_model)
+
+
+# --- helpers ----------------------------------------------------------------
+
+
+async def _stream_bytes(
+    http: httpx.AsyncClient,
+    url: str,
+    headers: dict[str, str],
+    body: dict[str, Any],
+) -> AsyncGenerator[bytes, None]:
+    try:
+        async with http.stream(
+            "POST",
+            url,
+            headers=headers,
+            json=body,
+            timeout=STREAM_HTTP_TIMEOUT,
+        ) as r:
+            if r.status_code >= 400:
+                # StreamingResponse has already committed to a 200 status by
+                # the time this generator runs, so emit a structured SSE error
+                # instead of raising and leaving the client with a broken chunk.
+                err_body = b""
+                async for chunk in r.aiter_bytes():
+                    err_body += chunk
+                detail = err_body.decode("utf-8", errors="replace")[:2000]
+                logger.warning("upstream stream returned %s: %s", r.status_code, detail)
+                yield _stream_error("upstream_http_error", detail, status_code=r.status_code)
+                return
+            async for chunk in r.aiter_bytes():
+                yield chunk
+    except httpx.ReadTimeout as exc:
+        logger.warning("upstream stream read timeout: %s", exc)
+        yield _stream_error(
+            "upstream_read_timeout",
+            "upstream stream stalled before completion",
+        )
+    except httpx.HTTPError as exc:
+        logger.error("upstream stream error: %s", exc)
+        yield _stream_error("upstream_stream_error", str(exc))
+
+
+def _stream_error(error_type: str, message: str, status_code: int | None = None) -> bytes:
+    payload: dict[str, Any] = {
+        "error": {
+            "type": error_type,
+            "message": message[:2000],
+        }
+    }
+    if status_code is not None:
+        payload["error"]["status_code"] = status_code
+    return f"event: error\ndata: {json.dumps(payload)}\n\n".encode()
+
+
+def _passthrough_response(resp: httpx.Response, route: str = "", model: str = "") -> JSONResponse:
+    """Forward upstream status + JSON body to the client.
+
+    If ``route`` + ``model`` are provided and metrics are enabled, record
+    request count + token usage from the OpenAI/Anthropic-style ``usage`` field.
+    """
+    try:
+        payload = resp.json()
+    except json.JSONDecodeError:
+        # Not JSON; forward as text wrapped.
+        payload = {"raw": resp.text[:4000]}
+
+    if route and model:
+        _METRICS.record_request(route, model, resp.status_code)
+        usage = payload.get("usage") if isinstance(payload, dict) else None
+        if isinstance(usage, dict):
+            prompt = int(usage.get("prompt_tokens") or usage.get("input_tokens") or 0)
+            completion = int(usage.get("completion_tokens") or usage.get("output_tokens") or 0)
+            if prompt or completion:
+                _METRICS.record_tokens(model, prompt, completion)
+
+    return JSONResponse(status_code=resp.status_code, content=payload)

vertex_proxy-0.2.0.dist-info/METADATA

@@ -0,0 +1,332 @@
+Metadata-Version: 2.4
+Name: vertex-proxy
+Version: 0.2.0
+Summary: Anthropic + Gemini + OpenAI API-compatible proxy for Google Cloud Vertex AI. Bridges static-URL API consumers to Vertex AI's service-account auth.
+Project-URL: Homepage, https://github.com/prasadus92/vertex-proxy
+Project-URL: Author, https://prasad.tech
+Project-URL: Issues, https://github.com/prasadus92/vertex-proxy/issues
+Project-URL: Changelog, https://github.com/prasadus92/vertex-proxy/blob/main/CHANGELOG.md
+Author-email: Prasad Subrahmanya <prasad@luminik.io>
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,api-proxy,claude,fastapi,gcp,gemini,google-cloud,llm,llm-proxy,openai,openai-compatible,proxy,service-account,vertex-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.109
+Requires-Dist: google-auth>=2.28
+Requires-Dist: httpx>=0.26
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: requests>=2.31
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vertex-proxy
+
+[![CI](https://github.com/prasadus92/vertex-proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/prasadus92/vertex-proxy/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+A small, local-only proxy that bridges **any tool speaking the Anthropic Messages API, Gemini API, or OpenAI Chat Completions API** to **Google Cloud Vertex AI**, so you can point existing clients at Vertex without changing their code.
+
+## What this is for
+
+You have a tool (Claude Code, Hermes Agent, opencode, Cline, Continue.dev, a custom SDK integration, etc.) that already knows how to talk to:
+
+- `api.anthropic.com`
+- `generativelanguage.googleapis.com`
+- any OpenAI-compatible endpoint
+
+You want that same tool to hit Vertex AI instead, maybe because you want to burn GCP credits, unify billing, or get higher quotas than the public APIs offer.
+
+The problem: Vertex uses **short-lived OAuth access tokens** from a service-account key. Most tools expect a static `Authorization: Bearer xxx` header. Nobody wants to rebuild auth in every client.
+
+vertex-proxy runs on `127.0.0.1:8787`, handles the auth refresh loop, and translates between the public API shapes and Vertex's publisher-model endpoints.
+
+```
+┌──────────────┐   Anthropic/Gemini/OpenAI   ┌──────────────┐   GCP auth   ┌────────────┐
+│  your tool   │ ──────────────────────────► │ vertex-proxy │ ──────────►  │ Vertex AI  │
+└──────────────┘   localhost:8787            └──────────────┘   SA JWT     └────────────┘
+```
+
+No client changes. Small, dependency-light Python. MIT licensed.
+
+## Install
+
+Python 3.11+, a GCP project with Vertex AI API enabled, and a service-account JSON key with `roles/aiplatform.user`.
+
+```bash
+pipx install vertex-proxy
+# or:  uv tool install vertex-proxy
+# or run it without installing:  uvx vertex-proxy
+```
+
+### From source (for development)
+
+```bash
+git clone https://github.com/prasadus92/vertex-proxy.git
+cd vertex-proxy
+python -m venv .venv
+.venv/bin/pip install -e .
+```
+
+## Run
+
+```bash
+export VERTEX_PROXY_CREDENTIALS_PATH=/path/to/service-account.json
+export VERTEX_PROXY_PROJECT_ID=your-gcp-project
+vertex-proxy
+# → listening on http://127.0.0.1:8787
+```
+
+Or inline:
+
+```bash
+vertex-proxy \
+  --credentials ~/.vertex/key.json \
+  --project-id my-project \
+  --port 8787
+```
+
+(From a source checkout, the command is `.venv/bin/vertex-proxy`.)
+
+Verify:
+
+```bash
+curl http://127.0.0.1:8787/health
+# {"status":"ok","project":"my-project"}
+
+curl -X POST http://127.0.0.1:8787/gemini/v1beta/models/gemini-2.5-flash:generateContent \
+  -H "Content-Type: application/json" \
+  -d '{"contents":[{"role":"user","parts":[{"text":"hello"}]}]}'
+```
+
+## Endpoints
+
+| Path | API compat | Vertex backend |
+|---|---|---|
+| `POST /anthropic/v1/messages` | Anthropic Messages API | `publishers/anthropic/models/{model}:rawPredict` |
+| `POST /gemini/v1beta/models/{m}:{action}` | Gemini generateContent API | `publishers/google/models/{m}:{action}` |
+| `POST /openai/v1/chat/completions` | OpenAI Chat Completions | Gemini (via Vertex OpenAI-compat) + MaaS partner models (Kimi, GLM, MiniMax, Qwen, Grok) |
+| `GET /v1/models` | - | Lists routable models |
+| `GET /health` | - | Liveness + auth check |
+
+The OpenAI Chat Completions shape is also accepted under the `/gemini` prefix and the bare root, so clients that build their URL from a `base_url` of `.../openai`, `.../gemini`, or the server root all reach the same handler. Model-discovery probes (`/v1/models`, `/models`) are mirrored under those prefixes too.
+
+Streaming is supported on all routes (Anthropic, Gemini, and the OpenAI-compat route).
+Streaming requests use a no-read-timeout upstream client so long Vertex generations do not get cut off during idle periods.
+
+## Pre-configured models
+
+All aliases live in [`vertex_proxy/config.py`](vertex_proxy/config.py); extend as needed.
+
+**Anthropic** (on Vertex, `us-east5` by default)
+- `claude-sonnet-4-5-20250929` → `claude-sonnet-4-5@20250929`
+- `claude-opus-4-5-20250929` → `claude-opus-4-5@20250929`
+- `claude-haiku-4-5-20250929` → `claude-haiku-4-5@20250929`
+
+**Gemini** (on Vertex, `us-central1` by default)
+- `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash`
+
+**MaaS partner models** (OpenAI-compatible route)
+- `kimi-k2.5`, `kimi-k2` (Moonshot)
+- `glm-5`, `glm-5.1`, `glm-4.6` (Zhipu)
+- `minimax-m2.5`, `minimax-m1` (MiniMax)
+- `qwen3.5`, `qwen-3` (Alibaba)
+- `grok-4.20`, `grok-4.1-fast` (xAI)
+
+## Recipes
+
+### Claude Code CLI
+
+Point Claude Code at the proxy via `ANTHROPIC_BASE_URL`:
+
+```bash
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787/anthropic
+export ANTHROPIC_AUTH_TOKEN=bypass   # proxy ignores this; Vertex auth is server-side
+claude
+```
+
+Your local Claude Code session now bills against your GCP project instead of api.anthropic.com.
+
+### Hermes Agent
+
+Add to `~/.hermes/config.yaml`:
+
+```yaml
+custom_providers:
+  - name: vertex-gemini
+    # Hermes's openai_chat transport appends /chat/completions (and probes
+    # /v1/models) onto base_url. Gemini is served through Vertex's OpenAI-compat
+    # layer, so any of these bases work: .../openai, .../gemini, or the bare root.
+    base_url: http://127.0.0.1:8787/openai
+    transport: openai_chat
+
+  - name: vertex-anthropic
+    base_url: http://127.0.0.1:8787/anthropic
+    transport: anthropic_messages
+
+fallback_model:
+  provider: vertex-gemini
+  model: gemini-2.5-pro
+```
+
+Zero Hermes source changes required. Picks up the existing `custom_providers` mechanism. The `openai_chat` transport routes through the proxy's OpenAI-compat handler, which dispatches Gemini models to Vertex's OpenAI-compatible endpoint based on the request body's `model`.
+
+### opencode / Cline / any Anthropic-SDK client
+
+Set the base URL environment variable the client supports (usually one of `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_URL`, or the equivalent in your client's config):
+
+```bash
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787/anthropic
+```
+
+## Run as a service (macOS launchd)
+
+```bash
+cd launchd
+./install.sh --credentials /path/to/key.json --project my-gcp-project
+```
+
+This renders the plist template, copies it to `~/Library/LaunchAgents/`, loads it, and does a health check. Logs go to `~/Library/Logs/vertex-proxy.{log,err}`.
+
+Stop:
+```bash
+launchctl unload ~/Library/LaunchAgents/ai.hermes.vertex-proxy.plist
+```
+
+For Linux, the same pattern works with systemd; see [`examples/systemd.service`](examples/systemd.service).
+
+## Configuration reference
+
+All settings accept `VERTEX_PROXY_` env var prefix or CLI flags.
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `VERTEX_PROXY_CREDENTIALS_PATH` | - | Service-account JSON path (falls back to ADC) |
+| `VERTEX_PROXY_PROJECT_ID` | inferred from key | GCP project ID |
+| `VERTEX_PROXY_ANTHROPIC_REGION` | `us-east5` | Region for Claude |
+| `VERTEX_PROXY_GEMINI_REGION` | `us-central1` | Region for Gemini |
+| `VERTEX_PROXY_MAAS_REGION` | `us-central1` | Region for Kimi / GLM / MiniMax / Qwen / Grok |
+| `VERTEX_PROXY_HOST` | `127.0.0.1` | Bind host |
+| `VERTEX_PROXY_PORT` | `8787` | Bind port |
+| `VERTEX_PROXY_TOKEN_REFRESH_SECONDS` | `3000` | Token refresh interval (50 min) |
+| `VERTEX_PROXY_LOG_LEVEL` | `info` | uvicorn log level |
+
+## A word on GCP credits
+
+**GCP promotional credits (startup, free trial, partner) typically do NOT cover Google Cloud Marketplace purchases.** On Vertex AI, this matters because:
+
+- **First-party Google models** (Gemini 2.5 Pro / Flash, Gemma) are billed as "Vertex AI API" usage → **credits cover ✅**
+- **Partner models** (Claude, Kimi, GLM, MiniMax, Grok) are typically billed via GCP Marketplace → **credits usually don't cover ❌**
+
+The "Promotional credits" section of your model's agreement page in Google Cloud Console will tell you explicitly. Quote from a typical Claude-on-Vertex agreement:
+
+> *Most Google Cloud promotional credits don't apply to Google Cloud Marketplace purchases.*
+
+If credit-burn is your goal, point vertex-proxy at Gemini. If billing unification is your goal, vertex-proxy works for everything.
+
+## Security
+
+vertex-proxy binds to `127.0.0.1` by default and **ships with no authentication**. It's designed as a local-loopback shim; anyone who can reach it can spend your GCP credits via your service account.
+
+Do not expose it to a public interface. If you need remote access, put it behind a reverse proxy with proper auth (nginx + basic auth, Tailscale, Cloud Run with IAP, etc.).
+
+## Status
+
+- [x] Anthropic Messages API → Vertex Claude (with streaming)
+- [x] Gemini generateContent API → Vertex Gemini (with streaming)
+- [x] OpenAI Chat Completions → Vertex Gemini via Vertex's OpenAI-compat layer
+- [x] OpenAI Chat Completions → Vertex MaaS partner models (Kimi, GLM, MiniMax, Qwen, Grok)
+- [x] Multiple URL shapes accepted for OpenAI client compatibility: chat completions under the `/openai`, `/gemini`, and bare-root prefixes (e.g. `/openai/v1/chat/completions`, `/gemini/chat/completions`, `/chat/completions`), plus model-discovery (`/v1/models`, `/models`) mirrored under the same prefixes
+- [x] Automatic GCP service-account token refresh
+- [x] launchd (macOS) + systemd (Linux) service recipes
+- [x] Dockerfile + docker-compose for containerized deploy
+- [x] Optional bearer-token auth on the proxy itself (for remote deploys)
+- [x] Prometheus metrics endpoint at `/metrics`
+- [x] `pipx` / `uv` / `uvx` install via PyPI (tag-triggered OIDC Trusted Publishing release workflow)
+- [x] 22 unit tests, GitHub Actions CI on Python 3.11 + 3.12
+
+### Tested with
+- [x] Hermes Agent: verified end-to-end with live Gemini 2.5 Flash dispatch
+- [x] Claude Code CLI: via `ANTHROPIC_BASE_URL` env
+- [x] Direct `curl` against all routes
+
+## Troubleshooting
+
+### Client reports incomplete chunked read during streaming
+
+This usually means the upstream Vertex stream was interrupted. Current streaming routes keep the upstream read open without a fixed read timeout and return a structured SSE error if Vertex still fails mid-stream, so clients should receive a clean error event instead of a broken HTTP chunk.
+
+### 404 "model not found" on Claude routes
+
+Most Vertex AI Claude model endpoints require one-time enablement in Model Garden. Go to https://console.cloud.google.com/vertex-ai/publishers/anthropic/model-garden and click ENABLE on the specific model (Sonnet, Opus, Haiku). Accept the Marketplace T&Cs. Your service account can then call them.
+
+Note: GCP promotional credits typically don't cover Marketplace models. See "A word on GCP credits" above.
+
+### 404 "model not found" on MaaS routes (Kimi, GLM, MiniMax, Qwen, Grok)
+
+Same as Claude: Vertex partner models require Model Garden enablement per model. Additionally, the MaaS path in `config.py` is a best-effort guess at Vertex's URL shape for these partners. If you hit 404s after enablement, check the "How to use" tab on the model's page in Model Garden and update the `maas_model_aliases` entry with the exact path fragment Google shows.
+
+### 401 / 403 on all routes
+
+Your service account lacks `roles/aiplatform.user`. Grant it:
+```
+gcloud projects add-iam-policy-binding YOUR_PROJECT \
+  --member="serviceAccount:YOUR_SA@YOUR_PROJECT.iam.gserviceaccount.com" \
+  --role="roles/aiplatform.user"
+```
+
+### Gemini 2.5 returns empty content with `reasoning_tokens` populated
+
+Gemini 2.5 models use an internal "thinking" budget that counts against `max_tokens`. If `max_tokens` is too low, the model may use all its budget on thinking and return no visible output. Raise `max_tokens` to at least 100 for anything beyond trivial replies.
+
+### Hermes (or any OpenAI-chat client) returns `404 {'detail': 'Not Found'}` for Gemini
+
+This happens when an OpenAI-chat client is pointed at the `/gemini` base. That client builds its request URL by appending `/chat/completions` (so it actually calls `/gemini/chat/completions`), but `/gemini` is the *native* `generateContent` route, which has no `chat/completions` handler. `curl` against `/gemini/v1beta/models/...:generateContent` works because that's the native shape; the OpenAI-chat client uses a different shape.
+
+The proxy now accepts the OpenAI-chat shape under the `/gemini` and `/openai` prefixes as well as the bare root, so `transport: openai_chat` works against any of these bases. If you're on an older build, point the provider's `base_url` at `http://127.0.0.1:8787/openai` (or the bare `http://127.0.0.1:8787`) instead of `.../gemini`. Gemini still routes correctly because the OpenAI-compat handler dispatches by the request body's `model`.
+
+### Request works with `curl` but fails from my OpenAI client
+
+Your client is probably sending requests to a URL shape the shim didn't expect. The shim accepts `/chat/completions`, `/v1/chat/completions`, `/openai/v1/chat/completions`, `/openai/chat/completions`, `/gemini/v1/chat/completions`, and `/gemini/chat/completions` for OpenAI-compatible traffic, and mirrors model discovery (`/v1/models`, `/models`) under the same prefixes. If your client sends something else, file an issue with the exact URL shape and we'll add it.
+
+### Token refresh errors in logs
+
+The background refresh task logs errors but doesn't crash the process. If you see repeated refresh failures, check:
+1. Service account JSON path is correct (`VERTEX_PROXY_CREDENTIALS_PATH`)
+2. Machine clock is in sync (GCP JWT exchange is clock-sensitive)
+3. Service account isn't disabled or rotated in GCP IAM
+
+## Comparison with alternatives
+
+| Tool | What it does | Fit |
+|---|---|---|
+| **vertex-proxy** (this) | Bridge existing Anthropic/Gemini/OpenAI clients to Vertex AI with auto-auth | You already use a tool with configurable base URL and want to point it at Vertex without rewriting auth |
+| **LiteLLM** | Full-featured multi-provider router with caching, budgets, observability | Managing many providers centrally with policies; heavier dependency |
+| **openai-compat-server** (various) | OpenAI shape over arbitrary backend | Similar to one route of vertex-proxy; doesn't handle GCP SA auth natively |
+| **Vertex AI Python SDK** | Direct first-party Google SDK | You're writing new code and want to talk Vertex directly |
+| **Anthropic Python SDK with Vertex backend** | First-party SDK with Vertex mode flag | You're writing new Anthropic code and control the client |
+
+Use vertex-proxy when you have an **existing** tool you can't modify and need to redirect its traffic to Vertex.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Credits
+
+Built by Prasad Subrahmanya ([prasad.tech](https://prasad.tech) · [@prasadus92](https://github.com/prasadus92)) as part of solving the "Hermes fallback model" problem for [Luminik](https://luminik.io), then extracted into a standalone tool because the shim turned out to be useful beyond Hermes.

vertex_proxy-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+vertex_proxy/__init__.py,sha256=ToDJZ3kXyPkqgK-G0GJpMglTTwGKsMgwgfNRIuGL7Xc,83
+vertex_proxy/__main__.py,sha256=2juNiHQpWzvqM6AeaD1h4WJSDpQed3JbPRgiPC7jZLQ,1894
+vertex_proxy/auth.py,sha256=enqOFZ8OyyUP0o0c6dSAP6qAnUB_eQDmnEhN-nsfBeg,5141
+vertex_proxy/config.py,sha256=idTrMsd5YZDVjwbpyG7Hvb0BHSNkftsg3p0q7lIIFbY,4159
+vertex_proxy/main.py,sha256=Hr4f5FAgjDsudZLfupr-DFUbji8QSeAzbQzhL7BxUM0,24155
+vertex_proxy-0.2.0.dist-info/METADATA,sha256=OY64FURWVVMg053s-VVCa2pwBZ6sFyuCurZWw9zEUb8,16655
+vertex_proxy-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+vertex_proxy-0.2.0.dist-info/entry_points.txt,sha256=otfhuFttbqSSH01ZkC118Uz49HOPIkvKR0socZxi21c,60
+vertex_proxy-0.2.0.dist-info/licenses/LICENSE,sha256=W00aDguL-XCsFfMdUU3fwd8Tq9a061MCZC6afJmtqwc,1075
+vertex_proxy-0.2.0.dist-info/RECORD,,

vertex_proxy-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

vertex_proxy-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vertex-proxy = vertex_proxy.__main__:main

vertex_proxy-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prasad Subrahmanya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.