Enhance AI Query Script with Commander and Content Type Filtering #7229

Author: tobiu

AGENTS.md

@@ -39,8 +39,10 @@ You must **NEVER** make guesses, assumptions, or "hallucinate" answers about the
 ### The Query Command
 Your most important tool is the local AI knowledge base. To use it, execute the following shell command:
 ```bash
-npm run ai:query -- -q "Your question here"
+npm run ai:query -- -q "Your question here" -t <type>
 ```
+- The `-t` or `--type` flag is optional and allows you to filter results by content type.
+- Supported types are: `all` (default), `blog`, `guide`, `src`, `example`.
 
 ### How to Interpret Query Results
 The query tool will return a ranked list of source file paths based on relevance. The output will look like this:
@@ -69,10 +71,22 @@ When you need to understand a new concept or feature area:
     - `npm run ai:query -- -q "form validation patterns"`
     - `npm run ai:query -- -q "how are stores implemented?"`
 
-#### 2. Implementation Pattern (Query Before Coding)
+#### 2. Targeted Content-Type Searching
+Use the `--type` (`-t`) flag to focus your search on specific types of content. This is a powerful way to get more relevant results.
+
+-   **To find conceptual explanations:**
+    - `npm run ai:query -- -q "state management" -t guide`
+-   **To find concrete usage examples:**
+    - `npm run ai:query -- -q "Button component" -t example`
+-   **To dive deep into implementation details:**
+    - `npm run ai:query -- -q "afterSet hook" -t src`
+
+**Strategy:** If a broad query returns too many source files and not enough conceptual documents, re-run the query with `-t guide`. Conversely, if you have read the guides but need to see the actual implementation, re-run with `-t src`.
+
+#### 3. Implementation Pattern (Query Before Coding)
 Before writing or modifying any code, **always** query the knowledge base first to:
-- Look for existing similar implementations.
-- Understand framework conventions for the task you are performing.
+- Look for existing similar implementations (try `-t src` or `-t example`).
+- Understand framework conventions for the task you are performing (try `-t guide`).
 - Identify common patterns used in the relevant area of the codebase.
 
 ### When Queries Fail to Find Information
@@ -127,4 +141,4 @@ Integrate the query tool into your development process.
 ## 5. Session Maintenance
 Your initialization is a snapshot in time. The codebase can change. If you pull new changes from the repository, you should consider re-running your initialization steps (reading `structure.json`, `Neo.mjs`, and `core/Base.mjs`) to ensure your understanding is up-to-date.
 
-Furthermore, after pulling changes, the local knowledge base may be out of sync. You should run `npm run ai:build-kb` to re-embed the latest changes into the database.
+Furthermore, after pulling changes, the local knowledge base may be out of sync. You should run `npm run ai:build-kb` to re-embed the latest changes into the database.

buildScripts/ai/queryKnowledgeBase.mjs

@@ -1,13 +1,23 @@
 import {ChromaClient}       from 'chromadb';
 import {GoogleGenerativeAI} from '@google/generative-ai';
+import {Command}            from 'commander/esm.mjs';
 import dotenv               from 'dotenv';
 import fs                   from 'fs-extra';
 import path                 from 'path';
-import yargs                from 'yargs';
-import {hideBin}            from 'yargs/helpers';
 
 dotenv.config({quiet: true});
 
+const program = new Command();
+
+program
+    .name('neo-ai-query')
+    .version('1.0.0') // Or from package.json
+    .option('-q, --query <value>', 'The search query for the knowledge base')
+    .option('-t, --type <value>', 'The content type to query for', 'all')
+    .parse(process.argv);
+
+const opts = program.opts();
+
 /**
  * This script is the final stage in the AI knowledge base pipeline: **Query**.
  *
@@ -31,14 +41,15 @@ dotenv.config({quiet: true});
  * @class QueryKnowledgeBase
  */
 class QueryKnowledgeBase {
-    static async run(query) {
+    static async run(query, type) {
         if (!query) {
             console.error('Error: A query string must be provided.');
-            console.log('Usage: npm run ai:query -- --query "your search query"');
+            console.log('Usage: npm run ai:query -- -q "your search query"');
             return;
         }
 
-        console.log(`Querying for: "${query}"...`);
+        console.log(`Querying for: "${query}" (type: ${type})...
+`);
 
         // 1. Connect to ChromaDB and get query results
         const dbClient       = new ChromaClient();
@@ -62,10 +73,29 @@ class QueryKnowledgeBase {
         const queryEmbedding = await model.embedContent(query);
         const results        = await collection.query({
             queryEmbeddings: [queryEmbedding.embedding.values],
-            nResults       : 50
+            nResults       : 100 // Increased to get a wider net for filtering
         });
 
-        // 2. Process results with the enhanced scoring algorithm
+        // 2. Filter results by content type if specified
+        if (type && type !== 'all') {
+            results.metadatas[0] = results.metadatas[0].filter(metadata => {
+                const source = metadata.source || '';
+                switch (type) {
+                    case 'blog':
+                        return source.includes('/learn/blog/');
+                    case 'guide':
+                        return source.includes('/learn/guides/');
+                    case 'src':
+                        return source.includes('/src/');
+                    case 'example':
+                        return source.includes('/examples/');
+                    default:
+                        return true;
+                }
+            });
+        }
+
+        // 3. Process results with the enhanced scoring algorithm
         if (results.metadatas?.length > 0 && results.metadatas[0].length > 0) {
             const sourceScores    = {};
             const queryLower      = query.toLowerCase();
@@ -114,7 +144,7 @@ class QueryKnowledgeBase {
             });
 
             if (Object.keys(sourceScores).length === 0) {
-                console.log('No relevant source files found.');
+                console.log('No relevant source files found for the specified type.');
                 return;
             }
 
@@ -139,20 +169,19 @@ class QueryKnowledgeBase {
             finalSorted.slice(0, 25).forEach(([source, score]) => {
                 console.log(`- ${source} (Score: ${score.toFixed(0)})`);
             });
-            console.log(`\nTop result: ${finalSorted[0][0]}`);
+
+            if (finalSorted.length > 0) {
+                console.log(`\nTop result: ${finalSorted[0][0]}`);
+            } else {
+                console.log('No relevant source files found after scoring.');
+            }
         } else {
-            console.log('No results found for your query.');
+            console.log('No results found for your query and type.');
         }
     }
 }
 
-const argv = yargs(hideBin(process.argv)).option('query', {
-    alias      : 'q',
-    type       : 'string',
-    description: 'The search query for the knowledge base'
-}).argv;
-
-QueryKnowledgeBase.run(argv.query).catch(err => {
+QueryKnowledgeBase.run(opts.query, opts.type).catch(err => {
     console.error(err);
     process.exit(1);
-});
+});