feat(medcat): Add component contracting

medcat-v2/README.md

@@ -151,6 +151,29 @@ See [Architecture Documentation](docs/architecture.md) for detailed information.
 ## Tutorials
 A guide on how to use MedCAT v2 is available at on the medcat documentation page on [docs.cogstack.org](https://docs.cogstack.org)
 
+## Contributing
+
+Please follow the [Contribution Guidelines](../CONTRIBUTING.md).
+
+When writing your own component (NER or linker), it is recommended making sure they follow the contracts for these components.
+<details>
+<summary>Example test for custom components in model pack</summary>
+
+```python
+from unittest import TestCase
+from medcat.components.contracting_testing import assert_component_contracts
+# implement create_model_with_my_component
+class MyComponentTest(TestCase):
+    def test_my_model_contract(self):
+        # create or load a model with your custom component(s)
+        # NOTE: This would (generally) need to be able to NER / link 1 entity in the example text
+        #       The test time models in medcat would be sufficient
+        cat = create_model_with_my_component()
+        assert_component_contracts(cat)
+```
+</details>
+
+
 ## Acknowledgements
 Entity extraction was trained on [MedMentions](https://github.com/chanzuckerberg/MedMentions) In total it has ~ 35K entites from UMLS
 

medcat-v2/medcat/components/base.py

@@ -0,0 +1,109 @@
+from typing import Protocol, runtime_checkable, Optional
+from typing_extensions import Self
+from enum import Enum
+
+from pydantic import BaseModel
+
+from medcat.tokenizing.tokens import MutableDocument
+from medcat.tokenizing.tokenizers import BaseTokenizer
+from medcat.cdb import CDB
+from medcat.vocab import Vocab
+from medcat.config.config import ComponentConfig
+
+
+@runtime_checkable
+class BaseComponent(Protocol):
+
+    @property
+    def full_name(self) -> Optional[str]:
+        """Name with the component type (e.g ner, linking, meta)."""
+        pass
+
+    @property
+    def name(self) -> str:
+        """The name of the component."""
+        pass
+
+    def is_core(self) -> bool:
+        """Whether the component is a core component or not.
+
+        Returns:
+            bool: Whether this is a core component.
+        """
+        pass
+
+    def __call__(self, doc: MutableDocument) -> MutableDocument:
+        pass
+
+    @classmethod
+    def create_new_component(
+            cls, cnf: ComponentConfig, tokenizer: BaseTokenizer,
+            cdb: CDB, vocab: Vocab, model_load_path: Optional[str]) -> Self:
+        """Create a new component or load one off disk if load path presented.
+
+        This may raise an exception if the wrong type of config is provided.
+
+        Args:
+            cnf (ComponentConfig): The config relevant to this components.
+            tokenizer (BaseTokenizer): The base tokenizer.
+            cdb (CDB): The CDB.
+            vocab (Vocab): The Vocab.
+            model_load_path (Optional[str]): Model load path (if present).
+
+        Returns:
+            Self: The new components.
+        """
+        pass
+
+class CollectionContract(BaseModel, frozen=True):
+    """Contract for a collection field — what each item in the collection provides."""
+    field: str                        # e.g. 'ner_ents'
+    must_provide: frozenset[str]      # fields every item must have
+    may_provide: frozenset[str] = frozenset()
+
+
+class ComponentContract(BaseModel, frozen=True):
+    needs: frozenset[str]
+    must_provide: frozenset[str]
+    may_provide: frozenset[str] = frozenset()
+    collection_contracts: frozenset[CollectionContract] = frozenset()
+
+
+class CoreComponentType(Enum):
+    tagging = ComponentContract(
+        needs=frozenset(),
+        must_provide=frozenset(),
+        # doesn't write for every token
+        may_provide=frozenset({'token.is_punctuation', 'token.to_skip'}),
+        collection_contracts=frozenset(),
+    )
+    token_normalizing = ComponentContract(
+        needs=frozenset(),
+        # should write for every token
+        must_provide=frozenset({'token.norm'}),
+        may_provide=frozenset(),
+        collection_contracts=frozenset(),
+    )
+    ner = ComponentContract(
+        needs=frozenset({'token.to_skip'}),
+        must_provide=frozenset({'doc.ner_ents'}),   # the list must exist
+        may_provide=frozenset(),
+        collection_contracts=frozenset({
+            CollectionContract(
+                field='doc.ner_ents',
+                must_provide=frozenset({'detected_name'}),
+            )
+        }),
+    )
+    linking = ComponentContract(
+        needs=frozenset({'doc.ner_ents'}),
+        # must write, but may be empty list
+        must_provide=frozenset({'doc.linked_ents'}),
+        may_provide=frozenset({}),
+        collection_contracts=frozenset({
+            CollectionContract(
+                field='doc.linked_ents',
+                must_provide=frozenset({'cui', 'context_similarity'}),
+            ),
+        }),
+    )

medcat-v2/medcat/components/contracting.py

@@ -0,0 +1,241 @@
+from typing import Callable
+from logging import Logger
+
+from medcat.tokenizing.tokens import MutableDocument
+from medcat.components.base import BaseComponent, ComponentContract
+from medcat.components.contracting_utils import (
+    AccessType, wrap_relevant_parts, ContractViolation)
+
+
+logger = Logger(__name__)
+
+
+def verify_part(
+    text: str,
+    doc_getter: Callable[[str], MutableDocument],
+    component: BaseComponent,
+    paths: list[str],
+    access_type: AccessType,
+    raise_on_violation: bool = True,
+    min_feedbacks: int = 0,
+) -> list[str]:
+    """Verify the parts for this text.
+
+    Args:
+        text (str): The text to use.
+        doc_getter (Callable[[str], MutableDocument]): The document getter.
+        component (BaseComponent): The component to check.
+        paths (list[str]): The paths to check.
+        access_type (AccessType): The type of access to check.
+        raise_on_violation (bool): Whether to raise on a violation.
+            Defaults to True.
+        min_feedbacks (int): The minimum number of feedbacks expected.
+            Defaults to 0.
+
+    Raises:
+        ContractViolation: If there are violations and instructed to raise.
+
+    Returns:
+        list[str]: The list of violations, if any.
+    """
+    violations: list[str] = []
+    for path in paths:
+        doc = doc_getter(text)
+        with wrap_relevant_parts(doc, path) as feedback:
+            doc = component(doc)
+        # verify each one access
+        accessed = sum(bool(fb) for fb in feedback)
+        total = len(feedback)
+        if accessed != total:
+            violations.append(
+                f"Component {component.full_name} does not {access_type.name} "
+                f"{path} ({accessed} / {total} accessed)")
+            logger.debug(
+                "Found a virolation in component '%s' for %s at '%s': "
+                "(%d / %d) accessed with feedback %s",
+                component.full_name, access_type.name,
+                path, accessed, total, feedback,
+            )
+        elif total < min_feedbacks:
+            violations.append(
+                f"Component {component.full_name} did not {access_type.name} "
+                f"{path} enough ({total} with minimum {min_feedbacks})")
+            logger.debug(
+                "Component '%s' did not %s "
+                "'%s' enough (%d with minimum %d)",
+                component.full_name, access_type.name,
+                path, total, min_feedbacks,
+            )
+    if raise_on_violation:
+        raise ContractViolation("\n".join(violations))
+    return violations
+
+
+def verify_needs(
+    text: str,
+    doc_getter: Callable[[str], MutableDocument],
+    component: BaseComponent,
+    contract: ComponentContract,
+    raise_on_violation: bool = True,
+    min_feedbacks: int = 0,
+) -> list[str]:
+    """Verify the needs portion of a contract.
+
+    Args:
+        text (str): The text to use.
+        doc_getter (Callable[[str], MutableDocument]): The document getter.
+        component (BaseComponent): The component to check.
+        contract (ComponentContract): The contract to check.
+        raise_on_violation (bool): Whether to raise on violations.
+            Defaults to True.
+        min_feedbacks (int,): The minimum number of feedbacks expected.
+            Defaults to 0.
+
+    Returns:
+        list[str]: The list of violations, if any.
+    """
+    return verify_part(
+        text, doc_getter, component, list(contract.needs),
+        AccessType.READ, raise_on_violation=raise_on_violation,
+        min_feedbacks=min_feedbacks,
+    )
+
+
+def verify_must_provide(
+    text: str,
+    doc_getter: Callable[[str], MutableDocument],
+    component: BaseComponent,
+    contract: ComponentContract,
+    raise_on_violation: bool = True,
+    min_feedbacks: int = 0,
+) -> list[str]:
+    """Verify the must-provide portion of a contract.
+
+    Args:
+        text (str): The text to use.
+        doc_getter (Callable[[str], MutableDocument]): The document getter.
+        component (BaseComponent): The component to check.
+        contract (ComponentContract): The contract to check.
+        raise_on_violation (bool): Whether to raise on violations.
+            Defaults to True.
+        min_feedbacks (int,): The minimum number of feedbacks expected.
+            Defaults to 0.
+
+    Returns:
+        list[str]: The list of violations, if any.
+    """
+    return verify_part(
+        text, doc_getter, component, list(contract.must_provide),
+        AccessType.WRITE, raise_on_violation=raise_on_violation,
+        min_feedbacks=min_feedbacks,
+    )
+
+
+def verify_collections_contracts(
+    text: str,
+    doc_getter: Callable[[str], MutableDocument],
+    component: BaseComponent,
+    contract: ComponentContract,
+    raise_on_violation: bool = True,
+    min_feedbacks: int = 0,
+) -> list[str]:
+    """Verify the collection contracts portion of a contract.
+
+    This method only really checks the length of the collection
+    and that each item in there has a truthy value for each required
+    field. The expectation is that the write action (for the collection)
+    is checked by other parts. And because these entities may be created
+    in order to put them in the lists (i.e for NER) without the data filled
+    in, it's fair to assume that if the data exists, it was filled in.
+
+    Args:
+        text (str): The text to use.
+        doc_getter (Callable[[str], MutableDocument]): The document getter.
+        component (BaseComponent): The component to check.
+        contract (ComponentContract): The contract to check.
+        raise_on_violation (bool): Whether to raise on violations.
+            Defaults to True.
+        min_feedbacks (int): The minimum number of feedbacks expected.
+            Defaults to 0.
+
+    Returns:
+        list[str]: The list of violations, if any.
+    """
+    violations: list[str] = []
+    if not contract.collection_contracts:
+        return violations
+    doc = doc_getter(text)
+    doc = component(doc)
+    for cc in contract.collection_contracts:
+        if not cc.field.startswith("doc."):
+            violations.append(
+                f"Collection contract field '{cc.field}' is not a doc-level "
+                f"field — only doc.* fields are currently supported")
+            continue
+        attr = cc.field.split(".", 1)[1]
+        try:
+            collection = getattr(doc, attr)
+        except AttributeError:
+            violations.append(
+                f"Component {component.full_name} did not provide "
+                f"collection '{cc.field}' at all")
+            continue
+        items = list(collection)
+        if len(items) < min_feedbacks:
+            violations.append(
+                f"Collection '{cc.field}' has too few items "
+                f"({len(items)} with minimum {min_feedbacks})")
+        for i, item in enumerate(items):
+            for field in cc.must_provide:
+                try:
+                    val = getattr(item, field)
+                except AttributeError:
+                    violations.append(
+                        f"Item {i} in '{cc.field}' is missing "
+                        f"required field '{field}'")
+                    continue
+                if not val:
+                    violations.append(
+                        f"Item {i} in '{cc.field}' has falsy value "
+                        f"for required field '{field}' (got {val!r})")
+    if violations and raise_on_violation:
+        raise ContractViolation("\n".join(violations))
+    return violations
+
+
+def verify_contract(
+    text: str,
+    doc_getter: Callable[[str], MutableDocument],
+    component: BaseComponent,
+    contract: ComponentContract,
+    raise_on_violation: bool = True,
+    min_feedbacks_need: int = 0,
+    min_feedbacks_provide: int = 0,
+    min_feedbacks_contracts: int = 0,
+) -> list[str]:
+    """
+    Verify a ComponentContract against a document before/after a component ran.
+    Returns a list of violation messages.
+
+    Raises ContractViolation if violations found and raise_on_violation.
+    """
+    # verify needs are met
+    violations = verify_needs(
+        text, doc_getter, component, contract, raise_on_violation=False,
+        min_feedbacks=min_feedbacks_need,
+    )
+    # verify mandatory returns are done
+    violations += verify_must_provide(
+        text, doc_getter, component, contract, raise_on_violation=False,
+        min_feedbacks=min_feedbacks_provide,
+    )
+    # verify collections contracts
+    violations += verify_collections_contracts(
+        text, doc_getter, component, contract, raise_on_violation=False,
+        min_feedbacks=min_feedbacks_contracts,
+    )
+
+    if violations and raise_on_violation:
+        raise ContractViolation("\n".join(violations))
+
+    return violations