Releases · dottxt-ai/outlines

18 Jun 15:32

1.0.0

d631de9

Outlines v1.0.0

Why a new major version?

The v1 intends on making Outlines more closely focused on constrained generation. To do so, we delegate a wider range of tasks to the users and inference libraries. On top of making Outlines leaner, this design provides more flexibility to the users and let them use interfaces they are already familiar with.

Our approach is inspired by the unix best practices — each element does one thing well, and we compose those functional elements.

As this new version deprecates some previously available features of Outlines, we have written a migration guide that gives detailed information on how to upgrade your v0 code to v1.

Deprecated

All deprecated features listed below will be removed in version 1.1.0. Until then, a warning will be displayed with information on how to migrate your code to v1.

The model loader functions from the models module (transformers, openai, etc.) have been deprecated. They are replaced by equivalent functions prefixed with from_ such as from_transformers, from_openai, etc. The new loader functions accept different arguments compared to the old ones. They now typically require an instance of an engine/client from the associated inference library. This change was made to avoid duplicating inference library logic and to give users more control over inference engine/client initialization.
Documentation

# v0
from outlines import models
from transformers import BertForSequenceClassification, BertTokenizer

model = models.transformers(
    model_name="prajjwal1/bert-tiny",
    model_class=BertForSequenceClassification,
    tokenizer_class=BertTokenizer,
    model_kwargs={"use_cache": False},
    tokenizer_kwargs={"model_max_length": 512},
)

# v1
import outlines
from transformers import BertForSequenceClassification, BertTokenizer

hf_model = BertForSequenceClassification.from_pretrained("prajjwal1/bert-tiny", use_cache=False)
hf_tokenizer = BertTokenizer.from_pretrained("prajjwal1/bert-tiny", model_max_length=512)
model = outlines.from_transformers(hf_model, hf_tokenizer)

The generate module and the associated functions (json, choice…) have been deprecated. They are replaced by the Generator constructor. While you had to select the right generate function for your output type, you can now provide any output type supported by Outlines to the unique Generator object.
Documentation

# v0
from pydantic import BaseModel
from outlines import generate, models

class Character(BaseModel):
	name: str
		
model = models.openai("gpt-4o")
generator = generate.json(model, Character)

# v1
from openai import OpenAI
from pydantic import BaseModel
from outlines import Generator, from_openai

class Character(BaseModel):
	name: str

model = from_openai(OpenAI())
generator = Generator(model, Character)

The TransformersVision model has been deprecated. It's replaced by TransformersMultiModal, which is more general as it supports additional input types beyond images, such as audio. When calling it, instead of providing the prompt and image assets separately, both should now be included in a single dictionary. The model is loaded with from_transformers just like the Transformers model, but the second argument must be a processor instead of a tokenizer.
Documentation

# v0
from io import BytesIO
from urllib.request import urlopen
from PIL import Image
from transformers import LlavaForConditionalGeneration
from outlines import models, generate

def img_from_url(url):
    img_byte_stream = BytesIO(urlopen(url).read())
    return Image.open(img_byte_stream).convert("RGB")

model = models.transformers_vision(
    model_name="trl-internal-testing/tiny-LlavaForConditionalGeneration",
    model_class=LlavaForConditionalGeneration,
)
generator = generate.text(model)
result = generator(
    "Describe the image <image>",
    img_from_url("https://upload.wikimedia.org/wikipedia/commons/2/25/Siam_lilacpoint.jpg")
)

# v1
from io import BytesIO
from urllib.request import urlopen
from PIL import Image
from transformers import LlavaForConditionalGeneration, AutoProcessor
import outlines

def img_from_url(url):
    img_byte_stream = BytesIO(urlopen(url).read())
    return Image.open(img_byte_stream).convert("RGB")

