diff --git a/docs/ai-primitives/_category_.json b/docs/ai-primitives/_category_.json new file mode 100644 index 00000000..967a4127 --- /dev/null +++ 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 new file mode 100644 index 00000000..d45b7c12 --- /dev/null +++ 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 new file mode 100644 index 00000000..eca720c2 --- /dev/null +++ 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 new file mode 100644 index 00000000..a42a2042 --- /dev/null +++ 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 new file mode 100644 index 00000000..2cc176a2 --- /dev/null +++ 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 new file mode 100644 index 00000000..2813bb22 --- /dev/null +++ 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 index 8b4eb426..ef91252c 100644 --- 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 index dc1f215c..cb80cc96 100644 --- a/src/theme/DocSidebar/categories.ts +++ b/src/theme/DocSidebar/categories.ts @@ -12,7 +12,7 @@ export const CATEGORY_CONFIG: Record = { }, 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: {