🤝 Tana Helper

Overview & Installation

One of the great things about Tana is that it is able to call external systems via the Make API request command. Not only can it make calls to internet services with APIs to fetch data into Tana, you can also pass existing Tana node data to these APIs and then receive results in return. The results of these calls can be added as new Tana nodes or can be used as input to further features like the built-in AI integration.

In my own daily use of Tana I have found myself wanting various enhancements to Tana – things that aren’t built-in already. The Make API request command gives me the ability to call out to custom code. Importantly, that code doesn’t have to run “on the internet” somewhere but can in fact run on my local laptop via the Avoid Proxy setting of Make API request. As a software engineer, this really opens things up for me.

And so I built a small service called tana-helper and started adding functions to it.

GitHub – verveguy/tana-helper

Small web service to handle API calls from Tana and do useful things

tana-helper is open source, licensed under the MIT license, and is completely free.

Installation

If you use a Mac the simplest way to get tana-helper running on your laptop is to download the double-clickable Tana Helper.app. This should work on any Mac running Mac OSX 12 (Monterey) or newer with either Intel or Apple Silicon. Open the .dmg and drag the Tana Helper app to your Applications folder.

For Windows users, there’s now also a Windows executable packaged as a tar.gz file. See Releases · verveguy/tana-helperYou’ll need to unpack the tarball which will create a folder. Put this anywhere you like.

If you are a developer and want to play with the code, you can get the tana-helper service running on your laptop by following the instructions at: GitHub – verveguy/tana-helper: Small web service to handle API calls from Tana and do useful things. (follow README instructions. ⚠️ Needs developer knowledge).

Running

For Mac users, just double-click the Tana Helper app. This will add a menu bar helper icon with a very simple menu. Starting tana-helper from the menu should launch a Terminal window showing you the log as Tana Helper runs and handles requests.

For Windows users, you can either launch the tanahelper.exe which will give you a small menu tray app which you can right-click to get the action menu. Or you can double-click the start.exe which should just launch a terminal window showing the log as tana-helper runs.

Tana configuration

Once you have the tana-helper service running, you’ll need a set of Tana Command nodes to call it. The best thing to do is load this content with all of the commands as a Tana template.

Once you’ve done that, you will need to configure a few secrets – as you try to use each command, Tana will prompt you. If you want to use the AI related features (including vector databases), you need to have an OpenAI key and have turned on Tana Labs —> AI For Builders in your Tana settings.

To make it easier to setup your tana-helper base URL, I’ve used the Tana support for secrets. The first time you run one of these commands in Tana, you’ll be prompted to fill in the value for the HelperURL. If you are running locally, use http://localhost:8000 (or whatever port you’re running on if you’ve tweaked the build). For server deployments of tana-helper, configure appropriately (some help is in the README on github).

Background

Calendar integration

I spend most of my day on zoom talking to various people about a lot of topics, including projects and technology. So most of my workflow in Tana revolves around meetings. Not surprisingly, the first example of something I really really wanted was fetching my Outlook calendar and making a series of #meeting nodes in Tana, pre-populated with the names of the people I was meeting with. I was able to write the code for this (originally in Swift) and then call it from Tana. That code is now included here in tana-helper. (See 📆 Import Calendar into Tana (Mac only))

Building up knowledge

As I take notes in these many meetings, I often create inline references to #topic nodes. Topics might be projects, technologies, events, etc. Each of these probably exists in my library, created at some earlier time. So meetings are one of the main ways I accumulate more knowledge about these topics. Most meetings also touch on more than one topic, and also have extraneous notes in them as well. So I can’t just organize each meeting neatly under a topic. After using Tana for a while, I found that I wanted to copy those notes to the Library nodes themselves rather than have them only appear in my meeting notes. Over time, this let me build up more and more knowledge of a topic through many conversations with my #topic nodes accumulating all that knowledge. (See 📌 Harvesting inline references).

People have asked me why the “References” section at the bottom of a node panel isn’t sufficient – why did I want the actual content moved to the node? Initially it was a UI thing: the references section is way down the bottom of the panel. But the more important reason now is that I really want a topic node to contain the accumulated content so that I can embed the whole node it in a vector database with all of the relevant content included.

