Vakyartha documentation

1902 total.output_tokens += u.output_tokens;
1903 }
1904 }
1905 total
1906 }
1907
1908 /// Proactive retrieval: find the most relevant older entries from the
1909 /// projected history, returning their entry IDs and messages.
1910 ///
1911 /// This is a projection-only operation — it returns entries that are
1912 /// already in the projection. No ledger mutation, no new entries.
1913 ///
1914 /// Scoring uses the same BM25+entity-bonus approach as cross-session
1915 /// search, but scored against the current query over the in-memory
1916 /// projection. The result is capped at `cap` entries and excludes the
1917 /// `exclude_tail` most recent entries.
1918 pub fn retrieve_relevant_entries(
1919 &self,
1920 query: &str,
1921 cap: usize,
1922 exclude_tail: usize,
1923 ) -> Vec<(String, vak_llm::Message)> {
1924 if query.trim().is_empty() || cap == 0 {
1925 return Vec::new();
1926 }
1927 let tagged = self.derive_keyed_tagged();
1928 if tagged.is_empty() {
1929 return Vec::new();
1930 }
1931
1932 let terms: Vec<String> = crate::search::tokenize_impl(query);
1933 let phrase = crate::search::normalize_impl(query);
1934 if terms.is_empty() || phrase.is_empty() {
1935 return Vec::new();
1936 }
1937
1938 let candidates: Vec<_> = if tagged.len() > exclude_tail {
1939 tagged[..tagged.len() - exclude_tail]
1940 .iter()
1941 .filter(|(_, _, is_summary, is_control)| !*is_summary && !*is_control)
1942 .collect()
1943 } else {
1944 Vec::new()
1945 };
1946
1947 if candidates.is_empty() {
1948 return Vec::new();
1949 }
1950
1951 let mut scored: Vec<(f32, &String, &vak_llm::Message)> = Vec::new();
1952 for (id, msg, _, _) in &candidates {
1953 let text = msg.text_content();
1954 let entities = crate::search::extract_entities(&text);
1955 let normalized = crate::search::normalize_impl(&text);
1956 let score = crate::search::score_normalized(&normalized, &terms, &phrase, &entities);
1957 if score > 0.0 {
1958 scored.push((score, id, msg));
1959 }
1960 }
1961
1962 // Sort by score descending, take the top `cap`.
1963 scored.sort_by(|a, b| b.0.total_cmp(&a.0));
1964 scored
1965 .into_iter()
1966 .take(cap)
1967 .map(|(_, id, m)| (id.clone(), m.clone()))
1968 .collect()
1969 }
1970}
1971
1972pub struct SessionPath;
1973
1974impl SessionPath {
1975 pub fn sessions_dir(home: &Path, cwd: &Path) -> PathBuf {
1976 home.join("sessions").join(hash_cwd(cwd))
1977 }
1978
1979 pub fn new_session_file(home: &Path, cwd: &Path, session_id: &str) -> PathBuf {
1980 Self::sessions_dir(home, cwd).join(format!("{session_id}.jsonl"))
1981 }
1982}
1983
1984/// FNV-1a: a fixed hash whose output does not change across Rust releases,
1985/// unlike DefaultHasher (SipHash with randomly-seeded-but-toolchain-chosen
1986/// parameters). Session directories must remain reachable after toolchain
1987/// upgrades.
1988fn hash_cwd(cwd: &Path) -> String {
1989 let mut h: u64 = 0xcbf2_9ce4_8422_2325;
1990 for b in cwd.to_string_lossy().as_bytes() {
1991 h ^= u64::from(*b);
1992 h = h.wrapping_mul(0x0000_0100_0000_01b3);
1993 }
1994 format!("{h:016x}")
1995}
1996
1997#[cfg(all(test, unix))]
1998mod tests {
1999 #![allow(clippy::unwrap_used, clippy::expect_used)]
2000 use super::*;
2001
2002 /// A child being spawned holds a duplicate of every open descriptor
2003 /// until it execs; the duplicate here stands in for one.
2004 #[test]
2005 fn the_lock_lasts_exactly_as_long_as_the_handle() {
2006 let dir = tempfile::tempdir().unwrap();
2007 let path = dir.path().join("session.jsonl");
2008 std::fs::write(&path, "").unwrap();
2009
2010 let log = SessionLog::open(path.clone()).unwrap();
2011 assert!(matches!(
2012 SessionLog::open(path.clone()),
2013 Err(SessionError::Locked(_))
2014 ));
2015
2016 let duplicate = log.file.file.try_clone().unwrap();
2017 drop(log);
2018 SessionLog::open(path).expect("the dropped handle's lock stayed with a duplicate");
2019 drop(duplicate);
2020 }
2021}
2022

