tawasuyu/brahman

1//! Clustering determinista (Phase A).
2//!
3//! Estrategia: agrupar por **directorio padre** + ranking por
4//! **extensión dominante**. No hay LLM ni embeddings — sólo metadatos.
5//! Esta capa cubre el 90% de los casos prácticos:
6//!
7//! - Un proyecto Rust en `~/dev/foo/src/` → Mónada coherente (.rs).
8//! - Un dump de fotos en `~/Pictures/2024/` → Mónada con lente Gallery.
9//! - Notas en `~/notes/` → Mónada con lente Markdown.
10//!
11//! Los casos donde esta heurística falla (archivos relacionados pero
12//! dispersos en el FS) son el dominio de los embeddings (Phase C) y
13//! del clustering por Nous (Phase D).
14
15use std::collections::BTreeMap;
16use std::path::PathBuf;
17
18use nouser_card::{FileEntry, Lens, MonadManifest};
19
20use crate::embed;
21
22/// Mínimo de archivos para que un directorio sea promovido a Mónada.
23/// Por debajo de eso, los archivos quedan "huérfanos" (no asignados).
24pub const DEFAULT_MIN_FILES_PER_MONAD: usize = 3;
25
26/// Agrupa archivos en Mónadas por directorio padre.
27///
28/// Devuelve un `Vec<MonadManifest>` ordenado por path. Archivos en
29/// directorios con menos de `min_files` no producen Mónada.
30pub fn by_directory(files: &[FileEntry], min_files: usize) -> Vec<MonadManifest> {
31    by_directory_hydrated(files, min_files, None)
32}
33
34/// Variante con hidratación: si `prior` está presente, busca Mónadas
35/// previas con el mismo `path_hint` y `centroid_model` válido, y reusa
36/// su `id` y `lineage`. Esto preserva identidad across re-scans —
37/// fundamental para que el daemon pueda republicar tras hidratar de
38/// sled sin generar duplicados en el broker.
39pub fn by_directory_hydrated(
40    files: &[FileEntry],
41    min_files: usize,
42    prior: Option<&crate::db::MonadDb>,
43) -> Vec<MonadManifest> {
44    let mut by_parent: BTreeMap<PathBuf, Vec<&FileEntry>> = BTreeMap::new();
45    for f in files {
46        if let Some(parent) = f.path.parent() {
47            by_parent.entry(parent.to_path_buf()).or_default().push(f);
48        }
49    }
50
51    let mut out = Vec::new();
52    for (parent, group) in by_parent {
53        if group.len() < min_files {
54            continue;
55        }
56        let mut m = build_monad(&parent, &group);
57        if let Some(db) = prior {
58            // Reusamos id si encontramos Mónada previa con mismo
59            // path_hint Y mismo centroid_model. Distintas hipótesis
60            // de modelo no comparten identidad — son objetos
61            // semánticos distintos, aunque parecidos.
62            if let Some(existing) = db.monads().find(|prev| {
63                prev.path_hint.as_deref() == m.path_hint.as_deref()
64                    && prev.centroid_model == m.centroid_model
65            }) {
66                m.id = existing.id;
67                m.lineage = existing.lineage;
68                m.created_at_ms = existing.created_at_ms;
69                m.touch();
70            }
71        }
72        out.push(m);
73    }
74    out
75}
76
77fn build_monad(parent: &std::path::Path, group: &[&FileEntry]) -> MonadManifest {
78    let label = label_from_path(parent);
79
80    let keywords = top_extensions(group, 5);
81    let lens = pick_lens(group);
82    let entropy = shannon_entropy_normalized(group);
83
84    let summary = build_summary(parent, group, &keywords);
85
86    // Centroide vectorial: promedio de los embeddings de los miembros.
87    // Esto es lo que permite "atracción" determinista de archivos
88    // nuevos sin tocar Nous.
89    let member_vecs: Vec<Vec<f32>> = group.iter().map(|f| embed::embed(f).to_vec()).collect();
90    let centroid = embed::centroid(&member_vecs);
91
92    let mut m = MonadManifest::new(label);
93    m.summary = summary;
94    m.keywords = keywords;
95    m.dominant_lens = lens;
96    m.entropy = entropy;
97    m.centroid = centroid;
98    // Taggeamos el centroide con su modelo. attract verifica esto
99    // antes de comparar para no mezclar pseudo-32d con real-384d.
100    m.centroid_model = Some(embed::MODEL_ID.to_string());
101    // path_hint = identidad estable across re-scans para
102    // hidratación. Display es lossy con UTF-8 inválido pero los
103    // paths legítimos se imprimen consistentes.
104    m.path_hint = Some(parent.display().to_string());
105    m.members = group.iter().map(|f| f.id).collect();
106    m.touch();
107    m
108}
109
110/// Construye un label legible tomando los últimos hasta 2 componentes
111/// del path. Esto desambigua `src/` repetidos en monorepos: en lugar
112/// de 5 Mónadas con label "src", quedan "ente-zero/src", "ente-brain/src",
113/// etc. Para directorios shallow (root o un nivel), cae al
114/// `file_name()` simple.
115fn label_from_path(p: &std::path::Path) -> String {
116    let normals: Vec<&str> = p
117        .components()
118        .filter_map(|c| match c {
119            std::path::Component::Normal(s) => s.to_str(),
120            _ => None,
121        })
122        .collect();
123    if normals.is_empty() {
124        return "unnamed".to_string();
125    }
126    let take = normals.len().min(2);
127    let start = normals.len() - take;
128    normals[start..].join("/")
129}
130
131fn build_summary(parent: &std::path::Path, group: &[&FileEntry], keywords: &[String]) -> String {
132    let path_str = parent.display();
133    let n = group.len();
134    let exts = if keywords.is_empty() {
135        "(sin extensiones)".to_string()
136    } else {
137        keywords.join(", ")
138    };
139    format!("{n} archivos en {path_str} (ext: {exts})")
140}
141
142/// Top-N extensiones por frecuencia, descendente. Empate por orden alfabético.
143fn top_extensions(files: &[&FileEntry], n: usize) -> Vec<String> {
144    let mut counts: BTreeMap<String, usize> = BTreeMap::new();
145    for f in files {
146        if let Some(ext) = &f.extension {
147            *counts.entry(ext.clone()).or_default() += 1;
148        }
149    }
150    let mut sorted: Vec<_> = counts.into_iter().collect();
151    sorted.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(&b.0)));
152    sorted.into_iter().take(n).map(|(k, _)| k).collect()
153}
154
155/// Elige el lente dominante según la extensión más frecuente.
156fn pick_lens(files: &[&FileEntry]) -> Lens {
157    let dominant = top_extensions(files, 1).into_iter().next();
158    match dominant.as_deref() {
159        Some("rs" | "py" | "ts" | "tsx" | "js" | "jsx" | "go" | "java" | "kt" | "c" | "cpp"
160        | "cc" | "h" | "hpp" | "rb" | "swift" | "zig") => Lens::Code,
161        Some("png" | "jpg" | "jpeg" | "gif" | "webp" | "svg" | "bmp" | "tiff" | "heic") => {
162            Lens::Gallery
163        }
164        Some("md" | "markdown" | "rst" | "txt" | "org" | "tex") => Lens::Markdown,
165        Some("db" | "sqlite" | "sqlite3" | "csv" | "tsv" | "parquet") => Lens::Database,
166        _ => Lens::Grid,
167    }
168}
169
170/// Entropía de Shannon normalizada sobre la distribución de extensiones.
171/// `0.0` = todos los archivos comparten extensión. `1.0` = uniformly
172/// distributed entre `n` extensiones (máx información).
173fn shannon_entropy_normalized(files: &[&FileEntry]) -> f32 {
174    let total = files.len() as f32;
175    if total <= 1.0 {
176        return 0.0;
177    }
178    let mut counts: BTreeMap<String, usize> = BTreeMap::new();
179    for f in files {
180        let ext = f.extension.as_deref().unwrap_or("(none)");
181        *counts.entry(ext.to_string()).or_default() += 1;
182    }
183    let entropy: f32 = counts
184        .values()
185        .map(|&c| {
186            let p = c as f32 / total;
187            -p * p.log2()
188        })
189        .sum();
190    let max_entropy = (counts.len() as f32).log2();
191    if max_entropy <= 0.0 {
192        0.0
193    } else {
194        (entropy / max_entropy).clamp(0.0, 1.0)
195    }
196}
197
198#[cfg(test)]
199mod tests {
200    use super::*;
201    use nouser_card::FileId;
202    use std::path::PathBuf;
203    use ulid::Ulid;
204
205    fn mkfile(path: &str, ext: Option<&str>) -> FileEntry {
206        FileEntry {
207            id: FileId::from(Ulid::new()),
208            path: PathBuf::from(path),
209            content_hash: None,
210            size: 100,
211            mtime_ms: 0,
212            extension: ext.map(String::from),
213        }
214    }
215
216    #[test]
217    fn groups_by_parent_directory() {
218        let files = vec![
219            mkfile("/proj/src/a.rs", Some("rs")),
220            mkfile("/proj/src/b.rs", Some("rs")),
221            mkfile("/proj/src/c.rs", Some("rs")),
222            mkfile("/proj/docs/readme.md", Some("md")),
223            mkfile("/proj/docs/guide.md", Some("md")),
224            mkfile("/proj/docs/notes.md", Some("md")),
225        ];
226        let monads = by_directory(&files, 3);
227        assert_eq!(monads.len(), 2);
228        let labels: std::collections::BTreeSet<_> = monads.iter().map(|m| &m.label).collect();
229        // Phase B: labels usan los últimos 2 componentes del path para
230        // desambiguar (proj/src vs proj/docs en lugar de src vs docs).
231        assert!(labels.iter().any(|l| l.as_str() == "proj/src"));
232        assert!(labels.iter().any(|l| l.as_str() == "proj/docs"));
233    }
234
235    #[test]
236    fn small_groups_not_promoted() {
237        let files = vec![
238            mkfile("/proj/single.txt", Some("txt")),
239            mkfile("/proj/sub/a.txt", Some("txt")),
240            mkfile("/proj/sub/b.txt", Some("txt")),
241            mkfile("/proj/sub/c.txt", Some("txt")),
242        ];
243        // min=3 → /proj/single solo no se promueve, /proj/sub sí.
244        let monads = by_directory(&files, 3);
245        assert_eq!(monads.len(), 1);
246        assert_eq!(monads[0].label, "proj/sub");
247    }
248
249    #[test]
250    fn label_from_root_only_one_component() {
251        // Un solo componente normal en el path → no hay "padre" útil.
252        let p = std::path::Path::new("/onlyone");
253        assert_eq!(label_from_path(p), "onlyone");
254    }
255
256    #[test]
257    fn label_from_deep_path_takes_last_two() {
258        let p = std::path::Path::new("/a/b/c/d/e");
259        assert_eq!(label_from_path(p), "d/e");
260    }
261
262    #[test]
263    fn lens_picked_by_dominant_extension() {
264        let files = vec![
265            mkfile("/x/a.rs", Some("rs")),
266            mkfile("/x/b.rs", Some("rs")),
267            mkfile("/x/c.rs", Some("rs")),
268        ];
269        let monads = by_directory(&files, 3);
270        assert_eq!(monads[0].dominant_lens, Lens::Code);
271
272        let files = vec![
273            mkfile("/y/1.png", Some("png")),
274            mkfile("/y/2.png", Some("png")),
275            mkfile("/y/3.png", Some("png")),
276        ];
277        let monads = by_directory(&files, 3);
278        assert_eq!(monads[0].dominant_lens, Lens::Gallery);
279    }
280
281    #[test]
282    fn entropy_zero_for_homogeneous() {
283        let files = vec![
284            mkfile("/x/a.rs", Some("rs")),
285            mkfile("/x/b.rs", Some("rs")),
286            mkfile("/x/c.rs", Some("rs")),
287        ];
288        let monads = by_directory(&files, 3);
289        assert_eq!(monads[0].entropy, 0.0);
290    }
291
292    #[test]
293    fn entropy_high_for_diverse() {
294        let files = vec![
295            mkfile("/x/a.rs", Some("rs")),
296            mkfile("/x/b.md", Some("md")),
297            mkfile("/x/c.json", Some("json")),
298            mkfile("/x/d.png", Some("png")),
299        ];
300        let monads = by_directory(&files, 3);
301        // 4 extensiones distintas, distribución uniforme → entropy ≈ 1.0
302        assert!(monads[0].entropy > 0.9, "got {}", monads[0].entropy);
303    }
304
305    #[test]
306    fn top_extensions_orders_by_freq_then_alpha() {
307        let files = vec![
308            mkfile("/x/a.rs", Some("rs")),
309            mkfile("/x/b.rs", Some("rs")),
310            mkfile("/x/c.md", Some("md")),
311            mkfile("/x/d.py", Some("py")),
312        ];
313        let refs: Vec<&FileEntry> = files.iter().collect();
314        let top = top_extensions(&refs, 3);
315        assert_eq!(top, vec!["rs", "md", "py"]);
316    }
317}