Request for comments: Trilium SDK

[mm21]

Problem statement

Trilium provides a very powerful mechanism to create extensions and an API for automation; it turns Trilium into your own custom app. However there are a few things which I think can help to fully realize this potential.

1. High level local automation
   By this I mean, it would be nice to run your own scripts locally and interface with Trilium. They can even serve a REST API which gives you a custom backend, basically using Trilium as a frontend for your own app. ETAPI is a perfect way to interface with Trilium, but it's a low level interface - there should be an abstraction on top of it.

2. Synchronization with a local folder
   Trilium has a robust note structure which is more powerful than a mere filesystem can represent, but I'm confident it can be done in a way that enables you to maintain your note tree locally in git and synchronize it with Trilium.

3. Extension development, distribution, and installation
   In order to facilitate sharing and reuse of Trilium extensions, there needs to be a developer-friendly mechanism to develop extensions and a user-friendly way to install them. Installing an extension should be no more effort than a pip install followed by a command to sync the package you installed to a specified destination in Trilium.

I think this could enable really neat features, like photo managers and AI assistants.

As far as I know, obsidian supports chatgpt because of plugins developed by third-party authors. A plug-in marketplace facilitates the creation of such plug-ins.

Originally posted by @SiriusXT in #3857 (comment)

Plan

I've started working on a Python package which is divided into 3 components, each of which will build on the previous ones. It's not in a shareable state yet, but I wanted to get feedback and ideas on the overall design, and the example Python note interfaces shown below. Once I have a stable enough API and docs I'll share it here.

Core: High level interface to work with notes/attributes/branches. Provides a way to define notes by subclassing the Note class. Attributes and parents/children can be accessed intuitively. This is about 95% complete coding wise, but I still need to write docs, so I'm hoping this part will be fully done by the end of June. This would be pretty useful if you're a developer and want to write your own custom automation. You can define a hierarchy of notes in Python and sync it to Trilium with just a few lines of code.

Extension: Uses core component to define a way to easily create and share Trilium extensions. An extension is just a Python file with classes which subclass Widget, Template, WorkspaceTemplate, etc. I've found things like attributes and note tree structures can be described very concisely in Python, so it should be really nice to maintain extensions this way. The structure of the extension is automatically generated, with child notes for "Widgets", "Templates", etc. For note content like js/css, you just maintain those files alongside the .py or in whatever folder you prefer.

Sync: Can install Python-defined note trees (one-way sync or "push") and sync (in both directions) arbitrary note trees from various formats. Plugin mechanism used to implement custom formats including markdown conversion to HTML notes, and even more advanced things like processing photos to generate thumbnails.

You can also use this to define your own custom folder structures which are parsed into notes. For example, say you have a folder called "Trips" and each folder under it describes a trip, with folders like "Days" and "Photos". Then you can write a custom plugin to convert each .md file under the "Days" folder to a note with a specific template or attributes. Takes a .yaml config file specifying which extensions you want to be installed, which folders you want synced using which plugins, and the destination notes for each.

This will be a big effort but I think it's all doable. I'm hoping to have it done by the end of the year, although I wouldn't be surprised if it took longer. But I'm building it because I need it for my own system - I really think having a local folder of notes that you can maintain in git and sync with Trilium, and maintaining extensions using Python packages, is the way to go.

Why Python?

I figured this may be a common question, so wanted to address it here. The main selling point for capturing note definitions and structures in Python is that it's a clean, declarative-oriented language. Javascript is great for imperative or functional programming, but I think Python is well suited for more of a declarative style of programming. For example you can define note structures by simply subclassing the base Note class or custom reusable Note subclasses.

Of course, extensions themselves are written in Javascript and CSS. The idea is to use Python to stitch together note attributes and structures, and leverage the package infrastructure. The .js/.css files to be installed will simply reside in the same package.

What's working

Here's a quick preview of some things you can do. This example shows how you could design a simple template to manage your phone contacts, and how you could automate maintaining it. Maybe you want to write a script to import your contacts from Google Takeout.

Declarative note definition

To start with, we create a mixin to represent an address which we can use in multiple different templates:

@label_def('streetAddress')
@label_def('city')
@label_def('state')
@label_def('zip')
class AddressMixin(NoteMixin): pass

This creates a reusable class encapsulating promoted attributes. @label_def creates a label definition, with promoted by default. It's defined as follows:

