PHI-Model-8B/docs/claims-and-terminology.md

106 lines
4.6 KiB
Markdown

# Terminology and verified claims
## Recommended project explanation
> The generator combines medical category values with curated positive and
> negative contextual patterns. It deterministically shuffles category values,
> patterns, explicit subjects, and requested tenses, then uses LM Studio to
> normalize grammar while preserving the protected medical concept and the
> example's polarity. Patterns without an explicit subject remain subjectless
> fragments; the normalizer assumes an implied singular member/patient only for
> grammar and must not add that subject to the text.
>
> The project uses **Category** as its taxonomy term because the labels are
> intended to integrate with a Presidio category/entity-type extension or
> override. This repository contains the category-based generator and model
> training pipeline, but the Presidio integration itself is maintained
> elsewhere or has not yet been added here.
>
> Positive and negative contexts teach the model that a medical word alone is
> insufficient. “Has diabetes” and “he had a reaction to shellfish” are intended
> positives, while “she wrote a book about diabetes” and “had a reaction to the
> horrible cover of Van Halen's Jump” are intended negatives.
## Review of the original statements
### “The Generator uses random subject, verb, etc.”
**Mostly correct, with precision needed.**
- It shuffles values, patterns, subjects, and a tense deck with a seeded
pseudorandom generator.
- Subjects are `He`, `She`, `They`, and `Member`.
- It does not simply select arbitrary verbs. Patterns supply grammar expressions
and sentence structure; local logic and LM Studio resolve/rewrite auxiliaries
and verb phrases for subject/tense.
- `[x]` starts with the canonical value. Allowed variants are supplied to the
normalizer, rather than directly sampled as an independent random deck.
- Planning is repeatable for unchanged seed/input/configuration; the external LM
service is a remaining reproducibility variable.
### “It creates context for positive and negative tuning examples.”
**Correct.**
Every category has explicit positive and negative pattern files. The label is
stored on each generated item and carried through export, SFT conversion,
training, and evaluation.
### “Categories instead of Nodes/Edges because of Presidio.”
**Reasonable design intent, not verifiable integration in this repository.**
The implementation consistently uses categories/entity types, and that is an
appropriate vocabulary for a Presidio recognizer extension. There is no graph
model in this code, so “nodes/edges” would be misleading. However, no Presidio
package, recognizer, registry, mapping, or runtime call is checked in. Phrase
this as intended compatibility/integration, not as a current in-repository
dependency.
### “Without a subject, or if a sentence fragment, it assumes the member is the subject.”
**Correct only when qualified.**
The implementation marks patterns without `[sub]` as fragments and does not
insert `Member`. The normalizer uses an implied singular member/patient for
agreement and tense only, and must preserve a subjectless output. `Member` is
also one explicit choice in the subject deck when `[sub]` is present.
Preferred wording:
> Subjectless patterns are treated as fragments. For grammar only, the
> normalizer assumes an implied singular member/patient but does not add that
> subject to the generated text.
### Context examples
**They correctly express the intended distinction.**
The medical term or word “reaction” is not enough by itself. Actual patient
medical assertions are positive; authored/educational or idiomatic non-medical
uses are negative. These exact examples should also become automated golden
tests if they are contractual behavior.
## Category versus entity type
- **Category** is the generator/database taxonomy object.
- **Entity type** is the name emitted in model JSON.
- Both currently use the same 12 `MEDICAL_*` identifiers.
- **Keyword** is a canonical medical value assigned to a category.
- **Variant** is an allowed surface/grammatical form of a keyword.
- **Pattern** supplies contextual structure and polarity.
- **Training item** is the resulting labeled text.
## What not to claim
Avoid saying:
- the model is a keyword matcher;
- all category variants are randomly selected;
- `Member` is inserted whenever a subject is absent;
- this repository contains a working Presidio integration;
- the tracked pipeline produces GGUF;
- the current model extracts exact medical spans;
- deterministic planning guarantees identical external LM responses;
- NIH, WHO, or CDC endorse this project.