
syncode
Efficient and general syntactical decoding for Large Language Models
Stars: 251

README:
âšī¸Â About | đ Features | đ More About SynCode | đ Quick Start | đ Example Usage | đ¤Â FAQs
- SynCode is a novel framework for the grammar-guided generation of Large Language Models (LLMs) that is scalable to general-purpose programming languages and has soundness and completeness guarantees.
- With SynCode, you can ensure that your Language Model is generating output that is syntactically valid with respect to the rules defined by a Context-Free Grammar (CFG).
- For example, SynCode gets 99% accuracy in JSON generation with Gemma-2b (check here) and is 10-20% faster than standard unconstrained generation
Check Grammars directory for supported grammars
Define your own grammar using simple EBNF syntax. Check out our notebooks directory for examples and a quick example at
Â
đĨ Fast grammar-guided generation (as little as 10% generation overhead with Python and Go!) |
đ¤ Seamlessly work with any HuggingFace Language Model, including Code, Chat, and Instruct models |
đī¸ Pass in any CFG in the EBNF format (even large grammars for programming languages like Python and Go!) |
đ Built-in CFGs for Python, Go, SQL, Math, JSON, and more! |
đ˛ Sample with any existing decoding strategy (eg. greedy, beam search, nucleus sampling) |
You can install SynCode via PyPI:
pip install syncode
Alternatively, you can install the latest development version directly from GitHub:
pip install git+https://github.com/structuredllm/syncode.git
SynCode depends on HuggingFace transformers:
SynCode version | Required transformers version | Python version |
---|---|---|
v0.4.10 (latest) |
v4.44.0 |
3.6 - 3.12 |
Note: Python 3.13 is not currently supported due to dependency constraints.
SynCode can be used as a simple logit processor with HuggingFace transformers library interface. Check this notebook for example.
Just import with and initialize it with the appropriate grammar
from syncode import SyncodeLogitsProcessor
and this can be passed as an argument to generate
function. For example,
output = model.generate(
inputs,
max_length=100,
pad_token_id=tokenizer.eos_token_id,
logits_processor=[syncode_logits_processor]
)
The other option is to use the SynCode
object for inference (this comes with additional optimizations),
from syncode import Syncode
Refer to SynCode Arguments for the full list of arguments to initialize the SynCode class. In Python, inference is performed using the infer() method in the SynCode class. infer() has the following arguments:
-
prompt
(str, optional): Prompt to the Language Model. Defaults to None. -
task_id
(int, optional): Problem task id for selecting a problem from a Dataset. Defaults to None.
If both prompt
and task_id
are not specified, infer() reads user input via stdin
.
The following example shows the benefit of SynCode:
In the example below, the unconstrained original Phi-2 model fails to generate a valid JSON object and instead generates Python code.
from syncode import Syncode
# Load the unconstrained original model
llm = Syncode(model="microsoft/phi-2", mode='original', max_new_tokens=50)
prompt = "Please return a JSON object to represent the country India with name, capital, and population?"
output = llm.infer(prompt)[0]
print(f"LLM output:\n{output}\n")
# LLM output:
#
# A:
#
# You can use the following code:
# import json
#
# def get_country_info(country_name):
# country_info = {
# 'name': country_name,
# 'capital':
When guided with the JSON grammar with SynCode, the model can generate a syntactically valid JSON object.
from syncode import Syncode
# Load the Syncode augmented model
syn_llm = Syncode(model = "microsoft/phi-2", grammar='json', parse_output_only=True, max_new_tokens=50)
prompt = "Please return a JSON object to represent the country India with name, capital, and population?"
output = syn_llm.infer(prompt)[0]
print(f"SynCode output:\n{output}")
# SynCode output:
# {
# "name": "India",
# "capital": "New Delhi",
# "population": "1,366,417,754"
# }
Check more examples of using Python, Go, and other grammars in Notebooks and a quick example at
Â
SynCode can also be used with Instruct-tuned models. For example, the following code snippet shows how to use SynCode with the Instruct-tuned LLM model.
messages = [
{"role": "system", "content": "You are a chatbot who always returns a JSON object."},
{"role": "user", "content": "can you give me a JSON object describing University of Illinois at Urbana-Champaign?"},
]
out = syn_llm.infer(messages)
See the notebook for example.
Optionally, you can set the directories for cache by exporting the following environment variables. Add the following lines to your .bashrc or .zshrc file:
export HF_CACHE="path_to_hf_cache"
export SYNCODE_CACHE="path_to_syncode_cache"
If these environment variables are not set, the tool will use the default cache directories.
To use the gated models on HuggingFace such as Llamma models, you can set the environment variable HF_ACCESS_TOKEN
export HF_ACCESS_TOKEN="your_huggingface_api_key"
Click to Expand on the List of Arguments for SynCode
-
mode
(str, optional): Mode for inference.grammar_mask
andgrammar_strict
are the modes that enable our tool.original
is the mode for the original LLM. Defaults to "grammar_strict". "original" mode are used for the original LLM without any grammar constraints and "grammar_strict" mode is a stricter mode for a grammar-constrained generation. -
model
(str): Model ID for Hugging Face model hub or model name if stored locally. -
quantize
(bool, optional): Quantize the model to bfloat16. Defaults to True. -
device
(str, optional): The device on which the model is run. Defaults tocuda
. -
grammar
(str, optional): Grammar in EBNF form (string or file path) or language for constrained generation. Defaults to None. You can use one of thepython
,go
,sql
,json
,java
,calc
or pass in a custom grammar (check notebooks for examples) in EBNF format. -
num_samples
(int, optional): Number of samples. Defaults to 1. -
dataset
(str, optional): Dataset. Defaults to "input". "input" indicates that the user can provide input via CLI or by passing in a prompt as a string. -
num_few_shot
(int, optional): Number of examples for few-shot prompting. Defaults to 0. -
dev_mode
(bool, optional): Development mode where we do not fail silently with parser errors. Defaults to False. -
log_level
(int, optional): 0 for no logs, 1 for minimal logs, 2 for all logs including time. Defaults to 2. -
new_mask_store
(bool, optional): Forces to use a new mask store otherwise use a cached mask store if available. Defaults to False. -
parser
(str, optional): Choose between LR(1) and LALR(1) parsing. Defaults to 'lalr'. -
task_id
(int, optional): Problem task id for selecting a problem from a Dataset. -
device_map
(str, optional): Device map for the model. Defaults to None. -
kwargs
(void, optional): Currently supportedkwargs
aremax_length
,max_new_tokens
,min_length
,min_new_tokens
,early_stopping
,do_sample
,num_beams
,use_cache
,temperature
,top_k
,top_p
,num_return_sequences
,pad_token_id
, andeos_token_id
. Refer to the HuggingFace Text Generation Documentation for more information.
Running SynCode via CLI
Clone this repository:
git clone https://github.com/structuredllm/syncode.git
To run the tool with CLI, use the following command:
python3 syncode/infer.py
--mode [original, grammar_mask, grammar_strict]
--model [model_name]
--quantize [True, False]
--device ["cpu", "cuda", "cuda:1" etc.]
--num_samples [num_samples]
--dataset [mbxp, humaneval, mathqa-x, input]
--few_shot [True, False]
--num_fs_examples [num_fs_examples]
--dev_mode [True, False]
--log_level [0, 1, 2]
--new_mask_store [True, False]
--parser ["lr", "lalr"]
--task_id [task_id]
--device_map [device_map]
Check out our notebooks directory which contains various interactive examples that showcase different use cases of SynCode! The grammars for some common programming languages are defined in the grammars directory. We also allow users to define a grammar using a simple EBNF syntax adapted from Lark. Users can pass in a string of rules or a path to a .lark file.
Large Language Models tend to struggle with generating Python code with correct indentation. Consider the example below. The unconstrained original
WizardCoder model fails to generate a code completion with the correct number of spaces. When executing this code, we get an Indentation Error.
from syncode import Syncode
model_name = "WizardLM/WizardCoder-1B-V1.0"
# Load the unconstrained original model
llm = Syncode(model = model_name, mode='original', max_new_tokens=200)
partial_code = "def is_prime(n):\n '''Return if prime'''\n "
#generate a completion to the input partial code
unconstrained_output = partial_code+llm.infer(partial_code)[0]
print(unconstrained_output)
# def is_prime(n):
# '''Return if prime'''
# if n < 2:
# return False
# for i in range(2, int(n**0.5)+1):
# if n % i == 0:
# return False
# return True
exec(unconstrained_output)
# IndentationError: unindent does not match any outer indentation level
SynCode can fix this problem! We simply switch the mode to grammar_mask
/grammar_strict
to load the SynCode augmented model. With the constrained decoding of SynCode, the LLM is able to generate a correct Python program.
from syncode import Syncode
model_name = "WizardLM/WizardCoder-1B-V1.0"
# Load the Syncode augmented model
syn_llm = Syncode(model=model_name, mode='grammar_strict', grammar='python', parse_output_only=False)
partial_code = "def is_prime(n):\n '''Return if prime'''\n "
#generate a completion to the input partial code
constrained_output = partial_code+ syn_llm.infer(partial_code)[0]
print(constrained_output)
# def is_prime(n):
# '''Return if prime'''
# if n < 2:
# return False
# for i in range(2, int(n**0.5) + 1):
# if n % i == 0:
# return False
# return True
exec(constrained_output)
# Correct Code :)
In the example below, the unconstrained original Phi-2 model fails to generate a valid JSON object and instead generates Python code.
from syncode import Syncode
# Load the unconstrained original model
llm = Syncode(model = "microsoft/phi-2", mode='original', max_new_tokens=50)
prompt = "Please return a json object to represent country India with name, capital and population?"
output = llm.infer(prompt)[0]
print(f"LLM output:\n{output}\n")
# LLM output:
#
# A:
#
# You can use the following code:
# import json
#
# def get_country_info(country_name):
# country_info = {
# 'name': country_name,
# 'capital':
When guided with the JSON grammar with SynCode, the model is able to generate a syntactically valid JSON object.
from syncode import Syncode
# Load the Syncode augmented model
syn_llm = Syncode(model="microsoft/phi-2", grammar='json', parse_output_only=True, max_new_tokens=50)
prompt = "Please return a json object to represent country India with name, capital and population?"
output = syn_llm.infer(prompt)[0]
print(f"SynCode output:\n{output}")
# SynCode output:
# {
# "name": "India",
# "capital": "New Delhi",
# "population": "1,366,417,754"
# }
Syncode allows users to define grammar using a simple EBNF syntax adapted from Lark. One can also simply feed the grammar rules directly as a string of rules as shown below.
Please refer to the notebooks directory for examples using custom grammars and instructions for instructions to define your own custom grammar.
In our example, we want our model to only respond in the format month day
. Without constrained decoding, the Language Model may not generate output that follows this syntax. Consider the code snippet below.
from syncode import Syncode
model_name = "microsoft/phi-2"
# Load the unconstrained original model
llm = Syncode(model=model_name, mode='original', max_new_tokens=20)
inp = "When is the christmas day?"
output = llm.infer(inp)
print(f"LLM output:\n{repr(output)}\n")
# LLM output:
# 'Christmas Day is on December 25th.\n<|im_end|>\n<|im'
As shown above, the LLM generates a correct response but not in the format we want. We can pass in a grammar and leverage the ability of SynCode to guide the LLM generation with this grammar. As shown in the snippet below, the SynCode augmented LLM generates output in the correct month day
format.
from syncode import Syncode
# Pass in a grammar as a string of rules in EBNF format
grammar = """ start: month day
day: /[1-9]/ | /[1-2][0-9]/ | /3[0-1]/
month: "January" | "February" | "March" | "April" | "May" | "June" | "July" | "August" | "September" | "October" | "November" | "December"
"""
model_name = "microsoft/phi-2"
# Load the Syncode augmented model
syn_llm = Syncode(model=model_name, grammar=grammar, parse_output_only=True)
inp = "When is the christmas day?"
output = syn_llm.infer(inp)
print(f"Syncode augmented LLM output:\n{output}")
# Syncode augmented LLM output:
# December 25
Â
@misc{ugare2024syncode,
title={SynCode: LLM Generation with Grammar Augmentation},
author={Shubham Ugare and Tarun Suresh and Hangoo Kang and Sasa Misailovic and Gagandeep Singh},
year={2024},
eprint={2403.01632},
archivePrefix={arXiv},
primaryClass={cs.LG}
}
In the SynCode workflow, the LLM takes partial code Ck and generates a distribution for the next token tk+1. The incremental parser processes Ck to generate accept sequences A, the sequences of terminals that can follow partial code called accept sequences. Simultaneously, the incremental parser computes a remainder r from the partial code, representing the suffix that may change its terminal type in subsequent generations. The backbone of SynCode is the offline construction of a DFA mask store, a lookup table derived from regular expressions representing the terminals of the language grammar. The DFA mask store facilitates efficient traversal of DFA states, enabling the retrieval of masks mapped to each state and accept sequence. SynCode walks over the DFA using the remainder and uses the mask store to compute the mask specific to each accept sequence. By unifying masks for each accept sequence SynCode gets the set of syntactically valid tokens. The LLM iteratively generates a token tk+1 using the distribution and the mask, appending it to Ck to create the updated code Ck+1. The process continues until the LLM returns the final code Cn based on the defined stop condition.
Tool | Regex | CFG* | Pre-Computed* | GPL* |
---|---|---|---|---|
LMQL |
â | â | â | â |
GUIDANCE |
â | â | â | â |
OUTLINES |
â | â | â | â |
PICARD |
â | â | â | â |
SYNCHROMESH |
â | â | â | â |
LLAMA.CPP |
â | â | â | â |
GCD |
â | â | â | â |
SynCode | â | â | â | â |
CFG*: Guide generation with a Context Free Grammar (CFG)
Pre-Computed*: Precompute masks over the vocabulary to significantly improve generation speed
GPL*: Support general-purpose programming languages, which involve non-context-free fragments, such as indentation in Python and end-of-scope markers in Golang.
For questions, please contact Shubham Ugare.
For Tasks:
Click tags to check more tools for each tasksFor Jobs:
Alternative AI tools for syncode
Similar Open Source Tools

syncode
SynCode is a novel framework for the grammar-guided generation of Large Language Models (LLMs) that ensures syntactically valid output with respect to defined Context-Free Grammar (CFG) rules. It supports general-purpose programming languages like Python, Go, SQL, JSON, and more, allowing users to define custom grammars using EBNF syntax. The tool compares favorably to other constrained decoders and offers features like fast grammar-guided generation, compatibility with HuggingFace Language Models, and the ability to work with various decoding strategies.

mistral-inference
Mistral Inference repository contains minimal code to run 7B, 8x7B, and 8x22B models. It provides model download links, installation instructions, and usage guidelines for running models via CLI or Python. The repository also includes information on guardrailing, model platforms, deployment, and references. Users can interact with models through commands like mistral-demo, mistral-chat, and mistral-common. Mistral AI models support function calling and chat interactions for tasks like testing models, chatting with models, and using Codestral as a coding assistant. The repository offers detailed documentation and links to blogs for further information.

HippoRAG
HippoRAG is a novel retrieval augmented generation (RAG) framework inspired by the neurobiology of human long-term memory that enables Large Language Models (LLMs) to continuously integrate knowledge across external documents. It provides RAG systems with capabilities that usually require a costly and high-latency iterative LLM pipeline for only a fraction of the computational cost. The tool facilitates setting up retrieval corpus, indexing, and retrieval processes for LLMs, offering flexibility in choosing different online LLM APIs or offline LLM deployments through LangChain integration. Users can run retrieval on pre-defined queries or integrate directly with the HippoRAG API. The tool also supports reproducibility of experiments and provides data, baselines, and hyperparameter tuning scripts for research purposes.

