plugin-examples/vector-search-plugin/vector-search-plugin.html at main · appdevforall/plugin-examples · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Vector Search Plugin</title>
<style>
  body {
    background: #ffffff;
    color: #000000;
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
    line-height: 1.6;
    margin: 0;
    padding: 1.25rem;
    max-width: 820px;
  }
  h1 { font-size: 1.6rem; margin: 0 0 0.75rem; }
  h2 { font-size: 1.2rem; margin: 1.75rem 0 0.5rem; border-bottom: 1px solid #e0e0e0; padding-bottom: 0.2rem; }
  code {
    background: #f4f4f4;
    padding: 0.1rem 0.3rem;
    border-radius: 3px;
    font-family: "SF Mono", Menlo, Consolas, monospace;
    font-size: 0.9em;
  }
  ul { padding-left: 1.25rem; }
  li { margin: 0.3rem 0; }
  table { border-collapse: collapse; margin: 0.5rem 0; width: 100%; }
  th, td { border: 1px solid #ddd; padding: 0.4rem 0.6rem; text-align: left; vertical-align: top; }
  th { background: #f4f4f4; }
  .note {
    border-left: 3px solid #999;
    padding: 0.25rem 0.75rem;
    margin: 1rem 0;
    background: #fafafa;
  }
</style>
</head>
<body>
  <h1>Vector Search Plugin</h1>

  <h2>Executive overview</h2>
  <p><b>Vector Search</b> adds <b>semantic</b>, meaning-based results to
  CodeOnTheGo's project search. Instead of matching only exact text, it ranks
  code by similarity of meaning, so a search for "read a file into a string" can
  surface the relevant method even when those exact words don't appear.</p>
  <p>It is a <b>headless</b> plugin — it has no screens of its own. It
  contributes an extra <b>"Semantic Results"</b> section to the existing project
  search. Everything runs on-device.</p>

  <h2>Core functionality</h2>
  <ul>
    <li><b>Semantic project search</b> — contributes ranked results via the IDE's
      project-search extension point.</li>
    <li><b>On-device indexing</b> — walks the project (capped, skipping
      <code>build</code>/<code>.git</code> and similar), chunks files by
      language-aware boundaries, and stores embeddings in a local SQLite
      database.</li>
    <li><b>Model embeddings when available</b> — uses AI Core's embedding service
      when present.</li>
    <li><b>Lexical fallback</b> — when AI Core embeddings aren't available, it
      falls back to a local lexical embedding (lower quality, but always works
      offline).</li>
    <li><b>Cosine-similarity ranking</b> with a relevance cutoff so only strong
      matches are returned.</li>
  </ul>

  <h2>Technical architecture</h2>
  <table>
    <tr><th>Component</th><th>Role</th></tr>
    <tr><td><code>VectorSearchPlugin</code></td><td>Entry point. Implements
      <code>ProjectSearchExtension</code>; runs indexing on a background scope and
      answers search requests.</td></tr>
    <tr><td><code>CodeChunker</code></td><td>Splits files into small, language-aware
      chunks with overlap for context.</td></tr>
    <tr><td><code>EmbeddingIndexingService</code></td><td>Collects files and stores
      chunk embeddings as BLOBs in a local SQLite database
      (<code>embeddings.db</code>).</td></tr>
    <tr><td><code>VectorMath</code> / <code>VectorSearchService</code></td><td>Cosine
      similarity and top-K ranking of stored embeddings against the query.</td></tr>
  </table>
  <p>Embeddings are requested from <b>AI Core</b> over the shared service registry
  when available; the plugin contains no model and no native code of its own.</p>

  <h2>Usage</h2>
  <ol>
    <li>(Optional) Install <b>AI Core</b> and select a local model for
      higher-quality embeddings.</li>
    <li>Install <b>Vector Search</b> via the Plugin Manager and restart the
      IDE.</li>
    <li>Use the IDE's <b>project search</b>. Semantic matches appear under a
      <b>"Semantic Results"</b> section. The first search on a project triggers a
      background index build.</li>
  </ol>
  <div class="note">
    <b>Privacy:</b> indexing and search run entirely on-device. File contents are
    chunked and stored in a local SQLite database; nothing leaves the device.
  </div>

  <h2>Key benefits</h2>
  <ul>
    <li><b>Find code by meaning</b> — surfaces relevant code even without an exact
      keyword match.</li>
    <li><b>Fully offline</b> — no network use; embeddings and the index stay on the
      device.</li>
    <li><b>Always usable</b> — degrades gracefully to lexical embeddings when AI
      Core isn't installed.</li>
    <li><b>Lightweight</b> — no bundled model or native libraries; a compact SQLite
      index.</li>
  </ul>
</body>
</html>