flowapy 0.4.2__tar.gz → 0.4.3__tar.gz

{flowapy-0.4.2 → flowapy-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowapy
-Version: 0.4.2
+Version: 0.4.3
 Summary: Variant literature assessment pipeline with AI extraction
 Project-URL: Homepage, https://github.com/populationgenomics/flowa
 Project-URL: Source, https://github.com/populationgenomics/flowa
@@ -115,12 +115,20 @@ The PyPI distribution is named `flowapy` (the `flowa` name was already taken), b
 
 ## Usage
 
+A variant is passed as `--variant-spec`, either inline JSON or `@path/to/spec.json`. The
+envelope is `{"schema_version": 1, "variants": [{ "kind": "hgvs_c", "transcript": ...,
+"hgvs_c": ... }]}` — `hgvs_c` is the bare coding change with no transcript prefix. The gene
+symbol and genomic coordinates are derived downstream, so they aren't part of the spec.
+
 ```bash
+# Example variant spec (GAA / Pompe, NM_000152.5:c.2238G>C)
+SPEC='{"schema_version":1,"variants":[{"kind":"hgvs_c","transcript":"NM_000152.5","hgvs_c":"c.2238G>C"}]}'
+
 # Full pipeline
-flowa run --variant-id VAR123 --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" --source litvar
+flowa run --variant-id VAR123 --variant-spec "$SPEC" --source litvar
 
 # Individual steps (for debugging)
-flowa query --variant-id VAR123 --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" --source litvar
+flowa query --variant-id VAR123 --variant-spec "$SPEC" --source litvar
 flowa download --doi '10.1038/s41586-020-2308-7'
 flowa convert --doi '10.1038/s41586-020-2308-7'
 flowa extract --variant-id VAR123 --doi '10.1038/s41586-020-2308-7'
@@ -294,7 +302,9 @@ Run the pipeline directly from a checkout (the [Quickstart](#quickstart) demo wr
 export FLOWA_STORAGE_BASE=file:///tmp/flowa
 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
+uv run flowa run --variant-id test \
+  --variant-spec '{"schema_version":1,"variants":[{"kind":"hgvs_c","transcript":"NM_000152.5","hgvs_c":"c.2238G>C"}]}' \
+  --source litvar
 ```
 
 ### Docker
@@ -306,7 +316,9 @@ docker run \
   -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
+  flowa run --variant-id VAR123 \
+  --variant-spec '{"schema_version":1,"variants":[{"kind":"hgvs_c","transcript":"NM_000152.5","hgvs_c":"c.2238G>C"}]}' \
+  --source litvar
 ```
 
 ### AWS Batch
@@ -341,6 +353,6 @@ aws batch submit-job \
   --job-definition flowa-worker \
   --job-queue flowa-queue \
   --container-overrides '{
-    "command": ["run", "--variant-id", "VAR123", "--gene", "GAA", "--hgvs-c", "NM_000152.5:c.2238G>C", "--source", "litvar"]
+    "command": ["run", "--variant-id", "VAR123", "--variant-spec", "{\"schema_version\":1,\"variants\":[{\"kind\":\"hgvs_c\",\"transcript\":\"NM_000152.5\",\"hgvs_c\":\"c.2238G>C\"}]}", "--source", "litvar"]
   }'
 ```

{flowapy-0.4.2 → flowapy-0.4.3}/README.md

@@ -53,12 +53,20 @@ The PyPI distribution is named `flowapy` (the `flowa` name was already taken), b
 
 ## Usage
 
+A variant is passed as `--variant-spec`, either inline JSON or `@path/to/spec.json`. The
+envelope is `{"schema_version": 1, "variants": [{ "kind": "hgvs_c", "transcript": ...,
+"hgvs_c": ... }]}` — `hgvs_c` is the bare coding change with no transcript prefix. The gene
+symbol and genomic coordinates are derived downstream, so they aren't part of the spec.
+
 ```bash
+# Example variant spec (GAA / Pompe, NM_000152.5:c.2238G>C)
+SPEC='{"schema_version":1,"variants":[{"kind":"hgvs_c","transcript":"NM_000152.5","hgvs_c":"c.2238G>C"}]}'
+
 # Full pipeline
-flowa run --variant-id VAR123 --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" --source litvar
+flowa run --variant-id VAR123 --variant-spec "$SPEC" --source litvar
 
 # Individual steps (for debugging)
-flowa query --variant-id VAR123 --gene GAA --hgvs-c "NM_000152.5:c.2238G>C" --source litvar
+flowa query --variant-id VAR123 --variant-spec "$SPEC" --source litvar
 flowa download --doi '10.1038/s41586-020-2308-7'
 flowa convert --doi '10.1038/s41586-020-2308-7'
 flowa extract --variant-id VAR123 --doi '10.1038/s41586-020-2308-7'
@@ -232,7 +240,9 @@ Run the pipeline directly from a checkout (the [Quickstart](#quickstart) demo wr
 export FLOWA_STORAGE_BASE=file:///tmp/flowa
 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
+uv run flowa run --variant-id test \
+  --variant-spec '{"schema_version":1,"variants":[{"kind":"hgvs_c","transcript":"NM_000152.5","hgvs_c":"c.2238G>C"}]}' \
+  --source litvar
 ```
 
 ### Docker
@@ -244,7 +254,9 @@ docker run \
   -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
+  flowa run --variant-id VAR123 \
+  --variant-spec '{"schema_version":1,"variants":[{"kind":"hgvs_c","transcript":"NM_000152.5","hgvs_c":"c.2238G>C"}]}' \
+  --source litvar
 ```
 
 ### AWS Batch
@@ -279,6 +291,6 @@ aws batch submit-job \
   --job-definition flowa-worker \
   --job-queue flowa-queue \
   --container-overrides '{
-    "command": ["run", "--variant-id", "VAR123", "--gene", "GAA", "--hgvs-c", "NM_000152.5:c.2238G>C", "--source", "litvar"]
+    "command": ["run", "--variant-id", "VAR123", "--variant-spec", "{\"schema_version\":1,\"variants\":[{\"kind\":\"hgvs_c\",\"transcript\":\"NM_000152.5\",\"hgvs_c\":\"c.2238G>C\"}]}", "--source", "litvar"]
   }'
 ```

{flowapy-0.4.2 → flowapy-0.4.3}/examples/demo/README.md

@@ -187,7 +187,8 @@ if [ -n "${BEDROCK_INFERENCE_PROFILE:-}" ]; then
   export FLOWA_EXTRACTION_MODEL__BEDROCK_INFERENCE_PROFILE="$BEDROCK_INFERENCE_PROFILE"
   export FLOWA_CONVERT_MODEL__BEDROCK_INFERENCE_PROFILE="$BEDROCK_INFERENCE_PROFILE"
 fi
-uv run flowa run --variant-id $VARIANT --gene RYR2 --hgvs-c "NM_001035.3:c.14174A>G"
+uv run flowa run --variant-id $VARIANT \
+  --variant-spec '{"schema_version":1,"variants":[{"kind":"hgvs_c","transcript":"NM_001035.3","hgvs_c":"c.14174A>G"}]}'
 ```
 
 Open `http://localhost:7700/viewer/$VARIANT/acmg_classification` (with

{flowapy-0.4.2 → flowapy-0.4.3}/examples/demo-gateway/README.md

@@ -35,7 +35,7 @@ imports as load-bearing and the rest as something to replace.
 
 | Method | Path | Behaviour |
 |---|---|---|
-| `POST` | `/runs` | Body `{ variant_id, gene, hgvs_c }`. Spawns the pipeline as an `asyncio` task and returns `{ run_id, started_at, status }` immediately. 409 if a run is already in flight for the variant; 429 at the concurrency cap. |
+| `POST` | `/runs` | Body `{ variant_id, variant_spec }`, where `variant_spec` is the `flowa.schema.VariantSpec` envelope. Spawns the pipeline as an `asyncio` task and returns `{ run_id, started_at, status }` immediately. 409 if a run is already in flight for the variant; 429 at the concurrency cap. |
 | `GET`  | `/runs/active?variant_id=X` | Most recent run for `variant_id` as `{ run_id, started_at, status }`. 404 if none. `status` is `running` while in flight; `success` / `error` once terminal. |
 | `POST` | `/resolve-citations` | Body `{ citations: [{ doi, quotes[] }] }`. Builds fsspec-based PDF and Markdown loaders rooted at `DEMO_DATA_DIR/papers/{encoded_doi}/` and calls `flowa.resolve.resolve_citations(...)` synchronously. Returns `{ resolved: { doi: { quote: HighlightBbox[] } }, errors: { doi: string } }`. DOIs whose source PDF or markdown can't be loaded land in `errors`; quotes the aligner searches for but can't locate land as empty arrays in `resolved`. |
 | `GET`  | `/health` | `{ "status": "ok" }`. |

{flowapy-0.4.2 → flowapy-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowapy"
-version = "0.4.2"
+version = "0.4.3"
 description = "Variant literature assessment pipeline with AI extraction"
 readme = "README.md"
 requires-python = "==3.13.*"

{flowapy-0.4.2 → flowapy-0.4.3}/src/flowa/content_validation.py

@@ -13,8 +13,11 @@ anchorite-backed resolver, not here.
 
 Keep in sync with `packages/chat-service/src/chat.ts` (`validateArtifactContent`).
 One rule here has no edit-time counterpart — `claim_quote_not_in_extraction`:
-every claim citation quote must be one the extraction surfaced. It's the same
-kind of exact, model-vs-model check; chat-service can't run it because an edit
+every claim citation quote must be byte-present in a quote the extraction
+surfaced — exact, or a contiguous substring of one (the aggregator legitimately
+trims a long surfaced passage to its load-bearing clause; that span is still
+verbatim source text and still resolves to a highlight downstream). It is still
+byte-exact, not a fuzzy threshold. chat-service can't run it because an edit
 session has no extraction input to compare against.
 """
 
@@ -28,6 +31,20 @@ from flowa.artifact import CategoryResult
 _CITE_LINK_RE = re.compile(r'\[[^\]]*\]\(#cite:([^ )"]+)(?:\s+"([^"]*)")?\)')
 
 
+def _quote_grounded(quote: str, allowed: set[str]) -> bool:
+    """True if `quote` is byte-present in any extraction quote the model was fed.
+
+    Exact set-membership (fast path), or a contiguous substring of a surfaced
+    quote — the aggregator trimming a long extraction passage to its load-bearing
+    clause is grounded, not fabricated. An empty quote grounds nothing.
+    """
+    if not quote:
+        return False
+    if quote in allowed:
+        return True
+    return any(quote in surfaced for surfaced in allowed)
+
+
 def validate_aggregate_category(
     cat_result: CategoryResult,
     valid_paper_ids: set[str],
@@ -90,11 +107,18 @@ def validate_aggregate_category(
             )
             break
 
-    # Every claim citation quote must be one the extraction surfaced.
+    # Every claim citation quote must be grounded in what the extraction surfaced.
+    # The aggregate model is fed only the extraction quotes (never the paper
+    # Markdown), so a claim quote is grounded iff it is byte-present in a surfaced
+    # quote for that paper. A contiguous SUBSTRING of a surfaced quote counts:
+    # the extraction deliberately captures long passages (a full sentence / table
+    # row) and the aggregator legitimately trims to the load-bearing clause, which
+    # is still verbatim source text and still resolves to a highlight downstream.
+    # Only a quote contained in NO surfaced quote is a fabrication/alteration.
     for claim in cat_result.claims:
         allowed = extraction_quotes_by_paper.get(claim.paper_id, set())
         for citation in claim.citations:
-            if citation.quote not in allowed:
+            if not _quote_grounded(citation.quote, allowed):
                 errors.append(
                     (
                         'claim_quote_not_in_extraction',

{flowapy-0.4.2 → flowapy-0.4.3}/tests/test_content_validation.py

@@ -162,3 +162,24 @@ def test_claim_quote_must_come_from_extraction() -> None:
         extraction_quotes_by_paper={'Smith2024': {'a quote the extraction actually surfaced'}},
     )
     assert 'claim_quote_not_in_extraction' in _rules(errors)
+
+
+def test_claim_quote_substring_of_extraction_passes() -> None:
+    # The extraction surfaces a long passage; the aggregator legitimately trims
+    # it to its load-bearing clause. That contiguous substring is still verbatim
+    # source text (it resolves to a highlight downstream), so it is grounded.
+    surfaced = (
+        'Each parent was heterozygous for one allele, and an unaffected sister did not have a mutation at either site.'
+    )
+    trimmed = 'an unaffected sister did not have a mutation at either site'
+    cat = _cat(
+        notes=f'Non-carrier sib ([sib](#cite:Smith2024 "{trimmed}")).',
+        papers=('Smith2024',),
+        claims=(_claim('Smith2024', trimmed),),
+    )
+    errors = validate_aggregate_category(
+        cat,
+        valid_paper_ids={'Smith2024'},
+        extraction_quotes_by_paper={'Smith2024': {surfaced}},
+    )
+    assert errors == []

{flowapy-0.4.2 → flowapy-0.4.3}/uv.lock

@@ -492,7 +492,7 @@ wheels = [
 
 [[package]]
 name = "flowapy"
-version = "0.4.2"
+version = "0.4.3"
 source = { editable = "." }
 dependencies = [
     { name = "anchorite" },