Chore: Add documentation on how to build a RAG with Orama (#857)

packages/docs/src/content/docs/open-source/plugins/writing-your-own-plugins.mdx

@@ -66,6 +66,24 @@ Every plugin should have:
 - A `name` property, which is a string (**mandatory**)
 - Any hook function you want to use (**optional**)
 
+
+:::caution
+When working with `async` hooks remember to always use the `async` keyword modifier.
+
+```js
+async function afterInsertPluginExample() {
+  return {
+    name: "after-insert-plugin",
+    afterInsert: async (orama, id, document) => {
+      console.log("Orama instance: ", orama);
+      console.log("Document id: ", id);
+      console.log("Document inserted: ", document);
+    },
+  };
+}
+```
+:::
+
 ## Plugin hooks
 
 With `v2.0.0-beta.5`, we essentially moved the hooks from the `components` property of the Orama instance to the `plugins` property.

packages/docs/src/content/docs/open-source/usage/answer-engine/introduction.mdx

@@ -119,4 +119,118 @@ In the example above, the `onStateChange` will be triggered for every new object
     errorMessage: null,
   }
 ]
+```
+
+## RAG implementation
+
+Orama provides a comprehensive toolkit for building high-performance RAG (Retrieval-Augmented Generation) pipelines tailored to your document processing needs.
+
+Below is a simple example demonstrating how to set up your application to leverage Orama's database capabilities and the [Secure Proxy Plugin](/cloud/orama-ai/orama-secure-proxy) for document-based answer generation.
+
+```ts copy
+import { create, insert, search, AnswerSession } from "@orama/orama";
+import { pluginSecureProxy } from "@orama/plugin-secure-proxy";
+
+// Configuration options for better maintainability
+const CONFIG = {
+  API_KEY: process.env.ORAMA_SECURE_PROXY_API_KEY,
+  VECTOR_DIMENSIONS: 1536,
+};
+
+// Sample documents
+const SAMPLE_DOCS = [
+  { description: "John Doe is a programmer, and he has 14 years." },
+  { description: "Mitch Smith is a programmer, and he has 32 years." },
+];
+
+/**
+ * Initialize the Orama database with secure proxy plugin
+ * @returns {Promise<Object>} Configured database instance
+ */
+async function initializeDatabase() {
+  const secureProxy = await pluginSecureProxy({
+    apiKey: CONFIG.API_KEY,
+    embeddings: {
+      model: "openai/text-embedding-ada-002",
+      defaultProperty: "embeddings",
+      onInsert: {
+        generate: true,
+        properties: ["description"],
+        verbose: true,
+      },
+    },
+    chat: {
+      model: "openai/gpt-3.5-turbo",
+    },
+  });
+
+  return create({
+    schema: {
+      description: "string",
+      embeddings: `vector[${CONFIG.VECTOR_DIMENSIONS}]`,
+    },
+    plugins: [secureProxy],
+  });
+}
+
+/**
+ * Populate the database with documents
+ * @param {Object} db - Database instance
+ * @param {Array} documents - Array of documents to insert
+ */
+async function populateDatabase(db, documents) {
+  const insertPromises = documents.map((doc) =>
+    insert(db, { description: doc.description })
+  );
+  await Promise.all(insertPromises);
+}
+
+/**
+ * Perform vector search and generate response
+ * @param {Object} db - Database instance
+ * @param {string} userPrompt - User's question
+ * @returns {Promise<string>} Generated response
+ */
+async function generateResponse(db, userPrompt) {
+  try {
+    const searchResults = await search(db, {
+      mode: "vector",
+      term: userPrompt,
+    });
+
+    const formattedPrompt = `### Context: \n\n${JSON.stringify(
+      searchResults?.hits
+    )}\n\n### Prompt:\n\n${userPrompt}`;
+
+    const session = new AnswerSession(db, {});
+    return await session.ask({ term: formattedPrompt });
+  } catch (error) {
+    console.error("Error generating response:", error);
+    throw error;
+  }
+}
+
+/**
+ * Main execution function
+ */
+async function main() {
+  try {
+    // Initialize database
+    const db = await initializeDatabase();
+
+    // Populate with sample data
+    await populateDatabase(db, SAMPLE_DOCS);
+
+    // Example query
+    const userPrompt = "Who is John Doe?";
+    const response = await generateResponse(db, userPrompt);
+
+    console.log("Response:", response);
+  } catch (error) {
+    console.error("Application error:", error);
+  }
+}
+
+// Execute the application
+main();
 ```