mlx-llm
mlx-llm is a library that allows you to run Large Language Models (LLMs) on Apple Silicon devices in real-time using Apple's MLX framework. It provides a simple and easy-to-use API for creating, loading, and using LLM models, as well as a variety of applications such as chatbots, fine-tuning, and retrieval-augmented generation.

client-python
The Mistral Python Client is a tool inspired by cohere-python that allows users to interact with the Mistral AI API. It provides functionalities to access and utilize the AI capabilities offered by Mistral. Users can easily install the client using pip and manage dependencies using poetry. The client includes examples demonstrating how to use the API for various tasks, such as chat interactions. To get started, users need to obtain a Mistral API Key and set it as an environment variable. Overall, the Mistral Python Client simplifies the integration of Mistral AI services into Python applications.

magentic
Easily integrate Large Language Models into your Python code. Simply use the `@prompt` and `@chatprompt` decorators to create functions that return structured output from the LLM. Mix LLM queries and function calling with regular Python code to create complex logic.

langchainrb
Langchain.rb is a Ruby library that makes it easy to build LLM-powered applications. It provides a unified interface to a variety of LLMs, vector search databases, and other tools, making it easy to build and deploy RAG (Retrieval Augmented Generation) systems and assistants. Langchain.rb is open source and available under the MIT License.

