docsynth 0.0.0__tar.gz → 0.1.0__tar.gz

docsynth-0.1.0/.env.example

@@ -0,0 +1,92 @@
+# docsynth — environment configuration
+#
+#   cp .env.example .env    then fill in the blanks.
+#
+# .env is gitignored. Never commit real credentials.
+# Values marked [required] must be set before the relevant mode will start;
+# startup validation fails fast rather than erroring mid-run.
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# LLM providers — catalogue generation (Step 2, one-time)
+# ═══════════════════════════════════════════════════════════════════════════
+
+# DeepSeek V4-Flash — 40% of catalogue.  https://platform.deepseek.com
+DEEPSEEK_API_KEY=
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DEEPSEEK_MODEL=deepseek-v4-flash
+
+# Qwen3.5-Flash via Alibaba DashScope — 40% of catalogue.
+# Use the Singapore endpoint unless your account is China-mainland.
+DASHSCOPE_API_KEY=
+DASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
+DASHSCOPE_MODEL=qwen3.5-flash
+
+# Anthropic Claude Haiku 4.5 — 20% of catalogue.  https://console.anthropic.com
+# Leave ANTHROPIC_API_KEY blank to fall back to an `ant auth login` profile.
+ANTHROPIC_API_KEY=
+ANTHROPIC_MODEL=claude-haiku-4-5
+# Batches API halves cost; catalogue generation is offline so keep this on.
+ANTHROPIC_USE_BATCH=true
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Logo generation (Step 2b) — abstract marks only; wordmarks are programmatic
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Black Forest Labs FLUX 2 Pro.  https://api.bfl.ai
+BFL_API_KEY=
+BFL_MODEL=flux-2-pro
+LOGO_ATTEMPTS_PER_COMPANY=3
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Google Cloud
+# ═══════════════════════════════════════════════════════════════════════════
+
+GOOGLE_CLOUD_PROJECT=                      # [required] GCP project ID
+GCP_REGION=us-central1
+
+# Local dev only. On Cloud Run, leave blank and use the attached service account.
+GOOGLE_APPLICATION_CREDENTIALS=
+
+GCS_BUCKET=                                # [required] e.g. docsynth-artifacts
+FIRESTORE_DATABASE=(default)
+BQ_DATASET=docsynth_golden                   # external tables land here
+
+# Artifact Registry path for the container image
+ARTIFACT_REGISTRY=                         # e.g. us-central1-docker.pkg.dev/PROJECT/docsynth
+CLOUD_RUN_SERVICE=docsynth-generate
+CLOUD_RUN_JOB=docsynth-export
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Run behaviour
+# ═══════════════════════════════════════════════════════════════════════════
+
+CATALOG_VERSION=v1                         # pinned per run; bump = regeneration
+WORK_UNIT_SIZE=1000                        # invoices per task / per JSONL shard
+RENDER_CONCURRENCY=8                       # parallel Chromium pages per instance
+MAX_LINE_ITEMS=8000                        # hard cap — validation error, not a timeout
+LARGE_INVOICE_THRESHOLD=250                # above this, route to the slow queue
+
+# Playwright resolves its own bundled Chromium if left blank.
+CHROMIUM_PATH=
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Budget guards — generation aborts rather than silently overrunning
+# ═══════════════════════════════════════════════════════════════════════════
+
+CATALOG_BUDGET_USD=50.00
+LOGO_BUDGET_USD=25.00
+TEST_BUDGET_USD=10.00                      # separate pot for smoke runs
+ABORT_ON_BUDGET_EXCEEDED=true
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Observability
+# ═══════════════════════════════════════════════════════════════════════════
+
+LOG_LEVEL=INFO
+LOG_FORMAT=json                            # json | console

docsynth-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Code owners for docsynth.
+# https://docs.github.com/articles/about-code-owners
+#
+# @kashodev owns everything in this repo by default — every path, one owner.
+# Add more specific rules below the global one if that ever changes (later rules
+# win over earlier ones for a matching path).
+
+* @kashodev