def label_def(name: str, promoted: bool = True, multi: bool = False, 
	type: 'text'|'number'|'boolean'|'date'|'url' = 'text', inheritable: bool = False):

This results in the label e.g. label:streetAddress=promoted,single,text. There's also @relation_def which creates a relation definition.

Then, say you wanted to embed an address in a Contact template:

@singleton
@label('template')
@icon('bx bxs-user') # equivalent to @label('iconClass', 'bx bxs-user')
@label_def('firstName')
@label_def('lastName')
@label_def('phoneNumber')
class Contact(Note, AddressMixin): pass

The class itself is generally empty, relying on decorators to define attributes and children. This enables a note to intuitively inherit the attributes/children of its ancestor classes rather than overriding them. (What you're doing when you use a decorator like @label is creating a new init method which is added to a linked list of methods. When the note is instantiated, this list is traversed and invoked to populate the note's attributes and children.) There is an init method you can define to inject your own arbitrary logic when the class is instantiated.

Attributes and children are ordered by Python's MRO. That is, attributes from more distant ancestors are added towards the end. This code results in the following template:

When you instantiate Contact you have a note with the labels template and iconClass, and a bunch of promoted attributes. @singleton makes it so the note's id is derived by the fully qualified class name, e.g. my_templates.Contact. Then every time you instantiate it, you'll get the same note and any updates will be automatically pushed to Trilium when you call context.flush(). At that point you don't even need a sync tool, you can just run a few lines of Python when you make changes.

Of course, Contact still needs to be placed in the note hierarchy. (I've just now hacked it up to add it to my root note.) You could have a "Templates" note which you create in Trilium and designate to hold your Python-maintained templates. Then you can represent it like:

@singleton(note_id='[note id of templates root]')
@children(Contact)
class Templates(Note): pass

Then when you instantiate Templates and call context.flush(), Contact will be automatically created/updated.

@children is used to add the provided classes as children. If the children of a singleton aren't also a singleton, an id is deterministically generated - this enables reuse of notes for different templates, like "TaskList" which you can place under both "Home" and "Work" and they'll be separate notes. (If you put a singleton note in more than one place in the hierarchy it will be automatically cloned.)

If there are no children specified, any existing children of a singleton will be deleted - so children of notes created this way can't be manually added by default. The system doesn't try to distinguish between children you created in the UI and children you previously set, but are just now deleting. If you want to maintain child notes in the UI, you have to simply use the @leaf decorator; this means you can't use @children, and when instantiated it won't tamper with any child notes.

Note automation

Say you wanted to programmatically create a note which has Contact as a template relation target. You first declare a class which has a template relation to Contact:

@template(Contact) # equivalent to @relation('template', Contact)
class ContactInstance(Note): pass

Then you similarly just instantiate it. The resulting object will be a new note with a template relation to the Contact template note created previously.

alice = ContactInstance()
alice.attributes['firstName'] = 'Alice' # creates or updates label

There's an intuitive way to access attributes via my_note.attributes, or my_note.attributes.owned / my_note.attributes.inherited. You can check if a note has an attribute by doing 'myAttribute' in my_note.attributes, or .owned / .inherited. If you prefer more verbosity, there are Label and Relation classes you can instantiate and add to the note; this also allows you to set inheritable on the fly. (Same for branches: there's a more succinct way and a more verbose way which allows access to prefix/isInheritable/isExpanded.) Position fields for attributes and branches are automatically maintained for you.

When a Note (or subclass) doesn't have note_id explicitly passed as a kwarg, and isn't a singleton, a new id is generated by Trilium when you call context.flush().

Alternatively, you could have done the following:

alice = Note()
alice.attributes['template'] = Contact() # creates or updates relation
alice.attributes['firstName'] = 'Alice'

Here's how to add alice to your "Contacts" note which is designated by the label contactsRoot:

# lookup note containing contacts
contacts_root = context.search('#contactsRoot')[0]

# add alice as a child
contacts_root += alice # equivalent to contacts_root.children += alice

alice.flush() # equivalent to context.flush(), or context.flush({alice})

The last major feature for the Core component which I'm still working on is managing note content. Currently you can set it like:

my_note = Note(title='My note')
my_note.content = 'My content'

# or
my_note.content = open('my_content.html')

You'll be able to specify content for subclassed notes by using e.g. @content('my_script.js'). This will be the basis for implementing extensions in the next stage.

Design overview

