This container within Hints holds notes that provide hints to Tinderbox's AI to help tag notes.
/Hints/Taggers
The name of each built-in note within the Taggers container corresponds to a Set-type attribute. See below for the additional set-up needed for user-created tagger notes.
Taggers, tags, and terms
A tagger note defines one or more 'tag' items that the tagger will add to/remove from the associated attribute.
Each 'tag' is defined by one of more 'term' items. At simplest a tag can be self defined as the tag name. The detail of the syntax for defining tags and terms is addressed further below.
For information about use of multiword tags and terms see detail under Tagger file syntax.
Scope of Analysis
A tagger looks at the content of a notes title ($Name) and text ($Text). Thus, it is important to understand that tag detection occurs only in the $Text and $Name of a note and not in any other attribute.
Built-in Taggers
There are the tagger notes added by default when the 'Hints' container is first added to the document. These tagger notes, all use 'NL' name prefixes, and have system attributes already in the document.
Three of built-in taggers, NLPlaces, NLNames, and NLOrganizations use underlying Apple NLP (see more on Natural Language Processing) features to match terms. Thus, for NLPlaces, Apple NLP is leveraged to detect any $Text content that appears—to the NLP algorithm—to be a location or place-name (indeed, exactly what those are is undefined), placing that term in the note's $NLPlaces attribute. As a result there is no tell-back as to why a term is auto-populated to the associated attribute.
Although 'NLTags' has an associated system attribute, it does not use any NLP and is essentially a quick stubs for using user-created tags without undue extra set-up. For this and user-defined taggers, the relationship is more simple. A tag addition/removal is linked to a case-insensitive match to any term defined for a tag.
Detection is dynamic: a match to a term in a note's $Text or $Name adds the relevant term to associated attribute for that tagger, removal (of all instances) of the term from $Text or $Name removes the tag from the associated attribute.
Attributes used by taggers
A tagger works with an associated Set-type attribute. Once assigned a tagger, Tinderbox makes the note read-only and this cannot be undone—manually or automatically—short of editing the raw XML of a document. The reason the attribute is marked as read-only is to ensure only the tagger may add or delete values in the course of its work.
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. In effect the attribute keeps a dynamic reference of current matched terms in a note's $Text or $Name.
Naming of taggers
Every discrete note in the 'Taggers' container is a distinct tagger. Each tagger works with s set-type attribute of exactly the same (case-sensitive name). Thus the tagger names should be one that meets attribute naming rules.
Built-in taggers are provided for $NLPlaces, $NLNames, $NLOrganizations, and $NLTags. Thus, the built-in tagger note 'NLTags' maps to system attribute $NLTags.
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).
Setting up for first run
There is some internal work associated with setting up a tagger, regardless of the size of the document. So, depending on the speed of the host Mac, it may take up to 30 seconds before the initial use of a new tagger (i.e. results are seen in the associated attribute). Once set up, performance—i.e. as in term detection—is essentially instant.
How often does tag detection run?
Tag detection runs all the time, but is throttled in large complex documents for pragmatic performance reasons. Despite this, taggers are not a full-on, always-updating service as with a rule. 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. See more about performance and update time.
The tagger mechanism also runs the sentiment analysis process and dominant language detection.
Editing taggers for 'NL' system attributes
When adding the Hints container to a document, the Taggers sub-container includes blank (i.e. no $Text) tagger notes for each of the NL-prefixed system attributes in the 'AI' group. Adding tags (see below).
Users should not create new taggers for any other built-in attributes. Instead, create a custom tagger as described below.
Adding custom taggers
Further taggers may be created for any user Set-type attributes. New taggers are placed in the same container as built-in ones. To add a totally new tagger involves 2 tasks (these can be done in any order):
- add a user Set-type attribute (it must be a Set) using the same name as will be used for the tagger. Pick a name not already used for an attribute or note name.
- create the tagger note with the same name as the attribute.
Tinderbox will now make the attribute read-only (this can't be undone) and will populate that attribute in any notes where the new tagger finds a match. Be aware that creating the tagger file alone does not auto-generate attributes, so user attributes must exist if they are to use taggers.
Customising built-in taggers
The built-in NL-prefix taggers may also be customised, if desired, using the same syntax (see below) as used for custom taggers.
Tagger file syntax
Described here.
Term matching and case
A tagger's defined terms are matched case-intensively in any note's $Text. Thus a term Tinderbox with match both "Tinderbox", "tinderbox" or any other case variant of the word.
Terms and NLP
Unlike user-defined taggers, the NL taggers may add tags the NLP process considers a match but will be unable to explain why. This is a current limitation and weakness of such NLP tools: they cannot explain their decisions, so triaging the cause of false positive (things that should not be matched) or false negative (things that should be matched and aren't) is difficult. Note that the NLP frameworks are Apple's and so any such errors are not caused by Tinderbox, but the underlying Apple code.
The tagger matches in the $Text are not marked or indicated in any way. In the case of custom taggers, or custom additions to built-in NL taggers, it is assumed the user knows the terms they have defined. For the built-in NL taggers additional Apple NLP frameworks are addressed.
Regular Expressions
Taggers do not support regular expressions. Why? Because taggers work with the OS' NLP libraries and those do not understand regex.
Taggers and agents
Described separately here.
Technical requirement
Taggers are require macOS 10.14 or later.
Other aspects of Tagger use:
See also—notes linking to here: