[![Latest Version]][crates.io] [![License]][github] ![MSRV][version]
[Latest Version]: https://img.shields.io/crates/v/outlines-core.svg
[crates.io]: https://crates.io/crates/outlines-core
[License]: https://img.shields.io/github/license/dottxt-ai/outlines-core.svg?color=blue&cachedrop
[github]: https://github.com/dottxt-ai/outlines-core/blob/main/LICENSE
[MSRV]: MSRV
[version]: https://img.shields.io/crates/msrv/outlines-core.svg?label=msrv&color=lightgrayy
*Structured generation (in Rust).*
## Outlines-core
This package provides the core functionality for structured generation, formerly implemented in [Outlines][outlines],
with a focus on performance and portability, it offers a convenient way to:
- build regular expressions from JSON schemas
- construct an `Index` object by combining a `Vocabulary` and regular expression to efficiently map tokens from a given vocabulary to state transitions in a finite-state automation
### Example
Basic example of how it all fits together.
```rust
use outlines_core::prelude::*;
// Define a JSON schema
let schema = r#"{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
},
"required": ["name", "age"]
}"#;
// Generate a regular expression from it
let regex = json_schema::regex_from_str(&schema, None)?;
// Create `Vocabulary` from pretrained large language model (but manually is also possible)
let vocabulary = Vocabulary::from_pretrained("openai-community/gpt2", None)?;
// Create new `Index` from regex and a given `Vocabulary`
let index = Index::new(®ex, &vocabulary)?;
let initial_state = index.initial_state();
let allowed_tokens = index.allowed_tokens(&initial_state).expect("Some allowed token ids");
let token_id = allowed_tokens.first().expect("First token id");
let next_state = index.next_state(&initial_state, token_id);
let final_states = index.final_states();
```
### Vocabulary
You can create a `Vocabulary` in three ways:
1. **`Vocabulary::from_pretrained(model, parameters)`** - Loads from a pretrained model (as in the example above)
2. **Manual creation** - You can create a vocabulary from token mappings:
1. **`Vocabulary::new(eos_token_id)`** - Creates an empty vocabulary, then add tokens with `try_insert()`:
```rust
let mut vocabulary = Vocabulary::new(50256);
vocabulary.try_insert("hello", 0)?;
vocabulary.try_insert(vec![32], 1)?;
```
2. **`Vocabulary::try_from((eos_token_id, tokens))`** - Creates a vocabulary by directly providing the token mappings.
- It can be done either with the tokens as strings:
```rust
use rustc_hash::FxHashMap as HashMap;
let eos_token_id: u32 = 50256;
let mut tokens: HashMap