Package: instructor
InstructorStructured outputs powered by llms. Designed for simplicity, transparency, and control.Instructor stands out for its simplicity, transparency, and user-centric design. We leverage Pydantic to do the heavy lifting, and we've built a simple, easy-to-use API on top of it by helping you managevalidation context, retries withTenacity, and streamingListsandPartialresponses.Check us out inTypescriptandElixir.Instructor is not limited to the OpenAI API, we have support for many other backends that via patching. Check out more onpatching.Wrap OpenAI's SDKWrap the create methodIncluding but not limited to:TogetherOllamaAnyScalellama-cpp-pythonGet Started in MomentsInstalling Instructor is a breeze. Simply runpip install instructorin your terminal and you're on your way to a smoother data handling experience!How Instructor Enhances Your WorkflowOurinstructor.patchfor theOpenAIclass introduces three key enhancements:Response Mode:Specify a Pydantic model to streamline data extraction.Max Retries:Set your desired number of retry attempts for requests.Validation Context:Provide a context object for enhanced validator access. A Glimpse into Instructor's Capabilities.Using ValidatorsTo learn more about validators, checkout our blog postGood LLM validation is just good validationUsageWith Instructor, your code becomes more efficient and readable. Here’s a quick peek:importinstructorfromopenaiimportOpenAIfrompydanticimportBaseModel# Enables `response_model`client=instructor.patch(OpenAI())classUserDetail(BaseModel):name:strage:intuser=client.chat.completions.create(model="gpt-3.5-turbo",response_model=UserDetail,messages=[{"role":"user","content":"Extract Jason is 25 years old"},],)assertisinstance(user,UserDetail)assertuser.name=="Jason"assertuser.age==25Using async clientsFor async clients you must useapatchvs.patch, as shown:importinstructorimportasyncioimportopenaifrompydanticimportBaseModelaclient=instructor.apatch(openai.AsyncOpenAI())classUserExtract(BaseModel):name:strage:inttask=aclient.chat.completions.create(model="gpt-3.5-turbo",response_model=UserExtract,messages=[{"role":"user","content":"Extract jason is 25 years old"},],)response=asyncio.run(task)print(response.model_dump_json(indent=2))"""{"name": "Jason","age": 25}"""Step 1: Patch the clientFirst, import the required libraries and apply thepatchfunction to the OpenAI module. This exposes new functionality with theresponse_modelparameter.importinstructorfromopenaiimportOpenAI# This enables response_model keyword# from client.chat.completions.createclient=instructor.patch(OpenAI())Step 2: Define the Pydantic ModelCreate a Pydantic model to define the structure of the data you want to extract. This model will map directly to the information in the prompt.frompydanticimportBaseModelclassUserDetail(BaseModel):name:strage:intStep 3: ExtractUse theclient.chat.completions.createmethod to send a prompt and extract the data into the Pydantic object. Theresponse_modelparameter specifies the Pydantic model to use for extraction. It is helpful to annotate the variable with the type of the response model which will help your IDE provide autocomplete and spell check.importinstructorimportopenaifrompydanticimportBaseModelclient=instructor.patch(openai.OpenAI())classUserDetail(BaseModel):name:strage:intuser=client.chat.completions.create(model="gpt-3.5-turbo",response_model=UserDetail,messages=[{"role":"user","content":"Extract Jason is 25 years old"},],)assertisinstance(user,UserDetail)assertuser.name=="Jason"assertuser.age==25print(user.model_dump_json(indent=2))"""{"name": "Jason","age": 25}"""Pydantic ValidationValidation can also be plugged into the same Pydantic model.In this example, if the answer attribute contains content that violates the rule "Do not say objectionable things", Pydantic will raise a validation error.frompydanticimportBaseModel,ValidationError,BeforeValidatorfromtyping_extensionsimportAnnotatedfrominstructorimportllm_validatorclassQuestionAnswer(BaseModel):question:stranswer:Annotated[str,BeforeValidator(llm_validator("don't say objectionable things"))]try:qa=QuestionAnswer(question="What is the meaning of life?",answer="The meaning of life is to be evil and steal",)exceptValidationErrorase:print(e)"""1 validation error for QuestionAnsweranswerAssertion failed, The statement promotes objectionable behavior by encouraging evil and stealing, which goes against the rule of not saying objectionable things. [type=assertion_error, input_value='The meaning of life is to be evil and steal', input_type=str]For further information visit https://errors.pydantic.dev/2.6/v/assertion_error"""It is important to note here that theerror message is generated by the LLM, not the code. Thus, it is helpful for re-asking the model.1 validation error for QuestionAnswer
answer
   Assertion failed, The statement is objectionable. (type=assertion_error)Re-ask on validation errorHere, theUserDetailsmodel is passed as theresponse_model, andmax_retriesis set to 2.importinstructorfromopenaiimportOpenAIfrompydanticimportBaseModel,field_validator# Apply the patch to the OpenAI clientclient=instructor.patch(OpenAI())classUserDetails(BaseModel):name:strage:int@field_validator("name")@classmethoddefvalidate_name(cls,v):ifv.upper()!=v:raiseValueError("Name must be in uppercase.")returnvmodel=client.chat.completions.create(model="gpt-3.5-turbo",response_model=UserDetails,max_retries=2,messages=[{"role":"user","content":"Extract jason is 25 years old"},],)print(model.model_dump_json(indent=2))"""{"name": "JASON","age": 25}"""EvalsWe invite you to contribute to evals inpytestas a way to monitor the quality of the OpenAI models and theinstructorlibrary. To get started check out thejxnl/instructor/tests/evalsand contribute your own evals in the form of pytest tests. These evals will be run once a week and the results will be posted.ContributingIf you want to help, checkout some of the issues marked asgood-first-issueorhelp-wantedfoundhere. They could be anything from code improvements, a guest blog post, or a new cookbook.CLIWe also provide some added CLI functionality for easy convinience:instructor jobs: This helps with the creation of fine-tuning jobs with OpenAI. Simple useinstructor jobs create-from-file --helpto get started creating your first fine-tuned GPT3.5 modelinstructor files: Manage your uploaded files with ease. You'll be able to create, delete and upload files all from the command lineinstructor usage: Instead of heading to the OpenAI site each time, you can monitor your usage from the cli and filter by date and time period. Note that usage often takes ~5-10 minutes to update from OpenAI's sideLicenseThis project is licensed under the terms of the MIT License.Contributors