What JointSchema actually enforces

[antejavor]

Part of #344

Question

What does gliner2.joint_ie.schema.JointSchema actually give us, and what are its limits?

Established already (installed gliner2==2.0.0, latest on PyPI):

• JointSchema exists with .entity(name, description, *, threshold, candidate_threshold, max_candidates, allow_nested) and .relation(name, head, tail, description, *, threshold, candidate_threshold, directed, symmetric, inverse, allow_self, max_per_head, max_per_tail) plus .no_self_loops(relation=None).
• RelationSpec takes head: tuple[str, ...] and tail: tuple[str, ...] — typed domain/range.
• Sibling classes: Constraint, AcyclicRelation, MaxRelationsPerHead, MaxRelationsPerTail, NoSelfLoops, EntitySpec.
• GLiNER2Backend._extract_sync uses none of this — it calls model.create_schema() (returns gliner2.inference.schema.Schema), whose .relations() always writes {"head": "", "tail": ""}.

Open, and everything else on this map leans on the answers:

1. Entry point. AutoExtractor.extract(text, schema: Union[SchemaAPI, Dict]) — does a JointSchema satisfy that union directly, or does it need .build()/to_dict() first, or a different call entirely (gliner2.joint_ie.engine)?
2. Long text. Does it compose with extract_long()'s windowing? This is not optional — unstructured2graph: GLiNER2Backend's single-pass extract() silently undercounts entities on long text (and is much slower than extract_long()) #336/unstructured2graph: GLiNER2Backend uses extract_long(), not extract() (#336) #338 made extract_long() mandatory because session texts blow the context window, and the blog claims spans are remapped to original-document offsets across chunks. Confirm whether constraints hold across window boundaries or only within one window.
3. Output shape. What do relations look like coming back? Still the {"entities": ..., "relation_extraction": ...} per-key shape _extract_sync parses today, or something else? Do include_spans / include_confidence still work?
4. Real enforcement vs post-filtering. Are max_per_head / no_self_loops / head-tail typing genuinely applied during beam-search decoding (as the write-up claims — "invalid combinations are never admitted into the search"), or applied as a filter afterwards? This matters directly: if it is post-filtering, the "valid by construction" argument for extraction-time constraints collapses and the constraint-model decision changes.
5. Unconstrained relations. What happens when head/tail are empty or omitted? The plan's backward-compat rule is that start_labels=()/end_labels=() means unconstrained, never a validation failure — check this is expressible.
6. Entity-schema coupling. The current code observed a located_in relation whose head/tail spans the entities pass never surfaced, and aingest_chunk skips-and-logs those. Does JointSchema make relation endpoints guaranteed-present in the entity output (the blog implies relations only reference entities that exist)? If so, the skip-and-log path may become dead code.

How to answer

Primary sources only: read the installed package source under .venv/lib/python3.11/site-packages/gliner2/joint_ie/ (schema.py, compiler.py, engine.py) and api_client.py, plus the upstream repo https://github.com/fastino-ai/GLiNER2 and https://fastino.ai/blog/gliner2-5-span-free-information-extraction. Where source reading is ambiguous, run it — the model checkpoint fastino/gliner2.5-base-v1 is already downloaded.

Environment note: gliner2 is a manual install that conflicts with the workspace's transformers>=5.0.0rc3 floor, and a bare uv run silently re-syncs the venv and clobbers it. Use uv run --no-sync, and if imports break, reinstall with uv run --no-sync python -m pip install 'gliner2[local]>=2.0.0'.

[antejavor]

Investigated against primary sources (gliner2==2.0.0 source on disk, fastino/gliner2.5-base-v1 run live, upstream tutorial/15-joint_ie.md). Full write-up with per-claim file:line and command output:

branch research/gliner2-jointschema, file unstructured2graph/docs/research/gliner2-jointschema.md

Short answers:

1. Entry point — a JointSchema does not satisfy AutoExtractor.extract(). It raises AttributeError there, and .to_dict() into the legacy runtime silently returns {}. The real path is gliner2.joint_ie.JointIEEngine (alias JointIE), which wraps an already-loaded model: JointIE.from_pretrained(...).extract(text, schema, config=JointIEConfig(...)). A plain dict is rejected — JointSchema only.
2. Long text — extract_long() exists and composes (note: include_spans/include_confidence move into JointIEConfig and are no longer kwargs). But constraints hold within one window only. Cross-window relations are never synthesized (long_text.py:51-56, and upstream says so), and the merge does no global re-check — demonstrated with a real-model run where extract_long emits the same span as city, company and person, violating the default EntityOverlapPolicy(disallow) that extract() never violates.
3. Output shape — different. A JointResult: flat entities list with the type as a field, relations whose head/tail are entity ids ("e1") not span dicts, each with its own confidence. The whole span/text re-matching apparatus in _extract_sync goes away. include_spans/include_confidence still work, as serialisation flags.
4. Real enforcement — yes, confirmed, and stronger than the blog claims. Head/tail typing and allow_self are enforced before scoring, inside the boundary pair generator: with a deliberately mistyped relation, only the declared type pair is ever scored; with allow_self=False, 0 of 16 candidates are self-pairs vs 8 of 24 with allow_self=True. Cardinality constraints are applied during beam expansion — instrumenting allow_edge gives 26 rejections during beam search, 0 at final validation under max_per_head=1, and the result stays feasible=True (a post-filter would have produced the mirror image, or an empty feasible=False fallback). Caveat: constraints govern the edge set, not node membership — blocking an edge does not remove its endpoints from the entity output. Also note constraints.py's own module docstring says "Post-decoding constraints", which is misleading; the call sites say otherwise.
5. Unconstrained relations — NOT expressible as empty. head/tail are required positional args, and "", (), None and omission each raise. The backward-compat rule ("start_labels=() means unconstrained, never a validation failure") has to be translated on our side to "all declared entity types", which does work — at quadratic candidate cost (3 types -> 36 edge candidates vs 4 for one typed pair). Upstream's own answer is to fall back to the legacy extract_relations API for truly unconstrained tuples.
6. Entity coupling — guaranteed. Relation endpoints are force-scored as entity mentions and bypass the entity threshold/caps, with hard invariants at four layers. The exact located_in townhouse/Brookside case now returns both endpoints as entities. The head_id is None or tail_id is None skip-and-log branch in aingest_chunk becomes dead code.

