@hasura/promptql 1.0.0 → 2.0.0-alpha.10

package/README.md

@@ -1,196 +1,309 @@
-# PromptQL NodeJS SDK 
+# PromptQL TypeScript SDK
 
-A Node.js SDK for [PromptQL API](https://hasura.io/docs/promptql/promptql-apis/overview/).
+The PromptQL TypeScript SDK is a general-purpose SDK that interacts with the [PromptQL API](https://promptql.hasura.io) by Hasura. PromptQL enables natural language querying of your data through an AI-powered interface.
 
-## Install
+> [!NOTE]
+> This SDK supports PromptQL v2. Please install [@hasura/promptql@1.0.0](https://www.npmjs.com/package/@hasura/promptql/v/1.0.0) if you wants to integrate PromptQL v1.
 
-Run the following command:
+## Features
 
-```sh
-npm install @hasura/promptql
+- **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
+
+```bash
+npm install @hasura/promptql@latest
 ```
 
-## Get started
+Or with your preferred package manager:
 
-### Prerequisite
+```bash
+# Yarn
+yarn add @hasura/promptql@latest
 
-- If you are new with PromptQL, follow [the quickstart guide of PromptQL](https://hasura.io/docs/promptql/quickstart/) to create a project.
-- Create a PromptQL API Key in project settings tab on [https://console.hasura.io](https://console.hasura.io).
-- Security headers and your Project API endpoint (version 1) or build version (version 2).
+# pnpm
+pnpm add @hasura/promptql@latest
 
-### Use PromptQL SDK
+# Bun
+bun add @hasura/promptql@latest
+```
 
-#### Create client
+## Quick Start
 
-Create the PromptQL client with required configurations:
+### Getting Service Account Token
 
-```ts
-import { createPromptQLClientV2 } from '@hasura/promptql';
+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
 
-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>'
-    //     }
-    // }}  
+For more details, check the [Hasura documentation](https://hasura.io/docs/3.0/project-configuration/project-management/service-accounts/#how-to-create-service-account).
+
+### Basic Usage
+
+#### Start a PromptQL thread
+
+```typescript
+import { PromptQLSdk } from '@hasura/promptql';
+
+// Initialize the SDK
+const sdk = new PromptQLSdk({
+  projectId: 'your-project-id',
+  serviceAccountToken: 'your-service-account-token',
 });
-```
 
-#### Run a Query
-
-```ts
-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: {}
-        }
+// 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'),
+});
+```
 
-    return response.
-}
+#### Continue a Conversation
 
-runQuery('what can you do?').then((response) => {
-    console.log(response)
+```typescript
+// 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),
+  });
 ```
 
-## Reference
+#### Wait until the final response only
+
+Use the `lastValueFrom` function to wrap the subscription.
 
-### Version 2
+```typescript
+import { PromptQLSdk } from '@hasura/promptql';
+import { lastValueFrom } from "rxjs";
 
-#### Natural Language
+// Initialize the SDK
+const sdk = new PromptQLSdk({
+  projectId: 'your-project-id',
+  serviceAccountToken: 'your-service-account-token',
+});
 
-The API version 2 simplifies request parameters: 
-- The DDN URL is replaced by `build_version`. 
-- `llm`, `ai_primitives_llm`, and `system_instructions` are removed. 
+// Start a new thread
+const thread = await sdk.thread.start({
+  message: 'What are the top 10 customers by revenue?',
+});
 
-To use the API v2, you need to create a PromptQL Client v2:
+console.log('Thread ID:', thread.thread_id);
 
-```ts
-import { createPromptQLClientV2 } from '@hasura/promptql';
+const events = await lastValueFrom(
+  sdk.thread.streamEvents(
+     result.thread_id,
+  ),
+);
 
-const client = createPromptQLClientV2({
-    apiKey: '<your-promptql-api-key>',
-    ddn: {
-        // build_version: '<your-build-version>',
-        headers: {
-            'Authorization': '<credential>'
-        }
-    },
+events.forEach(event => {
+  console.log('Event:', event);
 });
 ```
 
-##### Non-Streaming
+#### Print new events only
 
-```ts
-function query(
-    body: PromptQLQueryRequestV2,
-    queryOptions?: FetchOptions
-) => Promise<QueryResponse>
+```typescript
+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'),
+});
 ```
 
-##### Streaming
+### Listing Threads
 
-```ts
-function queryStream(
-    body: PromptQLQueryRequestV2, 
-    callback?: (data: QueryResponseChunk) => void | Promise<void>, 
-    queryOptions?: FetchOptions
-) Promise<Response>;
+```typescript
+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);
+});
 ```
 
-#### Execute Program
+### Get a Specific Thread
 
-Execute a PromptQL program with your data.
+```typescript
+const thread = await sdk.thread.get('thread-id');
+console.log('Thread:', thread);
+```
 
-```ts
-function executeProgram: (
-    body: PromptQLExecuteRequestV2,
-    executeOptions?: FetchOptions,
-) => Promise<PromptQlExecutionResult>
+## 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:
+
+```typescript
+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;
+      }
+    });
+  },
+});
 ```
 
-### Version 1
+### 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.
 
-#### Natural Language
+Common XML tags are:
 
-The [Natural Language Query API](https://hasura.io/docs/promptql/promptql-apis/natural-language-api/) allows you to interact with PromptQL directly, sending messages and receiving responses.
+- `<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.
 
-##### Non-Streaming
+You can remove them using regular expressions or parse the message to XML elements for advanced format.
 
-```ts
-function query(
-    body: PromptQLQueryRequestV1,
-    queryOptions?: FetchOptions
-) => Promise<QueryResponse>
+```typescript
+const xmlRegex = /<\w+.*\/>/gm;
+console.log(source.replaceAll(xmlRegex, ""));
 ```
 
-##### Streaming
+## Configuration Options
 
-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.
+```typescript
+interface PromptQLSdkOptions {
+  // Required: Project ID from PromptQL console
+  projectId: string;
 
-```ts
-function queryStream(
-    body: PromptQLQueryRequestV1, 
-    callback?: (data: QueryResponseChunk) => void | Promise<void>, 
-    queryOptions?: FetchOptions
-) Promise<Response>;
-```
+  // Required: Service account token for authentication
+  serviceAccountToken: string;
 
-Example:
-
-```ts
-client
-    .queryStream({
-        artifacts: [],
-        interactions: [
-            user_message: {
-                text: 'what can you do?',
-            }
-        ],
-    },
-    async (chunk) => {
-        console.log(chunk);
-    },
-);
-```
+  // 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;
 
-#### Execute Program
+  // Optional: Additional headers for all requests
+  headers?: Record<string, string>;
 
-Execute a PromptQL program with your data.
+  // Optional: IANA timezone for time-based queries
+  // Default: Client's timezone
+  timezone?: string;
 
-```ts
-function executeProgram: (
-    body: PromptQLExecuteRequestV1,
-    executeOptions?: FetchOptions,
-) => Promise<PromptQlExecutionResult>
+  // Optional: DDN build ID
+  // Default: Applied build
+  buildId?: string;
+}
 ```
 
-## Development
+## License
 
-### Generate types
+Apache License 2.0 - see [LICENSE](LICENSE) file for details.
 
-Use the following command to update TypeScript types of PromptQL APIs from OpenAPI document.
+## Links
 
-```bash
-npm run openapi:ts
-```
+- [PromptQL Website](https://promptql.hasura.io)
+- [PromptQL Console](https://promptql.console.hasura.io)
+- [Hasura Documentation](https://hasura.io/docs)
+
+## Support
+
+For support, please:
+
+1. Check the [documentation](https://promptql.hasura.io)
+2. Join the [Hasura Discord community](https://discord.gg/hasura)

package/biome.json

@@ -0,0 +1,15 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+	"root": false,
+	"files": {
+		"includes": [
+			"**/*.ts",
+			"**/*.gql",
+			"!src/generated/*",
+			"!dist/**/*"
+		]
+	},
+	"extends": [
+		"../biome-config/base.json"
+	]
+}