This is because, as I build up these #topic nodes, I want to query many of these same topics by semantic content rather than just text matching. I want to find topics that are similar or related in ways that perhaps aren’t initially obvious. Since Tana can’t do that (yet), I was able to write some code to copy the nodes to an external vector database as “embeddings” computed by OpenAI which I could then search by “semantic proximity” to any question I might want to ask of my own notes. Two Tana Make API commands are then all it takes – one to upsert a topic node into the database, and one to query the database using my current node as the “similarity” query. The vector database I originally chose was Pinecone, but a better choice now is ChromaDB, which stores all the data locally. (I now support Weaviate as well.) (See ↖️ Using Vector databases with Tana)

As of the 0.3.0 beta releases, you can now import your Tana JSON Export file directly into ChromaDB via the tana-helper web UI. Use the “RAG Index” menu and the Upload button. This will walk your entire Tana workspace, finding all tagged nodes and treating them as “topics”. It will embed all the child nodes such that, when you use the Query Chroma command, you will get the topic nodes as references back to Tana whenever a child node matches your semantic query. You can also change the Query Chroma command parameters to get back the smaller child fragments (”returns”: “node”), or ask for both topics and fragments. (”returns”: “both”) There’s even a mode for returning the topic node as an inline reference with the matching fragment nested within it. (”returns”: “nested”). You can also incrementally update to future versions of your workspace – just save a new Tana Export JSON file and use RAGIndex->Upload again. Only nodes that have been added or changed will be re-embedded. See this video demo for a quick tour.

Integrating with things

A lot of working with Make API commands is dealing with JSON and Tana Paste. Unfortunately, Tana doesn’t yet have automated conversion between these formats and so I added helper functions to do that as well. Inspired by my own needs and the needs of other folks in the Tana community, I added 🔠 Functions for JSON / Tana Paste bi-directional conversion and 🚪 Tana Helper as JSON proxy gateway. The Tana Paste to JSON conversion also allows for a “CSV export” in case you want to dump tables of data from Tana in CSV format.

Pushing data into Tana

An interesting diversion has been working out how to push data into Tana from the outside world. Make API is great, but you have to initiate those calls from within the Tana UI. I also want to be able to push data into Tana, even when it’s not running. Thankfully the Tana Input API came along which gives us the first step. Sadly, it doesn’t support Tana paste, and thus requires a lot of a priori hard-coded knowledge (e.g. tag node ids and field schemas) to be effective for more than simple text nodes. In order to ease the burden a little, I built 🪝 Automagic Webhooks for Tana Input API and more recently, the 📥 Tana Paste Input Queue features.

Tana Functions

I think someone asked a question in the Tana slack community about whether Tana might have functions in the future.Since most of tana-helper is written in python, and many of the functions are relatively short, I decided I’d try and have code written in Tana passed to tana-helper on the fly. The result is covered below in 🐍 Running user-defined python .

Visualization

And then, truly “just for the sake of it”, I built the 🌃 Tana Visualizer. It’s a small webapp included in tana-helper that lets you do things like this with a JSON export of your Tana workspace:

Recording: CleanShot 2023-06-08 at 22.13.31

So in summary,tana-helper does a bunch of useful stuff, all made possible by the built-in Tana Make API request command. Each command calls a different API ‘endpoint’ of tana-helper; you can think of it as a kind of “swiss army knife” of services.

Features

📆 Import Calendar into Tana (Mac only)

This feature allows you to pull your calendar into Tana via the Apple Calendar API. It uses your Apple Calendar configuration to act as a “gateway” to your calendar services. This allows it to reach iCloud, Google and Office365 calendars.

The /calendar endpoint will by default return you a list of your meetings for a given date from a calendar named “Calendar”. If no date is specified, defaults to the current date.

You can change things with the following JSON payload. All fields are optional.

{
  "me": "self name", // your own name to avoid adding you as an attendee
  "meeting": "#tag", // the tag to use for meetings defaults to #meeting
  "person": "#tag", // tag for people / attendees defaults to #person
  "solo": true | false, // include meetings with just one person (yourself?)
  "one2one": "#tag", // tag for 1 to 1 meetings, defaults to #1:1
  "calendar": "Calendar", // the name of the Calendar to read from
  "date": "2024-03-21" // date to fetch (defaults to Today)
  "offset": -n, | 0 | +n // how many days before or after today to start from
  "range": &gt;= 1, // how many days to retrieve. Defaults to 1
}

