deploy API

requirements.txt

@@ -10,3 +10,5 @@ pillow>=11
 huggingface_hub>=0.24     # downloads the model, catalogue and safety.sqlite from the private assets repo
 python-multipart>=0.0.9   # image uploads
 opencv-python-headless>=4.10   # the stand-in pill finder (/v1/scan)
+pypdf>=5.0                # prescriptions as PDF: the text layer
+pypdfium2>=4.30           # scanned PDFs: pages rendered for the text reader

serving/app/main.py

@@ -43,10 +43,12 @@ from pydantic import BaseModel, Field, ValidationError
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from epills.core.catalogue.confidence import assess
+from epills.core.catalogue.identity import product_identity
 from epills.core.catalogue.store import IMPRINT_ALPHA, IMPRINT_TOP_K
 from epills.core.imprint.match import GALLERY_MIN_WEIGHT, read_hits
 from epills.core.inference.matching import check_imprint, decide
 from epills.core.inference.pill_finder import detect_pills
+from epills.core.label import STRENGTH, compare_with_list, document_fields
 from epills.core.inference.preprocess import WINDOW, crop_window
 from epills.core.safety import openfda
 from epills.core.safety.db import SafetyDB
@@ -54,7 +56,7 @@ from epills.core.safety.rules import SOURCE_SCHEDULE, Alert, check_dose, check_m
 from epills.core.safety.rxnorm import RxNormClient, RxNormError
 from serving.app import schemas as S
 
