cortext 1.3.1

Rust bindings for the Cortext multimodal memory engine
Documentation
use std::fs::{self, File};
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};
use std::sync::Mutex;

use serde::Deserialize;
use sha2::{Digest, Sha256};

use crate::assets::{ensure_assets, models_root_from_assets};
use crate::error::Error;

const MODEL_ASSET_NAME: &str = "AIST-87M-GGUF/AIST-87M_q8_0.gguf";
const VOCAB_ASSET_NAME: &str = "mdbr-leaf-ir/vocab.txt";

#[derive(Debug, Deserialize)]
struct ModelManifest {
    assets: Vec<ModelAsset>,
}

#[derive(Debug, Deserialize)]
struct ModelAsset {
    filename: String,
    sha256: String,
    #[serde(default)]
    chunks: Vec<ModelChunk>,
}

#[derive(Debug, Deserialize)]
struct ModelChunk {
    filename: String,
    sha256: String,
}

static MATERIALIZE: Mutex<()> = Mutex::new(());

/// Reassemble AIST model chunks from the release asset tree into a local cache.
///
/// Release natives embed AIST and assemble it inside the library on first create.
/// Call this only when an external filesystem GGUF is required.
pub fn materialize_model(db_path: &str) -> Result<PathBuf, Error> {
    let cache_dir = model_cache_dir(db_path)?;
    let _guard = MATERIALIZE
        .lock()
        .map_err(|_| Error::new("model lock poisoned"))?;
    let root = ensure_assets()?;
    let models_root = models_root_from_assets(&root);
    materialize_model_locked(&cache_dir, &models_root)
}

/// Resolve the AIST GGUF from release asset chunks (Python `resolve_aist_model`).
pub fn resolve_aist_model(db_path: &str) -> Result<PathBuf, Error> {
    materialize_model(db_path)
}

/// Python `clear_materialize_cache` counterpart. Rust verifies files by checksum,
/// so this is a no-op kept for feature parity.
pub fn clear_materialize_cache() {}

fn model_cache_dir(db_path: &str) -> Result<PathBuf, Error> {
    if let Ok(env) = std::env::var("CORTEXT_MODEL_CACHE_DIR") {
        let env = env.trim();
        if !env.is_empty() {
            return Ok(PathBuf::from(env));
        }
    }
    if !db_path.is_empty() && db_path != ":memory:" {
        if let Ok(abs) = std::fs::canonicalize(Path::new(db_path)).or_else(|_| {
            Ok::<_, Error>(if Path::new(db_path).is_absolute() {
                PathBuf::from(db_path)
            } else {
                std::env::current_dir()?.join(db_path)
            })
        }) {
            if let Some(parent) = abs.parent() {
                return Ok(parent.join(".cortext-assets"));
            }
        }
    }
    if let Ok(cwd) = std::env::current_dir() {
        return Ok(cwd.join(".cortext-assets"));
    }
    Ok(crate::assets::default_user_cache_root()?.join("models"))
}

fn materialize_model_locked(cache_dir: &Path, models_root: &Path) -> Result<PathBuf, Error> {
    let manifest = load_model_manifest(models_root)?;
    let asset = find_model_asset(&manifest, MODEL_ASSET_NAME)?;
    if asset.chunks.is_empty() {
        return Err(Error::new(format!(
            "cortext model asset {MODEL_ASSET_NAME} has no chunks declared"
        )));
    }
    let model_path = cache_dir.join(MODEL_ASSET_NAME);
    if file_has_sha256(&model_path, &asset.sha256) {
        ensure_vocab_in_cache(cache_dir, models_root, &manifest)?;
        return Ok(model_path);
    }
    if let Some(parent) = model_path.parent() {
        fs::create_dir_all(parent)?;
    }
    ensure_vocab_in_cache(cache_dir, models_root, &manifest)?;
    let tmp_path = model_path.with_extension("tmp");
    let mut tmp = File::create(&tmp_path)?;
    let mut hasher = Sha256::new();
    for chunk in &asset.chunks {
        let chunk_path = models_root.join(&chunk.filename);
        match file_sha256(&chunk_path) {
            Some(actual) if actual == chunk.sha256 => {}
            Some(actual) => {
                let _ = fs::remove_file(&tmp_path);
                return Err(Error::new(format!(
                    "cortext model chunk checksum mismatch: {} (got {actual})",
                    chunk.filename
                )));
            }
            None => {
                let _ = fs::remove_file(&tmp_path);
                return Err(Error::new(format!(
                    "cortext model chunk missing: {}",
                    chunk.filename
                )));
            }
        }
        let mut input = File::open(&chunk_path)?;
        let mut buf = [0u8; 64 * 1024];
        loop {
            let n = input.read(&mut buf)?;
            if n == 0 {
                break;
            }
            tmp.write_all(&buf[..n])?;
            hasher.update(&buf[..n]);
        }
    }
    tmp.flush()?;
    drop(tmp);
    let actual = format!("{:x}", hasher.finalize());
    if actual != asset.sha256 {
        let _ = fs::remove_file(&tmp_path);
        return Err(Error::new(format!(
            "cortext reassembled model checksum mismatch: got {actual} want {}",
            asset.sha256
        )));
    }
    fs::rename(&tmp_path, &model_path).or_else(|_| {
        fs::copy(&tmp_path, &model_path).map(|_| ())?;
        let _ = fs::remove_file(&tmp_path);
        Ok::<(), io::Error>(())
    })?;
    Ok(model_path)
}

fn ensure_vocab_in_cache(
    cache_dir: &Path,
    models_root: &Path,
    manifest: &ModelManifest,
) -> Result<(), Error> {
    let asset = find_model_asset(manifest, VOCAB_ASSET_NAME)?;
    let dest = cache_dir.join(VOCAB_ASSET_NAME);
    if file_has_sha256(&dest, &asset.sha256) {
        return Ok(());
    }
    let src = models_root.join(VOCAB_ASSET_NAME);
    match file_sha256(&src) {
        Some(actual) if actual == asset.sha256 => {}
        Some(_) => {
            return Err(Error::new(format!(
                "cortext vocab checksum mismatch: {VOCAB_ASSET_NAME}"
            )))
        }
        None => {
            return Err(Error::new(format!(
                "cortext vocab asset missing: {VOCAB_ASSET_NAME}"
            )))
        }
    }
    if let Some(parent) = dest.parent() {
        fs::create_dir_all(parent)?;
    }
    fs::copy(src, dest)?;
    Ok(())
}

fn load_model_manifest(models_root: &Path) -> Result<ModelManifest, Error> {
    let path = models_root.join("manifest.json");
    let data = fs::read(&path)
        .map_err(|e| Error::new(format!("cortext model manifest unreadable: {e}")))?;
    serde_json::from_slice(&data)
        .map_err(|e| Error::new(format!("cortext model manifest invalid: {e}")))
}

fn find_model_asset<'a>(
    manifest: &'a ModelManifest,
    filename: &str,
) -> Result<&'a ModelAsset, Error> {
    manifest
        .assets
        .iter()
        .find(|asset| asset.filename == filename)
        .ok_or_else(|| Error::new(format!("cortext model asset not declared: {filename}")))
}

fn file_sha256(path: &Path) -> Option<String> {
    let mut file = File::open(path).ok()?;
    let mut hasher = Sha256::new();
    io::copy(&mut file, &mut hasher).ok()?;
    Some(format!("{:x}", hasher.finalize()))
}

fn file_has_sha256(path: &Path, want: &str) -> bool {
    file_sha256(path).is_some_and(|got| got == want)
}