Simple API service that provides a variety useful API services to complement your daily use of Tana
All payloads are in JSON (with the exception of one, documented below). All results are in Tana paste format unless otherwise stated.
See the Tana Publish page for more usage information and examples
There's also a Tana template that you can load into your Tana workspace with all the Tana commands preconfigured, demo nodes, etc.
A number of the capabilities of tana-helper need OpenAI and other services. For these, you'll need an OpenAI key.
This service is intended to be run as a local server. It also has some experimental support for hosting on Deta Space. See Webhooks README for details.
tana-helper includes a python base API service and a React Typescript web app.
You can either install from source (instructions below), or if you are on a Mac you can try the pre-built .app package. Check the Releases section of this github repository for latest downlodable .dmg disk image.
Mac OS app bundles have been tested on Monterey (12.x) , Ventura (13.x) and Sonoma (14.x) on both Intel and Apple Silicon. If you have any problems with these, please add an issue here or come find me on the Tana slack community.
To launch tana-helper, double-click the Mac .app. You'll get a menu bar app with a single Start tana-helper menu item. This will launch a Terminal window with showing the log as the helper service starts up.
(Coming sometime!)
First, using a terminal app, clone this git repo:
git clone https://github.com/verveguy/tana-helper.git
And change into the source directory before proceeding.
cd tana-helper
Install homebrew if you don't already have it (will install XCode tools if required)
/bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)“
brew install python@3.11
brew install node
brew install yarn
brew install create-dmg
Add python install location to PATH
Edit ~/.zprofile or whichever shell you use
echo “PATH=$PATH:/usr/local/opt/python@3.11/libexec/bin/” >> ~/.zprofile
source ~/.zprofile
pip install poetry
cd release
./build.sh
(instructions coming soon!)
For Windows 11:
.\\.venv\\Scripts\\Activate.ps1
If you have problems doing this due to "Execution Policy", open PowerShell as Administrator and do set-executionpolicy remotesigned. This should let you run the virtualenv Activate.ps1 script)
Then you can start the service:
cd service
uvicorn src.main:app
(If you want to hack on tana-helper, run it with --reload to ease development iterations)
If you want to host this service somewhere, there's experimental support for Deta Space in the main branch. Learn more about Deta Space here.
However, there's something wrong with Tana Proxy fetch right now...
There's a few different services provided by tana-helper: you may not want all of them.
You can remove services by modifying the file src/main/py. Comment out the line for the service you don't want.
See the Tana Publish page for more usage information and examples
There's also a Tana template that you can load into your Tana workspace with all the Tana commands preconfigured, demo nodes, etc.
Inspired by the marketing visualization on the Tana.inc website, tana-helper provides a 3D visualization of your Tana workspace.
Check out this video demo
For details, see Visualizer README
Based on the inspiring example from @houshuang (see recording), tana-helper now provides a powerful form of webhook processing.
Basically, you can shovel any text, email, etc at the /webhook/<tana_type> endpoint and it will process it into JSON using OpenAI and push the resulting JSON into Tana via the Tana Input API.
So you can call this webhook from pretty much any integration platform such as Zapier or for email, use the cloudmailin.com service as @houshuang did.
See Webhooks README for more details.
ChromaDB, Weaviate and Pinecone are all vector databases that let you take arbitrary chunks of text, turn them into "embeddings" (vectors) via OpenAI and then store. Why do this? So that you can take some other chunk of text, turn it into a vector and then use that vector to query your database.
This is a very powerful idea. It basically means Tana can have full semantic similarity search today, while we wait for Tana themselves to make this magical as part of the product.
There's three variants offered by tana-helper: ChromaDB and Weaviate (both local on your laptop) and Pinecone (hosted service). The latter requires a Pinecone account and you will need to create a Pinecone index within a Pinecone "environment" (Region). The default index name is tana-helper although this can also be configured.
For details, see the Tana templates located at https://app.tana.inc/?bundle=cVYW2gX8nY.G3v4049e-A
See Pinecone README for more details.
This is a useful addition to Tana depending on your workflow. Basically, it lets you take notes from say, a meeting, where you've used inline refs to link the note to various concept nodes and then "push" the new note to those concept nodes rather than just relying on the backlinks UI in Tana. (Which I find very limiting and disruptive to my reading flow)
/inlinerefs Given a node, finds and returns all inline refs as fields in Tana paste format.
See the Tana template for more information.
Ever want to run some chunk of code inside Tana? Well, now you can (kinda).
/exec Executes an arbitrary chunk of python code passed as a parameter. Useful for adding simple functions to Tana.
/exec_loose Same thing, but without the strict JSON format parameters requirement. Allows use of Tana formatted code nodes.
See the Tana template for more information.
Makes it easier to call external services that expect JSON. Let's you proxy requests to the external service via tana-helper, converting Tana nodes on the way in to JSON and converting JSON responses back to Tana nodes on the way back.
The Calendar API previously supported by tana-helper has been moved out to tana-calendar-helper. Why? These features are only available on a local Mac and so it was confusing to have Mac-only features in this service, which is intended to be run on a hosted server supporting team usage. It also let me rewrite the calendar helper in go for portability on different Mac architectures whereas this project is now pythonic.
(NOT YET POSSIBLE. SEE /usage)