1use std::collections::{BTreeMap, BTreeSet};
6
7use qualia_cooperative_core::contextual_evidence::{ClaimBasis, EvidenceValue, EvidencedAssertion};
8use serde::{Deserialize, Serialize};
9
10use crate::q42_volume::IngestProvenanceRecord;
11
12pub const SPECIES_CORPUS_CONTEXT: &str = "https://webizen.org/ns/qualia/species-corpus/v1";
13pub const SPECIES_CORPUS_TYPE: &str = "QualiaSpeciesCorpus";
14pub const SPECIES_CORPUS_FORMAT: &str = "qualia.q42.species-corpus.v1";
15pub const MAX_CORPUS_ASSERTIONS: usize = 1_000_000;
16
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19pub struct CorpusSource {
20 pub id: String,
21 pub title: String,
22 #[serde(default, skip_serializing_if = "Option::is_none")]
23 pub citation: Option<String>,
24 #[serde(default, skip_serializing_if = "Option::is_none")]
25 pub retrieved_at: Option<String>,
26 pub access_policy: String,
27 pub source_sha256: String,
28 pub mapping_version: String,
29 #[serde(default, skip_serializing_if = "Option::is_none")]
30 pub licence_iri: Option<String>,
31}
32
33impl CorpusSource {
34 pub fn from_ingest(id: &str, title: &str, record: &IngestProvenanceRecord) -> Self {
36 Self {
37 id: id.to_string(),
38 title: title.to_string(),
39 citation: None,
40 retrieved_at: None,
41 access_policy: record.access_policy.clone(),
42 source_sha256: record.source_sha256.clone(),
43 mapping_version: record.mapping_version.clone(),
44 licence_iri: None,
45 }
46 }
47}
48
49#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
51#[serde(rename_all = "snake_case")]
52pub enum KnowledgeGroup {
53 IdentifiersTaxonomy,
54 MorphologyAnatomy,
55 DevelopmentReproduction,
56 PhysiologyBehaviour,
57 Ecology,
58 DistributionObservations,
59 MolecularCellular,
60 ConservationHumanRelations,
61 RepresentationsMedia,
62 ProvenanceOperation,
63}
64
65#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
67pub struct KnowledgeGap {
68 pub id: String,
69 pub group: KnowledgeGroup,
70 pub property_iri: String,
71 #[serde(default, skip_serializing_if = "Option::is_none")]
72 pub part_iri: Option<String>,
73 pub reason: String,
74}
75
76#[derive(Debug, Clone, PartialEq)]
78pub struct CorpusFact<'a> {
79 pub assertion_id: &'a str,
80 pub property_iri: &'a str,
81 pub basis: &'a str,
82 pub active: bool,
83 pub min: Option<f64>,
84 pub max: Option<f64>,
85 pub unit_iri: Option<&'a str>,
86 pub text: Option<&'a str>,
87}
88
89#[derive(Debug, Clone, PartialEq, Eq)]
91pub struct CorpusConflict {
92 pub property_iri: String,
93 pub scope_key: String,
94 pub assertion_ids: Vec<String>,
95}
96
97#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
98pub struct SpeciesCorpus {
99 #[serde(rename = "@context")]
100 pub context: String,
101 #[serde(rename = "@type")]
102 pub type_: String,
103 pub format: String,
104 pub corpus_iri: String,
105 pub taxon_concept_iri: String,
106 pub species_id: String,
107 pub revision: String,
108 #[serde(default)]
109 pub sources: Vec<CorpusSource>,
110 #[serde(default)]
111 pub assertions: Vec<EvidencedAssertion>,
112 #[serde(default)]
113 pub gaps: Vec<KnowledgeGap>,
114}
115
116fn require(v: &str, what: &str) -> Result<(), String> {
117 if v.trim().is_empty() {
118 Err(format!("species corpus {what} is empty"))
119 } else {
120 Ok(())
121 }
122}
123
124fn unique<'a>(ids: impl Iterator<Item = &'a str>, what: &str) -> Result<BTreeSet<&'a str>, String> {
125 let mut seen = BTreeSet::new();
126 for id in ids {
127 require(id, &format!("{what} id"))?;
128 if !seen.insert(id) {
129 return Err(format!("duplicate {what} id '{id}'"));
130 }
131 }
132 Ok(seen)
133}
134
135impl SpeciesCorpus {
136 pub fn new(corpus_iri: &str, taxon_concept_iri: &str, species_id: &str, revision: &str) -> Self {
137 Self {
138 context: SPECIES_CORPUS_CONTEXT.to_string(),
139 type_: SPECIES_CORPUS_TYPE.to_string(),
140 format: SPECIES_CORPUS_FORMAT.to_string(),
141 corpus_iri: corpus_iri.to_string(),
142 taxon_concept_iri: taxon_concept_iri.to_string(),
143 species_id: species_id.to_string(),
144 revision: revision.to_string(),
145 sources: Vec::new(),
146 assertions: Vec::new(),
147 gaps: Vec::new(),
148 }
149 }
150
151 pub fn from_json_value(value: serde_json::Value) -> Result<Self, String> {
153 let corpus: Self =
154 serde_json::from_value(value).map_err(|e| format!("species corpus json: {e}"))?;
155 corpus.validate()?;
156 Ok(corpus)
157 }
158
159 pub fn validate(&self) -> Result<(), String> {
161 if self.context != SPECIES_CORPUS_CONTEXT || self.format != SPECIES_CORPUS_FORMAT {
162 return Err("not a species corpus v1 document".into());
163 }
164 require(&self.corpus_iri, "corpus_iri")?;
165 require(&self.taxon_concept_iri, "taxon_concept_iri")?;
166 require(&self.species_id, "species_id")?;
167 require(&self.revision, "revision")?;
168 if self.assertions.len() > MAX_CORPUS_ASSERTIONS {
169 return Err(format!("species corpus exceeds {MAX_CORPUS_ASSERTIONS} assertions"));
170 }
171 let source_ids = unique(self.sources.iter().map(|s| s.id.as_str()), "source")?;
172 unique(self.assertions.iter().map(|a| a.assertion.id.as_str()), "assertion")?;
173 unique(self.gaps.iter().map(|g| g.id.as_str()), "gap")?;
174 for s in &self.sources {
175 require(&s.title, &format!("source '{}' title", s.id))?;
176 if s.source_sha256.len() != 64 || !s.source_sha256.bytes().all(|b| b.is_ascii_hexdigit()) {
177 return Err(format!("source '{}' source_sha256 must be 64 hex digits", s.id));
178 }
179 }
180 for ea in &self.assertions {
181 let id = &ea.assertion.id;
182 ea.validate().map_err(|e| format!("assertion '{id}': {e}"))?;
183 let root = ea.assertion.root_source_id.as_str();
184 if !root.is_empty() && !source_ids.contains(root) {
185 return Err(format!("assertion '{id}' cites unknown source '{root}'"));
186 }
187 if let Some(t) = &ea.evidence.scope.taxon_concept_iri {
188 if t != &self.taxon_concept_iri {
189 return Err(format!(
190 "assertion '{id}' is scoped to taxon '{t}', not the corpus taxon"
191 ));
192 }
193 }
194 }
195 for g in &self.gaps {
196 require(&g.property_iri, &format!("gap '{}' property_iri", g.id))?;
197 require(&g.reason, &format!("gap '{}' reason", g.id))?;
198 }
199 Ok(())
200 }
201
202 pub fn facts(&self) -> Vec<CorpusFact<'_>> {
204 use qualia_cooperative_core::contextual_assertion::AssertionStatus;
205 use qualia_cooperative_core::contextual_evidence::EvidenceValue;
206 self.assertions
207 .iter()
208 .map(|a| {
209 let (min, max, unit_iri, text) = match &a.evidence.value {
210 Some(EvidenceValue::Quantity { value, unit_iri }) => {
211 (Some(*value), Some(*value), Some(unit_iri.as_str()), None)
212 }
213 Some(EvidenceValue::Range { min, max, unit_iri }) => {
214 (Some(*min), Some(*max), Some(unit_iri.as_str()), None)
215 }
216 Some(EvidenceValue::Text { text, .. }) => (None, None, None, Some(text.as_str())),
217 Some(EvidenceValue::Iri { iri }) => (None, None, None, Some(iri.as_str())),
218 None => (None, None, None, None),
219 };
220 CorpusFact {
221 assertion_id: a.assertion.id.as_str(),
222 property_iri: a.evidence.property_iri.as_str(),
223 basis: a.evidence.basis.as_str(),
224 active: a.assertion.assertion_status == AssertionStatus::Active,
225 min,
226 max,
227 unit_iri,
228 text,
229 }
230 })
231 .collect()
232 }
233
234 pub fn assertions_for<'a>(
236 &'a self,
237 property_iri: &'a str,
238 part_iri: Option<&'a str>,
239 ) -> impl Iterator<Item = &'a EvidencedAssertion> + 'a {
240 use qualia_cooperative_core::contextual_assertion::AssertionStatus;
241 self.assertions.iter().filter(move |a| {
242 a.evidence.property_iri == property_iri
243 && a.assertion.assertion_status == AssertionStatus::Active
244 && part_iri.map_or(true, |p| a.evidence.scope.part_iri.as_deref() == Some(p))
245 })
246 }
247
248 pub fn conflicts(&self) -> Vec<CorpusConflict> {
251 let mut groups: BTreeMap<(String, String), Vec<&EvidencedAssertion>> = BTreeMap::new();
252 for a in &self.assertions {
253 if matches!(
254 a.evidence.basis,
255 ClaimBasis::ModelAssumption | ClaimBasis::ArtisticChoice | ClaimBasis::Unknown
256 ) || a.evidence.value.is_none()
257 {
258 continue;
259 }
260 let s = &a.evidence.scope;
261 let scope_key = format!(
262 "{}|{}|{}|{}|{}",
263 s.part_iri.as_deref().unwrap_or(""),
264 s.life_stage_iri.as_deref().unwrap_or(""),
265 s.sex_iri.as_deref().unwrap_or(""),
266 s.population_iri.as_deref().unwrap_or(""),
267 s.individual_iri.as_deref().unwrap_or("")
268 );
269 groups
270 .entry((a.evidence.property_iri.clone(), scope_key))
271 .or_default()
272 .push(a);
273 }
274 let mut out = Vec::new();
275 for ((property_iri, scope_key), items) in groups {
276 let roots: BTreeSet<&str> =
277 items.iter().map(|a| a.assertion.root_source_id.as_str()).collect();
278 if roots.len() < 2 {
279 continue;
280 }
281 let first = items[0].evidence.value.as_ref();
282 if items.iter().any(|a| !values_compatible(first, a.evidence.value.as_ref())) {
283 out.push(CorpusConflict {
284 property_iri,
285 scope_key,
286 assertion_ids: items.iter().map(|a| a.assertion.id.clone()).collect(),
287 });
288 }
289 }
290 out
291 }
292}
293
294fn values_compatible(a: Option<&EvidenceValue>, b: Option<&EvidenceValue>) -> bool {
296 fn span(v: &EvidenceValue) -> Option<(f64, f64, &str)> {
297 match v {
298 EvidenceValue::Quantity { value, unit_iri } => Some((*value, *value, unit_iri)),
299 EvidenceValue::Range { min, max, unit_iri } => Some((*min, *max, unit_iri)),
300 _ => None,
301 }
302 }
303 match (a, b) {
304 (Some(x), Some(y)) => match (span(x), span(y)) {
305 (Some((a0, a1, ua)), Some((b0, b1, ub))) => ua == ub && a0 <= b1 && b0 <= a1,
306 _ => x == y,
307 },
308 _ => true,
309 }
310}