codex-pdf 1.2.0__tar.gz → 1.3.1__tar.gz

{codex_pdf-1.2.0 → codex_pdf-1.3.1}/Dockerfile

@@ -43,7 +43,11 @@ COPY tests ./tests
 # container start tries to repair the editable install and fails on
 # `/opt/venv/.../bin/codex-pdf: Permission denied` because the bin
 # entries land outside the dir tree the runtime user can write.
-RUN uv sync --frozen --no-dev \
+# Install the `redis` extra unconditionally so a deploy that wires
+# CODEX_REDIS_URL to a Railway Redis service uses the shared cache,
+# AND a deploy that deletes the redis service still boots cleanly
+# (codex falls back to in-memory; see codex_pdf.api.cache.make_cache).
+RUN uv sync --frozen --no-dev --extra redis \
  && chown -R codex:codex /opt/venv /app
 
 USER codex

{codex_pdf-1.2.0 → codex_pdf-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-pdf
-Version: 1.2.0
+Version: 1.3.1
 Summary: Authoritative, versioned PDF facts contract for Think Neverland tools.
 Author-email: Think Neverland <dev@thinkneverland.com>
 License-Expression: AGPL-3.0-or-later
@@ -13,6 +13,8 @@ Requires-Dist: pydantic>=2.8
 Requires-Dist: pymupdf>=1.24
 Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: uvicorn>=0.30
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
 Description-Content-Type: text/markdown
 
 ---

{codex_pdf-1.2.0 → codex_pdf-1.3.1}/clients/ts/node_modules/.vite/vitest/results.json

@@ -1 +1 @@
-{"version":"1.6.1","results":[[":src/index.test.ts",{"duration":1036,"failed":false}]]}
+{"version":"1.6.1","results":[[":src/index.test.ts",{"duration":1015,"failed":false}]]}

{codex_pdf-1.2.0 → codex_pdf-1.3.1}/clients/ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printwithsynergy/codex-client",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "TypeScript client for the codex-pdf HTTP API. Mirrors the Python codex_pdf.client surface.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

{codex_pdf-1.2.0 → codex_pdf-1.3.1}/clients/ts/src/index.ts

@@ -167,15 +167,21 @@ export class HttpClient {
     path: string,
     body: BodyInit,
     accept = "application/json",
+    contentType?: string,
   ): Promise<Response> {
     let lastErr: unknown;
     for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), this.timeoutMs);
       try {
+        const headers: Record<string, string> = this.headers({ Accept: accept });
+        if (contentType) headers["Content-Type"] = contentType;
+        // For FormData, let fetch set Content-Type itself so the
+        // multipart boundary is correct; we only override for JSON
+        // and other explicit body types.
         const res = await this.fetchImpl(this.baseUrl + path, {
           method: "POST",
-          headers: this.headers({ Accept: accept }),
+          headers,
           body,
           signal: controller.signal,
         });
@@ -433,4 +439,21 @@ export class HttpClient {
     const res = await this.post("/v1/walk/content-stream", fd);
     return (await res.json()) as { page_num: number; signals: Record<string, unknown> };
   }
+
+  /**
+   * Evaluate a PDF Type-4 PostScript function via codex.
+   *
+   * Returns `{result, fast_path}`. `result` is `null` when codex
+   * could not verify (Ghostscript missing, timeout, parse error).
+   * `fast_path: true` indicates the program was constant and was
+   * resolved without a subprocess (sub-millisecond).
+   */
+  async evalType4(
+    program: string,
+    inputs: number[] = [],
+  ): Promise<{ result: number[] | null; fast_path: boolean }> {
+    const body = JSON.stringify({ program, inputs });
+    const res = await this.post("/v1/walk/type4", body, "application/json", "application/json");
+    return (await res.json()) as { result: number[] | null; fast_path: boolean };
+  }
 }

{codex_pdf-1.2.0 → codex_pdf-1.3.1}/docs/deploy.md

