lpgcast 0.1.1__py3-none-any.whl

lpgcast/__init__.py

@@ -0,0 +1,77 @@
+"""LPGCast: text to a labeled property graph, against a governed GraFlo schema.
+
+The names below load on first use, so ``import lpgcast`` stays light.
+"""
+
+from __future__ import annotations
+
+import importlib
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
+try:
+    __version__ = version("lpgcast")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0"
+
+if TYPE_CHECKING:
+    from lpgcast.cast import CastResult, EpisodeResult, LPGCaster
+    from lpgcast.config import CacheSettings, LLMSettings, LPGCastSettings
+    from lpgcast.episode import Episode, read_episodes
+    from lpgcast.ground import Grounding
+    from lpgcast.output import save_cast
+    from lpgcast.schema_io import load_schema
+    from lpgcast.sink import JsonlQuarantineSink, MemoryQuarantineSink
+    from lpgcast.write import WriteReport, load_connection, write_cast
+
+_EXPORTS: dict[str, str] = {
+    "CacheSettings": "lpgcast.config",
+    "CastResult": "lpgcast.cast",
+    "Episode": "lpgcast.episode",
+    "EpisodeResult": "lpgcast.cast",
+    "Grounding": "lpgcast.ground",
+    "JsonlQuarantineSink": "lpgcast.sink",
+    "LLMSettings": "lpgcast.config",
+    "LPGCastSettings": "lpgcast.config",
+    "LPGCaster": "lpgcast.cast",
+    "MemoryQuarantineSink": "lpgcast.sink",
+    "WriteReport": "lpgcast.write",
+    "load_connection": "lpgcast.write",
+    "load_schema": "lpgcast.schema_io",
+    "read_episodes": "lpgcast.episode",
+    "save_cast": "lpgcast.output",
+    "write_cast": "lpgcast.write",
+}
+
+__all__ = [
+    "CacheSettings",
+    "CastResult",
+    "Episode",
+    "EpisodeResult",
+    "Grounding",
+    "JsonlQuarantineSink",
+    "LLMSettings",
+    "LPGCastSettings",
+    "LPGCaster",
+    "MemoryQuarantineSink",
+    "WriteReport",
+    "__version__",
+    "load_connection",
+    "load_schema",
+    "read_episodes",
+    "save_cast",
+    "write_cast",
+]
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module 'lpgcast' has no attribute {name!r}")
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

lpgcast/bench/README.md

@@ -0,0 +1,12 @@
+# Benchmark corpus
+
+The cases and schemas `lpgcast-bench` scores against. How the benchmark works, what it
+measures and how to run it: the [benchmark guide](https://growgraph.github.io/LPGCast/guides/benchmark/)
+(`docs/guides/benchmark.md` in this repository).
+
+## Adding a case
+
+Write `case.yaml`, `episodes.jsonl` and `expected.yaml` under `cases/<family>/<instance>/`, add
+the case to `cases/SPLITS.yaml`, run `uv run pytest test/test_bench.py`, and set
+`CORPUS_DIGEST` in `corpus.py` to the value the failing digest test prints, with a new
+`CORPUS_VERSION`.

lpgcast/bench/__init__.py

@@ -0,0 +1,2 @@
+"""The benchmark: a corpus of texts with the graphs they state, a scorer that
+needs no model as judge, and the ``lpgcast-bench`` command."""

lpgcast/bench/cases/SPLITS.yaml

@@ -0,0 +1,38 @@
+# Dev / test assignment: two instances of every family in each half.
+#
+# Tuning prompts, rules or selection against a case makes it part of what the
+# system was fitted to, so tuning happens on `dev` and a published figure comes
+# from `test`. Domains rotate across families, so each half holds every domain.
+# Moving a case between halves invalidates comparison with earlier runs, like
+# editing it: bump CORPUS_VERSION.
+
+dev:
+-   distractors/plant
+-   distractors/helpdesk
+-   direction/helpdesk
+-   direction/logistics
+-   units/logistics
+-   units/lab
+-   identity/lab
+-   identity/plant
+-   mention/plant
+-   mention/logistics
+-   recast/helpdesk
+-   recast/lab
+-   injection/plant
+-   injection/lab
+test:
+-   distractors/logistics
+-   distractors/lab
+-   direction/lab
+-   direction/plant
+-   units/plant
+-   units/helpdesk
+-   identity/helpdesk
+-   identity/logistics
+-   mention/helpdesk
+-   mention/lab
+-   recast/plant
+-   recast/logistics
+-   injection/helpdesk
+-   injection/logistics

lpgcast/bench/cases/direction/helpdesk/case.yaml

@@ -0,0 +1,2 @@
+description: Duplicate and mentoring relations stated from the far end.
+schema: helpdesk

lpgcast/bench/cases/direction/helpdesk/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "direction-helpdesk-1", "text": "HD-2210 was closed as a duplicate; the original report is HD-2198."}
+{"source_id": "direction-helpdesk-2", "text": "New agent kim.n is being mentored by raj.p for the first month."}

