#359 - Introduce AnnotationBase static type carrying the sofa feature

[reckart]

What's in the PR

• Introduce AnnotationBase static type as intermediate base between FeatureStructure and Annotation, carrying the sofa feature
• Re-parent Annotation onto AnnotationBase to mirror UIMA's type hierarchy (uima.cas.AnnotationBase → uima.tcas.Annotation)
• Add is_annotation_base() TypeGuard alongside is_annotation() for type narrowing
• Generalize FS-class builder from 2-way to 3-way base selection, skipping re-declaration of inherited features (sofa for AnnotationBase; sofa/begin/end for Annotation)
• Add TYPE_CHECKING import of Sofa to avoid circular import; use cast() at sofa access sites to satisfy static type checker while preserving hasattr() runtime guards

How to test manually

• No specific test procedure

Automatic testing

• PR includes unit tests

Documentation

• PR updates documentation

[Copilot]

Pull request overview

This PR introduces an AnnotationBase intermediate base class (between FeatureStructure and Annotation) to better mirror UIMA’s hierarchy and to provide a nominal/static home for the sofa feature across all uima.cas.AnnotationBase subtypes.

Changes:

• Add AnnotationBase and is_annotation_base() and re-parent Annotation to inherit from AnnotationBase.
• Generalize FS class generation to select among FeatureStructure / AnnotationBase / Annotation and avoid redeclaring inherited features (sofa, begin, end).
• Update CAS/JSON/util code paths to access sofa via the new base and use casts for static type checking; adjust a test string constant.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_cas.py	Updates the test’s sofa_uri string value.
src/cassis/util.py	Adjusts comparable-text anchor generation to access sofa via AnnotationBase (with casts).
src/cassis/typesystem.py	Introduces AnnotationBase, re-parents Annotation, adds is_annotation_base, and updates FS class base selection logic.
src/cassis/json.py	Updates offset-fixup logic to treat sofa as coming from AnnotationBase (with casts).
src/cassis/cas.py	Updates CAS add() to assign sofa via AnnotationBase (cast for typing).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.