tawasuyu/brahman

Rust 496TOML 195Markdown 55JSON 197001 Definitions

Clone over HTTPS, with plain git

⎇ main crates/modules/verbo/SDD.md Markdown · 43 lines · 2.0 KB History raw

docs(verbo): SDD del módulo — contrato + mock + daemon + backends pendientes 781a310c8 · sergio · 5 months ago

1# modules/verbo/ — Provider de embeddings model-agnostic (era dime)
2
3**Propósito.** Capa de embeddings estructuralmente agnóstica al modelo:
4la elección de backend es config por instancia. Los vectores quedan
5atados a su `ModelId` — comparar vectores de modelos distintos es un
6error explícito, no un sinsentido silencioso. Un daemon permite cargar
7un modelo una vez y compartirlo entre procesos.
8
9## Crates
10
11| crate          | tipo | rol                                                          |
12| -------------- | ---- | ------------------------------------------------------------ |
13| `verbo-core`   | lib  | Contrato: `ModelId`, `EmbeddingVector` (cosine), `EmbedError`, trait `Provider` |
14| `verbo-mock`   | lib  | Backend determinista sin modelo (FNV-1a + LCG) — para tests  |
15| `verbo-daemon` | lib  | `Daemon` (sirve un `Provider` por socket Unix) + `DaemonClient` (lo consume como `Provider`) |
16
17## Dependencias
18
19- `mock`, `daemon` ← `verbo-core`.
20- `daemon` ← `tokio` + `postcard` (frames con prefijo de largo).
21- `verbo-core` es `#![forbid(unsafe_code)]`, sólo `serde` + `async-trait`.
22
23## Compartir entre procesos
24
25`verbo-daemon` resuelve la duplicación de modelos en RAM: un `Daemon`
26carga el modelo una vez; N procesos lo consumen vía `DaemonClient`, que
27implementa `Provider` y por tanto es indistinguible de un backend local.
28Multi-instancia = un daemon por modelo, cada uno en su socket.
29
30## Estado
31
32Contrato + mock + daemon implementados y verdes (~25 tests).
33
34**Pendiente** — backends de modelos reales (requieren infra/API keys):
35
36| backend pendiente | tipo   | nota                                          |
37| ----------------- | ------ | --------------------------------------------- |
38| `verbo-cohere`    | remoto | API Cohere — recomendado para uso remoto      |
39| `verbo-bge`       | local  | `bge-code-large` vía ONNX — recomendado local |
40| `verbo-fastembed` | local  | modelos ligeros (MiniLM 384d)                 |
41
42Cada uno implementa `Provider` y puede servirse vía `verbo-daemon` sin
43cambios — el daemon es agnóstico del backend.

SDD.md

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.