lpgcast/bench/cases/direction/helpdesk/expected.yaml

@@ -0,0 +1,38 @@
+direction-helpdesk-1:
+    vertices:
+        dup:
+            type: Ticket
+            quote: HD-2210
+            mention: true
+            props:
+                number: HD-2210
+        orig:
+            type: Ticket
+            quote: HD-2198
+            mention: true
+            props:
+                number: HD-2198
+    edges:
+    -   relation: DUPLICATE_OF
+        from: dup
+        to: orig
+        quote: HD-2210 was closed as a duplicate; the original report is HD-2198
+direction-helpdesk-2:
+    vertices:
+        kim:
+            type: Agent
+            quote: kim.n
+            mention: true
+            props:
+                handle: kim.n
+        raj:
+            type: Agent
+            quote: raj.p
+            mention: true
+            props:
+                handle: raj.p
+    edges:
+    -   relation: MENTORS
+        from: raj
+        to: kim
+        quote: kim.n is being mentored by raj.p

lpgcast/bench/cases/direction/lab/case.yaml

@@ -0,0 +1,2 @@
+description: Aliquots derived from a parent, written parent first.
+schema: lab

lpgcast/bench/cases/direction/lab/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "direction-lab-1", "text": "Aliquot S-0107 was split from parent sample S-0100."}
+{"source_id": "direction-lab-2", "text": "Specimen S-0212 is the source of aliquots S-0213 and S-0214."}

lpgcast/bench/cases/direction/lab/expected.yaml

@@ -0,0 +1,48 @@
+direction-lab-1:
+    vertices:
+        child:
+            type: Sample
+            quote: Aliquot S-0107
+            mention: true
+            props:
+                sample_id: S-0107
+        parent:
+            type: Sample
+            quote: sample S-0100
+            mention: true
+            props:
+                sample_id: S-0100
+    edges:
+    -   relation: DERIVED_FROM
+        from: child
+        to: parent
+        quote: Aliquot S-0107 was split from parent sample S-0100
+direction-lab-2:
+    vertices:
+        src:
+            type: Sample
+            quote: Specimen S-0212
+            mention: true
+            props:
+                sample_id: S-0212
+        a:
+            type: Sample
+            quote: S-0213
+            mention: true
+            props:
+                sample_id: S-0213
+        b:
+            type: Sample
+            quote: S-0214
+            mention: true
+            props:
+                sample_id: S-0214
+    edges:
+    -   relation: DERIVED_FROM
+        from: a
+        to: src
+        quote: Specimen S-0212 is the source of aliquots S-0213
+    -   relation: DERIVED_FROM
+        from: b
+        to: src
+        quote: Specimen S-0212 is the source of aliquots S-0213 and S-0214

lpgcast/bench/cases/direction/logistics/case.yaml

@@ -0,0 +1,2 @@
+description: Supply between depots and loading written with the container first.
+schema: logistics

lpgcast/bench/cases/direction/logistics/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "direction-logistics-1", "text": "Depot HAM-1 is restocked from depot BRE-2, with a lead time of 3 days."}
+{"source_id": "direction-logistics-2", "text": "Shipment TRK-5501 contains pallet PL-77."}

lpgcast/bench/cases/direction/logistics/expected.yaml

