pi-codeindex

Indice semantico locale del codice per l'agente pi: embedding con EmbeddingGemma 2 (ONNX, servizio locale condiviso) e ricerca ibrida (coseno + lessico) che restituisce path:righe + simbolo + anteprima. Una sola copia del modello fra processi pi/CLI sullo stesso endpoint; nessun servizio remoto o database. Indice: due file in ~/.cache/pi-codeindex/<sha1(repo)>/.

Default dalla versione 1.1.1: porta locale 43127; integrazione pi spenta nei progetti mai abilitati. /codeindex enable salva il consenso per progetto, mentre il modello resta condiviso fra i progetti attivi.

Requisiti

• Node 22+ (testato su 26.5.1).
• CPU sempre disponibile come profilo base nelle build native supportate.
• GPU opzionale: CUDA su Linux x64, WebGPU dove incluso nel binding, DirectML su Windows, CoreML su macOS. Non tutte le combinazioni modello, driver e hardware sono verificate: vedi la matrice sotto.

Installazione

Da npm, solo su richiesta

pi -e npm:@alucard_24/pi-codeindex@1.1.1

Carica il pacchetto per questa invocazione, senza aggiungerlo alle impostazioni globali di pi. Dalla sessione puoi usare /codeindex configure e /codeindex doctor. I pesi vengono scaricati solo al primo utilizzo del modello; CUDA e Vulkan richiedono i setup opzionali descritti sotto.

Il pacchetto npm include codice, setup, schema, README, licenza e query di esempio. Il repository GitHub resta privato; piano di lavoro, report completi, harness sperimentale e test non sono inclusi nel tarball npm.

Dal sorgente (sviluppo)

npm install
npm run setup-gpu     # solo GPU NVIDIA: scarica il provider CUDA e lo configura

setup-gpu.sh è solo Linux x64 e richiede CUDA 13 + patchelf. Va rieseguito se un aggiornamento/reinstallazione sostituisce il provider. DirectML, CoreML e WebGPU usano i provider inclusi nel binding nativo; non richiedono questo script CUDA.

Il pacchetto espone anche il binario pi-codeindex: gli esempi node src/cli.js ... possono essere eseguiti come pi-codeindex ... quando il binario è sul PATH. pi-codeindex setup-gpu avvia il setup CUDA. Nessun postinstall scarica i pesi e nessuna configurazione globale di pi viene modificata dal pacchetto.

Embedding e backend

Il modello EmbeddingGemma 2 gira in un servizio locale condiviso avviato automaticamente al primo utilizzo, anche dall'indicizzazione automatica. I client pi/CLI non caricano una pipeline propria. I soli pesi testo vengono scaricati e riutilizzati fra repository; dopo il primo download è possibile lavorare offline. Il codice da embeddare viaggia solo sul loopback locale, non viene inviato al server dei pesi o a un'API di embedding remota.

Vulkan è selezionabile come backend nativo di WebGPU, non come provider ONNX autonomo: usa device: "webgpu" + webgpuBackend: "vulkan" dopo il setup opzionale sotto. device: "vulkan" resta un errore esplicativo. Con webgpuBackend: "auto" decide Dawn: non si garantisce Vulkan e non lo si presenta come forzato. Stato e metadati distinguono webgpu→vulkan/fp16 da webgpu→auto/fp16. Un provider presente nel binding non garantisce compatibilità, velocità, utilizzo della GPU dedicata o copertura totale del grafo: ORT può eseguire alcuni operatori su CPU. Gli smoke test non sostituiscono un benchmark di retrieval/performance per piattaforma. q4 è disponibile ma il drift non è validato sull'eval.

Auto: Linux prova CUDA → WebGPU → CPU; Windows DirectML → WebGPU → CPU; macOS CoreML → WebGPU → CPU. I provider assenti vengono saltati; una prova del modello reale deve riuscire prima che il profilo venga fissato. Tentativi e fallback sono visibili nei log e nello stato/avvisi dell'estensione. Un device forzato fallisce per default; fallback: "cpu" autorizza il ripiego. Il fallback avviene solo all'inizializzazione, mai durante l'embedding di un indice già iniziato. La prima riconciliazione di un processo inizializza il modello anche se l'indice era caldo; i vecchi tempi di re-index sotto indicati precedono questo cambiamento.

