Upload 5 files

docs/API/SEARCH.md

@@ -0,0 +1,117 @@
+# Perplexica Search API Documentation
+
+## Overview
+
+Perplexica’s Search API makes it easy to use our AI-powered search engine. You can run different types of searches, pick the models you want to use, and get the most recent info. Follow the following headings to learn more about Perplexica's search API.
+
+## Endpoint
+
+### **POST** `http://localhost:3001/api/search`
+
+**Note**: Replace `3001` with any other port if you've changed the default PORT
+
+### Request
+
+The API accepts a JSON object in the request body, where you define the focus mode, chat models, embedding models, and your query.
+
+#### Request Body Structure
+
+```json
+{
+  "chatModel": {
+    "provider": "openai",
+    "model": "gpt-4o-mini"
+  },
+  "embeddingModel": {
+    "provider": "openai",
+    "model": "text-embedding-3-large"
+  },
+  "optimizationMode": "speed",
+  "focusMode": "webSearch",
+  "query": "What is Perplexica",
+  "history": [
+    ["human", "Hi, how are you?"],
+    ["assistant", "I am doing well, how can I help you today?"]
+  ]
+}
+```
+
+### Request Parameters
+
+- **`chatModel`** (object, optional): Defines the chat model to be used for the query. For model details you can send a GET request at `http://localhost:3001/api/models`. Make sure to use the key value (For example "gpt-4o-mini" instead of the display name "GPT 4 omni mini").
+
+  - `provider`: Specifies the provider for the chat model (e.g., `openai`, `ollama`).
+  - `model`: The specific model from the chosen provider (e.g., `gpt-4o-mini`).
+  - Optional fields for custom OpenAI configuration:
+    - `customOpenAIBaseURL`: If you’re using a custom OpenAI instance, provide the base URL.
+    - `customOpenAIKey`: The API key for a custom OpenAI instance.
+
+- **`embeddingModel`** (object, optional): Defines the embedding model for similarity-based searching. For model details you can send a GET request at `http://localhost:3001/api/models`. Make sure to use the key value (For example "text-embedding-3-large" instead of the display name "Text Embedding 3 Large").
+
+  - `provider`: The provider for the embedding model (e.g., `openai`).
+  - `model`: The specific embedding model (e.g., `text-embedding-3-large`).
+
+- **`focusMode`** (string, required): Specifies which focus mode to use. Available modes:
+
+  - `webSearch`, `academicSearch`, `writingAssistant`, `wolframAlphaSearch`, `youtubeSearch`, `redditSearch`.
+
+- **`optimizationMode`** (string, optional): Specifies the optimization mode to control the balance between performance and quality. Available modes:
+
+  - `speed`: Prioritize speed and return the fastest answer.
+  - `balanced`: Provide a balanced answer with good speed and reasonable quality.
+
+- **`query`** (string, required): The search query or question.
+
+- **`history`** (array, optional): An array of message pairs representing the conversation history. Each pair consists of a role (either 'human' or 'assistant') and the message content. This allows the system to use the context of the conversation to refine results. Example:
+
+  ```json
+  [
+    ["human", "What is Perplexica?"],
+    ["assistant", "Perplexica is an AI-powered search engine..."]
+  ]
+  ```
+
+### Response
+
+The response from the API includes both the final message and the sources used to generate that message.
+
+#### Example Response
+
+```json
+{
+	"message": "Perplexica is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online. Here are some key features and characteristics of Perplexica:\n\n- **AI-Powered Technology**: It utilizes advanced machine learning algorithms to not only retrieve information but also to understand the context and intent behind user queries, providing more relevant results [1][5].\n\n- **Open-Source**: Being open-source, Perplexica offers flexibility and transparency, allowing users to explore its functionalities without the constraints of proprietary software [3][10].",
+	"sources": [
+		{
+			"pageContent": "Perplexica is an innovative, open-source AI-powered search engine designed to enhance the way users search for information online.",
+			"metadata": {
+				"title": "What is Perplexica, and how does it function as an AI-powered search ...",
+				"url": "https://askai.glarity.app/search/What-is-Perplexica--and-how-does-it-function-as-an-AI-powered-search-engine"
+			}
+		},
+		{
+			"pageContent": "Perplexica is an open-source AI-powered search tool that dives deep into the internet to find precise answers.",
+			"metadata": {
+				"title": "Sahar Mor's Post",
+				"url": "https://www.linkedin.com/posts/sahar-mor_a-new-open-source-project-called-perplexica-activity-7204489745668694016-ncja"
+			}
+		}
+        ....
+	]
+}
+```
+
+### Fields in the Response
+
+- **`message`** (string): The search result, generated based on the query and focus mode.
+- **`sources`** (array): A list of sources that were used to generate the search result. Each source includes:
+  - `pageContent`: A snippet of the relevant content from the source.
+  - `metadata`: Metadata about the source, including:
+    - `title`: The title of the webpage.
+    - `url`: The URL of the webpage.
+
+### Error Handling
+
+If an error occurs during the search process, the API will return an appropriate error message with an HTTP status code.
+
+- **400**: If the request is malformed or missing required fields (e.g., no focus mode or query).
+- **500**: If an internal server error occurs during the search.

