From: Dan Brown <redacted>
Date: Thu, 21 Aug 2025 11:14:52 +0000 (+0100)
Subject: Vectors: Split out vector search and llm query runs
X-Git-Url: http://source.bookstackapp.com/bookstack/commitdiff_plain/refs/pull/5552/head

Vectors: Split out vector search and llm query runs

Added a formal object type to carry across vector search results.
Added permission application and entity combining with vector search
results.
Also updated namespace from vectors to queries.
---

diff --git a/app/Console/Commands/RegenerateVectorsCommand.php b/app/Console/Commands/RegenerateVectorsCommand.php
index 700d05300..26259e943 100644
--- a/app/Console/Commands/RegenerateVectorsCommand.php
+++ b/app/Console/Commands/RegenerateVectorsCommand.php
@@ -4,8 +4,8 @@ namespace BookStack\Console\Commands;
 
 use BookStack\Entities\EntityProvider;
 use BookStack\Entities\Models\Entity;
-use BookStack\Search\Vectors\SearchVector;
-use BookStack\Search\Vectors\StoreEntityVectorsJob;
+use BookStack\Search\Queries\SearchVector;
+use BookStack\Search\Queries\StoreEntityVectorsJob;
 use Illuminate\Console\Command;
 
 class RegenerateVectorsCommand extends Command
diff --git a/app/Search/Vectors/EntityVectorGenerator.php b/app/Search/Queries/EntityVectorGenerator.php
similarity index 95%
rename from app/Search/Vectors/EntityVectorGenerator.php
rename to app/Search/Queries/EntityVectorGenerator.php
index 5f2a7c178..34e37eb03 100644
--- a/app/Search/Vectors/EntityVectorGenerator.php
+++ b/app/Search/Queries/EntityVectorGenerator.php
@@ -1,10 +1,12 @@
 <?php
 
-namespace BookStack\Search\Vectors;
+declare(strict_types=1);
+
+namespace BookStack\Search\Queries;
 
 use BookStack\Activity\Models\Tag;
 use BookStack\Entities\Models\Entity;
-use BookStack\Search\Vectors\Services\VectorQueryService;
+use BookStack\Search\Queries\Services\VectorQueryService;
 use Illuminate\Support\Facades\DB;
 
 class EntityVectorGenerator
diff --git a/app/Search/Queries/LlmQueryRunner.php b/app/Search/Queries/LlmQueryRunner.php
new file mode 100644
index 000000000..cbd1b617c
--- /dev/null
+++ b/app/Search/Queries/LlmQueryRunner.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace BookStack\Search\Queries;
+
+use Exception;
+
+class LlmQueryRunner
+{
+    public function __construct(
+        protected VectorQueryServiceProvider $vectorQueryServiceProvider,
+    ) {
+    }
+
+    /**
+     * Run a query against the configured LLM to produce a text response.
+     * @param VectorSearchResult[] $vectorResults
+     * @throws Exception
+     */
+    public function run(string $query, array $vectorResults): string
+    {
+        $queryService = $this->vectorQueryServiceProvider->get();
+
+        $matchesText = array_values(array_map(fn (VectorSearchResult $result) => $result->matchText, $vectorResults));
+        return $queryService->query($query, $matchesText);
+    }
+}
diff --git a/app/Search/QueryController.php b/app/Search/Queries/QueryController.php
similarity index 71%
rename from app/Search/QueryController.php
rename to app/Search/Queries/QueryController.php
index 895d63f13..95888a88f 100644
--- a/app/Search/QueryController.php
+++ b/app/Search/Queries/QueryController.php
@@ -1,9 +1,10 @@
 <?php
 
-namespace BookStack\Search;
+namespace BookStack\Search\Queries;
 
 use BookStack\Http\Controller;
-use BookStack\Search\Vectors\VectorSearchRunner;
+use BookStack\Search\SearchOptions;
+use BookStack\Search\SearchRunner;
 use Illuminate\Http\Request;
 
 class QueryController extends Controller
@@ -35,19 +36,13 @@ class QueryController extends Controller
     /**
      * Perform a vector/LLM-based query search.
      */
