docs(verbo): SDD del módulo — contrato + mock + daemon + backends pendientes

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 16:26:18 +00:00
parent 649ca02d4d
commit 781a310c8d
1 changed files with 43 additions and 0 deletions
@@ -0,0 +1,43 @@
+# modules/verbo/ — Provider de embeddings model-agnostic (era dime)
+
+**Propósito.** Capa de embeddings estructuralmente agnóstica al modelo:
+la elección de backend es config por instancia. Los vectores quedan
+atados a su `ModelId` — comparar vectores de modelos distintos es un
+error explícito, no un sinsentido silencioso. Un daemon permite cargar
+un modelo una vez y compartirlo entre procesos.
+
+## Crates
+
+| crate          | tipo | rol                                                          |
+| -------------- | ---- | ------------------------------------------------------------ |
+| `verbo-core`   | lib  | Contrato: `ModelId`, `EmbeddingVector` (cosine), `EmbedError`, trait `Provider` |
+| `verbo-mock`   | lib  | Backend determinista sin modelo (FNV-1a + LCG) — para tests  |
+| `verbo-daemon` | lib  | `Daemon` (sirve un `Provider` por socket Unix) + `DaemonClient` (lo consume como `Provider`) |
+
+## Dependencias
+
+- `mock`, `daemon` ← `verbo-core`.
+- `daemon` ← `tokio` + `postcard` (frames con prefijo de largo).
+- `verbo-core` es `#![forbid(unsafe_code)]`, sólo `serde` + `async-trait`.
+
+## Compartir entre procesos
+
+`verbo-daemon` resuelve la duplicación de modelos en RAM: un `Daemon`
+carga el modelo una vez; N procesos lo consumen vía `DaemonClient`, que
+implementa `Provider` y por tanto es indistinguible de un backend local.
+Multi-instancia = un daemon por modelo, cada uno en su socket.
+
+## Estado
+
+Contrato + mock + daemon implementados y verdes (~25 tests).
+
+**Pendiente** — backends de modelos reales (requieren infra/API keys):
+
+| backend pendiente | tipo   | nota                                          |
+| ----------------- | ------ | --------------------------------------------- |
+| `verbo-cohere`    | remoto | API Cohere — recomendado para uso remoto      |
+| `verbo-bge`       | local  | `bge-code-large` vía ONNX — recomendado local |
+| `verbo-fastembed` | local  | modelos ligeros (MiniLM 384d)                 |
+
+Cada uno implementa `Provider` y puede servirse vía `verbo-daemon` sin
+cambios — el daemon es agnóstico del backend.