-API_VERSION = "0.6.0"
+API_VERSION = "0.7.0"
 STARTED_AT = datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")
 LOCAL = {"safety_db": Path("data/processed/safety/safety.sqlite"),
          "embedder": Path("outputs/serving/stage2_model.pt"),
@@ -66,6 +68,10 @@ LABEL_NOTE = ("Medicines read from the photo. Check the name and strength agains
 VISUAL_LIMITS = ("A visual comparison with reference photos only: it can't confirm what the medicine is, its strength, "
                  "or that it is safe to take.")
 NO_PILL = "No pill found. Spread the pills apart on a plain background and photograph them again."
+SAFETY_NOTE = ("No alert doesn't mean these medicines are safe together: only interactions listed in DDInter 2.0 "
+               "between identified ingredients, and the same ingredient twice, are checked. Check with your pharmacist.")
+IMAGE_LICENCE = ("NLM C3PI pill images: for research and development use. A catalogue picture may not show the product "
+                 "the patient holds.")
 STAND_IN = "stand-in finder (plain backgrounds only)"
 MATCH_MESSAGES = {  # visual evidence only (blueprint D5): "looks like", never "is"
     "match": "This pill looks like your {name}.",
@@ -388,8 +394,12 @@ def product_summary(cat, pill_id, **extra):
     return {
         "pill_id": pill_id, "name": p["name"], "rxnorm_name": p["rxnorm_name"], "generic_name": p["generic_name"],
         "manufacturer": p["manufacturer"], "ingredients": [i["name"] for i in p["ingredients"]],
+        # identity fields (blueprint B13): never merge products across strength, dose form or release
+        **product_identity(p["rxnorm_name"]), "ndc9": p["ndc9"], "ndc11": p["ndc11"], "rxcui": p["rxcui"],
+        "rxnorm_status": p["rxnorm_status"], "market": "US",
         "shape": p["shape"], "colour": p["colour"], "size_mm": p["size_mm"], "imprint": p["imprint"],
         "images": [{"url": f"/v1/pills/{pill_id}/image/{i['n']}", "kind": i["kind"]} for i in p["images"]],
+        "image_licence": IMAGE_LICENCE,
         **extra,
     }
 
@@ -437,6 +447,16 @@ def health():
     }
 
 
+@app.get("/v1/tools")
+def tools():
+    """
+    Typed tool definitions for the Medication Care Agent (blueprint B14), generated from this API's OpenAPI document:
+    name, description for the agent, input and output schema, and how to call each. See docs/agent_tools.md.
+    """
+    from serving.app.tools import build_tools
+    return build_tools(app.openapi())
+
+
 @app.get("/v1/model-info", response_model=S.ModelInfo)
 def model_info():
     """
@@ -639,28 +659,79 @@ def advisory_dose(sched, pills, detection, meds):
 
 
 @app.post("/v1/read-label", response_model=S.ReadLabelResponse)
-async def read_label(image: UploadFile = File(description="A photo of a medicine box or a pharmacy label, close "
-                                                          "up and straight on")):
+async def read_label(image: UploadFile = File(description="A photo of a medicine box, a pharmacy label or a "
+                                                          "prescription (close up, straight on), or a PDF"),
+                     medications: str | None = Form(None, description="Optional JSON list of the patient's "
+                                                                      "medications, [{id, name, rxcui?, strength?}]: "
+                                                                      "each medicine read is compared with it")):
     """
-    **Which medicine is on this box or label?** Reads the printed text and finds the medicine names in it (RxNorm's
-    ingredient and brand names, international names such as paracetamol too), with strength, ingredients and RxNorm
-    code: send a candidate to `/v1/safety/medications` as `{"id", "name", "rxcui"}`. Always ask the user to confirm.
-    Nothing is stored; only the lines that name a medicine are returned (a label also shows the patient's name).
+    **Which medicine is on this box, label or prescription?** Reads the printed text and finds the medicine names in
+    it (RxNorm's ingredient and brand names, international names such as paracetamol too), with strength,
+    ingredients, RxNorm code, and what is printed about each (directions, quantity, dose form, dates), every value
+    with the line it was read from and `null` when not printed (blueprint B7). With `medications`, each medicine is
+    compared with the patient's list: same medicine, different strength, or not on the list (B9). Send a confirmed
+    candidate to `/v1/safety/medications` as `{"id", "name", "rxcui"}`. Always ask the user to confirm.
+    Nothing is stored; only the lines that name or describe a medicine are returned (labels show the patient's name).
     """
-    photo = await read_image(image)
+    data = await image.read()
     reader = asset("reader")
-    lines = await run_in_threadpool(reader.read_text, photo)
+    if data[:5] == b"%PDF-" or (image.filename or "").lower().endswith(".pdf"):
+        lines, source = await run_in_threadpool(pdf_lines, data, reader)
+    else:
+        try:
+            photo = ImageOps.exif_transpose(Image.open(io.BytesIO(data))).convert("RGB")
+        except (UnidentifiedImageError, OSError) as error:
+            raise HTTPException(422, f"{image.filename or 'image'} is not a readable image or PDF: {error}")
+        lines, source = await run_in_threadpool(reader.read_text, photo), "photo"
+    meds = parse_json(medications, "medications") if medications else None
     try:
-        candidates = await run_in_threadpool(asset("label_reader").read, lines)
+        label_reader = asset("label_reader")
+        candidates = await run_in_threadpool(label_reader.read, lines)
+        document_fields(lines, candidates)
+        if meds is not None:
+            listed = await run_in_threadpool(resolve_list, meds)
+            for c in candidates:
+                c["list_check"] = compare_with_list(c, listed)
     except RxNormError as error:
         raise HTTPException(502, f"RxNorm didn't answer: {error}")
-    result = {"candidates": candidates, "note": LABEL_NOTE, "ocr_model": reader.name}
+    result = {"candidates": candidates, "note": LABEL_NOTE, "ocr_model": reader.name, "source": source}
     if not candidates:
         result["message"] = ("No medicine name found. Photograph the label closer, straight on and in good light, "
                              "or type the name.")
     return result
 
 
+def pdf_lines(data, reader, max_pages=3):
+    """A PDF's lines: its text layer when it has one, else its pages rendered and read like photos."""
+    from pypdf import PdfReader
+    try:
+        pages = PdfReader(io.BytesIO(data)).pages[:max_pages]
+        lines = [line.strip() for page in pages for line in (page.extract_text() or "").splitlines() if line.strip()]
+    except Exception as error:
+        raise HTTPException(422, f"not a readable PDF: {error}")
+    if sum(len(line) for line in lines) >= 20:
+        return lines, "pdf_text"
+    import pypdfium2
+    pdf = pypdfium2.PdfDocument(data)
+    lines = []
+    for i in range(min(len(pdf), max_pages)):
+        lines += reader.read_text(pdf[i].render(scale=2).to_pil())
+    return lines, "pdf_scan"
+
+
+def resolve_list(meds):
+    """The patient's list for the comparison: each medication's ingredients (RxNorm) and printed strength."""
+    out = []
+    for m in meds:
+        if not isinstance(m, dict) or not m.get("id"):
+            raise HTTPException(422, "medications: each needs an id (and a name or rxcui)")
+        r = resolve_medication({"id": str(m["id"]), "name": m.get("name"), "rxcui": m.get("rxcui")}, app.state.rxnorm)
+        strength = m.get("strength") or next((x.group() for x in STRENGTH.finditer(m.get("name") or "")), None)
+        out.append({"id": str(m["id"]), "name": m.get("name") or r.display_name,
+                    "ingredients": {i.rxcui for i in r.ingredients if i.rxcui}, "strength": strength})
+    return out
+
+
 @app.get("/v1/pills/search", response_model=S.SearchResponse)
 def pills_search(name: str = Query(min_length=2, description="Brand or generic name, e.g. 'metformin', 'Glucophage'"),
                  strength: str | None = Query(None, description="e.g. '500 MG'"),
@@ -746,7 +817,8 @@ def safety_medications(request: MedicationsRequest):
     """
     Run when a medication is added or changed: interactions between every pair of the patient's medications
     (DDInter severity) and therapeutic duplications (the same active ingredient twice). Medications that can't be
-    identified are reported as alerts, so an empty alert list means every medication was checked.
+    identified are reported as alerts. `coverage` says what could actually be screened: **no alert does not mean the
+    medicines are safe together** (blueprint B10).
     """
     db = asset("safety_db")
     resolved = [resolve_medication(m.model_dump(), app.state.rxnorm) for m in request.medications]
@@ -755,11 +827,27 @@ def safety_medications(request: MedicationsRequest):
         "alerts": [a.to_dict() for a in alerts],
         "medications": per_med,
         "all_identified": all(m.resolved_by != "unresolved" for m in resolved),
+        "coverage": coverage(per_med),
+        "note": SAFETY_NOTE,
         "sources": {"interactions": db.meta.get("source"), "licence": db.meta.get("licence"),
                     "built_at": db.meta.get("built_at")},
     }
 
 
+def coverage(per_med):
+    """What the interaction check could screen: medications with at least one ingredient in DDInter, and pairs."""
+    screened = {m["id"] for m in per_med
+                if len(m["ingredients"]) > len(m["not_in_interaction_database"])}
+    ids = [m["id"] for m in per_med]
+    pairs = [(a, b) for i, a in enumerate(ids) for b in ids[i + 1:]]
+    checked = sum(a in screened and b in screened for a, b in pairs)
+    return {"medications": len(per_med), "screened": len(screened),
+            "not_screened": [m["name"] for m in per_med if m["id"] not in screened],
+            "ingredients_not_in_interaction_database": sorted({n for m in per_med
+                                                               for n in m["not_in_interaction_database"]}),
+            "pairs": len(pairs), "pairs_checked": checked, "pairs_not_checkable": len(pairs) - checked}
+
+
 @app.post("/v1/safety/dose", response_model=S.DoseResponse)
 def safety_dose(request: DoseRequest):
     """

serving/app/schemas.py

@@ -121,6 +121,11 @@ class Picture(Out):
     kind: str
 
 
+class Strength(Out):
+    ingredient: str
+    strength: str
+
+
 class Product(Out):
     pill_id: str
     name: str | None
@@ -128,11 +133,24 @@ class Product(Out):
     generic_name: str | None
     manufacturer: str | None
     ingredients: list[str]
+    strength: str | None = Field(None, description="e.g. '500 MG', or '40 MG / 1100 MG' for a combination")
+    strengths: list[Strength] = []
+    dose_form: str | None = Field(None, description="e.g. 'Oral Tablet', 'Extended Release Oral Capsule', 'Pack'")
+    release: Literal["IR", "ER", "DR"] | None = Field(None, description="Immediate, extended or delayed release")
+    brand: str | None = None
+    brand_or_generic: Literal["brand", "generic"] | None = None
+    pack: list[dict] | None = Field(None, description="For packs: each kind of pill, with count and strength")
+    ndc9: str | None = None
+    ndc11: str | None = None
+    rxcui: str | None = None
+    rxnorm_status: str | None = None
+    market: Literal["US"] = "US"
     shape: str | None
     colour: str | None
     size_mm: float | None
     imprint: str | None
     images: list[Picture]
+    image_licence: str | None = None
 
 
 class Candidate(Product):
@@ -230,6 +248,25 @@ class Ingredient(Out):
     name: str
 
 
+class Printed(Out):
+    value: str
+    line: str = Field(description="The line(s) it was read from")
+
+
+class DocumentFields(Out):
+    directions: Printed | None = Field(None, description="As printed, e.g. 'Take 1 tablet twice a day after meals'")
+    quantity: Printed | None = None
+    dose_form: Printed | None = None
+    date: Printed | None = Field(None, description="Dispensing or prescription date, as printed")
+    expiry_date: Printed | None = None
+
+
+class ListCheck(Out):
+    status: Literal["same_medicine", "different_strength", "contains_listed", "not_on_list"]
+    medication_id: str | None
+    message: str
+
+
 class LabelCandidate(Out):
     name: str
     brand: str | None
@@ -238,12 +275,17 @@ class LabelCandidate(Out):
     rxcui: str | None
     rxnorm_name: str | None
     found_in: list[str] = Field(description="Only the lines that name the medicine")
+    first_line: int | None = None
+    fields: DocumentFields | None = Field(None, description="What is printed about this medicine; null when not "
+                                                            "printed, never inferred")
+    list_check: ListCheck | None = Field(None, description="With `medications`: compared with the patient's list")
 
 
 class ReadLabelResponse(Out):
     candidates: list[LabelCandidate]
     note: str
     ocr_model: str
+    source: Literal["photo", "pdf_text", "pdf_scan"] = "photo"
     message: str | None = None
 
 
@@ -259,20 +301,36 @@ class SearchResponse(Out):
 
 
 # ---- Stage 3 and feedback --------------------------------------------------------------------------------------------
+class Coverage(Out):
+    medications: int
+    screened: int = Field(description="Medications with at least one ingredient in the interaction database")
+    not_screened: list[str]
+    ingredients_not_in_interaction_database: list[str]
+    pairs: int
+    pairs_checked: int
+    pairs_not_checkable: int
+
+
 class MedicationsResponse(Out):
     alerts: list[Alert]
     medications: list[dict]
     all_identified: bool
+    coverage: Coverage
+    note: str = Field(description="No alert doesn't mean the medicines are safe together")
     sources: dict
 
 
 class LabelResponse(Out):
     brand_name: str | None
     generic_name: str | None
-    label_date: str | None
+    label_date: str | None = Field(description="The label's effective date (YYYYMMDD)")
     matched_by: str
     sections: dict[str, str]
     disclaimer: str
+    source: str | None = None
+    set_id: str | None = None
+    label_id: str | None = None
+    url: str | None = Field(None, description="The label on DailyMed, for citation")
 
 
 class FeedbackStored(Out):

serving/app/tools.py

@@ -0,0 +1,88 @@
+"""
+Typed tool definitions for the Medication Care Agent (blueprint job B14), generated from the API's own OpenAPI
+document so they can't drift from it. Served at GET /v1/tools; usage notes and example traces in docs/agent_tools.md.
+
+Each tool: name (the blueprint's where it names one), description written for the agent (when to call it, what it
+must not conclude), input_schema (JSON Schema; an uploaded file becomes an image reference the app's tool layer
+resolves), output_schema ($refs into `components`), and how to call it (method, path, content type).
+"""
+
+TOOLS = [
+    ("detect_pills", "post", "/v1/detect",
+     "Find each pill in a photo and say whether the count can be trusted. Call before counting pills or embedding "
+     "several pills. If count_reliable is false, don't count: ask for a new photo (pills apart, plain surface)."),
+    ("embed_pill", "post", "/v1/embed",
+     "Turn one loose-pill photo (or a photo + box) into a 256-number embedding. Use at enrolment (store it with "
+     "model_version and embedding_space_id) and before match_gallery. Never embed boxes or blister packs."),
+    ("match_gallery", "post", "/v1/match",
+     "Compare pill embeddings with the patient's gallery: match / unknown / ambiguous per pill. Visual evidence only: "
+     "a match means 'looks like', not 'is' or 'safe to take'. ambiguous: ask for another photo. The gallery's "
+     "model_version is required; on 409 re-embed the enrolment photos."),
+    ("identify_pill", "post", "/v1/identify",
+     "Possible catalogue matches (US products) for a pill that isn't in the patient's list. Report the verdict and "
+     "confidence, never a definite identity; no_confident_match means the pill may not be a catalogue product."),
+    ("scan_photo", "post", "/v1/scan",
+     "Diagnostics in one call: detection plus each pill's visual decision (with a gallery) or catalogue candidates. "
+     "Don't use its dose check (deprecated): apply the backend's dose rules to the pills it returns."),
+    ("extract_medication_document", "post", "/v1/read-label",
+     "Read a medicine box, pharmacy label or prescription (photo or PDF): medicine names, strength, RxNorm code and "
+     "what is printed (directions, quantity, dates), each with its source line. Fields not printed are null; never "
+     "fill them in. With the patient's medications, says same medicine / different strength / not on the list. "
+     "Always have the patient confirm."),
+    ("find_medication_product", "get", "/v1/pills/search",
+     "Products and pictures for a medicine name (brand or generic), with strength, dose form and release as fields. "
+     "Never treat products of another strength or form as the same."),
+    ("screen_medication_list", "post", "/v1/safety/medications",
+     "Interaction and duplicate-ingredient alerts for the whole medication list (DDInter 2.0). Read coverage: no "
+     "alert does not mean safe. Advisory; defer to the pharmacist."),
+    ("evaluate_dose_reference", "post", "/v1/safety/dose",
+     "The reference dose rules on visual decisions (stateless). The backend's own dose policy is authoritative."),
+    ("retrieve_medication_info", "get", "/v1/safety/label",
+     "Warning sections of the official US label, with the label's date and DailyMed link for citation. General "
+     "information, not the patient's instructions."),
+    ("get_model_info", "get", "/v1/model-info",
+     "The served model: version, embedding space, decision rule and known limits. Check after a 409."),
+]
+FILE_NOTE = "An image reference: the app's tool layer uploads the file (photo, or PDF for documents)"
+
+
+def _resolve(schema, components):
+    ref = schema.get("$ref", "") if isinstance(schema, dict) else ""
+    return components.get(ref.rsplit("/", 1)[-1], {}) if ref else schema
+
+
+def _input_schema(op, components):
+    props, required = {}, []
+    for p in op.get("parameters", []):
+        props[p["name"]] = {**p.get("schema", {}), "description": p.get("description", "")}
+        if p.get("required"):
+            required.append(p["name"])
+    content = op.get("requestBody", {}).get("content", {})
+    for kind in ("application/json", "multipart/form-data"):
+        if kind in content:
+            body = _resolve(content[kind]["schema"], components)
+            for name, s in body.get("properties", {}).items():
+                is_file = s.get("format") == "binary" or s.get("contentMediaType") or \
+                    (s.get("type") == "array" and (s.get("items", {}).get("format") == "binary"
+                                                   or s.get("items", {}).get("contentMediaType")))
+                props[name] = ({"type": "array", "items": {"type": "string"}, "description": FILE_NOTE}
+                               if is_file and s.get("type") == "array" else
+                               {"type": "string", "description": FILE_NOTE} if is_file else s)
+            required += body.get("required", [])
+    return {"type": "object", "properties": props, "required": sorted(set(required))}
+
+
+def build_tools(openapi):
+    components = openapi.get("components", {}).get("schemas", {})
+    tools = []
+    for name, method, path, description in TOOLS:
+        op = openapi["paths"][path][method]
+        ok = op.get("responses", {}).get("200", {}).get("content", {}).get("application/json", {})
+        kind = next(iter(op.get("requestBody", {}).get("content", {"none": None})))
+        tools.append({"name": name, "description": description, "input_schema": _input_schema(op, components),
+                      "output_schema": ok.get("schema", {}),
+                      "call": {"method": method.upper(), "path": path,
+                               "content_type": None if kind == "none" else kind}})
+    return {"tools": tools, "components": {"schemas": components},
+            "notes": "Stage 2 answers are visual evidence only. The backend's safety policy decides actions; the "
+                     "agent reports evidence with its limits and asks the patient to confirm."}

src/epills/core/catalogue/identity.py

@@ -0,0 +1,45 @@
+"""
+A catalogue product's identity, from its RxNorm name (blueprint job B13): products must never be merged across
+strength, dose form or release, so these are returned as fields, not left inside a name.
+
+RxNorm clinical and branded drug names follow one pattern:
+  [12 HR | 24 HR] <ingredient> <amount> <unit> [/ <ingredient> <amount> <unit> ...] <dose form> [<Brand>]
+e.g. "24 HR metformin hydrochloride 500 MG Extended Release Oral Tablet [Glucophage]".
+"""
+import re
+
+UNIT = r"(?:MG|MCG|UNT|MEQ|ML|%|MG/ML|MG/MG|MCG/ML|UNT/ML|MEQ/ML|MG/HR|MCG/HR|MG/ACTUAT|MCG/ACTUAT|ACTUAT)"
+AMOUNT = re.compile(rf"(\d+(?:\.\d+)?)\s+({UNIT})(?=\s|$)")
+
+
+def product_identity(rxnorm_name, name=None):
+    """-> strength, strengths (per ingredient), dose_form, release (IR / ER / DR), brand, brand_or_generic."""
+    out = {"strength": None, "strengths": [], "dose_form": None, "release": None, "brand": None,
+           "brand_or_generic": None}
+    text = (rxnorm_name or "").strip()
+    if not text:
+        return out
+    brand = re.search(r"\s*\[([^\]]+)\]\s*$", text)
+    if brand:
+        out["brand"], text = brand.group(1), text[:brand.start()]
+    out["brand_or_generic"] = "brand" if brand else "generic"
+    if text.startswith("{"):  # a pack, e.g. "{7 (... Oral Tablet) / 7 (... Oral Tablet) } Pack": several pills
+        out["dose_form"], out["release"] = "Pack", "IR"
+        out["pack"] = [{"count": int(n), **{k: v for k, v in product_identity(re.sub(r"\s*\[[^\]]*\]", "", c)).items()
+                                            if k in ("strength", "dose_form", "release")}}
+                       for n, c in re.findall(r"(\d+) \(([^()]*)\)", text)]
+        return out
+    upper = text.upper()
+    out["release"] = ("ER" if re.match(r"^\d+ HR ", text) or "EXTENDED RELEASE" in upper else
+                      "DR" if "DELAYED RELEASE" in upper else "IR")
+    amounts = list(AMOUNT.finditer(text))
+    if amounts:
+        out["dose_form"] = text[amounts[-1].end():].strip() or None
+        body = re.sub(r"^\d+ HR ", "", text[:amounts[-1].end()])
+        for part in body.split(" / "):
+            m = AMOUNT.search(part)
+            if m:
+                out["strengths"].append({"ingredient": part[:m.start()].strip(),
+                                         "strength": f"{m.group(1)} {m.group(2)}"})
+        out["strength"] = " / ".join(s["strength"] for s in out["strengths"]) or None
+    return out

src/epills/core/imprint/ocr.py

@@ -52,8 +52,22 @@ class ImprintReader:
         return [texts[i:i + n] for i in range(0, len(texts), n)]
 
     def read_text(self, image, max_new_tokens=512):
-        """A photo of a box or label -> its lines of text, top to bottom (Florence-2's OCR with regions)."""
+        """
+        A photo of a box, label or document page -> its lines of text, top to bottom (Florence-2's OCR with
+        regions). Florence sees every image at 768 x 768, so a tall page is read in overlapping bands.
+        """
         image = image.convert("RGB")
+        w, h = image.size
+        if h <= 1.25 * w:
+            return self._read_region(image, max_new_tokens)
+        band, lines = int(w * 0.8), []
+        for top in range(0, max(1, h - band // 6), int(band * 0.85)):
+            for line in self._read_region(image.crop((0, top, w, min(h, top + band))), max_new_tokens):
+                if line not in lines[-8:]:  # the overlap reads some lines twice
+                    lines.append(line)
+        return lines
+
+    def _read_region(self, image, max_new_tokens):
         x = self.processor(text=["<OCR_WITH_REGION>"], images=[image], return_tensors="pt")
         raw = self.processor.batch_decode(self.generate(x["input_ids"], x["pixel_values"], max_new_tokens),
                                           skip_special_tokens=False)[0]

src/epills/core/label.py

@@ -243,7 +243,109 @@ class LabelReader:
                 "rxcui": product[0] if product else (lead.rxcui if lead.tty != "INN" else g["ingredients"][0][0]),
                 "rxnorm_name": product[1] if product else None,
                 "found_in": [lines[i] for i in sorted({f.line for f in found})],
+                "first_line": found[0].line,
                 "_rank": (-(bool(brand) + bool(strengths) + bool(product) + len(found)), found[0].line),
             })
         out.sort(key=lambda c: c.pop("_rank"))
         return out
+
+
+# ---- what else a label or prescription says (blueprint job B7) -------------------------------------------------------
+DIRECTION_START = re.compile(r"^\s*(take|apply|use|inhale|instil+|insert|dissolve|chew|swallow|place|spray|give|put|"
+                             r"rub|gargle|dilute|one|two|1|2)\b", re.I)
+DIRECTION_WORDS = re.compile(r"\b(times? (a|per) day|(once|twice|thrice) (a|per) day|daily|every \d+ hours?|"
+                             r"when necessary|as needed|at night|in the "
+                             r"morning|at bedtime|before (meals|food|breakfast)|after (meals|food|breakfast)|"
+                             r"with (meals|food)|on an empty stomach)\b", re.I)
+QUANTITY = re.compile(r"\b(?:qty|quantity|dispensed)\s*[:.]?\s*(\d+)\s*([a-z]*)|\b(\d+)\s+"
+                      r"(?:(?!(?:mg|mcg|g|ml|iu)\b)[a-z\-]+\s+)?(tablets?|capsules?|caplets?|tabs?|caps?|sachets?)\b",
+                      re.I)
+DATE = re.compile(r"\b(\d{1,2}[/.\-]\d{1,2}[/.\-]\d{2,4}|\d{1,2} (?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)"
+                  r"[a-z]* \d{4}|\d{1,2}[/.\-]\d{4})\b", re.I)
+PERSONAL = re.compile(r"\b(name|patient|nric|fin|address|tel|phone|dob|date of birth)\b", re.I)
+
+
+def _field(value, line):
+    return {"value": value, "line": line} if value else None
+
+
+def document_fields(lines, candidates):
+    """
+    Per candidate, what the label prints about it, each value with the line it was read from; None when it isn't
+    printed (never inferred). A candidate's block runs from its first line to the next candidate's (the first one
+    also gets the header lines above it: the dispensing date). Lines with personal details are never used.
+    """
+    starts = sorted({c["first_line"] for c in candidates})
+    for c in candidates:
+        i = starts.index(c["first_line"])
+        lo = 0 if i == 0 else starts[i]
+        hi = starts[i + 1] if i + 1 < len(starts) else len(lines)
+        block = [(n, lines[n]) for n in range(lo, hi) if not PERSONAL.search(lines[n])]
+        directions, quantity, date, expiry = [], None, None, None
+        for n, line in block:
+            is_direction = n >= c["first_line"] and (DIRECTION_START.search(line) and DIRECTION_WORDS.search(line)
+                                                    or (directions and directions[-1][0] == n - 1
+                                                        and DIRECTION_WORDS.search(line)))
+            if is_direction:
+                directions.append((n, line))
+                continue
+            q = QUANTITY.search(line)
+            if q and quantity is None and n >= c["first_line"] and line not in c["found_in"]:
+                number, unit = (q.group(1), q.group(2)) if q.group(1) else (q.group(3), q.group(4))
+                quantity = _field(f"{number} {unit.lower()}".strip(), line)
+            d = DATE.search(line)
+            if d:
+                if re.search(r"\bexp", line, re.I):
+                    expiry = expiry or _field(d.group(1), line)
+                else:
+                    date = date or _field(d.group(1), line)
+        form = dose_form([line for n, line in block if n >= c["first_line"]])
+        c["fields"] = {
+            "directions": _field(" ".join(l for _, l in directions), " / ".join(l for _, l in directions)),
+            "quantity": quantity,
+            "dose_form": _field(form, next((l for n, l in block if n >= c["first_line"] and form and
+                                            re.search(form[:5], l, re.I)), None)),
+            "date": date,
+            "expiry_date": expiry,
+        }
+    return candidates
+
+
+# ---- is this box one of my medicines? (blueprint job B9) -------------------------------------------------------------
+def _amounts(strength):
+    """'500 mg, 65 mg' or '500 MG / 65 MG' -> {(500.0, 'mg'), (65.0, 'mg')}."""
+    return {(float(m.group(1).replace(",", ".")), m.group(2).lower().replace("µg", "mcg").replace("ug", "mcg"))
+            for m in STRENGTH.finditer(strength or "")}
+
+
+def compare_with_list(candidate, medications):
+    """
+    medications: the patient's list, each {"id", "name", "ingredients": {rxcui}, "strength": printed or None}.
+    -> {"status", "medication_id", "message"}: a deterministic comparison of ingredients and strength, no model score.
+      same_medicine        same ingredients and strength (or the list gives no strength)
+      different_strength   same ingredients, another strength
+      contains_listed      a combination that includes a listed medicine's ingredient
+      not_on_list          no ingredient in common
+    """
+    have = {i["rxcui"] for i in candidate["ingredients"] if i.get("rxcui")}
+    best = None
+    for med in medications:
+        common = have & med["ingredients"]
+        if not common:
+            continue
+        if common == have == med["ingredients"]:
+            a, b = _amounts(candidate.get("strength")), _amounts(med.get("strength"))
+            if a and b and a != b:
+                status = "different_strength"
+                message = (f"This says {candidate.get('strength')}; your list has {med['name']}. Check with your "
+                           "pharmacist.")
+            else:
+                status = "same_medicine"
+                message = f"This matches your {med['name']}: the same medicine" + \
+                          (" and strength." if a and b else ". Check the strength printed on it.")
+            return {"status": status, "medication_id": med["id"], "message": message}
+        best = best or {"status": "contains_listed", "medication_id": med["id"],
+                        "message": f"This medicine shares an ingredient with your {med['name']} but is not the same. "
+                                   "Check with your pharmacist."}
+    return best or {"status": "not_on_list", "medication_id": None,
+                    "message": "This medicine isn't on your list. Check with your pharmacist."}

src/epills/core/safety/openfda.py

@@ -54,6 +54,7 @@ def label_warnings(rxcui=None, ingredient=None, max_chars=2000, fetch=None):
                     text = " ".join(r[name])
                     sections[name] = text[:max_chars] + ("…" if len(text) > max_chars else "")
             of = r.get("openfda", {})
+            set_id = r.get("set_id")
             return {
                 "brand_name": (of.get("brand_name") or [None])[0],
                 "generic_name": (of.get("generic_name") or [None])[0],
@@ -61,5 +62,9 @@ def label_warnings(rxcui=None, ingredient=None, max_chars=2000, fetch=None):
                 "matched_by": q.split(":")[0].replace("openfda.", ""),
                 "sections": sections,
                 "disclaimer": DISCLAIMER,
+                # for citation (the blueprint's Medication Knowledge tool): which label, from where
+                "source": "US FDA drug label (structured product labeling), via openFDA",
+                "set_id": set_id, "label_id": r.get("id"),
+                "url": f"https://dailymed.nlm.nih.gov/dailymed/lookup.cfm?setid={set_id}" if set_id else None,
             }
     return None