SENSEI

Semantic Extraction, Navigation, Search, Enrichment and Identification

SENSEI is a core part of SEN and provides an infrastructure for:

• Semantic Extraction: extract semantics hidden in files, like structure, entities or relations
• Navigation: provide a way to navigate linked data using plugins, integrating with applications for resolving relation properties (e.g. references to pages in a document)
• Search: search for missing metadata using available fragments and keys (ISBN, IMDB id, DOI,...)
• Enrichment: query open data sources for metadata and enrich local files, e.g. Book or Movie entities, PDF papers,...
• Identification: determine the semantic type of a given file, e.g. a Paper, Invoice or ebook from a PDF document

SEN uses native queries for plugins supporting a given FileType and Feature (any combination of the above). The plugin gets called with the original file reference and all properties of the relation.

More documentation is coming up soon and will be available in the Wiki.

Plugins

One folder per plugin in plugins/, named for what it does (pdf-extractor, text-reference-navigator, book-enricher, ...), and one package per plugin. A plugin supports one or more features (extract, navigate, enrich, identify, search) for one or more file types: PLUGINS.md lists them (generated by tools/overview.py from the Resources.rdef of the plugins). Code that several plugins use is in common/.

The signature of a plugin is application/x-vnd.sen-plugin.<vendor>.<name>, e.g. application/x-vnd.sen-plugin.sen-labs.pdf-extractor. The SEN server finds plugins with a query for that pattern, which works for installed packages, too (packagefs can only be queried for a few attributes, the signature is one of them).

pkgman add-repo https://kiri.sen-labs.org/x86_64     # once
pkgman install sen_plugins                           # all plugins at once
pkgman install sen_plugin_document_reference_navigator              # or one package per plugin, see PLUGINS.md for the names

Build and package on Haiku (each plugin has a build.sh that also writes the attributes from its resources, package.sh makes the packages):

./build.sh                          # all plugins (./build.sh document-reference-navigator text-reference-navigator: those); JOBS=8 for the number of jobs of make
./package.sh document-reference-navigator          # or without names: all plugins. The ones that are not up to date are built first (FORCE=1: all of them)

A plugin that fails to build does not stop the others; the summary lists them. The package sen_plugins requires every plugin at least in the version that it was packaged with, so that an older version in a repository cannot take its place.

Colophon / About the Logo

In Japanese, the kanji (Japanese symbols) in the logo can be translated as:

• 将 (shō) - "general" or "leader" - senseis act as leaders and guides in their discipline.
• 特 (toku) - "special" or "virtue/merit" - this connects to the special qualities and virtues a sensei embodies and teaches.
• 風 (fū) - "wind" or "style/way" - this relates to the teaching style or "way" (as in martial arts "do" - the way/path) that a sensei represents.

Together, these symbols represent the concept of a sensei's special leadership style or virtuous way of teaching - the particular manner in which a master guides students along their path. The ornate knot design reinforces this idea of interconnectedness and the binding relationship between teacher and student. These characters capture the essence of what makes a true teacher: leadership (将), special virtue (特), and a distinctive way or style (風) of guiding others.

(Note: I sadly don't speak Japanese so please correct me if this is wrong, just love references to Japanese culture as a nod to BeOS and Haiku, and of course to the origins of these references).

Settings of a plugin

A plugin has no window for its settings: the settings window of SEN (sen_settings, in the Settings item of the Deskbar menu) lists the plugins and shows the form of Shoji for the selected one. The window asks the plugin for its settings as a message and sends back what the user changes; the plugin keeps and validates them itself, in the place and format of its choice, and SEN never reads or writes them (loose coupling: the plugin decides how and when a change takes effect; a job that runs keeps the settings it started with).

What a plugin does (common/SettingsSession.h; Paperboy and the movie enricher are the examples: PaperSettingsForm.cpp, MovieSettingsForm.cpp, App.cpp; common/SettingsText.h reads and updates settings files of key = value lines without losing comments):

1. implement sensei::SettingsProvider: Describe() gives the settings as a BMessage (one field per setting, in its type: bool, integers, doubles, strings, times), a schema (per field name a message with label, help, kind, choices, min, max, step, ...: see SenSettingsForm.h; the form derives labels and controls from the types without one) and the defaults; Apply() gets the changed fields (each under its path key, which for a flat message is the name), validates, stores and names the ones it refuses;
2. keep a SettingsSession in the application and give it the messages (kSettings, kSettingsSet, kSettingsClose) in MessageReceived();
3. end the application when the session is over: IsEnded() after kSettingsClose, and Expired() (the window is gone, or it was quiet for a minute) in Pulse().

The window starts the plugin with the request (be_roster->Launch(file, &request)), so the plugin answers to the messenger in the request (kSettingsReply), and a multiple launch application is talked to at the instance that has the session. A plugin that does not know the request is asked to quit after a few seconds. sen_settings --plugin <file> shows the settings of a build of a plugin instead of the installed copy.

Where new entities go

A plugin that makes entities for a file (people for the authors of a book, the director of a movie) puts them into the Library of the current context (~/Library/People...), which the SEN server tells: sensei::FindOrCreateEntityFile() (common/EntityFile.h) finds the file of an entity by its name and what makes it the same entity (a key, an ORCID iD: a function of yours), in the Library and next to the file where earlier versions put it, and makes it in the Library if there is none; without a server it makes it next to the file as before. Do not make entity files in the folder of the file yourself. Entities are a core feature of SEN, so they are made by default: the settings of SEN (the node Plugins of the settings window) have Extract entities into Files (default: a rich entity with properties of its own, related to the file) or Attributes (only the plain names in the attributes of the file, the FAIR layer, for those who do not want entity files). A plugin asks sen::plugins::ExtractEntitiesIntoFiles() (SenPluginSettings.h) and, for Attributes, writes the names only (the Movie Enricher: schema:director, schema:actor; BERT and Paperboy: dc:creator is written in any case) and makes no entity files and no relations.