Merge branch 'canary'

Author: ItzCrazyKns

CONTRIBUTING.md

@@ -11,33 +11,63 @@ Perplexica's codebase is organized as follows:
 - **UI Components and Pages**:
   - **Components (`src/components`)**: Reusable UI components.
   - **Pages and Routes (`src/app`)**: Next.js app directory structure with page components.
-    - Main app routes include: home (`/`), chat (`/c`), discover (`/discover`), library (`/library`), and settings (`/settings`).
-  - **API Routes (`src/app/api`)**: API endpoints implemented with Next.js API routes.
-    - `/api/chat`: Handles chat interactions.
-    - `/api/search`: Provides direct access to Perplexica's search capabilities.
-    - Other endpoints for models, files, and suggestions.
+    - Main app routes include: home (`/`), chat (`/c`), discover (`/discover`), and library (`/library`).
+  - **API Routes (`src/app/api`)**: Server endpoints implemented with Next.js route handlers.
 - **Backend Logic (`src/lib`)**: Contains all the backend functionality including search, database, and API logic.
-  - The search functionality is present inside `src/lib/search` directory.
-  - All of the focus modes are implemented using the Meta Search Agent class in `src/lib/search/metaSearchAgent.ts`.
+  - The search system lives in `src/lib/agents/search`.
+  - The search pipeline is split into classification, research, widgets, and writing.
   - Database functionality is in `src/lib/db`.
-  - Chat model and embedding model providers are managed in `src/lib/providers`.
-  - Prompt templates and LLM chain definitions are in `src/lib/prompts` and `src/lib/chains` respectively.
+  - Chat model and embedding model providers are in `src/lib/models/providers`, and models are loaded via `src/lib/models/registry.ts`.
+  - Prompt templates are in `src/lib/prompts`.
+  - SearXNG integration is in `src/lib/searxng.ts`.
+  - Upload search lives in `src/lib/uploads`.
+
+### Where to make changes
+
+If you are not sure where to start, use this section as a map.
+
+- **Search behavior and reasoning**
+
+  - `src/lib/agents/search` contains the core chat and search pipeline.
+  - `classifier.ts` decides whether research is needed and what should run.
+  - `researcher/` gathers information in the background.
+
+- **Add or change a search capability**
+
+  - Research tools (web, academic, discussions, uploads, scraping) live in `src/lib/agents/search/researcher/actions`.
+  - Tools are registered in `src/lib/agents/search/researcher/actions/index.ts`.
+
+- **Add or change widgets**
+
+  - Widgets live in `src/lib/agents/search/widgets`.
+  - Widgets run in parallel with research and show structured results in the UI.
+
+- **Model integrations**
+
+  - Providers live in `src/lib/models/providers`.
+  - Add new providers there and wire them into the model registry so they show up in the app.
+
+- **Architecture docs**
+  - High level overview: `docs/architecture/README.md`
+  - High level flow: `docs/architecture/WORKING.md`
 
 ## API Documentation
 
-Perplexica exposes several API endpoints for programmatic access, including:
+Perplexica includes API documentation for programmatic access.
 
-- **Search API**: Access Perplexica's advanced search capabilities directly via the `/api/search` endpoint. For detailed documentation, see `docs/api/search.md`.
+- **Search API**: For detailed documentation, see `docs/API/SEARCH.md`.
 
 ## Setting Up Your Environment
 
 Before diving into coding, setting up your local environment is key. Here's what you need to do:
 
-1. In the root directory, locate the `sample.config.toml` file.
-2. Rename it to `config.toml` and fill in the necessary configuration fields.
-3. Run `npm install` to install all dependencies.
-4. Run `npm run db:migrate` to set up the local sqlite database.
-5. Use `npm run dev` to start the application in development mode.
+1. Run `npm install` to install all dependencies.
+2. Use `npm run dev` to start the application in development mode.
+3. Open http://localhost:3000 and complete the setup in the UI (API keys, models, search backend URL, etc.).
+
+Database migrations are applied automatically on startup.
+
+For full installation options (Docker and non Docker), see the installation guide in the repository README.
 
 **Please note**: Docker configurations are present for setting up production environments, whereas `npm run dev` is used for development purposes.
 

README.md

