@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-db/src/catalog_query/test_support.rs

@@ -0,0 +1,88 @@
+use crate::testing::TempPool;
+use rusqlite::params;
+
+// A fresh temp-file DB seeded with a small movies+shows catalog.
+pub(super) fn seeded_pool() -> TempPool {
+    let pool = crate::testing::temp_pool("catq");
+    let conn = pool.get().unwrap();
+    conn.execute(
+        "INSERT INTO libraries (id,name,kind,path,added_at) VALUES ('lib','L','movie','/x','t')",
+        [],
+    )
+    .unwrap();
+
+    let meta = |genres: &[&str], rating: f64, director: &str, actor: &str| {
+        serde_json::json!({
+            "tmdbId": 1, "tmdbUrl": "x",
+            "genres": genres,
+            "rating": rating,
+            "overview": "a film about things",
+            "crew": [{"name": director, "job": "Director"}],
+            "cast": [{"name": actor}],
+        })
+        .to_string()
+    };
+    let movie = |id: &str, title: &str, year: i64, m: String| {
+        conn.execute(
+            "INSERT INTO items (id,kind,title,year,container,library,added_at,metadata) \
+             VALUES (?1,'movie',?2,?3,'mkv','lib','t',?4)",
+            params![id, title, year, m],
+        )
+        .unwrap();
+    };
+    movie(
+        "m1",
+        "Dune",
+        2021,
+        meta(
+            &["Science Fiction"],
+            8.0,
+            "Denis Villeneuve",
+            "Timothée Chalamet",
+        ),
+    );
+    movie(
+        "m2",
+        "Sicario",
+        2015,
+        meta(
+            &["Thriller", "Crime"],
+            7.6,
+            "Denis Villeneuve",
+            "Emily Blunt",
+        ),
+    );
+    movie(
+        "m3",
+        "The Shining",
+        1980,
+        meta(&["Horror"], 8.4, "Stanley Kubrick", "Jack Nicholson"),
+    );
+    movie(
+        "m4",
+        "Hereditary",
+        2018,
+        meta(&["Horror"], 7.3, "Ari Aster", "Toni Collette"),
+    );
+    movie(
+        "m5",
+        "Old Unrated",
+        1990,
+        "{\"tmdbId\":2,\"tmdbUrl\":\"x\",\"genres\":[\"Drama\"]}".to_string(),
+    );
+
+    // A show + an episode (the episode must be excluded from the catalog).
+    conn.execute(
+        "INSERT INTO shows (id,library,title,year,added_at,metadata) VALUES ('s1','lib','Severance',2022,'t',?1)",
+        params![meta(&["Science Fiction", "Drama"], 8.7, "Ben Stiller", "Adam Scott")],
+    )
+    .unwrap();
+    conn.execute(
+        "INSERT INTO items (id,kind,title,container,library,show_id,season,episode,added_at) \
+         VALUES ('e1','episode','Ep1','mkv','lib','s1',1,1,'t')",
+        [],
+    )
+    .unwrap();
+    drop(conn);
+    pool
+}

package/rust/kroma-db/src/catalog_query.rs