1902 total.output_tokens += u.output_tokens;
1903 }
1904 }
1905 total
1906 }
1907
1908 /// Proactive retrieval: find the most relevant older entries from the
1909 /// projected history, returning their entry IDs and messages.
1910 ///
1911 /// This is a projection-only operation — it returns entries that are
1912 /// already in the projection. No ledger mutation, no new entries.
1913 ///
1914 /// Scoring uses the same BM25+entity-bonus approach as cross-session
1915 /// search, but scored against the current query over the in-memory
1916 /// projection. The result is capped at `cap` entries and excludes the
1917 /// `exclude_tail` most recent entries.
1918 pub fn retrieve_relevant_entries(
1919 &self,
1920 query: &str,
1921 cap: usize,
1922 exclude_tail: usize,
1923 ) -> Vec<(String, vak_llm::Message)> {
1924 if query.trim().is_empty() || cap == 0 {
1925 return Vec::new();
1926 }
1927 let tagged = self.derive_keyed_tagged();
1928 if tagged.is_empty() {
1929 return Vec::new();
1930 }
1931
1932 let terms: Vec<String> = crate::search::tokenize_impl(query);
1933 let phrase = crate::search::normalize_impl(query);
1934 if terms.is_empty() || phrase.is_empty() {
1935 return Vec::new();
1936 }
1937
1938 let candidates: Vec<_> = if tagged.len() > exclude_tail {
1939 tagged[..tagged.len() - exclude_tail]
1940 .iter()
1941 .filter(|(_, _, is_summary, is_control)| !*is_summary && !*is_control)
1942 .collect()
1943 } else {
1944 Vec::new()
1945 };
1946
1947 if candidates.is_empty() {
1948 return Vec::new();
1949 }
1950
1951 let mut scored: Vec<(f32, &String, &vak_llm::Message)> = Vec::new();
1952 for (id, msg, _, _) in &candidates {
1953 let text = msg.text_content();
1954 let entities = crate::search::extract_entities(&text);
1955 let normalized = crate::search::normalize_impl(&text);
1956 let score = crate::search::score_normalized(&normalized, &terms, &phrase, &entities);
1957 if score > 0.0 {
1958 scored.push((score, id, msg));
1959 }
1960 }
1961
1962 // Sort by score descending, take the top `cap`.
1963 scored.sort_by(|a, b| b.0.total_cmp(&a.0));
1964 scored
1965 .into_iter()
1966 .take(cap)
1967 .map(|(_, id, m)| (id.clone(), m.clone()))
1968 .collect()
1969 }
1970}
1971
1972pub struct SessionPath;
1973
1974impl SessionPath {
1975 pub fn sessions_dir(home: &Path, cwd: &Path) -> PathBuf {
1976 home.join("sessions").join(hash_cwd(cwd))
1977 }
1978
1979 pub fn new_session_file(home: &Path, cwd: &Path, session_id: &str) -> PathBuf {
1980 Self::sessions_dir(home, cwd).join(format!("{session_id}.jsonl"))
1981 }
1982}
1983
1984/// FNV-1a: a fixed hash whose output does not change across Rust releases,
1985/// unlike DefaultHasher (SipHash with randomly-seeded-but-toolchain-chosen
1986/// parameters). Session directories must remain reachable after toolchain
1987/// upgrades.
1988fn hash_cwd(cwd: &Path) -> String {
1989 let mut h: u64 = 0xcbf2_9ce4_8422_2325;
1990 for b in cwd.to_string_lossy().as_bytes() {
1991 h ^= u64::from(*b);
1992 h = h.wrapping_mul(0x0000_0100_0000_01b3);
1993 }
1994 format!("{h:016x}")
1995}
1996
1997#[cfg(all(test, unix))]
1998mod tests {
1999 #![allow(clippy::unwrap_used, clippy::expect_used)]
2000 use super::*;
2001
2002 /// A child being spawned holds a duplicate of every open descriptor
2003 /// until it execs; the duplicate here stands in for one.
2004 #[test]
2005 fn the_lock_lasts_exactly_as_long_as_the_handle() {
2006 let dir = tempfile::tempdir().unwrap();
2007 let path = dir.path().join("session.jsonl");
2008 std::fs::write(&path, "").unwrap();
2009
2010 let log = SessionLog::open(path.clone()).unwrap();
2011 assert!(matches!(
2012 SessionLog::open(path.clone()),
2013 Err(SessionError::Locked(_))
2014 ));
2015
2016 let duplicate = log.file.file.try_clone().unwrap();
2017 drop(log);
2018 SessionLog::open(path).expect("the dropped handle's lock stayed with a duplicate");
2019 drop(duplicate);
2020 }
2021}
2022

Indexing the workspace…