Sync to HuggingFace Spaces

.dockerignore

@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+

.editorconfig

@@ -0,0 +1,7 @@
+[*]
+charset = utf-8
+insert_final_newline = true
+end_of_line = lf
+indent_style = space
+indent_size = 2
+max_line_length = 80

.env.example

@@ -0,0 +1,29 @@
+# A comma-separated list of access keys. Example: `ACCESS_KEYS="ABC123,JUD71F,HUWE3"`. Leave blank for unrestricted access.
+ACCESS_KEYS=""
+
+# The timeout in hours for access key validation. Set to 0 to require validation on every page load.
+ACCESS_KEY_TIMEOUT_HOURS="24"
+
+# The default model ID for WebLLM with F16 shaders.
+WEBLLM_DEFAULT_F16_MODEL_ID="Qwen2.5-0.5B-Instruct-q4f16_1-MLC"
+
+# The default model ID for WebLLM with F32 shaders.
+WEBLLM_DEFAULT_F32_MODEL_ID="Qwen2.5-0.5B-Instruct-q4f32_1-MLC"
+
+# The default model ID for Wllama.
+WLLAMA_DEFAULT_MODEL_ID="qwen-2.5-0.5b"
+
+# The base URL for the internal OpenAI compatible API. Example: `INTERNAL_OPENAI_COMPATIBLE_API_BASE_URL="https://api.openai.com/v1"`. Leave blank to disable internal OpenAI compatible API.
+INTERNAL_OPENAI_COMPATIBLE_API_BASE_URL=""
+
+# The access key for the internal OpenAI compatible API.
+INTERNAL_OPENAI_COMPATIBLE_API_KEY=""
+
+# The model for the internal OpenAI compatible API.
+INTERNAL_OPENAI_COMPATIBLE_API_MODEL=""
+
+# The name of the internal OpenAI compatible API, displayed in the UI.
+INTERNAL_OPENAI_COMPATIBLE_API_NAME="Internal API"
+
+# The type of inference to use by default. Options: "browser" (browser-based), "openai" (OpenAI-compatible API), "internal" (internal API).
+DEFAULT_INFERENCE_TYPE="browser"

.github/workflows/on-pull-request-to-main.yml

@@ -0,0 +1,7 @@
+name: On Pull Request To Main
+on:
+  pull_request:
+    branches: ["main"]
+jobs:
+  test-lint-ping:
+    uses: ./.github/workflows/reusable-test-lint-ping.yml

.github/workflows/on-push-to-main.yml

@@ -0,0 +1,56 @@
+name: On Push To Main
+on:
+  push:
+    branches: ["main"]
+jobs:
+  test-lint-ping:
+    uses: ./.github/workflows/reusable-test-lint-ping.yml
+  build-and-push-image:
+    needs: [test-lint-ping]
+    name: Publish Docker image to GitHub Packages
+    runs-on: ubuntu-latest
+    env:
+      REGISTRY: ghcr.io
+      IMAGE_NAME: ${{ github.repository }}
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64,linux/arm64
+  sync-to-hf:
+    needs: [test-lint-ping]
+    name: Sync to HuggingFace Spaces
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+      - uses: JacobLinCool/huggingface-sync@v1
+        with:
+          github: ${{ secrets.GITHUB_TOKEN }}
+          user: ${{ vars.HF_SPACE_OWNER }}
+          space: ${{ vars.HF_SPACE_NAME }}
+          token: ${{ secrets.HF_TOKEN }}
+          configuration: "hf-space-config.yml"

.github/workflows/reusable-test-lint-ping.yml

@@ -0,0 +1,25 @@
+on:
+  workflow_call:
+jobs:
+  check-code-quality:
+    name: Check Code Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+      - run: npm ci --ignore-scripts
+      - run: npm test
+      - run: npm run lint
+  check-docker-container:
+    needs: [check-code-quality]
+    name: Check Docker Container
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker compose -f docker-compose.production.yml up -d
+      - name: Check if main page is available
+        run: until curl -s -o /dev/null -w "%{http_code}" localhost:7860 | grep 200; do sleep 1; done
+      - run: docker compose -f docker-compose.production.yml down

.github/workflows/update-searxng-docker-image.yml

@@ -0,0 +1,44 @@
+name: Update SearXNG Docker Image
+
+on:
+  schedule:
+    - cron: "0 14 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  update-searxng-image:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get latest SearXNG image tag
+        id: get_latest_tag
+        run: |
+          LATEST_TAG=$(curl -s "https://hub.docker.com/v2/repositories/searxng/searxng/tags/?page_size=3&ordering=last_updated" | jq -r '.results[] | select(.name != "latest-build-cache" and .name != "latest") | .name' | head -n 1)
+          echo "LATEST_TAG=${LATEST_TAG}" >> $GITHUB_OUTPUT
+
+      - name: Update Dockerfile
+        run: |
+          sed -i 's|FROM searxng/searxng:.*|FROM searxng/searxng:${{ steps.get_latest_tag.outputs.LATEST_TAG }}|' Dockerfile
+
+      - name: Check for changes
+        id: git_status
+        run: |
+          git diff --exit-code || echo "changes=true" >> $GITHUB_OUTPUT
+
+      - name: Commit and push if changed
+        if: steps.git_status.outputs.changes == 'true'
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add Dockerfile
+          git commit -m "Update SearXNG Docker image to tag ${{ steps.get_latest_tag.outputs.LATEST_TAG }}"
+          git push
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,7 @@
+node_modules
+.DS_Store
+/client/dist
+/server/models
+.vscode
+/vite-build-stats.html
+.env

.npmrc

@@ -0,0 +1 @@
+legacy-peer-deps = true

Dockerfile

@@ -0,0 +1,82 @@
+# Use the SearXNG image as the base
+FROM searxng/searxng:2024.10.23-b14d885f2
+
+# Set the default port to 7860 if not provided
+ENV PORT=7860
+
+# Expose the port specified by the PORT environment variable
+EXPOSE $PORT
+
+# Install necessary packages using Alpine's package manager
+RUN apk add --update \
+  nodejs \
+  npm \
+  git \
+  build-base \
+  cmake \
+  ccache
+
+# Set the SearXNG settings folder path
+ARG SEARXNG_SETTINGS_FOLDER=/etc/searxng
+
+# Modify SearXNG configuration:
+# 1. Change output format from HTML to JSON
+# 2. Remove user switching in the entrypoint script
+# 3. Create and set permissions for the settings folder
+RUN sed -i 's/- html/- json/' /usr/local/searxng/searx/settings.yml \
+  && sed -i 's/su-exec searxng:searxng //' /usr/local/searxng/dockerfiles/docker-entrypoint.sh \
+  && mkdir -p ${SEARXNG_SETTINGS_FOLDER}  \
+  && chmod 777 ${SEARXNG_SETTINGS_FOLDER}
+
+# Set up user and directory structure
+ARG USERNAME=user
+ARG HOME_DIR=/home/${USERNAME}
+ARG APP_DIR=${HOME_DIR}/app
+
+# Create a non-root user and set up the application directory
+RUN adduser -D -u 1000 ${USERNAME} \
+  && mkdir -p ${APP_DIR} \
+  && chown -R ${USERNAME}:${USERNAME} ${HOME_DIR}
+
+# Switch to the non-root user
+USER ${USERNAME}
+
+# Set the working directory to the application directory
+WORKDIR ${APP_DIR}
+
+# Define environment variables that can be passed to the container during build.
+# This approach allows for dynamic configuration without relying on a `.env` file,
+# which might not be suitable for all deployment scenarios.
+ARG ACCESS_KEYS
+ARG ACCESS_KEY_TIMEOUT_HOURS
+ARG WEBLLM_DEFAULT_F16_MODEL_ID
+ARG WEBLLM_DEFAULT_F32_MODEL_ID
+ARG WLLAMA_DEFAULT_MODEL_ID
+ARG INTERNAL_OPENAI_COMPATIBLE_API_BASE_URL
+ARG INTERNAL_OPENAI_COMPATIBLE_API_KEY
+ARG INTERNAL_OPENAI_COMPATIBLE_API_MODEL
+ARG INTERNAL_OPENAI_COMPATIBLE_API_NAME
+ARG DEFAULT_INFERENCE_TYPE
+
+# Copy package.json, package-lock.json, and .npmrc files
+COPY --chown=${USERNAME}:${USERNAME} ./package.json ./package.json
+COPY --chown=${USERNAME}:${USERNAME} ./package-lock.json ./package-lock.json
+COPY --chown=${USERNAME}:${USERNAME} ./.npmrc ./.npmrc
+
+# Install Node.js dependencies
+RUN npm ci
+
+# Copy the rest of the application files
+COPY --chown=${USERNAME}:${USERNAME} . .
+
+# Configure Git to treat the app directory as safe
+RUN git config --global --add safe.directory ${APP_DIR}
+
+# Build the application
+RUN npm run build
+
+# Set the entrypoint to use a shell
+ENTRYPOINT [ "/bin/sh", "-c" ]
+
+# Run SearXNG in the background and start the Node.js application using PM2
+CMD [ "(/usr/local/searxng/dockerfiles/docker-entrypoint.sh -f > /dev/null 2>&1) & (npx pm2 start ecosystem.config.cjs && npx pm2 logs production-server)" ]

README.md