As hinted at above, the system keeps track of any changes you make and only commits them when you call the flush() API, either on the context (flush all notes/attributes/branches with changes) or on a particular object. This is known as a Unit of Work design pattern. Additionally it maintains a cache of notes, and each unique note has a single instance. The following illustrates how that works:

contact = Contact()
contact2 = Contact()

# same object was returned when Contact was instantiated a second time since it was declared as a singleton
assert contact is contact2

Objects are lazy-loaded; that is, note metadata and content are only fetched once you access them. Once fetched, it will remain cached until you explicitly clear it from the cache using my_note.invalidate().

Acknowledgments

There are already Python libraries aiming to abstract ETAPI; see trilium-py and pytrilium. This project is more about providing a high level interface (inspired largely by SQLAlchemy) and enabling an ecosystem of extensions in a common format which can be installed using a common CLI tool.

[mm21]

Tagging some folks for visibility: @zadam @Nriver @perfectra1n @soulsands @meichthys @SiriusXT @passionate2023 @BeatLink @mabeyj

[Nriver]

Looks great!

[perfectra1n]

This is very well spelled out!

When it comes to the Core functionality, makes sense. Providing abstractions that are easier to work with (but those that still allow you to access lower-level functionality when needed) is great. When it comes to the Extension functionality, I'd be interested in seeing more and more examples. I understand that you're hoping to leverage the Core functionality, but I'm not quite sure what use cases exist there. For the Sync, I'm interested to see the implementation of it.

For this to be successful, I think practical examples / documentation will be the lifeblood. I've always found decorators / class mixin inheritance to lead to a great deal of "where is this coming from?" "why was this used?". It looks very interesting, so I'm excited to see what it can do.

[BeatLink]

Pretty interesting. Might keep my eye on this

[soulsands]

It looks very good. The folder synchronization is great, and I really hope to see it implemented, as it can attract more users who do not use servers, thereby allowing trilium to receive more feedback.

As for language, I personally think that TypeScript may be more suitable. It also has decorators, and is much more maintainable than JavaScript. For an SDK, stability is very important. Moreover, it is more compatible with JavaScript and is in the same technology stack, making it more conducive to collaboration with trilium. At the same time, people who write extensions are more likely to be familiar with JS/TS, which also lowers the barrier to entry for extensions.

I hope to have an SDK that can use trilium's UI components, interactive functions, and even the database more freely, although the database is also related to synchronization issues.

If it's TypeScript, extensions can be directly published to npm.

An official extension repository can be created, and extensions can be updated via pr, and the source code can be reviewed by everyone. Extensions provide some metadata, including version, installation scripts, download links, etc. Trilium can maintain installed plugin information and available plugin information in a simple way.

@zadam 's opinion is very important.

[zadam]

Well, I agree that using TypeScript/JavaScript would make adoption easier. The requirement of having to use/know 2 quite different languages is quite restricting.

But ultimately I see this project as distinct from the "core Trilium" and therefore don't really feel like my opinion has any weight here. Having a more standard way to distribute extensions is one of the long term goals and this project could provide inspiration even if based on Python.

[mm21]

Thanks all for the feedback!

@perfectra1n,

When it comes to the Extension functionality, I'd be interested in seeing more and more examples. I understand that you're hoping to leverage the Core functionality, but I'm not quite sure what use cases exist there.

Thanks for bringing that up. So the idea of the declarative (subclassed) note feature in trilium_sdk.core is to specify a whole note hierarchy as cleanly and maintainably as possible. In fact I started this originally so I could capture my own Trilium system (templates and scripts, themes, etc) in Python - just the "app" part of it, but not my personal data. I wanted to do that for maintainability first, but since there's good infrastructure for sharing Python packages I realized you can automatically share whole note hierarchies, of which extensions are merely a subset.

Another thing you get for free is the ability to sync it to Trilium. To install an extension, you could just instantiate the root note and then call flush(). Trilium objects (notes/attributes/branches) are then created/updated/deleted as necessary to reflect the state produced by the combination of decorators, inheritance, etc. The sync tool will do that for you as it will know how to install extensions written using trilium_sdk.extension, but in the meantime doing that manually will be an easy way to try things out.

Here's an example of what a theme would look like using trilium_sdk.core, without any of the extension helpers in trilium_sdk.extension:

@singleton
@note_type('code')
@mime('text/css')
@label('appTheme', 'MyTheme')
@content('my-theme.css')
class MyTheme(Note): pass