@@ -18,9 +18,11 @@ Want to know more about its architecture and how it works? You can read it [here
 
 🤖 **Support for all major AI providers** - Use local LLMs through Ollama or connect to OpenAI, Anthropic Claude, Google Gemini, Groq, and more. Mix and match models based on your needs.
 
-⚡ **Smart search modes** - Choose Balanced Mode for everyday searches, Fast Mode when you need quick answers, or wait for Quality Mode (coming soon) for deep research.
+⚡ **Smart search modes** - Choose Speed Mode when you need quick answers, Balanced Mode for everyday searches, or Quality Mode for deep research.
 
-🎯 **Six specialized focus modes** - Get better results with modes designed for specific tasks: Academic papers, YouTube videos, Reddit discussions, Wolfram Alpha calculations, writing assistance, or general web search.
+🧭 **Pick your sources** - Search the web, discussions, or academic papers. More sources and integrations are in progress.
+
+🧩 **Widgets** - Helpful UI cards that show up when relevant, like weather, calculations, stock prices, and other quick lookups.
 
 🔍 **Web search powered by SearxNG** - Access multiple search engines while keeping your identity private. Support for Tavily and Exa coming soon for even better results.
 
@@ -81,7 +83,7 @@ There are mainly 2 ways of installing Perplexica - With Docker, Without Docker.
 Perplexica can be easily run using Docker. Simply run the following command:
 
 ```bash
-docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data -v perplexica-uploads:/home/perplexica/uploads --name perplexica itzcrazykns1337/perplexica:latest
+docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:latest
 ```
 
 This will pull and start the Perplexica container with the bundled SearxNG search engine. Once running, open your browser and navigate to http://localhost:3000. You can then configure your settings (API keys, models, etc.) directly in the setup screen.
@@ -93,7 +95,7 @@ This will pull and start the Perplexica container with the bundled SearxNG searc
 If you already have SearxNG running, you can use the slim version of Perplexica:
 
 ```bash
-docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v perplexica-data:/home/perplexica/data -v perplexica-uploads:/home/perplexica/uploads --name perplexica itzcrazykns1337/perplexica:slim-latest
+docker run -d -p 3000:3000 -e SEARXNG_API_URL=http://your-searxng-url:8080 -v perplexica-data:/home/perplexica/data --name perplexica itzcrazykns1337/perplexica:slim-latest
 ```
 
 **Important**: Make sure your SearxNG instance has:
@@ -120,7 +122,7 @@ If you prefer to build from source or need more control:
 
    ```bash
    docker build -t perplexica .
-   docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data -v perplexica-uploads:/home/perplexica/uploads --name perplexica perplexica
+   docker run -d -p 3000:3000 -v perplexica-data:/home/perplexica/data --name perplexica perplexica
    ```
 
 5. Access Perplexica at http://localhost:3000 and configure your settings in the setup screen.
@@ -237,13 +239,8 @@ Perplexica runs on Next.js and handles all API requests. It works right away on
 
 ## Upcoming Features
 
-- [x] Add settings page
-- [x] Adding support for local LLMs
-- [x] History Saving features
-- [x] Introducing various Focus Modes
-- [x] Adding API support
-- [x] Adding Discover
-- [ ] Finalizing Copilot Mode
+- [ ] Adding more widgets, integrations, search sources
+- [ ] Adding authentication
 
 ## Support Us
 

docker-compose.yaml

@@ -1,6 +1,8 @@
 services:
   perplexica:
     image: itzcrazykns1337/perplexica:latest
+    build:
+      context: .
     ports:
       - '3000:3000'
     volumes:

docs/API/SEARCH.md

@@ -57,7 +57,7 @@ Use the `id` field as the `providerId` and the `key` field from the models array
 
 ### Request
 
-The API accepts a JSON object in the request body, where you define the focus mode, chat models, embedding models, and your query.
+The API accepts a JSON object in the request body, where you define the enabled search `sources`, chat models, embedding models, and your query.
 
 #### Request Body Structure
 
@@ -72,7 +72,7 @@ The API accepts a JSON object in the request body, where you define the focus mo
     "key": "text-embedding-3-large"
   },
   "optimizationMode": "speed",