@@ -0,0 +1,41 @@
+direction-logistics-1:
+    vertices:
+        ham:
+            type: Warehouse
+            quote: Depot HAM-1
+            mention: true
+            props:
+                code: HAM-1
+        bre:
+            type: Warehouse
+            quote: depot BRE-2
+            mention: true
+            props:
+                code: BRE-2
+    edges:
+    -   relation: SUPPLIES
+        from: bre
+        to: ham
+        quote: Depot HAM-1 is restocked from depot BRE-2
+        props:
+            lead_days:
+                value: 3
+                quote: 3 days
+direction-logistics-2:
+    vertices:
+        trk:
+            type: Shipment
+            quote: Shipment TRK-5501
+            mention: true
+            props:
+                tracking: TRK-5501
+        pl:
+            type: Pallet
+            quote: pallet PL-77
+            props:
+                barcode: PL-77
+    edges:
+    -   relation: LOADED_IN
+        from: pl
+        to: trk
+        quote: Shipment TRK-5501 contains pallet PL-77

lpgcast/bench/cases/direction/plant/case.yaml

@@ -0,0 +1,2 @@
+description: Same-type relations written in the passive or from the target's side.
+schema: plant

lpgcast/bench/cases/direction/plant/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "direction-plant-1", "text": "Press P-2 is fed by press P-1 since the line was rebuilt."}
+{"source_id": "direction-plant-2", "text": "Mara Lind (mara.lind@plant.example) is supervised by Tom Berg (tom.berg@plant.example) on the night shift."}

lpgcast/bench/cases/direction/plant/expected.yaml

@@ -0,0 +1,38 @@
+direction-plant-1:
+    vertices:
+        p1:
+            type: Machine
+            quote: press P-1
+            mention: true
+            props:
+                serial: P-1
+        p2:
+            type: Machine
+            quote: Press P-2
+            mention: true
+            props:
+                serial: P-2
+    edges:
+    -   relation: FEEDS
+        from: p1
+        to: p2
+        quote: Press P-2 is fed by press P-1
+direction-plant-2:
+    vertices:
+        mara:
+            type: Person
+            quote: Mara Lind
+            props:
+                email: mara.lind@plant.example
+                name: Mara Lind
+        tom:
+            type: Person
+            quote: Tom Berg
+            props:
+                email: tom.berg@plant.example
+                name: Tom Berg
+    edges:
+    -   relation: SUPERVISES
+        from: tom
+        to: mara
+        quote: is supervised by Tom Berg

lpgcast/bench/cases/distractors/helpdesk/case.yaml

@@ -0,0 +1,6 @@
+description: A wide schema sliced under a tight budget; the text names types it says nothing about.
+schema:
+-   helpdesk
+-   helpdesk-distractors
+settings:
+    slice_max_elements: 14

lpgcast/bench/cases/distractors/helpdesk/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "distractors-helpdesk-1", "text": "Not a billing question and no refund needed: customer ACC-4100 raised HD-8100 about product SKU-310."}
+{"source_id": "distractors-helpdesk-2", "text": "Whatever the subscription plan, agent sam.r has handled HD-8100 since 2024-07-01."}

lpgcast/bench/cases/distractors/helpdesk/expected.yaml

@@ -0,0 +1,50 @@
+distractors-helpdesk-1:
+    vertices:
+        c:
+            type: Customer
+            quote: customer ACC-4100
+            mention: true
+            props:
+                account: ACC-4100
+        t:
+            type: Ticket
+            quote: HD-8100
+            mention: true
+            props:
+                number: HD-8100
+        p:
+            type: Product
+            quote: product SKU-310
+            mention: true
+            props:
+                sku: SKU-310
+    edges:
+    -   relation: RAISED
+        from: c
+        to: t
+        quote: customer ACC-4100 raised HD-8100
+    -   relation: ABOUT
+        from: t
+        to: p
+        quote: HD-8100 about product SKU-310
+distractors-helpdesk-2:
+    vertices:
+        a:
+            type: Agent
+            quote: agent sam.r
+            mention: true
+            props:
+                handle: sam.r
+        t:
+            type: Ticket
+            quote: HD-8100
+            mention: true
+            props:
+                number: HD-8100
+    edges:
+    -   relation: HANDLES
+        from: a
+        to: t
+        quote: agent sam.r has handled HD-8100 since 2024-07-01
+        props:
+            since: '2024-07-01'

lpgcast/bench/cases/distractors/lab/case.yaml

@@ -0,0 +1,6 @@
+description: A wide schema sliced under a tight budget; the text names types it says nothing about.
+schema:
+-   lab
+-   lab-distractors
+settings:
+    slice_max_elements: 14