Then there would have to be some kind of registration or heuristic discovery to identify what kind of extension it is. But using trilium_sync.extension, you could just subclass a base Theme class:

from trilium_sdk.extension import Theme

@content('my-theme.css')
class MyTheme(Theme): pass

This way it's very concise, and as a bonus it can be automatically discovered by the trilium_sdk.sync tool and installed in the appropriate structure, e.g. subclasses of Theme under a "Themes" note.

Here's an example of a widget using only trilium_sdk.core:

@singleton
@note_type('code')
@mime('application/javascript;env=frontend')
@label('widget')
@content('SyntaxHighlightWidget.js')
class SyntaxHighlightWidget(Note): pass

And the same using trilium_sdk.extension:

from trilium_sdk.extension import Widget

class SyntaxHighlightWidget(Widget): pass

Here the default @content is based on the class name. (Not implemented yet, I just thought of it as I wrote this.)

Some extensions may be customizable by adding attributes. Users could then take an extension and subclass it, adding their own @label, etc.

Another interesting implication is that extensions can use other extensions, or resources from them like individual scripts. That could be done by simply importing them. Here's how a widget widget_a can use a script which is maintained in extension_b:

from extension_b import ScriptB

@children(ScriptB)
class WidgetA(Widget): pass

Since WidgetA is a parent of ScriptB, it can use functions defined in it. The neat thing is the user doesn't even need to have extension_b installed. If they do, ScriptB will be cloned to WidgetA; if they don't, it will be created. It would then be naturally deleted if widget_a was uninstalled.

Besides Trilium scripts, there could be whole Javascript libraries reused amongst different extensions this way.

I've always found decorators / class mixin inheritance to lead to a great deal of "where is this coming from?" "why was this used?".

I feel that for sure.

@soulsands,

Thanks for the thoughts, I see what you're saying. I definitely thought about that, but ultimately I felt it comes down to preference, and I happen to have a strong preference for Python. I think its readability and philosophy is great for this sort of thing. Just learned a bit about decorators in TypeScript just now and it's pretty neat. I think I'm too deep in the Python ecosystem myself, but don't see why they couldn't coexist if someone wanted to build that in TypeScript.

[zadam]

This is some interesting stuff. I can't at this point give a detailed feedback - some of these approaches are quite different from the line of thinking I use to have (e.g. the "notes as code" approach) and can't really fathom all the consequences. That's not a criticism, I'm curious to see some novel approaches, esp. if they could breathe some fresh air into topics which I've thought about (e.g. extensions), but couldn't form a conceptualization which I'd like.

[mm21]

Thanks @zadam for the thoughts.

After thinking about this more, I don't like the idea of having a particular language/package manager as the main delivery mechanism for extensions. This will inevitably fracture the ecosystem, with extensions you can only install if you use a certain package manager.

I'm working on a filesystem-based note tree format specification for use in trilium_sdk.sync, and I'd like to propose that as a language-agnostic standard for extensions and custom tools. Since you can capture an arbitrary Trilum tree as a filesystem tree, it could work well as a standard extension format. Extensions written in a language-specific way could then be simply compiled into this format for installation by trilium_sdk.sync or any other tool which can use the format.

This format is designed to be as concise and maintainable as possible. Therefore you don't have to specify things like positions of attributes/branches, and note/attribute ids are deterministically generated based on the file path. I envision to simply maintain a .yaml of note metadata alongside an optional file with the same base name representing the content. So an extension directory structure would look like:

MyExtension/
  myStylesheet.css
  myStylesheet.yaml
  myWidget.js
  myWidget.yaml

Extension developers could maintain this structure manually if they didn't want to go the language-specific route.

There would similarly be a need to share extensions in a way which isn't language-specific, but accessible in a standard format by tools. I propose using GitHub itself - you could simply put a URL to the extension repo in a config file, and the tool could manage syncing and installing it. There could be separate ecosystems of Python- and JavaScript-based extensions for "notes as code" approaches, but they would all be compiled into the same format and installed in the same way.

I'll publish the documentation for this and raise a separate RFC for further discussion, but I'd be interested in any comments in the meantime.

[zadam]

This kind of goes in the direction of what I was thinking about the extension basics.

There is actually already a language agnostic way to declaratively describe a directory structure with all the attributes and metadata - the export format. Check the demo.zip and specifically the !!!meta.json file. It is already being used as an ad-hoc mechanism to transfer and "install" extensions.

