ailoop_history/lib.rs
1//! Conversation history management for ailoop.
2//!
3//! Owns the message vector that drives every [`ChatRequest`] and
4//! enforces the token-budget contract: [`History`] tracks the
5//! running history, applies a [`CompactionStrategy`] when the wired
6//! [`Tokenizer`] reports the budget is exceeded, and persists the pin
7//! mask that keeps system-style anchors and live `ToolCall ↔ ToolResult`
8//! pairs intact across compactions.
9//!
10//! Most application code does not construct a `History` directly
11//! — the [`ailoop`](https://docs.rs/ailoop) façade wires one inside
12//! [`Conversation`](https://docs.rs/ailoop) with a sensible default
13//! budget. Reach for this crate when you need a custom strategy
14//! ([`SummarizeStrategy`] vs [`TruncateStrategy`]), a non-default
15//! tokenizer (e.g. `ailoop_anthropic::OnlineCalibratedTokenizer`),
16//! direct access to `compact_if_needed` from
17//! [`advanced::run_chat`](https://docs.rs/ailoop), or your own
18//! [`HistoryStore`] backend for persistence.
19//!
20//! ## Mini-index
21//!
22//! - [`History`] + [`HistoryBuilder`] — the history
23//! container and its configuration entry point.
24//! - [`CompactionStrategy`] — trait implemented by reduction
25//! algorithms; ships with [`TruncateStrategy`] and
26//! [`SummarizeStrategy`].
27//! - [`CompactionOutput`], [`CompactionReport`], [`CompactionError`],
28//! [`FromMessagesError`] — the surrounding vocabulary.
29//! - [`HistoryStore`] — async persistence trait. [`InMemoryHistoryStore`]
30//! and [`JsonFileHistoryStore`] cover tests and single-file durable
31//! storage; implement the trait for Redis, Postgres, etc.
32//! - [`ConversationSnapshot`] — versioned wire format for
33//! [`HistoryStore`] payloads. Validated at deserialize time so a
34//! malformed file fails loudly rather than panicking later.
35//! - [`Tokenizer`] / [`CharTokenizer`] — re-exported from
36//! [`ailoop_core`] so [`HistoryBuilder::tokenizer`] callers
37//! can stay on this crate's import surface.
38//!
39//! [`ChatRequest`]: ailoop_core::ChatRequest
40
41#![deny(missing_docs)]
42
43pub mod compaction;
44pub mod errors;
45pub mod history;
46pub mod history_store;
47pub mod snapshot;
48
49pub use compaction::{
50 CompactionOutput, CompactionStrategy, DEFAULT_SUMMARIZER_PROMPT, SummarizeStrategy,
51 TruncateStrategy,
52};
53pub use errors::{CompactionError, FromMessagesError};
54pub use history::{CompactionReport, History, HistoryBuilder};
55pub use history_store::{
56 HistoryStore, InMemoryHistoryStore, JsonFileHistoryStore, JsonFileHistoryStoreError,
57};
58pub use snapshot::ConversationSnapshot;
59
60// `Tokenizer` lives in `ailoop-core` (its canonical home alongside
61// `Message`). Re-export at the root so callers wiring
62// `HistoryBuilder::tokenizer` can stay on this crate's import
63// surface without dragging `ailoop-core` into their dep tree.
64// `CharTokenizer` is the dev/test fallback.
65pub use ailoop_core::{CharTokenizer, Tokenizer};