WebGPU con Vulkan forzato (opzionale, Linux x64)

npm run setup-vulkan
CODEINDEX_OFFLINE=true node src/cli.js doctor --probe --device webgpu --webgpu-backend vulkan
CODEINDEX_DEVICE=webgpu CODEINDEX_WEBGPU_BACKEND=vulkan pi -e ./src/extension.js

Il setup richiede compilatore C++17, header Node/N-API, tar, patchelf e rete per scaricare i piccoli sorgenti del binding. Non compila ORT/Dawn e non richiede CUDA o il Vulkan SDK: riusa il runtime precompilato con WebGPU; per eseguire serve il driver Vulkan. Header fuori dai percorsi standard: npm run setup-vulkan -- --node-headers /percorso/include/node.

Il binding Node standard 1.30.0 non espone il selettore Dawn. Il setup compila un binding opzionale da un commit ORT fissato e con hash dei sorgenti verificati. Binding e copia del runtime (con SONAME distinto) restano in ~/.cache/pi-codeindex/native/: nessuna modifica a node_modules, nessun provider standard sostituito. Il backend aggiunto ha nome unico e priorità negativa: viene usato solo da una sessione che lo richiede esplicitamente. Prima del caricamento si verificano gli hash; un controllo negativo obbligatorio rifiuta i binding che ignorano il selettore. Manca il setup, il runtime è cambiato o non esiste un adapter Vulkan? Errore, non WebGPU automatico nascosto. Il fallback CPU resta solo quello già autorizzato da fallback: "cpu".

Il setup è idempotente; dopo un cambio di runtime può essere necessario rieseguirlo. pi-codeindex setup-vulkan è equivalente. Riavvia pi dopo setup o cambi di profilo. Il backend WebGPU entra nell'identità dell'indice: cambiare auto ↔ vulkan richiede re-index. Con device: "auto" il selettore riguarda solo l'eventuale tentativo WebGPU: CUDA può ancora essere scelto prima.

Windows richiederebbe anche una build ORT/Dawn con Vulkan abilitato: non implementata/verificata da questo setup. AMD e Intel richiedono prove sulle rispettive GPU. Nessuna promessa di vantaggio prestazionale rispetto a CUDA. Le prove con il modello completo richiedono VRAM libera; il processo doctor riporta l'errore e non termina applicazioni GPU altrui per liberarla.

Test opzionali reali, dopo setup e download dei pesi fp16: CODEINDEX_TEST_VULKAN=1 node --test test/vulkan-integration.test.js. La suite normale non richiede GPU né compila addon. Verificati su questa macchina Linux x64 / RTX 5070 Ti: EmbeddingGemma fp16, indice incrementale, ricerca su fixture e coesistenza con i provider standard. Queste prove non sostituiscono un benchmark di qualità o prestazioni su altri hardware.

Servizio condiviso e memoria

Il primo client sceglie il profilo secondo la configurazione; gli altri riutilizzano la stessa pipeline se quel profilo è consentito. Un profilo incompatibile, una cache pesi diversa o valori diversi di cpuThreads o serviceIdleMs danno errore: nessun secondo modello e nessun fallback in-process. Un device forzato può riutilizzare un servizio CPU solo con fallback: cpu, con avviso esplicito. Le richieste sono serializzate, con massimo 16 richieste attive/in coda; ogni batch contiene al massimo 128 testi e 2 MiB di testo. La saturazione della coda produce un errore, non un altro worker. Un crash interrompe la richiesta corrente; un uso successivo può riavviare il servizio, verificando il profilo già fissato dal client.

Dopo 5 minuti senza operazioni sul modello il processo termina e l'OS libera RAM/VRAM native. status non rinnova il timer. Chiudere/disabilitare una singola sessione non arresta un modello che può servire altri processi. Per liberarlo subito, quando non ci sono inferenze in corso:

/codeindex service status
/codeindex service status --json
/codeindex service stop

