Add support for global rules

.claude/skills/optimize-element-descriptions/SKILL.md

@@ -2,8 +2,7 @@
 name: optimize-element-descriptions
 description: Iteratively improve TEIElement descriptions in _build_schema() to maximise F1 against the gold standard. Use when annotation quality is low or when evaluation shows missed or spurious spans.
 disable-model-invocation: true
-argument-hint: [--max-items N] [--provider gemini|kisski|all]
-allowed-tools: Read, Edit, Bash
+argument-hint: "--max-items N --provider gemini|kisski|all"
 ---
 
 # optimize-element-descriptions
@@ -59,6 +58,7 @@ Key principles (summary):
 - Add negative constraints: "never tag X as Y"
 - Include textual triggers (keywords, position) and inline surface-form examples
 - Prefix critical constraints with `CRITICAL:`
+- If a failure pattern affects **multiple element types**, add the constraint to `TEISchema.rules` instead of duplicating it in each element description — the prompt renders `rules` as a numbered "General Rules" section before all element descriptions.
 
 Only edit descriptions for elements where you identified a clear failure pattern.
 

README.md

@@ -100,7 +100,7 @@ API keys for real LLM endpoints go in `.env` (see `.env` for the expected variab
 
 ## Quick example
 
-Element descriptions are the primary signal the LLM uses to decide what to annotate and how. See [docs/tei-element-descriptions.md](docs/tei-element-descriptions.md) for guidelines on writing effective descriptions (span framing, multiplicity, parent–child span pairs, negative constraints, and more).
+Element descriptions are the primary signal the LLM uses to decide what to annotate and how. Cross-element constraints that apply to multiple span types (e.g. "always emit a `surname` span inside an enclosing `author` span") can be placed in `TEISchema.rules` instead of duplicating them in every element description — the prompt builder renders them as a numbered "General Rules" section before the per-element descriptions. See [docs/tei-element-descriptions.md](docs/tei-element-descriptions.md) for full guidelines.
 
 ```python
 from tei_annotator import (
@@ -110,18 +110,24 @@ from tei_annotator import (
 )
 
 # 1. Describe the elements you want to annotate
-schema = TEISchema(elements=[
-    TEIElement(
-        tag="persName",
-        description="a person's name",
-        attributes=[TEIAttribute(name="ref", description="authority URI")],
-    ),
-    TEIElement(
-        tag="placeName",
-        description="a geographical place name",
-        attributes=[],
-    ),
-])
+schema = TEISchema(
+    rules=[
+        # Cross-element constraints stated once, rendered before element descriptions
+        "Emit a 'surname' span within every enclosing 'persName' span.",
+    ],
+    elements=[
+        TEIElement(
+            tag="persName",
+            description="a person's name",
+            attributes=[TEIAttribute(name="ref", description="authority URI")],
+        ),
+        TEIElement(
+            tag="placeName",
+            description="a geographical place name",
+            attributes=[],
+        ),
+    ],
+)
 
 # 2. Wrap your inference endpoint
 def my_call_fn(prompt: str) -> str:

docs/tei-element-descriptions.md

@@ -14,10 +14,10 @@ The LLM is asked to **emit spans** — tuples of *(element name, verbatim text,
 surrounding context)*.  It never writes raw XML.  Descriptions therefore should
 be phrased in terms of *emitting a span*, not *wrapping text in a tag*.
 
-| Avoid | Prefer |
-|-------|--------|
-| "Wrap the author name in `<author>`." | "Emit an `author` span covering the full name text." |
-| "Nest `<surname>` inside `<author>`." | "The `surname` span must fall within the enclosing `author` span's text." |
+| Avoid                                   | Prefer                                                                    |
+| --------------------------------------- | ------------------------------------------------------------------------- |
+| "Wrap the author name in `<author>`."   | "Emit an `author` span covering the full name text."                      |
+| "Nest `<surname>` inside `<author>`."   | "The `surname` span must fall within the enclosing `author` span's text." |
 
 ---
 
@@ -80,10 +80,10 @@ Examples of effective negative constraints:
 
 > "A person's name (or surname alone) that follows 'in' is an editor — emit an
 > `editor` span, **never** a `title` span."
-
+>
 > "An institutional report name (e.g. 'Amok Internal Report') must be tagged as
 > `note` with type='report', **NOT** as `orgName` or `title`."
-
+>
 > "A label is always a number or short code — **never** a word or name.  An
 > ALL-CAPS word at the start of an entry is an author surname, not a label."
 
@@ -101,10 +101,10 @@ span represents semantically.
 
 > "An editor's name typically follows keywords such as 'in', 'ed.', 'éd.',
 > 'Hrsg.', 'dir.', '(ed.)', '(eds.)'."
-
+>
 > "A label appears at the very start of a bibliographic entry, before any author
 > or title."
-
+>
 > "The place of publication may appear in parentheses immediately after the
 > title, e.g. 'Title (City, Region)' — the parenthesised location is the
 > pubPlace."
@@ -119,7 +119,7 @@ text looks like:
 > "Typical label forms: a plain number ('17'), a number with a trailing period
 > ('17.'), a number in square brackets ('[77]', '[ACL30]'), or a compound number
 > ('5,6')."
-
+>
 > "Institutional report designations — such as 'Amok Internal Report', 'USGS
 > Open-File Report 97-123', or 'Technical Report No. 5' — must be tagged as
 > `note`."
@@ -133,11 +133,54 @@ when surrounding punctuation could reasonably be included:
 
 > "The separator that follows the label (period, dash, or space) is NOT part of
 > the label."
-
+>
 > "Do not include the surrounding parentheses in the pubPlace span."
 
 ---
 
+### 8. Use `TEISchema.rules` for cross-element constraints
+
+When the same constraint applies to **multiple element types**, put it in
+`TEISchema.rules` rather than copying it into every element description.
+The prompt builder renders `rules` as a numbered **"General Rules"** section
+that appears before all per-element descriptions.
+
+Good candidates for `rules`:
+
+- Parent–child pairing constraints shared by several elements (e.g. "`surname`
+  and `forename` must always appear inside an enclosing `author` or `editor`
+  span")
+- Constraints that span the same surface form from both sides (e.g. the rule
+  that `orgName` requires a sibling `author`/`editor` span, stated for both
+  `author` and `orgName`)
+- Bibliographic conventions that apply across multiple roles (e.g. "a dash or
+  underscore may stand for a repeated author **or editor** name")
+
+Keep the individual element `description` focused on element-specific cues
+(triggers, surface forms, boundaries, negative constraints) and let `rules`
+carry the shared structural invariants.
+
+**Example** — in `_build_schema()`:
+
+```python
+TEISchema(
+    rules=[
+        "For each person's name, emit an 'author' or 'editor' span covering "
+        "the full name AND separate 'surname', 'forename', or 'orgName' spans "
+        "for the individual name parts within that span.",
+        "Never emit 'surname', 'forename', or 'orgName' without a corresponding "
+        "enclosing 'author' or 'editor' span.",
+    ],
+    elements=[
+        TEIElement(tag="author", description="Names appearing at the start …"),
+        TEIElement(tag="surname", description="The inherited (family) name …"),
+        # 'surname' description no longer repeats the parent-span constraint
+    ],
+)
+```
+
+---
+
 ## Quick checklist
 
 Before finalising a description, ask:
@@ -149,3 +192,4 @@ Before finalising a description, ask:
 - [ ] Are there positional or keyword triggers that help the model find the span?
 - [ ] Are edge-case surface forms illustrated with a quoted example?
 - [ ] Are span boundaries (what's in / what's out) unambiguous?
+- [ ] Are cross-element constraints factored into `TEISchema.rules` rather than duplicated across descriptions?

scripts/evaluate_llm.py

@@ -137,6 +137,19 @@ def _build_schema():
         return TEIAttribute(name=name, description=desc, allowed_values=allowed)
 
     return TEISchema(
+        rules=[
+            "For each person's name, emit an 'author' or 'editor' span covering the full name "
+            "AND separate 'surname', 'forename', or 'orgName' spans for the individual name "
+            "parts within that span.",
+            "Never emit 'surname', 'forename', or 'orgName' without a corresponding enclosing "
+            "'author' or 'editor' span.",
+            "When an organisation acts as author or editor, emit BOTH an 'orgName' span AND an "
+            "enclosing 'author' (or 'editor') span covering the same text.",
+            "Emit a separate 'author' span for each distinct author — never merge multiple "
+            "authors into a single span.",
+            "In a bibliography, a dash or underscore may stand for a repeated author or editor "
+            "name — tag it as 'author' or 'editor' accordingly.",
+        ],
         elements=[
             TEIElement(
                 tag="label",
@@ -156,16 +169,8 @@ def _build_schema():
                 tag="author",
                 description=(
                     "Name(s) of the author(s) of the cited work. "
-                    "Emit a separate 'author' span for each distinct author — never merge multiple "
-                    "authors into a single span. "
-                    "Each 'author' span covers the full name text of one author. "
-                    "Also emit separate 'surname', 'forename', or 'orgName' spans for the "
-                    "individual name parts; those spans must fall within the 'author' span's text. "
-                    "When an organisation is the author, emit both an 'author' span and an "
-                    "'orgName' span covering the same text — never emit 'orgName' alone in that role. "
                     "Names appearing at the start of a bibliographic entry before the title and "
-                    "date are authors. "
-                    "In a bibliography, a dash or underscore may stand for a repeated author name."
+                    "date are authors."
                 ),
                 allowed_children=['surname', 'forename', 'orgName'],
                 attributes=[],
@@ -174,53 +179,32 @@ def _build_schema():
                 tag="editor",
                 description=(
                     "Name of an editor of the cited work. "
-                    "Emit an 'editor' span covering the full name text; also emit separate "
-                    "'surname', 'forename', or 'orgName' spans for the individual name parts — "
-                    "those spans must fall within the 'editor' span's text. "
                     "An editor's name typically follows keywords such as 'in', 'ed.', 'éd.', "
                     "'Hrsg.', 'dir.', '(ed.)', '(eds.)'. "
                     "CRITICAL: A person's name (or surname alone) that follows 'in' is an editor — "
-                    "emit an 'editor' span (plus name-part spans), never a 'title' span. "
-                    "In a bibliography, a dash or underscore may stand for a repeated editor name."
+                    "emit an 'editor' span (plus name-part spans), never a 'title' span."
                 ),
                 allowed_children=['surname', 'forename', 'orgName'],
                 attributes=[],
             ),
             TEIElement(
                 tag="surname",
-                description=(
-                    "The inherited (family) name of a person. "
-                    "Always emit together with an enclosing 'author' or 'editor' span covering "
-                    "the full name — never emit a 'surname' span without a corresponding "
-                    "'author' or 'editor' span."
-                ),
+                description="The inherited (family) name of a person.",
                 allowed_children=[],
                 attributes=[],
             ),
             TEIElement(
                 tag="forename",
-                description=(
-                    "The given (first) name or initials of a person. "
-                    "Always emit together with an enclosing 'author' or 'editor' span covering "
-                    "the full name — never emit a 'forename' span without a corresponding "
-                    "'author' or 'editor' span."
-                ),
+                description="The given (first) name or initials of a person.",
                 allowed_children=[],
                 attributes=[],
             ),
             TEIElement(
                 tag="orgName",
-                description=(
-                    "Name of an organisation. "
-                    "When the organisation is an author or editor of the cited work, you MUST emit "
-                    "both the 'orgName' span and an enclosing 'author' (or 'editor') span covering "
-                    "the same text. For example, if 'Acme Research Group' is an author, emit an "
-                    "'author' span AND an 'orgName' span both covering 'Acme Research Group'. "
-                    "Never emit 'orgName' alone when the organisation acts as author or editor."
-                ),
+                description="Name of an organisation.",
                 allowed_children=[],
                 attributes=[],
-            ),                              
+            ),
             TEIElement(
                 tag="title",
                 description="Title of the cited work.",
@@ -261,8 +245,8 @@ def _build_schema():
                 tag="biblScope",
                 description=(
                     "Scope reference within the cited item (page range, volume, issue). "
-                    "Emit a separate biblScope span for volume and issue.  "
-                    ),
+                    "Emit a separate biblScope span for volume and issue."
+                ),
                 allowed_children=[],
                 attributes=[
                     attr(

tei_annotator/models/schema.py

@@ -22,6 +22,7 @@ class TEIElement:
 @dataclass
 class TEISchema:
     elements: list[TEIElement] = field(default_factory=list)
+    rules: list[str] = field(default_factory=list)
 
     def get(self, tag: str) -> TEIElement | None:
         for elem in self.elements:

tei_annotator/prompting/templates/json_enforced.jinja2

@@ -1,6 +1,13 @@
 You are a TEI XML annotation assistant.
 
 ## TEI Schema
+{% if schema.rules %}
+### General Rules
+
+{% for rule in schema.rules %}
+{{ loop.index }}. {{ rule }}
+{% endfor %}
+{% endif %}
 {% for elem in schema.elements %}
 - `{{ elem.tag }}`: {{ elem.description }}{% if elem.attributes %} (attributes: {% for attr in elem.attributes %}`{{ attr.name }}`{% if not loop.last %}, {% endif %}{% endfor %}){% endif %}
 {% endfor %}

tei_annotator/prompting/templates/text_gen.jinja2

@@ -1,6 +1,14 @@
 You are a TEI XML annotation assistant. Your task is to identify named entities and spans in the source text and annotate them with TEI XML tags.
 
 ## TEI Schema
+{% if schema.rules %}
+### General Rules
+
+{% for rule in schema.rules %}
+{{ loop.index }}. {{ rule }}
+{% endfor %}
+{% endif %}
+### Element Descriptions
 
 The following TEI elements are in scope:
 {% for elem in schema.elements %}