flowapy 0.2.2__tar.gz → 0.4.0__tar.gz

{flowapy-0.2.2 → flowapy-0.4.0}/.github/workflows/lint.yaml

@@ -24,26 +24,19 @@ jobs:
 
       - run: uv sync --all-extras --group dev --frozen
 
+      # demo-gateway is a separate uv project; sync its venv so the
+      # `pytest-demo-gateway` pre-commit hook (which runs --no-sync) works.
+      - run: uv sync --frozen --group dev
+        working-directory: examples/demo-gateway
+
       - run: pnpm install --frozen-lockfile
 
-      # All lint checks (ruff, mypy, prettier, …) live in
-      # .pre-commit-config.yaml so local pre-commit and CI stay in lockstep.
+      # Every check — ruff, mypy, prettier, tsc, vitest, pytest — lives in
+      # .pre-commit-config.yaml, so this single `pre-commit run --all-files`
+      # is the whole gate and local pre-commit and CI stay in lockstep.
       - uses: actions/cache@v5
         with:
           path: ~/.cache/pre-commit
           key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
 
       - run: uv run pre-commit run --all-files --show-diff-on-failure
-
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: astral-sh/setup-uv@v7
-        with:
-          python-version: "3.13"
-
-      - run: uv sync --all-extras --group dev --frozen
-
-      - run: uv run pytest tests/

{flowapy-0.2.2 → flowapy-0.4.0}/.github/workflows/release-chat-service.yaml

@@ -42,13 +42,14 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: "22"
+          node-version-file: .nvmrc
           registry-url: "https://registry.npmjs.org"
           cache: "pnpm"
 
-      # Trusted publishing requires npm >= 11.5.1; Node 22.x ships npm 10.9.x.
-      # Install to a fresh prefix to sidestep `npm install -g npm@X` clobbering
-      # its own node_modules mid-upgrade.
+      # Trusted publishing requires npm >= 11.5.1, newer than the npm bundled
+      # with Node, so pin a known-good version. Install to a fresh prefix to
+      # sidestep `npm install -g npm@X` clobbering its own node_modules
+      # mid-upgrade.
       - name: Pin npm
         run: |
           mkdir -p "$RUNNER_TEMP/npm-pin"

{flowapy-0.2.2 → flowapy-0.4.0}/.github/workflows/release-react-viewer.yaml

@@ -39,13 +39,14 @@ jobs:
 
       - uses: actions/setup-node@v5
         with:
-          node-version: "22"
+          node-version-file: .nvmrc
           registry-url: "https://registry.npmjs.org"
           cache: "pnpm"
 
-      # Trusted publishing requires npm >= 11.5.1; Node 22.x ships npm 10.9.x.
-      # Install to a fresh prefix to sidestep `npm install -g npm@X` clobbering
-      # its own node_modules mid-upgrade.
+      # Trusted publishing requires npm >= 11.5.1, newer than the npm bundled
+      # with Node, so pin a known-good version. Install to a fresh prefix to
+      # sidestep `npm install -g npm@X` clobbering its own node_modules
+      # mid-upgrade.
       - name: Pin npm
         run: |
           mkdir -p "$RUNNER_TEMP/npm-pin"

{flowapy-0.2.2 → flowapy-0.4.0}/.gitignore

@@ -31,6 +31,9 @@ eggs/
 # unrelated `lib/` directories nested under packages or examples.
 /lib/
 /lib64/
+# Local dev/spike scripts live in the root /scripts/ dir. Anchored to the
+# repo root so it doesn't shadow the tracked examples/demo/scripts/ entry.
+/scripts/
 parts/
 sdist/
 var/
@@ -159,3 +162,8 @@ node_modules/
 demo-data/
 *.tsbuildinfo
 pnpm-debug.log*
+
+# Raw LLM-call traces emitted by the demo pipeline (convert/extract/aggregate).
+# Debug artifacts only — never consumed by the running demo; just the parsed
+# .json outputs are tracked. Keep them out of git and out of `git status`.
+examples/demo/fixtures/**/*_raw.json

