feat(search): add type inference fallback and cached search index

Add automatic type inference when a type filter returns no matches and

fallback to inferred types or no-type search to surface relevant results.

Build and cache a derived search index to speed suggestions and improve

search quality. Tighten type matching to require exact type equality.

- Add SearchIndex and cache path to CacheManager

- Implement DocService.getSearchIndex(), searchWithFallback(),

  suggestTypes(), getAvailableTypes()

- Update formatSearchResults to display fallback info and suggestions

- Enhance python_docs tool; add suggest_python_doc_types

- Bump package version to 0.2.0

- Update tests and mocks; add tests for search index inference

Author: yriveiro

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-python-docs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenCode plugin for Python documentation lookup via DevDocs",
   "module": "dist/index.js",
   "main": "dist/index.js",

src/cache.ts

@@ -13,6 +13,7 @@ import { dirname, join } from "node:path";
 /** Interface for cache operations, enabling dependency injection in tests. */
 export interface CacheManagerInterface {
   getIndexPath(version: string): string;
+  getSearchIndexPath(version: string): string;
   getDocPath(version: string, docPath: string): string;
   isValid(path: string, ttlMs: number): boolean;
   read<T>(path: string): T | null;
@@ -43,6 +44,10 @@ export function CacheManager(cacheRoot: string): CacheManagerInterface {
       return join(cacheRoot, `python-${version}.json`);
     },
 
+    getSearchIndexPath(version: string): string {
+      return join(cacheRoot, `python-${version}-search-index.json`);
+    },
+
     getDocPath(version: string, docPath: string): string {
       return join(cacheRoot, "docs", version, `${hash(docPath)}.json`);
     },

src/doc-service.ts

@@ -3,6 +3,13 @@ import type { PythonVersion } from "./config";
 import { CONFIG } from "./config";
 import { htmlToMarkdown } from "./html-to-markdown";
 import type { Logger } from "./logger";
+import {
+  createSearchIndex,
+  getAvailableTypes,
+  inferTypesForQuery,
+  type SearchIndex,
+  type TypeInferenceResult,
+} from "./search-index";
 import type { CachedDoc, DocIndex, FetchedDoc } from "./types";
 
 async function fetchWithTimeout(url: string, log: Logger): Promise<string> {
@@ -25,8 +32,22 @@ async function fetchWithTimeout(url: string, log: Logger): Promise<string> {
 /** Service for fetching and searching Python documentation. */
 export interface DocService {
   getIndex(version: PythonVersion): Promise<DocIndex>;
+  getSearchIndex(version: PythonVersion): Promise<SearchIndex>;
   getDoc(version: PythonVersion, path: string): Promise<FetchedDoc>;
   search(index: DocIndex, query: string, type?: string, limit?: number): DocIndex["entries"];
+  searchWithFallback(
+    index: DocIndex,
+    searchIndex: SearchIndex,
+    query: string,
+    type?: string,
+    limit?: number,
+  ): Promise<{
+    results: DocIndex["entries"];
+    fallbackUsed: boolean;
+    typeInference?: TypeInferenceResult;
+  }>;
+  suggestTypes(searchIndex: SearchIndex, query: string): TypeInferenceResult;
+  getAvailableTypes(searchIndex: SearchIndex): string[];
 }
 
 /**
@@ -51,6 +72,32 @@ export function createDocService(cache: CacheManagerInterface, log: Logger): Doc
       return index;
     },
 
+    async getSearchIndex(version: PythonVersion): Promise<SearchIndex> {
+      const searchIndexPath = cache.getSearchIndexPath(version);
+
+      // Check if we have a valid cached search index
+      if (cache.isValid(searchIndexPath, CONFIG.indexTtlMs)) {
+        const cached = cache.read<SearchIndex>(searchIndexPath);
+        if (cached) {
+          await log.info(`Using cached search index for Python ${version}`);
+          return cached;
+        }
+      }
+
+      // Build search index from the main index
+      await log.info(`Building search index for Python ${version}...`);
+      const index = await this.getIndex(version);
+      const searchIndex = createSearchIndex(index, version);
+
+      // Cache the search index
+      cache.write(searchIndexPath, searchIndex);
+      await log.info(
+        `Cached search index with ${searchIndex.keywordMappings.length} keyword mappings`,
+      );
+
+      return searchIndex;
+    },
+
     async getDoc(version: PythonVersion, path: string): Promise<FetchedDoc> {
       const normalizedPath = path.endsWith(".html") ? path.slice(0, -5) : path;
       const docPath = cache.getDocPath(version, normalizedPath);
@@ -89,7 +136,7 @@ export function createDocService(cache: CacheManagerInterface, log: Logger): Doc
         if (results.length >= maxResults) break;
 
         const nameMatch = entry.name.toLowerCase().includes(q);
-        const typeMatch = !t || entry.type.toLowerCase().includes(t);
+        const typeMatch = !t || entry.type.toLowerCase() === t;
 
         if (nameMatch && typeMatch) {
           results.push(entry);
@@ -98,5 +145,71 @@ export function createDocService(cache: CacheManagerInterface, log: Logger): Doc
 
       return results;
     },
+
+    async searchWithFallback(
+      index: DocIndex,
+      searchIndex: SearchIndex,
+      query: string,
+      type?: string,
+      limit?: number,
+    ): Promise<{
+      results: DocIndex["entries"];
+      fallbackUsed: boolean;
+      typeInference?: TypeInferenceResult;
+    }> {
+      // Try the requested search first
+      const results = this.search(index, query, type, limit);
+
+      // If we have results or no type filter, return as-is
+      if (results.length > 0 || !type) {
+        return { results, fallbackUsed: false };
+      }
+
+      // No results with type filter - use type inference to suggest alternatives
+      await log.info(`No results for "${query}" with type "${type}". Running type inference...`);
+
+      const typeInference = inferTypesForQuery(query, searchIndex);
+
+      // Try searching without the type filter
+      const resultsNoFilter = this.search(index, query, undefined, limit);
+
+      // Try searching with the most likely inferred types
+      let resultsWithInferred: DocIndex["entries"] = [];
+      for (const inferredType of typeInference.inferredTypes.slice(0, 2)) {
+        const inferredResults = this.search(
+          index,
+          query,
+          inferredType,
+          Math.ceil((limit ?? CONFIG.defaultLimit) / 2),
+        );
+        resultsWithInferred = resultsWithInferred.concat(inferredResults);
+      }
+
+      // Combine results: prioritize inferred type matches, then no-filter matches
+      const seen = new Set<string>();
+      const combinedResults: DocIndex["entries"] = [];
+
+      for (const entry of resultsWithInferred.concat(resultsNoFilter)) {
+        if (!seen.has(entry.path)) {
+          seen.add(entry.path);
+          combinedResults.push(entry);
+          if (combinedResults.length >= (limit ?? CONFIG.defaultLimit)) break;
+        }
+      }
+
+      return {
+        results: combinedResults,
+        fallbackUsed: true,
+        typeInference,
+      };
+    },
+
+    suggestTypes(searchIndex: SearchIndex, query: string): TypeInferenceResult {
+      return inferTypesForQuery(query, searchIndex);
+    },
+
+    getAvailableTypes(searchIndex: SearchIndex): string[] {
+      return getAvailableTypes(searchIndex);
+    },
   };
 }

src/formatters.ts

@@ -1,24 +1,51 @@
+import type { TypeInferenceResult } from "./search-index";
 import type { AnchorIndex, DocEntry } from "./types";
 
 /**
  * Formats search results into a human-readable string.
  * @param results - Matched documentation entries.
  * @param query - The original search query.
  * @param version - Python version searched.
+ * @param fallbackUsed - Whether type inference fallback was used.
+ * @param typeInference - Type inference result when fallback was used.
  * @returns Formatted string listing results or a no-results message.
  */
-export function formatSearchResults(results: DocEntry[], query: string, version: string): string {
+export function formatSearchResults(
+  results: DocEntry[],
+  query: string,
+  version: string,
+  fallbackUsed?: boolean,
+  typeInference?: TypeInferenceResult,
+): string {
   if (!results.length) {
-    return `No results found for "${query}" in Python ${version} docs.`;
+    let message = `No results found for "${query}" in Python ${version} docs.`;
+    if (typeInference && typeInference.inferredTypes.length > 0) {
+      message += `\n\nSuggested types based on your query:\n`;
+      message += typeInference.inferredTypes.map((t) => `  - ${t}`).join("\n");
+      if (typeInference.alternativeTypes.length > 0) {
+        message += `\n\nAlternative types:\n`;
+        message += typeInference.alternativeTypes.map((t) => `  - ${t}`).join("\n");
+      }
+    }
+    return message;
   }
 
-  return [
+  const lines: string[] = [
     `Found ${results.length} result(s) for "${query}" in Python ${version} docs.`,
-    "",
-    ...results.map((r) => `- ${r.name} [${r.type}] -> ${r.path}`),
-    "",
-    "Use fetch_python_doc with the path to get the full documentation.",
-  ].join("\n");
+  ];
+
+  if (fallbackUsed && typeInference) {
+    lines.push("");
+    lines.push("⚠️ Original search returned no results. Used type inference to find matches.");
+    lines.push(`   Inferred types: ${typeInference.inferredTypes.join(", ")}`);
+  }
+
+  lines.push("");
+  lines.push(...results.map((r) => `- ${r.name} [${r.type}] -> ${r.path}`));
+  lines.push("");
+  lines.push("Use fetch_python_doc with the path to get the full documentation.");
+
+  return lines.join("\n");
 }
 
 /**