This container within Hints holds notes that provide hints to Tinderbox's AI to help tag notes.
/Hints/Taggers
The name of each note within the Taggers container corresponds to a Set-type attribute. The tagger file adds or removes value(s) to that attribute based on the detection in the $Text or $Name of a note, of terms defined in the tagger file.
If an attribute has a tagger, that attribute is marked as read-only because only the tagger is free to add and delete tags in the course of its work.
The name of each note within the Tagger container corresponds to a Set-type attribute. Built-in taggers are provided for $NLPlaces, $NLNames, $NLOrganizations, and $NLTags. Thus, the build-in tagger note 'NLTags' maps to system attribute $NLTags. Further taggers may be created for any user Set-type attributes (the tagger file does not auto-generate attributes, so user attributes must exist if they are to use taggers).
A note will be flagged for tagging after its $Text or $Name is edited, and the tagging will be performed when the note is visited by the rule manager (i.e. the same cycle of operations that runs note rules).
N.B., taggers are not a full-on, always updating service. this reflects that they are a form of advisor and they need to run (using AI routines in the OS) in harmony with other Tinderbox processes. If in doubt about tagger output being up to date, close and re-open the current document as all Taggers run at document start. As this feature settles into its place in the app, the control of tagger operations (without affecting other task) will doubtless be improved.
The tagger mechanism also runs the sentiment analysis process.
Tagger file syntax
Each line of a tagger note's $Text describes one possible 'tag' (i.e term to be added) followed by a number of term(s) whose detection can trigger tag insertion. The general syntax is
tag:term 1;term 2;term 3;
The first term is the 'tag' separated by a colon from the trigger 'term(s)'. Each discrete term is delimited from others by a semi-colon (in the convention of Tinderbox list delimiters) but unlike other Tinderbox lists there should be a semi-colon after the last item: if a terminating semi-colon is omitted the last listed term may not get evaluated. Terms may be multi-word (e.g. first and last name) though the method is not intended for matching long texts. White space after colons and before/after semicolons is ignored. The layouts below are functionally equivalent:
tag:term 1;term 2;term 3;
tag: term 1; term 2; term 3;
If the only term matches the tag, as in:
Eastgate:Eastgate;
Then a shorthand form may be used, i.e. just the word, alone, on a single line:
Eastgate
The format is thus 'tag-name:term1;term2;etc…' or simply 'tag-name'.
Therefore, if the NLTags tagger file contains the line:
Eastgate:Eastgate;Tinderbox;Storyspace;Mark Bernstein;
then $NLTags will add the tag "Eastgate" if the text or title of the note mentions any one or more of the words "Eastgate", "Tinderbox", "Storyspace", or "Mark Bernstein".
As well as adding a tag if a term is matched, if a tagger formerly applied a tag but source term(s) are no longer detected, the tagger will remove that tag from the note's attribute.
Each discrete tag configuration forms a single line. Although the tagger file's $Text may wrap in the text pane, a single definition runs from the start of a line to the first line break regardless of soft wrapping.
Blank lines in the tagger note are ignored so may be used to separate the definition strings for clarity of reading.
Lines with content may be commented out be starting the line with a hash (#) symbol.
Taggers do not support regular expressions. Why? Because taggers work with the OS' NLP libraries and these don't understand regex).
Technical requirement. Taggers are require macOS 10.14 or later.