Commands

Get Today’s Calendar

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Usage

Make sure the Apple Calendar app is running (you may get an error response if it isn’t. The script will auto-launch it but sometimes the first time it hasn’t started yet)

cmd-K “Get Today’s Calendar” should fetch your calendar entries for today and insert them into your Tana workspace as children of the current node.

You can tailor the options by adjusting the Payload field of the Get Today’s Calendar command Make API node.

Make sure you set the “calendar” property of the Payload field. Set it to the name of your calendar as it appears in the Apple Calendar app.

The most common cause of problems is that you ask for a calendar that does not exist. The script defaults to Calendar as the name of your calendar. You can change this by passing ”calendar”: “<your calendar name>” in the JSON payload.

↖️ Using Vector databases with Tana

If you’re interested in using a vector DB with your Tana nodes, I have three variants all working – Vector Database for Vector Search | Pinecone (hosted service), the AI-native open-source embedding database (local on your machine) and Welcome | Weaviate – vector database (also local). You also need an OpenAI account.

What is a Vector Database?

Basically, a vector database is like any other database in that it stores records which can later be queried.The difference is that what is stored is an “embedding” – which you can think of as a “magic number” that somehow captures the meaning of a chunk of text. These embeddings are generated by OpenAI. You give it text, it gives you an embedding.

Once you’ve got a bunch of these embeddings stored in your vector database, you can then query it “by example”. By this, I mean that you take some new chunk of text, get the magic embedding for it and then ask “give me all the stored embeddings that are ‘close’ to this new embedding”.What comes back are a set of previously stored embeddings, each with some measure of “distance from” or “similarity to” the embedding in question. And each can also have an ID or other reference back to the original source text. In my case, the Tana node ID.This capability is sometimes described as similarity search or semantic search. The idea being that these magic numbers somehow encode the meaning.

The reason they’re called vector databases is because the embedding is actually an array of numbers. In the case of OpenAI embeddings, 1536 numbers per embedding. And the math they do to figure out “similarity” is vector math.

What can I do with one using Tana?

Using the following Tana commands, you push your Tana Nodes into the vector DB and then query that database to get back a list of relevant nodes. They will appear as references in Tana, just like a native Tana Query does.

So it’s basically a form of “semantic search” for Tana, powered by OpenAI and your choice of vector database.

Vector database options

📌 Harvesting inline references

This section contains commands to push a single node to one or more inlines references that the node contains. There are two commands involved and a small helper function provided by the tana-helper service. (Source code at GitHub – verveguy/tana-helper)

Use case: While in a meeting, you are taking notes on various topics, and you reference the topics inline in these notes. The meeting is a day/time/place oriented structure that is complete once the meeting is over. The topics you discussed however are quite probably ongoing, or even “evergreen”. At the end of the meeting, you wish to push the various notes you took to the nodes that represent each topic discussed.

Video Explainer

Example scenarios

Topics that are long-lived

Upcoming Holiday Party

Really tricky customer project

Highly confidential invention

Meetings

Weekly staff meeting with John and Jill

Date

Sun, May 28, 2023

Time

15:00

Place

Somewhere

Attendees

John

Jill

Jack

Tasks

Many Tasks

We started with a round of hellos and personal catch ups. John has a new partner. Congrats, John!

The Really tricky customer project is having some problems. It seems that the project scope wasn’t properly defined early on and now we’re facing serious over runs due to scope creep.

Our Upcoming Holiday Party is on track although there are problems with the entertainment. Seems we can’t get the act we originally wanted as so Jack is looking for alternatives.

Jill presented an update on the Highly confidential invention and noted that we really want the patent application to be filed before the Upcoming Holiday Party so that we can make a big announcement to all the staff at the event.

A node that can be referenced

Unplanned meeting with Dave and Jack

Date

Sun, May 28, 2023

Time

15:00

Place

Somewhere

Attendees

Dave

Jack

Tasks

Many Tasks

Houston, we have a problem.

Said someone, once.

A node that can be referenced

Commands: There are two commands implemented:

Find inline refs