@@ -89,6 +89,40 @@ The shared codex consumed by `lint-pdf` admin / `lint-pdf-ui`
 packages/app / `codex-pdf-marketing` should run with bearer auth and
 its `CODEX_BEARER_TOKEN` rotated through the operator's secret store.
 
+## Switching between shared and per-consumer (Option B)
+
+The same image, lockfile, and `Procfile` run in either mode —
+switching is a service-vars + DNS change, not a code change.
+
+### Shared → per-consumer (lint marketing example)
+
+1. New Railway service in the lintpdf.com project pointing at the
+   `codex-pdf` repo.
+2. Set "Root Directory" to `codex-pdf` so the canonical Dockerfile
+   is the build context (or, if you keep the sidecar config in the
+   marketing repo, override it via Railway's "Build Context" field
+   — see `lint-pdf-ui/packages/web/codex-sidecar/railway.toml`).
+3. Provision env vars (`CODEX_BEARER_TOKEN`, `CODEX_INTERNAL_TOKEN`,
+   etc.) — `openssl rand -hex 24` for both.
+4. Update the marketing service:
+   ```
+   CODEX_API_BASE_URL=<new sidecar URL>
+   CODEX_API_TOKEN=<sidecar bearer>
+   ```
+5. Trigger a marketing redeploy so it picks up the new base URL.
+
+### Per-consumer → shared
+
+1. Reset the marketing service vars to the shared codex:
+   ```
+   CODEX_API_BASE_URL=https://codex-pdf-production.up.railway.app
+   CODEX_API_TOKEN=<shared production bearer>
+   ```
+2. Pause / archive the sidecar service in the Railway dashboard.
+
+Both modes preserve `/healthz` (un-auth) and `/extract` aliases so
+ops probes / curl flows from either side keep working unchanged.
+
 ## Local development without HTTP
 
 Set `CODEX_API_BASE` empty (the default) and the

codex_pdf-1.3.1/docs/operations/codex-change-ripple.md

