docs: custom system prompts (#825)

oramasearch · Oct 17, 2024 · bea36bb · bea36bb
1 parent 50b631b
commit bea36bb
Show file tree

Hide file tree

Showing 6 changed files with 87 additions and 71 deletions.
diff --git a/packages/docs/config/menu/orama-cloud.ts b/packages/docs/config/menu/orama-cloud.ts
@@ -79,20 +79,10 @@ const oramaCloudMenu = [
           {
             label: 'Providing more context',
             link: '/cloud/answer-engine/providing-additional-knowledge'
-          }
-        ]
-      },
-      {
-        label: 'Custom system prompts',
-        collapsed: true,
-        items: [
-          {
-            label: 'Introduction to Custom System Prompts',
-            link: '/cloud/custom-system-prompts/'
           },
           {
-            label: 'Customizing the system prompts',
-            link: '/cloud/custom-system-prompts/customizing-the-system-prompts'
+            label: 'Answers Customization',
+            link: '/cloud/answer-engine/customizing-the-answers'
           }
         ]
       },

diff --git a/...rompts/customizing-the-system-prompts.mdx → ...answer-engine/customizing-the-answers.mdx b/...rompts/customizing-the-system-prompts.mdx → ...answer-engine/customizing-the-answers.mdx
@@ -1,41 +1,63 @@
 ---
-title: Customizing the System Prompts
-description: Learn how to customize the system prompts in your Orama index.
+title: Answers Customization
+description: Learn how to customize the answer engine behavior in your Orama index.
+next: false
 ---
+import { Steps } from '@astrojs/starlight/components';
 
-When creating an experience using the Orama Answer Engine APIs, you can customize the system prompts to give your users a more personalized experience.
+Orama allows you to define custom instructions (**System Prompts**) that shape how the AI engine responds to users. These prompts can be tailored for various use cases, such as **altering the tone** of the AI, **introducing information** that isn’t in the data sources, or **directing users** toward specific actions.
 
-This guide will help you understand how to customize the system prompts in your Orama index.
+For example, if a user asks about pricing, a system prompt could instruct the AI to suggest visiting a website for details, instead of providing a direct answer. You could also include **more context**, like software versions or other specialized information to ensure more accurate responses.
 
-First of all, let's create a new index. If this is your first time creating a new index, follow [this guide](/cloud/data-sources/static-files/json-file) to set up your first index.
-
-Once you have your index set up, you will find yourself in the index overview page. Click on the "System Prompts" tab on the left menu to access the system prompts settings.
-
-<img src="/cloud/guides/custom-system-prompts/new-index.png" alt="New index" />
+#### Best Practices and Limitations
 
-If you're creating your first system prompt, click on "create system prompt" to get started.
+While System Prompts give you powerful control over the AI’s behavior, they are subject to certain validation rules to maintain safety and efficiency. We implemented **jailbreak protection** to guard against malicious or harmful actions. There are also limits on the length and complexity of prompts to ensure optimal performance.
 
-<img src="/cloud/guides/custom-system-prompts/new-prompt.png" alt="New system prompt" />
+These safeguards ensure that while you have the freedom to shape the AI’s responses, the assistant will always behave in a reliable, secure, and efficient manner.
 
-You can finally customizing the system prompt by performing a number of operations, let's break them down:
+## Customizing AI Answers
 
-<img src="/cloud/guides/custom-system-prompts/customizing-the-prompt.png" alt="Customizing the system prompt" />
+This guide will help you understand how to customize the answers generated by the AI answer engine in your Orama index.
 
-### Giving a name to the system prompt
-
-Every system prompt should have a name. It should be unique and descriptive so that you can easily identify it later.
+First of all, let's create a new index. If this is your first time creating a new index, follow [this guide](/cloud/data-sources/static-files/json-file) to set up your first index.
 