Gli stessi comandi funzionano come node src/cli.js service status|stop. Stop viene rifiutato se ci sono richieste attive/in coda; non interrompe altri client. Il servizio si riavvierà al prossimo utilizzo del modello. Nessun avvio al login, servizio di sistema o modifica alle impostazioni globali di pi.

Il listener è solo 127.0.0.1, sulla porta predefinita 43127, con autenticazione tramite token in ~/.cache/pi-codeindex/service/ (directory 0700, record 0600 su POSIX). Il binding esclusivo della porta impedisce due avvii simultanei sullo stesso endpoint. Nessuna porta è garantita su tutte le macchine: se occupata o esclusa dal sistema, scegli una porta libera con /codeindex config set servicePort NUMERO e riavvia pi. Su Windows netsh interface ipv4 show excludedportrange protocol=tcp mostra gli intervalli esclusi; non cancellare le prenotazioni del sistema.

Usa gli stessi serviceDir/servicePort in tutti i client per condividere il modello. Arresta il vecchio servizio inattivo prima di cambiare porta (/codeindex service stop con la configurazione precedente), poi chiudi e riapri i client. Questo vale anche per il passaggio dalla porta automatica della 1.1.0 al nuovo default: un vecchio record può riferirsi alla porta precedente. Gli override già salvati non vengono sovrascritti; servicePort: 0 mantiene esplicitamente la scelta deterministica precedente. Directory diverse e porte diverse permettono deliberatamente più modelli; una stessa directory non va usata contemporaneamente con porte diverse. Non condividere il token o la directory.

Restano per-processo le cache degli indici, dei vettori e dei grafi: il servizio elimina le copie del modello, non tutta la memoria di pi. Dopo l'aggiornamento chiudi e riapri i vecchi processi pi: i modelli già caricati dal vecchio codice in-process non possono essere liberati dal nuovo servizio.

Verifica reale opt-in, con pesi già in cache (offline), due processi client, indice/ricerca e uscita idle:

CODEINDEX_TEST_SERVICE=1 CODEINDEX_DEVICE=cuda node --test test/service-integration.test.js
# Oppure cpu/q8, oppure WebGPU con CODEINDEX_WEBGPU_BACKEND=vulkan dopo setup-vulkan.

Questi test non sono un nuovo benchmark Fase 5–7. La piattaforma iniziale di verifica del servizio è Linux x64; Windows/DirectML e macOS/CoreML richiedono verifica sulle rispettive macchine.

Configurazione

Dentro pi:

/codeindex configure                     menu interattivo + conferma salvataggio
/codeindex config                        valori effettivi, provenienza e percorso
/codeindex config set device webgpu
/codeindex config set dtype fp16
/codeindex config set webgpuBackend vulkan  solo WebGPU, setup-vulkan richiesto
/codeindex config set fallback cpu
/codeindex config unset device           ripristina la scelta automatica
/codeindex service status                processo condiviso, profilo e memoria
/codeindex service stop                  rilascia il modello quando inattivo
/codeindex doctor                        inventario, senza inferenza/download
/codeindex doctor --probe --device webgpu prova reale isolata (può scaricare i pesi)

La configurazione è della macchina, non della sessione pi: $XDG_CONFIG_HOME/pi-codeindex/config.json oppure ~/.config/pi-codeindex/config.json (%APPDATA%/pi-codeindex/config.json su Windows). CODEINDEX_CONFIG=/percorso/config.json sceglie un file diverso, anche per un singolo progetto; nessun file del repository viene letto implicitamente. Non vengono modificate le impostazioni di pi. Precedenza: default < file < ambiente. Il menu salva solo i campi cambiati, non gli override d'ambiente. JSON malformato/chiavi sconosciute producono errori, non default silenziosi. Schema per editor: config.schema.json.

{
  "device": "auto",
  "dtype": "auto",
  "fallback": "error",
  "offline": false,
  "cpuThreads": 0
}