docsynth-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,76 @@
+<!--
+Fill in every section that applies and delete the ones that do not. A section
+left as an unedited prompt is worse than a deleted one — it reads as answered
+when it isn't.
+
+Keep it honest: if something is untested, partially done, or a known trade-off,
+say so here rather than letting a reviewer discover it.
+-->
+
+## What
+
+<!-- A high-level summary of the change and its scope. What does this PR do, and
+     just as importantly, what is deliberately *not* in it? -->
+
+## Why
+
+<!-- The problem being solved and why this solution. Link the ticket/issue.
+     If this is a fix, describe the failure it addresses — ideally the symptom a
+     user or a test would see. If a previous approach was replaced, say what was
+     wrong with it. -->
+
+Closes #
+
+## How
+
+<!-- High-level implementation notes: the shape of the change, key design
+     decisions, and the trade-offs behind them.
+
+     - Alternatives considered, and why they were rejected.
+     - Anything that constrains the design (a protocol, determinism, the exactness
+       of the golden data, a licence).
+     - Follow-ups deliberately left out of scope (link the TODO entry). -->
+
+## Testing
+
+<!-- How the change was verified. Be specific enough that a reviewer could repeat it.
+
+     - New/changed automated tests and what property each pins down.
+     - Full-suite result (e.g. `NNN passed, N skipped`).
+     - Manual verification steps, with the commands used.
+     - Anything gated/skipped in CI (emulators, Chromium, cloud creds) and how to
+       run it locally.
+     - What is *not* covered, and why. -->
+
+- [ ] Full test suite passes locally
+- [ ] New behaviour has tests that fail without the change
+
+## Visuals
+
+<!-- Rendering or UI changes: before/after images. For generated documents,
+     attach or reference the sample files that demonstrate the change.
+     For complex features, a diagram of the flow or data model.
+     Delete this section if the change has no visible output. -->
+
+| Before | After |
+| --- | --- |
+|  |  |
+
+## Reviewer focus
+
+<!-- Direct attention where it is most needed.
+
+     - The files/functions with the real complexity, and what to check about them.
+     - Assumptions worth challenging.
+     - What can be skimmed (mechanical renames, generated files, moved code with
+       no behaviour change).
+     - Any part you are unsure about and want a second opinion on. -->
+
+## Risk & rollout
+
+<!-- Delete if not applicable.
+
+     - Backwards compatibility: schema/protocol/config changes, migrations.
+     - Effect on existing runs or already-generated data.
+     - New dependencies and their licences.
+     - How to roll back if this goes wrong. -->

docsynth-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: ci
+
+# Runs the test suite on every push to main and every PR, and lints the Python
+# files a PR changed. Chromium- and emulator-backed tests skip themselves when
+# those services aren't present, and the cloud extras aren't installed, so the
+# core suite runs green on a plain runner.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e '.[dev]'
+      # `python -m pytest` (not bare `pytest`) puts the repo root on sys.path, which
+      # the suite needs — some tests import helpers via `from tests.… import …`.
+      - run: python -m pytest -q
+
+  lint:
+    name: ruff
+    # Repo-wide gate: the pre-existing lint debt was cleared, so the whole tree
+    # must stay clean. Rule scoping lives in pyproject's [tool.ruff.lint].
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # Pinned so a new ruff release can't fail the repo-wide gate on rules the
+      # tree was never checked against. Bump deliberately.
+      - run: pip install ruff==0.16.0
+      - run: ruff check .

docsynth-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: docs
+
+# Build the mkdocs-material site and deploy it to GitHub Pages (the gh-pages
+# branch) whenever the docs change on main. Enable Pages once in
+# Settings → Pages → Deploy from branch: gh-pages.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "site-docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: pip install -r site-docs/requirements.txt
+      - name: Build & deploy to GitHub Pages
+        run: mkdocs gh-deploy --force --config-file site-docs/mkdocs.yml

docsynth-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: release
+
+# Publish to PyPI via Trusted Publishing (OIDC) — no stored API token.
+# Fires when a GitHub Release is published; build the sdist+wheel and upload.
+# One-time PyPI + GitHub setup is documented in
+# site-docs/docs/operations/publishing.md.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Tag must match [project].version
+        run: |
+          ver=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$ver" != "$tag" ]; then
+            echo "release tag '$tag' != pyproject version '$ver'"; exit 1
+          fi
+          echo "publishing version $ver"
+      - run: pip install build
+      - run: python -m build
+      - run: pipx run twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # The trusted publisher on PyPI is scoped to this environment.
+    environment: pypi
+    permissions:
+      id-token: write        # mint the OIDC token PyPI verifies
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

docsynth-0.1.0/.gitignore