@@ -0,0 +1,96 @@
+---
+title: "Codex change ripple rule"
+description: "Every change to codex-pdf must cascade a redeploy of every consumer service in a fixed order."
+group: "Operations"
+order: 5
+slug: "codex-change-ripple"
+---
+
+# Codex change ripple rule
+
+Any change to `codex-pdf` — code, env contract, schema, Docker image,
+or Railway env var — **MUST** trigger a redeploy of every consumer
+service. Skipping the cascade silently pins consumers to a stale
+codex contract and is the single most common source of "demo broke
+overnight" pages.
+
+## Order
+
+Redeploy in this order so the cache and contract warm sanely:
+
+1. **codex-pdf** — both the shared `codex-pdf-production` service and
+   every per-consumer sidecar (`loupe-pdf-marketing/codex-sidecar`,
+   `lint-pdf-marketing/codex-sidecar`, `codex-pdf-marketing/codex-sidecar`,
+   `lint-pdf-ui/packages/web/codex-sidecar`).
+2. **lint-pdf engine + admin** (lint-pdf repo + lint-pdf-ui admin) so
+   the rule engine and admin app pick up new client behaviour /
+   contract fields before the marketing demos route through them.
+3. **All marketing sites**, in any order:
+   - `lint-pdf-marketing` (lintpdf.com)
+   - `loupe-pdf-marketing` (loupepdf.com)
+   - `codex-pdf-marketing` (codexpdf.com)
+4. **lint-pdf-ui admin** if it wasn't already redeployed in step 2.
+
+## Trigger
+
+There are three equivalent ways to redeploy:
+
+| How | When |
+|---|---|
+| `git push origin main` to the consumer repo | When the consumer commit references the new codex version. Railway picks up new commits automatically. |
+| Railway dashboard "Redeploy" button | When the consumer repo has no new commits but you need to force a build against the latest base image. |
+| GraphQL `serviceInstanceRedeploy` | Scriptable; matches the dashboard "Redeploy" button. Used by the deploy-verify-fix loop in the audit harness. |
+
+## Verification
+
+After each consumer redeploys, run the per-repo smoke script:
+
+- `loupe-pdf-marketing/scripts/smoke-codex-extract.mjs`
+- `lint-pdf-marketing/scripts/smoke-codex-extract.mjs`
+- `codex-pdf-marketing/scripts/smoke-codex-extract.mjs`
+
+Each script accepts a `CODEX_DEMO_BASE` env var and asserts
+`codex_version` matches the deployed codex package version.
+
+For codex itself:
+
+```bash
+curl -fsS https://codex-pdf-production.up.railway.app/healthz | jq
+# {"status":"ok","version":"1.3.1","ghostscript":true,"cache_backend":"redis"}
+
+curl -fsS https://codex-pdf-production.up.railway.app/v1/contract | jq .package_version
+# "1.3.1"
+```
+
+## Why a fixed order matters
+
+- Marketing sites cache the codex base URL at build time when the
+  consumer is server-rendered (Astro). Redeploying marketing first
+  bakes in the OLD codex URL, then a fresh codex deploy strands
+  marketing on a stale endpoint until the next push.
+- lint-pdf and lint-pdf-ui consume codex via subprocess + HTTP. They
+  must pick up new client behaviour before the marketing layer
+  proxies through them, otherwise "demo extract" succeeds but the
+  admin app's codex-cluster CLI shows a different schema.
+- Per-deploy sidecars share a Redis cache when configured. Redeploying
+  the sidecar with a fresh Docker image ahead of marketing prevents
+  cache key drift between an old codex version (pre-redeploy) and a
+  new one (post-redeploy) that would otherwise read each other's
+  serialized JSON shapes.
+
+## Sidecar mode (Option B)
+
+Each marketing repo ships a sibling `codex-sidecar/` config that
+runs the canonical `codex-pdf` Dockerfile alongside the marketing
+service. Sidecar redeploys are part of step 1 of the order above.
+The shared `codex-pdf-production` service serves admin, lint engine,
+and any consumer that hasn't opted into a sidecar.
+
+To switch a marketing service between shared and per-consumer codex,
+change one env var on the marketing service:
+
+- Shared: `CODEX_API_BASE_URL=https://codex-pdf-production.up.railway.app`
+- Sidecar: `CODEX_API_BASE_URL=https://${{codex-sidecar.RAILWAY_PRIVATE_DOMAIN}}`
+  (Railway service-reference; resolves at deploy time)
+
+See `codex-pdf/docs/deploy.md` for the full switch-back recipe.

codex_pdf-1.3.1/docs/operations/marketing-deploy-template.md

