PromptQL TypeScript SDK

The PromptQL TypeScript SDK is a general-purpose SDK that interacts with the PromptQL API by Hasura. PromptQL enables natural language querying of your data through an AI-powered interface.

[!NOTE] This SDK supports PromptQL v2. Please install @hasura/[email protected] if you wants to integrate PromptQL v1.

Features

• Type-safe API Client: Fully typed TypeScript SDK with auto-generated types from GraphQL schema
• Thread Management: Create, list, and manage conversation threads
• Real-time Streaming: Subscribe to thread events with GraphQL subscriptions using RxJS observables
• Authentication: Built-in authentication handling with service account tokens
• Query Planning: Access to AI agent query plans and execution steps
• Artifact Support: Handle modified artifacts from AI responses
• CLI Tool: Command-line interface for quick interactions
• Flexible Configuration: Support for custom base URLs, headers, and fetch implementations

Requirements

• Node.js >= 24
• TypeScript >= 5.9.2

Installation

npm install @hasura/promptql@latest

Or with your preferred package manager:

# Yarn
yarn add @hasura/promptql@latest

# pnpm
pnpm add @hasura/promptql@latest

# Bun
bun add @hasura/promptql@latest

Quick Start

Getting Service Account Token

1. Visit your Hasura project console
2. Navigate to Project Settings
3. Go to Service Accounts section
4. Create a new service account token with Read Only permission. Avoid using the Admin role. Hackers can modify your project metadata if the service account token is leaked.
5. Copy the token and use it in your SDK configuration

For more details, check the Hasura documentation.

Basic Usage

Start a PromptQL thread

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

// Initialize the SDK
const sdk = new PromptQLSdk({
  projectId: 'your-project-id',
  serviceAccountToken: 'your-service-account-token',
});

// Start a new thread
const thread = await sdk.thread.start({
  message: 'What are the top 10 customers by revenue?',
});

console.log('Thread ID:', thread.thread_id);

// Stream events from the thread
sdk.thread.streamEvents(thread.thread_id).subscribe({
  next: (events) => {
    events.forEach(event => {
      console.log('Event:', event);
    });
  },
  error: (err) => console.error('Error:', err),
  complete: () => console.log('Interaction complete'),
});

Continue a Conversation

// Send a follow-up message to an existing thread
const result = await sdk.thread.sendMessage({
  threadId: 'existing-thread-id',
  message: 'Now show me their average order value',
});

// Stream the response
sdk.streamEvents(result.thread_id, result.thread_event_id)
  .subscribe({
    next: (events) => console.log('New events:', events),
  });

Wait until the final response only

Use the lastValueFrom function to wrap the subscription.

import { PromptQLSdk } from '@hasura/promptql';
import { lastValueFrom } from "rxjs";

// Initialize the SDK
const sdk = new PromptQLSdk({
  projectId: 'your-project-id',
  serviceAccountToken: 'your-service-account-token',
});

// Start a new thread
const thread = await sdk.thread.start({
  message: 'What are the top 10 customers by revenue?',
});

console.log('Thread ID:', thread.thread_id);

const events = await lastValueFrom(
  sdk.thread.streamEvents(
     result.thread_id,
  ),
);

events.forEach(event => {
  console.log('Event:', event);
});

Print new events only

import { PromptQLSdk, diffThreadEvents } from '@hasura/promptql';
import { pairwise, map } from 'rxjs';

// Initialize the SDK
const sdk = new PromptQLSdk({
  projectId: 'your-project-id',
  serviceAccountToken: 'your-service-account-token',
});

// Start a new thread
const thread = await sdk.thread.start({
  message: 'What are the top 10 customers by revenue?',
});

console.log('Thread ID:', thread.thread_id);

// Stream events from the thread
sdk.streamEvents(thread.thread_id)
  .pipe(
    pairwise(),
    map(([prev, curr]) => diffThreadEvents(prev, curr)),
  )
  .subscribe({
  next: (events) => {
    events.forEach(event => {
      console.log('Event:', event);
    });
  },
  error: (err) => console.error('Error:', err),
  complete: () => console.log('Interaction complete'),
});

Listing Threads

const threads = await sdk.thread.list({
  limit: 20,
  offset: 0,
  order_by: [{ created_at: 'desc' }],
  where: {
    // Optional filters
  },
});

threads.forEach(thread => {
  console.log(`Thread ${thread.id}:`, thread.title);
});

Get a Specific Thread

const thread = await sdk.thread.get('thread-id');
console.log('Thread:', thread);

Event Handling

Basics

The data structure of event data is the union of many event type. Each event type contains a different payload. You can go to the definition of ThreadEventData type to view the full data structure details.

The SDK also provides utility functions to parse different event types, for example, the following example catches and prints the query plan event and the final generated response:

import {
  getAgentPlanGenerationStartedEvent,
  getAgentPlanStepGeneratedEvent,
  getAgentGeneratedResponse,
  getUserMessageEvent,
} from '@hasura/promptql';

sdk.thread.streamEvents(threadId).subscribe({
  next: (events) => {
    events.forEach(event => {
      // Check for plan generation start
      const planStart = getAgentPlanGenerationStartedEvent(event.event_data);
      if (planStart) {
        console.log('Query Plan:\n');
        return;
      }

      // Check for plan steps
      const planStep = getAgentPlanStepGeneratedEvent(event.event_data);
      if (planStep) {
        console.log(`  - Step ${planStep.step_index}: ${planStep.step_title}\n`);
        return;
      }

      // Check for final response
      const response = getAgentGeneratedResponse(event.event_data);
      if (response) {
        const xmlRegex = /<\w+.*\/>/gm;
        console.log('Response:', source.replaceAll(xmlRegex, response.response.message));
        if (response.response.modified_artifacts) {
          console.log('Artifacts:', response.response.modified_artifacts);
        }
        return;
      }
    });
  },
});

Handle XML tags in generated response message

The generated message may contains XML tags. They represents custom UI elements that the markdown text doesn't support. You should parse or remove them if they aren't required.

Common XML tags are:

• <artifact type="table" identifier="last_5_products" />: the identifier of the artifact block.
• <user_mention id="user_id" />: mentioned user in the chat message.
• <user_group_mention id="group_id" />: mentioned group in the chat message.
• <promptql_mention />: represents a @promptql tag in the chat message.

You can remove them using regular expressions or parse the message to XML elements for advanced format.

const xmlRegex = /<\w+.*\/>/gm;
console.log(source.replaceAll(xmlRegex, ""));

Configuration Options

interface PromptQLSdkOptions {
  // Required: Project ID from PromptQL console
  projectId: string;

  // Required: Service account token for authentication
  serviceAccountToken: string;

  // Optional: Base URL of PromptQL data plane
  // Default: 'https://promptql.ddn.hasura.app'
  promptqlBaseUrl?: string;

  // Optional: Custom authentication host (for self-hosted control plane)
  authHost?: string;

  // Optional: Custom fetch implementation
  fetch?: typeof fetch;

  // Optional: Additional headers for all requests
  headers?: Record<string, string>;

  // Optional: IANA timezone for time-based queries
  // Default: Client's timezone
  timezone?: string;

  // Optional: DDN build ID
  // Default: Applied build
  buildId?: string;
}

License

Apache License 2.0 - see LICENSE file for details.

Links

• PromptQL Website
• PromptQL Console
• Hasura Documentation

Support

For support, please:

1. Check the documentation
2. Join the Hasura Discord community