Nicolas: Create MCP/Reference resolution page from REFERENCE-RESOLUTION.md (via create-page on MediaWiki MCP Server)

2026-04-23T02:06:25Z

Create MCP/Reference resolution page from REFERENCE-RESOLUTION.md (via create-page on MediaWiki MCP Server)

New page

= Reference Resolution =

== Overview ==

Reference resolution transforms a natural language legal reference (or a document ID) into a query against the corpus. It is the bridge between how humans cite law and how the database stores it.

The resolver is used by:
* '''MCP <code>get</code> tool''': user asks for "article 1240 du code civil" → find the document
* '''Knowledge graph compiler''' (future): annotations reference articles by citation → resolve to corpus document IDs
* '''Edge resolution''': when <code>corpus.edges.target_id</code> is NULL, a background job resolves <code>reference</code> strings to document IDs

== TagQuery ==

The universal output of any reference parser. Jurisdiction-agnostic.

<syntaxhighlight lang="python">
@dataclass(frozen=True)
class TagQuery:
language: str # required, kw_only
kind: str | None = None
tag_filters: TagFilterSet = field(default_factory=TagFilterSet)
should_sort_in_force_first: bool = False
at_date: date | None = None
hint: str | None = None
</syntaxhighlight>

Fields:
* <code>language</code>: ISO 639-1 code, required (disambiguates language variants)
* <code>kind</code>: filter on document kind (legislation, decision, record...)
* <code>tag_filters</code>: TagFilterSet with all tag predicates (EQ, IN, NOT_IN, ILIKE, EXISTS, NOT_EXISTS, NORMALIZE)
* <code>should_sort_in_force_first</code>: order results with <code>tags.in_force=true</code> first, then by date descending
* <code>at_date</code>: temporal version selection — <code>date <= at_date AND (date_end IS NULL OR date_end > at_date)</code>
* <code>hint</code>: optional human-readable interpretation label. TagQueries '''with''' <code>hint</code> are ''candidates'' (collected from all plugins, disambiguated at MCP level); those '''without''' are ''confident matches'' (first hit wins)

== TagFilterSet ==

Unified immutable filter model. A tuple of <code>TagFilter</code> predicates, AND-combined.
Replaces the previous scattered dict params (<code>tags</code>, <code>tags_ilike</code>, <code>normalize</code>).

<syntaxhighlight lang="python">
class TagFilterOp(enum.Enum):
EQ # tags @> '{"k": "v"}' (JSONB containment)
IN # tags->>'k' = ANY(...)
NOT_IN # tags ? 'k' AND NOT (tags->>'k' = ANY(...))
ILIKE # unaccent(tags->>'k') ILIKE unaccent(pattern)
EXISTS # tags ? 'k'
NOT_EXISTS # NOT (tags ? 'k')
NORMALIZE # regexp_replace comparison (reference resolution only)

@dataclass(frozen=True)
class TagFilter:
key: str # tag key or virtual key (source/jurisdiction/language)
op: TagFilterOp
value: str | list[str] | None = None
normalize_pattern: str | None = None # only for NORMALIZE
</syntaxhighlight>

Convenience constructor: <code>TagFilterSet.from_tags({"k": "v"})</code> builds EQ filters from a dict.

== Resolution pipeline ==

<pre>
input string
|
v
1. Direct ID lookup (try as corpus.documents.id — covers all kinds in one query)
| found? → return (with CID-based version redirection if at_date is set)
v
2. Jurisdiction parser (FR, EU, GB...) → TagQuery
| parsed? → execute against store
| Note: SIREN 9-digit lookup is a detector in the FR plugin (with Luhn validation)
v
3. Disambiguation (bare article number matches multiple codes → error with suggestions)
</pre>

== TagQuery examples ==

<syntaxhighlight lang="python">
# "article 1240 du code civil"
TagQuery(language="fr", kind="legislation",
tag_filters=TagFilterSet.from_tags({"article_number": "1240", "code": "Code civil"}),
should_sort_in_force_first=True)

# "article 1147 du code civil" (version in force in 2015)
TagQuery(language="fr", kind="legislation",
tag_filters=TagFilterSet.from_tags({"article_number": "1147", "code": "Code civil"}),
at_date=date(2015, 6, 15))

# "loi n 2021-1109"
TagQuery(language="fr", kind="legislation",
tag_filters=TagFilterSet.from_tags({"nature": "LOI", "number": "2021-1109"}))

# "pourvoi 20-20.648" — case number with court filter and hint (candidate)
TagQuery(language="fr", kind="decision",
tag_filters=TagFilterSet(filters=(
TagFilter(key="case_number", op=TagFilterOp.NORMALIZE,
value="20-20.648", normalize_pattern=r"[\s.\-/]"),
TagFilter(key="court", op=TagFilterOp.EQ, value="cour_cassation"),
)),
hint="pourvoi Cour de cassation")

# "486329" — CE request number
TagQuery(language="fr", kind="decision",
tag_filters=TagFilterSet(filters=(
TagFilter(key="case_number", op=TagFilterOp.NORMALIZE,
value="486329", normalize_pattern=r"[\s.\-/]"),
TagFilter(key="court", op=TagFilterOp.EQ, value="conseil_etat"),
)),
hint="requete Conseil d'Etat")