@@ -0,0 +1,121 @@
+---
+title: MiniSearch
+emoji: 👌🔍
+colorFrom: yellow
+colorTo: yellow
+sdk: docker
+short_description: Minimalist web-searching app with browser-based AI assistant
+pinned: true
+custom_headers:
+  cross-origin-embedder-policy: require-corp
+  cross-origin-opener-policy: same-origin
+  cross-origin-resource-policy: cross-origin
+---
+
+# MiniSearch
+
+A minimalist web-searching app with an AI assistant that runs directly from your browser.
+
+Live demo: https://felladrin-minisearch.hf.space
+
+## Screenshot
+
+![MiniSearch Screenshot](https://github.com/user-attachments/assets/f8d72a8e-a725-42e9-9358-e6ebade2acb2)
+
+## Features
+
+- **Privacy-focused**: [No tracking, no ads, no data collection](https://docs.searxng.org/own-instance.html#how-does-searxng-protect-privacy)
+- **Easy to use**: Minimalist yet intuitive interface for all users
+- **Cross-platform**: Models run inside the browser, both on desktop and mobile
+- **Integrated**: Search from the browser address bar by setting it as the default search engine
+- **Efficient**: Models are loaded and cached only when needed
+- **Customizable**: Tweakable settings for search results and text generation
+- **Open-source**: [The code is available for inspection and contribution at GitHub](https://github.com/felladrin/MiniSearch)
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/)
+
+## Getting started
+
+There are two ways to get started with MiniSearch. Pick one that suits you best.
+
+**Option 1** - Use [MiniSearch's Docker Image](https://github.com/felladrin/MiniSearch/pkgs/container/minisearch) by running:
+
+```bash
+docker run -p 7860:7860 ghcr.io/felladrin/minisearch:main
+```
+
+**Option 2** - Build from source by [downloading the repository files](https://github.com/felladrin/MiniSearch/archive/refs/heads/main.zip) and running:
+
+```bash
+docker compose -f docker-compose.production.yml up --build
+```
+
+Then, open http://localhost:7860 in your browser and start searching!
+
+## Frequently asked questions
+
+<details>
+  <summary>How do I search via the browser's address bar?</summary>
+  <p>
+    You can set MiniSearch as your browser's address-bar search engine using the pattern <code>http://localhost:7860/?q=%s</code>, in which your search term replaces <code>%s</code>.
+  </p>
+</details>
+
+<details>
+  <summary>Can I use custom models via OpenAI-Compatible API?</summary>
+  <p>
+    Yes! For this, open the Menu and change the "AI Processing Location" to <code>Remote server (API)</code>. Then configure the Base URL, and optionally set an API Key and a Model to use.
+  </p>
+</details>
+
+<details>
+  <summary>How do I restrict the access to my MiniSearch instance via password?</summary>
+  <p>
+    Create a <code>.env</code> file and set a value for <code>ACCESS_KEYS</code>. Then reset the MiniSearch docker container.
+  </p>
+  <p>
+    For example, if you to set the password to <code>PepperoniPizza</code>, then this is what you should add to your <code>.env</code>:<br/>
+    <code>ACCESS_KEYS="PepperoniPizza"</code>
+  </p>
+  <p>
+    You can find more examples in the <code>.env.example</code> file.
+  </p>
+</details>
+
+<details>
+  <summary>I want to serve MiniSearch to other users, allowing them to use my own OpenAI-Compatible API key, but without revealing it to them. Is it possible?</summary>
+  <p>Yes! In MiniSearch, we call this text-generation feature "Internal OpenAI-Compatible API". To use this it:</p>
+  <ol>
+    <li>Set up your OpenAI-Compatible API endpoint by configuring the following environment variables in your <code>.env</code> file:
+      <ul>
+        <li><code>INTERNAL_OPENAI_COMPATIBLE_API_BASE_URL</code>: The base URL for your API</li>
+        <li><code>INTERNAL_OPENAI_COMPATIBLE_API_KEY</code>: Your API access key</li>
+        <li><code>INTERNAL_OPENAI_COMPATIBLE_API_MODEL</code>: The model to use</li>
+        <li><code>INTERNAL_OPENAI_COMPATIBLE_API_NAME</code>: The name to display in the UI</li>
+      </ul>
+    </li>
+    <li>Restart MiniSearch server.</li>
+    <li>In the MiniSearch menu, select the new option (named as per your <code>INTERNAL_OPENAI_COMPATIBLE_API_NAME</code> setting) from the "AI Processing Location" dropdown.</li>
+  </ol>
+</details>
+
+<details>
+  <summary>How can I contribute to the development of this tool?</summary>
+  <p>Fork this repository and clone it. Then, start the development server by running the following command:</p>
+  <p><code>docker compose up</code></p>
+  <p>Make your changes, push them to your fork, and open a pull request! All contributions are welcome!</p>
+</details>
+
+<details>
+  <summary>Why is MiniSearch built upon SearXNG's Docker Image and using a single image instead of composing it from multiple services?</summary>
+  <p>There are a few reasons for this:</p>
+  <ul>
+    <li>MiniSearch utilizes SearXNG as its meta-search engine.</li>
+    <li>Manual installation of SearXNG is not trivial, so we use the docker image they provide, which has everything set up.</li>
+    <li>SearXNG only provides a Docker Image based on Alpine Linux.</li>
+    <li>The user of the image needs to be customized in a specific way to run on HuggingFace Spaces, where MiniSearch's demo runs.</li>
+    <li>HuggingFace only accepts a single docker image. It doesn't run docker compose or multiple images, unfortunately.</li>
+  </ul>
+</details>

client/components/AiResponse/AiModelDownloadAllowanceContent.tsx

@@ -0,0 +1,62 @@
+import { Alert, Button, Group, Text } from "@mantine/core";
+import { IconCheck, IconInfoCircle, IconX } from "@tabler/icons-react";
+import { usePubSub } from "create-pubsub/react";
+import { settingsPubSub } from "../../modules/pubSub";
+import { useState } from "react";
+import { addLogEntry } from "../../modules/logEntries";
+
+export default function AiModelDownloadAllowanceContent() {
+  const [settings, setSettings] = usePubSub(settingsPubSub);
+  const [hasDeniedDownload, setDeniedDownload] = useState(false);
+
+  const handleAccept = () => {
+    setSettings({
+      ...settings,
+      allowAiModelDownload: true,
+    });
+    addLogEntry("User allowed the AI model download");
+  };
+
+  const handleDecline = () => {
+    setDeniedDownload(true);
+    addLogEntry("User denied the AI model download");
+  };
+
+  return hasDeniedDownload ? null : (
+    <Alert
+      variant="light"
+      color="blue"
+      title="Allow AI model download?"
+      icon={<IconInfoCircle />}
+    >
+      <Text size="sm" mb="md">
+        To obtain AI responses, a language model needs to be downloaded to your
+        browser. Enabling this option lets the app store it and load it
+        instantly on subsequent uses.
+      </Text>
+      <Text size="sm" mb="md">
+        Please note that the download size ranges from 100 MB to 4 GB, depending
+        on the model you select in the Menu, so it's best to avoid using mobile
+        data for this.
+      </Text>
+      <Group justify="flex-end" mt="md">
+        <Button
+          variant="subtle"
+          color="gray"
+          leftSection={<IconX size="1rem" />}
+          onClick={handleDecline}
+          size="xs"
+        >
+          Not now
+        </Button>
+        <Button
+          leftSection={<IconCheck size="1rem" />}
+          onClick={handleAccept}
+          size="xs"
+        >
+          Allow download
+        </Button>
+      </Group>
+    </Alert>
+  );
+}

client/components/AiResponse/AiResponseContent.tsx

@@ -0,0 +1,145 @@
+import {
+  ActionIcon,
+  Alert,
+  Badge,
+  Box,
+  Card,
+  CopyButton,
+  Group,
+  ScrollArea,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import {
+  IconArrowsMaximize,
+  IconCheck,
+  IconCopy,
+  IconHandStop,
+  IconInfoCircle,
+} from "@tabler/icons-react";
+import { PublishFunction } from "create-pubsub";
+import { lazy, ReactNode, Suspense, useMemo, useState } from "react";
+import { match } from "ts-pattern";
+
+const FormattedMarkdown = lazy(() => import("./FormattedMarkdown"));
+
+export default function AiResponseContent({
+  textGenerationState,
+  response,
+  setTextGenerationState,
+}: {
+  textGenerationState: string;
+  response: string;
+  setTextGenerationState: PublishFunction<
+    | "failed"
+    | "awaitingSearchResults"
+    | "preparingToGenerate"
+    | "idle"
+    | "loadingModel"
+    | "generating"
+    | "interrupted"
+    | "completed"
+  >;
+}) {
+  const [isScrollAreaEnabled, setScrollAreaEnabled] = useState(true);
+
+  const ConditionalScrollArea = useMemo(
+    () =>
+      ({ children }: { children: ReactNode }) => {
+        return isScrollAreaEnabled ? (
+          <ScrollArea.Autosize mah={300} type="auto" offsetScrollbars>
+            {children}
+          </ScrollArea.Autosize>
+        ) : (
+          <Box>{children}</Box>
+        );
+      },
+    [isScrollAreaEnabled],
+  );
+
+  return (
+    <Card withBorder shadow="sm" radius="md">
+      <Card.Section withBorder inheritPadding py="xs">
+        <Group justify="space-between">
+          <Group gap="xs" align="center">
+            <Text fw={500}>
+              {match(textGenerationState)
+                .with("generating", () => "Generating AI Response...")
+                .otherwise(() => "AI Response")}
+            </Text>
+            {match(textGenerationState)
+              .with("interrupted", () => (
+                <Badge variant="light" color="yellow" size="xs">
+                  Interrupted
+                </Badge>
+              ))
+              .otherwise(() => null)}
+          </Group>
+          <Group gap="xs" align="center">
+            {match(textGenerationState)
+              .with("generating", () => (
+                <Tooltip label="Interrupt generation">
+                  <ActionIcon
+                    onClick={() => setTextGenerationState("interrupted")}
+                    variant="subtle"
+                    color="gray"
+                  >
+                    <IconHandStop size={16} />
+                  </ActionIcon>
+                </Tooltip>
+              ))
+              .otherwise(() => null)}
+            {isScrollAreaEnabled && (
+              <Tooltip label="Show full response without scroll bar">
+                <ActionIcon
+                  onClick={() => setScrollAreaEnabled(false)}
+                  variant="subtle"
+                  color="gray"
+                >
+                  <IconArrowsMaximize size={16} />
+                </ActionIcon>
+              </Tooltip>
+            )}
+            <CopyButton value={response} timeout={2000}>
+              {({ copied, copy }) => (
+                <Tooltip
+                  label={copied ? "Copied" : "Copy response"}
+                  withArrow
+                  position="right"
+                >
+                  <ActionIcon
+                    color={copied ? "teal" : "gray"}
+                    variant="subtle"
+                    onClick={copy}
+                  >
+                    {copied ? <IconCheck size={16} /> : <IconCopy size={16} />}
+                  </ActionIcon>
+                </Tooltip>
+              )}
+            </CopyButton>
+          </Group>
+        </Group>
+      </Card.Section>
+      <Card.Section withBorder>
+        <ConditionalScrollArea>
+          <Suspense>
+            <FormattedMarkdown>{response}</FormattedMarkdown>
+          </Suspense>
+        </ConditionalScrollArea>
+        {match(textGenerationState)
+          .with("failed", () => (
+            <Alert
+              variant="light"
+              color="yellow"
+              title="Failed to generate response"
+              icon={<IconInfoCircle />}
+            >
+              Could not generate response. It's possible that your browser or
+              your system is out of memory.
+            </Alert>
+          ))
+          .otherwise(() => null)}
+      </Card.Section>
+    </Card>
+  );
+}

client/components/AiResponse/AiResponseSection.tsx

@@ -0,0 +1,88 @@
+import { usePubSub } from "create-pubsub/react";
+import { lazy, Suspense, useMemo } from "react";
+import { match, Pattern } from "ts-pattern";
+import {
+  modelLoadingProgressPubSub,
+  responsePubSub,
+  settingsPubSub,
+  queryPubSub,
+  textGenerationStatePubSub,
+} from "../../modules/pubSub";
+
+const AiResponseContent = lazy(() => import("./AiResponseContent"));
+const PreparingContent = lazy(() => import("./PreparingContent"));
+const LoadingModelContent = lazy(() => import("./LoadingModelContent"));
+const ChatInterface = lazy(() => import("./ChatInterface"));
+const AiModelDownloadAllowanceContent = lazy(
+  () => import("./AiModelDownloadAllowanceContent"),
+);
+
+export default function AiResponseSection() {
+  const [query] = usePubSub(queryPubSub);
+  const [response] = usePubSub(responsePubSub);
+  const [textGenerationState, setTextGenerationState] = usePubSub(
+    textGenerationStatePubSub,
+  );
+  const [modelLoadingProgress] = usePubSub(modelLoadingProgressPubSub);
+  const [settings] = usePubSub(settingsPubSub);
+
+  return useMemo(
+    () =>
+      match([settings.enableAiResponse, textGenerationState])
+        .with([true, Pattern.not("idle").select()], (textGenerationState) =>
+          match(textGenerationState)
+            .with(
+              Pattern.union("generating", "interrupted", "completed", "failed"),
+              (textGenerationState) => (
+                <>
+                  <Suspense>
+                    <AiResponseContent
+                      textGenerationState={textGenerationState}
+                      response={response}
+                      setTextGenerationState={setTextGenerationState}
+                    />
+                  </Suspense>
+                  {textGenerationState === "completed" && (
+                    <Suspense>
+                      <ChatInterface
+                        initialQuery={query}
+                        initialResponse={response}
+                      />
+                    </Suspense>
+                  )}
+                </>
+              ),
+            )
+            .with("awaitingModelDownloadAllowance", () => (
+              <Suspense>
+                <AiModelDownloadAllowanceContent />
+              </Suspense>
+            ))
+            .with("loadingModel", () => (
+              <Suspense>
+                <LoadingModelContent
+                  modelLoadingProgress={modelLoadingProgress}
+                />
+              </Suspense>
+            ))
+            .with(
+              Pattern.union("awaitingSearchResults", "preparingToGenerate"),
+              (textGenerationState) => (
+                <Suspense>
+                  <PreparingContent textGenerationState={textGenerationState} />
+                </Suspense>
+              ),
+            )
+            .exhaustive(),
+        )
+        .otherwise(() => null),
+    [
+      settings,
+      textGenerationState,
+      setTextGenerationState,
+      modelLoadingProgress,
+      response,
+      query,
+    ],
+  );
+}

client/components/AiResponse/ChatInterface.tsx

@@ -0,0 +1,173 @@
+import {
+  useState,
+  useEffect,
+  lazy,
+  Suspense,
+  useRef,
+  KeyboardEvent,
+} from "react";
+import {
+  Card,
+  Text,
+  Textarea,
+  Button,
+  Stack,
+  Group,
+  Paper,
+} from "@mantine/core";
+import { IconSend } from "@tabler/icons-react";
+import {
+  ChatMessage,
+  generateChatResponse,
+} from "../../modules/textGeneration";
+import { addLogEntry } from "../../modules/logEntries";
+import { usePubSub } from "create-pubsub/react";
+import { settingsPubSub } from "../../modules/pubSub";
+import { match } from "ts-pattern";
+
+const FormattedMarkdown = lazy(() => import("./FormattedMarkdown"));
+
+export default function ChatInterface({
+  initialQuery,
+  initialResponse,
+}: {
+  initialQuery: string;
+  initialResponse: string;
+}) {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [input, setInput] = useState("");
+  const [isGenerating, setIsGenerating] = useState(false);
+  const [streamedResponse, setStreamedResponse] = useState("");
+  const latestResponseRef = useRef("");
+  const [settings] = usePubSub(settingsPubSub);
+
+  useEffect(() => {
+    setMessages([
+      { role: "user", content: initialQuery },
+      { role: "assistant", content: initialResponse },
+    ]);
+  }, [initialQuery, initialResponse]);
+
+  const handleSend = async () => {
+    if (input.trim() === "" || isGenerating) return;
+
+    const newMessages = [...messages, { role: "user", content: input }];
+    setMessages(newMessages);
+    setInput("");
+    setIsGenerating(true);
+    setStreamedResponse("");
+    latestResponseRef.current = "";
+
+    try {
+      addLogEntry("User sent a follow-up question");
+      await generateChatResponse(newMessages, (partialResponse) => {
+        setStreamedResponse(partialResponse);
+        latestResponseRef.current = partialResponse;
+      });
+      setMessages((prevMessages) => [
+        ...prevMessages,
+        { role: "assistant", content: latestResponseRef.current },
+      ]);
+      addLogEntry("AI responded to follow-up question");
+    } catch (error) {
+      addLogEntry(`Error generating chat response: ${error}`);
+      setMessages((prevMessages) => [
+        ...prevMessages,
+        {
+          role: "assistant",
+          content: "Sorry, I encountered an error while generating a response.",
+        },
+      ]);
+    } finally {
+      setIsGenerating(false);
+      setStreamedResponse("");
+    }
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    match([event, settings.enterToSubmit])
+      .with([{ code: "Enter", shiftKey: false }, true], () => {
+        event.preventDefault();
+        handleSend();
+      })
+      .with([{ code: "Enter", shiftKey: true }, false], () => {
+        event.preventDefault();
+        handleSend();
+      })
+      .otherwise(() => undefined);
+  };
+
+  return (
+    <Card withBorder shadow="sm" radius="md">
+      <Card.Section withBorder inheritPadding py="xs">
+        <Text fw={500}>Follow-up questions</Text>
+      </Card.Section>
+      <Stack gap="md" pt="md">
+        {messages.slice(2).length > 0 && (
+          <Stack gap="md">
+            {messages.slice(2).map((message, index) => (
+              <Paper
+                key={index}
+                shadow="xs"
+                radius="xl"
+                p="sm"
+                maw="90%"
+                style={{
+                  alignSelf:
+                    message.role === "user" ? "flex-end" : "flex-start",
+                }}
+              >
+                <Suspense>
+                  <FormattedMarkdown>{message.content}</FormattedMarkdown>
+                </Suspense>
+              </Paper>
+            ))}
+            {isGenerating && streamedResponse.length > 0 && (
+              <Paper
+                shadow="xs"
+                radius="xl"
+                p="sm"
+                maw="90%"
+                style={{ alignSelf: "flex-start" }}
+              >
+                <Suspense>
+                  <FormattedMarkdown>{streamedResponse}</FormattedMarkdown>
+                </Suspense>
+              </Paper>
+            )}
+          </Stack>
+        )}
+        <Group align="flex-end" style={{ position: "relative" }}>
+          <Textarea
+            placeholder="Anything else you would like to know?"
+            value={input}
+            onChange={(event) => setInput(event.currentTarget.value)}
+            onKeyDown={handleKeyDown}
+            autosize
+            minRows={1}
+            maxRows={4}
+            style={{ flexGrow: 1, paddingRight: "50px" }}
+            disabled={isGenerating}
+          />
+          <Button
+            size="sm"
+            variant="default"
+            onClick={handleSend}
+            loading={isGenerating}
+            style={{
+              height: "100%",
+              position: "absolute",
+              right: 0,
+              top: 0,
+              bottom: 0,
+              borderTopLeftRadius: 0,
+              borderBottomLeftRadius: 0,
+            }}
+          >
+            <IconSend size={16} />
+          </Button>
+        </Group>
+      </Stack>
+    </Card>
+  );
+}

client/components/AiResponse/FormattedMarkdown.tsx

@@ -0,0 +1,37 @@
+import { TypographyStylesProvider } from "@mantine/core";
+import Markdown from "react-markdown";
+import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
+import syntaxHighlighterStyle from "react-syntax-highlighter/dist/esm/styles/prism/one-dark";
+
+const FormattedMarkdown = ({ children }: { children: string }) => {
+  return (
+    <TypographyStylesProvider p="md">
+      <Markdown
+        components={{
+          code(props) {
+            const { children, className, node, ref, ...rest } = props;
+            void node;
+            const languageMatch = /language-(\w+)/.exec(className || "");
+            return languageMatch ? (
+              <SyntaxHighlighter
+                {...rest}
+                ref={ref as never}
+                children={children?.toString().replace(/\n$/, "") ?? ""}
+                language={languageMatch[1]}
+                style={syntaxHighlighterStyle}
+              />
+            ) : (
+              <code {...rest} className={className}>
+                {children}
+              </code>
+            );
+          },
+        }}
+      >
+        {children}
+      </Markdown>
+    </TypographyStylesProvider>
+  );
+};
+
+export default FormattedMarkdown;

client/components/AiResponse/LoadingModelContent.tsx

@@ -0,0 +1,23 @@
+import { Card, Progress, Text } from "@mantine/core";
+
+export default function LoadingModelContent({
+  modelLoadingProgress,
+}: {
+  modelLoadingProgress: number;
+}) {
+  const isLoadingComplete =
+    modelLoadingProgress === 100 || modelLoadingProgress === 0;
+  const percent = isLoadingComplete ? 100 : modelLoadingProgress;
+  const strokeColor = isLoadingComplete ? "#52c41a" : "#3385ff";
+
+  return (
+    <Card withBorder shadow="sm" radius="md">
+      <Card.Section withBorder inheritPadding py="xs">
+        <Text fw={500}>Loading AI...</Text>
+      </Card.Section>
+      <Card.Section withBorder inheritPadding py="md">
+        <Progress color={strokeColor} value={percent} animated />
+      </Card.Section>
+    </Card>
+  );
+}

client/components/AiResponse/PreparingContent.tsx

@@ -0,0 +1,29 @@
+import { Card, Stack, Skeleton, Text } from "@mantine/core";
+import { match } from "ts-pattern";
+
+export default function PreparingContent({
+  textGenerationState,
+}: {
+  textGenerationState: string;
+}) {
+  return (
+    <Card withBorder shadow="sm" radius="md">
+      <Card.Section withBorder inheritPadding py="xs">
+        <Text fw={500}>
+          {match(textGenerationState)
+            .with("awaitingSearchResults", () => "Awaiting search results...")
+            .with("preparingToGenerate", () => "Preparing AI response...")
+            .otherwise(() => null)}
+        </Text>
+      </Card.Section>
+      <Card.Section withBorder inheritPadding py="md">
+        <Stack>
+          <Skeleton height={8} radius="xl" />
+          <Skeleton height={8} width="70%" radius="xl" />
+          <Skeleton height={8} radius="xl" />
+          <Skeleton height={8} width="43%" radius="xl" />
+        </Stack>
+      </Card.Section>
+    </Card>
+  );
+}

client/components/AiResponse/WebLlmModelSelect.tsx

@@ -0,0 +1,52 @@
+import { ComboboxItem, Select } from "@mantine/core";
+import { useState, useEffect } from "react";
+import { isF16Supported } from "../../modules/webGpu";
+import { prebuiltAppConfig } from "@mlc-ai/web-llm";
+
+export default function WebLlmModelSelect({
+  value,
+  onChange,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const [webGpuModels] = useState<ComboboxItem[]>(() => {
+    const suffix = isF16Supported ? "-q4f16_1-MLC" : "-q4f32_1-MLC";
+
+    const models = prebuiltAppConfig.model_list
+      .filter((model) => model.model_id.endsWith(suffix))
+      .sort((a, b) => (a.vram_required_MB ?? 0) - (b.vram_required_MB ?? 0))
+      .map((model) => ({
+        label: `${Math.round(model.vram_required_MB ?? 0) || "N/A"} MB • ${model.model_id.replace(suffix, "")}`,
+        value: model.model_id,
+      }));
+
+    return models;
+  });
+
+  useEffect(() => {
+    const isCurrentModelValid = webGpuModels.some(
+      (model) => model.value === value,
+    );
+
+    if (!isCurrentModelValid && webGpuModels.length > 0) {
+      onChange(webGpuModels[0].value);
+    }
+  }, []);
+
+  const handleChange = (value: string | null) => {
+    if (value) onChange(value);
+  };
+
+  return (
+    <Select
+      value={value}
+      onChange={handleChange}
+      label="AI Model"
+      description="Select the model to use for AI responses."
+      data={webGpuModels}
+      allowDeselect={false}
+      searchable
+    />
+  );
+}

client/components/AiResponse/WllamaModelSelect.tsx

@@ -0,0 +1,42 @@
+import { ComboboxItem, Select } from "@mantine/core";
+import { useState, useEffect } from "react";
+import { wllamaModels } from "../../modules/wllama";
+
+export default function WllamaModelSelect({
+  value,
+  onChange,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const [wllamaModelOptions] = useState<ComboboxItem[]>(
+    Object.entries(wllamaModels)
+      .sort(([, a], [, b]) => a.fileSizeInMegabytes - b.fileSizeInMegabytes)
+      .map(([value, { label, fileSizeInMegabytes }]) => ({
+        label: `${fileSizeInMegabytes} MB • ${label}`,
+        value,
+      })),
+  );
+
+  useEffect(() => {
+    const isCurrentModelValid = wllamaModelOptions.some(
+      (model) => model.value === value,
+    );
+
+    if (!isCurrentModelValid && wllamaModelOptions.length > 0) {
+      onChange(wllamaModelOptions[0].value);
+    }
+  }, []);
+
+  return (
+    <Select
+      value={value}
+      onChange={(value) => value && onChange(value)}
+      label="AI Model"
+      description="Select the model to use for AI responses."
+      data={wllamaModelOptions}
+      allowDeselect={false}
+      searchable
+    />
+  );
+}

client/components/App/App.tsx

@@ -0,0 +1,76 @@
+import { Route, Switch } from "wouter";
+import { MantineProvider } from "@mantine/core";
+import "@mantine/core/styles.css";
+import { lazy, useEffect, useState } from "react";
+import { usePubSub } from "create-pubsub/react";
+import { settingsPubSub } from "../../modules/pubSub";
+import { defaultSettings } from "../../modules/settings";
+import { addLogEntry } from "../../modules/logEntries";
+import { Notifications } from "@mantine/notifications";
+import "@mantine/notifications/styles.css";
+import { match } from "ts-pattern";
+import { verifyStoredAccessKey } from "../../modules/accessKey";
+
+const MainPage = lazy(() => import("../Pages/Main/MainPage"));
+const AccessPage = lazy(() => import("../Pages/AccessPage"));
+
+export function App() {
+  useInitializeSettings();
+
+  const [hasValidatedAccessKey, setValidatedAccessKey] = useState(false);
+  const [isCheckingStoredKey, setCheckingStoredKey] = useState(true);
+
+  useEffect(() => {
+    async function checkStoredAccessKey() {
+      if (VITE_ACCESS_KEYS_ENABLED) {
+        const isValid = await verifyStoredAccessKey();
+        if (isValid) setValidatedAccessKey(true);
+      }
+      setCheckingStoredKey(false);
+    }
+
+    checkStoredAccessKey();
+  }, []);
+
+  if (isCheckingStoredKey) return null;
+
+  return (
+    <MantineProvider defaultColorScheme="dark">
+      <Notifications />
+      <Switch>
+        <Route path="/">
+          {match([VITE_ACCESS_KEYS_ENABLED, hasValidatedAccessKey])
+            .with([true, false], () => (
+              <AccessPage
+                onAccessKeyValid={() => setValidatedAccessKey(true)}
+              />
+            ))
+            .otherwise(() => (
+              <MainPage />
+            ))}
+        </Route>
+      </Switch>
+    </MantineProvider>
+  );
+}
+
+/**
+ * A custom React hook that initializes the application settings.
+ *
+ * @returns The initialized settings object.
+ *
+ * @remarks
+ * This hook uses the `usePubSub` hook to access and update the settings state.
+ * It initializes the settings by merging the default settings with any existing settings.
+ * The initialization is performed once when the component mounts.
+ */
+function useInitializeSettings() {
+  const [settings, setSettings] = usePubSub(settingsPubSub);
+
+  useEffect(() => {
+    setSettings({ ...defaultSettings, ...settings });
+    addLogEntry("Settings initialized");
+  }, []);
+
+  return settings;
+}

client/components/Logs/LogsModal.tsx

@@ -0,0 +1,107 @@
+import {
+  Modal,
+  Table,
+  Pagination,
+  Button,
+  Alert,
+  Group,
+  Center,
+} from "@mantine/core";
+import { usePubSub } from "create-pubsub/react";
+import { logEntriesPubSub } from "../../modules/logEntries";
+import { useCallback, useMemo, useState } from "react";
+import { IconInfoCircle } from "@tabler/icons-react";
+
+export default function LogsModal({
+  opened,
+  onClose,
+}: {
+  opened: boolean;
+  onClose: () => void;
+}) {
+  const [logEntries] = usePubSub(logEntriesPubSub);
+
+  const [page, setPage] = useState(1);
+
+  const logEntriesPerPage = 5;
+
+  const logEntriesFromCurrentPage = useMemo(
+    () =>
+      logEntries.slice(
+        (page - 1) * logEntriesPerPage,
+        page * logEntriesPerPage,
+      ),
+    [logEntries, page, logEntriesPerPage],
+  );
+
+  const downloadLogsAsJson = useCallback(() => {
+    const jsonString = JSON.stringify(logEntries, null, 2);
+    const blob = new Blob([jsonString], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = "logs.json";
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+  }, [logEntries]);
+
+  return (
+    <Modal opened={opened} onClose={onClose} size="xl" title="Logs">
+      <Alert
+        variant="light"
+        color="blue"
+        title="Privacy Notice"
+        icon={<IconInfoCircle />}
+        mb="md"
+      >
+        <Group justify="space-between" align="center">
+          <span>
+            These logs are stored only in your browser for private use. They are
+            not sent automatically and exist for debugging purposes in case you
+            need to{" "}
+            <a
+              href="https://github.com/felladrin/MiniSearch/issues/new?labels=bug&template=bug_report.yml"
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              report a bug
+            </a>
+            .
+          </span>
+          <Button onClick={downloadLogsAsJson} size="xs" data-autofocus>
+            Download Logs
+          </Button>
+        </Group>
+      </Alert>
+      <Table striped highlightOnHover withTableBorder>
+        <Table.Thead>
+          <Table.Tr>
+            <Table.Th>Time</Table.Th>
+            <Table.Th>Message</Table.Th>
+          </Table.Tr>
+        </Table.Thead>
+        <Table.Tbody>
+          {logEntriesFromCurrentPage.map((entry, index) => (
+            <Table.Tr key={index}>
+              <Table.Td>
+                {new Date(entry.timestamp).toLocaleTimeString()}
+              </Table.Td>
+              <Table.Td>{entry.message}</Table.Td>
+            </Table.Tr>
+          ))}
+        </Table.Tbody>
+      </Table>
+      <Center>
+        <Pagination
+          total={Math.ceil(logEntries.length / logEntriesPerPage)}
+          value={page}
+          onChange={setPage}
+          size="sm"
+          mt="md"
+        />
+      </Center>
+    </Modal>
+  );
+}

client/components/Logs/ShowLogsButton.tsx

@@ -0,0 +1,42 @@
+import { Stack, Center, Loader, Button, Text } from "@mantine/core";
+import { useState, Suspense, lazy } from "react";
+import { addLogEntry } from "../../modules/logEntries";
+
+const LogsModal = lazy(() => import("./LogsModal"));
+
+export default function ShowLogsButton() {
+  const [isLogsModalOpen, setLogsModalOpen] = useState(false);
+
+  const handleShowLogsButtonClick = () => {
+    addLogEntry("User opened the logs modal");
+    setLogsModalOpen(true);
+  };
+
+  const handleCloseLogsButtonClick = () => {
+    addLogEntry("User closed the logs modal");
+    setLogsModalOpen(false);
+  };
+
+  return (
+    <Stack gap="xs">
+      <Suspense
+        fallback={
+          <Center>
+            <Loader color="gray" type="bars" />
+          </Center>
+        }
+      >
+        <Button size="sm" onClick={handleShowLogsButtonClick} variant="default">
+          Show logs
+        </Button>
+        <Text size="xs" c="dimmed">
+          View session logs for debugging.
+        </Text>
+        <LogsModal
+          opened={isLogsModalOpen}
+          onClose={handleCloseLogsButtonClick}
+        />
+      </Suspense>
+    </Stack>
+  );
+}

client/components/Pages/AccessPage.tsx

@@ -0,0 +1,61 @@
+import { FormEvent, useState } from "react";
+import { TextInput, Button, Stack, Container, Title } from "@mantine/core";
+import { addLogEntry } from "../../modules/logEntries";
+import { validateAccessKey } from "../../modules/accessKey";
+
+export default function AccessPage({
+  onAccessKeyValid,
+}: {
+  onAccessKeyValid: () => void;
+}) {
+  const [accessKey, setAccessKey] = useState("");
+  const [error, setError] = useState("");
+
+  const handleSubmit = async (formEvent: FormEvent<HTMLFormElement>) => {
+    formEvent.preventDefault();
+    setError("");
+    try {
+      const isValid = await validateAccessKey(accessKey);
+      if (isValid) {
+        addLogEntry("Valid access key entered");
+        onAccessKeyValid();
+      } else {
+        setError("Invalid access key");
+        addLogEntry("Invalid access key attempt");
+      }
+    } catch (error) {
+      setError("Error validating access key");
+      addLogEntry(`Error validating access key: ${error}`);
+    }
+  };
+
+  return (
+    <Container size="xs">
+      <Stack p="lg" mih="100vh" justify="center">
+        <Title order={2} ta="center">
+          Access Restricted
+        </Title>
+        <form onSubmit={handleSubmit}>
+          <Stack gap="xs">
+            <TextInput
+              value={accessKey}
+              onChange={({ target }) => setAccessKey(target.value)}
+              placeholder="Enter your access key to continue"
+              required
+              autoFocus
+              error={error}
+              styles={{
+                input: {
+                  textAlign: "center",
+                },
+              }}
+            />
+            <Button size="xs" type="submit">
+              Submit
+            </Button>
+          </Stack>
+        </form>
+      </Stack>
+    </Container>
+  );
+}

client/components/Pages/Main/MainPage.tsx

@@ -0,0 +1,74 @@
+import { usePubSub } from "create-pubsub/react";
+import {
+  queryPubSub,
+  searchStatePubSub,
+  textGenerationStatePubSub,
+} from "../../../modules/pubSub";
+import { Center, Container, Loader, Stack } from "@mantine/core";
+import { Suspense, useEffect } from "react";
+import { addLogEntry } from "../../../modules/logEntries";
+import { lazy } from "react";
+import { match, Pattern } from "ts-pattern";
+
+const AiResponseSection = lazy(
+  () => import("../../AiResponse/AiResponseSection"),
+);
+const SearchResultsSection = lazy(
+  () => import("../../Search/Results/SearchResultsSection"),
+);
+const MenuButton = lazy(() => import("./Menu/MenuButton"));
+const SearchForm = lazy(() => import("../../Search/Form/SearchForm"));
+
+export default function MainPage() {
+  const [query, updateQuery] = usePubSub(queryPubSub);
+  const [searchState] = usePubSub(searchStatePubSub);
+  const [textGenerationState] = usePubSub(textGenerationStatePubSub);
+
+  useEffect(() => {
+    addLogEntry(`Search state changed to '${searchState}'`);
+  }, [searchState]);
+
+  useEffect(() => {
+    addLogEntry(`Text generation state changed to '${textGenerationState}'`);
+  }, [textGenerationState]);
+
+  return (
+    <Container>
+      <Stack
+        py="md"
+        mih="100vh"
+        justify={match(query)
+          .with(Pattern.string.length(0), () => "center")
+          .otherwise(() => undefined)}
+      >
+        <Suspense
+          fallback={
+            <Center>
+              <Loader type="bars" />
+            </Center>
+          }
+        >
+          <SearchForm
+            query={query}
+            updateQuery={updateQuery}
+            additionalButtons={<MenuButton />}
+          />
+        </Suspense>
+        {match(textGenerationState)
+          .with(Pattern.not("idle"), () => (
+            <Suspense>
+              <AiResponseSection />
+            </Suspense>
+          ))
+          .otherwise(() => null)}
+        {match(searchState)
+          .with(Pattern.not("idle"), () => (
+            <Suspense>
+              <SearchResultsSection />
+            </Suspense>
+          ))
+          .otherwise(() => null)}
+      </Stack>
+    </Container>
+  );
+}

client/components/Pages/Main/Menu/AISettingsForm.tsx

@@ -0,0 +1,288 @@
+import { usePubSub } from "create-pubsub/react";
+import { settingsPubSub } from "../../../../modules/pubSub";
+import { isWebGPUAvailable } from "../../../../modules/webGpu";
+import { match, Pattern } from "ts-pattern";
+import {
+  NumberInput,
+  Select,
+  Slider,
+  Stack,
+  Switch,
+  Textarea,
+  Text,
+  TextInput,
+  Group,
+  ComboboxData,
+  Skeleton,
+} from "@mantine/core";
+import { useForm } from "@mantine/form";
+import { lazy, Suspense, useEffect, useState } from "react";
+import { defaultSettings, inferenceTypes } from "../../../../modules/settings";
+import { getOpenAiClient } from "../../../../modules/openai";
+import { IconInfoCircle } from "@tabler/icons-react";
+import { addLogEntry } from "../../../../modules/logEntries";
+
+const WebLlmModelSelect = lazy(
+  () => import("../../../AiResponse/WebLlmModelSelect"),
+);
+const WllamaModelSelect = lazy(
+  () => import("../../../AiResponse/WllamaModelSelect"),
+);
+
+export default function AISettingsForm() {
+  const [settings, setSettings] = usePubSub(settingsPubSub);
+  const [openAiModels, setOpenAiModels] = useState<ComboboxData>([]);
+
+  const form = useForm({
+    initialValues: settings,
+    onValuesChange: setSettings,
+  });
+
+  useEffect(() => {
+    async function fetchOpenAiModels() {
+      try {
+        const openai = getOpenAiClient({
+          baseURL: settings.openAiApiBaseUrl,
+          apiKey: settings.openAiApiKey,
+        });
+        const response = await openai.models.list();
+        const models = response.data.map((model) => ({
+          label: model.id,
+          value: model.id,
+        }));
+        setOpenAiModels(models);
+        form.setFieldError("openAiApiModel", null);
+        if (!form.values.openAiApiModel) {
+          form.setFieldValue("openAiApiModel", models[0].value);
+        }
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        addLogEntry(`Error fetching OpenAI models: ${errorMessage}`);
+        setOpenAiModels([]);
+        form.setFieldError("openAiApiModel", errorMessage);
+      }
+    }
+
+    if (form.values.inferenceType === "openai") {
+      fetchOpenAiModels();
+    }
+  }, [
+    form.values.inferenceType,
+    settings.openAiApiBaseUrl,
+    settings.openAiApiKey,
+  ]);
+
+  const isUsingCustomInstructions =
+    form.values.systemPrompt !== defaultSettings.systemPrompt;
+
+  const handleRestoreDefaultInstructions = () => {
+    form.setFieldValue("systemPrompt", defaultSettings.systemPrompt);
+  };
+
+  return (
+    <Stack gap="md">
+      <Switch
+        label="AI Response"
+        {...form.getInputProps("enableAiResponse", {
+          type: "checkbox",
+        })}
+        labelPosition="left"
+        description="Enable or disable AI-generated responses to your queries. When disabled, you'll only see web search results."
+      />
+
+      {form.values.enableAiResponse && (
+        <>
+          <Stack gap="xs" mb="md">
+            <Text size="sm">Search results to consider</Text>
+            <Text size="xs" c="dimmed">
+              Determines the number of search results to consider when
+              generating AI responses. A higher value may enhance accuracy, but
+              it will also increase response time.
+            </Text>
+            <Slider
+              {...form.getInputProps("searchResultsToConsider")}
+              min={0}
+              max={6}
+              marks={Array.from({ length: 7 }, (_, index) => ({
+                value: index,
+                label: index.toString(),
+              }))}
+            />
+          </Stack>
+
+          <Select
+            {...form.getInputProps("inferenceType")}
+            label="AI Processing Location"
+            data={inferenceTypes}
+            allowDeselect={false}
+          />
+
+          {form.values.inferenceType === "openai" && (
+            <>
+              <TextInput
+                {...form.getInputProps("openAiApiBaseUrl")}
+                label="API Base URL"
+                placeholder="http://localhost:11434/v1"
+                required
+              />
+              <Group gap="xs">
+                <IconInfoCircle size={16} />
+                <Text size="xs" c="dimmed" flex={1}>
+                  You may need to add{" "}
+                  <em>
+                    {`${self.location.protocol}//${self.location.hostname}`}
+                  </em>{" "}
+                  to the list of allowed network origins in your API server
+                  settings.
+                </Text>
+              </Group>
+              <TextInput
+                {...form.getInputProps("openAiApiKey")}
+                label="API Key"
+                type="password"
+                description="Optional, as local API servers usually do not require it."
+              />
+              <Select
+                {...form.getInputProps("openAiApiModel")}
+                label="API Model"
+                data={openAiModels}
+                description="Optional, as some API servers don't provide a model list."
+                allowDeselect={false}
+                searchable
+              />
+            </>
+          )}
+
+          {form.values.inferenceType === "browser" && (
+            <>
+              {isWebGPUAvailable && (
+                <Switch
+                  label="WebGPU"
+                  {...form.getInputProps("enableWebGpu", {
+                    type: "checkbox",
+                  })}
+                  labelPosition="left"
+                  description="Enable or disable WebGPU usage. When disabled, the app will use the CPU instead."
+                />
+              )}
+
+              {match([isWebGPUAvailable, form.values.enableWebGpu])
+                .with([true, true], () => (
+                  <Suspense fallback={<Skeleton height={50} />}>
+                    <WebLlmModelSelect
+                      value={form.values.webLlmModelId}
+                      onChange={(value) =>
+                        form.setFieldValue("webLlmModelId", value)
+                      }
+                    />
+                  </Suspense>
+                ))
+                .with([false, Pattern.any], [Pattern.any, false], () => (
+                  <>
+                    <Suspense fallback={<Skeleton height={50} />}>
+                      <WllamaModelSelect
+                        value={form.values.wllamaModelId}
+                        onChange={(value) =>
+                          form.setFieldValue("wllamaModelId", value)
+                        }
+                      />
+                    </Suspense>
+                    <NumberInput
+                      label="CPU threads to use"
+                      description="Number of threads to use for the AI model. Lower values will use less CPU, but may take longer to respond. A too-high value may cause the app to hang."
+                      min={1}
+                      {...form.getInputProps("cpuThreads")}
+                    />
+                  </>
+                ))
+                .otherwise(() => null)}
+            </>
+          )}
+
+          <Textarea
+            label="Instructions for AI"
+            descriptionProps={{ component: "div" }}
+            description={
+              <>
+                <span>
+                  Customize instructions for the AI to tailor its responses.
+                </span>
+                <br />
+                <span>For example:</span>
+                <ul>
+                  <li>
+                    Specify preferences
+                    <ul>
+                      <li>
+                        <em>"use simple language"</em>
+                      </li>
+                      <li>
+                        <em>"provide step-by-step explanations"</em>
+                      </li>
+                    </ul>
+                  </li>
+                  <li>
+                    Set a response style
+                    <ul>
+                      <li>
+                        <em>"answer in a friendly tone"</em>
+                      </li>
+                      <li>
+                        <em>"write your response in Spanish"</em>
+                      </li>
+                    </ul>
+                  </li>
+                  <li>
+                    Provide context about the audience
+                    <ul>
+                      <li>
+                        <em>"you're talking to a high school student"</em>
+                      </li>
+                      <li>
+                        <em>
+                          "consider that your audience is composed of
+                          professionals in the field of graphic design"
+                        </em>
+                      </li>
+                    </ul>
+                  </li>
+                </ul>
+                <span>
+                  The special tag <em>{`{{searchResults}}`}</em> will be
+                  replaced with the search results, while{" "}
+                  <em>{`{{dateTime}}`}</em> will be replaced with the current
+                  date and time.
+                </span>
+                {isUsingCustomInstructions && (
+                  <>
+                    <br />
+                    <br />
+                    <span>
+                      Currently, you're using custom instructions. If you ever
+                      need to restore the default instructions, you can do so by
+                      clicking
+                    </span>{" "}
+                    <Text
+                      component="span"
+                      size="xs"
+                      c="blue"
+                      style={{ cursor: "pointer" }}
+                      onClick={handleRestoreDefaultInstructions}
+                    >
+                      here
+                    </Text>
+                    <span>.</span>
+                  </>
+                )}
+              </>
+            }
+            autosize
+            maxRows={10}
+            {...form.getInputProps("systemPrompt")}
+          />
+        </>
+      )}
+    </Stack>
+  );
+}

client/components/Pages/Main/Menu/ActionsForm.tsx

@@ -0,0 +1,18 @@
+import { Stack } from "@mantine/core";
+import { Suspense, lazy } from "react";
+
+const ClearDataButton = lazy(() => import("./ClearDataButton"));
+const ShowLogsButton = lazy(() => import("../../../Logs/ShowLogsButton"));
+
+export default function ActionsForm() {
+  return (
+    <Stack gap="lg">
+      <Suspense>
+        <ClearDataButton />
+      </Suspense>
+      <Suspense>
+        <ShowLogsButton />
+      </Suspense>
+    </Stack>
+  );
+}

client/components/Pages/Main/Menu/ClearDataButton.tsx

@@ -0,0 +1,58 @@
+import { Stack, Button, Text } from "@mantine/core";
+import { useState } from "react";
+import { addLogEntry } from "../../../../modules/logEntries";
+import { sleep } from "../../../../modules/sleep";
+
+export default function ClearDataButton() {
+  const [isClearingData, setIsClearingData] = useState(false);
+  const [hasClearedData, setHasClearedData] = useState(false);
+
+  const handleClearDataButtonClick = async () => {
+    const sureToDelete = self.confirm(
+      "Are you sure you want to reset the settings and delete all files in cache?",
+    );
+
+    if (!sureToDelete) return;
+
+    addLogEntry("User initiated data clearing");
+
+    setIsClearingData(true);
+
+    self.localStorage.clear();
+
+    for (const cacheName of await self.caches.keys()) {
+      await self.caches.delete(cacheName);
+    }
+
+    for (const databaseInfo of await self.indexedDB.databases()) {
+      if (databaseInfo.name) self.indexedDB.deleteDatabase(databaseInfo.name);
+    }
+
+    setIsClearingData(false);
+
+    setHasClearedData(true);
+
+    addLogEntry("All data cleared successfully");
+
+    await sleep(1000);
+
+    self.location.reload();
+  };
+
+  return (
+    <Stack gap="xs">
+      <Button
+        onClick={handleClearDataButtonClick}
+        variant="default"
+        loading={isClearingData}
+        loaderProps={{ type: "bars" }}
+        disabled={hasClearedData}
+      >
+        {hasClearedData ? "Data cleared" : "Clear all data"}
+      </Button>
+      <Text size="xs" c="dimmed">
+        Reset settings and delete all files in cache to free up space.
+      </Text>
+    </Stack>
+  );
+}

client/components/Pages/Main/Menu/InterfaceSettingsForm.tsx

@@ -0,0 +1,54 @@
+import { usePubSub } from "create-pubsub/react";
+import { settingsPubSub } from "../../../../modules/pubSub";
+import {
+  Stack,
+  Switch,
+  useComputedColorScheme,
+  useMantineColorScheme,
+} from "@mantine/core";
+import { useForm } from "@mantine/form";
+
+export default function InterfaceSettingsForm() {
+  const [settings, setSettings] = usePubSub(settingsPubSub);
+  const form = useForm({
+    initialValues: settings,
+    onValuesChange: setSettings,
+  });
+  const { setColorScheme } = useMantineColorScheme();
+  const computedColorScheme = useComputedColorScheme("light");
+
+  const toggleColorScheme = () => {
+    setColorScheme(computedColorScheme === "dark" ? "light" : "dark");
+  };
+
+  return (
+    <Stack gap="md">
+      <Switch
+        label="Dark Mode"
+        checked={computedColorScheme === "dark"}
+        onChange={toggleColorScheme}
+        labelPosition="left"
+        description="Enable or disable the dark color scheme."
+        styles={{ labelWrapper: { width: "100%" } }}
+      />
+
+      <Switch
+        {...form.getInputProps("enableImageSearch", {
+          type: "checkbox",
+        })}
+        label="Image Search"
+        labelPosition="left"
+        description="Enable or disable image search results. When enabled, relevant images will be displayed alongside web search results."
+      />
+
+      <Switch
+        {...form.getInputProps("enterToSubmit", {
+          type: "checkbox",
+        })}
+        label="Enter to Submit"
+        labelPosition="left"
+        description="Enable or disable using Enter key to submit the search query. When disabled, you'll need to click the Search button or use Shift+Enter to submit."
+      />
+    </Stack>
+  );
+}

client/components/Pages/Main/Menu/MenuButton.tsx

@@ -0,0 +1,53 @@
+import { lazy, Suspense, useCallback, useEffect, useState } from "react";
+import { Button } from "@mantine/core";
+import { addLogEntry } from "../../../../modules/logEntries";
+
+const MenuDrawer = lazy(() => import("./MenuDrawer"));
+
+export default function MenuButton() {
+  const [isDrawerOpen, setDrawerOpen] = useState(false);
+  const [isDrawerLoaded, setDrawerLoaded] = useState(false);
+
+  const openDrawer = useCallback(() => {
+    setDrawerOpen(true);
+    addLogEntry("User opened the menu");
+  }, []);
+
+  const closeDrawer = useCallback(() => {
+    setDrawerOpen(false);
+    addLogEntry("User closed the menu");
+  }, []);
+
+  const handleDrawerLoad = useCallback(() => {
+    if (!isDrawerLoaded) {
+      addLogEntry("Menu drawer loaded");
+      setDrawerLoaded(true);
+    }
+  }, [isDrawerLoaded]);
+
+  return (
+    <>
+      <Button
+        size="xs"
+        onClick={openDrawer}
+        variant="default"
+        loading={isDrawerOpen && !isDrawerLoaded}
+      >
+        Menu
+      </Button>
+      {(isDrawerOpen || isDrawerLoaded) && (
+        <Suspense fallback={<SuspenseListener onUnload={handleDrawerLoad} />}>
+          <MenuDrawer onClose={closeDrawer} opened={isDrawerOpen} />
+        </Suspense>
+      )}
+    </>
+  );
+}
+
+function SuspenseListener({ onUnload }: { onUnload: () => void }) {
+  useEffect(() => {
+    return () => onUnload();
+  }, [onUnload]);
+
+  return null;
+}

client/components/Pages/Main/Menu/MenuDrawer.tsx

@@ -0,0 +1,102 @@
+import { lazy, Suspense } from "react";
+import {
+  Drawer,
+  Accordion,
+  ActionIcon,
+  HoverCard,
+  Stack,
+  Group,
+  Center,
+  FocusTrap,
+  DrawerProps,
+} from "@mantine/core";
+import { IconBrandGithub } from "@tabler/icons-react";
+import { repository } from "../../../../../package.json";
+import prettyMilliseconds from "pretty-ms";
+import { getSemanticVersion } from "../../../../modules/stringFormatters";
+import { addLogEntry } from "../../../../modules/logEntries";
+
+const AISettingsForm = lazy(() => import("./AISettingsForm"));
+const ActionsForm = lazy(() => import("./ActionsForm"));
+const InterfaceSettingsForm = lazy(() => import("./InterfaceSettingsForm"));
+
+export default function MenuDrawer(drawerProps: DrawerProps) {
+  const repoName = repository.url.split("/").pop();
+
+  return (
+    <Drawer
+      {...drawerProps}
+      position="right"
+      size="md"
+      title={
+        <Group gap="xs">
+          <ActionIcon
+            variant="subtle"
+            component="a"
+            color="var(--mantine-color-text)"
+            href={repository.url}
+            target="_blank"
+            onClick={() => addLogEntry("User clicked the GitHub link")}
+          >
+            <IconBrandGithub size={16} />
+          </ActionIcon>
+          <HoverCard shadow="md" withArrow>
+            <HoverCard.Target>
+              <Center>{repoName}</Center>
+            </HoverCard.Target>
+            <HoverCard.Dropdown>
+              <Stack gap="xs">
+                <Center>{repoName}</Center>
+                <Center>
+                  {`v${getSemanticVersion(VITE_BUILD_DATE_TIME)}+${VITE_COMMIT_SHORT_HASH}`}
+                </Center>
+                <Center>
+                  Released{" "}
+                  {prettyMilliseconds(
+                    new Date().getTime() -
+                      new Date(VITE_BUILD_DATE_TIME).getTime(),
+                    {
+                      compact: true,
+                      verbose: true,
+                    },
+                  )}{" "}
+                  ago
+                </Center>
+              </Stack>
+            </HoverCard.Dropdown>
+          </HoverCard>
+        </Group>
+      }
+    >
+      <FocusTrap.InitialFocus />
+      <Drawer.Body>
+        <Accordion variant="separated" multiple>
+          <Accordion.Item value="aiSettings">
+            <Accordion.Control>AI Settings</Accordion.Control>
+            <Accordion.Panel>
+              <Suspense>
+                <AISettingsForm />
+              </Suspense>
+            </Accordion.Panel>
+          </Accordion.Item>
+          <Accordion.Item value="interfaceSettings">
+            <Accordion.Control>Interface Settings</Accordion.Control>
+            <Accordion.Panel>
+              <Suspense>
+                <InterfaceSettingsForm />
+              </Suspense>
+            </Accordion.Panel>
+          </Accordion.Item>
+          <Accordion.Item value="actions">
+            <Accordion.Control>Actions</Accordion.Control>
+            <Accordion.Panel>
+              <Suspense>
+                <ActionsForm />
+              </Suspense>
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </Drawer.Body>
+    </Drawer>
+  );
+}

client/components/Search/Form/SearchForm.tsx

@@ -0,0 +1,137 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  useCallback,
+  ChangeEvent,
+  KeyboardEvent,
+  ReactNode,
+} from "react";
+import { getRandomQuerySuggestion } from "../../../modules/querySuggestions";
+import { useLocation } from "wouter";
+import { searchAndRespond } from "../../../modules/textGeneration";
+import { match, Pattern } from "ts-pattern";
+import { Button, Group, Stack, Textarea } from "@mantine/core";
+import { addLogEntry } from "../../../modules/logEntries";
+import { sleepUntilIdle } from "../../../modules/sleep";
+import { settingsPubSub } from "../../../modules/pubSub";
+import { usePubSub } from "create-pubsub/react";
+import { postMessageToParentWindow } from "../../../modules/parentWindow";
+
+export default function SearchForm({
+  query,
+  updateQuery,
+  additionalButtons,
+}: {
+  query: string;
+  updateQuery: (query: string) => void;
+  additionalButtons?: ReactNode;
+}) {
+  const textAreaRef = useRef<HTMLTextAreaElement>(null);
+  const [textAreaValue, setTextAreaValue] = useState(query);
+  const defaultSuggestedQuery = "Anything you need!";
+  const [suggestedQuery, setSuggestedQuery] = useState(defaultSuggestedQuery);
+  const [, navigate] = useLocation();
+  const [settings] = usePubSub(settingsPubSub);
+
+  useEffect(() => {
+    sleepUntilIdle().then(() => {
+      searchAndRespond();
+    });
+  }, []);
+
+  useEffect(() => {
+    getRandomQuerySuggestion().then((querySuggestion) => {
+      setSuggestedQuery(querySuggestion);
+    });
+  }, []);
+
+  const handleInputChange = async (event: ChangeEvent<HTMLTextAreaElement>) => {
+    const text = event.target.value;
+
+    setTextAreaValue(text);
+
+    if (text.length === 0) {
+      setSuggestedQuery(await getRandomQuerySuggestion());
+    }
+  };
+
+  const handleClearButtonClick = async () => {
+    setSuggestedQuery(await getRandomQuerySuggestion());
+    setTextAreaValue("");
+    textAreaRef.current?.focus();
+    addLogEntry("User cleaned the search query field");
+  };
+
+  const startSearching = useCallback(() => {
+    const queryToEncode = match(textAreaValue.trim())
+      .with(Pattern.string.minLength(1), () => textAreaValue)
+      .otherwise(() => suggestedQuery);
+
+    setTextAreaValue(queryToEncode);
+
+    const queryString = `q=${encodeURIComponent(queryToEncode)}`;
+
+    postMessageToParentWindow({ queryString, hash: "" });
+
+    navigate(`/?${queryString}`, { replace: true });
+
+    updateQuery(queryToEncode);
+
+    searchAndRespond();
+
+    addLogEntry(
+      `User submitted a search with ${queryToEncode.length} characters length`,
+    );
+  }, [textAreaValue, suggestedQuery, updateQuery]);
+
+  const handleSubmit = (event: { preventDefault: () => void }) => {
+    event.preventDefault();
+    startSearching();
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    match([event, settings.enterToSubmit])
+      .with(
+        [{ code: "Enter", shiftKey: false }, true],
+        [{ code: "Enter", shiftKey: true }, false],
+        () => handleSubmit(event),
+      )
+      .otherwise(() => undefined);
+  };
+
+  return (
+    <form onSubmit={handleSubmit} style={{ width: "100%" }}>
+      <Stack gap="xs">
+        <Textarea
+          value={textAreaValue}
+          placeholder={suggestedQuery}
+          ref={textAreaRef}
+          onKeyDown={handleKeyDown}
+          onChange={handleInputChange}
+          autosize
+          minRows={1}
+          maxRows={8}
+          autoFocus
+        />
+        <Group gap="xs">
+          {match(textAreaValue)
+            .with(Pattern.string.minLength(1), () => (
+              <Button
+                size="xs"
+                onClick={handleClearButtonClick}
+                variant="default"
+              >
+                Clear
+              </Button>
+            ))
+            .otherwise(() => null)}
+          <Button size="xs" type="submit" variant="default" flex={1}>
+            Search
+          </Button>
+          {additionalButtons}
+        </Group>
+      </Stack>
+    </form>
+  );
+}

client/components/Search/Results/Graphical/ImageResultsList.tsx

@@ -0,0 +1,112 @@
+import { Carousel } from "@mantine/carousel";
+import { SearchResults } from "../../../../modules/search";
+import { useState, useEffect } from "react";
+import { Button, Group, rem, Stack, Transition, Text } from "@mantine/core";
+import "@mantine/carousel/styles.css";
+import Lightbox from "yet-another-react-lightbox";
+import Captions from "yet-another-react-lightbox/plugins/captions";
+import "yet-another-react-lightbox/styles.css";
+import "yet-another-react-lightbox/plugins/captions.css";
+import { addLogEntry } from "../../../../modules/logEntries";
+import { getHostname } from "../../../../modules/stringFormatters";
+
+export default function ImageResultsList({
+  imageResults,
+}: {
+  imageResults: SearchResults["imageResults"];
+}) {
+  const [isLightboxOpen, setLightboxOpen] = useState(false);
+  const [lightboxIndex, setLightboxIndex] = useState(0);
+  const [isMounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+
+  const handleImageClick = (index: number) => {
+    setLightboxIndex(index);
+    setLightboxOpen(true);
+  };
+
+  const imageStyle = {
+    objectFit: "cover",
+    height: rem(180),
+    width: rem(240),
+    borderRadius: rem(4),
+    border: `${rem(2)} solid var(--mantine-color-default-border)`,
+    cursor: "zoom-in",
+  } as const;
+
+  return (
+    <>
+      <Carousel slideSize="0" slideGap="xs" align="start" dragFree loop>
+        {imageResults.map(([title, , thumbnailUrl], index) => (
+          <Transition
+            key={index}
+            mounted={isMounted}
+            transition="fade"
+            timingFunction="ease"
+            enterDelay={index * 250}
+            duration={1500}
+          >
+            {(styles) => (
+              <Carousel.Slide style={styles}>
+                <img
+                  alt={title}
+                  src={thumbnailUrl}
+                  onClick={() => handleImageClick(index)}
+                  style={imageStyle}
+                />
+              </Carousel.Slide>
+            )}
+          </Transition>
+        ))}
+      </Carousel>
+      <Lightbox
+        open={isLightboxOpen}
+        close={() => setLightboxOpen(false)}
+        plugins={[Captions]}
+        index={lightboxIndex}
+        slides={imageResults.map(([title, url, thumbnailUrl, sourceUrl]) => ({
+          src: thumbnailUrl,
+          description: (
+            <Stack align="center" gap="md">
+              {title && (
+                <Text component="cite" ta="center">
+                  {title}
+                </Text>
+              )}
+              <Group align="center" justify="center" gap="xs">
+                <Button
+                  variant="subtle"
+                  component="a"
+                  size="xs"
+                  href={sourceUrl}
+                  target="_blank"
+                  title="Click to see the image in full size"
+                  rel="noopener noreferrer"
+                  onClick={() => {
+                    addLogEntry("User visited an image result in full size");
+                  }}
+                >
+                  View in full resolution
+                </Button>
+                <Button
+                  variant="subtle"
+                  component="a"
+                  href={url}
+                  target="_blank"
+                  size="xs"
+                  title="Click to visit the page where the image was found"
+                  rel="noopener noreferrer"
+                  onClick={() => {
+                    addLogEntry("User visited an image result source");
+                  }}
+                >
+                  Visit {getHostname(url)}
+                </Button>
+              </Group>
+            </Stack>
+          ),
+        }))}
+      />
+    </>
+  );
+}

client/components/Search/Results/SearchResultsSection.tsx

@@ -0,0 +1,129 @@
+import { usePubSub } from "create-pubsub/react";
+import {
+  searchResultsPubSub,
+  searchStatePubSub,
+  settingsPubSub,
+} from "../../../modules/pubSub";
+import { match, Pattern } from "ts-pattern";
+import {
+  Divider,
+  Skeleton,
+  Alert,
+  Stack,
+  Group,
+  Space,
+  AspectRatio,
+  em,
+} from "@mantine/core";
+import { IconInfoCircle } from "@tabler/icons-react";
+import { lazy, Suspense, useMemo } from "react";
+import { Settings } from "../../../modules/settings";
+import { SearchResults } from "../../../modules/search";
+import { useMediaQuery } from "@mantine/hooks";
+
+const ImageResultsList = lazy(() => import("./Graphical/ImageResultsList"));
+const SearchResultsList = lazy(() => import("./Textual/SearchResultsList"));
+
+export default function SearchResultsSection() {
+  const [searchResults] = usePubSub(searchResultsPubSub);
+  const [searchState] = usePubSub(searchStatePubSub);
+  const [settings] = usePubSub(settingsPubSub);
+
+  return useMemo(
+    () =>
+      match(searchState)
+        .with("running", () => <RunningSearchContent />)
+        .with("failed", () => <FailedSearchContent />)
+        .with("completed", () => (
+          <CompletedSearchContent
+            searchResults={searchResults}
+            settings={settings}
+          />
+        ))
+        .otherwise(() => null),
+    [searchState, searchResults, settings],
+  );
+}
+
+function RunningSearchContent() {
+  const hasSmallScreen = useMediaQuery(`(max-width: ${em(530)})`);
+
+  const numberOfSquareSkeletons = hasSmallScreen ? 4 : 6;
+
+  return (
+    <>
+      <Divider
+        mb="sm"
+        variant="dashed"
+        labelPosition="center"
+        label="Searching the web..."
+      />
+      <Stack>
+        <Group>
+          {[...Array(numberOfSquareSkeletons)].map((_, index) => (
+            <AspectRatio key={index} ratio={1} flex={1}>
+              <Skeleton />
+            </AspectRatio>
+          ))}
+        </Group>
+        <Stack>
+          <Skeleton height={8} radius="xl" />
+          <Skeleton height={8} width="87%" radius="xl" />
+          <Skeleton height={8} radius="xl" />
+          <Skeleton height={8} width="70%" radius="xl" />
+          <Skeleton height={8} radius="xl" />
+          <Skeleton height={8} width="52%" radius="xl" />
+          <Skeleton height={8} radius="xl" />
+          <Skeleton height={8} width="63%" radius="xl" />
+        </Stack>
+      </Stack>
+    </>
+  );
+}
+
+function FailedSearchContent() {
+  return (
+    <>
+      <Divider
+        mb="sm"
+        variant="dashed"
+        labelPosition="center"
+        label="Search Results"
+      />
+      <Alert
+        variant="light"
+        color="yellow"
+        title="No results found"
+        icon={<IconInfoCircle />}
+      >
+        It looks like your current search did not return any results. Try
+        refining your search by adding more keywords or rephrasing your query.
+      </Alert>
+    </>
+  );
+}
+
+function CompletedSearchContent({
+  searchResults,
+  settings,
+}: {
+  searchResults: SearchResults;
+  settings: Settings;
+}) {
+  return (
+    <>
+      <Divider variant="dashed" labelPosition="center" label="Search Results" />
+      {match([settings.enableImageSearch, searchResults.imageResults.length])
+        .with([true, Pattern.number.positive()], () => (
+          <Suspense>
+            <ImageResultsList imageResults={searchResults.imageResults} />
+            <Space h={8} />
+          </Suspense>
+        ))
+        .otherwise(() => null)}
+      <Suspense>
+        <SearchResultsList searchResults={searchResults.textResults} />
+      </Suspense>
+    </>
+  );
+}

client/components/Search/Results/Textual/SearchResultsList.tsx

@@ -0,0 +1,85 @@
+import { SearchResults } from "../../../../modules/search";
+import {
+  Tooltip,
+  Stack,
+  Text,
+  Flex,
+  UnstyledButton,
+  Transition,
+  em,
+} from "@mantine/core";
+import { useMediaQuery } from "@mantine/hooks";
+import { getHostname } from "../../../../modules/stringFormatters";
+import { addLogEntry } from "../../../../modules/logEntries";
+import { useEffect, useState } from "react";
+
+export default function SearchResultsList({
+  searchResults,
+}: {
+  searchResults: SearchResults["textResults"];
+}) {
+  const shouldDisplayDomainBelowTitle = useMediaQuery(
+    `(max-width: ${em(720)})`,
+  );
+  const [isMounted, setMounted] = useState(false);
+
+  useEffect(() => setMounted(true), []);
+
+  return (
+    <Stack gap={40}>
+      {searchResults.map(([title, snippet, url], index) => (
+        <Transition
+          key={url}
+          mounted={isMounted}
+          transition="fade"
+          timingFunction="ease"
+          enterDelay={index * 200}
+          duration={750}
+        >
+          {(styles) => (
+            <Stack gap={16} style={styles}>
+              <Flex
+                gap={shouldDisplayDomainBelowTitle ? 0 : 16}
+                justify="space-between"
+                align="flex-start"
+                direction={shouldDisplayDomainBelowTitle ? "column" : "row"}
+              >
+                <UnstyledButton
+                  variant="transparent"
+                  component="a"
+                  href={url}
+                  target="_blank"
+                  onClick={() => {
+                    addLogEntry("User clicked a text result");
+                  }}
+                >
+                  <Text fw="bold" c="var(--mantine-color-blue-light-color)">
+                    {title}
+                  </Text>
+                </UnstyledButton>
+                <Tooltip label={url}>
+                  <UnstyledButton
+                    variant="transparent"
+                    component="a"
+                    href={url}
+                    target="_blank"
+                    fs="italic"
+                    ta="end"
+                    onClick={() => {
+                      addLogEntry("User clicked a text result");
+                    }}
+                  >
+                    {getHostname(url)}
+                  </UnstyledButton>
+                </Tooltip>
+              </Flex>
+              <Text size="sm" c="dimmed" style={{ wordWrap: "break-word" }}>
+                {snippet}
+              </Text>
+            </Stack>
+          )}
+        </Transition>
+      ))}
+    </Stack>
+  );
+}

client/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no"
+    />
+    <meta
+      name="description"
+      content="Minimalist web-searching app with an AI assistant that is always available and runs directly from your browser."
+    />
+    <meta itemprop="name" content="MiniSearch" />
+    <meta
+      itemprop="description"
+      content="Minimalist web-searching app with an AI assistant that is always available and runs directly from your browser."
+    />
+    <meta property="og:type" content="website" />
+    <meta property="og:title" content="MiniSearch" />
+    <meta
+      property="og:description"
+      content="Minimalist web-searching app with an AI assistant that is always available and runs directly from your browser."
+    />
+    <meta name="twitter:card" content="summary" />
+    <meta name="twitter:title" content="MiniSearch" />
+    <meta
+      name="twitter:description"
+      content="Minimalist web-searching app with an AI assistant that is always available and runs directly from your browser."
+    />
+    <title>MiniSearch</title>
+    <link
+      rel="icon"
+      href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🔍</text></svg>"
+    />
+  </head>
+  <body>
+    <script type="module" src="./index.tsx"></script>
+  </body>
+</html>

client/index.tsx

@@ -0,0 +1,9 @@
+import { createRoot } from "react-dom/client";
+import { addLogEntry } from "./modules/logEntries";
+import { App } from "./components/App/App";
+
+createRoot(document.body.appendChild(document.createElement("div"))).render(
+  <App />,
+);
+
+addLogEntry("App initialized");

client/modules/accessKey.ts

@@ -0,0 +1,95 @@
+import { addLogEntry } from "./logEntries";
+import { notifications } from "@mantine/notifications";
+import { argon2id } from "hash-wasm";
+
+const ACCESS_KEY_STORAGE_KEY = "accessKeyHash";
+
+interface StoredAccessKey {
+  hash: string;
+  timestamp: number;
+}
+
+async function hashAccessKey(accessKey: string): Promise<string> {
+  const salt = new Uint8Array(16);
+  crypto.getRandomValues(salt);
+
+  return argon2id({
+    password: accessKey,
+    salt,
+    parallelism: 1,
+    iterations: 16,
+    memorySize: 512,
+    hashLength: 8,
+    outputType: "encoded",
+  });
+}
+
+export async function validateAccessKey(accessKey: string): Promise<boolean> {
+  try {
+    const hash = await hashAccessKey(accessKey);
+    const response = await fetch("/api/validate-access-key", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ accessKeyHash: hash }),
+    });
+    const data = await response.json();
+
+    if (data.valid) {
+      const storedData: StoredAccessKey = {
+        hash,
+        timestamp: Date.now(),
+      };
+      localStorage.setItem(ACCESS_KEY_STORAGE_KEY, JSON.stringify(storedData));
+      addLogEntry("Access key hash stored");
+    }
+
+    return data.valid;
+  } catch (error) {
+    addLogEntry(`Error validating access key: ${error}`);
+    notifications.show({
+      title: "Error validating access key",
+      message: "Please contact the administrator",
+      color: "red",
+      position: "top-right",
+    });
+    return false;
+  }
+}
+
+export async function verifyStoredAccessKey(): Promise<boolean> {
+  if (VITE_ACCESS_KEY_TIMEOUT_HOURS === 0) return false;
+
+  const storedData = localStorage.getItem(ACCESS_KEY_STORAGE_KEY);
+  if (!storedData) return false;
+
+  try {
+    const { hash, timestamp }: StoredAccessKey = JSON.parse(storedData);
+
+    const expirationTime = VITE_ACCESS_KEY_TIMEOUT_HOURS * 60 * 60 * 1000;
+    if (Date.now() - timestamp > expirationTime) {
+      localStorage.removeItem(ACCESS_KEY_STORAGE_KEY);
+      addLogEntry("Stored access key expired");
+      return false;
+    }
+
+    const response = await fetch("/api/validate-access-key", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ accessKeyHash: hash }),
+    });
+
+    const data = await response.json();
+    if (!data.valid) {
+      localStorage.removeItem(ACCESS_KEY_STORAGE_KEY);
+      addLogEntry("Stored access key is no longer valid");
+      return false;
+    }
+
+    addLogEntry("Using stored access key");
+    return true;
+  } catch (error) {
+    addLogEntry(`Error verifying stored access key: ${error}`);
+    localStorage.removeItem(ACCESS_KEY_STORAGE_KEY);
+    return false;
+  }
+}

client/modules/logEntries.ts

@@ -0,0 +1,20 @@
+import { createPubSub } from "create-pubsub";
+
+type LogEntry = {
+  timestamp: string;
+  message: string;
+};
+
+export const logEntriesPubSub = createPubSub<LogEntry[]>([]);
+
+const [updateLogEntries, , getLogEntries] = logEntriesPubSub;
+
+export function addLogEntry(message: string) {
+  updateLogEntries([
+    ...getLogEntries(),
+    {
+      timestamp: new Date().toISOString(),
+      message,
+    },
+  ]);
+}

client/modules/openai.ts

@@ -0,0 +1,16 @@
+import OpenAI, { ClientOptions } from "openai";
+
+export function getOpenAiClient({
+  baseURL,
+  apiKey,
+}: {
+  baseURL: ClientOptions["baseURL"];
+  apiKey: ClientOptions["apiKey"];
+}) {
+  return new OpenAI({
+    baseURL,
+    apiKey,
+    dangerouslyAllowBrowser: true,
+    defaultHeaders: { "X-Stainless-Retry-Count": null },
+  });
+}

client/modules/parentWindow.ts

@@ -0,0 +1,5 @@
+export function postMessageToParentWindow(message: unknown) {
+  const parentWindow = self.parent;
+  const targetOrigin = parentWindow?.[0]?.location?.ancestorOrigins?.[0];
+  if (targetOrigin) parentWindow.postMessage(message, targetOrigin);
+}

client/modules/pubSub.ts

@@ -0,0 +1,88 @@
+import { createPubSub } from "create-pubsub";
+import { defaultSettings } from "./settings";
+
+function createLocalStoragePubSub<T>(localStorageKey: string, defaultValue: T) {
+  const localStorageValue = localStorage.getItem(localStorageKey);
+  const localStoragePubSub = createPubSub(
+    localStorageValue ? (JSON.parse(localStorageValue) as T) : defaultValue,
+  );
+
+  const [, onValueChange] = localStoragePubSub;
+
+  onValueChange((value) =>
+    localStorage.setItem(localStorageKey, JSON.stringify(value)),
+  );
+
+  return localStoragePubSub;
+}
+
+const querySuggestionsPubSub = createLocalStoragePubSub<string[]>(
+  "querySuggestions",
+  [],
+);
+
+const lastSearchTokenHashPubSub = createLocalStoragePubSub(
+  "lastSearchTokenHash",
+  "",
+);
+
+export const [updateLastSearchTokenHash, , getLastSearchTokenHash] =
+  lastSearchTokenHashPubSub;
+
+export const [updateQuerySuggestions, , getQuerySuggestions] =
+  querySuggestionsPubSub;
+
+export const queryPubSub = createPubSub(
+  new URLSearchParams(self.location.search).get("q") ?? "",
+);
+
+export const [, , getQuery] = queryPubSub;
+
+export const responsePubSub = createPubSub("");
+
+export const [updateResponse] = responsePubSub;
+
+export const searchResultsPubSub = createPubSub<
+  import("./search").SearchResults
+>({
+  textResults: [],
+  imageResults: [],
+});
+
+export const [updateSearchResults, , getSearchResults] = searchResultsPubSub;
+
+export const [updateSearchPromise, , getSearchPromise] = createPubSub<
+  Promise<import("./search").SearchResults>
+>(Promise.resolve({ textResults: [], imageResults: [] }));
+
+export const textGenerationStatePubSub = createPubSub<
+  | "idle"
+  | "awaitingModelDownloadAllowance"
+  | "loadingModel"
+  | "awaitingSearchResults"
+  | "preparingToGenerate"
+  | "generating"
+  | "interrupted"
+  | "failed"
+  | "completed"
+>("idle");
+
+export const [updateTextGenerationState, , getTextGenerationState] =
+  textGenerationStatePubSub;
+
+export const searchStatePubSub = createPubSub<
+  "idle" | "running" | "failed" | "completed"
+>("idle");
+
+export const [updateSearchState] = searchStatePubSub;
+
+export const modelLoadingProgressPubSub = createPubSub(0);
+
+export const [updateModelLoadingProgress] = modelLoadingProgressPubSub;
+
+export const settingsPubSub = createLocalStoragePubSub(
+  "settings",
+  defaultSettings,
+);
+
+export const [, listenToSettingsChanges, getSettings] = settingsPubSub;

client/modules/querySuggestions.ts

@@ -0,0 +1,31 @@
+import { getQuerySuggestions, updateQuerySuggestions } from "./pubSub";
+import { addLogEntry } from "./logEntries";
+
+export async function getRandomQuerySuggestion() {
+  if (getQuerySuggestions().length === 0) await refillQuerySuggestions(25);
+
+  const querySuggestions = getQuerySuggestions();
+
+  const randomQuerySuggestion = querySuggestions.pop() as string;
+
+  updateQuerySuggestions(querySuggestions);
+
+  return randomQuerySuggestion;
+}
+
+async function refillQuerySuggestions(limit?: number) {
+  const querySuggestionsFileUrl = new URL(
+    "/query-suggestions.json",
+    self.location.origin,
+  );
+
+  const fetchResponse = await fetch(querySuggestionsFileUrl.toString());
+
+  const querySuggestionsList: string[] = await fetchResponse.json();
+
+  updateQuerySuggestions(
+    querySuggestionsList.sort(() => Math.random() - 0.5).slice(0, limit),
+  );
+
+  addLogEntry(`Query suggestions refilled with ${limit} suggestions`);
+}

client/modules/search.ts

@@ -0,0 +1,159 @@
+import { getSearchTokenHash } from "./searchTokenHash";
+import { name } from "../../package.json";
+import { addLogEntry } from "./logEntries";
+
+export type SearchResults = {
+  textResults: [title: string, snippet: string, url: string][];
+  imageResults: [
+    title: string,
+    url: string,
+    thumbnailUrl: string,
+    sourceUrl: string,
+  ][];
+};
+
+/**
+ * Creates a cached version of a search function using IndexedDB for storage.
+ *
+ * @param fn - The original search function to be cached.
+ * @returns A new function that wraps the original, adding caching functionality.
+ *
+ * This function implements a caching mechanism for search results using IndexedDB.
+ * It stores search results with a 15-minute time-to-live (TTL) to improve performance
+ * for repeated searches. The cache is automatically cleaned of expired entries.
+ *
+ * The returned function behaves as follows:
+ * 1. Checks IndexedDB for a cached result matching the query.
+ * 2. If a valid (non-expired) cached result exists, it is returned immediately.
+ * 3. Otherwise, the original search function is called, and its result is both
+ *    returned and stored in the cache for future use.
+ *
+ * If IndexedDB is not available, the function falls back to using the original
+ * search function without caching.
+ */
+function cacheSearchWithIndexedDB(
+  fn: (query: string, limit?: number) => Promise<SearchResults>,
+): (query: string, limit?: number) => Promise<SearchResults> {
+  const storeName = "searches";
+  const timeToLive = 15 * 60 * 1000;
+
+  async function openDB(): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(name, 1);
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        const db = request.result;
+        cleanExpiredCache(db);
+        resolve(db);
+      };
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        db.createObjectStore(storeName);
+      };
+    });
+  }
+
+  async function cleanExpiredCache(db: IDBDatabase): Promise<void> {
+    const transaction = db.transaction(storeName, "readwrite");
+    const store = transaction.objectStore(storeName);
+    const currentTime = Date.now();
+
+    return new Promise((resolve) => {
+      const request = store.openCursor();
+      request.onsuccess = (event) => {
+        const cursor = (event.target as IDBRequest).result;
+        if (cursor) {
+          if (currentTime - cursor.value.timestamp >= timeToLive) {
+            cursor.delete();
+          }
+          cursor.continue();
+        } else {
+          resolve();
+        }
+      };
+    });
+  }
+
+  /**
+   * Generates a hash for a given query string.
+   *
+   * This function implements a simple hash algorithm:
+   * 1. It iterates through each character in the query string.
+   * 2. For each character, it updates the hash value using bitwise operations.
+   * 3. The final hash is converted to a 32-bit integer.
+   * 4. The result is returned as a base-36 string representation.
+   *
+   * @param query - The input string to be hashed.
+   * @returns A string representation of the hash in base-36.
+   */
+  function hashQuery(query: string): string {
+    return query
+      .split("")
+      .reduce((acc, char) => ((acc << 5) - acc + char.charCodeAt(0)) | 0, 0)
+      .toString(36);
+  }
+
+  const dbPromise = openDB();
+
+  return async (query: string, limit?: number): Promise<SearchResults> => {
+    addLogEntry("Starting new search");
+    if (!indexedDB) return fn(query, limit);
+
+    const db = await dbPromise;
+    const transaction = db.transaction(storeName, "readwrite");
+    const store = transaction.objectStore(storeName);
+    const key = hashQuery(query);
+    const cachedResult = await new Promise<
+      | {
+          results: SearchResults;
+          timestamp: number;
+        }
+      | undefined
+    >((resolve) => {
+      const request = store.get(key);
+      request.onerror = () => resolve(undefined);
+      request.onsuccess = () => resolve(request.result);
+    });
+
+    if (cachedResult && Date.now() - cachedResult.timestamp < timeToLive) {
+      addLogEntry(
+        `Search cache hit, returning cached results containing ${cachedResult.results.textResults.length} texts and ${cachedResult.results.imageResults.length} images`,
+      );
+      return cachedResult.results;
+    } else {
+      addLogEntry("Search cache miss, fetching new results");
+    }
+
+    const results = await fn(query, limit);
+
+    const writeTransaction = db.transaction(storeName, "readwrite");
+    const writeStore = writeTransaction.objectStore(storeName);
+    writeStore.put({ results, timestamp: Date.now() }, key);
+
+    addLogEntry(
+      `Search completed with ${results.textResults.length} text results and ${results.imageResults.length} image results`,
+    );
+
+    return results;
+  };
+}
+
+export const search = cacheSearchWithIndexedDB(
+  async (query: string, limit?: number): Promise<SearchResults> => {
+    const searchUrl = new URL("/search", self.location.origin);
+
+    searchUrl.searchParams.set("q", query);
+
+    searchUrl.searchParams.set("token", await getSearchTokenHash());
+
+    if (limit && limit > 0) {
+      searchUrl.searchParams.set("limit", limit.toString());
+    }
+
+    const response = await fetch(searchUrl.toString());
+
+    return response.ok
+      ? response.json()
+      : { textResults: [], imageResults: [] };
+  },
+);