@@ -0,0 +1,70 @@
+# ─── Secrets ────────────────────────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+*-service-account*.json
+gcp-credentials*.json
+
+# ─── Design scratch (never committed) ───────────────────────────────────────
+# Feature-exploration write-ups: thinking-in-progress, superseded as soon as the
+# decision lands in DESIGN.md / docs/. Keeping them out of git stops stale
+# analysis being mistaken for the current design.
+feature_explorations/
+
+# ─── Reference material (never committed) ───────────────────────────────────
+# Third-party images used only as visual reference while building the
+# procedural equivalents. Not ours to redistribute, and not needed to build.
+templates/stamps/
+
+# ─── Generated artefacts ────────────────────────────────────────────────────
+out/
+catalog/
+*.parquet
+*.jsonl
+*.jsonl.gz
+
+# ─── Python ─────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+
+# ─── Tooling / OS ───────────────────────────────────────────────────────────
+.DS_Store
+.idea/
+.vscode/
+
+# Belt-and-suspenders: ignore PDFs anywhere by default. The original reason was
+# the source templates, which carried real personal data and have since been
+# removed from the repo — but the blanket rule stays, so a stray real-world PDF
+# dropped anywhere in the tree can never be committed by accident.
+# Case-insensitive matching is on by default on macOS but NOT on Linux, so the
+# explicit glob protects a Linux clone too.
+*.pdf
+*.Pdf
+*.PDF
+
+# ...with one deliberate exception: samples/ holds generated showcase documents.
+# They are synthetic end to end — procedural catalogue data, no personal data —
+# and are committed so the rendering can be reviewed without running a job.
+!samples/**/*.pdf
+!samples/**/*.PDF
+
+# Real run configurations. `run.example.yaml` is the committed template; every
+# other run.yaml is one operator's actual run — project ids, bucket names, doc
+# counts and secret *names* — which is noise in review at best and a leak at
+# worst. Copy the example, never commit the copy.
+run.yaml
+run.*.yaml
+!run.example.yaml
+
+# mkdocs build output for the docs site
+site-docs/site/

docsynth-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing
+
+## Branching
+
+`main` is protected — it does not accept direct pushes. **All work goes on a
+branch and lands through a pull request**, however small.
+
+```bash
+git switch -c <type>/<short-description>    # branch from an up-to-date main
+# ...work, commit...
+git push -u origin <branch>
+```
+
+Branch names are `<type>/<short-description>`, where type is one of:
+
+| Type | For |
+|---|---|
+| `feat/` | new capability |
+| `fix/` | a defect |
+| `refactor/` | restructuring with no behaviour change |
+| `docs/` | documentation only |
+| `chore/` | tooling, packaging, housekeeping |
+| `test/` | tests only |
+
+One PR per logical change. Two unrelated changes on one branch make review
+harder and a revert riskier — branch twice instead.
+
+## Pull requests
+
+[`.github/pull_request_template.md`](.github/pull_request_template.md) is applied
+automatically. Fill in every section that applies and **delete the ones that do
+not** — a section left as an unedited prompt reads as answered when it isn't.
+
+The template asks for the *What*, *Why*, *How* (including trade-offs and
+alternatives), *Testing*, *Visuals*, *Reviewer focus*, and *Risk & rollout*. The
+two that most often get skipped and matter most:
+
+- **How** — the reasoning, not a restatement of the diff. A reviewer can read the
+  code; they cannot read why you rejected the other approach.
+- **Reviewer focus** — say what to scrutinise and what to skim. A 900-line diff
+  that is 850 lines of moved code deserves that note.
+
+Be honest in the PR body about anything untested, partially done, or knowingly
+traded off. It is much cheaper to flag it than to have a reviewer find it.
+
+## Before opening a PR
+
+```bash
+PYTHONPATH=src pytest -q          # full suite
+```
+
+- New behaviour needs a test that fails without the change.
+- Some tests are gated and skip without their dependency (Chromium, the
+  Firestore/GCS emulators, boto3/moto, a real BigQuery project). If your change
+  touches those paths, run them locally and say so in *Testing*.
+- Rendering changes: regenerate the affected files in `samples/` and reference
+  them in *Visuals*.
+
+## Things that will fail review
+
+- Committing anything with real personal data. PDFs are gitignored by default;
+  the `samples/` exception exists only because that content is wholly synthetic.
+- Committing third-party reference material (see `templates/stamps/`).
+- Changing a golden value. The record is the ground truth an extraction pipeline
+  is scored against — rendering may change freely, the computed figures may not.
+- Changing how the RNG is consumed **without saying so in the PR**. Drawing an
+  extra value, drawing in a different order, or drawing a different number of
+  values shifts every subsequent draw, so every document changes for a given
+  `(run_id, index)`. That is sometimes the right thing to do — making line items
+  distinct was — but it means a run cannot be resumed across the change, and an
+  old run id no longer reproduces its old corpus. Call it out explicitly under
+  *Risk & rollout* so a reviewer can weigh it — reproducibility is per code
+  version, not absolute (see the docs site → Architecture → Concurrency &
+  coordination).

