Support court-specific filing hints

Author: nonprofittechy

docs/developer-notes/issue-106-vermont-handoff-validation.md

@@ -100,8 +100,8 @@ minor-specific semantic hint was verified by a sender unit test.
 
 ## Final automated checks
 
-- LITEFile: `uv run pytest -q` — 782 passed.
-- Vermont sender: `python -m pytest -q tests/test_litefile.py` — 16 passed.
+- LITEFile: `uv run pytest -q` — 784 passed.
+- Vermont sender: `python -m pytest -q tests/test_litefile.py` — 17 passed.
 - LITEFile: `uv run ruff check .` and `uv run ty check` — passed.
 - Django: `makemigrations --check --dry-run` — no model drift; migration 0023
   was applied to the isolated test database.
@@ -179,7 +179,7 @@ Installed the refactored adapter on the running Docassemble server and verified:
 - Retrying the correction kept one replacement receipt and two total transfer
   caches (initial and correction).
 - Text extraction from the stored affidavit confirmed the new correction text.
-- Sixteen adapter tests, Ruff, whitespace checks, and the documentation build
+- Seventeen adapter tests, Ruff, whitespace checks, and the documentation build
   pass.
 
 The reusable person helper defaults to the standard AssemblyLine and
@@ -191,6 +191,15 @@ The final live retry used the flat `litefile` server configuration and logged an
 empty argument mapping for `litefile_upload`. Credentials, correction tokens,
 and interview answers therefore remained outside the background job arguments.
 
+Follow-up contract tests cover county and court-specific semantic hints. They
+verify court-over-county-over-general precedence across case categories, case
+types, filing types, document types, and filing components. Validation rejects
+unknown document IDs and county keys that normalize to the same name. The
+sender test confirms that the declarative override mapping reaches the payload.
+The updated interview was also reinstalled and completed another live
+background handoff: draft 11 received four PDFs plus the default empty county
+and court override maps, and the success screen cleared the pending task.
+
 The first attempt encountered a stopped LocalStack container and a recoverable
 HTTP 503. Restarting local storage allowed the same cached transfer to succeed.
 No additional court submission was made during this refactor validation.

docs/docs/partners-courts/interview-integration.md

@@ -121,6 +121,52 @@ suggestions remain in the receipt; numeric suggestions never populate resolved
 court-code fields. Supported questionnaire answers `has_children` and
 `child_count` also populate their normal filing fields.
 