client/modules/searchTokenHash.ts

@@ -0,0 +1,41 @@
+import { argon2id, argon2Verify } from "hash-wasm";
+import { updateLastSearchTokenHash, getLastSearchTokenHash } from "./pubSub";
+import { addLogEntry } from "./logEntries";
+
+export async function getSearchTokenHash() {
+  const password = VITE_SEARCH_TOKEN;
+  const lastSearchTokenHash = getLastSearchTokenHash();
+
+  try {
+    const lastSearchTokenHashIsValid = await argon2Verify({
+      password,
+      hash: lastSearchTokenHash,
+    });
+
+    if (lastSearchTokenHashIsValid) {
+      addLogEntry("Using cached search token hash");
+      return lastSearchTokenHash;
+    }
+  } catch (error) {
+    void error;
+  }
+
+  const salt = new Uint8Array(16);
+  crypto.getRandomValues(salt);
+
+  const newSearchTokenHash = await argon2id({
+    password,
+    salt,
+    parallelism: 1,
+    iterations: 16,
+    memorySize: 512,
+    hashLength: 8,
+    outputType: "encoded",
+  });
+
+  updateLastSearchTokenHash(newSearchTokenHash);
+
+  addLogEntry("New search token hash generated");
+
+  return newSearchTokenHash;
+}

