Skip to main content

qualia_semantic_library/llm/
mod.rs

1//! The external-LLM seam. Embeddings and structured method-extraction are the
2//! only steps that need a language model; everything else in the crate is
3//! deterministic. That model is reached **over HTTP behind this trait**, so it
4//! can be a local Ollama server today, a hosted API tomorrow, or the native
5//! QualiaDB engine later — without touching the rest of the pipeline. It is
6//! never compiled into QualiaDB's core inference path.
7
8pub mod ollama;
9pub use ollama::OllamaBackend;
10
11use serde::Deserialize;
12
13use crate::container::{AssetKind, HmcWriter};
14use crate::embedding::encode_f32_matrix;
15
16/// A swappable language-model backend.
17pub trait LlmBackend {
18    /// Embed a batch of texts. Returns one vector per input, all of the same
19    /// dimensionality (`embed_dim`).
20    fn embed(&self, texts: &[String]) -> anyhow::Result<Vec<Vec<f32>>>;
21
22    /// Free-form completion used for structured extraction. `system` sets the
23    /// instruction; `prompt` carries the chunk. Implementations should request
24    /// non-streaming output.
25    fn generate(&self, system: &str, prompt: &str) -> anyhow::Result<String>;
26
27    /// Embedding dimensionality, if known ahead of a call (0 = discover on first embed).
28    fn embed_dim(&self) -> u32;
29
30    /// Identifier recorded in the container manifest (e.g. `ollama/nomic-embed-text`).
31    fn model_id(&self) -> String;
32}
33
34/// Minimal view of a stored chunk — only what embedding needs (decoupled from
35/// the `ingest` module so the LLM seam compiles without the `pdf` feature).
36#[derive(Deserialize)]
37struct StoredChunk {
38    text: String,
39}
40
41/// Enrichment pass: open a container, embed its chunks with `backend`, and write
42/// the embedding matrix + updated manifest back into the same container.
43pub fn embed_container(path: &std::path::Path, backend: &dyn LlmBackend) -> anyhow::Result<usize> {
44    let mut writer = HmcWriter::reopen(path)?;
45
46    let texts: Vec<String> = {
47        let mut c = crate::container::HmcContainer::open(path)?;
48        let jsonl = c.read_kind(AssetKind::Chunks)?;
49        String::from_utf8_lossy(&jsonl)
50            .lines()
51            .filter_map(|l| serde_json::from_str::<StoredChunk>(l).ok())
52            .map(|c| c.text)
53            .collect()
54    };
55    if texts.is_empty() {
56        return Ok(0);
57    }
58
59    let vectors = backend.embed(&texts)?;
60    let dim = vectors.first().map(|v| v.len()).unwrap_or(0) as u32;
61
62    let bytes = encode_f32_matrix(&vectors);
63    writer.add_derived(
64        AssetKind::Embeddings,
65        "vectors.f32",
66        "application/octet-stream",
67        bytes,
68    );
69
70    let pipeline = &mut writer.manifest_mut().pipeline;
71    pipeline.embedder = backend.model_id();
72    pipeline.embed_dim = dim;
73    writer.manifest_mut().status.embedded = true;
74
75    let dir = path.parent().unwrap_or(std::path::Path::new("."));
76    writer.write_to_dir(dir)?;
77    Ok(vectors.len())
78}
79
80const TAG_SYSTEM: &str = "You are a librarian for a formal-methods / mathematics / \
81logic / computing research library. Given an excerpt, reply with 1 to 4 short \
82lowercase topical tags (single words or hyphenated), comma-separated, no prose, \
83no explanation. Prefer tags like: logic, deontic, algebra, category-theory, \
84optimization, numerics, machine-learning, nlp, crypto, zero-knowledge, \
85semantic-web, ontology, graph-theory, probability.";
86
87/// Analysis pass: ask the backend for topical tags from the document's leading
88/// chunks and write them into the container manifest (drives reorganise/route).
89pub fn analyze_container(
90    path: &std::path::Path,
91    backend: &dyn LlmBackend,
92) -> anyhow::Result<Vec<String>> {
93    let excerpt: String = {
94        let mut c = crate::container::HmcContainer::open(path)?;
95        let jsonl = c.read_kind(AssetKind::Chunks)?;
96        String::from_utf8_lossy(&jsonl)
97            .lines()
98            .filter_map(|l| serde_json::from_str::<StoredChunk>(l).ok())
99            .take(4)
100            .map(|c| c.text)
101            .collect::<Vec<_>>()
102            .join("\n\n")
103    };
104    if excerpt.trim().is_empty() {
105        return Ok(vec![]);
106    }
107    let raw = backend.generate(TAG_SYSTEM, &truncate_chars(&excerpt, 6000))?;
108    let tags = parse_tags(&raw);
109
110    let mut writer = HmcWriter::reopen(path)?;
111    writer.manifest_mut().tags = tags.clone();
112    writer.manifest_mut().status.analyzed = true;
113    let dir = path.parent().unwrap_or(std::path::Path::new("."));
114    writer.write_to_dir(dir)?;
115    Ok(tags)
116}
117
118fn parse_tags(raw: &str) -> Vec<String> {
119    raw.split([',', '\n'])
120        .map(|t| {
121            t.trim()
122                .trim_matches(|c: char| !c.is_alphanumeric() && c != '-')
123                .to_ascii_lowercase()
124        })
125        .filter(|t| !t.is_empty() && t.len() <= 30)
126        .take(4)
127        .collect()
128}
129
130fn truncate_chars(s: &str, max: usize) -> String {
131    if s.chars().count() <= max {
132        return s.to_string();
133    }
134    s.chars().take(max).collect()
135}