@designerbyron/lifecode-rag 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +220 -2
- package/bin/lifecode-rag.mjs +449 -0
- package/client.js +3515 -0
- package/cordis.patch.yml +3 -0
- package/docs/ARCHITECTURE-v0.2.md +269 -0
- package/docs/AUTO-DISCOVERY.md +111 -0
- package/docs/AUTOMATION-POLICIES.md +232 -0
- package/docs/CONTRATO-v0.1.md +195 -0
- package/docs/EMBEDDING-PROVIDERS.md +105 -0
- package/docs/OBSERVABILITY.md +241 -0
- package/docs/PA-UI-0-API-CONTRACT.md +887 -0
- package/docs/PERFORMANCE-BUDGETS.md +118 -0
- package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
- package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
- package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
- package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
- package/docs/WORKSPACE-API.md +239 -0
- package/icon.svg +7 -0
- package/index.js +198 -0
- package/lib/audit-export.mjs +70 -0
- package/lib/audit.mjs +120 -0
- package/lib/auto-context.mjs +322 -0
- package/lib/automation.mjs +214 -0
- package/lib/chunk.mjs +100 -0
- package/lib/config-resolve.mjs +119 -0
- package/lib/context.mjs +150 -0
- package/lib/conversation-events.mjs +145 -0
- package/lib/db.mjs +309 -0
- package/lib/diagnose.mjs +197 -0
- package/lib/discovery.mjs +402 -0
- package/lib/doctor.mjs +82 -0
- package/lib/embed.mjs +96 -0
- package/lib/embedders.mjs +103 -0
- package/lib/errors.mjs +231 -0
- package/lib/exec-context.mjs +238 -0
- package/lib/extract.mjs +260 -0
- package/lib/harness-workspaces.mjs +85 -0
- package/lib/hash.mjs +34 -0
- package/lib/ingest.mjs +239 -0
- package/lib/inputs.mjs +67 -0
- package/lib/library-state.mjs +252 -0
- package/lib/maintenance.mjs +113 -0
- package/lib/metrics.mjs +164 -0
- package/lib/migrate.mjs +373 -0
- package/lib/operations.mjs +132 -0
- package/lib/pa-api.mjs +946 -0
- package/lib/paths.mjs +345 -0
- package/lib/policy.mjs +125 -0
- package/lib/profile.mjs +128 -0
- package/lib/readmodel.mjs +159 -0
- package/lib/recovery.mjs +557 -0
- package/lib/registry-schema.mjs +206 -0
- package/lib/registry.mjs +606 -0
- package/lib/resolve.mjs +318 -0
- package/lib/retention.mjs +143 -0
- package/lib/revocation.mjs +124 -0
- package/lib/roots-structure.mjs +224 -0
- package/lib/schema.mjs +173 -0
- package/lib/scope-ops.mjs +379 -0
- package/lib/scope-stores.mjs +128 -0
- package/lib/search.mjs +345 -0
- package/lib/selection.mjs +225 -0
- package/lib/server.mjs +340 -0
- package/lib/session-identity.mjs +51 -0
- package/lib/sessions.mjs +343 -0
- package/lib/sync-scheduler.mjs +354 -0
- package/lib/sync.mjs +755 -0
- package/lib/tags.mjs +45 -0
- package/lib/tools.mjs +364 -0
- package/lib/trusted-roots.mjs +149 -0
- package/lib/worker-context.mjs +22 -0
- package/package.json +67 -5
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# LifeCode RAG — Presupuestos de rendimiento
|
|
2
|
+
|
|
3
|
+
**Fecha:** 2026-11-17 · **Estado:** baseline medido + objetivos propuestos
|
|
4
|
+
**Regla:** ningún límite se inventa. Primero se mide el baseline; después se fija el objetivo y se
|
|
5
|
+
verifica con el mismo arnés.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Baseline medido hoy (v0.1.0)
|
|
10
|
+
|
|
11
|
+
> **Actualización v0.2.0:** las mediciones vigentes del motor v0.2 (1k/5k/10k chunks, con pesos RRF 3:1)
|
|
12
|
+
> están en [`eval/m5/INFORME-M5.md`](../../eval/m5/INFORME-M5.md) §2. La tabla siguiente se conserva como
|
|
13
|
+
> baseline histórico del banco de 42 consultas; no describe el motor actual.
|
|
14
|
+
|
|
15
|
+
Arnés: `node tools/benchmark.mjs` — 40 documentos sintéticos, 40 chunks, y **42 consultas**:
|
|
16
|
+
40 exactas (una por documento), **1 paráfrasis** (`instalar` frente a `instalación` en el corpus) y
|
|
17
|
+
**1 sin acento** (`instalacion`). No son 40 paráfrasis: ese banco no existe todavía y el documento no debe
|
|
18
|
+
sugerir que se midió. Almacén temporal, en este host (Windows 11, Electron 44.7 / Node 24.21).
|
|
19
|
+
|
|
20
|
+
| Medición | FTS5 | Híbrida (FTS+vector+RRF) |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| Recall@5 (40 exactas) | 1.000 | 1.000 |
|
|
23
|
+
| MRR@5 (40 exactas) | 1.000 | 0.988 |
|
|
24
|
+
| Recall@5 (1 paráfrasis) | 0.000 | 0.000 |
|
|
25
|
+
| Recall@5 (1 sin acento) | 1.000 | 1.000 |
|
|
26
|
+
| Latencia media | 0.16 ms | 0.68 ms |
|
|
27
|
+
| Latencia p95 | 0.31 ms | 0.79 ms |
|
|
28
|
+
|
|
29
|
+
Contexto (presupuesto 2000 tokens): 1702 tokens servidos frente a 13 010 del corpus completo,
|
|
30
|
+
**86.9 % de ahorro**, 0/40 truncados. Es una estimación `ceil(chars/4)`, no tokens reales.
|
|
31
|
+
|
|
32
|
+
**Límite honesto:** el corpus es pequeño (40 documentos) y el embedder `local-hash-v1` es léxico. Una sola
|
|
33
|
+
consulta de paráfrasis no estima la calidad semántica: el 0.000 dice «este caso falla», no «el sistema
|
|
34
|
+
falla en paráfrasis». Los presupuestos de §3 son objetivos de v0.2.0, no resultados.
|
|
35
|
+
|
|
36
|
+
### 1.1 Qué es baseline, qué es objetivo y qué exige arnés nuevo
|
|
37
|
+
|
|
38
|
+
| Dato | Origen | Válido para presupuestar |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| Recall/MRR/latencia de §1 | medido en v0.1.0 con 42 consultas | no; solo como referencia |
|
|
41
|
+
| Ahorro 86.9 % | medido en v0.1.0, estimación `ceil(chars/4)` | no; referencia |
|
|
42
|
+
| Umbrales de §3 | **propuesta** v0.2.0 sin medir | no hasta M0 |
|
|
43
|
+
| 120 consultas de `RETRIEVAL-EVALUATION.md` | especificación | no existe todavía |
|
|
44
|
+
| 1k/5k/10k chunks | requiere `tools/bench.mjs` (M0) | no hasta M0 |
|
|
45
|
+
|
|
46
|
+
No se puede inferir de 40 documentos el comportamiento con 10 000 chunks, ni de una paráfrasis la calidad
|
|
47
|
+
semántica. Cualquier tabla futura dirá escala, número de consultas y si el almacén estaba caliente.
|
|
48
|
+
|
|
49
|
+
## 2. Qué falta medir antes de fijar presupuestos
|
|
50
|
+
|
|
51
|
+
| Dimensión | Por qué no se puede presupuestar aún | Cómo se medirá |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| Búsqueda con 10k chunks | solo hay 40 | corpus sintético escalado (1k/5k/10k), mediana de 5 pasadas |
|
|
54
|
+
| Escritura/ingesta | no hay benchmark de ingesta | 200 ficheros, 20 MB, medir p50/p95 y memoria |
|
|
55
|
+
| Arranque del plugin | el host arranca el módulo, no la pestaña | `performance.now()` del host desde `apply` hasta registro |
|
|
56
|
+
| Apertura de pestaña | no hay UI aún | marca en el slot: montaje → primer esqueleto → primer snapshot |
|
|
57
|
+
| Memoria del Workspace | no hay UI | `process.memoryUsage().rss` antes/después de 10 aperturas |
|
|
58
|
+
| CPU en reposo | no hay polling aún | 5 min con pestaña oculta y visible, `os.loadavg` no sirve en Windows → CPU del proceso |
|
|
59
|
+
| Coste en tokens de una respuesta | requiere modelo | contar `context.tokens` + longitud de la respuesta, en benchmark de tarea |
|
|
60
|
+
|
|
61
|
+
## 3. Objetivos propuestos (a verificar en M0/M3; no son promesas)
|
|
62
|
+
|
|
63
|
+
| Superficie | Objetivo | Condición |
|
|
64
|
+
|---|---|---|
|
|
65
|
+
| `GET /snapshot` | p95 ≤ 60 ms | 10 000 chunks, conexión caliente |
|
|
66
|
+
| `GET /sources` | p95 ≤ 40 ms | 10 000 fuentes, página 50 |
|
|
67
|
+
| `POST /retrieval` (híbrida) | p95 ≤ 250 ms | 10 000 chunks, scan vectorial completo |
|
|
68
|
+
| `POST /retrieval` (FTS) | p95 ≤ 60 ms | misma base |
|
|
69
|
+
| Montaje de pestaña | esqueleto ≤ 150 ms | tras primer clic, módulo ya cargado |
|
|
70
|
+
| Primer dato real | ≤ 400 ms | snapshot en caliente |
|
|
71
|
+
| Memoria adicional | ≤ 40 MB RSS | con 6 secciones visitadas |
|
|
72
|
+
| CPU en reposo | ~0 % (sin intervalo cuando oculta) | pestaña oculta 5 min |
|
|
73
|
+
| Refresco visible | ≤ 1 petición / 30 s | ETag evita cuerpo completo |
|
|
74
|
+
|
|
75
|
+
Si un objetivo no se cumple, se documenta el número real y se decide: optimizar, paginar más o degradar
|
|
76
|
+
la función. No se ajusta el objetivo al resultado sin decirlo.
|
|
77
|
+
|
|
78
|
+
## 4. Reglas de diseño que sostienen los presupuestos
|
|
79
|
+
|
|
80
|
+
1. **Una conexión.** El plugin abre SQLite una vez; el read model la reutiliza. En Windows una segunda
|
|
81
|
+
conexión sobre el mismo fichero puede bloquearse (`store-busy`), y abrir/cerrar por petición mata la latencia.
|
|
82
|
+
2. **Agregados, no escaneos.** `metrics_daily` evita calcular series sobre eventos crudos.
|
|
83
|
+
3. **Paginación real en SQL.** `LIMIT/OFFSET` con índices; nunca cargar todo y cortar en JS.
|
|
84
|
+
4. **Texto bajo demanda.** La lista no trae `chunk.text`; el detalle lo pide por chunk.
|
|
85
|
+
5. **Sin trabajo pesado en el hilo de UI.** Agregaciones grandes y exportaciones van al hilo del host;
|
|
86
|
+
el cliente solo pinta lo recibido. Si en M3 una consulta bloquea > 50 ms, se mueve a `worker_threads`
|
|
87
|
+
(disponible en el host, ya probado).
|
|
88
|
+
6. **Sin polling oculto.** El intervalo vive en el panel y se activa solo si
|
|
89
|
+
`usePanelInfo(info => info.activePanelId === 'lifecode-rag')` **y** `document.visibilityState === 'visible'`;
|
|
90
|
+
al cambiar de panel o minimizar, se limpia. `visibilityState` no sustituye la señal de panel activo (§5
|
|
91
|
+
de `WORKSPACE-UX.md`).
|
|
92
|
+
7. **Cancelación.** Toda operación larga acepta `AbortSignal` y se comprueba entre unidades (fichero,
|
|
93
|
+
fuente), nunca a mitad de una transacción.
|
|
94
|
+
8. **Cierre limpio.** Desmontar la pestaña libera intervalos, listeners y gráficos; no deja procesos.
|
|
95
|
+
|
|
96
|
+
## 5. Medición reproducible
|
|
97
|
+
|
|
98
|
+
- `tools/bench.mjs` (nuevo en M0) con modos `--scale 1000|5000|10000`, `--seed`, `--runs 5`, salida JSON
|
|
99
|
+
y markdown; mismo corpus semilla para comparar versiones.
|
|
100
|
+
- Cada informe declara: máquina, versión de Node/Electron, tamaño del corpus, número de pasadas,
|
|
101
|
+
y si el almacén estaba caliente o frío.
|
|
102
|
+
- La UI mide con `performance.mark/measure` y envía un resumen agregado **solo** si la analítica está
|
|
103
|
+
activa; sin texto.
|
|
104
|
+
|
|
105
|
+
## 6. Degradación segura
|
|
106
|
+
|
|
107
|
+
| Situación | Comportamiento |
|
|
108
|
+
|---|---|
|
|
109
|
+
| Almacén bloqueado | `423 store-busy`, reintento único con backoff corto, mensaje claro |
|
|
110
|
+
| Consulta demasiado amplia | `limit` acotado; `partial:true` si se recorta |
|
|
111
|
+
| Vector scan > techo | `truncated:true` en `vectors`, la UI lo muestra |
|
|
112
|
+
| Memoria alta | el Workspace descarta series largas y pide buckets mayores |
|
|
113
|
+
| UI lenta | esqueleto primero; secciones bajo demanda; nunca bloquear el hilo |
|
|
114
|
+
|
|
115
|
+
## 7. Criterio de aceptación de rendimiento
|
|
116
|
+
|
|
117
|
+
Un criterio solo pasa si: (a) existe el número medido en el informe, (b) el arnés es reproducible con el
|
|
118
|
+
comando publicado, (c) la cifra se midió en este host, no en otro. Si no, queda `PARTIAL`.
|