Skip to main content

qualia_client_core/
poet_library_provider.rs

1//! Persistent Semantic Library provider for the POET loopback API.
2
3use std::{path::PathBuf, sync::Mutex};
4
5use ed25519_dalek::SigningKey;
6use qualia_core_db::services::poet_library_api::{
7    register_poet_library_provider as register_provider, PoetLibraryIngestRequest,
8    PoetLibraryProvider, PoetLibraryQueryRequest,
9};
10
11use crate::wellfair::{
12    api::{library_stats_at, query_library_faceted_at, ManualFacets, WebizenHostApi},
13    policy::PolicyDecisionService,
14    vault::VaultService,
15};
16
17pub struct SemanticLibraryProvider {
18    storage_root: PathBuf,
19    host: Mutex<Option<WebizenHostApi>>,
20    ingest_diagnostic: Option<String>,
21}
22
23impl SemanticLibraryProvider {
24    /// Creates a new instance.
25    pub fn new(storage_root: PathBuf, signing_key_bytes: [u8; 32]) -> Self {
26        let _ = std::fs::create_dir_all(&storage_root);
27        let author_did_hash = qualia_core_db::q_hash("did:q42:local");
28        let wal_path = storage_root.join("qualia_global.wal");
29        let host = VaultService::open(&wal_path, &storage_root, author_did_hash).map(|vault| {
30            WebizenHostApi::new(
31                vault,
32                PolicyDecisionService::new(),
33                SigningKey::from_bytes(&signing_key_bytes),
34                "did:q42:wellfair:owner".into(),
35                "did:q42:wellfair:owner".into(),
36                storage_root.clone(),
37            )
38        });
39        let (host, ingest_diagnostic) = match host {
40            Ok(host) => (Some(host), None),
41            Err(error) => (
42                None,
43                Some(format!(
44                    "Semantic Library reads are available, but ingestion could not open its vault: {error}"
45                )),
46            ),
47        };
48        Self {
49            storage_root,
50            host: Mutex::new(host),
51            ingest_diagnostic,
52        }
53    }
54}
55
56/// Registers a semantic library provider.
57pub fn register_semantic_library_provider(
58    storage_root: PathBuf,
59    signing_key_bytes: [u8; 32],
60) -> Result<(), String> {
61    register_provider(std::sync::Arc::new(SemanticLibraryProvider::new(
62        storage_root,
63        signing_key_bytes,
64    )))
65    .map_err(str::to_string)
66}
67
68impl PoetLibraryProvider for SemanticLibraryProvider {
69    fn stats(&self) -> Result<serde_json::Value, String> {
70        library_stats_at(&self.storage_root)
71    }
72
73    fn query(&self, request: &PoetLibraryQueryRequest) -> Result<serde_json::Value, String> {
74        let filter = serde_json::json!({
75            "section": request.section,
76            "text": if request.query.is_empty() { None } else { Some(&request.query) },
77            "topics": request.topics,
78            "purposes": request.purposes,
79            "projects": request.projects,
80            "media_types": request.media_types,
81            "categories": request.categories,
82        });
83        query_library_faceted_at(
84            &self.storage_root,
85            &serde_json::to_string(&filter).map_err(|error| error.to_string())?,
86            request.sort.as_deref().unwrap_or("newest"),
87        )
88    }
89
90    fn ingest(&self, request: &PoetLibraryIngestRequest) -> Result<serde_json::Value, String> {
91        let guard = self
92            .host
93            .lock()
94            .map_err(|_| "Semantic Library host lock was poisoned".to_string())?;
95        let host = guard.as_ref().ok_or_else(|| {
96            self.ingest_diagnostic
97                .clone()
98                .unwrap_or_else(|| "Semantic Library ingestion is unavailable".into())
99        })?;
100        let manual = ManualFacets {
101            occurred_at: request.occurred_at,
102            place_label: request.place_label.clone(),
103            lat: request.lat,
104            lon: request.lon,
105            projects: request.projects.clone(),
106            purposes: request.purposes.clone(),
107            sensitivity: request.sensitivity.clone(),
108            section: request.section.clone(),
109            commons_visibility: None,
110        };
111        host.ingest_document_annotated(
112            &request.uri,
113            &request.media_type,
114            &request.text,
115            &manual,
116            None,
117        )
118    }
119}
120
121#[cfg(test)]
122mod tests {
123    use super::*;
124
125    #[test]
126    fn ingested_document_is_persistent_and_semantically_queryable() {
127        let dir = tempfile::tempdir().unwrap();
128        let provider = SemanticLibraryProvider::new(dir.path().to_path_buf(), [7; 32]);
129        let result = provider
130            .ingest(&PoetLibraryIngestRequest {
131                uri: "urn:poet:test:library".into(),
132                media_type: "text/markdown".into(),
133                text: "# Catchment plan\nWater stewardship and ecological restoration.".into(),
134                section: Some("work".into()),
135                sensitivity: Some("public".into()),
136                projects: vec!["catchment".into()],
137                purposes: vec!["restoration".into()],
138                occurred_at: None,
139                place_label: None,
140                lat: None,
141                lon: None,
142            })
143            .unwrap();
144        assert_eq!(result["asset_uri"], "urn:poet:test:library");
145
146        let reopened = SemanticLibraryProvider::new(dir.path().to_path_buf(), [7; 32]);
147        let query = reopened
148            .query(&PoetLibraryQueryRequest {
149                query: "stewardship".into(),
150                section: Some("work".into()),
151                ..Default::default()
152            })
153            .unwrap();
154        assert_eq!(query["total"], 1);
155        assert_eq!(query["entries"][0]["asset_uri"], "urn:poet:test:library");
156    }
157}