model = outlines.from_transformers(
	LlavaForConditionalGeneration.from_pretrained("trl-internal-testing/tiny-LlavaForConditionalGeneration"),
	AutoProcessor.from_pretrained("trl-internal-testing/tiny-LlavaForConditionalGeneration")
)
image = img_from_url("https://upload.wikimedia.org/wikipedia/commons/2/25/Siam_lilacpoint.jpg")
result = model({"text": "Describe the image <image>", "images": image})

The Exllamav2 model has been deprecated without replacement because its interface is not fully compatible with Outlines. We had to implement cumbersome patching to make it work, so we decided to remove it entirely.
The function module and the associated Function class have been deprecated. They are replaced by the Application class, which serves a similar purpose to Function. There are two notable differences: an Application is not initialized with a model (a model must be provided when calling the object), and template variables must be provided in a dictionary instead of as keyword arguments when calling the Application.
Documentation

# v0
from pydantic import BaseModel
from outlines import Function, Template

class Character(BaseModel):
	name: str

template = Template.from_string("Create a {{ gender }} character.")
fn = Function(template, Character, "hf-internal-testing/tiny-random-GPTJForCausalLM")
response = fn(gender="female")

# v1
from pydantic import BaseModel
from outlines import Application, Template, from_transformers
from transformers import AutoModelForCausalLM, AutoTokenizer

class Character(BaseModel):
	name: str

model = from_transformers(
    AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
    AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct")
)

template = Template.from_string("Create a {{ gender }} character.")
app = Application(template, Character)
response = app(model, {"gender": "female"})

The samplers module and the associated objects (multinomial, greedy…) have been deprecated. You should now use the inference arguments specific to the inference library your model is based on to control the sampling.

# v0
from outlines import generate, models, samplers

model = models.transformers("microsoft/Phi-3-mini-4k-instruct")
generator = generate.text(model, samplers.beam_search(2))
response = generator("Write a short story about a cat", max_tokens=10)

# v1
from outlines import Generator, from_transformers
from transformers import AutoModelForCausalLM, AutoTokenizer

model = from_transformers(
    AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
    AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct")
)
response = model("Write a short story about a cat", num_beams=2)

The load_lora methods on the VLLM and LlamaCpp models have been deprecated. You should now load through the Llama instance provided when initializing the model in the case of the LlamaCpp model, and provide it as a keyword argument when calling the model in the case of the VLLM model.

# v0
from outlines import models
from vllm import LLM

model = models.vllm("erwanf/gpt2-mini")
model.load_lora("path/to/lora/file")
response = model("Write a short story about a cat.")

#v1
from outlines import from_vllm
from vllm import LLM
from vllm.lora.request import LoRARequest

model = from_vllm(
    LLM("microsoft/Phi-3-mini-4k-instruct")
)
lora_request = LoRARequest("path/to/lora/file", 1, "path/to/lora/file")
response = model("Write a short story about a cat.", lora_request=lora_request)

Modified

Some objects are maintained, but their interface or behavior has been modified.

The interface of Model classes (Transformers, OpenAI, etc.) has been significantly modified. Models can now be called directly with a prompt and an output type without having to create a generator first. Additionally, all models have a stream method that can be invoked directly by the user.
Documentation

# v0
from pydantic import BaseModel
from outlines import generate, models

class Character(BaseModel):
		name: str

model = models.openai("gpt-4o")
generator = generate.json(model, Character)
result = generator("Create a character")

# v1
from openai import OpenAI
from pydantic import BaseModel
from outlines import from_openai

class Character(BaseModel):
	name: str

model = from_openai(OpenAI(), "gpt-4o")
result = model("Create a character", Character)