flowapy-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,147 @@
+# Single source of truth for pre-commit + CI lint. .github/workflows/lint.yaml
+# invokes `uv run pre-commit run --all-files`, so adding a check here
+# automatically runs it locally and in CI.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+        exclude: '\.*conda/.*'
+      - id: end-of-file-fixer
+        # Demo fixtures are generated artifacts (markdown.md, extractions,
+        # aggregation.json) — normalising them is noise, not authored style.
+        exclude: ^examples/demo/fixtures/
+      - id: trailing-whitespace
+        # …and stripping trailing whitespace inside a generated markdown.md
+        # would shift the code-point offsets its markdown_anchor citations
+        # index into, misaligning highlights. Fixtures stay out (cf. the
+        # markdownlint exclude below).
+        exclude: '\.txt$|\.tsv$|^examples/demo/fixtures/'
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: debug-statements
+      - id: check-added-large-files
+        # Demo fixture PDFs (real published CC-BY papers) run up to ~5MB
+        # for figure-heavy articles (Sci Rep, Front Cardiovasc Med); set a
+        # 6MB ceiling that fits the current corpus with some headroom.
+        args: ["--maxkb=6144"]
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.38.0
+    hooks:
+      - id: markdownlint
+        # Demo fixture markdown is extracted by the pipeline from real PDFs;
+        # it isn't authored content the project owns the style of.
+        exclude: ^examples/demo/fixtures/
+
+  - repo: https://github.com/populationgenomics/pre-commits
+    rev: "v0.1.3"
+    hooks:
+      - id: cpg-id-checker
+
+  # Use the project's pinned tools via uv / pnpm so pre-commit and CI checks
+  # match what runs locally — no separate version pinning here.
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --no-sync ruff format --check src/ tests/
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --no-sync ruff check src/ tests/
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: mypy
+        name: mypy
+        entry: uv run --no-sync mypy src/ tests/
+        language: system
+        pass_filenames: false
+        always_run: true
+      # markdownlint owns markdown above, so prettier stays out of .md.
+      - id: prettier
+        name: prettier --check
+        entry: pnpm exec prettier --check
+        language: system
+        files: \.(ts|tsx|js|jsx|mjs|cjs|json|yaml|yml)$
+        # pnpm-lock + generated demo fixtures (JSON whose format the pipeline
+        # owns via json.dump, not prettier).
+        exclude: '^pnpm-lock\.yaml$|^examples/demo/fixtures/'
+
+      # Type + test gates. tsc and vitest run nowhere on push/PR otherwise
+      # (the TS packages are only typechecked/tested in their release
+      # workflows), which let the demo's CategorySuggestion consumer rot
+      # silently through the schema rename. These are whole-project checks,
+      # so `pass_filenames: false`; the `files:` regex only decides *whether*
+      # to fire (any staged TS change → run the full workspace gate), so a
+      # docs-only commit skips them. `--all-files` in CI fires every hook.
+      #
+      # ts-build MUST come first: @flowajs/chat-service + @flowajs/react-viewer
+      # are consumed via their exports maps (→ dist/), which is gitignored and
+      # not built on `pnpm install` (ignore-scripts, no prepare script). Without
+      # this, the workspace typecheck/test can't resolve `@flowajs/*` from
+      # examples/demo + prompts/ on a fresh checkout (e.g. CI). pre-commit runs
+      # hooks in listed order, so this builds dist/ before tsc/vitest see it.
+      - id: ts-build
+        name: build workspace packages
+        entry: pnpm --filter @flowajs/chat-service --filter @flowajs/react-viewer build
+        language: system
+        pass_filenames: false
+        files: \.(ts|tsx)$
+      - id: ts-typecheck
+        name: tsc --noEmit (workspace)
+        entry: pnpm -r typecheck
+        language: system
+        pass_filenames: false
+        files: \.(ts|tsx)$
+      - id: ts-test
+        name: vitest (workspace)
+        entry: pnpm -r test
+        language: system
+        pass_filenames: false
+        files: \.(ts|tsx)$
+      - id: pytest
+        name: pytest (flowa)
+        entry: uv run --no-sync pytest tests/
+        language: system
+        pass_filenames: false
+        files: ^(src/flowa/|tests/).*\.py$
+      # demo-gateway is its own uv project (separate venv + ruff/mypy config),
+      # so these cd in and run that project's pinned tools, mirroring the pytest
+      # hook below.
+      #
+      # demo-gateway installs flowapy as an editable path dep (`path = "../.."`),
+      # so a change to `src/flowa/` can break its mypy/pytest gates even when no
+      # demo-gateway file is touched. The type+behaviour gates therefore also
+      # fire on `src/flowa/**.py`; the formatters don't, since ruff only inspects
+      # demo-gateway's own files. (Without this, a flowapy-only commit skips these
+      # locally — pre-commit runs hooks against staged files — and the break only
+      # surfaces in CI's `--all-files` run.)
+      - id: ruff-format-demo-gateway
+        name: ruff format (demo-gateway)
+        entry: bash -c 'cd examples/demo-gateway && uv run --no-sync ruff format --check src/ tests/'
+        language: system
+        pass_filenames: false
+        files: ^examples/demo-gateway/.*\.py$
+      - id: ruff-check-demo-gateway
+        name: ruff check (demo-gateway)
+        entry: bash -c 'cd examples/demo-gateway && uv run --no-sync ruff check src/ tests/'
+        language: system
+        pass_filenames: false
+        files: ^examples/demo-gateway/.*\.py$
+      - id: mypy-demo-gateway
+        name: mypy (demo-gateway)
+        entry: bash -c 'cd examples/demo-gateway && uv run --no-sync mypy src/ tests/'
+        language: system
+        pass_filenames: false
+        files: ^(examples/demo-gateway/.*|src/flowa/.*)\.py$
+      - id: pytest-demo-gateway
+        name: pytest (demo-gateway)
+        entry: bash -c 'cd examples/demo-gateway && uv run --no-sync pytest tests/'
+        language: system
+        pass_filenames: false
+        files: ^(examples/demo-gateway/.*|src/flowa/.*)\.py$