This command finds all inline refs in a given node and adds them as node references to a field named `inline refs`. This field is intended to be used by related the Push node to inline ref command. This command uses the tana-helper server to actually extract the inline references. Note that one inline ref field is added per inline ref which might seem off at first but is important to the operation of the Push node command.

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Push node to inline ref

This command grabs one of the inline ref fields on the current node and moves the current node to the node referenced by the inline ref field. It then removes the inline ref field itself. If the current node has no inline ref fields, it does nothing.

Move node

System command. Params: *Move node target, Remove reference after moving node, Move original node

Remove fields

System command. Params: *Fields to remove

patent

event

project

meeting

🐍 Running user-defined python

There’s been many times when I’ve wished Tana had a way to just “run some code”. The ability of OpenAI to kinda do code-like things has been great, but I still want the predictability (and speed!) of simple coded solutions for many things.

So saying, I decided to add a little function to the tana-helper that lets the user craft a Tana command that runs an arbitrary chunk of python code against some passed in params.

Video Explainer

Commands. There are three commands involved:

User function with inline code (CURRENTLY BROKEN \n HANDLING BY TANA)

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

User function with loose inline code

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

User function with indirect code

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Examples

Hello, world! using inline code

Hello, world! using loose inline code

something

(A different time and place)

Hello, world! using indirect code. Note: if you use Tana code blocks, you must select “python” as the language. Otherwise, the helper service won’t know to remove it from the code before evaluating it.

code

import re def do_something(): result = ‘Welcome to ‘+something+’ [[^’+ nodeId + ‘]]’ return result

call

do_something()

something

(another time and place)

Dynamic templates

One thing that is hard to do in Tana is have a tag chosen indirectly. Andre Foeken was trying to do this recently so I used the Tana helper feature to solve the problem in one way.

Brett Adam

meeting tag

brett meeting

Add 1:1 meeting

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

🪝 Automagic Webhooks for Tana Input API

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.

But how does the external service reach my local tana-helper service? Using something like ngrok you can open a tunnel back to your local machine, exposing only the tana-helper port 8000.

Note that when your external service calls these APIs, it must pass your Tana API Token via the X-Tana-API-Token HTTP header otherwise tana-helper will not be able to insert anything into Tana.

NOTE: So far, I’ve found that GPT3.5 does very poorly at this task, whereas GPT4 does well.

Commands

Create webhook from schema

This command creates a new webhook endpoint in tana-helper, which you can then call to push arbitrary data into Tana via the webhook. You will need to execute this command on a node that has a ‘typescript schema’ field that contains the Tana schema of the supertag you wish your webhook to use.When invoked, the webhook will call OpenAI GPT to process the text payload and produce JSON which will be pushed into the Tana Input API. (See Tana documentation on using the Input API for more information).

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Example:

The following Tana node and commands allow you to try out the creation of a webhook and then the invocation of it with test data. Note that you will want to update the schema to be your own schema – this is my schema from my instance of this Tana Helper workspace.

Test webhook locally

This is a local test command to simulate calling the webhook “for real”. It will call the webhook URL and push some Tana node data into it which the webhook will then parse via OpenAI GPT into a JSON structure. The JSON will be returned here as well as pushed into the Tana Input API.

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

webhook

flight

Add a webhook for flights

supertag

flight

typescript schema

type Node = { name: string; description:string; supertags: [{ /* flight */ id: ‘6VD3LyFIV5’ }]; children: [ { /* Price */ type: ‘field’; attributeId: ‘ab4e0ZhLJZ’; children: Node[]; }, { /* Passenger */ type: ‘field’; attributeId: ‘gyXW-sDZAC’; children: Node[]; }, { /* Arrival time */ type: ‘field’; attributeId: ‘05lU87Osx9’; children: Node[]; }, { /* Departure time */ type: ‘field’; attributeId: ‘mIFn7Uyt-G’; children: Node[]; }, { /* To airport */ type: ‘field’; attributeId: ‘BcuysCHdR_’; children: Node[]; }, { /* From airport */ type: ‘field’; attributeId: ‘DybG3gf_aT’; children: Node[]; }, ]; };

hook URL

http://localhost:8000/webhook/flight

test data

Welcome to Hawaii!

Flight AL 3622

Leaves BOS at 14:40 on April 1 2023

Arrives AUA at 18:53 on April 1 2023

