hasura · robertjdominguez · Jul 8, 2025 · Jul 8, 2025 · Jul 8, 2025
diff --git a/docs/ai-primitives/_category_.json b/docs/ai-primitives/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "AI Primitives",
+  "position": 8
+}
diff --git a/docs/ai-primitives/classify.mdx b/docs/ai-primitives/classify.mdx
@@ -0,0 +1,56 @@
+---
+title: Classify
+sidebar_position: 2
+description: "See how PromptQL can classify unstructured data."
+sidebar_label: Classify
+keywords:
+  - ai
+  - primitive
+  - ai primitives
+  - tools
+  - toolbox
+---
+
+# Classify
+
+## Introduction
+
+The classify function leverages PromptQL's deep understanding of context to automatically sort content into meaningful
+categories. While you can provide category lists and basic guidance, PromptQL intelligently recognizes subtle
+distinctions and nuances that determine classification. It understands context-specific signals - like what makes a
+restaurant "fine dining" versus "casual," or what distinguishes different cuisine types - without requiring exhaustive
+rules or criteria.
+
+## Example
+
+If you ask a question like:
+
+> "Can you help me organize my list of restaurants? I need to know which ones are fancy versus casual, and what kind of
+> food they serve.
+
+Here's an example showing how PromptQL handles restaurant classification with minimal instruction:
+
+```python
+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
+)
+```
+
+Notice how the instructions provide just basic examples - PromptQL automatically understands the many signals that
+indicate dining style (like price points, menu complexity, atmosphere) and cuisine authenticity, making sophisticated
+classification decisions without needing detailed criteria for each category.
+
+## Next steps
+
+Classification pairs well with PromptQL's ability to [extract](/ai-primitives/extract.mdx) information and structure it
+in a way that makes it easier to draw insights.
diff --git a/docs/ai-primitives/extract.mdx b/docs/ai-primitives/extract.mdx
@@ -0,0 +1,57 @@
+---
+title: Extract
+sidebar_position: 3
+description:
+  "Learn how PromptQL can pull specific pieces of information from text, like getting character names and locations from
+  movie descriptions or prices and dates from receipts."
+sidebar_label: Extract
+keywords:
+  - ai
+  - primitive
+  - ai primitives
+  - tools
+  - toolbox
+---
+
+# Extract
+
+## Introduction
+
+The extract function demonstrates PromptQL's ability to intelligently identify and structure relevant information from
+text, even when that information appears in different forms or contexts. While you provide a basic schema of what you're
+interested in, PromptQL automatically recognizes various ways information might be expressed - understanding that "no
+nuts" and "nut allergy" represent the same dietary restriction, or that "celebrating our 10th" implies an anniversary.
+
+## Example
+
+Here's an example showing how PromptQL handles reservation notes with minimal guidance:
+
+> "I need to go through all these reservation notes and pull out any special requests - you know, like if people have
+> food allergies, if they're celebrating something, or if they want specific tables. Can you help me organize all that
+> information?"
+
+```python
+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
+    )
+```
+
+In this example, the instructions outline basic categories without having to specify every possible way information
+might be phrased. PromptQL automatically handles variations in language, implied information, and contextual clues -
+understanding that "by the window" is a seating preference or that "gluten-free" belongs under dietary requirements,
+even without explicit mapping of these terms.
+
+## Next steps
+
+Once PromptQL has extracted structured information, it can
+[automatically visualize patterns and trends in that data](/ai-primitives/visualize.mdx) - for example, turning
+extracted dietary requirements and seating preferences into interactive charts that reveal popular accommodations or
+seasonal trends in special occasion bookings.
diff --git a/docs/ai-primitives/index.mdx b/docs/ai-primitives/index.mdx
@@ -0,0 +1,38 @@
+---
+title: AI Primitives
+sidebar_position: 1
+description: "Learn about the set of AI primitives available to PromptQL when working with your data."
+keywords:
+  - ai
+  - primitive
+  - ai primitives
+  - tools
+  - toolbox
+---
+
+# AI Primitives
+
+## Introduction
+
+Under the hood, PromptQL utilizes a set of built-in primitives, in conjunction with any
+[custom business logic](/business-logic/index.mdx) 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.
+
+The built-in primitives available are:
+
+- [Summarize](/ai-primitives/summarize.mdx)
+- [Classify](/ai-primitives/classify.mdx)
+- [Extract](/ai-primitives/extract.mdx)
+- [Visualize](/ai-primitives/visualize.mdx)
+
+:::info 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](/business-logic/index.mdx), you're providing more specific tools to PromptQL
+that it can compose and use to solve your business problems.
+
+:::
diff --git a/docs/ai-primitives/summarize.mdx b/docs/ai-primitives/summarize.mdx
@@ -0,0 +1,49 @@
+---
+title: Summarize
+sidebar_position: 1
+description: "See how PromptQL can summarize larger chunks of text and data into an easy-to-read format."
+sidebar_label: Summarize
+keywords:
+  - ai
+  - primitive
+  - ai primitives
+  - tools
+  - toolbox
+---
+
+# Summarize
+
+## Introduction
+
+If you're dealing with lengthy content and need the key points, PromptQL automatically engages the summarize primitive
+to create concise versions that capture what matters. You don't need to explicitly request summarization; it recognizes
+when condensing information would be helpful.
+
+## Example
+
+Imagine asking PromptQL something like:
+
+> "I have a bunch of restaurant reservations and I need quick overviews of each one - just the restaurant name and
+> anything important I should know about each booking."
+
+The summarize function doesn't just condense text - it intelligently determines what information is most relevant based
+on context. While you can guide the summarization with specific instructions, PromptQL automatically identifies
+important details, relationships, and key points that should be preserved. In this restaurant reservation example,
+PromptQL knows to maintain crucial booking details even without being explicitly told about every field:
+
+```python
+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
+)
+```
+
+## Next steps
+
+Now that you know more about how PromptQL can summarize large bodies of text and data, learn how it can intelligently
+[classify](/ai-primitives/classify.mdx) data into categories.
diff --git a/docs/ai-primitives/visualize.mdx b/docs/ai-primitives/visualize.mdx
@@ -0,0 +1,55 @@
+---
+title: Visualize
+sidebar_position: 4
+description:
+  "Learn how PromptQL can take your data — and any questions asked on it — to create stunning, dynamic visualizations."
+sidebar_label: Visualize
+keywords:
+  - ai
+  - primitive
+  - ai primitives
+  - tools
+  - toolbox
+---
+
+# Visualize
+
+## Introduction
+
+The visualize function illustrates PromptQL's ability to transform data into meaningful visual insights without
+requiring technical visualization expertise. While you can provide styling preferences, PromptQL automatically
+determines the most effective way to represent your data - choosing appropriate chart types, scales, and interactive
+features based on the data's structure and the insights you're seeking.
+
+## Example
+
+Here's an example showing how PromptQL creates an interactive visualization of restaurant categories:
+
+> "Can you help me make sense of all this restaurant data?"
+
+```python
+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
+)
+```
+
+The instructions focus on the desired outcome rather than technical specifications. PromptQL automatically handles the
+complexity of creating responsive, interactive visualizations - managing details like proper data scaling, axis
+formatting, and mobile responsiveness while ensuring the resulting visualization effectively communicates your data's
+story.
+
+## Next steps
+
+If you've explored all the built-in primitives which PromptQL can access, it's time to check out how to
+[add your own custom business logic](/business-logic/index.mdx) and extend what PromptQL can do!
diff --git a/docs/promptql-apis/execute-program-api.mdx b/docs/promptql-apis/execute-program-api.mdx
@@ -17,87 +17,12 @@ import TabItem from "@theme/TabItem";
 
 ## Introduction
 
-Under the hood, PromptQL utilizes a set of built-in primitives, in conjunction with any
-[custom business logic](/business-logic/index.mdx) 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
-
-```python title="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
-
-```python title="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
-    )
-```
+The Execute Program API is the interface for running PromptQL programs against your connected data. It allows you to
+trigger atomic, LLM-powered operations through a simple HTTP request—returning structured outputs, modifying artifacts,
+and recording LLM usage as part of the execution.
 
-### Classify
-
-```python title="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
-
-```python title="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
-)
-```
-
-:::info 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.
-
-:::
+This API gives you precise control over program behavior and environment configuration, making it easy to integrate
+PromptQL workflows into your own systems.
 
 ## Execute Program Endpoint
 

diff --git a/src/theme/DocSidebar/categories.ts b/src/theme/DocSidebar/categories.ts
@@ -12,7 +12,7 @@ export const CATEGORY_CONFIG: Record<string, CategoryConfig> = {
   },
   coreConcepts: {
     title: 'Core Concepts', 
-    directories: ['architecture', 'data-sources', 'metadata', 'business-logic', 'auth'],
+    directories: ['architecture', 'data-sources', 'metadata', 'ai-primitives', 'business-logic', 'auth'],
     exactMatch: false,
   },
   buildingApps: {