{flowapy-0.2.2 → flowapy-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowapy
-Version: 0.2.2
+Version: 0.4.0
 Summary: Variant literature assessment pipeline with AI extraction
 Project-URL: Homepage, https://github.com/populationgenomics/flowa
 Project-URL: Source, https://github.com/populationgenomics/flowa
@@ -34,7 +34,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Requires-Python: ==3.13.*
-Requires-Dist: anchorite>=0.4.1
+Requires-Dist: anchorite>=0.5.1
 Requires-Dist: boto3
 Requires-Dist: defusedxml
 Requires-Dist: fsspec
@@ -42,9 +42,11 @@ Requires-Dist: gcsfs
 Requires-Dist: httpx
 Requires-Dist: jinja2
 Requires-Dist: logfire
+Requires-Dist: markitdown[docx,xls,xlsx]>=0.1.5
 Requires-Dist: pydantic-settings
 Requires-Dist: pypdf
 Requires-Dist: s3fs
+Requires-Dist: socksio>=1.0.0
 Requires-Dist: tenacity
 Requires-Dist: typer
 Requires-Dist: zstandard
@@ -66,6 +68,23 @@ Variant literature assessment pipeline with AI extraction.
 
 *Each citation in the aggregated assessment links back to the exact highlighted quote in the source paper's PDF.*
 
+## Quickstart
+
+Run the whole stack locally against a captured example variant. The demo ships pre-seeded with a real assessment, so the evidence viewer is populated the moment it boots — you don't have to run the pipeline yourself to explore it.
+
+```bash
+git clone https://github.com/populationgenomics/flowa.git
+cd flowa
+pnpm install                                       # repo root — this is a pnpm workspace
+cp examples/demo/.env.example examples/demo/.env   # the demo's only config file
+# Edit examples/demo/.env: uncomment exactly one provider block and fill in your key.
+pnpm demo
+```
+
+Then open <http://localhost:7700>. `pnpm demo` builds the workspace packages and boots three services — Next.js (UI + triage API), chat-service, and a Python pipeline gateway.
+
+**Prerequisites:** [Node 24+](https://nodejs.org) (the demo uses the built-in `node:sqlite`) and [uv](https://docs.astral.sh/uv/getting-started/installation/) on your `PATH`. For the full walkthrough, demo simplifications, and how to run a live pipeline, see [`examples/demo/README.md`](examples/demo/README.md).
+
 ## Architecture
 
 Flowa is a single async pipeline that processes genetic variant literature:
@@ -84,15 +103,15 @@ Papers are processed in parallel. LLM concurrency is controlled via `--llm-concu
 
 ## Installation
 
-Install from PyPI, opting into the provider extras you need (one of `anthropic`, `bedrock`, `google`, `openai`):
+The [Quickstart](#quickstart) above needs no separate install. To use the pipeline as a library or CLI in your own project, install `flowapy` from PyPI, opting into the provider extras you need (one or more of `anthropic`, `bedrock`, `google`, `openai`):
 
 ```bash
-pip install 'flowapy[bedrock]==0.1.0'
+pip install 'flowapy[bedrock]'
 # or
-uv pip install 'flowapy[bedrock,anthropic]==0.1.0'
+uv pip install 'flowapy[bedrock,anthropic]'
 ```
 
-The `flowa` CLI is exposed as a console script. See [Configuration](#configuration) for credentials and storage setup.
+The PyPI distribution is named `flowapy` (the `flowa` name was already taken), but the import, module, and CLI are all `flowa`. The CLI is exposed as a console script — see [Configuration](#configuration) for credentials and storage setup.
 
 ## Usage
 
@@ -112,11 +131,22 @@ flowa aggregate --variant-id VAR123
 
 ### Environment Variables
 
-| Variable                | Description                                                       | Example                                            |
-| ----------------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
-| `FLOWA_STORAGE_BASE`    | Storage path for PDFs, extractions, results                       | `s3://bucket`, `gs://bucket`, `file:///path`        |
-| `FLOWA_CONVERT_MODEL`   | LLM for PDF→Markdown conversion (anchorite)                     | `bedrock:au.anthropic.claude-sonnet-4-6`        |
-| `FLOWA_EXTRACTION_MODEL`| LLM for extraction and aggregation                               | `bedrock:au.anthropic.claude-opus-4-6`          |
+The model settings are nested config objects: set their sub-fields with the `__` delimiter — `__NAME` selects the model. These three are required:
+
+| Variable                       | Description                                                                  | Example                                      |
+| ------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------- |
+| `FLOWA_STORAGE_BASE`           | Storage path for PDFs, extractions, results                                  | `s3://bucket`, `gs://bucket`, `file:///path` |
+| `FLOWA_CONVERT_MODEL__NAME`    | LLM for PDF→Markdown conversion (anchorite), in `<provider>:<model>` form   | `bedrock:au.anthropic.claude-sonnet-4-6`     |
+| `FLOWA_EXTRACTION_MODEL__NAME` | LLM for extraction and aggregation                                           | `bedrock:au.anthropic.claude-opus-4-6`       |
+
+Optional:
+
+| Variable                                            | Description                                                                                                                  |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `FLOWA_CONVERT_MODEL__BEDROCK_INFERENCE_PROFILE`    | Bedrock application inference profile ARN for cost attribution. When set, `__NAME` must point at the underlying foundation model. |
+| `FLOWA_EXTRACTION_MODEL__BEDROCK_INFERENCE_PROFILE` | Same, for the extraction/aggregation model.                                                                                 |
+| `MASTERMIND_API_TOKEN`                              | Required when querying with `--source mastermind`; use `--source litvar` (free, no token) otherwise.                        |
+| `NCBI_API_KEY`                                      | Optional NCBI key for higher PubMed rate limits.                                                                            |
 
 ### LLM Providers
 
@@ -258,10 +288,12 @@ The tag-driven workflow (`.github/workflows/release-flowapy.yaml`) builds the pa
 
 ### Local Development
 
+Run the pipeline directly from a checkout (the [Quickstart](#quickstart) demo wraps this with a UI):
+
 ```bash
 export FLOWA_STORAGE_BASE=file:///tmp/flowa
-export FLOWA_CONVERT_MODEL=bedrock:au.anthropic.claude-sonnet-4-6
-export FLOWA_EXTRACTION_MODEL=bedrock:au.anthropic.claude-opus-4-6
+export FLOWA_CONVERT_MODEL__NAME=bedrock:au.anthropic.claude-sonnet-4-6
+export FLOWA_EXTRACTION_MODEL__NAME=bedrock:au.anthropic.claude-opus-4-6
 uv run flowa run --variant-id test --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" --source litvar
 ```
 
@@ -271,8 +303,8 @@ uv run flowa run --variant-id test --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" -
 docker build --build-arg LLM_EXTRA=bedrock -t flowa .
 docker run \
   -e FLOWA_STORAGE_BASE=s3://bucket \
-  -e FLOWA_CONVERT_MODEL=bedrock:au.anthropic.claude-sonnet-4-6 \
-  -e FLOWA_EXTRACTION_MODEL=bedrock:au.anthropic.claude-opus-4-6 \
+  -e FLOWA_CONVERT_MODEL__NAME=bedrock:au.anthropic.claude-sonnet-4-6 \
+  -e FLOWA_EXTRACTION_MODEL__NAME=bedrock:au.anthropic.claude-opus-4-6 \
   -e AWS_REGION=ap-southeast-2 \
   flowa run --variant-id VAR123 --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" --source litvar
 ```
@@ -293,8 +325,8 @@ aws batch register-job-definition \
     ],
     "environment": [
       {"name": "FLOWA_STORAGE_BASE", "value": "s3://flowa-data"},
-      {"name": "FLOWA_CONVERT_MODEL", "value": "bedrock:au.anthropic.claude-sonnet-4-6"},
-      {"name": "FLOWA_EXTRACTION_MODEL", "value": "bedrock:au.anthropic.claude-opus-4-6"}
+      {"name": "FLOWA_CONVERT_MODEL__NAME", "value": "bedrock:au.anthropic.claude-sonnet-4-6"},
+      {"name": "FLOWA_EXTRACTION_MODEL__NAME", "value": "bedrock:au.anthropic.claude-opus-4-6"}
     ]
   }' \
   --retry-strategy '{"attempts": 2}' \

{flowapy-0.2.2 → flowapy-0.4.0}/README.md

@@ -6,6 +6,23 @@ Variant literature assessment pipeline with AI extraction.
 
 *Each citation in the aggregated assessment links back to the exact highlighted quote in the source paper's PDF.*
 
+## Quickstart
+
+Run the whole stack locally against a captured example variant. The demo ships pre-seeded with a real assessment, so the evidence viewer is populated the moment it boots — you don't have to run the pipeline yourself to explore it.
+
+```bash
+git clone https://github.com/populationgenomics/flowa.git
+cd flowa
+pnpm install                                       # repo root — this is a pnpm workspace
+cp examples/demo/.env.example examples/demo/.env   # the demo's only config file
+# Edit examples/demo/.env: uncomment exactly one provider block and fill in your key.
+pnpm demo
+```
+
+Then open <http://localhost:7700>. `pnpm demo` builds the workspace packages and boots three services — Next.js (UI + triage API), chat-service, and a Python pipeline gateway.
+
+**Prerequisites:** [Node 24+](https://nodejs.org) (the demo uses the built-in `node:sqlite`) and [uv](https://docs.astral.sh/uv/getting-started/installation/) on your `PATH`. For the full walkthrough, demo simplifications, and how to run a live pipeline, see [`examples/demo/README.md`](examples/demo/README.md).
+
 ## Architecture
 
 Flowa is a single async pipeline that processes genetic variant literature:
@@ -24,15 +41,15 @@ Papers are processed in parallel. LLM concurrency is controlled via `--llm-concu
 
 ## Installation
 
-Install from PyPI, opting into the provider extras you need (one of `anthropic`, `bedrock`, `google`, `openai`):
+The [Quickstart](#quickstart) above needs no separate install. To use the pipeline as a library or CLI in your own project, install `flowapy` from PyPI, opting into the provider extras you need (one or more of `anthropic`, `bedrock`, `google`, `openai`):
 
 ```bash
-pip install 'flowapy[bedrock]==0.1.0'
+pip install 'flowapy[bedrock]'
 # or
-uv pip install 'flowapy[bedrock,anthropic]==0.1.0'
+uv pip install 'flowapy[bedrock,anthropic]'
 ```
 
-The `flowa` CLI is exposed as a console script. See [Configuration](#configuration) for credentials and storage setup.
+The PyPI distribution is named `flowapy` (the `flowa` name was already taken), but the import, module, and CLI are all `flowa`. The CLI is exposed as a console script — see [Configuration](#configuration) for credentials and storage setup.
 
 ## Usage
 
@@ -52,11 +69,22 @@ flowa aggregate --variant-id VAR123
 
 ### Environment Variables
 
-| Variable                | Description                                                       | Example                                            |
-| ----------------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
-| `FLOWA_STORAGE_BASE`    | Storage path for PDFs, extractions, results                       | `s3://bucket`, `gs://bucket`, `file:///path`        |
-| `FLOWA_CONVERT_MODEL`   | LLM for PDF→Markdown conversion (anchorite)                     | `bedrock:au.anthropic.claude-sonnet-4-6`        |
-| `FLOWA_EXTRACTION_MODEL`| LLM for extraction and aggregation                               | `bedrock:au.anthropic.claude-opus-4-6`          |
+The model settings are nested config objects: set their sub-fields with the `__` delimiter — `__NAME` selects the model. These three are required:
+
+| Variable                       | Description                                                                  | Example                                      |
+| ------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------- |
+| `FLOWA_STORAGE_BASE`           | Storage path for PDFs, extractions, results                                  | `s3://bucket`, `gs://bucket`, `file:///path` |
+| `FLOWA_CONVERT_MODEL__NAME`    | LLM for PDF→Markdown conversion (anchorite), in `<provider>:<model>` form   | `bedrock:au.anthropic.claude-sonnet-4-6`     |
+| `FLOWA_EXTRACTION_MODEL__NAME` | LLM for extraction and aggregation                                           | `bedrock:au.anthropic.claude-opus-4-6`       |
+
+Optional:
+
+| Variable                                            | Description                                                                                                                  |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `FLOWA_CONVERT_MODEL__BEDROCK_INFERENCE_PROFILE`    | Bedrock application inference profile ARN for cost attribution. When set, `__NAME` must point at the underlying foundation model. |
+| `FLOWA_EXTRACTION_MODEL__BEDROCK_INFERENCE_PROFILE` | Same, for the extraction/aggregation model.                                                                                 |
+| `MASTERMIND_API_TOKEN`                              | Required when querying with `--source mastermind`; use `--source litvar` (free, no token) otherwise.                        |
+| `NCBI_API_KEY`                                      | Optional NCBI key for higher PubMed rate limits.                                                                            |
 
 ### LLM Providers
 
@@ -198,10 +226,12 @@ The tag-driven workflow (`.github/workflows/release-flowapy.yaml`) builds the pa
 
 ### Local Development
 
+Run the pipeline directly from a checkout (the [Quickstart](#quickstart) demo wraps this with a UI):
+
 ```bash
 export FLOWA_STORAGE_BASE=file:///tmp/flowa
-export FLOWA_CONVERT_MODEL=bedrock:au.anthropic.claude-sonnet-4-6
-export FLOWA_EXTRACTION_MODEL=bedrock:au.anthropic.claude-opus-4-6
+export FLOWA_CONVERT_MODEL__NAME=bedrock:au.anthropic.claude-sonnet-4-6
+export FLOWA_EXTRACTION_MODEL__NAME=bedrock:au.anthropic.claude-opus-4-6
 uv run flowa run --variant-id test --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" --source litvar
 ```
 
@@ -211,8 +241,8 @@ uv run flowa run --variant-id test --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" -
 docker build --build-arg LLM_EXTRA=bedrock -t flowa .
 docker run \
   -e FLOWA_STORAGE_BASE=s3://bucket \
-  -e FLOWA_CONVERT_MODEL=bedrock:au.anthropic.claude-sonnet-4-6 \
-  -e FLOWA_EXTRACTION_MODEL=bedrock:au.anthropic.claude-opus-4-6 \
+  -e FLOWA_CONVERT_MODEL__NAME=bedrock:au.anthropic.claude-sonnet-4-6 \
+  -e FLOWA_EXTRACTION_MODEL__NAME=bedrock:au.anthropic.claude-opus-4-6 \
   -e AWS_REGION=ap-southeast-2 \
   flowa run --variant-id VAR123 --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" --source litvar
 ```
@@ -233,8 +263,8 @@ aws batch register-job-definition \
     ],
     "environment": [
       {"name": "FLOWA_STORAGE_BASE", "value": "s3://flowa-data"},
-      {"name": "FLOWA_CONVERT_MODEL", "value": "bedrock:au.anthropic.claude-sonnet-4-6"},
-      {"name": "FLOWA_EXTRACTION_MODEL", "value": "bedrock:au.anthropic.claude-opus-4-6"}
+      {"name": "FLOWA_CONVERT_MODEL__NAME", "value": "bedrock:au.anthropic.claude-sonnet-4-6"},
+      {"name": "FLOWA_EXTRACTION_MODEL__NAME", "value": "bedrock:au.anthropic.claude-opus-4-6"}
     ]
   }' \
   --retry-strategy '{"attempts": 2}' \

{flowapy-0.2.2 → flowapy-0.4.0}/examples/demo/README.md

@@ -166,10 +166,12 @@ VARIANT=NM_001035_3-c_14174A_G
 rm -f assessments/$VARIANT/aggregation.json \
       assessments/$VARIANT/aggregation_raw.json
 rm -rf assessments/$VARIANT/extractions/ assessments/$VARIANT/runs/
-# Re-runs flowa.convert (which uses anchorite for PDF chunking and
-# builds pdf_index.pkl.zst). Drop this line to reuse the cached markdown
-# + index and only redo extract + aggregate.
-rm -f papers/*/markdown.md papers/*/convert_raw.json papers/*/pdf_index.pkl.zst
+# Re-runs flowa.convert (which transcribes each PDF, builds merged.pdf when
+# there are PDF supplements, and builds pdf_index.pkl.zst). Drop this line to
+# reuse the cached transcriptions + index and only redo extract + aggregate.
+rm -f papers/*/main.md papers/*/merged.md papers/*/merged.pdf \
+      papers/*/convert_raw.json papers/*/pdf_index.pkl.zst \
+      papers/*/supplements/*.pdf.md
 ```
 
 Then drive the pipeline. The demo's `scripts/start.ts` translates the
@@ -207,11 +209,11 @@ and not needed by anything downstream.
 
 For papers whose source license blocks redistribution (CC-BY-NC-ND,
 paywalled; see `fixtures/LICENSES.md` for the rule), do **not** delete
-the whole `papers/{encodedDoi}/` directory — only delete `source.pdf`,
-`markdown.md`, `convert_raw.json`, and `pdf_index.pkl.zst`. The
-`pdf_index.pkl.zst` embeds the PDF's extracted text (anchorite's char
-index), so it carries the same copyright as `source.pdf` and must not
-ship in the open-source repo. Keep `metadata.json` (the bibliographic
+the whole `papers/{encodedDoi}/` directory — only delete `main.pdf`,
+`merged.pdf`, `main.md`, `merged.md`, `convert_raw.json`, `pdf_index.pkl.zst`,
+and the `supplements/` directory. The `pdf_index.pkl.zst` embeds the PDF's
+extracted text (anchorite's char index), so it carries the same copyright as
+`main.pdf` and must not ship in the open-source repo. Keep `metadata.json` (the bibliographic
 fields are factual data, not copyrightable) but replace its `abstract`
 field with a sentinel string, so the omission reads as deliberate (not
 a missing-data bug) when the literature view renders the row:

{flowapy-0.2.2 → flowapy-0.4.0}/examples/demo/fixtures/LICENSES.md

@@ -2,7 +2,7 @@
 
 The fixture under `examples/demo/fixtures/papers/` ships three kinds of entries, all keyed by the encoded DOI:
 
-1. **Full-content papers** (15) — `source.pdf` + `markdown.md` + `metadata.json`. The pipeline downloaded the PDF from PMC, converted it to Markdown, and ran extraction. All are CC-BY (any version) or CC0, so both the PDF and the derivative Markdown are redistributable provided attribution is preserved (entries below).
+1. **Full-content papers** (15) — `main.pdf` + `main.md` + `metadata.json` + `pdf_index.pkl.zst`. The pipeline downloaded the main PDF from PMC, transcribed it to Markdown (`main.md`), and ran extraction. Papers with supplements also carry a `supplements/` directory and an assembled `merged.md` (`main.md` + the supplement transcriptions/conversions): **3** carry an xlsx/docx (office) supplement, and **2** carry a separate PDF supplement (which is additionally concatenated into a derived `merged.pdf` and transcribed). All are CC-BY (any version) or CC0, so the PDFs, the derivative Markdown, and the supplements are redistributable provided attribution is preserved (entries below).
 2. **Metadata-only, license-restricted** (5) — only `metadata.json`; the source paper is paywalled or under a no-derivatives / non-commercial licence (e.g. CC-BY-NC-ND). The `abstract` field is replaced with a sentinel string explaining the omission, since the abstract is the author's prose and is subject to publisher copyright. Bibliographic facts (DOI, PMID, title, authors, journal, date) are not copyrightable and ship as-is.
 3. **Metadata-only, CC-BY not in PMC** (1) — only `metadata.json`; the source paper IS CC-BY-licensed but PMC's OA subset doesn't carry it, so flowa's PMC-only download path silently skipped it. Abstract is preserved (CC-BY permits redistribution); PDF/Markdown are absent. A curator running the demo locally can fetch the PDF from the journal site.
 
@@ -54,6 +54,7 @@ For all three kinds, the demo's literature page renders the row from `metadata.j
 - **DOI:** [10.1038/s41598-022-25914-8](https://doi.org/10.1038/s41598-022-25914-8)
 - **PMID:** 36517654
 - **License:** [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+- **Supplement:** `supplements/000_41598_2022_25914_MOESM1_ESM.docx` (electronic supplementary material; inherits the article's CC-BY 4.0).
 
 ### `10.3389%2Ffcvm.2022.1061384/`
 
@@ -81,6 +82,7 @@ For all three kinds, the demo's literature page renders the row from `metadata.j
 - **DOI:** [10.3389/fcvm.2023.1261172](https://doi.org/10.3389/fcvm.2023.1261172)
 - **PMID:** 38162137
 - **License:** [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+- **Supplement:** `supplements/000_Table1.docx` (supplementary tables of patient demographics + biochemical indicators; inherits the article's CC-BY 4.0).
 
 ### `10.1186%2Fs13023-021-02146-z/`
 
@@ -99,6 +101,7 @@ For all three kinds, the demo's literature page renders the row from `metadata.j
 - **DOI:** [10.1002/humu.23878](https://doi.org/10.1002/humu.23878)
 - **PMID:** 31342611
 - **License:** [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+- **Supplement:** `supplements/000_HUMU-40-2146-s001.pdf` (supplementary data PDF; inherits the article's CC-BY 4.0).
 
 ### `10.1186%2Fs12881-019-0878-8/`
 
@@ -117,6 +120,7 @@ For all three kinds, the demo's literature page renders the row from `metadata.j
 - **DOI:** [10.1016/j.ymgmr.2024.101163](https://doi.org/10.1016/j.ymgmr.2024.101163)
 - **PMID:** 39835171
 - **License:** [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+- **Supplement:** `supplements/000_mmc1.docx` (electronic supplementary material; inherits the article's CC-BY 4.0).
 
 ### `10.1186%2Fs13052-019-0692-0/`
 
@@ -144,12 +148,18 @@ For all three kinds, the demo's literature page renders the row from `metadata.j
 - **DOI:** [10.3389/fped.2021.729824](https://doi.org/10.3389/fped.2021.729824)
 - **PMID:** 34966699
 - **License:** [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+- **Supplement:** `supplements/000_Image_1.PDF` (supplementary figure PDF; inherits the article's CC-BY 4.0).
 
 ### Derivative artifacts
 
 For each full-content paper the fixture also ships the pipeline's derivatives:
 
-- `markdown.md` — Markdown extracted from the PDF by the conversion stage.
+- `main.md` — the main PDF transcribed to Markdown by the conversion stage.
+- `merged.md` — present only for papers with supplements: `main.md` + the
+  PDF-supplement transcriptions + the converted office supplements.
+- `merged.pdf` — present only for the two papers with a PDF supplement: `main.pdf`
+  concatenated with the supplement PDF (what the viewer renders + the index is built from).
+- `pdf_index.pkl.zst` — the anchorite PDF index (embeds the PDF's extracted text).
 - `metadata.json` — bibliographic metadata (DOI, PMID, title, authors, etc.).
 
 These derivatives are released under the same CC-BY licence as the underlying PDFs.