@hasura/promptql 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,116 @@
+# PromptQL NodeJS SDK 
+
+A Node.js SDK for [PromptQL API](https://hasura.io/docs/promptql/promptql-apis/overview/).
+
+## Install
+
+Run the following command:
+
+```sh
+npm install @hasura/promptql
+```
+
+## Get started
+
+### Prerequisite
+
+- 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).
+- Your Project API endpoint and security headers.
+
+### Use PromptQL SDK
+
+Create the PromptQL client with required configurations:
+
+```ts
+import { createPromptQLClient } from '@hasura/promptql';
+
+const client = createPromptQLClient({
+    apiKey: '<your-promptql-api-key>',
+    ddn: {
+        url: '<your-project-endpoint>',
+        headers: {
+            'Authorization': '<credential>'
+        }
+    },
+    // You can define a lazy function for the ddn options.
+    //
+    // ddn: () => {{ 
+    //     url: '<your-project-endpoint>',
+    //     headers: {
+    //         'Authorization': '<credential>'
+    //     }
+    // }}  
+});
+
+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
+
+### Natural Language 
+
+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.
+
+#### Non-Streaming
+
+```ts
+function query(body: PromptQLQueryRequest, 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.
+
+```ts
+function queryStream: (body: PromptQLQueryRequest, callback?: (data: QueryResponseChunk) => void | Promise<void>, queryOptions?: FetchOptions) Promise<Response>;
+```
+
+Example:
+
+```ts
+client
+    .queryStream({
+        artifacts: [],
+        interactions: [
+            user_message: {
+                text: 'what can you do?',
+            }
+        ],
+    },
+    async (chunk) => {
+        console.error(chunk);
+    },
+);
+```
+
+### Execute Program
+
+Execute a PromptQL program with your data.
+
+```ts
+function executeProgram: (body: PromptQLExecuteRequest, executeOptions?: FetchOptions) Promise<PromptQlExecutionResult>;
+```

package/dist/client.d.ts

@@ -0,0 +1,8 @@
+import { PromptQLClient, PromptQLClientConfig } from './types';
+/**
+ * Description placeholder
+ *
+ * @param {PromptQLClientConfig} options
+ * @returns {{ client: any; query: (body: any, queryOptions?: Omit<FetchOptions<operations>, "body">) => Promise<QueryResponse>; executeProgram: (body: any, executeOptions?: Omit<FetchOptions<operations>, "body">) => Promise<...>; }}
+ */
+export declare const createPromptQLClient: (options: PromptQLClientConfig) => PromptQLClient;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './promptql';
+export * from './types';
+export * from './client';

package/dist/index.iife.js

@@ -0,0 +1 @@
+var promptql=function(i){"use strict";var E=Object.defineProperty;var k=(i,r,s)=>r in i?E(i,r,{enumerable:!0,configurable:!0,writable:!0,value:s}):i[r]=s;var _=(i,r,s)=>k(i,typeof r!="symbol"?r+"":r,s);class r extends Error{constructor(h,w){super(w||h.map(f=>f.msg).join(". "));_(this,"detail",[]);this.detail=h}}const s="data: ",v=async t=>(await $(t),t.json()),$=async t=>{if(t.status>500){const c=t.body?await t.text():t.statusText;throw new r([],c)}if(t.status>400){const c=t.body?await t.json():null;throw c!=null&&c.detail?new r(c.detail):new r([{loc:[],msg:t.statusText,type:"unknown"}])}},j=t=>{const c=t.baseUrl?t.baseUrl[t.baseUrl.length-1]==="/"?t.baseUrl:`${t.baseUrl}/`:"https://api.promptql.pro.hasura.io/",h={...t.headers??{},Authorization:`Bearer ${t.apiKey}`},w=t.timezone||Intl.DateTimeFormat().resolvedOptions().timeZone,f=t.llm??{provider:"hasura"},C=async e=>{const a=typeof t.ddn=="function"?await t.ddn():t.ddn;return{url:(e==null?void 0:e.url)||(a.url.endsWith("/v1/sql")?a.url:`${a.url}/v1/sql`),headers:{...(a==null?void 0:a.headers)??{},...(e==null?void 0:e.headers)??{}}}},T=async(e,a,n)=>{const l=await C(e.ddn);return fetch(`${c}query`,{...n,method:"POST",headers:{...h,...n==null?void 0:n.headers,"Content-Type":"application/json"},body:JSON.stringify({llm:f,...e,version:"v1",ddn:l,timezone:e.timezone||w,stream:a})})};return{query:(e,a)=>T(e,!1,a).then(v),queryStream:async(e,a,n)=>{var S;const l=await T(e,!0,n);if(typeof a!="function"||!l.body)return l;const x=l.body.getReader(),z=new TextDecoder("utf-8");let o="";const P=async u=>{if(!u&&!o)return;let d=o+u;o="",d.startsWith(s)&&(d=u.substring(s.length)),d.split(s).forEach(async(y,U)=>{const m=y.trim();if(m[m.length-1]!=="}"){o+=U>0?`data: ${y}`:y;return}let b;try{b=JSON.parse(m)}catch{o+=U>0?`data: ${m}`:m}b&&await a(b)})};for(;!((S=n==null?void 0:n.signal)!=null&&S.aborted);){const{value:u,done:d}=await x.read();if(d)break;const g=z.decode(u);g&&await P(g)}return o&&await P(""),l},executeProgram:async(e,a)=>{const n=await C(e.ddn);return await fetch(`${c}execute_program`,{...a,body:JSON.stringify({...e,ai_primitives_llm:e.ai_primitives_llm??f,ddn:n})}).then(v)}}};return i.PromptQLError=r,i.createPromptQLClient=j,Object.defineProperty(i,Symbol.toStringTag,{value:"Module"}),i}({});

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var $=Object.defineProperty;var j=(t,e,s)=>e in t?$(t,e,{enumerable:!0,configurable:!0,writable:!0,value:s}):t[e]=s;var x=(t,e,s)=>j(t,typeof e!="symbol"?e+"":e,s);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class m extends Error{constructor(s,h){super(h||s.map(d=>d.msg).join(". "));x(this,"detail",[]);this.detail=s}}const y="data: ",S=async t=>(await z(t),t.json()),z=async t=>{if(t.status>500){const e=t.body?await t.text():t.statusText;throw new m([],e)}if(t.status>400){const e=t.body?await t.json():null;throw e!=null&&e.detail?new m(e.detail):new m([{loc:[],msg:t.statusText,type:"unknown"}])}},E=t=>{const e=t.baseUrl?t.baseUrl[t.baseUrl.length-1]==="/"?t.baseUrl:`${t.baseUrl}/`:"https://api.promptql.pro.hasura.io/",s={...t.headers??{},Authorization:`Bearer ${t.apiKey}`},h=t.timezone||Intl.DateTimeFormat().resolvedOptions().timeZone,d=t.llm??{provider:"hasura"},b=async a=>{const r=typeof t.ddn=="function"?await t.ddn():t.ddn;return{url:(a==null?void 0:a.url)||(r.url.endsWith("/v1/sql")?r.url:`${r.url}/v1/sql`),headers:{...(r==null?void 0:r.headers)??{},...(a==null?void 0:a.headers)??{}}}},v=async(a,r,n)=>{const i=await b(a.ddn);return fetch(`${e}query`,{...n,method:"POST",headers:{...s,...n==null?void 0:n.headers,"Content-Type":"application/json"},body:JSON.stringify({llm:d,...a,version:"v1",ddn:i,timezone:a.timezone||h,stream:r})})};return{query:(a,r)=>v(a,!1,r).then(S),queryStream:async(a,r,n)=>{var T;const i=await v(a,!0,n);if(typeof r!="function"||!i.body)return i;const U=i.body.getReader(),_=new TextDecoder("utf-8");let c="";const C=async l=>{if(!l&&!c)return;let o=c+l;c="",o.startsWith(y)&&(o=l.substring(y.length)),o.split(y).forEach(async(w,P)=>{const u=w.trim();if(u[u.length-1]!=="}"){c+=P>0?`data: ${w}`:w;return}let g;try{g=JSON.parse(u)}catch{c+=P>0?`data: ${u}`:u}g&&await r(g)})};for(;!((T=n==null?void 0:n.signal)!=null&&T.aborted);){const{value:l,done:o}=await U.read();if(o)break;const f=_.decode(l);f&&await C(f)}return c&&await C(""),i},executeProgram:async(a,r)=>{const n=await b(a.ddn);return await fetch(`${e}execute_program`,{...r,body:JSON.stringify({...a,ai_primitives_llm:a.ai_primitives_llm??d,ddn:n})}).then(S)}}};exports.PromptQLError=m;exports.createPromptQLClient=E;

package/dist/index.mjs

@@ -0,0 +1,114 @@
+var S = Object.defineProperty;
+var z = (t, e, s) => e in t ? S(t, e, { enumerable: !0, configurable: !0, writable: !0, value: s }) : t[e] = s;
+var U = (t, e, s) => z(t, typeof e != "symbol" ? e + "" : e, s);
+class g extends Error {
+  constructor(s, h) {
+    super(h || s.map((u) => u.msg).join(". "));
+    U(this, "detail", []);
+    this.detail = s;
+  }
+}
+const y = "data: ", _ = async (t) => (await j(t), t.json()), j = async (t) => {
+  if (t.status > 500) {
+    const e = t.body ? await t.text() : t.statusText;
+    throw new g([], e);
+  }
+  if (t.status > 400) {
+    const e = t.body ? await t.json() : null;
+    throw e != null && e.detail ? new g(e.detail) : new g([
+      {
+        loc: [],
+        msg: t.statusText,
+        type: "unknown"
+      }
+    ]);
+  }
+}, R = (t) => {
+  const e = t.baseUrl ? t.baseUrl[t.baseUrl.length - 1] === "/" ? t.baseUrl : `${t.baseUrl}/` : "https://api.promptql.pro.hasura.io/", s = {
+    ...t.headers ?? {},
+    Authorization: `Bearer ${t.apiKey}`
+  }, h = t.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone, u = t.llm ?? {
+    provider: "hasura"
+  }, b = async (a) => {
+    const r = typeof t.ddn == "function" ? await t.ddn() : t.ddn;
+    return {
+      url: (a == null ? void 0 : a.url) || (r.url.endsWith("/v1/sql") ? r.url : `${r.url}/v1/sql`),
+      headers: {
+        ...(r == null ? void 0 : r.headers) ?? {},
+        ...(a == null ? void 0 : a.headers) ?? {}
+      }
+    };
+  }, v = async (a, r, n) => {
+    const c = await b(a.ddn);
+    return fetch(`${e}query`, {
+      ...n,
+      method: "POST",
+      headers: {
+        ...s,
+        ...n == null ? void 0 : n.headers,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        llm: u,
+        ...a,
+        version: "v1",
+        ddn: c,
+        timezone: a.timezone || h,
+        stream: r
+      })
+    });
+  };
+  return {
+    query: (a, r) => v(a, !1, r).then(_),
+    queryStream: async (a, r, n) => {
+      var x;
+      const c = await v(a, !0, n);
+      if (typeof r != "function" || !c.body)
+        return c;
+      const $ = c.body.getReader(), P = new TextDecoder("utf-8");
+      let i = "";
+      const C = async (l) => {
+        if (!l && !i)
+          return;
+        let o = i + l;
+        i = "", o.startsWith(y) && (o = l.substring(y.length)), o.split(y).forEach(async (f, T) => {
+          const d = f.trim();
+          if (d[d.length - 1] !== "}") {
+            i += T > 0 ? `data: ${f}` : f;
+            return;
+          }
+          let w;
+          try {
+            w = JSON.parse(d);
+          } catch {
+            i += T > 0 ? `data: ${d}` : d;
+          }
+          w && await r(w);
+        });
+      };
+      for (; !((x = n == null ? void 0 : n.signal) != null && x.aborted); ) {
+        const { value: l, done: o } = await $.read();
+        if (o)
+          break;
+        const m = P.decode(l);
+        m && await C(m);
+      }
+      return i && await C(""), c;
+    },
+    executeProgram: async (a, r) => {
+      const n = await b(a.ddn);
+      return await fetch(`${e}execute_program`, {
+        ...r,
+        body: JSON.stringify({
+          ...a,
+          ai_primitives_llm: a.ai_primitives_llm ?? u,
+          ddn: n
+        })
+      }).then(_);
+    }
+  };
+};
+export {
+  g as PromptQLError,
+  R as createPromptQLClient
+};