llm-client
LLMClient is a JavaScript/TypeScript library that simplifies working with large language models (LLMs) by providing an easy-to-use interface for building and composing efficient prompts using prompt signatures. These signatures enable the automatic generation of typed prompts, allowing developers to leverage advanced capabilities like reasoning, function calling, RAG, ReAcT, and Chain of Thought. The library supports various LLMs and vector databases, making it a versatile tool for a wide range of applications.

neural-speed
Neural Speed is an innovative library designed to support the efficient inference of large language models (LLMs) on Intel platforms through the state-of-the-art (SOTA) low-bit quantization powered by Intel Neural Compressor. The work is inspired by llama.cpp and further optimized for Intel platforms with our innovations in NeurIPS' 2023

python-tgpt
Python-tgpt is a Python package that enables seamless interaction with over 45 free LLM providers without requiring an API key. It also provides image generation capabilities. The name _python-tgpt_ draws inspiration from its parent project tgpt, which operates on Golang. Through this Python adaptation, users can effortlessly engage with a number of free LLMs available, fostering a smoother AI interaction experience.

instructor
Instructor is a Python library that makes it a breeze to work with structured outputs from large language models (LLMs). Built on top of Pydantic, it provides a simple, transparent, and user-friendly API to manage validation, retries, and streaming responses. Get ready to supercharge your LLM workflows!