client/modules/settings.ts

@@ -0,0 +1,48 @@
+import { addLogEntry } from "./logEntries";
+import { isF16Supported } from "./webGpu";
+
+export const defaultSettings = {
+  enableAiResponse: true,
+  enableWebGpu: true,
+  enableImageSearch: true,
+  webLlmModelId: isF16Supported
+    ? VITE_WEBLLM_DEFAULT_F16_MODEL_ID
+    : VITE_WEBLLM_DEFAULT_F32_MODEL_ID,
+  wllamaModelId: VITE_WLLAMA_DEFAULT_MODEL_ID,
+  cpuThreads: 1,
+  searchResultsToConsider: 3,
+  systemPrompt: `I need assistance with my research, so please provide short and clear responses following these guidelines:
+- Base your responses on the provided search results and your general knowledge about the topic.
+- Answer in the same language in which I ask, with an analytical tone.
+- Use Markdown format, without headers.
+- Keep in mind today's date and time ({{dateTime}}).
+- Include any additional relevant information you think would be good to know.
+
+Search results:
+{{searchResults}}`,
+  inferenceType: VITE_DEFAULT_INFERENCE_TYPE,
+  inferenceTemperature: 0.5,
+  inferenceTopP: 1,
+  inferenceFrequencyPenalty: 0.5,
+  inferencePresencePenalty: 0.3,
+  inferenceRepeatPenalty: 1.176,
+  openAiApiBaseUrl: "",
+  openAiApiKey: "",
+  openAiApiModel: "",
+  enterToSubmit: true,
+  allowAiModelDownload: false,
+};
+
+addLogEntry(
+  `Number of logical processors in CPU: ${navigator.hardwareConcurrency ?? "unknown"}`,
+);
+
+export type Settings = typeof defaultSettings;
+
+export const inferenceTypes = [
+  { value: "browser", label: "In the browser (Private)" },
+  { value: "openai", label: "Remote server (API)" },
+  ...(VITE_INTERNAL_API_ENABLED
+    ? [{ value: "internal", label: VITE_INTERNAL_API_NAME }]
+    : []),
+];

