Introducing Tablada
An open source framework for building deterministic, performant, and simple natural language APIs (NLAs)
Motivation
We, at Calligram, believe natural language APIs are going to be critical building blocks of the next generation of software and AGI. Tablada aims to empower developers to create NLAs tailored to their specific requirements.
Embracing Open Source for the Future of NLAs
At Calligram, we strongly advocate for open source as the future of NLAs. Beyond the social equity benefits, we recognize that companies want to retain control over their products. By leveraging adaptable and open source frameworks like Tablada, companies can build NLAs that align with their unique needs and priorities. For some, cost may be paramount, while others may prioritize increased accuracy or support for cross-endpoint joining. This mirrors the paradigm of API development, where proprietary web applications are built on top of customizable language-specific frameworks.
Redefining the Unit of Action: APIs vs. Endpoints
Alternative approaches to NLAs (such as Zapier’s natural language actions API), often treat API endpoints as atomic units of action. However, Tablada challenges this approach by considering the API itself as the unit of action. While targeting individual endpoints remains possible, this broader perspective offers a range of advantages. It enables consistency in primary key identifiers across endpoints and eliminates unnecessary complexity. With Tablada, developers can effortlessly achieve granular control while harnessing the benefits of object relationships within a single API.
A Brief History of APIs
Almost all modern day applications, and thus APIs, are database-backed. This means that, very crudely stated, pretty much every modern API is more or less a wrapper around some set of CRUD operations interacting with a database on the back end.
APIs offer additional guarantees and conveniences to application developers. They allow for data to be accessed in consistent and safe ways (e.g. automatic limits and row level security based on request issuer). In this way, APIs enable single page applications to dynamically update page content.
So, why does any of this matter? The key point is that pretty much every API offers a reduced set of functionality for manipulating and accessing the underlying data as compared to running SQL directly on a database in exchange for convenience, safety, and performance. This isn’t even really a new or novel realization. Projects like Apache Calcite and Steampipe allow you to query APIs using SQL and have proven that deterministic conversion works for most APIs ^1.
Natural Language to SQL
How does all of this tie back to natural language? Natural language to SQL has been a widely studied area of research in machine learning for the last several years. There are many open source transformer models that are faster and achieve better performance than even GPT-4. And, GPT-4 also works well for SQL generation!
The ability to reliably generate SQL from natural language provides us with a robust superset of functionality compared to most APIs. This realization enables us to seamlessly interface with APIs. Projects such as Calcite and Steampipe have validated this concept, showcasing the deterministic nature of the translation from SQL to API. In many cases, the translation code can be auto-generated using the assistance of Language Models (LLMs). With just a few lines of code and the right configuration, Tablada empowers developers to leverage the power of natural language to interact seamlessly with APIs.
Design Principles
Determinism: prefer deterministic to probabilistic run-time behavior whenever possible
Performance: target sub-second request processing performance
Simplicity: reuse existing solutions whenever possible and avoid components that must be fine-tuned or retrained for every application instance
Design
The basic architecture of the natural language API framework is very similar to a standard retrieval augmented generation architecture (RAG) ^2. The main difference is that data/document retrieval happens after the seq2seq model output is generated instead of before. This reduces the amount of data that needs to be passed to the seq2seq model and lowers operational cost. The basic architecture is as follows.
Natural language to SQL transformer (probabilistic)
SQL parser and adjuster relying on matching service (probabilistic)
SQL execution engine
SQL to API transformer (deterministic)
Query execution engine (deterministic)
The matching service (2) ensures that valid conditions are generated for enumerated fields i.e. fields that can only assume one of several predefined values. It is also worth noting that a Steampipe plugin can frequently be used for (3) but is often overkill and sometimes prohibitively restrictive due to the typing limitations.
Example
Imagine we are exposing a natural language API for the Yelp Fusion API. A user could pass the following query to the NLA:
coffee near me.
We pass this query along with minimal context about the Yelp API schema (such as resource names and resource attributes) to generate the following SQL query:
SELECT * FROM businesses WHERE category=’coffee’
This gets parsed into a standard SQL parse tree. Since category
is an enumerated field in the Yelp API, the category
condition value gets embedded and passed to the matching service where it is updated to the correct value of coffeeshops
.
The adjusted query
SELECT * FROM businesses WHERE category=’coffeeshops’
then gets passed to the SQL engine. This can be as simple as a SQL to API translation layer plus an HTTP request executor or as complicated as a Postgres instance with foreign data wrappers that call the API behind the scenes (e.g. Steampipe) to enable more complex queries.
Benefits
Cheap
Accurate
Fast sub-second request processing for most endpoints
Reduces solution complexity and allows developers to focus on solution components that actually impact operational accuracy and cost
Works out of the box for 99% of CRUD APIs - no need to fine-tune foundation or embedding models if you don't want to
Deterministic and verified results - as long as the underlying API ensures data accuracy and is deterministic, then semantically equivalent queries should return the same verified, results
Easily verifiable and debuggable - debugging an incorrect request is as simple as debugging SQL
Framework Parameters
There are only three parameters in the Tablada framework that affect operational performance.
Embedding model
Seq2seq transformer model
Vector database
These are the only things a developer needs to think about in order to tweak the performance of an NLA. By default, Calligram recommends using qdrant.
Next Steps
In the coming weeks, Calligram will release Tablada in two formats: (1) an open source Python application framework and (2) a deployable Helm chart leveraging (1) for swift setup. Stay tuned by subscribing to our blog to receive updates on the first version's release!