instructor
Instructor is a popular Python library for managing structured outputs from large language models (LLMs). It offers a user-friendly API for validation, retries, and streaming responses. With support for various LLM providers and multiple languages, Instructor simplifies working with LLM outputs. The library includes features like response models, retry management, validation, streaming support, and flexible backends. It also provides hooks for logging and monitoring LLM interactions, and supports integration with Anthropic, Cohere, Gemini, Litellm, and Google AI models. Instructor facilitates tasks such as extracting user data from natural language, creating fine-tuned models, managing uploaded files, and monitoring usage of OpenAI models.

LLMDebugger
This repository contains the code and dataset for LDB, a novel debugging framework that enables Large Language Models (LLMs) to refine their generated programs by tracking the values of intermediate variables throughout the runtime execution. LDB segments programs into basic blocks, allowing LLMs to concentrate on simpler code units, verify correctness block by block, and pinpoint errors efficiently. The tool provides APIs for debugging and generating code with debugging messages, mimicking how human developers debug programs.

clarifai-python
The Clarifai Python SDK offers a comprehensive set of tools to integrate Clarifai's AI platform to leverage computer vision capabilities like classification , detection ,segementation and natural language capabilities like classification , summarisation , generation , Q&A ,etc into your applications. With just a few lines of code, you can leverage cutting-edge artificial intelligence to unlock valuable insights from visual and textual content.

litdata
LitData is a tool designed for blazingly fast, distributed streaming of training data from any cloud storage. It allows users to transform and optimize data in cloud storage environments efficiently and intuitively, supporting various data types like images, text, video, audio, geo-spatial, and multimodal data. LitData integrates smoothly with frameworks such as LitGPT and PyTorch, enabling seamless streaming of data to multiple machines. Key features include multi-GPU/multi-node support, easy data mixing, pause & resume functionality, support for profiling, memory footprint reduction, cache size configuration, and on-prem optimizations. The tool also provides benchmarks for measuring streaming speed and conversion efficiency, along with runnable templates for different data types. LitData enables infinite cloud data processing by utilizing the Lightning.ai platform to scale data processing with optimized machines.