client/modules/sleep.ts

@@ -0,0 +1,9 @@
+export async function sleep(milliseconds: number) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+  });
+}
+
+export function sleepUntilIdle() {
+  return sleep(0);
+}

client/modules/stringFormatters.ts

@@ -0,0 +1,22 @@
+/**
+ * Get the hostname of a URL.
+ * @param url - The URL to get the hostname of.
+ * @returns The hostname of the URL.
+ */
+export function getHostname(url: string) {
+  try {
+    return new URL(url).hostname.replace("www.", "");
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Get the semantic version of a date.
+ * @param date - The date to get the semantic version of.
+ * @returns The semantic version of the date.
+ */
+export function getSemanticVersion(date: number | string | Date) {
+  const targetDate = new Date(date);
+  return `${targetDate.getFullYear()}.${targetDate.getMonth() + 1}.${targetDate.getDate()}`;
+}

client/modules/systemPrompt.ts

@@ -0,0 +1,7 @@
+import { getSettings } from "./pubSub";
+
+export function getSystemPrompt(searchResults: string) {
+  return getSettings()
+    .systemPrompt.replace("{{searchResults}}", searchResults)
+    .replace("{{dateTime}}", new Date().toString());
+}

client/modules/textGeneration.ts

@@ -0,0 +1,735 @@
+import { isWebGPUAvailable } from "./webGpu";
+import {
+  updateSearchResults,
+  updateResponse,
+  getSearchResults,
+  getQuery,
+  updateSearchPromise,
+  getSearchPromise,
+  updateTextGenerationState,
+  updateSearchState,
+  updateModelLoadingProgress,
+  getTextGenerationState,
+  getSettings,
+  listenToSettingsChanges,
+} from "./pubSub";
+import { search } from "./search";
+import { addLogEntry } from "./logEntries";
+import { getSystemPrompt } from "./systemPrompt";
+import prettyMilliseconds from "pretty-ms";
+import { getOpenAiClient } from "./openai";
+import { getSearchTokenHash } from "./searchTokenHash";
+import {
+  ChatCompletionCreateParamsStreaming,
+  ChatCompletionMessageParam,
+} from "openai/resources/chat/completions.mjs";
+import gptTokenizer from "gpt-tokenizer";
+import { ChatOptions } from "@mlc-ai/web-llm";
+import { defaultSettings } from "./settings";
+
+export async function searchAndRespond() {
+  if (getQuery() === "") return;
+
+  document.title = getQuery();
+
+  updateResponse("");
+
+  updateSearchResults({ textResults: [], imageResults: [] });
+
+  updateSearchPromise(startSearch(getQuery()));
+
+  if (!getSettings().enableAiResponse) return;
+
+  const responseGenerationStartTime = new Date().getTime();
+
+  updateTextGenerationState("loadingModel");
+
+  try {
+    const settings = getSettings();
+    if (settings.inferenceType === "openai") {
+      await generateTextWithOpenAI();
+    } else if (settings.inferenceType === "internal") {
+      await generateTextWithInternalApi();
+    } else {
+      await canDownloadModels();
+      updateTextGenerationState("loadingModel");
+      try {
+        if (!isWebGPUAvailable) throw Error("WebGPU is not available.");
+
+        if (!settings.enableWebGpu) throw Error("WebGPU is disabled.");
+
+        await generateTextWithWebLlm();
+      } catch (error) {
+        addLogEntry(`Skipping text generation with WebLLM: ${error}`);
+        addLogEntry(`Starting text generation with Wllama`);
+        await generateTextWithWllama();
+      }
+    }
+
+    if (getTextGenerationState() !== "interrupted") {
+      updateTextGenerationState("completed");
+    }
+  } catch (error) {
+    addLogEntry(`Error generating text: ${error}`);
+    updateTextGenerationState("failed");
+  }
+
+  addLogEntry(
+    `Response generation took ${prettyMilliseconds(
+      new Date().getTime() - responseGenerationStartTime,
+      { verbose: true },
+    )}`,
+  );
+}
+
+async function generateTextWithOpenAI() {
+  const settings = getSettings();
+  const openai = getOpenAiClient({
+    baseURL: settings.openAiApiBaseUrl,
+    apiKey: settings.openAiApiKey,
+  });
+
+  await canStartResponding();
+
+  updateTextGenerationState("preparingToGenerate");
+
+  const completion = await openai.chat.completions.create({
+    ...getDefaultChatCompletionCreateParamsStreaming(),
+    model: settings.openAiApiModel,
+    messages: [
+      {
+        role: "user",
+        content: getSystemPrompt(getFormattedSearchResults(true)),
+      },
+      { role: "assistant", content: "Ok!" },
+      { role: "user", content: getQuery() },
+    ],
+  });
+
+  let streamedMessage = "";
+
+  for await (const chunk of completion) {
+    const deltaContent = chunk.choices[0].delta.content;
+
+    if (deltaContent) streamedMessage += deltaContent;
+
+    if (getTextGenerationState() === "interrupted") {
+      completion.controller.abort();
+    } else if (getTextGenerationState() !== "generating") {
+      updateTextGenerationState("generating");
+    }
+
+    updateResponseRateLimited(streamedMessage);
+  }
+
+  updateResponse(streamedMessage);
+}
+
+async function generateTextWithInternalApi() {
+  await canStartResponding();
+
+  updateTextGenerationState("preparingToGenerate");
+
+  const inferenceUrl = new URL("/inference", self.location.origin);
+
+  const tokenPrefix = "Bearer ";
+
+  const token = await getSearchTokenHash();
+
+  const response = await fetch(inferenceUrl.toString(), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `${tokenPrefix}${token}`,
+    },
+    body: JSON.stringify({
+      ...getDefaultChatCompletionCreateParamsStreaming(),
+      messages: [
+        {
+          role: "user",
+          content: getSystemPrompt(getFormattedSearchResults(true)),
+        },
+        { role: "assistant", content: "Ok!" },
+        { role: "user", content: getQuery() },
+      ],
+    } as ChatCompletionCreateParamsStreaming),
+  });
+
+  if (!response.ok || !response.body) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let streamedMessage = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value);
+    const lines = chunk.split("\n");
+    const parsedLines = lines
+      .map((line) => line.replace(/^data: /, "").trim())
+      .filter((line) => line !== "" && line !== "[DONE]")
+      .map((line) => JSON.parse(line));
+
+    for (const parsedLine of parsedLines) {
+      const deltaContent = parsedLine.choices[0].delta.content;
+      if (deltaContent) streamedMessage += deltaContent;
+
+      if (getTextGenerationState() === "interrupted") {
+        reader.cancel();
+      } else if (getTextGenerationState() !== "generating") {
+        updateTextGenerationState("generating");
+      }
+
+      updateResponseRateLimited(streamedMessage);
+    }
+  }
+
+  updateResponse(streamedMessage);
+}
+
+async function generateTextWithWebLlm() {
+  const { CreateWebWorkerMLCEngine, CreateMLCEngine, hasModelInCache } =
+    await import("@mlc-ai/web-llm");
+
+  type InitProgressCallback = import("@mlc-ai/web-llm").InitProgressCallback;
+  type MLCEngineConfig = import("@mlc-ai/web-llm").MLCEngineConfig;
+  type ChatOptions = import("@mlc-ai/web-llm").ChatOptions;
+
+  const selectedModelId = getSettings().webLlmModelId;
+
+  addLogEntry(`Selected WebLLM model: ${selectedModelId}`);
+
+  const isModelCached = await hasModelInCache(selectedModelId);
+
+  let initProgressCallback: InitProgressCallback | undefined;
+
+  if (isModelCached) {
+    updateTextGenerationState("preparingToGenerate");
+  } else {
+    initProgressCallback = (report) => {
+      updateModelLoadingProgress(Math.round(report.progress * 100));
+    };
+  }
+
+  const engineConfig: MLCEngineConfig = {
+    initProgressCallback,
+    logLevel: "SILENT",
+  };
+
+  const chatOptions: ChatOptions = {
+    repetition_penalty: defaultSettings.inferenceRepeatPenalty,
+  };
+
+  const engine = Worker
+    ? await CreateWebWorkerMLCEngine(
+        new Worker(new URL("./webLlmWorker.ts", import.meta.url), {
+          type: "module",
+        }),
+        selectedModelId,
+        engineConfig,
+        chatOptions,
+      )
+    : await CreateMLCEngine(selectedModelId, engineConfig, chatOptions);
+
+  if (getSettings().enableAiResponse) {
+    await canStartResponding();
+
+    updateTextGenerationState("preparingToGenerate");
+
+    const completion = await engine.chat.completions.create({
+      ...getDefaultChatCompletionCreateParamsStreaming(),
+      messages: [
+        {
+          role: "user",
+          content: getSystemPrompt(getFormattedSearchResults(true)),
+        },
+        { role: "assistant", content: "Ok!" },
+        { role: "user", content: getQuery() },
+      ],
+    });
+
+    let streamedMessage = "";
+
+    for await (const chunk of completion) {
+      const deltaContent = chunk.choices[0].delta.content;
+
+      if (deltaContent) streamedMessage += deltaContent;
+
+      if (getTextGenerationState() === "interrupted") {
+        await engine.interruptGenerate();
+      } else if (getTextGenerationState() !== "generating") {
+        updateTextGenerationState("generating");
+      }
+
+      updateResponseRateLimited(streamedMessage);
+    }
+
+    updateResponse(streamedMessage);
+  }
+
+  addLogEntry(
+    `WebLLM finished generating the response. Stats: ${await engine.runtimeStatsText()}`,
+  );
+
+  engine.unload();
+}
+
+async function generateTextWithWllama() {
+  const { initializeWllama, wllamaModels } = await import("./wllama");
+
+  let loadingPercentage = 0;
+
+  const model = wllamaModels[getSettings().wllamaModelId];
+
+  const wllama = await initializeWllama(model.url, {
+    wllama: {
+      suppressNativeLog: true,
+    },
+    model: {
+      n_threads: getSettings().cpuThreads,
+      n_ctx: model.contextSize,
+      cache_type_k: model.cacheType,
+      embeddings: false,
+      allowOffline: true,
+      progressCallback: ({ loaded, total }) => {
+        const progressPercentage = Math.round((loaded / total) * 100);
+
+        if (loadingPercentage !== progressPercentage) {
+          loadingPercentage = progressPercentage;
+          updateModelLoadingProgress(progressPercentage);
+        }
+      },
+    },
+  });
+
+  if (getSettings().enableAiResponse) {
+    await canStartResponding();
+
+    updateTextGenerationState("preparingToGenerate");
+
+    const prompt = await model.buildPrompt(
+      wllama,
+      getQuery(),
+      getFormattedSearchResults(model.shouldIncludeUrlsOnPrompt),
+    );
+
+    let streamedMessage = "";
+
+    await wllama.createCompletion(prompt, {
+      stopTokens: model.stopTokens,
+      sampling: model.sampling,
+      onNewToken: (_token, _piece, currentText, { abortSignal }) => {
+        if (getTextGenerationState() === "interrupted") {
+          abortSignal();
+        } else if (getTextGenerationState() !== "generating") {
+          updateTextGenerationState("generating");
+        }
+
+        if (model.stopStrings) {
+          for (const stopString of model.stopStrings) {
+            if (
+              currentText.slice(-(stopString.length * 2)).includes(stopString)
+            ) {
+              abortSignal();
+              currentText = currentText.slice(0, -stopString.length);
+              break;
+            }
+          }
+        }
+
+        streamedMessage = currentText;
+
+        updateResponseRateLimited(streamedMessage);
+      },
+    });
+
+    updateResponse(streamedMessage);
+  }
+
+  await wllama.exit();
+}
+
+function getFormattedSearchResults(shouldIncludeUrl: boolean) {
+  const searchResults = getSearchResults().textResults.slice(
+    0,
+    getSettings().searchResultsToConsider,
+  );
+
+  if (searchResults.length === 0) return "None.";
+
+  if (shouldIncludeUrl) {
+    return searchResults
+      .map(
+        ([title, snippet, url], index) =>
+          `${index + 1}. [${title}](${url}) | ${snippet}`,
+      )
+      .join("\n");
+  }
+
+  return searchResults
+    .map(([title, snippet]) => `- ${title} | ${snippet}`)
+    .join("\n");
+}
+
+async function getKeywords(text: string, limit?: number) {
+  return (await import("keyword-extractor")).default
+    .extract(text, { language: "english" })
+    .slice(0, limit);
+}
+
+async function startSearch(query: string) {
+  updateSearchState("running");
+
+  let searchResults = await search(
+    query.length > 2000 ? (await getKeywords(query, 20)).join(" ") : query,
+    30,
+  );
+
+  if (searchResults.textResults.length === 0) {
+    const queryKeywords = await getKeywords(query, 10);
+
+    searchResults = await search(queryKeywords.join(" "), 30);
+  }
+
+  updateSearchState(
+    searchResults.textResults.length === 0 ? "failed" : "completed",
+  );
+
+  updateSearchResults(searchResults);
+
+  return searchResults;
+}
+
+async function canStartResponding() {
+  if (getSettings().searchResultsToConsider > 0) {
+    updateTextGenerationState("awaitingSearchResults");
+    await getSearchPromise();
+  }
+}
+
+function updateResponseRateLimited(text: string) {
+  const currentTime = Date.now();
+
+  if (
+    currentTime - updateResponseRateLimited.lastUpdateTime >=
+    updateResponseRateLimited.updateInterval
+  ) {
+    updateResponse(text);
+    updateResponseRateLimited.lastUpdateTime = currentTime;
+  }
+}
+updateResponseRateLimited.lastUpdateTime = 0;
+updateResponseRateLimited.updateInterval = 1000 / 12;
+
+class ChatGenerationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ChatGenerationError";
+  }
+}
+
+async function generateChatWithOpenAI(
+  messages: ChatMessage[],
+  onUpdate: (partialResponse: string) => void,
+) {
+  const settings = getSettings();
+  const openai = getOpenAiClient({
+    baseURL: settings.openAiApiBaseUrl,
+    apiKey: settings.openAiApiKey,
+  });
+  const completion = await openai.chat.completions.create({
+    ...getDefaultChatCompletionCreateParamsStreaming(),
+    model: settings.openAiApiModel,
+    messages: messages as ChatCompletionMessageParam[],
+  });
+
+  let streamedMessage = "";
+
+  for await (const chunk of completion) {
+    const deltaContent = chunk.choices[0].delta.content;
+
+    if (deltaContent) {
+      streamedMessage += deltaContent;
+      onUpdate(streamedMessage);
+    }
+
+    if (getTextGenerationState() === "interrupted") {
+      completion.controller.abort();
+      throw new ChatGenerationError("Chat generation interrupted");
+    }
+  }
+
+  return streamedMessage;
+}
+
+async function generateChatWithInternalApi(
+  messages: ChatMessage[],
+  onUpdate: (partialResponse: string) => void,
+) {
+  const inferenceUrl = new URL("/inference", self.location.origin);
+  const tokenPrefix = "Bearer ";
+  const token = await getSearchTokenHash();
+
+  const response = await fetch(inferenceUrl.toString(), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `${tokenPrefix}${token}`,
+    },
+    body: JSON.stringify({
+      ...getDefaultChatCompletionCreateParamsStreaming(),
+      messages,
+    } as ChatCompletionCreateParamsStreaming),
+  });
+
+  if (!response.ok || !response.body) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let streamedMessage = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value);
+    const lines = chunk.split("\n");
+    const parsedLines = lines
+      .map((line) => line.replace(/^data: /, "").trim())
+      .filter((line) => line !== "" && line !== "[DONE]")
+      .map((line) => JSON.parse(line));
+
+    for (const parsedLine of parsedLines) {
+      const deltaContent = parsedLine.choices[0].delta.content;
+      if (deltaContent) {
+        streamedMessage += deltaContent;
+        onUpdate(streamedMessage);
+      }
+
+      if (getTextGenerationState() === "interrupted") {
+        reader.cancel();
+        throw new ChatGenerationError("Chat generation interrupted");
+      }
+    }
+  }
+
+  return streamedMessage;
+}
+
+async function generateChatWithWebLlm(
+  messages: ChatMessage[],
+  onUpdate: (partialResponse: string) => void,
+) {
+  const { CreateWebWorkerMLCEngine, CreateMLCEngine } = await import(
+    "@mlc-ai/web-llm"
+  );
+
+  type MLCEngineConfig = import("@mlc-ai/web-llm").MLCEngineConfig;
+  type ChatCompletionMessageParam =
+    import("@mlc-ai/web-llm").ChatCompletionMessageParam;
+
+  const selectedModelId = getSettings().webLlmModelId;
+
+  addLogEntry(`Selected WebLLM model for chat: ${selectedModelId}`);
+
+  const engineConfig: MLCEngineConfig = {
+    logLevel: "SILENT",
+  };
+
+  const chatOptions: ChatOptions = {
+    repetition_penalty: defaultSettings.inferenceRepeatPenalty,
+  };
+
+  const engine = Worker
+    ? await CreateWebWorkerMLCEngine(
+        new Worker(new URL("./webLlmWorker.ts", import.meta.url), {
+          type: "module",
+        }),
+        selectedModelId,
+        engineConfig,
+        chatOptions,
+      )
+    : await CreateMLCEngine(selectedModelId, engineConfig, chatOptions);
+
+  const completion = await engine.chat.completions.create({
+    ...getDefaultChatCompletionCreateParamsStreaming(),
+    messages: messages as ChatCompletionMessageParam[],
+  });
+
+  let streamedMessage = "";
+
+  for await (const chunk of completion) {
+    const deltaContent = chunk.choices[0].delta.content;
+
+    if (deltaContent) {
+      streamedMessage += deltaContent;
+      onUpdate(streamedMessage);
+    }
+
+    if (getTextGenerationState() === "interrupted") {
+      await engine.interruptGenerate();
+      throw new ChatGenerationError("Chat generation interrupted");
+    }
+  }
+
+  addLogEntry(
+    `WebLLM finished generating the chat response. Stats: ${await engine.runtimeStatsText()}`,
+  );
+
+  engine.unload();
+
+  return streamedMessage;
+}
+
+async function generateChatWithWllama(
+  messages: ChatMessage[],
+  onUpdate: (partialResponse: string) => void,
+) {
+  const { initializeWllama, wllamaModels } = await import("./wllama");
+
+  const model = wllamaModels[getSettings().wllamaModelId];
+
+  const wllama = await initializeWllama(model.url, {
+    wllama: {
+      suppressNativeLog: true,
+    },
+    model: {
+      n_threads: getSettings().cpuThreads,
+      n_ctx: model.contextSize,
+      cache_type_k: model.cacheType,
+      embeddings: false,
+      allowOffline: true,
+    },
+  });
+
+  const prompt = await model.buildPrompt(
+    wllama,
+    messages[messages.length - 1].content,
+    getFormattedSearchResults(model.shouldIncludeUrlsOnPrompt),
+  );
+
+  let streamedMessage = "";
+
+  await wllama.createCompletion(prompt, {
+    stopTokens: model.stopTokens,
+    sampling: model.sampling,
+    onNewToken: (_token, _piece, currentText, { abortSignal }) => {
+      if (getTextGenerationState() === "interrupted") {
+        abortSignal();
+        throw new ChatGenerationError("Chat generation interrupted");
+      }
+
+      if (model.stopStrings) {
+        for (const stopString of model.stopStrings) {
+          if (
+            currentText.slice(-(stopString.length * 2)).includes(stopString)
+          ) {
+            abortSignal();
+            currentText = currentText.slice(0, -stopString.length);
+            break;
+          }
+        }
+      }
+
+      streamedMessage = currentText;
+      onUpdate(streamedMessage);
+    },
+  });
+
+  await wllama.exit();
+
+  return streamedMessage;
+}
+
+export async function generateChatResponse(
+  newMessages: ChatMessage[],
+  onUpdate: (partialResponse: string) => void,
+) {
+  const settings = getSettings();
+  let response = "";
+
+  try {
+    const allMessages = [
+      {
+        role: "user",
+        content: getSystemPrompt(getFormattedSearchResults(true)),
+      },
+      { role: "assistant", content: "Ok!" },
+      ...newMessages,
+    ];
+
+    const lastMessagesReversed: ChatMessage[] = [];
+
+    let totalTokens = 0;
+
+    for (const message of allMessages.reverse()) {
+      const newTotalTokens =
+        totalTokens + gptTokenizer.encode(message.content).length;
+
+      if (newTotalTokens > 1280) break;
+
+      totalTokens = newTotalTokens;
+      lastMessagesReversed.push(message);
+    }
+
+    const lastMessages = lastMessagesReversed.reverse();
+
+    if (settings.inferenceType === "openai") {
+      response = await generateChatWithOpenAI(lastMessages, onUpdate);
+    } else if (settings.inferenceType === "internal") {
+      response = await generateChatWithInternalApi(lastMessages, onUpdate);
+    } else {
+      if (isWebGPUAvailable && settings.enableWebGpu) {
+        response = await generateChatWithWebLlm(lastMessages, onUpdate);
+      } else {
+        response = await generateChatWithWllama(lastMessages, onUpdate);
+      }
+    }
+  } catch (error) {
+    if (error instanceof ChatGenerationError) {
+      addLogEntry(`Chat generation interrupted: ${error.message}`);
+    } else {
+      addLogEntry(`Error generating chat response: ${error}`);
+    }
+    throw error;
+  }
+
+  return response;
+}
+
+export interface ChatMessage {
+  role: "user" | "assistant" | string;
+  content: string;
+}
+
+function canDownloadModels(): Promise<void> {
+  return new Promise((resolve) => {
+    if (getSettings().allowAiModelDownload) {
+      resolve();
+    } else {
+      updateTextGenerationState("awaitingModelDownloadAllowance");
+      listenToSettingsChanges((settings) => {
+        if (settings.allowAiModelDownload) {
+          resolve();
+        }
+      });
+    }
+  });
+}
+
+function getDefaultChatCompletionCreateParamsStreaming() {
+  return {
+    stream: true,
+    max_tokens: 2048,
+    temperature: defaultSettings.inferenceTemperature,
+    top_p: defaultSettings.inferenceTopP,
+    frequency_penalty: defaultSettings.inferenceFrequencyPenalty,
+    presence_penalty: defaultSettings.inferencePresencePenalty,
+  } as const;
+}