@@ -0,0 +1,198 @@
+//! Read-only catalog queries powering the **LLM connector** (`services::llm`).
+//!
+//! Where the rest of `db` serves the UI, these answer the questions a model asks
+//! while curating: *"horror titles rated ≥7, newest first"*, *"everything Nolan
+//! directed"*, *"which genres exist"*. All of it runs over the `metadata` JSON
+//! column with SQLite's JSON1 (`json_each` / `json_extract`), across **movies and
+//! shows** at once via a small `cat` CTE so a tool query spans the whole
+//! library without the caller stitching two tables together.
+
+use super::*;
+
+use rusqlite::OptionalExtension;
+
+use kroma_domain::Metadata;
+
+mod find_titles;
+
+#[cfg(test)]
+mod test_support;
+
+pub use find_titles::*;
+
+// Every query below selects `FROM cat`. The trailing space is intentional:
+// the per-query `SELECT …` is concatenated directly after it.
+const CAT_CTE: &str = "WITH cat(id,title,year,kind,metadata) AS (\
+    SELECT id,title,year,'movie',metadata FROM items WHERE kind != 'episode' \
+    UNION ALL SELECT id,title,year,'show',metadata FROM shows) ";
+
+const DIRECTING_JOBS_SQL: &str = "('Director','Creator')";
+
+/// A title in full form (`get_title`) adds people, synopsis, tagline.
+pub struct TitleFull {
+    pub id: String,
+    pub title: String,
+    pub year: Option<u32>,
+    pub kind: String,
+    pub rating: Option<f32>,
+    pub genres: Vec<String>,
+    pub directors: Vec<String>,
+    pub cast: Vec<String>,
+    pub overview: Option<String>,
+    pub tagline: Option<String>,
+}
+
+/// Fetch one title's full data by **id first, else exact title** (case-
+/// insensitive; highest-rated on a tie). `None` when nothing matches.
+pub fn get_title(pool: &Pool, query: &str) -> Result<Option<TitleFull>> {
+    let q = query.trim();
+    if q.is_empty() {
+        return Ok(None);
+    }
+    let conn = pool.get()?;
+    let sql = format!(
+        "{CAT_CTE}SELECT id,title,year,kind,metadata FROM cat \
+         WHERE id = ?1 OR title = ?1 COLLATE NOCASE \
+         ORDER BY (id = ?1) DESC, CAST(json_extract(cat.metadata,'$.rating') AS REAL) DESC LIMIT 1"
+    );
+    let row = conn
+        .query_row(&sql, params![q], |r| {
+            let meta = parse_metadata(r.get::<_, Option<String>>(4)?);
+            Ok(full_from(r.get(0)?, r.get(1)?, r.get(2)?, r.get(3)?, meta))
+        })
+        .optional()?;
+    Ok(row)
+}
+
+/// Every genre present, with how many titles carry it (most common first).
+pub fn genre_counts(pool: &Pool) -> Result<Vec<(String, usize)>> {
+    let conn = pool.get()?;
+    let sql = format!(
+        "{CAT_CTE}SELECT g.value AS genre, COUNT(*) AS n \
+         FROM cat, json_each(cat.metadata,'$.genres') g \
+         GROUP BY genre ORDER BY n DESC, genre"
+    );
+    let mut stmt = conn.prepare(&sql)?;
+    let rows = stmt
+        .query_map([], |r| {
+            Ok((r.get::<_, String>(0)?, r.get::<_, i64>(1)? as usize))
+        })?
+        .collect::<rusqlite::Result<Vec<_>>>()?;
+    Ok(rows)
+}
+
+/// Most-credited people for a `role` (`"director"` default | `"actor"`), with
+/// their title counts. Capped at `limit` (1..=100).
+pub fn people_counts(pool: &Pool, role: &str, limit: usize) -> Result<Vec<(String, usize)>> {
+    let lim = limit.clamp(1, 100);
+    let sql = match role.trim().to_ascii_lowercase().as_str() {
+        "actor" | "cast" => format!(
+            "{CAT_CTE}SELECT json_extract(c.value,'$.name') AS name, COUNT(*) AS n \
+             FROM cat, json_each(cat.metadata,'$.cast') c \
+             WHERE name IS NOT NULL AND name != '' \
+             GROUP BY name ORDER BY n DESC, name LIMIT {lim}"
+        ),
+        _ => format!(
+            "{CAT_CTE}SELECT json_extract(c.value,'$.name') AS name, COUNT(*) AS n \
+             FROM cat, json_each(cat.metadata,'$.crew') c \
+             WHERE json_extract(c.value,'$.job') IN {DIRECTING_JOBS_SQL} AND name IS NOT NULL AND name != '' \
+             GROUP BY name ORDER BY n DESC, name LIMIT {lim}"
+        ),
+    };
+    let conn = pool.get()?;
+    let mut stmt = conn.prepare(&sql)?;
+    let rows = stmt
+        .query_map([], |r| {
+            Ok((r.get::<_, String>(0)?, r.get::<_, i64>(1)? as usize))
+        })?
+        .collect::<rusqlite::Result<Vec<_>>>()?;
+    Ok(rows)
+}
+
+fn full_from(
+    id: String,
+    title: String,
+    year: Option<u32>,
+    kind: String,
+    meta: Option<Metadata>,
+) -> TitleFull {
+    let Some(m) = meta else {
+        return TitleFull {
+            id,
+            title,
+            year,
+            kind,
+            rating: None,
+            genres: Vec::new(),
+            directors: Vec::new(),
+            cast: Vec::new(),
+            overview: None,
+            tagline: None,
+        };
+    };
+    let directors = m
+        .crew
+        .iter()
+        .filter(|c| matches!(c.job.as_str(), "Director" | "Creator"))
+        .map(|c| c.name.clone())
+        .collect();
+    let cast = m.cast.iter().take(10).map(|c| c.name.clone()).collect();
+    TitleFull {
+        id,
+        title,
+        year,
+        kind,
+        rating: m.rating,
+        genres: m.genres,
+        directors,
+        cast,
+        overview: m.overview,
+        tagline: m.tagline,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::catalog_query::test_support::*;
+
+    #[test]
+    fn get_title_and_counts() {
+        let pool = seeded_pool();
+        let dune = get_title(&pool, "Dune").unwrap().unwrap();
+        assert_eq!(dune.id, "m1");
+        assert_eq!(dune.directors, ["Denis Villeneuve"]);
+        assert_eq!(dune.cast, ["Timothée Chalamet"]);
+        assert_eq!(
+            get_title(&pool, "m3").unwrap().unwrap().title,
+            "The Shining"
+        );
+        assert!(get_title(&pool, "Nonexistent").unwrap().is_none());
+
+        let genres = genre_counts(&pool).unwrap();
+        let horror = genres.iter().find(|(g, _)| g == "Horror").unwrap();
+        assert_eq!(horror.1, 2);
+
+        let directors = people_counts(&pool, "director", 10).unwrap();
+        assert_eq!(directors[0], ("Denis Villeneuve".to_string(), 2)); // most prolific first
+    }
+
+    #[test]
+    fn a_blank_lookup_finds_nothing_and_an_unknown_kind_reads_as_movie() {
+        let pool = seeded_pool();
+        assert!(get_title(&pool, "   ").unwrap().is_none());
+        assert!(get_title(&pool, "").unwrap().is_none());
+
+        let unknown_kind = find_titles(
+            &pool,
+            &TitleFilter {
+                kind: Some("documentary".into()),
+                limit: Some(50),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        assert!(unknown_kind.iter().all(|t| t.kind == "movie"));
+        assert_eq!(unknown_kind.len(), 5);
+    }
+}

package/rust/kroma-db/src/chunked.rs

@@ -0,0 +1,36 @@
+//! Reading an id list back in batches SQLite can bind.
+
+use anyhow::Result;
+use rusqlite::{Connection, Row};
+
+/// Chunk size for `IN (...)` id lists: comfortably under SQLite's bound-variable
+/// limit while keeping the query count per batch effectively constant.
+pub(crate) const IN_CHUNK: usize = 800;
+
+/// Run a `subject_kind = ? AND subject_id IN (…)` lookup over `ids` in
+/// [`IN_CHUNK`]-sized batches, prepending `kind` to each chunk's bound params
+/// and appending `tail`. `build_sql` receives the `?,?,…` placeholder list and
+/// returns the full statement; `map` turns each row into a `T`. Rows come back
+/// flat in DB order, for the caller to fold into whatever shape it needs.
+pub(crate) fn query_by_subject_ids<T>(
+    conn: &Connection,
+    kind: &str,
+    ids: &[&str],
+    tail: &[&str],
+    build_sql: impl Fn(&str) -> String,
+    mut map: impl FnMut(&Row) -> rusqlite::Result<T>,
+) -> Result<Vec<T>> {
+    let mut out = Vec::new();
+    for chunk in ids.chunks(IN_CHUNK) {
+        let ph = vec!["?"; chunk.len()].join(",");
+        let mut stmt = conn.prepare(&build_sql(&ph))?;
+        let params_iter = std::iter::once(kind)
+            .chain(chunk.iter().copied())
+            .chain(tail.iter().copied());
+        let rows = stmt.query_map(rusqlite::params_from_iter(params_iter), &mut map)?;
+        for row in rows {
+            out.push(row?);
+        }
+    }
+    Ok(out)
+}

package/rust/kroma-db/src/core_tables.rs

@@ -0,0 +1,99 @@
+//! Which tables belong to the core schema.
+
+use std::collections::BTreeSet;
+use std::sync::LazyLock;
+
+use crate::schema::{MIGRATIONS, SCHEMA};
+
+static OWNED: LazyLock<BTreeSet<String>> = LazyLock::new(|| {
+    let schema = without_comments(SCHEMA);
+    schema
+        .split(';')
+        .filter_map(created_table)
+        .chain(MIGRATIONS.iter().copied().filter_map(created_table))
+        .collect()
+});
+
+/// Whether `name` is a table the core creates, compared the way SQLite compares
+/// identifiers: trimmed and ASCII case-insensitive.
+///
+/// Read off the DDL itself rather than a second list beside it, so a table added
+/// to the schema is covered the day it lands. The module supervisor consults
+/// this before moving a table out of the core database: a table the core owns is
+/// never a module's to take, whatever its manifest declares.
+pub fn is_core_table(name: &str) -> bool {
+    OWNED.contains(name.trim().to_ascii_lowercase().as_str())
+}
+
+// Runs before the split on `;`: a comment holding one would otherwise cut a
+// statement away from its own `CREATE`.
+fn without_comments(sql: &str) -> String {
+    sql.lines()
+        .map(|line| line.split("--").next().unwrap_or_default())
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+fn created_table(statement: &str) -> Option<String> {
+    let rest = strip_prefix_ci(statement.trim(), "CREATE TABLE ")?;
+    let rest = strip_prefix_ci(rest.trim_start(), "IF NOT EXISTS ").unwrap_or(rest);
+    let name = rest
+        .trim_start()
+        .split(['(', ' ', '\t'])
+        .find(|word| !word.is_empty())?;
+    Some(name.trim_matches('"').to_ascii_lowercase())
+}
+
+fn strip_prefix_ci<'a>(sql: &'a str, prefix: &str) -> Option<&'a str> {
+    let head = sql.get(..prefix.len())?;
+    head.eq_ignore_ascii_case(prefix)
+        .then(|| &sql[prefix.len()..])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_table_a_fresh_database_holds_is_known_to_be_the_cores() {
+        let pool = crate::testing::temp_pool("core-tables-fresh");
+        let conn = pool.get().unwrap();
+
+        let held: Vec<String> = conn
+            .prepare(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'",
+            )
+            .unwrap()
+            .query_map([], |r| r.get(0))
+            .unwrap()
+            .collect::<rusqlite::Result<_>>()
+            .unwrap();
+
+        assert!(held.len() > 20, "{held:?}");
+        for name in &held {
+            assert!(
+                is_core_table(name),
+                "'{name}' is in the schema but not derived from it"
+            );
+        }
+    }
+
+    #[test]
+    fn a_table_created_by_a_migration_counts_as_the_cores() {
+        assert!(is_core_table("passkeys"));
+        assert!(is_core_table("file_segments"));
+    }
+
+    #[test]
+    fn an_identifier_matches_whatever_case_and_padding_it_arrives_in() {
+        assert!(is_core_table("USERS"));
+        assert!(is_core_table("  Sessions  "));
+    }
+
+    #[test]
+    fn a_table_the_core_never_creates_is_not_its_own() {
+        assert!(!is_core_table("indexers"));
+        assert!(!is_core_table("download_clients"));
+        assert!(!is_core_table(""));
+    }
+}

package/rust/kroma-db/src/curated.rs

@@ -0,0 +1,192 @@
+//! Persistence for global editorial curated collections (the `sections.curate`
+//! job): a replace-all set, read by the `curated` home source. Members are
+//! resolved to real item/show ids at write time so serving is a plain hydrate.
+
+use std::collections::{HashMap, HashSet};
+
+use super::translations::{self, TransData};
+use super::*;
+
+/// One curated collection. `item_ids` are resolved member ids (movies or shows);
+/// `source` is `"director"` (deterministic) or `"llm"` (editorial). The localized
+/// `titles`/`reasons` (locale -> string) live in the generic `translations` cache
+/// (`subject_kind='curated'`), not in per-language columns.
+#[derive(Debug, Clone, Default)]
+pub struct CuratedRow {
+    pub key: String,
+    pub rank: i64,
+    pub source: String,
+    pub item_ids: Vec<String>,
+    pub titles: HashMap<String, String>,
+    pub reasons: HashMap<String, String>,
+}
+
+/// All curated collections, lowest `rank` first, with every stored language's
+/// title/reason hydrated from the translation cache.
+pub fn get_curated(pool: &Pool) -> Result<Vec<CuratedRow>> {
+    let mut rows: Vec<CuratedRow> = {
+        let conn = pool.get()?;
+        let mut stmt = conn.prepare(
+            "SELECT key, rank, source, item_ids FROM curated_sections ORDER BY rank ASC",
+        )?;
+        let mapped = stmt.query_map([], |r| {
+            let ids_json: String = r.get(3)?;
+            Ok(CuratedRow {
+                key: r.get(0)?,
+                rank: r.get(1)?,
+                source: r.get(2)?,
+                item_ids: serde_json::from_str(&ids_json).unwrap_or_default(),
+                titles: HashMap::new(),
+                reasons: HashMap::new(),
+            })
+        })?;
+        mapped.collect::<rusqlite::Result<Vec<_>>>()?
+    };
+    // Hydrate localized title/reason (all languages) from the translation cache.
+    let keys: Vec<&str> = rows.iter().map(|r| r.key.as_str()).collect();
+    let mut by_key = translations::load_all(pool, "curated", &keys)?;
+    for row in &mut rows {
+        if let Some(by_lang) = by_key.remove(&row.key) {
+            for (lang, data) in by_lang {
+                if let Some(t) = data.title {
+                    row.titles.insert(lang.clone(), t);
+                }
+                if let Some(rs) = data.reason {
+                    row.reasons.insert(lang, rs);
+                }
+            }
+        }
+    }
+    Ok(rows)
+}
+
+/// Replace the entire curated set in one transaction (the job regenerates it):
+/// the base rows in `curated_sections`, the localized title/reason per language
+/// in `translations` (`subject_kind='curated'`).
+pub fn set_curated(pool: &Pool, rows: &[CuratedRow]) -> Result<()> {
+    let mut conn = pool.get()?;
+    let tx = conn.transaction()?;
+    tx.execute("DELETE FROM curated_sections", [])?;
+    tx.execute(
+        "DELETE FROM translations WHERE subject_kind = 'curated'",
+        [],
+    )?;
+    let now = kroma_primitives::now_ms();
+    // Skip duplicate keys: the director + LLM producers can independently emit the
+    // same slug (e.g. two spellings of a director's name normalize alike). `key`
+    // is the PRIMARY KEY, so a plain INSERT of a dup would abort the whole
+    // transaction and wipe out every curated row keep the first, drop the rest.
+    let mut seen = HashSet::new();
+    for row in rows {
+        if !seen.insert(row.key.as_str()) {
+            continue;
+        }
+        let ids = serde_json::to_string(&row.item_ids).unwrap_or_else(|_| "[]".into());
+        tx.execute(
+            "INSERT INTO curated_sections (key, rank, source, item_ids, updated_at) \
+             VALUES (?1, ?2, ?3, ?4, ?5)",
+            params![row.key, row.rank, row.source, ids, now],
+        )?;
+        let langs: HashSet<&str> = row
+            .titles
+            .keys()
+            .chain(row.reasons.keys())
+            .map(String::as_str)
+            .collect();
+        for lang in langs {
+            let data = TransData {
+                title: row.titles.get(lang).cloned(),
+                reason: row.reasons.get(lang).cloned(),
+                ..Default::default()
+            };
+            translations::write(&tx, "curated", &row.key, lang, translations::LLM, &data)?;
+        }
+    }
+    tx.commit()?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::TempPool;
+    use std::collections::HashMap;
+
+    fn pool() -> TempPool {
+        crate::testing::temp_pool("cur")
+    }
+
+    fn map(pairs: &[(&str, &str)]) -> HashMap<String, String> {
+        pairs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn set_get_roundtrip_ordering_and_dedup() {
+        let p = pool();
+        let rows = vec![
+            CuratedRow {
+                key: "spielberg".into(),
+                rank: 0,
+                source: "director".into(),
+                item_ids: vec!["m1".into(), "m2".into()],
+                titles: map(&[("fr", "Spielberg"), ("en", "Spielberg")]),
+                reasons: map(&[("fr", "le maitre")]),
+            },
+            CuratedRow {
+                key: "horror".into(),
+                rank: 1,
+                source: "llm".into(),
+                item_ids: vec![],
+                titles: map(&[("en", "Best Horror")]),
+                reasons: HashMap::new(),
+            },
+            // Duplicate key: skipped (kept the first).
+            CuratedRow {
+                key: "spielberg".into(),
+                rank: 2,
+                source: "llm".into(),
+                ..Default::default()
+            },
+        ];
+        set_curated(&p, &rows).unwrap();
+
+        let got = get_curated(&p).unwrap();
+        assert_eq!(got.len(), 2, "duplicate key dropped");
+        // Ordered by rank ascending.
+        assert_eq!(got[0].key, "spielberg");
+        assert_eq!(got[0].source, "director");
+        assert_eq!(got[0].item_ids, vec!["m1".to_string(), "m2".to_string()]);
+        assert_eq!(
+            got[0].titles.get("fr").map(String::as_str),
+            Some("Spielberg")
+        );
+        assert_eq!(
+            got[0].titles.get("en").map(String::as_str),
+            Some("Spielberg")
+        );
+        assert_eq!(
+            got[0].reasons.get("fr").map(String::as_str),
+            Some("le maitre")
+        );
+        assert!(!got[0].reasons.contains_key("en"));
+        assert_eq!(got[1].key, "horror");
+
+        // Replace-all: a fresh set supersedes the previous one entirely.
+        set_curated(
+            &p,
+            &[CuratedRow {
+                key: "solo".into(),
+                rank: 0,
+                source: "llm".into(),
+                ..Default::default()
+            }],
+        )
+        .unwrap();
+        let got = get_curated(&p).unwrap();
+        assert_eq!(got.len(), 1);
+        assert_eq!(got[0].key, "solo");
+    }
+}