-    public function run(Request $request, VectorSearchRunner $runner)
+    public function run(Request $request, VectorSearchRunner $searchRunner, LlmQueryRunner $llmRunner)
     {
         // TODO - Validate if query system is active
         $query = $request->get('query', '');
 
-        if ($query) {
-            $results = $runner->run($query);
-        } else {
-            $results = null;
-        }
-
-        return view('search.query', [
-            'results' => $results,
-        ]);
+        $results = $query ? $searchRunner->run($query) : [];
+        $llmResult = $llmRunner->run($query, $results);
+        dd($results, $llmResult);
     }
 }
diff --git a/app/Search/Queries/SearchVector.php b/app/Search/Queries/SearchVector.php
new file mode 100644
index 000000000..fcad45da6
--- /dev/null
+++ b/app/Search/Queries/SearchVector.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BookStack\Search\Queries;
+
+use BookStack\Permissions\Models\JointPermission;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * @property string $entity_type
+ * @property int $entity_id
+ * @property string $text
+ * @property string $embedding
+ */
+class SearchVector extends Model
+{
+    public $timestamps = false;
+
+    public function jointPermissions(): HasMany
+    {
+        return $this->hasMany(JointPermission::class, 'entity_id', 'entity_id')
+            ->whereColumn('search_vectors.entity_type', '=', 'joint_permissions.entity_type');
+    }
+}
diff --git a/app/Search/Vectors/Services/OpenAiVectorQueryService.php b/app/Search/Queries/Services/OpenAiVectorQueryService.php
similarity index 98%
rename from app/Search/Vectors/Services/OpenAiVectorQueryService.php
rename to app/Search/Queries/Services/OpenAiVectorQueryService.php
index fea4d5c14..9bd9080ba 100644
--- a/app/Search/Vectors/Services/OpenAiVectorQueryService.php
+++ b/app/Search/Queries/Services/OpenAiVectorQueryService.php
@@ -1,6 +1,6 @@
 <?php
 
-namespace BookStack\Search\Vectors\Services;
+namespace BookStack\Search\Queries\Services;
 
 use BookStack\Http\HttpRequestService;
 
diff --git a/app/Search/Vectors/Services/VectorQueryService.php b/app/Search/Queries/Services/VectorQueryService.php
similarity index 91%
rename from app/Search/Vectors/Services/VectorQueryService.php
rename to app/Search/Queries/Services/VectorQueryService.php
index 746f95f5b..114669474 100644
--- a/app/Search/Vectors/Services/VectorQueryService.php
+++ b/app/Search/Queries/Services/VectorQueryService.php
@@ -1,6 +1,6 @@
 <?php
 
