@designerbyron/lifecode-rag 0.0.0-stage → 1.0.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 +191 -2
- package/bin/lifecode-rag.mjs +449 -0
- package/client.js +2801 -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 +802 -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 +227 -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 +517 -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 +406 -0
- package/lib/resolve.mjs +311 -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 +150 -0
- package/lib/server.mjs +335 -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,195 @@
|
|
|
1
|
+
# Contrato de herramientas — LifeCode RAG v0.1.0
|
|
2
|
+
|
|
3
|
+
**Estado:** CONGELADO el 2026-11-17. Este documento fija la superficie pública de la versión 0.1.0:
|
|
4
|
+
siete herramientas `lifecode_rag_*`, sus entradas, salidas, permisos, límites y errores. Cambiar
|
|
5
|
+
cualquiera de esos puntos exige una versión nueva y su propia matriz de aceptación; no se amplía el
|
|
6
|
+
alcance por acumulación.
|
|
7
|
+
|
|
8
|
+
Base verificable: `node --test` (66/66), `node tools/check.mjs` (estructura, cero dependencias, cero
|
|
9
|
+
red) y `node tools/hermetic.mjs` (la suite no toca el almacén real). La matriz de aceptación
|
|
10
|
+
AC1–AC29 y sus estados viven en [`ACEPTACION-v0.1.md`](ACEPTACION-v0.1.md).
|
|
11
|
+
|
|
12
|
+
## Reglas comunes
|
|
13
|
+
|
|
14
|
+
- **Sólo herramientas, sin UI y sin sección de system prompt.** La superficie pública son las siete
|
|
15
|
+
herramientas; el plugin no registra paneles, rutas web ni texto de sistema.
|
|
16
|
+
- **Cero dependencias.** `package.json` no declara dependencias, peerDependencies ni optionalDependencies,
|
|
17
|
+
y ningún fuente importa `@deepseek-ai/*`.
|
|
18
|
+
- **Cero red.** Ningún módulo usa `fetch`, `node:http(s)`, `node:net` ni `node:dns`; el comprobador
|
|
19
|
+
`tools/check.mjs` lo verifica y falla si aparece.
|
|
20
|
+
- **Almacén propio.** SQLite en `$DSH_HOME/lifecode-rag/rag.sqlite3` (o `LIFECODE_RAG_ROOT`); nunca
|
|
21
|
+
lee ni escribe el almacén del Skill Center.
|
|
22
|
+
- **Fallo en cerrado.** Una aprobación denegada, ausente o no disponible, una ruta protegida, un
|
|
23
|
+
enlace duro, un enlace simbólico o un índice inconsistente producen error; nunca una escritura
|
|
24
|
+
parcial ni una respuesta "vacía pero correcta".
|
|
25
|
+
- **Resultado de herramienta.** El valor devuelto es un objeto JSON serializable; el adaptador lo
|
|
26
|
+
renderiza como un bloque de texto legible con la misma información. Un fallo llega como
|
|
27
|
+
`{ isError: true, error: { message, info? } }` y el mensaje empieza por el código estable
|
|
28
|
+
(`path-denied: …`), para que el modelo y las pruebas puedan distinguir la causa.
|
|
29
|
+
|
|
30
|
+
### Códigos de error estables
|
|
31
|
+
|
|
32
|
+
Fuente única de verdad: `RAG_CODES` en `lib/errors.mjs` declara **25** códigos. De ellos, **20** se emiten
|
|
33
|
+
hoy, **5** están reservados (declarados y sin emisión) y **3** se emiten sin estar declarados: una deuda
|
|
34
|
+
interna registrada, no un cambio de contrato. En total, el código emite **23** códigos distintos.
|
|
35
|
+
|
|
36
|
+
**Emitidos (23)**
|
|
37
|
+
|
|
38
|
+
`invalid-argument`, `invalid-config`, `invalid-tag`, `store-not-initialized`, `store-not-rag`,
|
|
39
|
+
`store-version-unsupported`, `store-corrupt`, `fts-integrity`, `source-not-found`, `source-unreadable`,
|
|
40
|
+
`path-denied`, `path-not-allowed`, `path-unsupported`, `path-escape`, `hardlink-refused`, `too-large`,
|
|
41
|
+
`too-many-files`, `binary-file`, `approval-required`, `approval-unavailable`, `vector-index-incomplete`,
|
|
42
|
+
`cancelled`, `internal`.
|
|
43
|
+
|
|
44
|
+
**Reservados, sin emisión (5)**
|
|
45
|
+
|
|
46
|
+
`store-busy` (el almacén espera con `busy_timeout` en vez de fallar), `path-outside-root` y
|
|
47
|
+
`path-protected` (sustituidos en la práctica por `path-not-allowed` y `path-denied`),
|
|
48
|
+
`egress-denied` y `embedding-failed` (no hay proveedor remoto en v0.1.0).
|
|
49
|
+
|
|
50
|
+
**Deuda registrada:** `path-escape`, `hardlink-refused` y `vector-index-incomplete` se lanzan desde
|
|
51
|
+
`lib/policy.mjs` y `lib/maintenance.mjs` pero no figuran en `RAG_CODES`. El contrato los documenta porque
|
|
52
|
+
el código los emite; alinearlos en la constante exige tocar código y queda para la siguiente versión
|
|
53
|
+
(no se hace en una reconciliación documental).
|
|
54
|
+
|
|
55
|
+
`codigo: detalle` es el formato del mensaje; los detalles no son contrato y pueden precisarse.
|
|
56
|
+
|
|
57
|
+
### Límites por defecto
|
|
58
|
+
|
|
59
|
+
| Límite | Valor | Dónde se cambia |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| Tamaño máximo por fichero | 2 000 000 bytes | `config.json` → `maxFileBytes` |
|
|
62
|
+
| Ficheros por llamada de ingesta | 200 | `maxFilesPerIngest` |
|
|
63
|
+
| Chunk objetivo / máximo / solape | 1200 / 2000 / 120 caracteres | `chunk.*` |
|
|
64
|
+
| Resultados de búsqueda | 8 (máximo 50) | `search.limit`, `search.maxLimit` |
|
|
65
|
+
| Presupuesto de contexto | 2000 tokens estimados | `context.budgetTokens` |
|
|
66
|
+
| Chunks por contexto | 12 | `context.maxChunks` |
|
|
67
|
+
| Diversidad MMR | 0.7 | `context.mmrLambda` |
|
|
68
|
+
| Embedder local | `local-hash-v1`, 256 dimensiones | `embedding.provider`, `embedding.dim` |
|
|
69
|
+
|
|
70
|
+
Los tokens son una **estimación** (`ceil(caracteres / 4)`), no un conteo del tokenizador del modelo;
|
|
71
|
+
la matriz lo declara como límite conocido (AC20, PARTIAL).
|
|
72
|
+
|
|
73
|
+
## Herramientas
|
|
74
|
+
|
|
75
|
+
### `lifecode_rag_ingest`
|
|
76
|
+
|
|
77
|
+
Indexa ficheros o directorios de texto del proyecto. Acepta rutas relativas al directorio de la
|
|
78
|
+
sesión o absolutas.
|
|
79
|
+
|
|
80
|
+
| Parámetro | Tipo | Obligatorio | Significado |
|
|
81
|
+
|---|---|---|---|
|
|
82
|
+
| `paths` | string \| string[] | sí | Ficheros o directorios a indexar |
|
|
83
|
+
| `collection` | string | no | Agrupa fuentes para filtrar después |
|
|
84
|
+
| `tags` | string[] | no | Etiquetas normalizadas (máx. 20) |
|
|
85
|
+
| `force` | boolean | no | Reindexa aunque el contenido no haya cambiado |
|
|
86
|
+
|
|
87
|
+
- Recorre directorios omitiendo `.git`, `node_modules`, `.dsh`, `dist`, `build`, `coverage`, enlaces
|
|
88
|
+
simbólicos y junctions.
|
|
89
|
+
- Clasifica **todas** las rutas antes de abrir el almacén: si una sola está protegida, la llamada
|
|
90
|
+
entera falla sin escribir nada.
|
|
91
|
+
- Fuera del proyecto (y de las raíces permitidas) exige aprobación humana con la lista exacta.
|
|
92
|
+
- Formatos: `md`, `txt`, `html`, `json`, `jsonl`, `csv`, `tsv`, `yaml`, `xml`, `logs` y código.
|
|
93
|
+
- Devuelve `{ ingested, skipped, errors, approvedOutside }`; `skipped` son fuentes cuyo contenido no
|
|
94
|
+
cambió (mismo `sha256` y sin `force`), no un fallo.
|
|
95
|
+
- Reingerir el mismo contenido con etiquetas distintas actualiza sólo las etiquetas y **no** sube
|
|
96
|
+
`index_revision` (auditoría `ingest.tags`).
|
|
97
|
+
|
|
98
|
+
### `lifecode_rag_search`
|
|
99
|
+
|
|
100
|
+
Búsqueda híbrida: FTS5 léxica + similitud de vectores, fusionadas con Reciprocal Rank Fusion (k=60).
|
|
101
|
+
Devuelve fragmentos compactos; el texto completo se pide con `lifecode_rag_get`.
|
|
102
|
+
|
|
103
|
+
| Parámetro | Tipo | Obligatorio | Significado |
|
|
104
|
+
|---|---|---|---|
|
|
105
|
+
| `query` | string | sí | Consulta en lenguaje natural |
|
|
106
|
+
| `limit` | number | no | Resultados (1–50; por defecto 8) |
|
|
107
|
+
| `collection` | string | no | Filtra por colección |
|
|
108
|
+
| `tags` | string[] | no | Filtra por etiquetas |
|
|
109
|
+
| `tagMode` | `any` \| `all` | no | Cualquiera (por defecto) o todas |
|
|
110
|
+
|
|
111
|
+
- Devuelve `{ results, mode, elapsedMs }` con `results[] = { chunkKey, sourceId, uri, title, heading,
|
|
112
|
+
ordinal, rrf, snippet }`. `mode` indica `hybrid` o `fts`.
|
|
113
|
+
- Nunca devuelve el texto completo del chunk: sólo un `snippet` de hasta 240 caracteres.
|
|
114
|
+
- La recuperación es léxica de base; `local-hash-v1` **no** es un modelo semántico y el contrato no
|
|
115
|
+
promete paráfrasis. La medición está en [`BENCHMARK-2026-11-17.md`](BENCHMARK-2026-11-17.md).
|
|
116
|
+
|
|
117
|
+
### `lifecode_rag_context`
|
|
118
|
+
|
|
119
|
+
Ensambla contexto listo para el modelo con diversificación MMR y citas numeradas verificables.
|
|
120
|
+
|
|
121
|
+
| Parámetro | Tipo | Obligatorio | Significado |
|
|
122
|
+
|---|---|---|---|
|
|
123
|
+
| `query` | string | sí | Consulta |
|
|
124
|
+
| `budgetTokens` | number | no | Presupuesto estimado (por defecto 2000) |
|
|
125
|
+
| `maxChunks` | number | no | Fragmentos máximos (por defecto 12) |
|
|
126
|
+
| `collection` | string | no | Filtra por colección |
|
|
127
|
+
| `tags` | string[] | no | Filtra por etiquetas |
|
|
128
|
+
|
|
129
|
+
- Devuelve `{ text, citations, tokens, truncated, considered }`.
|
|
130
|
+
- `citations[] = { n, chunkKey, sourceId, uri, title, heading, ordinal, charStart, charEnd }`.
|
|
131
|
+
- Si el primer fragmento no cabe en el presupuesto, devuelve `text` vacío y `truncated: true`; no
|
|
132
|
+
corta un chunk a la mitad ni presenta un contexto incompleto como completo.
|
|
133
|
+
|
|
134
|
+
### `lifecode_rag_get`
|
|
135
|
+
|
|
136
|
+
Lee una fuente indexada y sus fragmentos completos, para verificar una cita.
|
|
137
|
+
|
|
138
|
+
| Parámetro | Tipo | Obligatorio | Significado |
|
|
139
|
+
|---|---|---|---|
|
|
140
|
+
| `ref` | string | sí | `sourceId` (`src_…`) o URI indexada |
|
|
141
|
+
| `limit` | number | no | Fragmentos a devolver |
|
|
142
|
+
|
|
143
|
+
Devuelve la fuente normalizada (título, uri, colección, etiquetas, hash, fechas, `index_revision`) y
|
|
144
|
+
sus chunks en orden. `source-not-found` si la referencia no existe.
|
|
145
|
+
|
|
146
|
+
### `lifecode_rag_list`
|
|
147
|
+
|
|
148
|
+
Lista fuentes con filtros y paginación.
|
|
149
|
+
|
|
150
|
+
| Parámetro | Tipo | Obligatorio | Significado |
|
|
151
|
+
|---|---|---|---|
|
|
152
|
+
| `collection` | string | no | Filtra por colección |
|
|
153
|
+
| `tag` | string | no | Filtra por etiqueta |
|
|
154
|
+
| `limit` | number | no | Tamaño de página |
|
|
155
|
+
| `offset` | number | no | Desplazamiento |
|
|
156
|
+
|
|
157
|
+
Devuelve `{ total, rows }` con una fila por fuente y su número de chunks.
|
|
158
|
+
|
|
159
|
+
### `lifecode_rag_forget`
|
|
160
|
+
|
|
161
|
+
Elimina una fuente y todo lo indexado de ella (chunks, vectores, etiquetas, FTS por cascada).
|
|
162
|
+
|
|
163
|
+
| Parámetro | Tipo | Obligatorio | Significado |
|
|
164
|
+
|---|---|---|---|
|
|
165
|
+
| `ref` | string | sí | `sourceId` o URI |
|
|
166
|
+
|
|
167
|
+
- **Siempre** exige aprobación humana; el motivo incluye el `sourceId` y la URI exactos.
|
|
168
|
+
- Si la aprobación falta, se deniega o no hay respondiente: `approval-required` /
|
|
169
|
+
`approval-unavailable`, sin borrar nada.
|
|
170
|
+
- Devuelve `{ forgotten: true, sourceId, uri }`.
|
|
171
|
+
|
|
172
|
+
### `lifecode_rag_reindex`
|
|
173
|
+
|
|
174
|
+
Reconstruye el índice de texto, los vectores o ambos.
|
|
175
|
+
|
|
176
|
+
| Parámetro | Tipo | Obligatorio | Significado |
|
|
177
|
+
|---|---|---|---|
|
|
178
|
+
| `operation` | `fts` \| `vectors` \| `all` | sí | Qué reconstruir |
|
|
179
|
+
|
|
180
|
+
- **Siempre** exige aprobación humana. `all` ejecuta primero FTS y después vectores.
|
|
181
|
+
- `fts` es una transacción global: `rebuild`, verificación de integridad, subida de
|
|
182
|
+
`index_revision` y asiento de auditoría, todo o nada.
|
|
183
|
+
- `vectors` va por fuente, con transacción propia, y comprueba entre fuentes si la operación fue
|
|
184
|
+
cancelada (`cancelled`). Al terminar exige que cada chunk tenga su vector
|
|
185
|
+
(`vector-index-incomplete` si falta alguno).
|
|
186
|
+
- Devuelve `{ operation, rebuiltChunks?, rebuiltSources? }`.
|
|
187
|
+
|
|
188
|
+
## Fuera del contrato v0.1.0
|
|
189
|
+
|
|
190
|
+
No forman parte de esta versión y no deben anunciarse como disponibles: ingesta de PDF/DOCX,
|
|
191
|
+
embeddings neuronales, egress remoto, UI/panel, sección de system prompt, búsqueda por `minScore`,
|
|
192
|
+
formato de contexto alternativo, `list` por tipo de fuente, `forget` por lote, historial de
|
|
193
|
+
versiones de un documento y exportación/importación del almacén. La tabla de desviaciones completa
|
|
194
|
+
está en [`ACEPTACION-v0.1.md`](ACEPTACION-v0.1.md), sección «Desviaciones del contrato de herramientas
|
|
195
|
+
(§16 de v2)».
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# LifeCode RAG — Proveedores de embeddings
|
|
2
|
+
|
|
3
|
+
**Fecha:** 2026-11-17 · **Estado:** contrato propuesto + alternativas a evaluar
|
|
4
|
+
**Restricción de esta fase:** no se descarga ningún modelo, no se instala ninguna dependencia y no se
|
|
5
|
+
activa ningún proveedor remoto. Este documento diseña la decisión; no la toma.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Situación actual
|
|
10
|
+
|
|
11
|
+
`lib/embed.mjs` implementa `local-hash-v1`: bolsa de tokens con hash SHA-256 a 256 dimensiones, signo por
|
|
12
|
+
bucket, `1+log1p(count)`, bigramas con peso 0.5 y L2. Es **léxico**, no semántico.
|
|
13
|
+
|
|
14
|
+
Consecuencia medida (benchmark v0.1.0): una paráfrasis como `instalar` contra un corpus que dice
|
|
15
|
+
`instalación` obtiene Recall@5 = 0.000, tanto en FTS como en híbrida. No es un defecto del código: es el
|
|
16
|
+
límite del modelo. La corrección es un proveedor semántico, no más magia léxica.
|
|
17
|
+
|
|
18
|
+
El valor de `local-hash-v1` sigue siendo real: cero dependencias, determinista, offline, rápido, y sirve
|
|
19
|
+
como red de seguridad cuando el semántico no está disponible.
|
|
20
|
+
|
|
21
|
+
## 2. Contrato `EmbeddingProvider`
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
/**
|
|
25
|
+
* @typedef {Object} EmbeddingProvider
|
|
26
|
+
* @property {string} id // 'local-hash-v1' | 'onnx-multilingual-minilm-v1' | ...
|
|
27
|
+
* @property {number} dim
|
|
28
|
+
* @property {'local'|'remote'} kind
|
|
29
|
+
* @property {string} [license] // licencia del código y, si aplica, del modelo
|
|
30
|
+
* @property {(texts: string[], opts?: {signal?: AbortSignal}) => Promise<Float32Array[]>} embedBatch
|
|
31
|
+
*/
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Requisitos:
|
|
35
|
+
|
|
36
|
+
- **Determinista**: mismo texto ⇒ mismo vector, mismo `id`, mismo `dim`.
|
|
37
|
+
- **Normalizado** (L2 = 1) o se normaliza en el adaptador; el coseno no debe depender del proveedor.
|
|
38
|
+
- **Lotes**: `embedBatch` acepta N textos; el adaptador decide el tamaño real.
|
|
39
|
+
- **Cancelable**: `signal` comprobado entre lotes.
|
|
40
|
+
- **Sin red por defecto**: `kind:'remote'` exige aprobación por llamada y `localOnly=false`.
|
|
41
|
+
- **Errores**: cualquier fallo se normaliza a `RagError('embedding-failed')`; nunca se escribe un vector
|
|
42
|
+
a medias.
|
|
43
|
+
- **Identidad versionada**: `id` incluye versión (`...-v1`). Cambiar de modelo es un `id` nuevo, no un
|
|
44
|
+
cambio silencioso del anterior.
|
|
45
|
+
|
|
46
|
+
## 3. Almacenamiento y migración
|
|
47
|
+
|
|
48
|
+
La tabla `vectors` ya guarda `(chunk_key, model, dim, vec)` con `model` en la PK lógica por chunk. Reglas:
|
|
49
|
+
|
|
50
|
+
- Un chunk puede tener vectores de varios modelos (migración en caliente).
|
|
51
|
+
- La búsqueda usa **un** modelo: el activo en configuración; si no hay cobertura completa, se declara
|
|
52
|
+
`vector-index-incomplete` y la híbrida degrada a FTS.
|
|
53
|
+
- `reindex vectors` con un modelo nuevo es una operación de confirmación (puede tardar y ocupar CPU).
|
|
54
|
+
- Borrar el modelo antiguo es explícito (`reindex vectors --prune`), nunca automático.
|
|
55
|
+
- El esquema no cambia para añadir un proveedor: solo `model`/`dim` y la política de cuál está activo.
|
|
56
|
+
|
|
57
|
+
## 4. Alternativas (a verificar en M6, sin instalar ahora)
|
|
58
|
+
|
|
59
|
+
| Opción | Ventajas | Costes/riesgos | Español | Estado |
|
|
60
|
+
|---|---|---|---|---|
|
|
61
|
+
| **A. ONNX Runtime + modelo multilingüe pequeño** (p. ej. familia MiniLM/E5 multilingüe, ONNX) | CPU, offline, ecosistema maduro; `onnxruntime-node` con binarios Windows | dependencia nativa (~decenas de MB), modelo 80–120 MB, licencia del modelo aparte de la del runtime; hay que verificar compatibilidad Electron/ABI | sí (modelos multilingües) | **no probado en este host** |
|
|
62
|
+
| **B. transformers.js (ONNX) en proceso** | JS puro sobre ONNX, sin compilar | memoria y arranque; descarga de modelo desde hub si no se vendoriza; versión de ONNX Runtime | sí | **no probado** |
|
|
63
|
+
| **C. node-llama-cpp + GGUF** | buenos embeddings, CPU/GPU, modelos pequeños | binario nativo, compilación/ABI, licencia del modelo; consumo de memoria | depende del modelo | **no probado** |
|
|
64
|
+
| **D. Windows ML / DirectML** | aceleración en Windows | API y empaquetado propios; dependencia de versión de Windows | depende | **no probado** |
|
|
65
|
+
| **E. API remota compatible OpenAI** (`/v1/embeddings`) | cero binarios, calidad alta | egress, coste, latencia, privacidad; requiere aprobación por llamada | sí | contrato ya previsto |
|
|
66
|
+
| **F. Seguir solo léxico** | cero deps | no resuelve paráfrasis | n/a | actual |
|
|
67
|
+
|
|
68
|
+
Ninguna opción se elige por intuición. La decisión es un resultado de medición, no una preferencia.
|
|
69
|
+
|
|
70
|
+
## 5. Protocolo de evaluación (M6)
|
|
71
|
+
|
|
72
|
+
1. Corpus congelado de `RETRIEVAL-EVALUATION.md` (120 consultas, es/en).
|
|
73
|
+
2. Línea base: `local-hash-v1` (ya medida).
|
|
74
|
+
3. Para cada candidato: mismo corpus, mismo chunking, mismos K; medir Recall@5/10, MRR@5/10, NDCG@10,
|
|
75
|
+
latencia p50/p95 de `embedBatch` y de consulta, RAM pico, tiempo de arranque.
|
|
76
|
+
4. Repetir 3 veces; publicar mediana y dispersión.
|
|
77
|
+
5. Criterio de promoción: mejora **medida** en Recall@10 ≥ 10 puntos absolutos sobre la paráfrasis sin
|
|
78
|
+
degradar latencia p95 de consulta por encima de +50 ms ni RAM por encima de +150 MB.
|
|
79
|
+
6. Si ningún candidato cumple, se queda `local-hash-v1` y se dice.
|
|
80
|
+
|
|
81
|
+
## 6. Empaquetado y licencias
|
|
82
|
+
|
|
83
|
+
- El proveedor debe poder instalarse **como dependencia opcional** del bundle, no obligatoria: quien no
|
|
84
|
+
la tenga sigue funcionando en modo léxico.
|
|
85
|
+
- Un modelo pesado no entra en el paquete npm del plugin; se vendoriza o se descarga con consentimiento
|
|
86
|
+
explícito y checksum publicado. `tools/check.mjs` seguirá fallando si aparece una descarga implícita.
|
|
87
|
+
- Se documentan dos licencias: la del **código** del runtime y la del **modelo**. Una licencia permisiva
|
|
88
|
+
del runtime no implica licencia del modelo.
|
|
89
|
+
- Sin telemetría del proveedor; sin llamadas de "comprobación de versión".
|
|
90
|
+
|
|
91
|
+
## 7. Riesgos
|
|
92
|
+
|
|
93
|
+
| Riesgo | Mitigación |
|
|
94
|
+
|---|---|
|
|
95
|
+
| ABI nativa incompatible con Electron 44 | probar carga en el proceso host antes de comprometerse; si falla, opción B |
|
|
96
|
+
| Modelo que alucina similitud en español | evaluar con corpus es antes de promover |
|
|
97
|
+
| Aumento de tamaño del bundle | opcional + vendorizado fuera del paquete |
|
|
98
|
+
| Migración a medias | `model` por vector + cobertura obligatoria antes de activar |
|
|
99
|
+
| Egress accidental | `localOnly` por defecto; el proveedor remoto no se activa por config sin aprobación |
|
|
100
|
+
|
|
101
|
+
## 8. Decisión pendiente
|
|
102
|
+
|
|
103
|
+
`DECISIONS-v0.2.0.md` ADR-06 fija: **no se adopta proveedor en v0.2.0; se implementa el puerto y el
|
|
104
|
+
arnés de evaluación**. La adopción ocurre en v0.2.1 con números. Esta es una decisión deliberada para no
|
|
105
|
+
vender "semántico" sin evidencia.
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# LifeCode RAG — Observabilidad
|
|
2
|
+
|
|
3
|
+
**Fecha:** 2026-11-17 · **Estado:** diseño propuesto (sin instrumentación implementada)
|
|
4
|
+
**Principio:** métricas **agregadas**, con procedencia declarada; nunca contenido.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 1. Límites de privacidad (no negociables)
|
|
9
|
+
|
|
10
|
+
No se persiste, bajo ninguna configuración:
|
|
11
|
+
|
|
12
|
+
- prompts del sistema o del usuario;
|
|
13
|
+
- respuestas del modelo;
|
|
14
|
+
- texto de las consultas;
|
|
15
|
+
- texto de los chunks recuperados como telemetría;
|
|
16
|
+
- conversaciones, sesiones, IDs de sesión o de agente como dimensión de métrica;
|
|
17
|
+
- credenciales, tokens o cabeceras.
|
|
18
|
+
|
|
19
|
+
Sí se persiste: contadores, latencias por cubo, conteos por colección y estrategia, y el resultado
|
|
20
|
+
`ok|error|zero-results` de una consulta. Una consulta con cero resultados incrementa un contador; su
|
|
21
|
+
texto se descarta al terminar la petición.
|
|
22
|
+
|
|
23
|
+
## 2. Catálogo de métricas
|
|
24
|
+
|
|
25
|
+
Cada fila declara **procedencia**: `medido` (instrumentado en el punto de ejecución) o
|
|
26
|
+
`derivado` (calculado a partir de medidos), y su **método**.
|
|
27
|
+
|
|
28
|
+
| Métrica | Definición | Procedencia | Punto |
|
|
29
|
+
|---|---|---|---|
|
|
30
|
+
| `queries.agent` | consultas servidas por `lifecode_rag_search`/`context` | medido | tool execute |
|
|
31
|
+
| `queries.lab` | consultas del Laboratorio (separadas) | medido | `POST /retrieval` |
|
|
32
|
+
| `queries.zero` | consultas con 0 resultados | medido | `search()` |
|
|
33
|
+
| `contexts.built` | contextos devueltos por `lifecode_rag_context` | medido | `assembleContext` |
|
|
34
|
+
| `contexts.truncated` | contextos que no cupieron en el presupuesto | medido | `assembleContext` |
|
|
35
|
+
| `tokens.served` | suma de `tokens` estimados de contextos servidos | derivado | `ceil(chars/4)` |
|
|
36
|
+
| `tokens.corpus` | tamaño del corpus indexado en tokens estimados | derivado | `ceil(chars/4)` |
|
|
37
|
+
| `latency.bucket` | histograma por estrategia (`fts`/`vector`/`hybrid`) | medido | `search()` |
|
|
38
|
+
| `ingest.files` / `ingest.chunks` / `ingest.errors` | volumen y fallos de ingesta | medido | `ingestFiles` |
|
|
39
|
+
| `vectors.coverage` | chunks con vector / chunks totales, por modelo | derivado | mantenimiento |
|
|
40
|
+
| `fts.coverage` | filas FTS / chunks | derivado | health check |
|
|
41
|
+
| `audit.events` | eventos por acción y resultado | medido | `appendAudit` |
|
|
42
|
+
| `maintenance.runs` | reindex/forget ejecutados y su duración | medido | `maintenance` |
|
|
43
|
+
| `approvals.asked` / `approvals.allowed` / `approvals.rejected` | decisiones del host | medido | tool wrapper |
|
|
44
|
+
| `storage.bytes` | tamaño de `rag.sqlite3` + `-wal` | medido | snapshot |
|
|
45
|
+
| `metrics.write_failures` | escrituras de métricas fallidas (contador en memoria, volcado best-effort) | derivado | borde de telemetría |
|
|
46
|
+
|
|
47
|
+
No se mide «calidad de respuesta generada»: no hay acceso a la respuesta del modelo y no se va a inventar.
|
|
48
|
+
|
|
49
|
+
## 3. Almacenamiento
|
|
50
|
+
|
|
51
|
+
**Una sola tabla.** Se evaluó una segunda tabla (día × métrica y otra por dimensión) y se descarta: la PK
|
|
52
|
+
`(day, metric, dim)` ya separa estrategias, cubos y colecciones, y una tabla extra duplicaría escrituras
|
|
53
|
+
sin resolver ninguna consulta que la primera no resuelva.
|
|
54
|
+
|
|
55
|
+
```sql
|
|
56
|
+
CREATE TABLE metrics_daily (
|
|
57
|
+
day TEXT NOT NULL, -- YYYY-MM-DD (UTC)
|
|
58
|
+
metric TEXT NOT NULL, -- enum cerrado (§3.1)
|
|
59
|
+
dim TEXT NOT NULL DEFAULT '', -- enum estructurado (§3.1)
|
|
60
|
+
value REAL NOT NULL, -- contador o cubo; nunca texto
|
|
61
|
+
updated_at INTEGER NOT NULL,
|
|
62
|
+
PRIMARY KEY (day, metric, dim)
|
|
63
|
+
) STRICT;
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- Un `UPSERT` por incremento (`value = value + excluded.value`), dentro de la misma transacción que la
|
|
67
|
+
operación cuando la operación ya escribe; si no, transacción propia de una fila.
|
|
68
|
+
- Escritura en lote por operación (una transacción por tool/llamada, no una por chunk).
|
|
69
|
+
- Latencia por cubos fijos (ms): `0-10, 10-25, 25-50, 50-100, 100-250, 250-500, 500-1000, 1000+`.
|
|
70
|
+
Guardar cubos, no muestras, evita crecer con el uso.
|
|
71
|
+
- Retención por defecto **90 días** (`metrics.retentionDays`, 7–365), con la clasificación de purga de §7.
|
|
72
|
+
- No hay tabla de «uso por consulta»: el ahorro se deriva de `tokens.served`, `tokens.corpus` y
|
|
73
|
+
`contexts.built`; guardar una fila por consulta crecería con el uso y acercaría el riesgo de perfilado.
|
|
74
|
+
|
|
75
|
+
Índices: la PK cubre `(day, metric, dim)`; serie = `WHERE metric=? AND day BETWEEN ? AND ? ORDER BY day`.
|
|
76
|
+
|
|
77
|
+
### 3.1 Enumeraciones cerradas
|
|
78
|
+
|
|
79
|
+
`metric` es una lista cerrada; cualquier otro valor se rechaza con `invalid-metric` antes de escribir:
|
|
80
|
+
|
|
81
|
+
```text
|
|
82
|
+
queries.agent | queries.lab | queries.zero | contexts.built | contexts.truncated
|
|
83
|
+
tokens.served | tokens.corpus | latency.bucket
|
|
84
|
+
ingest.files | ingest.chunks | ingest.errors
|
|
85
|
+
vectors.coverage | fts.coverage | audit.events | maintenance.runs
|
|
86
|
+
approvals.asked | approvals.allowed | approvals.rejected
|
|
87
|
+
storage.bytes | metrics.write_failures
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`dim` no es texto libre: se compone de un **tipo permitido** y un valor validado:
|
|
91
|
+
|
|
92
|
+
| Tipo | Valor permitido | Ejemplo |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| `strategy` | `fts` \| `vector` \| `hybrid` | `strategy:hybrid` |
|
|
95
|
+
| `bucket` | uno de los 8 cubos de latencia | `bucket:50-100` |
|
|
96
|
+
| `collection` | nombre de colección ya existente, `^[a-z0-9][a-z0-9._-]{0,63}$` | `collection:docs` |
|
|
97
|
+
| `model` | id de embedder, `^[a-z0-9][a-z0-9._-]{0,63}$` | `model:local-hash-v1` |
|
|
98
|
+
| `channel` | `agent` \| `lab` | `channel:lab` |
|
|
99
|
+
| `outcome` | `ok` \| `error` \| `zero` \| `allowed` \| `rejected` \| `asked` | `outcome:zero` |
|
|
100
|
+
| `action` | una acción de auditoría existente | `action:ingest` |
|
|
101
|
+
|
|
102
|
+
Reglas de validación (implementadas en `lib/metrics.mjs`, no en la UI):
|
|
103
|
+
|
|
104
|
+
1. `metric` debe estar en la lista; `dim` debe casar `^(strategy|bucket|collection|model|channel|outcome|action):…`.
|
|
105
|
+
2. `collection` y `model` se aceptan solo si ya existen en la base; si no, se descarta la métrica (no se
|
|
106
|
+
crea una dimensión nueva desde una petición).
|
|
107
|
+
3. Se rechaza cualquier `dim` que contenga `/`, `\`, `:` extra, espacios, longitud > 96 o el texto de la
|
|
108
|
+
consulta (comparación con la cadena de la petición antes de descartarla).
|
|
109
|
+
4. Nunca se usa la ruta de un fichero, un id de sesión/agente, una cabecera ni un token como dimensión.
|
|
110
|
+
|
|
111
|
+
### 3.2 Agregado de `tokens.corpus`
|
|
112
|
+
|
|
113
|
+
`tokens.corpus` **no** se recalcula escaneando todos los chunks en `/snapshot`. Se mantiene un agregado
|
|
114
|
+
persistido en `meta`:
|
|
115
|
+
|
|
116
|
+
| Clave | Contenido |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `tokens_corpus_estimate` | suma de `ceil(length(text)/4)` de los chunks vigentes |
|
|
119
|
+
| `tokens_corpus_chunks` | número de chunks usados en la suma |
|
|
120
|
+
| `tokens_corpus_seq` | `index_revision` en el momento del cálculo |
|
|
121
|
+
|
|
122
|
+
Actualización, siempre en la **misma transacción** que la mutación:
|
|
123
|
+
|
|
124
|
+
- ingesta nueva: `+= estimate(chunks insertados)`; reemplazo: `-= estimate(chunks borrados)` y `+=` los
|
|
125
|
+
nuevos (se hace con los valores leídos antes del `DELETE`, no después);
|
|
126
|
+
- `forget`: `-= estimate(chunks de la fuente)`;
|
|
127
|
+
- `reindex all`/`fts`: recalcula al final de la transacción global porque rebuild no cambia textos, pero sí
|
|
128
|
+
verifica;
|
|
129
|
+
- `reindex vectors`: no cambia textos → no toca el agregado.
|
|
130
|
+
|
|
131
|
+
Reconstrucción si queda inconsistente (p. ej. caída entre mutación y agregado, o edición manual):
|
|
132
|
+
`SELECT SUM((length(text)+3)/4), COUNT(*) FROM chunks` dentro de una transacción, y `writeMeta` con los tres
|
|
133
|
+
valores. Se ejecuta en `doctor` cuando `tokens_corpus_chunks != COUNT(*)` o
|
|
134
|
+
`tokens_corpus_seq != sources.index_revision` agregado; el resultado se marca en `/health` como
|
|
135
|
+
`tokens.corpus: reconstruido`. La UI muestra `≈` y la fórmula; nunca lo presenta como tokens reales.
|
|
136
|
+
|
|
137
|
+
## 4. Instrumentación
|
|
138
|
+
|
|
139
|
+
Un único módulo `lib/metrics.mjs` con API mínima:
|
|
140
|
+
|
|
141
|
+
```js
|
|
142
|
+
recordMetric(db, { metric, value = 1, dim = '', at = Date.now() })
|
|
143
|
+
withTiming(db, { metric, dim }, fn) // mide y registra aunque fn lance
|
|
144
|
+
readSummary(db, { from, to })
|
|
145
|
+
readSeries(db, { metric, from, to, bucket = 'day' })
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Reglas:
|
|
149
|
+
|
|
150
|
+
- **Nunca lanza** hacia el camino de negocio: la operación continúa aunque la métrica falle. El fallo se
|
|
151
|
+
contabiliza en un contador **en memoria** (`telemetryFailures`) y se escribe una sola vez, en un `try`
|
|
152
|
+
independiente, como `metrics.write_failures`. Si esa escritura también falla, **no se intenta registrar
|
|
153
|
+
el fallo del registro** (no hay recursión): queda el contador en memoria y una línea en `stderr`, y la
|
|
154
|
+
operación de negocio termina igual. `metrics.write_failures` jamás se cuenta a través de `recordMetric`.
|
|
155
|
+
- La telemetría no abre transacciones anidadas: si la operación ya escribió y la métrica falla, se pierde
|
|
156
|
+
la métrica, no la operación.
|
|
157
|
+
- El reloj se inyecta (`at`) para pruebas deterministas.
|
|
158
|
+
- Se llama en el borde (tools, rutas, mantenimiento), no dentro de bucles de chunk.
|
|
159
|
+
- Un test verifica que ninguna tabla de métricas contiene texto de consulta: se ejecuta una consulta con
|
|
160
|
+
una cadena única y se comprueba que esa cadena no aparece en ningún fichero del almacén.
|
|
161
|
+
|
|
162
|
+
## 5. Derivaciones y honestidad
|
|
163
|
+
|
|
164
|
+
La UI debe poder responder «¿de dónde sale este número?». Cada tarjeta de Analítica muestra:
|
|
165
|
+
|
|
166
|
+
1. definición en una frase;
|
|
167
|
+
2. procedencia (`medido`/`derivado`);
|
|
168
|
+
3. ventana temporal;
|
|
169
|
+
4. si es estimado, la fórmula.
|
|
170
|
+
|
|
171
|
+
`tokens.served` y `tokens.corpus` son **estimaciones** (`ceil(chars/4)`), no tokens reales del modelo.
|
|
172
|
+
Se etiquetan como tales en la UI y en el benchmark. La estimación se sustituirá por conteo real cuando
|
|
173
|
+
exista un contrato de tokenizer en el host; hoy no lo hay.
|
|
174
|
+
|
|
175
|
+
## 6. Consultas de lectura
|
|
176
|
+
|
|
177
|
+
`lib/query.mjs` expone:
|
|
178
|
+
|
|
179
|
+
- `metricsSummary(db, {from, to})` → `{window, queries, zeroRate, contexts, tokens, latencyP50, latencyP95, topCollections}`;
|
|
180
|
+
- `metricsSeries(db, {metric, from, to})` → `[{day, value}]`;
|
|
181
|
+
- `metricsHealth(db)` → cobertura FTS/vectores, última escritura, filas de métricas, retención.
|
|
182
|
+
|
|
183
|
+
`latencyP50/P95` se calculan a partir de los cubos con el método de §6.1; no son valores exactos.
|
|
184
|
+
|
|
185
|
+
### 6.1 Percentiles a partir de cubos
|
|
186
|
+
|
|
187
|
+
Algoritmo (determinista, sin muestras):
|
|
188
|
+
|
|
189
|
+
1. `N` = suma de valores de los 8 cubos de la ventana.
|
|
190
|
+
2. Para `q ∈ {0.50, 0.95}`, objetivo `t = q·N`; se acumulan cubos hasta que el acumulado `≥ t`.
|
|
191
|
+
3. Sea el cubo `[lo, hi)` con acumulado previo `a` y ancho `w`; la estimación es
|
|
192
|
+
`p = lo + w · (t − a) / count(cubo)`.
|
|
193
|
+
4. El cubo abierto `1000+` se trata como `[1000, ∞)`: se devuelve `≥1000` y **no** se extrapola un valor
|
|
194
|
+
puntual.
|
|
195
|
+
5. La precisión publicada es «± ancho del cubo»: p. ej. con `250-500` la estimación puede desviarse hasta
|
|
196
|
+
250 ms. La UI muestra `≈` y el texto «estimado por histograma».
|
|
197
|
+
|
|
198
|
+
Consecuencia honesta: p95 no sirve para afirmar «cumplimos 250 ms» si el cubo que lo contiene es ancho. Para
|
|
199
|
+
el presupuesto de recuperación se mide con el arnés (muestras reales), no con el histograma.
|
|
200
|
+
|
|
201
|
+
## 7. Retención y purga: clasificación única
|
|
202
|
+
|
|
203
|
+
| Operación | Quién | Requisito |
|
|
204
|
+
|---|---|---|
|
|
205
|
+
| Purga rutinaria dentro de la retención (90 d) | automática al abrir/cerrar mantenimiento | ninguna; auditada |
|
|
206
|
+
| Cambio de `retentionDays` (7–365) | persona desde Configuración | confirmación explícita |
|
|
207
|
+
| Purga anticipada (borrar antes de la retención) | persona | confirmación + motivo; auditada |
|
|
208
|
+
| Purga de todo el histórico | persona | **aprobación humana** por el motor de políticas |
|
|
209
|
+
| Borrado del almacén completo | persona | **aprobación humana** + copia previa ofrecida |
|
|
210
|
+
|
|
211
|
+
La UI no puede aprobar nada: `POST /actions` con `purgeMetrics`/`purgeAll` devuelve `approval-required` y
|
|
212
|
+
el host pide la aprobación con su propio diálogo. Ninguna purga se ejecuta por una ruta HTTP sin ese paso.
|
|
213
|
+
|
|
214
|
+
### 7.1 Exportación, opt-out y desinstalación
|
|
215
|
+
|
|
216
|
+
- `metrics export` (CLI) escribe un JSON con las series; no incluye contenido.
|
|
217
|
+
- Desactivar analítica (`usageAnalytics: false`) detiene la escritura de `queries.*`, `tokens.*` y
|
|
218
|
+
`latency.*`; mantiene salud e integridad, que son diagnóstico, no uso.
|
|
219
|
+
- Desinstalar el plugin no borra el almacén: la UI de DSH no ejecuta borrados; se documenta la ruta.
|
|
220
|
+
|
|
221
|
+
## 8. Pruebas exigidas (M-v0.2.0)
|
|
222
|
+
|
|
223
|
+
1. Incremento y lectura por día/cubo; idempotencia dentro de la misma transacción.
|
|
224
|
+
2. Fallo de métrica no altera el resultado de la operación.
|
|
225
|
+
3. Fallo del propio `metrics.write_failures` no produce recursión ni excepción (contador en memoria).
|
|
226
|
+
4. `metric`/`dim` fuera del enum se rechazan y no crean filas.
|
|
227
|
+
5. Sin texto de consulta en el fichero SQLite ni en `-wal` tras una consulta única (test de privacidad).
|
|
228
|
+
6. Purga respeta retención y deja auditoría; purga total sin aprobación devuelve `approval-required`.
|
|
229
|
+
7. Series con huecos devuelven días sin dato como `null`, no como 0.
|
|
230
|
+
8. `usageAnalytics:false` no escribe métricas de uso pero sí de salud.
|
|
231
|
+
9. `tokens.corpus` sobrevive a ingesta/reemplazo/forget; tras corromper `meta` a mano, `doctor` reconstruye
|
|
232
|
+
y marca `reconstruido`.
|
|
233
|
+
|
|
234
|
+
## 9. Riesgos
|
|
235
|
+
|
|
236
|
+
| Riesgo | Mitigación |
|
|
237
|
+
|---|---|
|
|
238
|
+
| Métricas que se convierten en perfilado | Sin texto, sin sesión, sin agente; retención corta; opt-out |
|
|
239
|
+
| Coste de escritura por consulta | UPSERT de una fila; cubos en vez de muestras |
|
|
240
|
+
| Números que la UI presenta como exactos | Sello `medido/derivado/estimado` obligatorio en el contrato |
|
|
241
|
+
| Divergencia UI/motor | El cálculo vive en `metrics.mjs`/`query.mjs`, no en el cliente |
|