@@ -0,0 +1,78 @@
+---
+title: "Marketing deploy template"
+description: "Reusable Railway service layout for any consumer that needs a codex sidecar + optional redis cache + optional clamav."
+group: "Operations"
+order: 6
+slug: "marketing-deploy-template"
+---
+
+# Marketing deploy template
+
+Each `*-pdf-marketing` repo declares the same Railway service layout
+so a fresh `railway up` in any of them spins up the full stack with
+zero manual configuration.
+
+## Services
+
+| Name | Required | Purpose |
+|---|---|---|
+| `web` (the marketing app) | yes | Astro / Next.js public site + `/api/demo*` proxies |
+| `codex` | yes | Per-consumer codex-pdf sidecar (Option B) |
+| `redis` | **no** (recommended for prod) | Shared render cache for codex; delete this service for a smaller footprint and codex falls back to the in-memory cache |
+| `clamav` | **no** (only where the demo virus-scans) | clamd over TCP for the upload sanitizer |
+
+## Auto-wired env (Railway service references)
+
+Web service:
+
+```
+CODEX_API_BASE_URL=https://${{codex.RAILWAY_PRIVATE_DOMAIN}}
+NEXT_PUBLIC_CODEX_API_BASE_URL=https://${{codex.RAILWAY_PUBLIC_DOMAIN}}
+CLAMAV_HOST=${{clamav.RAILWAY_PRIVATE_DOMAIN}}     # only where used
+CLAMAV_PORT=3310
+```
+
+Codex service:
+
+```
+CODEX_REDIS_URL=${{redis.REDIS_URL}}
+CODEX_AUTH_MODE=internal,bearer
+CODEX_LOCAL_FALLBACK=1
+ALLOW_EXTERNAL_FETCH=true
+FETCH_TIMEOUT_MS=15000
+FETCH_MAX_BYTES=52428800
+```
+
+Service references resolve at deploy time. If the operator deletes
+`redis`, `${{redis.REDIS_URL}}` resolves to an empty string and
+codex falls back to the in-memory cache automatically (logged
+warning, no crash). Same for `clamav`: deleting the service makes
+`${{clamav.RAILWAY_PRIVATE_DOMAIN}}` empty, the marketing demo's
+`clamAvEnabled()` returns false, and the upload pipeline skips the
+virus-scan step with a `"skipped"` status surfaced to the user.
+
+## Manual secrets (Quincy-set, never auto-wired)
+
+| Var | Service | Purpose |
+|---|---|---|
+| `CODEX_BEARER_TOKEN` | codex + web | Server-to-server bearer auth |
+| `CODEX_API_TOKEN` | web | Same value as `CODEX_BEARER_TOKEN`; the marketing site forwards it |
+| `CODEX_BASIC_AUTH_USERNAME` / `CODEX_BASIC_AUTH_PASSWORD` | codex | Optional Basic Auth for human curl probes |
+| `CODEX_INTERNAL_TOKEN` | codex | Optional internal-token mode for sidecar-only routes |
+
+Generate them with `openssl rand -hex 24` and paste into the Railway
+service-vars dashboard. No bearer / Basic-Auth value should ever live
+in the marketing browser bundle.
+
+## Healthchecks
+
+| Service | URL |
+|---|---|
+| Web | `/` |
+| Codex | `/healthz` (returns `{status, version, ghostscript, cache_backend}`) |
+| Redis | n/a — Railway monitors the redis container directly |
+| ClamAV | n/a — clamd is TCP-only |
+
+The web service's `healthcheckPath` and `restartPolicy` are baked
+into its `railway.toml`; codex inherits the canonical Dockerfile's
+healthcheck.