# "21/00091" — CA/TJ RG number
TagQuery(language="fr", kind="decision",
tag_filters=TagFilterSet(filters=(
TagFilter(key="case_number", op=TagFilterOp.NORMALIZE,
value="21/00091", normalize_pattern=r"[\s.\-/]"),
TagFilter(key="court", op=TagFilterOp.IN, value=["cour_appel", "tribunal_judiciaire"]),
)),
hint="RG cour d'appel ou tribunal judiciaire")

# ECLI
TagQuery(language="fr", kind="decision",
tag_filters=TagFilterSet.from_tags({"ecli": "ECLI:FR:CCASS:2024:C100001"}))

# "IDCC 3239"
TagQuery(language="fr", kind="legislation",
tag_filters=TagFilterSet.from_tags({"idcc": "3239", "in_force": "true"}))

# UK: "section 1 of the Theft Act 1968" (ILIKE for fuzzy act title)
TagQuery(language="en", kind="legislation",
tag_filters=TagFilterSet(filters=(
TagFilter(key="section_number", op=TagFilterOp.EQ, value="1"),
TagFilter(key="act_title", op=TagFilterOp.ILIKE, value="Theft Act 1968"),
)))

# DE: "§ 823 BGB"
TagQuery(language="de", kind="legislation",
tag_filters=TagFilterSet.from_tags({"paragraph": "823", "code": "BGB"}))

# EU: "Article 101 TFEU"
TagQuery(language="en", kind="legislation",
tag_filters=TagFilterSet.from_tags({"article_number": "101", "treaty": "TFEU"}))
</syntaxhighlight>

== Store execution ==

The store translates TagQuery to SQL via the shared <code>build_tag_filter_conditions</code>
helper. Zero jurisdiction knowledge. Each TagFilterOp maps to a specific SQL pattern:

<syntaxhighlight lang="sql">
SELECT * FROM corpus.documents
WHERE language = %(language)s -- always required
AND kind = %(kind)s
AND tags @> %(eq_batch)s -- coalesced EQ filters (GIN)
AND tags->>'k' = ANY(%(in_values)s) -- IN filter
AND unaccent(tags->>'code') ILIKE unaccent(%(code_pattern)s) -- ILIKE filter
AND regexp_replace(tags->>'case_number', %(p)s, '', 'g') -- NORMALIZE filter
= regexp_replace(%(v)s, %(p)s, '', 'g')
AND date <= %(at_date)s -- temporal (if at_date)
AND (date_end IS NULL OR date_end > %(at_date)s)
ORDER BY
(tags->>'in_force')::boolean DESC NULLS LAST, -- should_sort_in_force_first
date DESC NULLS LAST
LIMIT 10;
</syntaxhighlight>

== Multi-candidate resolution ==

When a reference is ambiguous (e.g., a French case number that could match
multiple courts), the resolver returns multiple TagQuery instances, each with
a <code>hint</code> describing the interpretation. The MCP <code>get_document</code> tool:

# Collects all TagQueries from all jurisdiction plugins
# Separates '''confident''' (no hint) from '''candidates''' (with hint)
# Tries confident matches first — first hit wins (existing behavior)
# Tries all candidates against the store:
#* 1 match → returns the document with a warning noting the interpretation
#* 2+ matches → returns an error listing all candidates with IDs
#* 0 matches → falls through to "not found"

The <code>get_document</code> tool also accepts an optional <code>tags</code> parameter that merges
additional EQ filters into each TagQuery, narrowing the search (e.g.,
<code>tags={"court": "conseil_etat"}</code>).

== Jurisdiction parsers ==

Each jurisdiction plugin provides a parser that recognizes its citation formats:

{| class="wikitable"
! Plugin !! Recognizes
|-
| duralex-fr || Articles of codes, loi/decret/ordonnance by number, NOR codes, IDCC, ECLI, case numbers, BOFiP IDs, named laws
|-
| duralex-eu || CELEX numbers, ECLI, treaty articles, directive/regulation numbers
|-
| Future duralex-gb || Neutral citations ([2024] UKSC 1), Act + section, SI numbers
|-
| Future duralex-de || § + BGB/StGB/etc, Aktenzeichen, ECLI
|}

Parsers are composable: the MCP server chains all installed jurisdiction parsers. First match wins.

== Batch resolution (for knowledge graph) ==

The compiler needs to resolve millions of references. The same TagQuery mechanism is used, but with batch-friendly optimizations:
* Pre-filter by known patterns (regex on reference strings)
* Group by reference type and execute one query per group
* Cache resolved IDs in a lookup table for the duration of compilation

== Edge resolution (background job) ==

When <code>corpus.edges.target_id</code> is NULL, a background job periodically attempts resolution:

<syntaxhighlight lang="sql">
SELECT id, reference FROM corpus.edges WHERE target_id IS NULL;
-- For each: parse reference → TagQuery → execute → update target_id
UPDATE corpus.edges SET target_id = %(resolved_id)s WHERE id = %(edge_id)s;
</syntaxhighlight>

[[Category:MCP]]

MCP/Reference resolution - Revision history

Nicolas: Create MCP/Reference resolution page from REFERENCE-RESOLUTION.md (via create-page on MediaWiki MCP Server)