-  "focusMode": "webSearch",
+  "sources": ["web"],
   "query": "What is Perplexica",
   "history": [
     ["human", "Hi, how are you?"],
@@ -87,24 +87,25 @@ The API accepts a JSON object in the request body, where you define the focus mo
 
 ### Request Parameters
 
-- **`chatModel`** (object, optional): Defines the chat model to be used for the query. To get available providers and models, send a GET request to `http://localhost:3000/api/providers`.
+- **`chatModel`** (object, required): Defines the chat model to be used for the query. To get available providers and models, send a GET request to `http://localhost:3000/api/providers`.
 
   - `providerId` (string): The UUID of the provider. You can get this from the `/api/providers` endpoint response.
   - `key` (string): The model key/identifier (e.g., `gpt-4o-mini`, `llama3.1:latest`). Use the `key` value from the provider's `chatModels` array, not the display name.
 
-- **`embeddingModel`** (object, optional): Defines the embedding model for similarity-based searching. To get available providers and models, send a GET request to `http://localhost:3000/api/providers`.
+- **`embeddingModel`** (object, required): Defines the embedding model for similarity-based searching. To get available providers and models, send a GET request to `http://localhost:3000/api/providers`.
 
   - `providerId` (string): The UUID of the embedding provider. You can get this from the `/api/providers` endpoint response.
   - `key` (string): The embedding model key (e.g., `text-embedding-3-large`, `nomic-embed-text`). Use the `key` value from the provider's `embeddingModels` array, not the display name.
 
-- **`focusMode`** (string, required): Specifies which focus mode to use. Available modes:
+- **`sources`** (array, required): Which search sources to enable. Available values:
 
-  - `webSearch`, `academicSearch`, `writingAssistant`, `wolframAlphaSearch`, `youtubeSearch`, `redditSearch`.
+  - `web`, `academic`, `discussions`.
 
 - **`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.
+  - `quality`: Prioritize answer quality (may be slower).
 
 - **`query`** (string, required): The search query or question.
 
@@ -132,14 +133,14 @@ The response from the API includes both the final message and the sources used t
   "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.",
+      "content": "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.",
+      "content": "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"
@@ -158,7 +159,7 @@ Example of streamed response objects:
 
 ```
 {"type":"init","data":"Stream connected"}
-{"type":"sources","data":[{"pageContent":"...","metadata":{"title":"...","url":"..."}},...]}
+{"type":"sources","data":[{"content":"...","metadata":{"title":"...","url":"..."}},...]}
 {"type":"response","data":"Perplexica is an "}
 {"type":"response","data":"innovative, open-source "}
 {"type":"response","data":"AI-powered search engine..."}
@@ -174,9 +175,9 @@ Clients should process each line as a separate JSON object. The different messag
 
 ### Fields in the Response
 
-- **`message`** (string): The search result, generated based on the query and focus mode.
+- **`message`** (string): The search result, generated based on the query and enabled `sources`.
 - **`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.
+  - `content`: 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.
@@ -185,5 +186,5 @@ Clients should process each line as a separate JSON object. The different messag
 
 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).
+- **400**: If the request is malformed or missing required fields (e.g., no `sources` or `query`).
 - **500**: If an internal server error occurs during the search.

docs/architecture/README.md

@@ -1,11 +1,38 @@
-# Perplexica's Architecture
+# Perplexica Architecture
 
-Perplexica's architecture consists of the following key components:
+Perplexica is a Next.js application that combines an AI chat experience with search.
 
-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 high level flow, see [WORKING.md](WORKING.md). For deeper implementation details, see [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
-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).
+## Key components
+
+1. **User Interface**
+
+   - A web based UI that lets users chat, search, and view citations.
+
+2. **API Routes**
+
+   - `POST /api/chat` powers the chat UI.
+   - `POST /api/search` provides a programmatic search endpoint.
+   - `GET /api/providers` lists available providers and model keys.
+
+3. **Agents and Orchestration**
+
+   - The system classifies the question first.
+   - It can run research and widgets in parallel.
+   - It generates the final answer and includes citations.
+
+4. **Search Backend**
+
+   - A meta search backend is used to fetch relevant web results when research is enabled.
+
+5. **LLMs (Large Language Models)**
+
+   - Used for classification, writing answers, and producing citations.
+
+6. **Embedding Models**
+
+   - Used for semantic search over user uploaded files.
+
+7. **Storage**
+   - Chats and messages are stored so conversations can be reloaded.