+### County-specific and court-specific hints
+
+Use `filing_hint_overrides` when a semantic name is correct in one filing
+location and wrong in another. Matching county values replace general hints
+field by field. Matching court values apply afterward and replace the county
+value for the same field. Fields that an override omits continue using the less
+specific value.
+
+```json
+{
+  "case_category_name_hints": ["Civil"],
+  "case_type_name_hints": ["General case type"],
+  "filing_hint_overrides": {
+    "counties": {
+      "Cook": {
+        "case_type_name_hints": ["Cook County case type"],
+        "documents": {
+          "complaint": {
+            "filing_type_name_hints": ["Cook County complaint"]
+          }
+        }
+      }
+    },
+    "courts": {
+      "First Municipal District": {
+        "case_category_name_hints": ["Court-specific category"],
+        "documents": {
+          "complaint": {
+            "filing_type_name_hints": ["Court-specific complaint"],
+            "document_type_name_hints": ["Court-specific document type"],
+            "filing_component_name_hints": ["Court-specific lead document"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+County keys match `case.county`; they may include or omit the word `County`.
+Court keys match either the source's `case.court_name` or the official court
+name resolved from live metadata. Matching ignores capitalization and ordinary
+name punctuation. Scoped `documents` keys must be document IDs declared in the
+same request. Names remain semantic suggestions: LITEFile only saves a code
+when exactly one live option matches.
+
 ## Response, continuation, and retries
 
 A new receipt returns HTTP 201. An identical retry returns HTTP 200 with the same

efile_app/efile/services/handoff.py

@@ -78,6 +78,71 @@ def _hints(value, path):
                 _string(hint, field)
 
 
+def _scope_name(value, scope):
+    name = normalize_name(value)
+    if scope == "counties":
+        name = name.removesuffix(" county")
+    return name
+
+
+def _validate_filing_hint_overrides(payload, document_ids):
+    overrides = _object(payload.get("filing_hint_overrides", {}), "filing_hint_overrides")
+    for scope in ("counties", "courts"):
+        choices = _object(overrides.get(scope, {}), f"filing_hint_overrides.{scope}")
+        if len(choices) > 100:
+            raise HandoffError(f"filing_hint_overrides.{scope} supports up to 100 names.")
+        normalized = set()
+        for name, values in choices.items():
+            _string(name, f"filing_hint_overrides.{scope} name")
+            key = _scope_name(name, scope)
+            if not key or key in normalized:
+                raise HandoffError(f"filing_hint_overrides.{scope} names must be unique.")
+            normalized.add(key)
+            values = _object(values, f"filing_hint_overrides.{scope}.{name}")
+            _hints(values, f"filing_hint_overrides.{scope}.{name}")
+            documents = _object(values.get("documents", {}), f"filing_hint_overrides.{scope}.{name}.documents")
+            if not set(documents).issubset(document_ids):
+                raise HandoffError("Scoped document hints must use a declared document id.")
+            for document_id, document_hints in documents.items():
+                _hints(
+                    _object(
+                        document_hints,
+                        f"filing_hint_overrides.{scope}.{name}.documents.{document_id}",
+                    ),
+                    f"filing_hint_overrides.{scope}.{name}.documents.{document_id}",
+                )
+
+
+def _matching_hint_override(payload, scope, candidates):
+    choices = payload.get("filing_hint_overrides", {}).get(scope, {})
+    wanted = {_scope_name(candidate, scope) for candidate in candidates if candidate}
+    return next(
+        (values for name, values in choices.items() if _scope_name(name, scope) in wanted),
+        {},
+    )
+
+
+def effective_hints(payload, *, court_name="", document=None):
+    """Apply general, county, then court-specific semantic hint overrides."""
+    base = document if document is not None else payload
+    result = {field: list(value) for field in HINT_FIELDS if isinstance((value := base.get(field)), list)}
+    case = payload.get("case", {})
+    scopes = (
+        _matching_hint_override(payload, "counties", [case.get("county", "")]),
+        _matching_hint_override(
+            payload,
+            "courts",
+            [case.get("court_name", ""), court_name],
+        ),
+    )
+    for override in scopes:
+        selected = override.get("documents", {}).get(document.get("id", ""), {}) if document else override
+        for field in HINT_FIELDS:
+            if field in selected:
+                result[field] = list(selected[field])
+    return result
+
+
 def validate_payload(payload, source_config, files):
     _object(payload, "payload")
     if type(payload.get("schema_version")) is not int or payload["schema_version"] != 1:
@@ -98,6 +163,7 @@ def validate_payload(payload, source_config, files):
         raise HandoffError("case.existing_case must be true or false when known.")
     for field in CASE_FIELDS:
         _string(case.get(field, ""), f"case.{field}", FilingDraft._meta.get_field(field).max_length)
+    _string(case.get("county", ""), "case.county")
     _object(payload.get("known_filing_facts", {}), "known_filing_facts")
     parties = payload.get("parties", [])
     if not isinstance(parties, list) or len(parties) > 100:
@@ -167,6 +233,7 @@ def validate_payload(payload, source_config, files):
         raise HandoffError("A document bundle needs exactly one lead PDF.")
     if set(files) != ids or any(len(files.getlist(key)) != 1 for key in files):
         raise HandoffError("Upload each declared document exactly once.")
+    _validate_filing_hint_overrides(payload, ids)
     return payload
 
 
@@ -296,12 +363,13 @@ def choose(obj, field, options, hints):
     choose(draft, "court_code", _codes(draft.jurisdiction, "", with_names=True), court_hints(draft, payload))
     if not draft.court_code:
         return
+    payload_hints = effective_hints(payload, court_name=draft.court_name)
     timing = "Subsequent" if draft.existing_case == ExistingCase.EXISTING else "Initial"
     choose(
         draft,
         "case_category_code",
         _codes(draft.jurisdiction, f"{draft.court_code}/categories", timing=timing, fileable_only=True),
-        intent.get("case_category_name_aliases", []) + payload.get("case_category_name_hints", []),
+        intent.get("case_category_name_aliases", []) + payload_hints.get("case_category_name_hints", []),
     )
     if not draft.case_category_code:
         return
@@ -311,7 +379,7 @@ def choose(obj, field, options, hints):
         _codes(
             draft.jurisdiction, f"{draft.court_code}/case_types/", category_id=draft.case_category_code, timing=timing
         ),
-        intent.get("case_type_name_aliases", []) + payload.get("case_type_name_hints", []),
+        intent.get("case_type_name_aliases", []) + payload_hints.get("case_type_name_hints", []),
     )
     if not draft.case_type_code:
         return
@@ -325,16 +393,17 @@ def choose(obj, field, options, hints):
     for document in draft.documents.all():
         suggestion = draft.metadata_events.filter(path=f"documents.{document.pk}", kind="source_suggestion").first()
         hints = suggestion.value if suggestion else {}
+        document_hints = effective_hints(payload, court_name=draft.court_name, document=hints)
         curated = intent.get("documents", {}).get(hints.get("id", ""), {})
         choose(
             document,
             "filing_type_code",
             options,
             curated.get("filing_type_name_aliases", [])
             + (
-                hints.get("filing_type_name_hints", [])
+                document_hints.get("filing_type_name_hints", [])
                 or (
-                    intent.get("filing_type_name_aliases", []) + payload.get("filing_type_name_hints", [])
+                    intent.get("filing_type_name_aliases", []) + payload_hints.get("filing_type_name_hints", [])
                     if document.role == "lead"
                     else [hints.get("form_name", "")]
                 )
@@ -348,7 +417,12 @@ def choose(obj, field, options, hints):
                 choices = _codes(
                     draft.jurisdiction, f"{draft.court_code}/filing_types/{document.filing_type_code}/{endpoint}"
                 )
-                choose(document, field, choices, hints.get(field.replace("_code", "_name_hints"), []))
+                choose(
+                    document,
+                    field,
+                    choices,
+                    document_hints.get(field.replace("_code", "_name_hints"), []),
+                )
     party_options = _codes(draft.jurisdiction, f"{draft.court_code}/case_types/{draft.case_type_code}/party_types")
     for party in draft.parties.all():
         if party.role == "filer" and not (party.is_self or party.is_filing_party):

efile_app/efile/tests/test_handoff.py

@@ -7,7 +7,7 @@
 from django.urls import reverse
 
 from efile.models import FilingDraft, InterviewHandoff
-from efile.services.handoff import HandoffError, create_correction, resolve_metadata, unique_match
+from efile.services.handoff import HandoffError, create_correction, effective_hints, resolve_metadata, unique_match
 
 pytestmark = pytest.mark.django_db
 PDF = b"%PDF-1.4\nsynthetic test document"
@@ -159,6 +159,72 @@ def codes(jurisdiction, path, **params):
     assert InterviewHandoff.objects.get().payload["documents"][0]["filing_type_code"] == "9999"
 
 
+def test_county_and_court_hint_overrides_replace_general_hints(client, source, payload, storage):
+    payload["case"]["county"] = "Cook County"
+    payload["filing_hint_overrides"] = {
+        "counties": {
+            "Cook": {
+                "case_category_name_hints": ["County category"],
+                "case_type_name_hints": ["County case type"],
+                "documents": {"complaint": {"document_type_name_hints": ["County confidential"]}},
+            }
+        },
+        "courts": {
+            "Test Family Court": {
+                "case_category_name_hints": ["Court category"],
+                "documents": {
+                    "complaint": {
+                        "filing_type_name_hints": ["Court complaint"],
+                        "filing_component_name_hints": ["Court lead"],
+                    }
+                },
+            }
+        },
+    }
+    assert effective_hints(payload, court_name="Test family court")["case_category_name_hints"] == ["Court category"]
+    send(client, source, payload)
+    draft = FilingDraft.objects.get()
+
+    def codes(jurisdiction, path, **params):
+        return {
+            "": [{"code": "vt", "name": "Test family court"}],
+            "vt/categories": [
+                {"code": "county", "name": "County category"},
+                {"code": "court", "name": "Court category"},
+            ],
+            "vt/case_types/": [{"code": "county-type", "name": "County case type"}],
+            "vt/filing_types/": [{"code": "court-filing", "name": "Court complaint"}],
+            "vt/filing_types/court-filing/document_types": [
+                {"code": "county-confidential", "name": "County confidential"}
+            ],
+            "vt/filing_types/court-filing/filing_components": [{"code": "court-lead", "name": "Court lead"}],
+        }.get(path, [])
+
+    with patch("efile.services.handoff._codes", side_effect=codes):
+        resolve_metadata(draft)
+    draft.refresh_from_db()
+    document = draft.documents.get()
+    assert draft.case_category_code == "court"
+    assert draft.case_type_code == "county-type"
+    assert document.filing_type_code == "court-filing"
+    assert document.document_type_code == "county-confidential"
+    assert document.filing_component_code == "court-lead"
+
+
+def test_scoped_hints_reject_unknown_documents_and_duplicate_counties(client, source, payload, storage):
+    payload["filing_hint_overrides"] = {
+        "counties": {"Cook": {"documents": {"missing": {"filing_type_name_hints": ["Complaint"]}}}}
+    }
+    assert send(client, source, payload).status_code == 400
+    payload["filing_hint_overrides"] = {
+        "counties": {
+            "Cook": {"case_type_name_hints": ["One"]},
+            "Cook County": {"case_type_name_hints": ["Two"]},
+        }
+    }
+    assert send(client, source, payload).status_code == 400
+
+
 def test_correction_preserves_snapshot_and_blocks_ambiguous_attempts(
     client, source, payload, storage, django_user_model
 ):