-namespace BookStack\Search\Vectors\Services;
+namespace BookStack\Search\Queries\Services;
 
 interface VectorQueryService
 {
diff --git a/app/Search/Vectors/StoreEntityVectorsJob.php b/app/Search/Queries/StoreEntityVectorsJob.php
similarity index 89%
rename from app/Search/Vectors/StoreEntityVectorsJob.php
rename to app/Search/Queries/StoreEntityVectorsJob.php
index e96fc345a..a410184d7 100644
--- a/app/Search/Vectors/StoreEntityVectorsJob.php
+++ b/app/Search/Queries/StoreEntityVectorsJob.php
@@ -1,6 +1,8 @@
 <?php
 
-namespace BookStack\Search\Vectors;
+declare(strict_types=1);
+
+namespace BookStack\Search\Queries;
 
 use BookStack\Entities\Models\Entity;
 use Illuminate\Contracts\Queue\ShouldQueue;
diff --git a/app/Search/Vectors/TextChunker.php b/app/Search/Queries/TextChunker.php
similarity index 97%
rename from app/Search/Vectors/TextChunker.php
rename to app/Search/Queries/TextChunker.php
index 3ddf1ad4a..73350664c 100644
--- a/app/Search/Vectors/TextChunker.php
+++ b/app/Search/Queries/TextChunker.php
@@ -1,6 +1,8 @@
 <?php
 
-namespace BookStack\Search\Vectors;
+declare(strict_types=1);
+
+namespace BookStack\Search\Queries;
 
 use InvalidArgumentException;
 
diff --git a/app/Search/Vectors/VectorQueryServiceProvider.php b/app/Search/Queries/VectorQueryServiceProvider.php
similarity index 79%
rename from app/Search/Vectors/VectorQueryServiceProvider.php
rename to app/Search/Queries/VectorQueryServiceProvider.php
index eae7149d0..e9bd460eb 100644
--- a/app/Search/Vectors/VectorQueryServiceProvider.php
+++ b/app/Search/Queries/VectorQueryServiceProvider.php
@@ -1,10 +1,12 @@
 <?php
 
-namespace BookStack\Search\Vectors;
+declare(strict_types=1);
+
+namespace BookStack\Search\Queries;
 
 use BookStack\Http\HttpRequestService;
-use BookStack\Search\Vectors\Services\OpenAiVectorQueryService;
-use BookStack\Search\Vectors\Services\VectorQueryService;
+use BookStack\Search\Queries\Services\OpenAiVectorQueryService;
+use BookStack\Search\Queries\Services\VectorQueryService;
 
 class VectorQueryServiceProvider
 {
diff --git a/app/Search/Queries/VectorSearchResult.php b/app/Search/Queries/VectorSearchResult.php
new file mode 100644
index 000000000..b4c27bf9d
--- /dev/null
+++ b/app/Search/Queries/VectorSearchResult.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BookStack\Search\Queries;
+
+use BookStack\Entities\Models\Entity;
+
+readonly class VectorSearchResult
+{
+    public function __construct(
+        public Entity $entity,
+        public float $distance,
+        public string $matchText
+    ) {
+    }
+}
diff --git a/app/Search/Queries/VectorSearchRunner.php b/app/Search/Queries/VectorSearchRunner.php
new file mode 100644
index 000000000..aa9ab7994
--- /dev/null
+++ b/app/Search/Queries/VectorSearchRunner.php
@@ -0,0 +1,54 @@
+<?php
+
+namespace BookStack\Search\Queries;
+
+use BookStack\Entities\Tools\MixedEntityListLoader;
+use BookStack\Permissions\PermissionApplicator;
+use Exception;
+
+class VectorSearchRunner
+{
+    public function __construct(
+        protected VectorQueryServiceProvider $vectorQueryServiceProvider,
+        protected PermissionApplicator $permissions,
+        protected MixedEntityListLoader $entityLoader,
+    ) {
+    }
+
+    /**
+     * Run a vector search query to find results across entities.
+     * @return VectorSearchResult[]
+     * @throws Exception
+     */
+    public function run(string $query): array
+    {
+        $queryService = $this->vectorQueryServiceProvider->get();
+        $queryVector = $queryService->generateEmbeddings($query);
+
+        // TODO - Test permissions applied
+        $topMatchesQuery = SearchVector::query()->select('text', 'entity_type', 'entity_id')
+            ->selectRaw('VEC_DISTANCE_COSINE(VEC_FROMTEXT("[' . implode(',', $queryVector) . ']"), embedding) as distance')
+            ->orderBy('distance', 'asc')
+            ->having('distance', '<', 0.6)
+            ->limit(10);
+
+        $query = $this->permissions->restrictEntityRelationQuery($topMatchesQuery, 'search_vectors', 'entity_id', 'entity_type');
+        $topMatches = $query->get();
+
+        $this->entityLoader->loadIntoRelations($topMatches->all(), 'entity', true);
+
+        $results = [];
+
+        foreach ($topMatches as $match) {
+            if ($match->relationLoaded('entity')) {
+                $results[] = new VectorSearchResult(
+                    $match->getRelation('entity'),
+                    $match->getAttribute('distance'),
+                    $match->getAttribute('text'),
+                );
+            }
+        }
+
+        return $results;
+    }
+}
diff --git a/app/Search/SearchController.php b/app/Search/SearchController.php
index 6ae54b393..9050f65f5 100644
--- a/app/Search/SearchController.php
+++ b/app/Search/SearchController.php
@@ -6,7 +6,7 @@ use BookStack\Entities\Queries\PageQueries;
 use BookStack\Entities\Queries\QueryPopular;
 use BookStack\Entities\Tools\SiblingFetcher;
 use BookStack\Http\Controller;
-use BookStack\Search\Vectors\VectorSearchRunner;
+use BookStack\Search\Queries\VectorSearchRunner;
 use Illuminate\Http\Request;
 
 class SearchController extends Controller
diff --git a/app/Search/SearchIndex.php b/app/Search/SearchIndex.php
index 569fddc73..aaee97fe7 100644
--- a/app/Search/SearchIndex.php
+++ b/app/Search/SearchIndex.php
@@ -6,8 +6,8 @@ use BookStack\Activity\Models\Tag;
 use BookStack\Entities\EntityProvider;
 use BookStack\Entities\Models\Entity;
 use BookStack\Entities\Models\Page;
-use BookStack\Search\Vectors\StoreEntityVectorsJob;
-use BookStack\Search\Vectors\VectorQueryServiceProvider;
+use BookStack\Search\Queries\StoreEntityVectorsJob;
+use BookStack\Search\Queries\VectorQueryServiceProvider;
 use BookStack\Util\HtmlDocument;
 use DOMNode;
 use Illuminate\Database\Eloquent\Builder;
diff --git a/app/Search/Vectors/SearchVector.php b/app/Search/Vectors/SearchVector.php
deleted file mode 100644
index 4a5555f87..000000000
--- a/app/Search/Vectors/SearchVector.php
+++ /dev/null
@@ -1,16 +0,0 @@
-<?php
-
-namespace BookStack\Search\Vectors;
-
-use Illuminate\Database\Eloquent\Model;
-
-/**
- * @property string $entity_type
- * @property int $entity_id
- * @property string $text
- * @property string $embedding
- */
-class SearchVector extends Model
-{
-    public $timestamps = false;
-}
diff --git a/app/Search/Vectors/VectorSearchRunner.php b/app/Search/Vectors/VectorSearchRunner.php
deleted file mode 100644
index 53b1a4bd6..000000000
--- a/app/Search/Vectors/VectorSearchRunner.php
+++ /dev/null
@@ -1,34 +0,0 @@
-<?php
-
-namespace BookStack\Search\Vectors;
-
-class VectorSearchRunner
-{
-    public function __construct(
-        protected VectorQueryServiceProvider $vectorQueryServiceProvider
-    ) {
-    }
-
-    public function run(string $query): array
-    {
-        $queryService = $this->vectorQueryServiceProvider->get();
-        $queryVector = $queryService->generateEmbeddings($query);
-
-        // TODO - Apply permissions
-        // TODO - Join models
-        $topMatches = SearchVector::query()->select('text', 'entity_type', 'entity_id')
-            ->selectRaw('VEC_DISTANCE_COSINE(VEC_FROMTEXT("[' . implode(',', $queryVector) . ']"), embedding) as distance')
-            ->orderBy('distance', 'asc')
-            ->having('distance', '<', 0.6)
-            ->limit(10)
-            ->get();
-
-        $matchesText = array_values(array_map(fn (SearchVector $match) => $match->text, $topMatches->all()));
-        $llmResult = $queryService->query($query, $matchesText);
-
-        return [
-            'llm_result' => $llmResult,
-            'entity_matches' => $topMatches->toArray()
-        ];
-    }
-}
diff --git a/routes/web.php b/routes/web.php
index 9982c044a..d27855100 100644
--- a/routes/web.php
+++ b/routes/web.php
@@ -11,7 +11,7 @@ use BookStack\Exports\Controllers as ExportControllers;
 use BookStack\Http\Middleware\VerifyCsrfToken;
 use BookStack\Permissions\PermissionsController;
 use BookStack\References\ReferenceController;
-use BookStack\Search\QueryController;
+use BookStack\Search\Queries\QueryController;
 use BookStack\Search\SearchController;
 use BookStack\Settings as SettingControllers;
 use BookStack\Sorting as SortingControllers;
@@ -199,6 +199,7 @@ Route::middleware('auth')->group(function () {
 
     // Queries
     Route::get('/query', [QueryController::class, 'show']);
+    Route::get('/query/run', [QueryController::class, 'run']); // TODO - Development only, remove
     Route::post('/query', [QueryController::class, 'run']);
 
     // User Search
diff --git a/tests/Search/TextChunkerTest.php b/tests/Search/TextChunkerTest.php
index f78bf11a4..c742c4a64 100644
--- a/tests/Search/TextChunkerTest.php
+++ b/tests/Search/TextChunkerTest.php
@@ -2,7 +2,7 @@
 
 namespace Search;
 
-use BookStack\Search\Vectors\TextChunker;
+use BookStack\Search\Queries\TextChunker;
 use Tests\TestCase;
 
 class TextChunkerTest extends TestCase