Skip to main content

oc_sidememory/
lib.rs

1// Portions derived from outlines-core and modified by OC-Sidememory contributors.
2// See the repository PROVENANCE.md and MODIFICATIONS.md.
3
4//! # OC-Sidememory
5//!
6//! `oc_sidememory` provides checked structured-generation foundations.
7//!
8//! - build regular expressions from JSON schemas
9//!
10//! - construct an [`index::Index`] object by combining a [`vocabulary::Vocabulary`] and regular
11//!   expression to efficiently map tokens from a given `Vocabulary` to state transitions in a
12//!   finite-state automation
13//!
14//! ## `json_schema`
15//!
16//! [`json_schema`] module provides interfaces to generate a regular expression based on a given JSON schema, depending on its type:
17//! - [`json_schema::regex_from_str`]
18//! - [`json_schema::regex_from_value`]
19//!
20//! Whitespace pattern could be customized, otherwise the default [`json_schema::WHITESPACE`] pattern is used.
21//!
22//! Note, that not all the features of JSON schema are supported for regex generation: [Supported Features](json_schema#supported-features)
23//!
24//! ## `Index`
25//!
26//! Once [`index::Index`] is built, it can be used to evaluate or validate token sequences.
27//!
28//! ### Complexity and construction cost
29//!
30//! `Index` can accommodate large vocabularies and complex regular expressions. However, its size **may** grow
31//! significantly with the complexity of the input, as well as time and computational resources.
32//!
33//! ## Python bindings
34//!
35//! Additionally, crate provides interfaces to integrate the crate's functionality with Python.
36//!
37//! ## Support
38//!
39//! `Outlines_core` is primarily used in structured text generation project [`outlines`](https://github.com/dottxt-ai/outlines),
40//! if you need support, consider reaching out to its maintainers, you can also open an issue or start a discussion
41//! on [github](https://github.com/dhanavanthesh/oc-sidememory)
42//!
43//! ## Example
44//!
45//! Basic example of how it all fits together.
46//!
47//! ```no_run
48//! # use oc_sidememory::Error;
49//! use oc_sidememory::prelude::*;
50//!
51//! # fn main() -> Result<(), Error> {
52//! // Define a JSON schema
53//! let schema = r#"{
54//!     "type": "object",
55//!     "properties": {
56//!         "name": { "type": "string" },
57//!         "age": { "type": "integer" }
58//!     },
59//!     "required": ["name", "age"]
60//! }"#;
61//!
62//! // Generate a regular expression from it
63//! let regex = json_schema::regex_from_str(&schema, None, None)?;
64//! println!("Generated regex: {}", regex);
65//!
66//! // Build a small local vocabulary. Model loading is available behind the Hub feature.
67//! let mut vocabulary = Vocabulary::new(2);
68//! vocabulary.try_insert(b"0".to_vec(), 0)?;
69//! vocabulary.try_insert(b"1".to_vec(), 1)?;
70//!
71//! // Create new `Index` from regex and a given `Vocabulary`
72//! let index = Index::new(&regex, &vocabulary)?;
73//!
74//! let initial_state = index.initial_state();
75//! println!("Is initial state {} a final state? {}", initial_state, index.is_final_state(&initial_state));
76//!
77//! let allowed_tokens = index.allowed_tokens(&initial_state).expect("Some allowed tokens");
78//! println!("Allowed tokens at initial state are {:?}", allowed_tokens);
79//!
80//! let token_id = allowed_tokens.first().expect("First token");
81//! println!("Next state for the token_id {} is {:?}", token_id, index.next_state(&initial_state, token_id));
82//! println!("Final states are {:?}", index.final_states());
83//! println!("Index has exactly {} transitions", index.transitions().len());
84//! # Ok(())
85//! }
86//! ```
87
88pub mod error;
89pub mod index;
90pub mod json_schema;
91pub mod prelude;
92pub mod primitives;
93pub mod sidememory;
94pub mod vocabulary;
95
96pub use error::{Error, Result};
97pub use json_schema::compile::{compile_schema, CompileOptions, CompiledSchema};
98pub use json_schema::extensions::{ExtensionPlanV1, RelationOperator};
99pub use sidememory::{Guide, GuideError, GuideOptions, ImportedMemory};
100pub use vocabulary::Vocabulary;