package/dist/index.umd.js

@@ -0,0 +1 @@
+(function(n,a){typeof exports=="object"&&typeof module<"u"?a(exports):typeof define=="function"&&define.amd?define(["exports"],a):(n=typeof globalThis<"u"?globalThis:n||self,a(n.promptql={}))})(this,function(n){"use strict";var z=Object.defineProperty;var E=(n,a,o)=>a in n?z(n,a,{enumerable:!0,configurable:!0,writable:!0,value:o}):n[a]=o;var p=(n,a,o)=>E(n,typeof a!="symbol"?a+"":a,o);class a extends Error{constructor(m,w){super(w||m.map(h=>h.msg).join(". "));p(this,"detail",[]);this.detail=m}}const o="data: ",T=async e=>(await U(e),e.json()),U=async e=>{if(e.status>500){const s=e.body?await e.text():e.statusText;throw new a([],s)}if(e.status>400){const s=e.body?await e.json():null;throw s!=null&&s.detail?new a(s.detail):new a([{loc:[],msg:e.statusText,type:"unknown"}])}},_=e=>{const s=e.baseUrl?e.baseUrl[e.baseUrl.length-1]==="/"?e.baseUrl:`${e.baseUrl}/`:"https://api.promptql.pro.hasura.io/",m={...e.headers??{},Authorization:`Bearer ${e.apiKey}`},w=e.timezone||Intl.DateTimeFormat().resolvedOptions().timeZone,h=e.llm??{provider:"hasura"},v=async t=>{const r=typeof e.ddn=="function"?await e.ddn():e.ddn;return{url:(t==null?void 0:t.url)||(r.url.endsWith("/v1/sql")?r.url:`${r.url}/v1/sql`),headers:{...(r==null?void 0:r.headers)??{},...(t==null?void 0:t.headers)??{}}}},C=async(t,r,i)=>{const c=await v(t.ddn);return fetch(`${s}query`,{...i,method:"POST",headers:{...m,...i==null?void 0:i.headers,"Content-Type":"application/json"},body:JSON.stringify({llm:h,...t,version:"v1",ddn:c,timezone:t.timezone||w,stream:r})})};return{query:(t,r)=>C(t,!1,r).then(T),queryStream:async(t,r,i)=>{var P;const c=await C(t,!0,i);if(typeof r!="function"||!c.body)return c;const $=c.body.getReader(),j=new TextDecoder("utf-8");let l="";const x=async d=>{if(!d&&!l)return;let u=l+d;l="",u.startsWith(o)&&(u=d.substring(o.length)),u.split(o).forEach(async(y,S)=>{const f=y.trim();if(f[f.length-1]!=="}"){l+=S>0?`data: ${y}`:y;return}let b;try{b=JSON.parse(f)}catch{l+=S>0?`data: ${f}`:f}b&&await r(b)})};for(;!((P=i==null?void 0:i.signal)!=null&&P.aborted);){const{value:d,done:u}=await $.read();if(u)break;const g=j.decode(d);g&&await x(g)}return l&&await x(""),c},executeProgram:async(t,r)=>{const i=await v(t.ddn);return await fetch(`${s}execute_program`,{...r,body:JSON.stringify({...t,ai_primitives_llm:t.ai_primitives_llm??h,ddn:i})}).then(T)}}};n.PromptQLError=a,n.createPromptQLClient=_,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})});