Riavvia pi con un nuovo processo dopo una modifica: non si cambia pipeline nel mezzo di un run. Se il servizio ha già un profilo/configurazione diversi, usa anche service stop quando inattivo, oppure attendi l'uscita idle. Prima di aggiornare a un protocollo incompatibile, arresta il vecchio servizio. Il menu non riavvia né reindicizza da solo. Device, dtype e backend WebGPU effettivi sono salvati nell'indice; se diversi, la ricerca rifiuta di mescolare i vettori e chiede un re-index. Gli indici precedenti senza device vengono ricostruiti alla prossima indicizzazione.

Da shell, senza avviare pi:

node src/cli.js config show
node src/cli.js config set device cpu
node src/cli.js config set cpuThreads 4
node src/cli.js doctor --probe --device cpu --json
node src/cli.js doctor --probe --all       # prove sequenziali dei provider presenti
node src/cli.js doctor --probe --device webgpu --webgpu-backend vulkan
CODEINDEX_DEVICE=cuda CODEINDEX_DTYPE=fp16 pi -e ./src/extension.js

doctor senza --probe non carica/scarica il modello. Le prove reali girano in subprocessi isolati con timeout di 120 s per backend; --all può scaricare più varianti. Ogni provider forzato viene provato senza fallback, per non attribuire alla GPU un successo ottenuto in CPU. Usa offline: true per provarle solo dalla cache. Un crash nativo di una prova non abbatte pi. I probe restano esplicitamente isolati e possono caricare una copia aggiuntiva del modello mentre il servizio è attivo: arresta prima il servizio se vuoi evitare questo picco. Anche la pipeline ordinaria è ora isolata, nel worker condiviso. Smoke del menu e dei comandi via RPC, senza chiamate LLM e con cache modello temporanea/offline: CODEINDEX_TEST_RPC=1 node --test test/config-rpc.test.js (richiede pi sul PATH; usa un file config temporaneo, non modifica quello utente).

Comandi

node src/cli.js index   [--root DIR] [--max-files 5000] [--max-bytes 200] [--force]
node src/cli.js status  [--root DIR]
node src/cli.js search  "query" [--k 8] [--path-prefix src/] [--stale] [--bundle] [--json]
node src/cli.js eval    [--file eval/queries.jsonl] [--json]
node src/cli.js embed-test

• index è incrementale: confronta l'hash di ogni file e riusa i vettori dei chunk invariati. Salvataggio atomico; una cache di ripresa evita di ricalcolare tutto se il run viene interrotto.
• search legge il codice dal disco solo per i risultati finali e non esce mai dal repo.
• eval misura recall@3/@8 e latenza sulle query della fixture.

Attivazione per progetto

Il caricamento dell'estensione non abilita automaticamente un progetto. Prima del consenso non vengono avviati modello, download, indicizzazione, watcher o caricamento automatico dell'indice. Configurazione, stato e doctor restano disponibili; doctor --probe richiede esplicitamente il modello.

/codeindex enable    # abilita solo il progetto corrente, anche per le sessioni future
/codeindex disable   # disabilita solo quel progetto, senza fermare il modello condiviso
/codeindex status    # mostra radice, stato e percorso del file di attivazione

La scelta è salvata fuori dai sorgenti, in projects/<sha256(radice canonica)>.json accanto al file restituito da /codeindex config path (normalmente ~/.config/pi-codeindex/projects/, oppure %APPDATA%\\pi-codeindex\\projects\\ su Windows). Non viene aggiunto un flag globale di attivazione alla configurazione di pi o al profilo embedding. Symlink e differenze di maiuscole su Windows non creano consensi separati per lo stesso percorso canonico.

Nei repository Git la scelta vale per l'intera radice Git, anche dalle sottocartelle. Senza Git vale per la cartella di avvio. Gli altri client dello stesso progetto rileggono la scelta al prompt, alle richieste di stato/reindex e prima di indicizzare; i progetti diversi mantengono il proprio stato.

I vecchi flag nel branch della sessione non abilitano implicitamente un progetto: dopo l'aggiornamento usa /codeindex enable una volta per progetto. Stato corrotto o illeggibile significa spento con avviso, non consenso implicito. /codeindex reindex a progetto spento invita prima ad abilitarlo; i comandi CLI espliciti di indice/ricerca non cambiano il consenso dell'integrazione pi.

Uso dentro pi

