The DatetimeOutputParser is an output parser that generates structured outputs in the form of datetime objects.
By converting the outputs of LLMs into datetime objects, it enables more systematic and consistent processing of date and time data, making it useful for data processing and analysis.
This tutorial demonstrates how to use the DatetimeOutputParser to:
Set up and initialize the parser for datetime generation
Convert a datetime object to a string
Table of Contents
References
Environment Setup
[Note]
langchain-opentutorial is a package that provides a set of easy-to-use environment setup, useful functions and utilities for tutorials.
You can alternatively set OPENAI_API_KEY in .env file and load it.
[Note] This is not necessary if you've already set OPENAI_API_KEY in previous steps.
from dotenv import load_dotenv
load_dotenv(override=True)
False
Using the DatetimeOutputParser
If you need to generate output in the form of a date or time, the DatetimeOutputParser from LangChain simplifies the process.
The format of the DatetimeOutputParser can be specified by referring to the table below.
Format Code
Description
Example
%Y
4-digit year
2024
%y
2-digit year
24
%m
2-digit month
07
%d
2-digit day
04
%H
24-hour format hour
14
%I
12-hour format hour
02
%p
AM or PM
PM
%M
2-digit minute
45
%S
2-digit second
08
%f
Microsecond (6 digits)
000123
%z
UTC offset
+0900
%Z
Timezone name
KST
%a
Abbreviated weekday
Thu
%A
Full weekday name
Thursday
%b
Abbreviated month
Jul
%B
Full month name
July
%c
Full date and time
Thu Jul 4 14:45:08 2024
%x
Full date
07/04/24
%X
Full time
14:45:08
from langchain.output_parsers import DatetimeOutputParser
from langchain_core.prompts import PromptTemplate
# Initialize the output parser
output_parser = DatetimeOutputParser()
# Specify date format
date_format = "%Y-%m-%d"
output_parser.format = date_format
# Get format instructions
format_instructions = output_parser.get_format_instructions()
# Create answer template for user questions
template = """Answer the users question:\n\n#Format Instructions: \n{format_instructions}\n\n#Question: \n{question}\n\n#Answer:"""
# Create a prompt from the template
prompt = PromptTemplate.from_template(
template,
partial_variables={
"format_instructions": format_instructions,
}, # Use parser's format instructions
)
print(format_instructions)
print("-----------------------------------------------\n")
print(prompt)
Write a datetime string that matches the following pattern: '%Y-%m-%d'.
Examples: 0594-05-12, 0088-08-25, 0371-10-02
Return ONLY this string, no other words!
-----------------------------------------------
input_variables=['question'] input_types={} partial_variables={'format_instructions': "Write a datetime string that matches the following pattern: '%Y-%m-%d'.\n\nExamples: 0594-05-12, 0088-08-25, 0371-10-02\n\nReturn ONLY this string, no other words!"} template='Answer the users question:\n\n#Format Instructions: \n{format_instructions}\n\n#Question: \n{question}\n\n#Answer:'
from langchain_openai import ChatOpenAI
model = ChatOpenAI(temperature=0, model_name="gpt-4o-mini")
# Combine the prompt, chat model, and output parser into a chain
chain = prompt | model | output_parser
# Call the chain to get an answer to the question
output = chain.invoke({"question": "The year Google was founded"})
print(output)
print(type(output))
1998-09-04 00:00:00
# Convert the result to a string
output.strftime(date_format)
'1998-09-04'
Using DatetimeOutputParser in astream
Let's create a simple example that converts astream output to datetime objects using a generator function.
from langchain_core.output_parsers.string import StrOutputParser
from langchain.output_parsers.datetime import DatetimeOutputParser
from langchain_core.prompts.prompt import PromptTemplate
from langchain_openai.chat_models.base import ChatOpenAI
import datetime
from typing import AsyncIterator, List
# Initialize the output parser
output_parser = DatetimeOutputParser()
# Specify date format
date_format = "%Y-%m-%d"
output_parser.format = date_format
# Get format instructions
format_instructions = output_parser.get_format_instructions()
# Create answer template for user questions
template = (
"Answer the users question:\n\n"
"#Format Instructions: \n{format_instructions}\n"
"Write a comma-separated list of 5 founding years of companies similar to: {company}"
)
# Create a prompt from the template
prompt = PromptTemplate.from_template(
template,
partial_variables={"format_instructions": format_instructions},
)
# Initialize the ChatOpenAI model with temperature set to 0.0
model = ChatOpenAI(temperature=0.0, model_name="gpt-4o-mini")
# Create a chain combining the prompt, model, and string output parser
str_chain = prompt | model | StrOutputParser()
# Define an asynchronous function to convert strings to datetime objects
async def convert_strings_to_datetime(
input: AsyncIterator[str],
) -> AsyncIterator[List[datetime.datetime]]:
buffer = ""
async for chunk in input:
buffer += chunk
while "," in buffer:
comma_index = buffer.index(",")
date_str = buffer[:comma_index].strip()
date_obj = output_parser.parse(date_str) # Convert to datetime object
yield [date_obj]
buffer = buffer[comma_index + 1 :]
date_str = buffer.strip()
if date_str:
date_obj = output_parser.parse(
date_str
) # Convert remaining buffer to datetime object
yield [date_obj]
# Connect the str_chain and convert_strings_to_datetime in a pipeline
alist_chain = str_chain | convert_strings_to_datetime
# Use async for loop to stream data.
async for chunk in alist_chain.astream({"company": "Google"}):
# Print each chunk and flush the buffer.
print(chunk, flush=True)