docs/architecture/README.md

@@ -0,0 +1,11 @@
+## Perplexica's Architecture
+
+Perplexica's architecture consists of the following key components:
+
+1. **User Interface**: A web-based interface that allows users to interact with Perplexica for searching images, videos, and much more.
+2. **Agent/Chains**: These components predict Perplexica's next actions, understand user queries, and decide whether a web search is necessary.
+3. **SearXNG**: A metadata search engine used by Perplexica to search the web for sources.
+4. **LLMs (Large Language Models)**: Utilized by agents and chains for tasks like understanding content, writing responses, and citing sources. Examples include Claude, GPTs, etc.
+5. **Embedding Models**: To improve the accuracy of search results, embedding models re-rank the results using similarity search algorithms such as cosine similarity and dot product distance.
+
+For a more detailed explanation of how these components work together, see [WORKING.md](https://github.com/ItzCrazyKns/Perplexica/tree/master/docs/architecture/WORKING.md).

docs/architecture/WORKING.md

@@ -0,0 +1,19 @@
+## How does Perplexica work?
+
+Curious about how Perplexica works? Don't worry, we'll cover it here. Before we begin, make sure you've read about the architecture of Perplexica to ensure you understand what it's made up of. Haven't read it? You can read it [here](https://github.com/ItzCrazyKns/Perplexica/tree/master/docs/architecture/README.md).
+
+We'll understand how Perplexica works by taking an example of a scenario where a user asks: "How does an A.C. work?". We'll break down the process into steps to make it easier to understand. The steps are as follows:
+
+1. The message is sent via WS to the backend server where it invokes the chain. The chain will depend on your focus mode. For this example, let's assume we use the "webSearch" focus mode.
+2. The chain is now invoked; first, the message is passed to another chain where it first predicts (using the chat history and the question) whether there is a need for sources and searching the web. If there is, it will generate a query (in accordance with the chat history) for searching the web that we'll take up later. If not, the chain will end there, and then the answer generator chain, also known as the response generator, will be started.
+3. The query returned by the first chain is passed to SearXNG to search the web for information.
+4. After the information is retrieved, it is based on keyword-based search. We then convert the information into embeddings and the query as well, then we perform a similarity search to find the most relevant sources to answer the query.
+5. After all this is done, the sources are passed to the response generator. This chain takes all the chat history, the query, and the sources. It generates a response that is streamed to the UI.
+
+### How are the answers cited?
+
+The LLMs are prompted to do so. We've prompted them so well that they cite the answers themselves, and using some UI magic, we display it to the user.
+
+### Image and Video Search
+
+Image and video searches are conducted in a similar manner. A query is always generated first, then we search the web for images and videos that match the query. These results are then returned to the user.

docs/installation/NETWORKING.md

@@ -0,0 +1,109 @@
+# Expose Perplexica to a network
+
+This guide will show you how to make Perplexica available over a network. Follow these steps to allow computers on the same network to interact with Perplexica. Choose the instructions that match the operating system you are using.
+
+## Windows
+
+1. Open PowerShell as Administrator
+
+2. Navigate to the directory containing the `docker-compose.yaml` file
+
+3. Stop and remove the existing Perplexica containers and images:
+
+```
+docker compose down --rmi all
+```
+
+4. Open the `docker-compose.yaml` file in a text editor like Notepad++
+
+5. Replace `127.0.0.1` with the IP address of the server Perplexica is running on in these two lines:
+
+```
+args:
+  - NEXT_PUBLIC_API_URL=http://127.0.0.1:3001/api
+  - NEXT_PUBLIC_WS_URL=ws://127.0.0.1:3001
+```
+
+6. Save and close the `docker-compose.yaml` file
+
+7. Rebuild and restart the Perplexica container:
+
+```
+docker compose up -d --build
+```
+
+## macOS
+
+1. Open the Terminal application
+
+2. Navigate to the directory with the `docker-compose.yaml` file:
+
+```
+cd /path/to/docker-compose.yaml
+```
+
+3. Stop and remove existing containers and images:
+
+```
+docker compose down --rmi all
+```
+
+4. Open `docker-compose.yaml` in a text editor like Sublime Text:
+
+```
+nano docker-compose.yaml
+```
+
+5. Replace `127.0.0.1` with the server IP in these lines:
+
+```
+args:
+  - NEXT_PUBLIC_API_URL=http://127.0.0.1:3001/api
+  - NEXT_PUBLIC_WS_URL=ws://127.0.0.1:3001
+```
+
+6. Save and exit the editor
+
+7. Rebuild and restart Perplexica:
+
+```
+docker compose up -d --build
+```
+
+## Linux
+
+1. Open the terminal
+
+2. Navigate to the `docker-compose.yaml` directory:
+
+```
+cd /path/to/docker-compose.yaml
+```
+
+3. Stop and remove containers and images:
+
+```
+docker compose down --rmi all
+```
+
+4. Edit `docker-compose.yaml`:
+
+```
+nano docker-compose.yaml
+```
+
+5. Replace `127.0.0.1` with the server IP:
+
+```
+args:
+  - NEXT_PUBLIC_API_URL=http://127.0.0.1:3001/api
+  - NEXT_PUBLIC_WS_URL=ws://127.0.0.1:3001
+```
+
+6. Save and exit the editor
+
+7. Rebuild and restart Perplexica:
+
+```
+docker compose up -d --build
+```

docs/installation/UPDATING.md

@@ -0,0 +1,40 @@
+# Update Perplexica to the latest version
+
+To update Perplexica to the latest version, follow these steps:
+
+## For Docker users
+
+1. Clone the latest version of Perplexica from GitHub:
+
+```bash
+   git clone https://github.com/ItzCrazyKns/Perplexica.git
+```
+
+2. Navigate to the Project Directory.
+
+3. Pull latest images from registry.
+
+```bash
+docker compose pull
+```
+
+4. Update and Recreate containers.
+
+```bash
+docker compose up -d
+```
+
+5. Once the command completes running go to http://localhost:3000 and verify the latest changes.
+
+## For non Docker users
+
+1. Clone the latest version of Perplexica from GitHub:
+
+```bash
+   git clone https://github.com/ItzCrazyKns/Perplexica.git
+```
+
+2. Navigate to the Project Directory
+3. Execute `npm i` in both the `ui` folder and the root directory.
+4. Once packages are updated, execute `npm run build` in both the `ui` folder and the root directory.
+5. Finally, start both the frontend and the backend by running `npm run start` in both the `ui` folder and the root directory.