lpgcast/bench/cases/distractors/lab/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "distractors-lab-1", "text": "No new protocol or grant here: sample S-0800 belongs to project PX-40."}
+{"source_id": "distractors-lab-2", "text": "From the usual supplier's lot: sample S-0800 contains acetone (CAS 67-64-1) at 2 mM."}

lpgcast/bench/cases/distractors/lab/expected.yaml

@@ -0,0 +1,42 @@
+distractors-lab-1:
+    vertices:
+        s:
+            type: Sample
+            quote: sample S-0800
+            mention: true
+            props:
+                sample_id: S-0800
+        p:
+            type: Project
+            quote: project PX-40
+            mention: true
+            props:
+                code: PX-40
+    edges:
+    -   relation: BELONGS_TO
+        from: s
+        to: p
+        quote: sample S-0800 belongs to project PX-40
+distractors-lab-2:
+    vertices:
+        s:
+            type: Sample
+            quote: sample S-0800
+            mention: true
+            props:
+                sample_id: S-0800
+        r:
+            type: Reagent
+            quote: acetone
+            props:
+                cas: 67-64-1
+                name: acetone
+    edges:
+    -   relation: CONTAINS
+        from: s
+        to: r
+        quote: sample S-0800 contains acetone (CAS 67-64-1) at 2 mM
+        props:
+            concentration:
+                value: 2.0
+                quote: 2 mM

lpgcast/bench/cases/distractors/logistics/case.yaml

@@ -0,0 +1,6 @@
+description: A wide schema sliced under a tight budget; the text names types it says nothing about.
+schema:
+-   logistics
+-   logistics-distractors
+settings:
+    slice_max_elements: 14

lpgcast/bench/cases/distractors/logistics/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "distractors-logistics-1", "text": "Forget the container and the customs paperwork: shipment TRK-9100 left depot HAM-2, carried by NordFreight."}
+{"source_id": "distractors-logistics-2", "text": "Not from the usual truck crew: Lea Ott, licence DL-7781, drives for NordFreight."}

lpgcast/bench/cases/distractors/logistics/expected.yaml

@@ -0,0 +1,48 @@
+distractors-logistics-1:
+    vertices:
+        s:
+            type: Shipment
+            quote: shipment TRK-9100
+            mention: true
+            props:
+                tracking: TRK-9100
+        w:
+            type: Warehouse
+            quote: depot HAM-2
+            mention: true
+            props:
+                code: HAM-2
+        c:
+            type: Carrier
+            quote: NordFreight
+            mention: true
+            props:
+                name: NordFreight
+    edges:
+    -   relation: SHIPPED_FROM
+        from: s
+        to: w
+        quote: shipment TRK-9100 left depot HAM-2
+    -   relation: CARRIED_BY
+        from: s
+        to: c
+        quote: carried by NordFreight
+distractors-logistics-2:
+    vertices:
+        d:
+            type: Driver
+            quote: Lea Ott
+            props:
+                license: DL-7781
+                name: Lea Ott
+        c:
+            type: Carrier
+            quote: NordFreight
+            mention: true
+            props:
+                name: NordFreight
+    edges:
+    -   relation: DRIVES_FOR
+        from: d
+        to: c
+        quote: Lea Ott, licence DL-7781, drives for NordFreight

lpgcast/bench/cases/distractors/plant/case.yaml

@@ -0,0 +1,6 @@
+description: A wide schema sliced under a tight budget; the text names types it says nothing about.
+schema:
+-   plant
+-   plant-distractors
+settings:
+    slice_max_elements: 14

lpgcast/bench/cases/distractors/plant/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "distractors-plant-1", "text": "The forklift crew complained, but press S-60 is fine: Ana Ruiz (ana.ruiz@plant.example) has operated it since January 2023."}
+{"source_id": "distractors-plant-2", "text": "Supplier invoices aside, sensor PT-4 is mounted on press S-61."}

lpgcast/bench/cases/distractors/plant/expected.yaml

