Getting Started

Intento is an open source framework to help you build performant, reliable, and secure intent recognition services powered by LLMs (large language models).

How it works?

The core component of Intento is an Intent Recognition Service (IRS) endpoint. When you configure your project and run the server, the IRS endpoint that you setup, listens for incoming requests. When a new request is received, the IRS endpoint processes the request, extracts the intent and information from the user input, and sends back the extracted intent and information in the response.

Here is the basic workflow for setting up an intent recognition service using Intento:

Intento Project: First step is to setup an Intento project. You can install Intento as a package, or use the Intento starter template to get started.
Prepare IRS Data: The most important part of any intent recognition service is the data that it uses to recognize intents and extract information. Before you can setup an IRS endpoint, you need to prepare the data that the IRS endpoint will use. Check the Data page to learn more.
Setup IRS Data Source: Setup a data source that the IRS endpoint will be able to use to access the data related to the intent recognition service (IRS). Check the Data Sources page to learn more.
Specify IRS Endpoint Configurations: Next step is to specify the configurations for the IRS endpoint(s) we want our server to serve. Through these configurations we configure the endpoint name, data source to use for the IRS, whether to use authentication or not, and enable or disable verbose mode. Check the IRS Endpoints page to learn more.
Run the Server: Once we have completed the steps above, we can run the IRS server by providing it a list of all configuration objects for the IRS endpoints we want defined. The server will start and listen for incoming requests at the IRS endpoints.

When using the Intento starter template, it comes with pre-configured IRS endpoints based on test data related to an inventory management app. You can test these endpoints to see how the IRS endpoints work and to confirm Intento setup.

Installing Intento Package

You can install Intento using the following command:

npm install @oconva/intento

pnpm add @oconva/intento

Setup Environment Variables

By default, Intento uses Google's Gemini API for text generation and embedding models. If you don't yet have a Google Gen AI API key, you can get one from Gemini API - Get an API Key (opens in a new tab).

You can also use OpenAI API instead of Gemini API. You'll have to provide your OpenAI API key as the OPENAI_API_KEY environment variable and configure your IRS endpoints to use the LLM model you want it to use.

Intento was developed using QvikChat which is built on top of Firebase Genkit, which allows you to easily add any Genkit plugins to your Intento project. You can easily use any LLM model available through any Genkit plugin by simply configuring that plugin when setting up Genkit.

To learn more about configuring IRS endpoints to use a specific LLM model, check here.

If using the default Gemini API models or OpenAI models, there should be a .env file at the root level of your project directory, and it should have a value for at least one of the following, depending on which API you want to use:

GOOGLE_GENAI_API_KEY=
OPENAI_API_KEY=

Alternatively, you can copy the .env.tmp file or rename it to .env and fill in the values.

Usage

The below code shows a simple example of defining an IRS endpoint using Intento. This example uses an in-memory data source for the IRS endpoint. Intento also provides built-in support for using Cloud Firestore as the data source. To learn more about data sources, check here.

index.ts

import {
  InMemoryDataSource,
  runIRSServer,
  type IRSData,
  type IntentData,
  type APIKeyRecord,
  type IRSEndpointConfig,
} from '@oconva/intento';
 
// Import the sample data for IRS.
import IRS_DATA from '../data/irs-data.json';
import INTENTS_DATA from '../data/intents-data.json';
import API_KEYS_DATA from '../data/api-keys-data.json';
 
// Create an in-memory data source for IRS.
// Below example uses the sample data present in the `data` directory at the root of the project.
const irsDataSource = new InMemoryDataSource({
  irsId: 'jV0DFAmdTGVA8mtTUdlC',
  files: {
    irsData: IRS_DATA as IRSData[],
    intentsData: INTENTS_DATA as IntentData[],
    apiKeysData: API_KEYS_DATA as APIKeyRecord[],
  },
});
 
// Configure the IRS endpoint with endpoint name and data source.
const irsEndpointConfig: IRSEndpointConfig = {
  endpoint: 'irs',
  dataSource: irsDataSource,
};
 
// Run server with the IRS endpoint configurations.
// You can provide multiple endpoint configurations if you want to enable multiple IRS endpoints.
// This will involve fetching the IRS data from data source, setting up the required prompts with IRS data, and API key store setup.
runIRSServer({
  endpointConfigs: [irsEndpointConfig],
});

Running the above code will run a Express (opens in a new tab) server with your defined IRS endpoint accessible through it.

You should be able to access the IRS endpoint defined above at the irs endpoint.

The below given command shows you an example of sending a query to an IRS endpoint from terminal using the curl command. You will need to modify the server URL, endpoint, API key, query and user ID to match your setup.

curl -X POST "http://127.0.0.1:3400/irs" -H "Content-Type: application/json" -H "Authorization: a5zwhp0YlcRVkpnOXchIkL1lrmf0MPg24POM0kO6HcM=" -d '{"data": { "query": "add 4 litres milk?", "uid": "DI2UZuaTWjQPzVCRjzPW" } }'

Check the testing endpoints section to learn more about how you can test your IRS endpoints.

Intento Starter Template

To get up and running quickly, you can use the Intento starter template. The starter template is a pre-configured project with all the necessary configurations and setup to get you started with Intento write quality and reliable code. It comes pre-configured with support for TypeScript, ESLint, Prettier, Jest, SWC, and more, so you can get started with developing the next revolutionary chat app right away, without worrying about all these things.

Setup

Simply, clone the Intento starter template (opens in a new tab) to get started.

git clone https://github.com/oconva/intento-starter-template.git

Environment Variables

To learn more about configuring IRS endpoints to use a specific LLM model, check here.

GOOGLE_GENAI_API_KEY=
OPENAI_API_KEY=

Alternatively, you can copy the .env.tmp file or rename it to .env and fill in the values.

Install Dependencies

You can run the following commands to install the dependencies:

npm install # or pnpm install

Testing Predefined Endpoint

Intento starter template comes pre-defined with an IRS endpoint based on test data related to an inventory management app. This endpoint is defined in the src/index.ts file.

You can test the pre-defined endpoint to see how the IRS endpoints work and to confirm Intento setup. You can do this either using a graphical interface or by running the server locally and testing the endpoints using the terminal.

Check the testing endpoints section to learn more about how you can test your IRS endpoints.

To learn more about the Intento starter template, check the Intento Starter Template (opens in a new tab) repo.

How it works?

Each IRS service is created by defining an IRS endpoint. The code that gets called when a new request is received at the endpoint depends on the way you configure your IRS endpoint. You can define multiple IRS services, each with its own endpoint.

Intento provides you with an easy way to define these IRS endpoints using the defineIRSEndpoint function. This is the real superpower of Intento. Check the IRS Endpoints page to learn more.

Introduction IRS Endpoints