Introducing PromptQL Program API: Dynamic Integrations made simple

PromptQL is a data access agent that creates and runs query plans. With access to Hasura DDN connectors, PromptQL integrates with any data source, allowing AI models to access and interact with all your data under a unified schema.

With the PromptQL Program API, you can now trigger PromptQL Programs via HTTP, bringing flexibility and intelligence to your business workflows. Whether you're automating workflows or enhancing analytical reports, the API ensures seamless integration outside the chat interface of the PromptQL Playground.

What are PromptQL Programs?

PromptQL Programs are Python programs that read and write data via Python functions. PromptQL Programs are generated by LLMs. These programs are typically executed within the PromptQL Playground during interactive sessions. However, with the Program API, saved PromptQL Programs can now be executed on demand, allowing developers to integrate them into external systems and automate complex tasks effortlessly.

PromptQL Programs can:

Read/write or search through data by invoking Python functions. The tools are implemented outside of PromptQL. Example tools:
- Search: Vector, attribute, keyword, etc.
- Reading and writing data: Interact with databases effectively.
- Interacting with APIs: Seamlessly integrate external APIs.
Use PromptQL Primitives (classify, summarize, extract) to make use of LLM’s capabilities.
Create memory artifacts (text or table) to reference the data anytime in a thread.

The ability of the PromptQL agent to consistently generate high-quality PromptQL Programs is one of the important factors that determine the effectiveness of PromptQL.

Generating the API

Here is the specification for the Program API:

API endpoint:

POST https://api.promptql.pro.hasura.io/execute_program

Headers:

Content-Type: application/json

Request body:

{
  "code": "<your code>",
  "promptql_api_key": "<promptql api key created from project settings>",
  "ai_primitives_llm": {
    "provider": "hasura"
  },
  "ddn": {
    "url": "<project sql endpoint url, eg: https://tidy-katydid-4994.ddn.hasura.app/v1/sql>",
    "headers": {}
  },
  "artifacts": []
}

Response format:

{
  "output": "<program output>",
  "error": null,
  "modified_artifacts": [
    {
      "identifier": "my_artifact",
      "title": "My artifact",
      "artifact_type": "table",
      "data": [
        {
          "my_column": 1
        },
        {
          "my_column": 2
        }
      ]
    }
  ],
  "llm_usages": [
    {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "input_tokens": 691,
      "output_tokens": 33
    }
  ]
}

Using the PromptQL Playground:

You can generate the API code from a Playground interaction by clicking on the API button as shown below:

cURL code for PromptQL Program Execution

Authentication: Secure your Program API

By default, the Program API uses an ephemeral Hasura DDN token for authentication. While this is sufficient for testing and internal applications, production environments require robust authentication mechanisms.

To configure authentication for production apps:

Add an AuthConfig in the Hasura DDN metadata. Refer to this documentation.
Define rules for token generation, expiration, and user roles to ensure secure access.

This setup ensures that only authorized users can interact with your APIs, aligning with industry standards for security.

Example use cases for the Program API

The API execution of PromptQL Programs opens up a world of possibilities beyond the chat interface. Here are some practical applications:

Automated summarization with GitHub webhooks:

Set up a webhook in GitHub to trigger on events like issue creation.
Configure the webhook to call your PromptQL Program API endpoint.
Use the API to classify issues by label or generate a summary, providing instant insights to your team.

Customer support workflows:

Trigger a program to analyze customer queries or generate response drafts.
Integrate the API with ticketing systems to streamline support operations.

E-commerce analytics:

Monitor cart activity or generate reports on customer behavior.
Trigger the API via serverless functions to analyze user trends and send notifications.

These examples showcase how the API empowers developers to embed PromptQL’s capabilities into diverse business scenarios.