package/dist/promptql.d.ts

@@ -0,0 +1,441 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export type paths = {
+    "/execute_program": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Execute Program */
+        post: operations["execute_program_execute_program_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/query": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Query */
+        post: operations["query_query_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+};
+export type webhooks = Record<string, never>;
+export type components = {
+    schemas: {
+        /** ApiAnthropicConfig */
+        ApiAnthropicConfig: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            provider: "anthropic";
+            /** Model */
+            model?: string | null;
+            /** Base Url */
+            base_url?: string | null;
+            /** Api Key */
+            api_key: string;
+        };
+        /** ApiOpenAIConfig */
+        ApiOpenAIConfig: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            provider: "openai";
+            /** Model */
+            model?: string | null;
+            /** Base Url */
+            base_url?: string | null;
+            /** Api Key */
+            api_key: string;
+        };
+        /** AssistantAction */
+        AssistantAction: {
+            /** Message */
+            message?: string | null;
+            /** Plan */
+            plan?: string | null;
+            /** Code */
+            code?: string | null;
+            /** Code Output */
+            code_output?: string | null;
+            /** Code Error */
+            code_error?: string | null;
+        };
+        /** DdnConfig */
+        DdnConfig: {
+            /**
+             * Url
+             * @description URL of the /sql endpoint on Hasura DDN
+             */
+            url: string;
+            /**
+             * Headers
+             * @description HTTP headers that should be forwarded to DDN
+             */
+            headers?: {
+                [key: string]: string;
+            };
+        };
+        /** ExecuteRequest */
+        ExecuteRequest: {
+            /** Code */
+            code: string;
+            /**
+             * Promptql Api Key
+             * @deprecated
+             */
+            promptql_api_key?: string | null;
+            /** Ai Primitives Llm */
+            ai_primitives_llm: (components["schemas"]["HasuraLlmConfig"] | components["schemas"]["ApiOpenAIConfig"] | components["schemas"]["ApiAnthropicConfig"]) | null;
+            ddn: components["schemas"]["DdnConfig"] | null;
+            /** Artifacts */
+            artifacts: (components["schemas"]["TextArtifact"] | components["schemas"]["TableArtifact"] | components["schemas"]["VisualizationArtifact"])[];
+        };
+        /** HTTPValidationError */
+        HTTPValidationError: {
+            /** Detail */
+            detail?: components["schemas"]["ValidationError"][];
+        };
+        /** HasuraLlmConfig */
+        HasuraLlmConfig: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            provider: "hasura";
+        };
+        /** Interaction */
+        Interaction: {
+            user_message: components["schemas"]["UserMessage"];
+            /** Assistant Actions */
+            assistant_actions?: components["schemas"]["AssistantAction"][];
+        };
+        /** LlmUsage */
+        LlmUsage: {
+            /**
+             * Provider
+             * @default unknown
+             */
+            provider: string;
+            /**
+             * Model
+             * @default unknown
+             */
+            model: string;
+            /**
+             * Input Tokens
+             * @default 0
+             */
+            input_tokens: number;
+            /**
+             * Output Tokens
+             * @default 0
+             */
+            output_tokens: number;
+        };
+        /** PromptQlExecutionResult */
+        PromptQlExecutionResult: {
+            /** Output */
+            output: string;
+            /** Error */
+            error: string | null;
+            /** Accessed Artifact Ids */
+            accessed_artifact_ids: string[];
+            /** Modified Artifacts */
+            modified_artifacts: (components["schemas"]["TextArtifact"] | components["schemas"]["TableArtifact"] | components["schemas"]["VisualizationArtifact"])[];
+            /** Llm Usages */
+            llm_usages: components["schemas"]["LlmUsage"][];
+        };
+        /** QueryRequest */
+        QueryRequest: {
+            /**
+             * Version
+             * @constant
+             */
+            version: "v1";
+            /**
+             * Promptql Api Key
+             * @deprecated
+             */
+            promptql_api_key?: string | null;
+            /** Llm */
+            llm?: components["schemas"]["HasuraLlmConfig"] | components["schemas"]["ApiOpenAIConfig"] | components["schemas"]["ApiAnthropicConfig"];
+            /** Ai Primitives Llm */
+            ai_primitives_llm?: (components["schemas"]["HasuraLlmConfig"] | components["schemas"]["ApiOpenAIConfig"] | components["schemas"]["ApiAnthropicConfig"]) | null;
+            ddn: components["schemas"]["DdnConfig"];
+            /** Artifacts */
+            artifacts?: (components["schemas"]["TextArtifact"] | components["schemas"]["TableArtifact"] | components["schemas"]["VisualizationArtifact"])[];
+            /** System Instructions */
+            system_instructions?: string | null;
+            /**
+             * Timezone
+             * @description An IANA timezone used to interpret queries that implicitly require timezones
+             */
+            timezone: string;
+            /** Interactions */
+            interactions: components["schemas"]["Interaction"][];
+            /** Stream */
+            stream: boolean;
+        };
+        /** QueryResponse */
+        QueryResponse: {
+            /** Assistant Actions */
+            assistant_actions: components["schemas"]["AssistantAction"][];
+            /**
+             * Modified Artifacts
+             * @description List of artifacts created or updated in this request. May contain duplicate artifact identifiers.
+             */
+            modified_artifacts: (components["schemas"]["TextArtifact"] | components["schemas"]["TableArtifact"] | components["schemas"]["VisualizationArtifact"])[];
+        };
+        /** TableArtifact */
+        TableArtifact: {
+            /** Identifier */
+            identifier: string;
+            /** Title */
+            title: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            artifact_type: "table";
+            /**
+             * Data
+             * @description Table data as a list of objects, with the object keys being column names
+             */
+            data: {
+                [key: string]: unknown;
+            }[];
+        };
+        /** TextArtifact */
+        TextArtifact: {
+            /** Identifier */
+            identifier: string;
+            /** Title */
+            title: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            artifact_type: "text";
+            /** Data */
+            data: string;
+        };
+        /** UserMessage */
+        UserMessage: {
+            /** Text */
+            text: string;
+        };
+        /** ValidationError */
+        ValidationError: {
+            /** Location */
+            loc: (string | number)[];
+            /** Message */
+            msg: string;
+            /** Error Type */
+            type: string;
+        };
+        /** VisualizationArtifact */
+        VisualizationArtifact: {
+            /** Identifier */
+            identifier: string;
+            /** Title */
+            title: string;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            artifact_type: "visualization";
+            /** @description Visualization data containing HTML and visualization data */
+            data: components["schemas"]["VisualizationArtifactData"];
+        };
+        /**
+         * VisualizationArtifactData
+         * @description Data structure for visualization artifacts containing HTML and associated data.
+         *
+         *     Attributes:
+         *         html: The HTML markup for rendering the visualization
+         *         visualization_data: The underlying data used to generate the visualization
+         */
+        VisualizationArtifactData: {
+            /** Html */
+            html: string;
+            /** Visualization Data */
+            visualization_data: unknown;
+        };
+        QueryResponseChunk: components["schemas"]["AssistantActionChunk"] | components["schemas"]["ArtifactUpdateChunk"] | components["schemas"]["ErrorChunk"];
+        /** ArtifactUpdateChunk */
+        ArtifactUpdateChunk: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "artifact_update_chunk";
+            /** Artifact */
+            artifact: components["schemas"]["TextArtifact"] | components["schemas"]["TableArtifact"] | components["schemas"]["VisualizationArtifact"];
+        };
+        /** AssistantActionChunk */
+        AssistantActionChunk: {
+            /**
+             * Message
+             * @default null
+             */
+            message: string | null;
+            /**
+             * Plan
+             * @default null
+             */
+            plan: string | null;
+            /**
+             * Code
+             * @default null
+             */
+            code: string | null;
+            /**
+             * Code Output
+             * @default null
+             */
+            code_output: string | null;
+            /**
+             * Code Error
+             * @default null
+             */
+            code_error: string | null;
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "assistant_action_chunk";
+            /** Index */
+            index: number;
+        };
+        /** ErrorChunk */
+        ErrorChunk: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "error_chunk";
+            /** Error */
+            error: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+};
+export type ApiAnthropicConfig = components['schemas']['ApiAnthropicConfig'];
+export type ApiOpenAiConfig = components['schemas']['ApiOpenAIConfig'];
+export type AssistantAction = components['schemas']['AssistantAction'];
+export type DdnConfig = components['schemas']['DdnConfig'];
+export type ExecuteRequest = components['schemas']['ExecuteRequest'];
+export type HttpValidationError = components['schemas']['HTTPValidationError'];
+export type HasuraLlmConfig = components['schemas']['HasuraLlmConfig'];
+export type Interaction = components['schemas']['Interaction'];
+export type LlmUsage = components['schemas']['LlmUsage'];
+export type PromptQlExecutionResult = components['schemas']['PromptQlExecutionResult'];
+export type QueryRequest = components['schemas']['QueryRequest'];
+export type QueryResponse = components['schemas']['QueryResponse'];
+export type TableArtifact = components['schemas']['TableArtifact'];
+export type TextArtifact = components['schemas']['TextArtifact'];
+export type UserMessage = components['schemas']['UserMessage'];
+export type ValidationError = components['schemas']['ValidationError'];
+export type VisualizationArtifact = components['schemas']['VisualizationArtifact'];
+export type VisualizationArtifactData = components['schemas']['VisualizationArtifactData'];
+export type QueryResponseChunk = components['schemas']['QueryResponseChunk'];
+export type ArtifactUpdateChunk = components['schemas']['ArtifactUpdateChunk'];
+export type AssistantActionChunk = components['schemas']['AssistantActionChunk'];
+export type ErrorChunk = components['schemas']['ErrorChunk'];
+export type $defs = Record<string, never>;
+export interface operations {
+    execute_program_execute_program_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ExecuteRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PromptQlExecutionResult"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    query_query_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["QueryRequest"];
+            };
+        };
+        responses: {
+            /** @description Either a JSON response (QueryResponse object) or a stream of Server-Sent Events (SSE) (QueryResponseChunk objects) depending on whether the 'stream' parameter was set */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["QueryResponse"];
+                    "text/event-stream": components["schemas"]["QueryResponseChunk"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+import { IncomingHttpHeaders } from 'node:http';
+import { ApiAnthropicConfig, ApiOpenAiConfig, DdnConfig, ExecuteRequest, HasuraLlmConfig, PromptQlExecutionResult, QueryRequest, QueryResponse, QueryResponseChunk, TableArtifact, TextArtifact, ValidationError, VisualizationArtifact } from './promptql';
+/**
+ * PromptQL client config contains common settings to connect the PromptQL API.
+ *
+ * @export
+ * @typedef {PromptQLClientOptions}
+ */
+export type PromptQLClientConfig = {
+    /**
+     * PromptQL API key created from project settings.
+     *
+     * @type {string}
+     */
+    apiKey: string;
+    /**
+     * DDN configuration including URL and headers.
+     *
+     * @type {(DdnConfig | (() => DdnConfig | Promise<DdnConfig>))}
+     */
+    ddn: DdnConfig | (() => DdnConfig | Promise<DdnConfig>);
+    /**
+     * The optional base URL of PromptQL API. The default value is the endpoint to the public DDN.
+     *
+     * @type {?string}
+     */
+    baseUrl?: string;
+    /**
+     * Custom headers to be injected into requests.
+     *
+     * @type {?IncomingHttpHeaders}
+     */
+    headers?: IncomingHttpHeaders;
+    /**
+     * Configuration for the main LLM provider.
+     *
+     * @type {?(HasuraLlmConfig | ApiOpenAiConfig | ApiAnthropicConfig)}
+     */
+    llm?: HasuraLlmConfig | ApiOpenAiConfig | ApiAnthropicConfig;
+    /**
+     * An [IANA timezone](https://data.iana.org/time-zones/tzdb-2021a/zone1970.tab) for interpreting time-based queries. Default is the system timezone.
+     *
+     * @type {?string}
+     */
+    timezone?: string;
+};
+/**
+ * A simple http client wrapper for [PromptQL API](https://hasura.io/docs/promptql/promptql-apis/overview/).
+ *
+ * @export
+ * @typedef {PromptQLClient}
+ */
+export type PromptQLClient = {
+    /**
+     * 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.
+     * The response is non-streaming.
+     *
+     * @param {PromptQLQueryRequest} body
+     * @param {?FetchOptions} [queryOptions]
+     * @returns {Promise<QueryResponse>}
+     */
+    query: (body: PromptQLQueryRequest, queryOptions?: FetchOptions) => Promise<QueryResponse>;
+    /**
+     * 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.
+     *
+     * @param {PromptQLQueryRequest} body
+     * @param {?(data: QueryResponseChunk) => void} callback
+     * @param {?FetchOptions} [queryOptions]
+     * @returns {Promise<Response>}
+     */
+    queryStream: (body: PromptQLQueryRequest, callback?: (data: QueryResponseChunk) => void | Promise<void>, queryOptions?: FetchOptions) => Promise<Response>;
+    /**
+     * Execute a PromptQL program with your data.
+     *
+     * @async
+     * @param {PromptQLExecuteRequest} body
+     * @param {?FetchOptions} [executeOptions]
+     * @returns {Promise<PromptQlExecutionResult>}
+     */
+    executeProgram: (body: PromptQLExecuteRequest, executeOptions?: FetchOptions) => Promise<PromptQlExecutionResult>;
+};
+/**
+ * PromptQL artifacts are stores of data and can be referenced from PromptQL programs. PromptQL programs can create artifacts.
+ *
+ * @export
+ * @typedef {Artifact}
+ */
+export type Artifact = TextArtifact | TableArtifact | VisualizationArtifact;
+/**
+ * The request body to the [Natural Language Query API](https://hasura.io/docs/promptql/promptql-apis/natural-language-api/).
+ *
+ * @export
+ * @typedef {PromptQLQueryRequest}
+ */
+export type PromptQLQueryRequest = Omit<QueryRequest, 'timezone' | 'ddn' | 'version' | 'stream'> & {
+    /**
+     * An [IANA timezone](https://data.iana.org/time-zones/tzdb-2021a/zone1970.tab) for interpreting time-based queries. Default is the timezone from the client config.
+     *
+     * @type {?string}
+     */
+    readonly timezone?: string;
+    /**
+     * DDN configuration including URL and headers. Used to override the default client settings.
+     *
+     * @readonly
+     * @type {?Partial<DdnConfig>}
+     */
+    readonly ddn?: Partial<DdnConfig>;
+};
+/**
+ * Optional fetch options to the PromptQL API.
+ *
+ * @export
+ * @typedef {FetchOptions}
+ */
+export type FetchOptions = Omit<RequestInit, 'method' | 'body'>;
+/**
+ * The request body to the [Execute Program API](https://hasura.io/docs/promptql/promptql-apis/execute-program-api/).
+ *
+ * @export
+ * @typedef {PromptQLExecuteRequest}
+ */
+export type PromptQLExecuteRequest = Omit<ExecuteRequest, 'ddn' | 'version'> & {
+    /**
+     * DDN configuration including URL and headers. Used to override the default client settings.
+     *
+     * @readonly
+     * @type {?Partial<DdnConfig>}
+     */
+    readonly ddn?: Partial<DdnConfig>;
+};
+/**
+ * A general GraphQL error that is retrieved from the PromptQL server.
+ *
+ * @export
+ * @class PromptQLError
+ * @typedef {PromptQLError}
+ * @extends {Error}
+ */
+export declare class PromptQLError extends Error {
+    detail: ValidationError[];
+    constructor(detail: ValidationError[], message?: string);
+}

package/dist/utils.d.ts

@@ -0,0 +1,10 @@
+export declare const DATA_CHUNK_PREFIX = "data: ";
+/**
+ * Decode the response as JSON.
+ *
+ * @async
+ * @template T
+ * @param {Response} response
+ * @returns {Promise<T>}
+ */
+export declare const decodeResponseJson: <T>(response: Response) => Promise<T>;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hasura/promptql",
+  "description": "A Node.js SDK allows you to interact with PromptQL API",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Hasura",
+  "homepage": "https://promptql.hasura.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasura/promptql-nodejs-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hasura/promptql-nodejs-sdk/issues"
+  },
+  "keywords": [
+    "promptql",
+    "api",
+    "typescript"
+  ],
+  "scripts": {
+    "copy-files": "cp ./src/promptql.d.ts ./dist/promptql.d.ts",
+    "build": "tsc && vite build && npm run copy-files",
+    "release": "npm run test && changelogen --release --push && npm publish",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "test": "vitest --run",
+    "test:coverage": "vitest --coverage",
+    "prepublishOnly": "npm run build",
+    "openapi:ts": "openapi-typescript https://api.promptql.pro.hasura.io/openapi.json --export-type --root-types-no-schema-prefix --root-types -o ./src/promptql.d.ts"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "openapi-typescript": "^7.6.1",
+    "@types/node": "^22.14.1",
+    "@vitest/coverage-v8": "^3.1.1",
+    "@biomejs/biome": "1.9.4",
+    "changelogen": "^0.6.1",
+    "typescript": "^5.8.3",
+    "vite": "^6.2.6",
+    "vite-plugin-dts": "^4.5.3",
+    "vitest": "^3.1.1"
+  }
+}