# pacchetto npm: solo questa invocazione, nessuna configurazione globale
pi -e npm:@alucard_24/pi-codeindex@1.1.1

# in sviluppo, dalla directory del progetto
pi -e ./src/extension.js

Cosa aggiunge:

• search_code — ricerca semantica (query, k 1–30, path_prefix, context) che restituisce path:start-end, simbolo e anteprima. Non sostituisce grep.
  • i risultati il cui file è cambiato dopo l'indicizzazione sono marcati STALE (hash su disco, non fiducia nel watcher);
  • context: "bundle" aggiunge import, importatori e fino a 5 chiamanti euristici dei primi 3 risultati: un round-trip invece di una catena grep+read.
• outline su read — se leggi un file > 300 righe con ≥ 5 simboli indicizzati e senza offset/limit mirati, ricevi un blocco [outline from code index] con i simboli e i loro range (max 40, ~3,5% di caratteri in più).
• riga di stato nel footer (codeindex: 5.2k chunk, codeindex: 1.2k/4.8k durante l'indicizzazione).
• /codeindex status|reindex [--force]|enable|disable|config|configure|doctor. disable spegne tutto: tool, outline, riga di stato, riga nel system prompt, watcher e indicizzazione in corso. Lo stato è persistito per progetto, non nel branch della sessione e non globalmente. Disabilitare libera anche le cache dell'indice e del grafo di quel client, senza fermare il servizio condiviso.
• indicizzazione automatica solo nei progetti già abilitati, in background, single-flight, interrompibile, con cap 5.000 file / 200 MB.
• sincronizzazione: watcher ricorsivo con debounce 800 ms, invalidazione diretta da write/edit e controllo dopo bash: sweep git status nei repository, riconciliazione incrementale nelle cartelle senza Git. Una riconciliazione riusa i vettori dei file intatti (misurato nei repository: 1 chunk re-embedded su 3 dopo una modifica, 920 ms fino all'indice aggiornato).

Se il modello non è scaricabile o il reindex fallisce, search_code risponde con lo stato reale e la sessione continua.

Cartelle senza Git

Git è opzionale. Nei repository la radice resta quella restituita da Git, anche avviando pi da una sottocartella. Altrimenti viene usata esattamente la directory da cui avvii pi: non viene creato .git, non servono commit né un remote. /codeindex status mostra radice e modalità.

In modalità cartella la scansione esclude le directory nascoste e le consuete directory di dipendenze/output (node_modules, dist, build, out, vendor, target, coverage, venv, __pycache__); non segue i symlink. Restano i limiti di estensione, dimensione, 5.000 file e 200 MB. Le esclusioni sono quelle fisse della scansione locale: senza Git i file .gitignore non vengono interpretati. Nei repository continua a valere git ls-files con le esclusioni Git.

Il watcher gestisce anche rename/cancellazioni di directory; dopo bash viene accodata una riconciliazione senza ricalcolare i vettori invariati. Se il watcher non è disponibile, la riconciliazione viene accodata anche all'inizio di un nuovo prompt. /codeindex reindex resta disponibile per aggiornare manualmente l'indice; --force ricalcola tutti i vettori.

Per evitare scansioni involontarie dell'intera macchina, nella home e nella radice del disco, se non sono repository Git, l'indice parte spento. Avvia pi dalla cartella del progetto oppure abilitalo esplicitamente con /codeindex enable; nelle due cartelle protette il consenso va ripetuto a ogni avvio della sessione. Nessuna nuova configurazione globale è necessaria.

Cosa indicizza

JS/TS/TSX/JSX, Python, Go, Rust, C, C++, C#, PowerBuilder (.srw/.sru/…), Markdown. Chunk declaration-aware, con fusione dei chunk piccoli (Markdown fino a 80 righe; codice solo micro-chunk ≤6 righe). Esclusi: binari, file >1 MB, minified, lockfile, .pbl/.pbt/.pbw.

Numeri misurati (runtime originale in-process, RTX 5070 Ti, fp16)

Queste misure precedono il servizio condiviso e non ne misurano memoria, latenza IPC o prestazioni con client concorrenti.

Su CPU q8 (pi.dev-ext): 18m28s il primo indice, 143 ms il secondo. Ricerca a indice caldo: p50 32 ms. Recall@3 sulla fixture: 5/8.

Dentro pi: cache in-process dell'indice (stat dei due file come chiave), quindi 11,5 ms a caldo su pi.dev-ext e 40 ms su Strata (30k chunk), contro ~1,2 s di caricamento modello alla prima query di un processo nuovo. Outline su un file da 3.713 righe: +3,5% caratteri sulla read.

Misura (giro completo)

I file e i comandi di questa sezione si riferiscono al checkout di sviluppo: piano, report completi e harness non vengono distribuiti nel pacchetto npm. Il riepilogo e i limiti delle misure sono riportati qui senza estenderne lo scope.

RESULTS.md riporta l'esperimento A (pi nudo) vs C (pi + indice) su 10 task per repo × 3 ripetizioni: mediana dei delta −25,4% token su Strata e −9,7% su pi.dev-ext, ma costo totale −12,3% e −12,9%: sotto la soglia del 15% del gate primario. Il verdetto è nel file: gate non superato, progetto fermo per la regola scritta in PLAN.md. Il braccio B (OpenLore) non è stato eseguito: nessun claim comparativo.

La Fase 6 ha ripetuto la misura con un budget di 80 tool call per sessione (RESULTS-FASE6.md): costo −23,2% su Strata e −19,2% su pi.dev-ext, ma successo 27/30 vs 28/30 su Strata. Tutti i fallimenti sono run tagliati dal cap; il criterio pre-registrato C ≥ A non è soddisfatto per una run, quindi quel gate resta non superato.

La Fase 7 (RESULTS-FASE7.md, 80 coppie appaiate per repo, ipotesi più debole pre-registrata prima dei run) supera il gate che chiede solo di non spendere più: costo appaiato −22,1% su Strata (CI unilaterale [−29,3%, −14,1%]) e −21,5% su pi.dev-ext, successo 74/80 vs 74/80 e 79/80 vs 80/80. La soglia del 15% resta non misurata: quello che è dimostrato è "in sessione con budget di 80 tool call il costo non aumenta e il successo non peggiora oltre 10pp".

node scripts/experiment.mjs --repo ~/AI-Projects/Strata --repeat 8 \
  --max-tool-calls 80 --out /tmp/exp5-strata
node scripts/analyze-experiment.mjs --runs /tmp/exp5-strata --runs /tmp/exp5-pidev

Limiti noti

• Il chunker è euristico (regex per famiglia): nessun parser AST, nessun call graph. Gli errori di confine sono possibili e non etichettati.
• I chiamanti del bundle sono euristici (scansione dell'identificatore, non un call graph): su un campione di 61 casi la precisione misurata è 92%. Il livello import è più stretto: solo specifiche che risolvono a un unico file, 29/30 edge senza ambiguità su Strata.
• I documenti di piano Markdown competono con il codice nella ricerca: il cap di 2 risultati per file e il peso maggiore di path/simbolo mitigano, non eliminano il problema.
• Query in italiano su codice con identificatori inglesi funzionano meno bene delle query in inglese.
• Device e dtype fanno parte dell'identità dei vettori: cambiarli richiede un re-index. Lo storage v2 lega manifest e vettori con SHA-256: anche un salvataggio concorrente/incompleto non viene scambiato per un indice valido. Gli indici vecchi senza digest richiedono ricostruzione. La directory è unica per repo: processi con profili diversi possono sostituirla o renderla temporaneamente indisponibile, mai riutilizzare vettori incompatibili.
• DirectML e CoreML richiedono ancora smoke test su Windows/macOS; WebGPU è verificato solo sulla macchina Linux disponibile, non su tutte le GPU.
• I pesi sono ancora scaricati dalla revisione main del modello; il cache non viene aggiornato automaticamente. Prima di un rilascio riproducibile occorre fissare uno snapshot dei pesi e verificarne l'integrità.

Licenza

Il codice di pi-codeindex è distribuito sotto licenza MIT. Dipendenze, sorgenti upstream scaricati dal setup e pesi del modello mantengono le rispettive licenze; non sono inclusi nel tarball del pacchetto.