Passengers: Brett Adam, Karanina Minotti, Violet Becker

Total flight time: 5h30m

Supertags

sport

video.other

flight

meeting

project

event

patent

object

supertag

command

webhook

person

website

shared

template

brett meeting

brett

🔠 Functions for JSON / Tana Paste bi-directional conversion

A small command and associated helper service that will take your current node and its full context and convert it to an equivalent JSON structure. Useful perhaps when you then need to pass a JSON structure to some other command. These functions are used elsewhere by Tana helper but I figured they were also useful standalone to save you a round-trip to Chat GPT just to do JSON conversions.

There are two variations of JSON supported: the first is “Tana JSON” – a set of simple Tana nodes that are structured in a JSON-like structure, one line per Tana node. The second format is actual JSON stored in a formatted Tana node of type “code”.

🐛 Right now, Tana is inconsistent in a variety of ways when it comes to sending Tana structures as payloads. Code blocks in particular are not properly nested so you can’t preserve their structure. Also when receiving back Tana paste format, Tana treats code blocks in weird ways, again incorrectly nesting them beyond the first level of node structure.

The Export to JSON command can also be Export to CSV by putting ?format=csv on the URL. (if you leave format off, it’ll default to json)

Commands

You will want to modify the Target node of these commands for your use cases – right now, they’re set up here for demonstration purposes, populating the various “Output” nodes in the demo section below.

Convert to JSON

Takes a Tana node structure and converts it into the closest logical JSON equivalent. The result is a set of Tana nodes structured as if they were JSON. (“Tana JSON”) Make sure to set the Target node to something logical for your use-case.

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Export to JSON

Take a regular Tana node structure and converts it into the closet logical JSON equivalent. Saves the results to a temporary file on the tana-helper server. (Typically localhost:/tmp/tana-helper/export/). Also allows for CSV with format=csv query param.

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Convert to Tana

Takes a Tana JSON structure and converts it into the logical Tana paste equivalent without requiring roundtrips to Open AI.

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Convert to JSON code node

Converts the Tana node structure to JSON and then returns the result as a Tana node formatted as code.

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Convert code node to JSON

Converts a Tana code node to an equivalent set of Tana nodes formatted in Tana-JSON representation.

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Demonstration

Testing JSON / TANA conversion commands

Test node for conversions – try this Search code

Meetings

Weekly staff meeting with John and Jill

Unplanned meeting with Dave and Jack

A node that can be referenced

Time

Tomorrow

Place

Nowhere in particular

Output node for convert to JSON command

Output node for convert to code node command

Output for convert to Tana

Demo data

Meetings

Weekly staff meeting with John and Jill

Date

Sun, May 28, 2023

Time

15:00

Place

Somewhere

Attendees

John

Jill

Jack

Tasks

Many Tasks

We started with a round of hellos and personal catch ups. John has a new partner. Congrats, John!

The Really tricky customer projectis having some problems. It seems that the project scope wasn’t properly defined early on and now we’re facing serious over runs due to scope creep.

Our Upcoming Holiday Partyis on track although there are problems with the entertainment. Seems we can’t get the act we originally wanted as so Jack is looking for alternatives.

Jill presented an update on the Highly confidential inventionand noted that we really want the patent application to be filed before the Upcoming Holiday Partyso that we can make a big announcement to all the staff at the event.

A node that can be referenced

Unplanned meeting with Dave and Jack

Date

Sun, May 28, 2023

Time

15:00

Place

Somewhere

Attendees

Dave

Jack

Tasks

Many Tasks

Houston, we have a problem.

Said someone, once.

A node that can be referenced

Bugs

A complex example that shows various bugs in Tana send and receive handling

Code

This is a block of code multiple lines Trying this out to see what happens Oh boy! if trash_node is not None: trash_children = trash_node.children if trash_children: for node_id in trash_children: if node_id in index: trash[node_id] = index[node_id] #del index[node_id]

Next field

Something good

All for the good

And the bettermemt of my friends

A field

Another value

🚪 Tana Helper as JSON proxy gateway

This is a small demo of how you can use the tana-helper service to act as a proxy gateway to other API endpoints, converting Tana nodes to JSON on the way out, and converting JSON responses back to Tana paste format on the way back. It uses the functions in the 🔠 Functions for JSON / Tana Paste bi-directional conversionsection to do the conversions.