docsynth-0.1.0/Dockerfile

@@ -0,0 +1,67 @@
+# docsynth container.
+#
+# NOT required to try docsynth. The local-first path — filesystem storage,
+# SQLite state, Parquet + DuckDB golden — runs from a plain `pip install docsynth`
+# with no container and no cloud account.
+#
+# This image exists for the two things that genuinely benefit from one:
+#
+#   1. Reproducible rendering. PDF generation drives headless Chromium via
+#      Playwright, whose output is sensitive to browser and font versions.
+#      Pinning them in an image makes 250k documents byte-reproducible across
+#      machines. The Playwright base image ships a matched Chromium.
+#
+#   2. The Cloud Run deploy artifact (GCP path). The same image runs as the
+#      generation Service and the export Job — one build, two entry commands.
+#
+# Build:  docker build -t docsynth .
+# Local:  docker run --rm -v "$PWD/out:/data" docsynth generate --config ...
+# Cloud:  pushed to Artifact Registry, deployed to Cloud Run (see deploy.sh).
+
+# The base image bundles a Chromium build matched to ONE Playwright version, and
+# the pip package MUST be that exact version or launch fails with
+# "Executable doesn't exist". They are declared together here, from a single arg,
+# so they can never drift — an unpinned `playwright>=…` floating to a newer
+# release than the base image is what silently broke every rendered document.
+# Bump both by bumping this one number (and picking the matching `vX.Y.Z-noble`).
+ARG PLAYWRIGHT_VERSION=1.61.0
+FROM mcr.microsoft.com/playwright/python:v1.61.0-noble
+ARG PLAYWRIGHT_VERSION
+
+# Stream stdout/stderr immediately, so a long job's progress reaches Cloud
+# Logging as it happens rather than only when the process exits.
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Install dependencies first so the layer caches across code changes.
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+# Pin Playwright to the base image's version *before* installing the package, so
+# `.[gcp,anthropic]` (whose `playwright>=…` is already satisfied) cannot pull a
+# newer, browser-mismatched release. `[gcp]` adds the GCS / Firestore / BigQuery
+# SDKs for the cloud path; drop it for a purely local image, add `[aws]` for S3.
+RUN pip install --no-cache-dir "playwright==${PLAYWRIGHT_VERSION}" \
+ && pip install --no-cache-dir ".[gcp,anthropic]" \
+ && test "$(python -c 'import importlib.metadata as m; print(m.version("playwright"))')" = "${PLAYWRIGHT_VERSION}"
+
+# Ship the invoice pack's templates (they live inside the package).
+COPY templates/manifest.yaml ./templates/manifest.yaml
+
+# Smoke-test the wiring that actually breaks in production. `import` alone passed
+# happily while rendering was completely broken — the pack registered, but every
+# document failed to launch a browser. So this renders ONE real PDF end to end
+# (record → HTML → Chromium → PDF bytes) and fails the build if it cannot. It is
+# the one assertion standing between a broken image and a green run over zero
+# documents.
+#
+# Written as `python -c` one-liners rather than a heredoc on purpose: Cloud
+# Build's daemon has no BuildKit heredoc support, and a `RUN … <<'PY'` block gets
+# parsed as Dockerfile instructions (a Python `from x import y` reads as a second
+# `FROM`).
+RUN python -c "import docsynth.packs; print('packs:', docsynth.available_packs())"
+RUN python -c "import docsynth.packs; from docsynth.core import get_pack; from docsynth.core.pipeline.pdf import PdfRenderer; pack=get_pack('invoice'); rec=pack.default_source().generate('docker-build-check', 0); pdf=PdfRenderer(pack).render(rec).data; assert pdf[:5]==b'%PDF-', 'renderer did not return a PDF'; assert len(pdf) > 1000, f'suspiciously small PDF ({len(pdf)} bytes)'; print(f'render check: {len(pdf)} byte PDF OK')"
+
+ENTRYPOINT ["docsynth"]
+CMD ["--help"]

docsynth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Okasha
+
+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.