The interface of the __init__ method of the OpenAI model class has been modified. While it previously accepted a client and an OpenAIConfig object instance, it now accepts a client and a model name. The inference arguments from the config object should now be specified when calling the model to more closely align with the OpenAI Python library's functionality. If you provide an OpenAIConfig instance when initializing the model, a deprecation warning will appear and your model will behave like a v0 model.
We recommend using the from_openai function instead of initializing models directly.
[Documentation](https://dottxt-ai.gith...

Assets 2

03 Apr 10:47

rlouf

0.2.3

05d775f

Outlines v0.2.3

What's Changed

JSON schema error when using OpenAI with Pydantic model by @derfred in #1472
Tweak version commands in bug_report.yml by @nchammas in #1476
Fix capitalization in installation.md by @cpfiffer in #1488
Remove all issue templates except bug reports by @rlouf in #1496
Update the logo by @rlouf in #1521

New Contributors

@nchammas made their first contribution in #1476

Full Changelog: 0.2.2...0.2.3

Contributors

derfred, cpfiffer, and 2 other contributors

Assets 2

04 Mar 15:42

RobinPicard

0.2.2

fde48c8

Outlines v0.2.2

What's Changed

Update prompt templating documentation by @rlouf in #1448
Format files and fix numerous mypy warnings, thanks to ruff by @yvan-sraka in #1470
Remove pre-commit runtime dependency by @yvan-sraka in #1468
Improve the regex DSL (replace | by either and introduce new quantifiers) by @rlouf in #1463

Full Changelog: 0.2.1...0.2.2

Contributors

yvan-sraka and rlouf

Assets 2

24 Feb 08:47

rlouf

0.2.1

ce27432

Outlines v0.2.1

What's Changed

Various docs fixes by @EdAbati in #1429
Add Bluesky social media profile link to docs by @deepybee in #1435
Rename Prompt to Template and add deprecation warning to the prompt decorator by @rlouf in #1440

New Contributors

@deepybee made their first contribution in #1435

Full Changelog: 0.2.0...0.2.1

Contributors

rlouf, deepybee, and EdAbati

Assets 2

19 Feb 21:00

rlouf

0.2.0

116ebff

Outlines v0.2.0

What's Changed

Add a few dotfiles to improve newcomers' experience by @yvan-sraka in #1368
Update Dockerfile to Multi-Stage by @multi-stager in #1401
Add DevContainer configuration file by @yvan-sraka in #1389
Replaced pycountry with iso3166 for Better Licensing Compliance by @aman-17 in #1410
Update "Contribute" guide with uv and DevContainer intructions by @yvan-sraka in #1405
Reproducible Python virtual environment using uv and nix by @yvan-sraka in #1387
Fix documentation error #1426 by @cpfiffer in #1427
Fix cache dir, make it more robust when there is no $HOME by @larroy in #1425
Add a DSL to generate regular expressions by @rlouf in #1403

New Contributors

@multi-stager made their first contribution in #1401
@aman-17 made their first contribution in #1410
@larroy made their first contribution in #1425

Full Changelog: 0.1.14...0.2.0

Contributors

cpfiffer, yvan-sraka, and 4 other contributors

Assets 2

27 Jan 17:28

rlouf

0.1.14

437ffe4

Outlines v0.1.14

What's Changed

Fix typo in examples docs by @petros in #1379
Fix readme to reflect routing through enum by @farnasirim in #1382
Sort, clean and update .gitignore by @yvan-sraka in #1388
Update README to include chat templating by @cpfiffer in #1372
Add genson integration for json generation by @g-prz in #1390

New Contributors

@petros made their first contribution in #1379
@farnasirim made their first contribution in #1382

Full Changelog: 0.1.13...0.1.14

Contributors

petros, cpfiffer, and 3 other contributors

Assets 2

15 Jan 12:29

rlouf

0.1.13

088f439

Outlines v0.1.13

What's Changed

Update react_agent.md with current import structure by @pervrosen in #1375
[docs] Fix transformers_vision multiple Images example by @gante in #1370
Fix vllm-related pytest warning (that was spaming user) by @yvan-sraka in #1362
add filters to prompt function by @derfred in #1371
Remove incorrect text from feature matrix docs by @cpfiffer in #1377
Update vllm_integration.py to the latest version of outlines by @denadai2 in #1352
[MLX] [bugfix] Preserve dtype of array when converting to torch by @neilmehta24 in #1349