<div align="center" style="margin-bottom: 1em;">
<img src="./docs/assets/images/logo.png" alt="Outlines-core Logo" width=500></img>
[![Latest Version]][crates.io] [![License]][github] ![MSRV]
[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]: https://img.shields.io/badge/MSRV-1.71.1-brightgreen
<!---
Once it uploaded to crates.io badge could be generated like:
[version]: https://img.shields.io/crates/msrv/outlines-core.svg?label=msrv&color=lightgrayy
-->
*Structured generation (in Rust).*
</div>
## 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();
```
## Python Bindings
Additionally, project provides interfaces to integrate the crate's functionality with Python.
``` python
import json
from outlines_core.json_schema import build_regex_from_schema
from outlines_core.guide import Guide, Index, Vocabulary
schema = {
"title": "Foo",
"type": "object",
"properties": {"date": {"type": "string", "format": "date"}}
}
regex = build_regex_from_schema(json.dumps(schema))
vocabulary = Vocabulary.from_pretrained("openai-community/gpt2")
index = Index(regex, vocabulary)
guide = Guide(index)
# Get current state of the Guide:
current_state = guide.get_state()
# Get allowed tokens for the current state of the Guide:
allowed_tokens = guide.get_tokens()
# Advance Guide to the next state via some token_id and return allowed tokens for that new state:
next_allowed_tokens = guide.advance(allowed_tokens[-1])
# To check if Guide is finished:
guide.is_finished()
# If it's finished then this assertion holds:
assert guide.get_tokens() == [vocabulary.get_eos_token_id()]
```
## How to contribute?
### Setup
Fork the repository on GitHub and clone the fork locally:
```bash
git clone git@github.com/YourUserName/outlines-core.git
cd outlines-core
```
Create a new virtual environment and install the dependencies in editable mode:
``` bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pre-commit install
```
### Before pushing your code
If working with Python bindings don't forget to build Rust extension before testing, for example, in debug mode:
```bash
make build-extension-debug
```
Run Python tests:
``` bash
pytest
```
Run Rust tests:
``` bash
cargo test
```
Or alternatively using Makefile for both:
``` bash
make test
```
Finally, run the code style checks:
``` bash
pre-commit run --all-files
```
Or using Makefile:
``` bash
make pcc
```
If necessary you can run benchmarks locally:
``` bash
make pybench
```
## Join us
- 💡 **Have an idea?** Come chat with us on [Discord][discord]
- **Found a bug?** Open an [issue](https://github.com/dottxt-ai/outlines-core/issues)
[outlines]: https://github.com/dottxt-ai/outlines
[discord]: https://discord.gg/R9DSu34mGd
Raw data
{
"_id": null,
"home_page": null,
"name": "outlines-core",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "machine learning, deep learning, language models, structured generation",
"author": "Outlines Developers",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0f/22/b2d68f4c7decd7c11f44dc2ebcc94250dceafa78b275faaff893d2c9fe9c/outlines_core-0.2.2.tar.gz",
"platform": null,
"description": "<div align=\"center\" style=\"margin-bottom: 1em;\">\n\n<img src=\"./docs/assets/images/logo.png\" alt=\"Outlines-core Logo\" width=500></img>\n\n[![Latest Version]][crates.io] [![License]][github] ![MSRV]\n\n[Latest Version]: https://img.shields.io/crates/v/outlines-core.svg\n[crates.io]: https://crates.io/crates/outlines-core\n[License]: https://img.shields.io/github/license/dottxt-ai/outlines-core.svg?color=blue&cachedrop\n[github]: https://github.com/dottxt-ai/outlines-core/blob/main/LICENSE\n[MSRV]: https://img.shields.io/badge/MSRV-1.71.1-brightgreen\n\n<!---\nOnce it uploaded to crates.io badge could be generated like:\n [version]: https://img.shields.io/crates/msrv/outlines-core.svg?label=msrv&color=lightgrayy\n -->\n\n*Structured generation (in Rust).*\n\n</div>\n\n## Outlines-core\n\nThis package provides the core functionality for structured generation, formerly implemented in [Outlines][outlines],\nwith a focus on performance and portability, it offers a convenient way to:\n\n- build regular expressions from JSON schemas\n\n- 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\n\n### Example\n\nBasic example of how it all fits together.\n\n```rust\nuse outlines_core::prelude::*;\n\n// Define a JSON schema\nlet schema = r#\"{\n \"type\": \"object\",\n \"properties\": {\n \"name\": { \"type\": \"string\" },\n \"age\": { \"type\": \"integer\" }\n },\n \"required\": [\"name\", \"age\"]\n}\"#;\n\n// Generate a regular expression from it\nlet regex = json_schema::regex_from_str(&schema, None)?;\n\n// Create `Vocabulary` from pretrained large language model (but manually is also possible)\nlet vocabulary = Vocabulary::from_pretrained(\"openai-community/gpt2\", None)?;\n\n// Create new `Index` from regex and a given `Vocabulary`\nlet index = Index::new(®ex, &vocabulary)?;\n\nlet initial_state = index.initial_state();\nlet allowed_tokens = index.allowed_tokens(&initial_state).expect(\"Some allowed token ids\");\nlet token_id = allowed_tokens.first().expect(\"First token id\");\nlet next_state = index.next_state(&initial_state, token_id);\nlet final_states = index.final_states();\n```\n\n## Python Bindings\n\nAdditionally, project provides interfaces to integrate the crate's functionality with Python.\n\n``` python\nimport json\n\nfrom outlines_core.json_schema import build_regex_from_schema\nfrom outlines_core.guide import Guide, Index, Vocabulary\n\nschema = {\n \"title\": \"Foo\",\n \"type\": \"object\",\n \"properties\": {\"date\": {\"type\": \"string\", \"format\": \"date\"}}\n}\nregex = build_regex_from_schema(json.dumps(schema))\n\nvocabulary = Vocabulary.from_pretrained(\"openai-community/gpt2\")\nindex = Index(regex, vocabulary)\nguide = Guide(index)\n\n# Get current state of the Guide:\ncurrent_state = guide.get_state()\n\n# Get allowed tokens for the current state of the Guide:\nallowed_tokens = guide.get_tokens()\n\n# Advance Guide to the next state via some token_id and return allowed tokens for that new state:\nnext_allowed_tokens = guide.advance(allowed_tokens[-1])\n\n# To check if Guide is finished:\nguide.is_finished()\n\n# If it's finished then this assertion holds:\nassert guide.get_tokens() == [vocabulary.get_eos_token_id()]\n```\n\n## How to contribute?\n\n### Setup\n\nFork the repository on GitHub and clone the fork locally:\n\n```bash\ngit clone git@github.com/YourUserName/outlines-core.git\ncd outlines-core\n```\n\nCreate a new virtual environment and install the dependencies in editable mode:\n\n``` bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[test]\"\npre-commit install\n```\n\n### Before pushing your code\n\nIf working with Python bindings don't forget to build Rust extension before testing, for example, in debug mode:\n\n```bash\nmake build-extension-debug\n```\n\nRun Python tests:\n\n``` bash\npytest\n```\n\nRun Rust tests:\n\n``` bash\ncargo test\n```\n\nOr alternatively using Makefile for both:\n\n``` bash\nmake test\n```\n\nFinally, run the code style checks:\n\n``` bash\npre-commit run --all-files\n```\n\nOr using Makefile:\n\n``` bash\nmake pcc\n```\n\nIf necessary you can run benchmarks locally:\n\n``` bash\nmake pybench\n```\n\n## Join us\n\n- \ud83d\udca1 **Have an idea?** Come chat with us on [Discord][discord]\n- **Found a bug?** Open an [issue](https://github.com/dottxt-ai/outlines-core/issues)\n\n[outlines]: https://github.com/dottxt-ai/outlines\n[discord]: https://discord.gg/R9DSu34mGd\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Structured Text Generation in Rust",
"version": "0.2.2",
"project_urls": {
"documentation": "https://dottxt-ai.github.io/outlines-core/",
"homepage": "https://github.com/dottxt-ai/outlines-core",
"repository": "https://github.com/dottxt-ai/outlines-core"
},
"split_keywords": [
"machine learning",
" deep learning",
" language models",
" structured generation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2fad386f50677a384f7e1e8e1e513d68932a4facd433d27f8d07c8c80c6aae41",
"md5": "7e2de5508b802dc90667798cc7a953a1",
"sha256": "8a8546112060d8677177c9c3b1a5d2f35b57e5b9ac6f7922251fd1c42d84ffa3"
},
"downloads": -1,
"filename": "outlines_core-0.2.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "7e2de5508b802dc90667798cc7a953a1",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.8",
"size": 2022846,
"upload_time": "2025-01-31T23:12:02",
"upload_time_iso_8601": "2025-01-31T23:12:02.077782Z",
"url": "https://files.pythonhosted.org/packages/2f/ad/386f50677a384f7e1e8e1e513d68932a4facd433d27f8d07c8c80c6aae41/outlines_core-0.2.2-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "746446d1a1b5ae89e90729c975504d50f12ddde5b862ea21fbba4b790478c5e3",
"md5": "1ac01c305c2d487f4dab555ff795e2dd",
"sha256": "a5be1e5112180833ead2b33c3714ba1c0a89c3548a60feb9b448f2a2ff6f564c"
},
"downloads": -1,
"filename": "outlines_core-0.2.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "1ac01c305c2d487f4dab555ff795e2dd",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.8",
"size": 2183081,
"upload_time": "2025-01-31T23:12:04",
"upload_time_iso_8601": "2025-01-31T23:12:04.693802Z",
"url": "https://files.pythonhosted.org/packages/74/64/46d1a1b5ae89e90729c975504d50f12ddde5b862ea21fbba4b790478c5e3/outlines_core-0.2.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "08121b478b0ff428d662d083e4919f64ed2eefdb30f07dc51f47e85dcb326047",
"md5": "d331f890443eb3aaea0debf4e1691879",
"sha256": "9852adddbee2fbacf0ae9dbb07bf8bd8087a05126f9fdfbad20c405c1892e99c"
},
"downloads": -1,
"filename": "outlines_core-0.2.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "d331f890443eb3aaea0debf4e1691879",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.8",
"size": 2022676,
"upload_time": "2025-01-31T23:12:08",
"upload_time_iso_8601": "2025-01-31T23:12:08.608165Z",
"url": "https://files.pythonhosted.org/packages/08/12/1b478b0ff428d662d083e4919f64ed2eefdb30f07dc51f47e85dcb326047/outlines_core-0.2.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9f34446b4087835ae77cd39ec800f230946441656a2f56ee552cc7702b0ed445",
"md5": "f9955723b0a0f9b7924934e869180600",
"sha256": "72944f5526128cc1d6b15f69d796e2e78c428f5e2185c868e9b6fc442ecd895e"
},
"downloads": -1,
"filename": "outlines_core-0.2.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "f9955723b0a0f9b7924934e869180600",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.8",
"size": 2182676,
"upload_time": "2025-01-31T23:12:10",
"upload_time_iso_8601": "2025-01-31T23:12:10.900976Z",
"url": "https://files.pythonhosted.org/packages/9f/34/446b4087835ae77cd39ec800f230946441656a2f56ee552cc7702b0ed445/outlines_core-0.2.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c9428d15374b40bea235e0a4d029888e13c2eaabcc352585fa28afbd5d00c31b",
"md5": "a212dcf1e4392055c81c1a70f811784f",
"sha256": "1e1cc220d764567324858649464e5e968a1002409d6a5eafff97b32b93cd0284"
},
"downloads": -1,
"filename": "outlines_core-0.2.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "a212dcf1e4392055c81c1a70f811784f",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.8",
"size": 2023209,
"upload_time": "2025-01-31T23:12:13",
"upload_time_iso_8601": "2025-01-31T23:12:13.023994Z",
"url": "https://files.pythonhosted.org/packages/c9/42/8d15374b40bea235e0a4d029888e13c2eaabcc352585fa28afbd5d00c31b/outlines_core-0.2.2-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ca36c41a5c461b50e3c9d25d866a8de196275af071d6ef6b8cc95b7031eff31f",
"md5": "414eba4f6fd5ec5d8232c3b6adc2d32e",
"sha256": "e820cbb6e5f801b8f02122ba66afcaa45e112a929362da1f6056bc4e5d043990"
},
"downloads": -1,
"filename": "outlines_core-0.2.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "414eba4f6fd5ec5d8232c3b6adc2d32e",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.8",
"size": 2183261,
"upload_time": "2025-01-31T23:12:14",
"upload_time_iso_8601": "2025-01-31T23:12:14.439278Z",
"url": "https://files.pythonhosted.org/packages/ca/36/c41a5c461b50e3c9d25d866a8de196275af071d6ef6b8cc95b7031eff31f/outlines_core-0.2.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2bb58ef947255aa5cbca2fc9eebade57af9c80d72620efcb978926d39b8f996a",
"md5": "5a833381c69b2d3ce38c50dc613d6782",
"sha256": "5a8f513d219140d9ce99742e1a521368226c9eca72323abedd9fc1bb09f913ae"
},
"downloads": -1,
"filename": "outlines_core-0.2.2-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "5a833381c69b2d3ce38c50dc613d6782",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.8",
"size": 2023616,
"upload_time": "2025-01-31T23:12:16",
"upload_time_iso_8601": "2025-01-31T23:12:16.513753Z",
"url": "https://files.pythonhosted.org/packages/2b/b5/8ef947255aa5cbca2fc9eebade57af9c80d72620efcb978926d39b8f996a/outlines_core-0.2.2-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "54722ddfd2d1a0e48fb96df4b4c5beb0625469670a7dc4664a62f5b01ca845cc",
"md5": "322632ffcc20c95c73e8e5df068cb914",
"sha256": "8f4ecc97e8c966a5262228429c635b83fae5f4415b77d09de9e5730166f075d5"
},
"downloads": -1,
"filename": "outlines_core-0.2.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "322632ffcc20c95c73e8e5df068cb914",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.8",
"size": 2183859,
"upload_time": "2025-01-31T23:12:18",
"upload_time_iso_8601": "2025-01-31T23:12:18.682480Z",
"url": "https://files.pythonhosted.org/packages/54/72/2ddfd2d1a0e48fb96df4b4c5beb0625469670a7dc4664a62f5b01ca845cc/outlines_core-0.2.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f22b2d68f4c7decd7c11f44dc2ebcc94250dceafa78b275faaff893d2c9fe9c",
"md5": "95a34eddd4fd6d3686057d497d0cc917",
"sha256": "dcd252617cd9cedc5b3ea3cbad78c13e5d09ac3671c4482210a27ec36a5019d9"
},
"downloads": -1,
"filename": "outlines_core-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "95a34eddd4fd6d3686057d497d0cc917",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 72639,
"upload_time": "2025-01-31T23:12:19",
"upload_time_iso_8601": "2025-01-31T23:12:19.939492Z",
"url": "https://files.pythonhosted.org/packages/0f/22/b2d68f4c7decd7c11f44dc2ebcc94250dceafa78b275faaff893d2c9fe9c/outlines_core-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-31 23:12:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dottxt-ai",
"github_project": "outlines-core",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "outlines-core"
}
JSON