Two things I could not determine, flagged in the doc: (a) whether re-running the optimizer over a merged multi-window graph is practical as a post-pass — the machinery looks reusable but Constraint.apply has zero call sites in the package; (b) whether the span (non-boundary) architecture behaves identically — on that path UniqueRelationSlot would cap relations per type per window at count_top_k (default 2), but I did not verify on a span checkpoint.

Leaving this open for verification.

[antejavor]

Resolution — verified

Findings independently spot-checked against the library source and by running it. All four high-stakes claims hold.

1. Entry point — a different call path, not extract(). Confirmed by running it:

from gliner2.joint_ie import JointIE, JointIEConfig
joint = JointIE.from_pretrained("fastino/gliner2.5-base-v1")   # or JointIEEngine(existing_model)
s = (joint.create_schema()
     .entity("Person").entity("Organization")
     .relation("works_for", ("Person",), ("Organization",)))
r = joint.extract(text, s, config=JointIEConfig(include_spans=True, include_confidence=True))

Returns JointResult. include_spans/include_confidence move into JointIEConfig — passing them as kwargs raises. Note compile_schema(s).build() appears to work but compiler.py:26-28 rebuilds the model-facing schema as {"head": "", "tail": ""}, silently dropping all typing — i.e. it degrades to exactly today's behaviour. Easy trap.

2. Constraints are enforced during decoding — verified. allow_edge is called at joint_ie/optimizers/beam.py:67, inside the beam-expansion loop, before the state is appended to the beam (same at optimizers/greedy.py:46). Typing is enforced even earlier, at candidate construction: joint_ie/scoring.py:621-647 only ever builds an edge candidate for head_type ∈ spec.head × tail_type ∈ spec.tail. This is not post-filtering. (Cited path in the report was joint_ie/beam.py; actual is joint_ie/optimizers/beam.py.)

3. Cross-window relations are never produced — verified verbatim. joint_ie/long_text.py carries the explicit comment: "Both IDs must originate in this same chunk result. This explicit lookup is what prevents accidental cross-window edge creation." Any relation whose endpoints land in different windows is silently dropped, and the merge never re-checks constraints — so valid-by-construction holds per window only, and the merged document-level result can violate the very constraints declared.

4. "Unconstrained" is not expressible — verified. All five forms raise:

form	result
omitted	TypeError: missing 2 required positional arguments
""	ValueError: relation head contains an invalid entity type
()	ValueError: relation head must contain at least one entity type
None	TypeError: 'NoneType' object is not iterable
undeclared type	ValueError: references unknown entity types

Every compiled schema also carries EntityOverlapPolicy, TypedEndpoints, NoSelfLoops, UniqueRelationPair, UniqueRelationSlot by default — confirmed. Consequence for the plan: its backward-compat rule that start_labels=() means "unconstrained, never a validation failure" cannot pass through to JointSchema. Our adapter must translate empty → all declared entity types, which costs quadratically at candidate time.

Additional finding, from verification rather than the research. Mention-level duplication happens within a single extraction, not just across chunks. On "Ante Javor works for Memgraph. Memgraph is based in Zagreb.":

e2  Organization  'Memgraph'
e3  Organization  'Memgraph'
works_for   e1 -> e2      located_in  e2 -> e4
works_for   e1 -> e3      located_in  e3 -> e4

Two mentions of one organisation become two entities and duplicate every edge. This makes the identity problem materially worse than #346 states — carried over to that ticket.

Full write-up: unstructured2graph/docs/research/gliner2-jointschema.md on branch research/gliner2-jointschema.

Carried as inconclusive: whether a post-merge constraint re-pass is practical (Constraint.apply has zero call sites in the package — untested surface); span-vs-boundary architecture differences (all findings are on the boundary path, which is what our checkpoint uses); and quality impact, which is what #350 exists to judge.

[antejavor]

The research note is now on the remote, so the reference above is live:
unstructured2graph/docs/research/gliner2-jointschema.md (branch research/gliner2-jointschema, commit a9f0055).

Same convention as the benchmark survey the eval README links off research/memory-benchmarks — a research branch, no PR.

It was local-only until now, which is worth flagging because #347, #348 and #352 all cite its findings, and #350's brief depends on them.