The demo uses tana-helper as a proxy to the restful-api.dev service to simply POST Tana structures to their free "database in the sky". Try this with your own API endpoints and let me know how you make out

Use this API to call external services. The URL pattern is /proxy/<METHOD>/<TARGET URL>. So /proxy/DELETE/http://something.com/foo?id=12 will make. a DELETE request to whatever is at http://something.com/foo?id=12

Video Explainer

restful-api.dev call via proxy

Use this API to call external services. The URL pattern is /proxy/<method>/<target URL>. So /proxy/DELETE/http://something.com/foo?id=12 will make. a DELETE request to whatever is at http://something.com/foo?id=12

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

This is a RESTful data object. We pass a Tana structure as the value of data field

data

Another object

What this looks like as JSON to the upstream restful-api.dev service:

{
    "name": "This is a RESTful data object.  We pass a Tana structure as the value of data field",
    "data": [
        {
            "name": "Another object",
            "field 1": "Foo",
            "field 2": "Bar"
        }
    ]
}

This is a RESTful object in Tana. Note the data field has fields

data

api_key

none

format

text

target

source

auto

What on earth does this do?

What this node looks like to the upstream service…

{
    "name": "This is a RESTful  object in Tana. Note the data field has fields",
    "data": {
        "api_key": "none",
        "format": "text",
        "target": "de",
        "source": "auto",
        "q": "What on earth does this do?"
    }
}

🌃 Tana Visualizer

Inspired by the original marketing visualization on the Tana.inc website, tana-helper provides a 3D visualization of your Tana workspace.

How do I use it? Go to http://localhost:8000/ui and you will be presented with the Visualizer webapp. You can upload your most recent Tana JSON export and then play with the visualization.

Check out this video demo

📥 Tana Paste Input Queue

After getting tired of being unable to send Tana Paste formatted text via the Tana Input API, I decided to do something about this. Hopefully at some point, Tana will close this gap but until then, this is a workaround that lets you push Tana Paste into Tana from anywhere that can reach your tana-helper service.

The basic strategy is that you call a tana-helper API to “queue up” the paste which adds a special queue node to your Tana Inbox. Later on when back in the Tana UI, you use a Tana Make API request command to “fetch” the queued paste. This is the only way to get Tana paste into Tana currently via a push API.

The first use-case for this was ChatGPT. Using the new Custom GPT feature, you can build a GPT that can format answers in Tana paste format making up fields, tags, etc. as required. By configuring your GPT to know about the tana-helper Enqueue Entry API, you can have ChatGPT sending data directly into Tana.

Now, since tana-helper is mostly intended to be a local service these days, you need to expose your Tana helper service via something like ngrok for this to work from the outside world. Be careful: there’s currently no security on tana-helper (yet – I’m working on it).

But how does the external service reach my local tana-helper service? Using something like ngrok you can open a tunnel back to your local machine, exposing only the tana-helper port 8000.

Note that when your external service calls these APIs, it must pass your Tana API Token via the X-Tana-API-Token HTTP header otherwise tana-helper will not be able to insert anything into Tana.

Commands

There’s really only one Tana command needed – Fetch Queued Entry. The other API is documented here as if it were a command, but Enqueue is only needed by external systems that generate Tana paste format output and want to push it into Tana.

Fetch Queued Entry

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Enqueue Entry

This is merely for documentation – call this from outside Tana, sending Tana Paste text in the body (payload)

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

Testing things

Echo

Make API request

System command. Params: *URL, Prompt, Target node, Insert output strategy, Payload, API method, Parse result, Authorization header, Headers, Avoid using proxy

MORE IDEAS

Update the python helper functions to let you register a function as a code block in the same way you can register a webhook. Save the code block to a file on the service side. Generate an endpoint from the file name just like with a webhook. Then, automatically do the Tana->JSON and JSON->Tana conversions when calling the function.

To do

Change task bar icon on Windoze

Consider making the RAG Index JSON export importer import into any of the vector databases Tana-helper supports. (Currently only supports ChromaDB)

Add field support to the graph visualizer operations.

(demo support stuff)

object

website

person

command

flight

video.other

sport

article

brett meeting