khive-runtime 0.12.0

Composable Service API: entity/note CRUD, graph traversal, hybrid search, curation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

//! Required synchronous index effects for admitted entity candidates.

use super::*;

impl KhiveRuntime {
    /// Prepare required index effects before an admitted entity takes its writer.
    /// Bulk and direct structural ingest deliberately defer dense vectors.
    pub(crate) async fn prepare_admitted_entity_indexes(
        &self,
        token: &NamespaceToken,
        entity: &Entity,
        attachments: &[Attachment],
        embed: bool,
    ) -> RuntimeResult<(
        Vec<PlanStatement>,
        crate::retrieval::EmbeddingTruncationReport,
    )> {
        let _ = self.entities(token)?;
        let _ = self.text(token)?;
        let document = entity_fts_document(entity);
        let mut statements = vec![PlanStatement {
            statement: khive_db::stores::text::delete_document_statement(
                "fts_entities",
                &entity.namespace,
                entity.id,
            ),
            guard: None,
        }];
        statements.extend(
            insert_document_statements("fts_entities", &document)
                .into_iter()
                .map(|statement| PlanStatement {
                    statement,
                    guard: Some(AffectedRowGuard::exactly(1)),
                }),
        );
        for attachment in attachments {
            statements.push(PlanStatement {
                statement: khive_db::stores::attachment::attachment_upsert_statement(attachment)?,
                guard: Some(AffectedRowGuard::exactly(1)),
            });
        }
        let mut report = crate::retrieval::EmbeddingTruncationReport::default();
        if !embed {
            return Ok((statements, report));
        }

        let models = self.registered_embedding_model_names();
        let model_metadata = models
            .iter()
            .map(|name| {
                self.vector_model_metadata(name)
                    .map(|(name, dimensions)| (crate::config::sanitize_key(&name), dimensions))
            })
            .collect::<RuntimeResult<Vec<_>>>()?;
        let model_specs: Vec<_> = model_metadata
            .iter()
            .map(|(key, dimensions)| (key.as_str(), *dimensions))
            .collect();
        if !model_specs.is_empty() {
            self.backend().ensure_vector_tables(&model_specs)?;
        }
        for (model, (table_key, dimensions)) in models.iter().zip(model_metadata.iter()) {
            let outcome = self
                .embed_document_with_model_outcome_for_token(token, model, &document.body)
                .await?;
            if outcome.vector.len() != *dimensions {
                return Err(RuntimeError::InvalidInput(format!(
                    "entity embedding dimension mismatch for model {model}"
                )));
            }
            if outcome.vector.iter().any(|value| !value.is_finite()) {
                return Err(RuntimeError::InvalidInput(
                    "entity embedding contains a non-finite value".into(),
                ));
            }
            report.observe(&outcome);
            statements.extend(
                crate::atomic_message::vector_insert_statements_for_substrate(
                    &format!("vec_{table_key}"),
                    &entity.namespace,
                    entity.id,
                    SubstrateKind::Entity,
                    "entity.body",
                    model,
                    &outcome.vector,
                    "entity-finalizer-vector",
                    Some(AffectedRowGuard::exactly(1)),
                ),
            );
        }
        Ok((statements, report))
    }
}