@hasura/promptql

PromptQL NodeJS SDK

A Node.js SDK for PromptQL API.

Install

Run the following command:

npm install @hasura/promptql

Get started

Prerequisite

• If you are new with PromptQL, follow the quickstart guide of PromptQL to create a project.
• Create a PromptQL API Key in project settings tab on https://console.hasura.io.
• Security headers and your Project API endpoint (version 1) or build version (version 2).

Use PromptQL SDK

Create client

Create the PromptQL client with required configurations:

import { createPromptQLClientV2 } from '@hasura/promptql';

const client = createPromptQLClientV2({
    apiKey: '<your-promptql-api-key>',
    ddn: {
        headers: {
            'Authorization': '<credential>'
        }
    },
    // You can define a lazy function for the ddn options.
    //
    // ddn: () => {{ 
    //     headers: {
    //         'Authorization': '<credential>'
    //     }
    // }}  
});

Run a Query

const runQuery = (text: string) => {
    return client.query({
        artifacts: [],
        interactions: [
            {
                user_message: {
                    text,
                }
            }
        ],
        ddn: {
            // you can override the default ddn config, 
            // for example, dynamic auth credentials
            headers: {}
        }
    });

    return response.
}

runQuery('what can you do?').then((response) => {
    console.log(response)
});

Reference

Version 2

Natural Language

The API version 2 simplifies request parameters:

• The DDN URL is replaced by build_version.
• llm, ai_primitives_llm, and system_instructions are removed.

To use the API v2, you need to create a PromptQL Client v2:

import { createPromptQLClientV2 } from '@hasura/promptql';

const client = createPromptQLClientV2({
    apiKey: '<your-promptql-api-key>',
    ddn: {
        // build_version: '<your-build-version>',
        headers: {
            'Authorization': '<credential>'
        }
    },
});

Non-Streaming

function query(
    body: PromptQLQueryRequestV2,
    queryOptions?: FetchOptions
) => Promise<QueryResponse>

Streaming

function queryStream(
    body: PromptQLQueryRequestV2, 
    callback?: (data: QueryResponseChunk) => void | Promise<void>, 
    queryOptions?: FetchOptions
) Promise<Response>;

Execute Program

Execute a PromptQL program with your data.

function executeProgram: (
    body: PromptQLExecuteRequestV2,
    executeOptions?: FetchOptions,
) => Promise<PromptQlExecutionResult>

Version 1

Natural Language

The Natural Language Query API allows you to interact with PromptQL directly, sending messages and receiving responses.

Non-Streaming

function query(
    body: PromptQLQueryRequestV1,
    queryOptions?: FetchOptions
) => Promise<QueryResponse>

Streaming

The streaming response sends chunks of data in Server-Sent Events (SSE) format. If the callback isn't set the client returns the raw response and you need to handle the response manually.

function queryStream(
    body: PromptQLQueryRequestV1, 
    callback?: (data: QueryResponseChunk) => void | Promise<void>, 
    queryOptions?: FetchOptions
) Promise<Response>;

Example:

client
    .queryStream({
        artifacts: [],
        interactions: [
            user_message: {
                text: 'what can you do?',
            }
        ],
    },
    async (chunk) => {
        console.log(chunk);
    },
);

Execute Program

Execute a PromptQL program with your data.

function executeProgram: (
    body: PromptQLExecuteRequestV1,
    executeOptions?: FetchOptions,
) => Promise<PromptQlExecutionResult>

Development

Generate types

Use the following command to update TypeScript types of PromptQL APIs from OpenAPI document.

npm run openapi:ts