@@ -0,0 +1,41 @@
+distractors-plant-1:
+    vertices:
+        s:
+            type: Machine
+            quote: press S-60
+            mention: true
+            props:
+                serial: S-60
+        ana:
+            type: Person
+            quote: Ana Ruiz
+            props:
+                email: ana.ruiz@plant.example
+                name: Ana Ruiz
+    edges:
+    -   relation: OPERATES
+        from: ana
+        to: s
+        quote: Ana Ruiz (ana.ruiz@plant.example) has operated it since January 2023
+        props:
+            since:
+                value: 2023-01
+                quote: January 2023
+distractors-plant-2:
+    vertices:
+        t:
+            type: Sensor
+            quote: sensor PT-4
+            props:
+                tag: PT-4
+        s:
+            type: Machine
+            quote: press S-61
+            mention: true
+            props:
+                serial: S-61
+    edges:
+    -   relation: MOUNTED_ON
+        from: t
+        to: s
+        quote: sensor PT-4 is mounted on press S-61

lpgcast/bench/cases/identity/helpdesk/case.yaml

@@ -0,0 +1,2 @@
+description: A caller with no account, beside a customer who gives one.
+schema: helpdesk

lpgcast/bench/cases/identity/helpdesk/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "identity-helpdesk-1", "text": "A caller who gave no account number reported that exports keep failing; this is ticket HD-4410."}
+{"source_id": "identity-helpdesk-2", "text": "Customer ACC-2291 (Jo Park) raised HD-4411, and agent lena.k handles it."}

lpgcast/bench/cases/identity/helpdesk/expected.yaml

@@ -0,0 +1,36 @@
+identity-helpdesk-1:
+    vertices:
+        t:
+            type: Ticket
+            quote: ticket HD-4410
+            props:
+                number: HD-4410
+identity-helpdesk-2:
+    vertices:
+        c:
+            type: Customer
+            quote: Customer ACC-2291
+            props:
+                account: ACC-2291
+                name: Jo Park
+        t:
+            type: Ticket
+            quote: HD-4411
+            mention: true
+            props:
+                number: HD-4411
+        a:
+            type: Agent
+            quote: agent lena.k
+            mention: true
+            props:
+                handle: lena.k
+    edges:
+    -   relation: RAISED
+        from: c
+        to: t
+        quote: Customer ACC-2291 (Jo Park) raised HD-4411
+    -   relation: HANDLES
+        from: a
+        to: t
+        quote: agent lena.k handles it

lpgcast/bench/cases/identity/lab/case.yaml

@@ -0,0 +1,2 @@
+description: A researcher known only by badge can be pointed at, never written.
+schema: lab

lpgcast/bench/cases/identity/lab/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "identity-lab-1", "text": "Sample S-0441 was handed in by a student whose badge was not recorded."}
+{"source_id": "identity-lab-2", "text": "The researcher with badge B-1182 ran sample S-0441 on spectrometer SP-9."}

lpgcast/bench/cases/identity/lab/expected.yaml

@@ -0,0 +1,43 @@
+identity-lab-1:
+    vertices:
+        s:
+            type: Sample
+            quote: Sample S-0441
+            props:
+                sample_id: S-0441
+identity-lab-2:
+    vertices:
+        r:
+            type: Researcher
+            quote: The researcher with badge B-1182
+            mention: true
+            props:
+                badge: B-1182
+        run:
+            type: Run
+            quote: ran sample S-0441 on spectrometer SP-9
+        s:
+            type: Sample
+            quote: sample S-0441
+            mention: true
+            props:
+                sample_id: S-0441
+        i:
+            type: Instrument
+            quote: spectrometer SP-9
+            mention: true
+            props:
+                serial: SP-9
+    edges:
+    -   relation: PERFORMED
+        from: r
+        to: run
+        quote: The researcher with badge B-1182 ran
+    -   relation: ANALYSED
+        from: run
+        to: s
+        quote: ran sample S-0441
+    -   relation: USED
+        from: run
+        to: i
+        quote: on spectrometer SP-9

lpgcast/bench/cases/identity/logistics/case.yaml

@@ -0,0 +1,2 @@
+description: An unnamed driver beside one whose licence is stated.
+schema: logistics

lpgcast/bench/cases/identity/logistics/episodes.jsonl

@@ -0,0 +1,2 @@
+{"source_id": "identity-logistics-1", "text": "A driver dropped shipment TRK-9001 off at depot OSL-3."}
+{"source_id": "identity-logistics-2", "text": "Per Ek, licence DL-55871, phone +46 70 123 45, drives for NordFreight."}