-### Choosing the usage method
+<Steps>
+<ol>
+    <li>
+      <p class="pl-10">Once you have your index set up, you will find yourself in the index overview page. Click on the "**System Prompts**" tab on the left menu to access the system prompts settings.</p>
+
+      <img src="/cloud/guides/custom-system-prompts/new-index.png" alt="New index" class="mx-10" />
+
+      <p class="pl-10">If you're creating your first system prompt, click on "**Create system prompt**" to get started.</p>
+
+      <img src="/cloud/guides/custom-system-prompts/new-prompt.png" alt="New system prompt" class="mx-10" />
+    </li>
+    <li>
+      <p class="pl-10">You can finally customize the system prompt by performing a number of operations, let's break them down:</p>
+      <img src="/cloud/guides/custom-system-prompts/customizing-the-prompt.png" alt="Customizing the system prompt" class="mx-10" />
+    </li>
+    <li>
+      <strong class="pl-10">Giving a name to the system prompt</strong>
+      <p class="pl-10">Every system prompt should have a name. It should be unique and descriptive so that you can easily identify it later.</p>
+    </li>
+    <li>
+      <strong class="pl-10">Usage method</strong>
+      <p class="pl-10">Select how the system prompt should be activated: <strong>Automatic</strong> or <strong>Manual</strong>. See [Usage Methods](#usage-methods) for more details.</p>
+    </li>
+  </ol>
+</Steps>
+
+## Usage Methods
 
 Orama allows you to use the custom system prompts in a few different ways:
 
-#### Automatic
+### Automatic
 
 By default, when giving an answer, Orama will automatically choose the system prompt to use. If you create multiple system prompts, Orama will randomly choose one of them.
 
 This is useful when you want to A/B test which system prompt works best for your users.
 
-#### Manual via SDK
+### Manual via SDK
 
 When set to "manual via SDK", the system prompt will not be used automatically. Instead, you will need to specify the system prompt ID when making a request to the Orama Answer Engine API via the SDK.
 
@@ -90,7 +112,7 @@ await session.ask({
 })
 ```
 
-### Customizing the system prompt
+## Using the editor
 
 You can instruct Orama to behave in a specific way when giving answers to the user. For example, you could say to always reply in Italian, or to reply in a very specific format (like JSON), etc.
 

diff --git a/packages/docs/src/content/docs/cloud/glossary.mdx b/packages/docs/src/content/docs/cloud/glossary.mdx
@@ -4,38 +4,43 @@ description: Learn Orama Cloud and the glossary of this documentation.
 editUrl: false
 prev: true
 next: true
+tableOfContents: false
 ---
 
 Orama Cloud is a next-gen search and answer engine that helps you create a high-performance answer engine for your website or application. This glossary will help you understand the terms used in this documentation.
 
-### Answer Engine
+#### Answer Engine
 
 An answer engine is a software system that provides answers to questions asked by users. The answer engine processes the user's question and generates the most relevant answer from the indexed data in real-time.
 
-### Data Source
+#### Data Source
 
 A data source is where the data comes from. It can be a database, a file, a web page, or any other source of data. The data source is where the search engine gets the data to index and search.
 
-### Deployment
+#### Deployment
 
 Deployment is the process of making your search engine live and available to users. Orama Cloud indexes are immutable, so you need to trigger a new deployment every time you make changes to your index. When you deploy your index, it becomes accessible to your users.
 
-### Document
+#### Document
 
 A document is a piece of data that the search engine indexes and searches. A document can be a web page, a blog post, a product, a user profile, or any other piece of data that you want to make searchable.
 
-### Index
+#### Index
 
 An index is a collection of documents that are searchable and retrievable by the search engine. The index is the core of the search engine, and it is where the search engine stores and retrieves the documents.
 
-### Search Engine
+#### Search Engine
 
 A search engine is a software system that searches for and retrieves information from a database or index. The search engine processes the search query and returns the relevant documents to the user.
 
-### Search Query
+#### Search Query
 
 A search query is a request for information that the user submits to the search engine. The search query can be a keyword, a phrase, or a question. The search engine processes the search query and returns the relevant documents to the user.
 
-### SDK
+#### System Prompts
+
+System prompts are custom instructions that shape how the AI engine responds to users. System prompts can be tailored for various use cases, such as altering the tone of the AI, introducing information that isn’t in the data sources, or directing users toward specific actions.
+
+#### SDK
 
 A software development kit (SDK) is a set of tools, libraries, and documentation that developers use to build software applications. The SDK provides the necessary resources to interact with the software system and build custom applications.
diff --git a/packages/docs/src/content/docs/cloud/ui-components/chat-box.mdx b/packages/docs/src/content/docs/cloud/ui-components/chat-box.mdx
@@ -3,7 +3,7 @@ title: Chat Box
 description: Chat Box component for Orama Cloud UI components.
 editUrl: false
 prev: true
-next: true
+next: false
 ---
 
 

diff --git a/packages/docs/src/content/docs/cloud/ui-components/design-system.mdx b/packages/docs/src/content/docs/cloud/ui-components/design-system.mdx
@@ -2,7 +2,7 @@
 title: UI Components
 description: Orama Cloud offers a ready-to-use design system for your search and answer engine.
 editUrl: false
-prev: true
+prev: false
 next: true
 ---
 import { ShowcaseProfile } from 'starlight-showcases';

diff --git a/packages/docs/src/content/docs/cloud/whats-new.mdx b/packages/docs/src/content/docs/cloud/whats-new.mdx
@@ -1,45 +1,44 @@
 ---
-title: What's new?
+title: Releases
 description: Orama Cloud recent releases and new features.
 editUrl: false
 prev: false
 next: false
+tableOfContents: false
 ---
+import { Aside } from '@astrojs/starlight/components';
 
-This page features the release history of Orama Cloud.<br />
-We continously release new features and new integrations, check them out!
-
-## Releases
-
-The following release history resumes the most relevant features as we release them. Some features might not be fully-documented yet.
+This page features the release history of **[Orama Cloud](https://cloud.orama.com)**. 
+If you are looking for Orama Open Source release history, you can find it here.
 
-### Orama Cloud 3.0 (Latest)
-
-- 🧠 Custom system prompts and AI quality checks.
-- 🤖 [Answers engine](/cloud/answer-engine/) SDK.
-- 👫 Audience management. 
-- 📦 [Web Components](/cloud/ui-components/search-box) library.
-- 🧑‍💻 [Strapi](/cloud/data-sources/native-integrations/strapi) plugin native integration. 
-
-### Orama Cloud 2.5
+We continously release new features and new integrations, check them out!
 
-- 🚀 Extra-large indexes are now supported!
-- ⚙️ [Official SDKs](/cloud/integrating-orama-cloud/official-sdk) for JS, PHP, Swift and Kotlin.
-- 💬 Answers generation. 
-- 🧩 [Searchbox](/cloud/ui-components/search-box) web component. 
+<Aside>
+The following release history resumes the most relevant features as we release them.<br />Some features might not be fully-documented yet.
+</Aside>
 
-### Orama Cloud 2.1
+### Orama Cloud 3.x (Latest)
 
-- 🛍️ [Shopify](/cloud/data-sources/native-integrations/shopify) and Elastic Path native integrations.
-- 🔐 [Secure Proxy](/cloud/orama-ai/orama-secure-proxy) and custom embeddings.
+- 🤖 [Answers engine](/cloud/answer-engine/) SDK
+- 🧠 Custom [system prompts](/cloud/answer-engine/customizing-the-answers)
+- 👫 [Audience management](/cloud/audience-management/introduction) and segmentation
+- 📦 [Web Components](/cloud/ui-components/search-box) library
 
-### Orama Cloud 2.0
+### Orama Cloud 2.x
 
-- 🦖 [Docusaurus](/cloud/data-sources/native-integrations/docusaurus) plugin native integration.
-- 👩‍💻 [REST API](/cloud/data-sources/custom-integrations/rest-apis) custom http integrations.
+- ⚙️ [Official SDKs](/cloud/integrating-orama-cloud/official-sdk) for JS, PHP, Swift and Kotlin
+- 💬 Answers generation
+- 🧩 [Searchbox](/cloud/ui-components/search-box) web component
+- 🔐 [Secure Proxy](/cloud/orama-ai/orama-secure-proxy) and custom embeddings
+- 🕸️ [Web Crawler](/cloud/data-sources/other-sources/web-crawler) to scrape your website data
+- 🧑‍💻 [Strapi](/cloud/data-sources/native-integrations/strapi) plugin native integration
+- 🛍️ [Shopify](/cloud/data-sources/native-integrations/shopify) and Elastic Path native integrations
 
 ### Orama Cloud 1.0
 
-- 🏄‍♂️ Bringing the Orama search experience on the edge!
-- 🔥 Unlimited full-text, vector and hybrid search.
-- 🤖 [Embeddings generation](/cloud/orama-ai/automatic-embeddings-generation).
+- 🏄‍♂️ Bringing Orama's blazing-fast search experience to the cloud!
+- 🔥 Unlimited full-text, vector and hybrid search
+- 📊 Analytics and insights
+- 🤖 [Embeddings generation](/cloud/orama-ai/automatic-embeddings-generation)
+- 🦖 [Docusaurus](/cloud/data-sources/native-integrations/docusaurus) plugin native integration
+- 🔨 [REST API](/cloud/data-sources/custom-integrations/rest-apis) custom http integrations