Execute Program API

Introduction

Under the hood, PromptQL utilizes a set of built-in primitives, in conjunction with any custom business logic you've provided, to create small programs on top of your data.

These primitives pair relevant data or artifacts—represented as inputs or data—from your application with on-the-fly and context-aware instructions based on the thread between the user and PromptQL.

Summarize

Example:

summaries = executor.summarize(
    instructions="""
    Create a concise summary of each reservation focusing on:
    - The restaurant name
    - Any special notes or important details
    Keep each summary to 1-2 sentences.
    """,
    inputs=reservation_texts
)

Extract

Example:

extracted_info = executor.extract(
        json_schema=json_schema,
        instructions="""
        Extract any mentioned dietary requirements, special occasions, or seating preferences from the reservation notes.
        For dietary requirements, include any allergies, restrictions, or preferences mentioned.
        For special occasions, look for mentions of birthdays, anniversaries, celebrations etc.
        For seating preferences, identify if they specifically requested indoor, outdoor, bar seating etc.
        If any field is not mentioned, omit it from the output.
        """,
        inputs=notes_to_extract
    )

Classify

Example:

classifications = executor.classify(
    instructions="""
    Categorize each restaurant based on its name and any available description.
    A restaurant can belong to multiple categories.
    Consider both the dining style (Fine Dining, Casual) and cuisine type.
    Examples:
    - A high-end Italian restaurant would be both "Fine Dining" and "Italian"
    - A casual American pub would be both "Casual Dining" and "American"
    """,
    categories=categories,
    allow_multiple=True,
    inputs=unique_restaurants
)

Visualize

Example:

viz_result = executor.visualize(
    instructions="""
    Create an interactive bar chart showing the distribution of restaurant categories.
    Requirements:
    - Use a horizontal bar chart for better readability of category names
    - Sort bars by count in descending order
    - Use a pleasant color scheme (preferably blues or teals)
    - Include hover tooltips showing exact count
    - Add a clear title 'Restaurant Categories Distribution'
    - Make the chart responsive to container width
    - Include total number of restaurants in each category
    """,
    data=viz_data
)

Think of this as a toolbox

Each primitive is a specialized tool designed to perform a specific task on your data. They're flexible, composable, and context-aware, letting you build intelligent workflows by combining natural language instructions with structured input.

As you add your own custom business logic, you're providing more specific tools to PromptQL.

Execute Program Endpoint

Execute a PromptQL program with your data.

Request

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

Headers

Content-Type: application/json

Request Body

{
  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
  "promptql_api_key": "<YOUR_API_KEY_HERE>",
  "ai_primitives_llm": {
    "provider": "hasura"
  },
  "ddn": {
    "url": "https://<PROJECT_NAME>.ddn.hasura.app/v1/sql",
    "headers": {}
  },
  "artifacts": []
}

Request Body Fields

Field	Type	Required	Description
code	string	Yes	The PromptQL program code to execute
promptql_api_key	string	Yes	PromptQL API key created from project settings
ai_primitives_llm	object	Yes	Configuration for the AI primitives LLM provider
ddn	object	Yes	DDN configuration including URL and headers
artifacts	array	Yes	List of artifacts to provide as context or initial state

LLM Provider Options

The ai_primitives_llm field supports the following providers:

1. Hasura:

{
  "provider": "hasura"
}

2. Anthropic:

{
  "provider": "anthropic",
  "api_key": "<your anthropic api key>"
}

3. OpenAI:

{
  "provider": "openai",
  "api_key": "<your openai api key>"
}

Artifacts

The artifacts array can contain both text and table artifacts:

1. Text Artifact:

{
  "identifier": "my_text",
  "title": "My Text Document",
  "artifact_type": "text",
  "data": "Text content here"
}

2. Table Artifact:

{
  "identifier": "my_table",
  "title": "My Data Table",
  "artifact_type": "table",
  "data": [
    {
      "column1": "value1",
      "column2": "value2"
    }
  ]
}

Request DDN Auth

The ddn.headers field can be used to pass any auth header information through to DDN. Read more about auth with these APIs.

Response

{
  "output": "<program output>",
  "error": null,
  "accessed_artifact_ids": ["artifact1", "artifact2"],
  "modified_artifacts": [
    {
      "identifier": "new_artifact",
      "title": "New Artifact",
      "artifact_type": "table",
      "data": [
        {
          "column1": "value1",
          "column2": "value2"
        }
      ]
    }
  ],
  "llm_usages": [
    {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "input_tokens": 691,
      "output_tokens": 33
    }
  ]
}

Response Fields

Field	Type	Description
output	string	The program's output, similar to what you see in the playground
error	string|null	Error message if execution failed, null otherwise
accessed_artifact_ids	array	List of artifact identifiers that were accessed during execution
modified_artifacts	array	List of artifacts that were created or modified during execution
llm_usages	array	Details about LLM usage during execution

LLM Usage Fields

Field	Type	Description
provider	string	The LLM provider used (e.g., "hasura", "anthropic", "openai")
model	string	The specific model used
input_tokens	integer	Number of input tokens consumed
output_tokens	integer	Number of output tokens generated

Error Response

When the API encounters an error, it will return a 422 status code with a validation error response:

{
  "detail": [
    {
      "loc": ["field_name"],
      "msg": "error message",
      "type": "error_type"
    }
  ]
}

Notes for using the Execute Program API

1. Program Code

   • Ensure your PromptQL program code is properly formatted and tested
   • You can export working programs from the PromptQL playground using the "Export as API" button

2. Artifacts

   • Provide all necessary artifacts that your program needs to run
   • Make sure artifact identifiers match those referenced in your program code
   • Both text and table artifacts are supported

3. Error Handling

   • Always check the error field in the response
   • Implement appropriate retry logic for transient failures
   • Validate your inputs against the API schema to catch issues early

Get PromptQL programs from the playground

You don't have to write these programs yourself! You can get PromptQL programs from Playground interactions by clicking on the "Export as API" button next to the Query Plan. Then, you can use the exported program in the code key-value pair in your request to the /execute_program endpoint.