{codex_pdf-1.2.0 → codex_pdf-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-pdf"
-version = "1.2.0"
+version = "1.3.1"
 description = "Authoritative, versioned PDF facts contract for Think Neverland tools."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -20,6 +20,11 @@ dependencies = [
   "python-multipart>=0.0.9",
 ]
 
+[project.optional-dependencies]
+redis = [
+    "redis>=5.0",
+]
+
 [project.scripts]
 codex-pdf = "codex_pdf.cli:main"
 

codex_pdf-1.3.1/src/codex_pdf/api/cache.py

@@ -0,0 +1,160 @@
+"""Codex API cache backends.
+
+Content-addressed by ``sha256(pdf) + sha256(args_json)``. Pluggable:
+
+- ``memory`` (default) — in-process LRU. Always works, no deps.
+- ``redis`` — set ``CODEX_REDIS_URL=redis://...``. **Optional**: any
+  failure to import ``redis``, parse the URL, connect, or PING is
+  logged and the service falls back to the in-memory cache. Redis
+  must never crash the codex API at boot or at request time.
+- ``s3`` — placeholder; not wired here. Front the API with a CDN /
+  object-store cache instead.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+from collections import OrderedDict
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def cache_key(pdf_bytes: bytes, args: dict[str, Any], *, kind: str) -> str:
+    """Content-addressed cache key for one render result.
+
+    ``kind`` segregates by endpoint family ("page", "separations",
+    "heatmap", "layer", "sample-color", "sample-density",
+    "walk-content-stream") so identical args from different endpoints
+    don't collide.
+    """
+    pdf_sha = hashlib.sha256(pdf_bytes).hexdigest()
+    args_blob = json.dumps(args, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    args_sha = hashlib.sha256(args_blob).hexdigest()
+    return f"codex:{kind}:{pdf_sha}:{args_sha}"
+
+
+class MemoryCache:
+    """Simple LRU. ``maxsize`` defaults to 256 entries."""
+
+    name = "memory"
+
+    def __init__(self, maxsize: int = 256) -> None:
+        self._maxsize = maxsize
+        self._store: OrderedDict[str, bytes] = OrderedDict()
+
+    def get(self, key: str) -> bytes | None:
+        if key in self._store:
+            self._store.move_to_end(key)
+            return self._store[key]
+        return None
+
+    def set(self, key: str, value: bytes) -> None:
+        if key in self._store:
+            self._store.move_to_end(key)
+        self._store[key] = value
+        while len(self._store) > self._maxsize:
+            self._store.popitem(last=False)
+
+
+class RedisCache:
+    """Thin wrapper over redis-py. Imported lazily.
+
+    Constructor performs a single ``PING`` at init time so a bogus URL
+    or unreachable Redis service surfaces as a startup-time
+    ``RuntimeError`` (caught by :func:`make_cache` and downgraded to
+    a logged warning). Once initialised, transient ``get``/``set``
+    failures are logged and treated as cache misses — they never
+    propagate to the API request handler.
+    """
+
+    name = "redis"
+
+    def __init__(self, url: str, ttl_seconds: int = 86400) -> None:
+        try:
+            import redis  # type: ignore
+        except ImportError as exc:
+            raise RuntimeError(
+                "CODEX_REDIS_URL set but the 'redis' Python package is not installed. "
+                "Install codex-pdf with the 'redis' extra, or unset CODEX_REDIS_URL "
+                "to use the in-memory cache."
+            ) from exc
+
+        try:
+            self._client = redis.Redis.from_url(url, socket_connect_timeout=2.0, socket_timeout=2.0)
+        except Exception as exc:
+            raise RuntimeError(f"failed to parse CODEX_REDIS_URL: {exc}") from exc
+
+        try:
+            pong = self._client.ping()
+        except Exception as exc:
+            raise RuntimeError(f"Redis PING failed for {url!r}: {exc}") from exc
+        if not pong:
+            raise RuntimeError(f"Redis at {url!r} did not return PONG")
+
+        self._ttl = ttl_seconds
+
+    def get(self, key: str) -> bytes | None:
+        try:
+            return self._client.get(key)
+        except Exception:
+            logger.warning("RedisCache.get failed for %s; treating as miss", key, exc_info=True)
+            return None
+
+    def set(self, key: str, value: bytes) -> None:
+        try:
+            self._client.set(key, value, ex=self._ttl)
+        except Exception:
+            logger.warning("RedisCache.set failed for %s; cache write skipped", key, exc_info=True)
+
+
+def make_cache():
+    """Pick the cache backend based on environment.
+
+    Order of preference:
+
+    1. ``CODEX_REDIS_URL`` set + non-empty + reachable → ``RedisCache``
+    2. Anything else (URL missing, empty, unreachable, malformed) →
+       ``MemoryCache`` with a logged warning so operators can spot the
+       fallback in deploy logs.
+
+    This function MUST NOT raise. The codex API treats the cache as a
+    soft dependency: even if every backend is misconfigured the
+    service must still come up and serve requests (cache misses on
+    every call, but functional).
+    """
+    redis_url = (os.environ.get("CODEX_REDIS_URL") or "").strip()
+    if not redis_url:
+        logger.info("codex cache: in-memory (CODEX_REDIS_URL unset)")
+        return MemoryCache()
+    try:
+        cache = RedisCache(redis_url)
+        logger.info("codex cache: redis (%s)", _mask_url(redis_url))
+        return cache
+    except Exception as exc:
+        logger.warning(
+            "codex cache: Redis init failed (%s); falling back to in-memory cache. "
+            "This is safe but cold-cache CPU is higher. Fix CODEX_REDIS_URL or "
+            "delete the redis service to silence this warning.",
+            exc,
+        )
+        return MemoryCache()
+
+
+def _mask_url(url: str) -> str:
+    """Strip credentials from a Redis URL before logging it."""
+    try:
+        from urllib.parse import urlparse, urlunparse
+
+        parsed = urlparse(url)
+        if parsed.password or parsed.username:
+            netloc = parsed.hostname or ""
+            if parsed.port:
+                netloc = f"{netloc}:{parsed.port}"
+            return urlunparse(parsed._replace(netloc=netloc))
+        return url
+    except Exception:
+        return "<redacted>"

{codex_pdf-1.2.0 → codex_pdf-1.3.1}/src/codex_pdf/api/main.py

@@ -167,10 +167,28 @@ class WalkContentStreamRequest(BaseModel):
     page: int = Field(default=1, ge=1)
 
 
+class Type4Request(BaseModel):
+    """JSON body for ``POST /v1/walk/type4``.
+
+    Mirrors the in-process API of :func:`codex_pdf.eval.ps_type4.evaluate`.
+    """
+
+    program: str = Field(..., min_length=1, max_length=16384)
+    inputs: list[float] = Field(default_factory=list, max_length=64)
+
+
+class Type4Response(BaseModel):
+    """Response shape — ``result`` is None when codex couldn't verify."""
+
+    result: list[float] | None
+    fast_path: bool
+
+
 class HealthResponse(BaseModel):
     status: str
     version: str
     ghostscript: bool
+    cache_backend: str
 
 
 class VersionResponse(BaseModel):
@@ -237,7 +255,12 @@ async def healthz_root() -> HealthResponse:
 async def healthz() -> HealthResponse:
     from codex_pdf.render._common import has_ghostscript
 
-    return HealthResponse(status="ok", version=VERSION, ghostscript=has_ghostscript())
+    return HealthResponse(
+        status="ok",
+        version=VERSION,
+        ghostscript=has_ghostscript(),
+        cache_backend=getattr(_cache, "name", type(_cache).__name__.lower()),
+    )
 
 
 @app.get("/v1/version", response_model=VersionResponse)
@@ -261,6 +284,7 @@ async def contract() -> ContractResponse:
             "POST /v1/sample/color",
             "POST /v1/sample/density",
             "POST /v1/walk/content-stream",
+            "POST /v1/walk/type4",
             "GET /v1/healthz",
             "GET /v1/version",
             "GET /v1/contract",
@@ -728,6 +752,32 @@ async def sample_density_endpoint(
         ) from exc
 
 
+@app.post("/v1/walk/type4", dependencies=[Depends(authenticate)])
+async def walk_type4_endpoint(body: Type4Request) -> Type4Response:
+    """Evaluate a PDF Type-4 PostScript function via codex.
+
+    Codex owns the PostScript byte-level evaluation surface; this
+    endpoint exists so lint-pdf (and any other consumer) can avoid
+    shelling out to ``gs -dNODISPLAY`` directly. Fast-path constants
+    are returned synchronously without a subprocess.
+    """
+    started = time.perf_counter()
+    try:
+        from codex_pdf.eval.ps_type4 import _fast_path_constants, evaluate
+
+        fast = _fast_path_constants(body.program)
+        result = evaluate(body.program, inputs=list(body.inputs))
+        _record("walk_type4", 200, time.perf_counter() - started)
+        return Type4Response(result=result, fast_path=fast is not None)
+    except Exception as exc:
+        logger.exception("walk_type4 failed")
+        _record("walk_type4", 500, time.perf_counter() - started)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"walk_type4 failed: {exc}",
+        ) from exc
+
+
 @app.post("/v1/walk/content-stream", dependencies=[Depends(authenticate)])
 async def walk_content_stream_endpoint(
     pdf: UploadFile = File(...),