So my line of thinking was to basically leverage this existing format and build some infrastructure around it. The idea with using github seems good, but there are some other issues:

• the extension itself should remain immutable, so that it can be automatically updated. On the other hand, it will likely need to store data/configuration somewhere - where? In the hidden subtree? Will we allow multiple instances of the same extension? Should each instance have its own config/storage and where (given that an extension doesn't really know much about the structure of the host database)?
• github for storing extensions is a good idea, but do we also need some registry?
• do we handle version compatibility of extensions in some way? Declaring that the extension is compatible with versions >= X.Y is clear, how about with future versions possibly breaking compatibility?
• what's the extension development workflow? GitHub would be used for versioning and distribution, but for testing, the extension has to be loaded into trilium. Would that be handled perhaps with some ETAPI tooling doing the sync between file system (backed by git) and trilium? (I guess that's where your sync module might be useful)

Not all the issues have to be solved beforehand, but still worth thinking about.

[mm21]

Thanks - I studied the zip format to evaluate if it would work for my use case, but concluded it's more of a machine-friendly format than a human-friendly one. It definitely makes sense for Trilium to work with this format, but I think there's still a case for a separate human-friendly one.

To expand on why I think this is needed, I have a "text first" way of thinking about PKM. That is, I subscribe to the idea that your knowledge database should be accessible primarily in a maintainable text format (usually Markdown files) with which you can track changes using SCM. I think enabling this format with third party tooling will open up Trilium to many users of Obsidian and the like, and I imagine they would be very interested in moving to an app which is open source and truly free.

But there's a lot of complexity in designing such a human-friendly format, and I wouldn't expect that to be handled by Trilium itself. I'd be happy to take on the tooling to convert to/from Trilium's zip format as needed.

Maybe there could be an ETAPI interface to import a zip file. Then there could be tooling to automate both installation and zip exporting.

the extension itself should remain immutable, so that it can be automatically updated. On the other hand, it will likely need to store data/configuration somewhere - where? In the hidden subtree? Will we allow multiple instances of the same extension? Should each instance have its own config/storage and where (given that an extension doesn't really know much about the structure of the host database)?

Good point. Personally I'd really like for my extensions and config to be installed separately from my notes, say the Options subtree. Something like how Launch Bar works would be great I think, and maybe Enabled/Disabled subtrees like Visible/Available Launchers.

For extension config/data, maybe the extension could actually be installed under another layer of notes which acts as configuration. These would simply define inheritable attributes which are passed down to the installed extension. There could be inheritable relations to designate external user-provided notes containing data.

Alternatively extensions could be automatically cloned to a user-provided note with a label like #extensionDataRoot, or just manually cloned by the user, and the user would similarly define inheritable attributes to configure them.

I kind of think it should be the user's responsibility to ensure there's only one instance of each extension, that extensions are compatible, etc. I'm thinking about generating noteId for my extensions as a hash of the extension name, which would naturally enforce only one instance of it being installed.

what's the extension development workflow? GitHub would be used for versioning and distribution, but for testing, the extension has to be loaded into trilium. Would that be handled perhaps with some ETAPI tooling doing the sync between file system (backed by git) and trilium? (I guess that's where your sync module might be useful)

I was indeed hoping the sync tool could be useful for extension development - it would just be running a command after making changes. Long-term I'd like to have a "watch folder" feature where you can automatically update Trilium with changes from a local folder.

[mm21]

Hi everyone,

Wanted to give an update here: things are coming along smoothly, albeit not as quickly as I was hoping. Right now I'm looking at the end of July for an initial release.

Also, we have a name: TriliumAlchemy!

Here's an example from the user guide of cloning your todos (identified by the label #todo) to today's day note:

from trilium_alchemy import Session, Note
from datetime import date
from my_secrets import HOST, TOKEN

with Session(HOST, token=TOKEN) as session:

    # get todos
    todo_list: list[Note] = session.search('#todo')

    # clone to today's day note
    today: Note = session.get_day_note(date.today())

    for todo in todo_list:
        today += todo

    # new branches created upon exiting context

[jwhonce]

@mm21 Do you have a pointer to a repo I could peek at? I am playing with a CLI for Task Manager demo and am interested in your attribute/label handling.

[mm21]

Hi, I'm planning to have the repo up soon. That sounds like a perfect application for it.

[meichthys]

Hi @mm21 Just to confirm, is this the repo?
https://github.com/mm21/trilium-alchemy

[jwhonce]

@meichthys Yup