Skip to content

Commit

Permalink
docs: add docs on StrOutputParser (#28089)
Browse files Browse the repository at this point in the history
Think it's worth adding a quick guide and including in the table in the
concepts page. `StrOutputParser` can make it easier to deal with the
union type for message content. For example, ChatAnthropic with bound
tools will generate string content if there are no tool calls and
`list[dict]` content otherwise.

I'm also considering removing the output parser section from the
["quickstart"
tutorial](https://python.langchain.com/docs/tutorials/llm_chain/); we
can link to this guide instead.
  • Loading branch information
ccurme authored Nov 13, 2024
1 parent 6ec688c commit 940e93e
Show file tree
Hide file tree
Showing 7 changed files with 208 additions and 0 deletions.
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
eNrNVstu20YUbZbNqv0DYtDHRpRE01ZsFUXhyInbxI6d2ECcxIEwIkfiRNQMMzNU5BpcNO0P8BPaKFIgOA+jAbJouy266A+4i35L75DUK5ZtZFEn2lAzcx9nzn3MfdxvEyEpZxcOKFNEYEfBQsaP+4I8DIlUP/VaRHnc7W5ubG0/CQU9+txTKpDlQgEHNI+Z8gQPqJN3eKvQtgotIiVuENmtcXfvnwvuPmrhTlXxJmESlQ2rODefM9BQCnbu7SPBfQL/UCiJQHDqcIDClN667WH1pTSUR4xHBMNHGJQZW5gZVwVmDpUOzxmV5W9QdF+b5S7xtZrj49Alpm0umB6mzdD0sYLLaONSCYJbIKRESGCtOPczHAy3EhwNoqqZN63hEukIGmhi9OkqUVN46oK3DGz43MFaJK9VKAtCVZWOR1oYdPZRACQRoWhy5X00FE4Wai9I3AIyyhooisCAZp8K4mpgY2l9x6E0rz0gjgLp+1HfI9iFMP770Sddj0sVHx4LzUvsOCRQJmEOd8FL/LzxPQ1yhkvqmpoBUM5IEvt40CQkMLFP26SXasWvcBD4NAVReCA5O8hCZGo0x48HOpImBJip+M3yEEdhcw8yiRnFvH0pb73qmFJhynxIBQgPQOoFyflvkwcBdppgx8yyNO6lyi8mZbiMn65jZ2NryiQWjhc/xaJVmv91cl+ETNEWifuVzePussOxOztvWflLh1OG5R5z4qd17EtyOCJ5pDKYK87ZZrFkFq03U6aJEnumw8FD/HPxxZBAn7CG8uIn9kLpmSAygOIjP/ZATYXycReCRf7+q5+Vyy8b18eh/rS7AoGL/7hN3Jxh2cYN3jbA9bxhlcrzdtkqGavr2weVzM22jtORoUhHFUhb76R18JXheFhIor4OVd1cPNyGqpJ1CN6VYaL0HS9kTeIOKjNT5HkFQ5ab2g+UcfyMcdPRO0doTI0AoD5tUWVmTQUCrpdxd75YLB59caqkgBKiTCPp2ktLS2fYBQqJil9rIkzLMi17e0jH3SNjlmbamTI8PY0HEH12iuQYTw/waGnjVOkT8Qwy0CZ149/hf7VoLSwuXN9hrte5Vlsv8dbK3eZa55L1pE1xPLDyltHgvOGTl5WrZsr6VpImcX/lzo3l9e8qBzvmLV7jQMM2BroYZ6S3RQRkZjxwfB66UOuC9ED91vKd+PUimSvai/PWXN2u2bXSknl5Yytp2z/00lb0z8d/JrlSNrIErEJeCnXRxQqPGxeaOkS54RqV9xF19blswN3stfblRbuy9+2NoL56J2ytidVH7RUQn7YCG+lzgLCUFEyyxGTa2I/3dU0svClzIDN6Ne7dz0Ev5UEVElzqHstC38+2pOacOWS4GY6QJh17+E7Z9kIO8VBN7llRZOhfdPFixkrmsVqDBt2czc0MEYBKmUs6qFzMTZ9rHJmeLlTNjf6UEYom3QYQmrf8GChIno4ToAF5Cp8OLRGZgpbuTEMaiWXA1ohCKSvZ79wRQGpCCyNOU7/Jk1jOH4kTCqETcIqQ9wFkNJlwAWDO3//b4xk8FACFUTyk5twh5dFZtcuDs0qXBxNuz4zuu3cD65RuADNqFWYqLexm61D31Ic327Ur69cJaW/aOzevhUs7lU4HpNJJdnqQTVscWI2i/yU7reOhSJuqnghHwgHcmWI/2cw62/vGsL87nrCjD4WYXWjquyipJJjx3y+WiVL+cAha3kXRqdnzrjVtndS2h/PNzItNHaKJi0xNIJMVPGMOiSYGkbemjtJSdAKcWfebPEPji/wHR26g7g==
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
eNqFVF1MHFUUXlJJ1RdLNLYxJk4X0VS5uzM7W2BRk9JdFPnpImxTadPiZeayM93Ze4eZO5uupFax9UVFrz7U1FgrLLt1RSiRpBK01bSNxoga00SwsY1GH0x9MJo+kCbiHdjlJyDO08z5/c73nTN9uRSybJ3gkmEdU2RBhfIPm/XlLNTjIJsezSYR1YiaaY22xwYdS5+p0Cg17Vq/H5q6D2KqWcTUFZ9Ckv6U5E8i24ZxZGe6iJqeMXq9SXiok5IEwra3VpDEQLBS8BaDuGVfr9ciBuJvXsdGlpd7FcKRYOqaGpBhEO/h/W4OUZHh2hQDOioCMtgONKgnHGBAyoF6D+c0BFU+zVXPpoxGbMrGViEchYqCTAoQVoiq4zj7MP6sblYKKup2q+R5a4zmKWD5BEImgIaeQtmFLHYGmqahK9D1+w/aBA8XoAKaNtFqd96dCPBBMWVn64o4/K1pTigWRJ9c7ZPOHAI2hTo2OCV8Eg4pa877J5c7TKgkeB1QEItlF5JHlscQmw21QCXavqIktBSNDUErWRX8aLndcjDVk4jlwq2r2xWcS+1knyT5qsdWFLbTWGFD3dCw0dgiyYsp+YAYkIFYBUTp7IrSiFppoBDegb0njhQJNBCOU40NSmLNaQvZJt9B9GKWp1HH7stwsdDXX+YKazMQbVqSuiwT4cKxT/cgtVKQZGEXSQm8dVCQqmqDcq0UEJ5oiQ2HC21ia+o0FrMgtru5VvXFvcgpmoMTSM2H19yIGe/SxBbvb+hJnYLCyXAd3U+WCYqiOPPAupEWSnJm3I4ZORQK/U9dzgyibNydD0gSkORYYUpp74ywVubC4RXwZF08HNH960Qu4SlGC+tG/weewN58ATTQVfYJf+8UpfagaWuhWFOgOdzaE8YojSO74cHBlA5ZXvJJQpyQuIFGw4+DMFQ0BNrn1We5SMeuupYnw8NPgzbSRTgNMcjpwgSjbDuy+MKxvGIQR+UnbKEsT2+r62DjNSggyjWBKlFVQ3JXVQjs5JdR3INFnTPu/c//q17g22Zx08Xf7nv5Vs/8s6G5f6rxonjXsc6Kk87tyezgG1N/0AM7yuobDd87YhLnJp5q+n2yaWPpno3n/r7QsenRypcub0c3/vzr8uyVWfbu9R+i5+c+lp1HXvnu9XQG1G+b6D8l9ZwvOd7W8MvADuWZ6GOVP15F0Usj05sf3PzNhDj0/gffb9HG7z028Nk5cOTtndf23Xzo7i9O/Rq586fT5Ue2VbMToYe/3ZpqnJ6cff7G/vLbXpuK+HqOltZfazjpfe7VyPHmsYrpt24eKO+MXind2t9xz8/ypVt6Rz/v+OfNr4av38HnmZvb4FFi2oWyEo/nX+5BZNA=
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
eNqFVF1sFFUUbosRHtQUUERCcboBUejsznS2he6D2G6haumP7dZSTK13Z253pjt77zBzd2FZ+9AqmlhNHIOiMajIsluW2lKokIiYINji7wMPmDahogKmivyYEEXFeme725+01n3Zufd855zvnO+c2x4PQd1QMMrsUhCBOhAJPRhme1yHW4LQIM/HApDIWIpWV9V69gZ1ZXCFTIhmuBwOoCl2gIisY00R7SIOOEK8IwANA/igEfViKTyU6YnYAmBbE8F+iAybi+G5fGceY0uj6M1TEZuOVUi/bEED6jZqFTGlgoh1VS8DstJgiAyZrRDQP51REFMLELNBB0hUDBHnMe7idbbWRisslqBquYkqCEqQFdgCVgaKP8iqgNBirOAEYzWVF4FAMq8PkqZUdAshQUPUFc1qhGUtg2RK/mYdBxjAqFgEFsRuuShIC5ImQ5RhAFCfiE2jTYE6UZIlRmxpcPJAwloyrUF0Bflsra00gNVtRYeSRWwCbdWURmNvCxQJRTe2xmUIJCrbcEZ2VMYGMXunSdEDRBFqhIVIxBLNYn7g265oeYwEm61WJGiLEUxqbSb8EGosUJUQjI15mQeBpqnKGAlHi4FRV0oS1mIz3ZywlGOpoIiYR4vTPBzVYTo5iOHswho7f3AbaxCgIJVKT+WglGJa0n5sskEDop/GYVNTacbGnLsnY7Bh7qsAYlXtlJBAF2VzH9ADhc7Dk+/1ICJKAJpxd/X0dCnjRDrBzvP2Nb1TAhthJJr7moFqwN7xJo+7JPK5fIHlClmOPzolNCR6mBUxzWDu4brTDVQh8hHZ3Cs4uU4dGhpdNvhcjLqRoNEepWLBr07HU+vxflX5hNTzo6VUOPN4PZTyGF5gKnGIoamdDF/ocgouelNW4elyp9J4ZtSp10OXxmimWq1Pz0VclIPID6WEe8aJGLRNVKzT/KoSUAibehuojtbRjDo5jht8YFakTjdDQVbGqFBUVPQ/cWlnIDH7rPpYnmd5wZOqMn/zIDOT59gDk+ITs/hQRstnQU7wSaOZWdH/wUfYnEiRZhXJ/Jh+N3F8qZOv31pe1rJJqwv6/BvDdZXrt/iMvSEFmAnezjM+jH0q7HFvYN2APhlsbVJ9M17aUFlc8Zi7axNbg72YtsEDaLsQRjBWC3U6cGZCVHFQoiuswxh1ryluMPvWwnxOWJtfVOAtbBa8hUVsCd2M9ByM6xy19j/5KLfFxh6ezzKL7u+Yl5H8zZGqz5Wf5LJH6z89/sdrj69b6h2+FN14os11KremJNQHlTMFuwKNI6P2/S+1Vw2cu/XJlds7jzLvbYHzVx6oONx04cuL/+T2PP3tW8sjw0u3n3+ktSNzxzefL2hz+4KLH/2ppexMtiZfXlQwr3rzn+yGBmfHqoarz+7sH6lbEH9Iqz6bvSTr+sN/ywveyYqsyrri6Gu+5+c3bpwV6vYM8YlXc56o2ZFz4M6I+cLF3c5E6Av9yJuHu+2rvb89+Ff54ps9hz786Jr91G50x3HHDxdixxrXvb1w2XeXtt78foTPDT+5+vwz0sJtK2qu/3pvZ+zGbd6MwOvRoSXZ1xxZL/84d27ZEda1E2Xd6n130V2/L3ulJLvf//WJqp67T+5yF4de7G87fei+ub+MXL3syhmooj0aHZ2T0edPDOzPzMj4F2C/3M4=
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
eNqFVGtsFFUU3spDSNDwsuoP43SpbQid3ZlOKWyXCHVpa2laSrvKy7Lenbm7M3T23unM3UK7VEMp/IAYO6gYkSDIdpesLXSVhBhAQ7CJCDEGiKYlxQSEVBvwUWIgUfHOdrelAXH/7Nx7vnPOd853zm2PN0PdUDDK6lYQgToQCT0YZntch01haJCOWAgSGUvR2pX13kNhXel/QSZEM0qcTqApDoCIrGNNER0iDjmbeWcIGgYIQiPqx1LLQJY3Yg+BzT6CGyEy7CUMzxUWFTD2DIrerI/YdaxC+mUPG1C3U6uIKRVErKvVMiD5BkNkyGyCgP7pjIKYeoCYch0gUTFEXMB4Spfa2xqssFiCquUmqiAsQVZgF7IyUBrDrAoILcYKTjBW03kRCKXyBiHxpaNbCAkaoq5oViMsawUkE/IHdBxiAKNiEVgQh+WiIC1MfIYowxCgPhG7RpsCdaKkSozYM+DUgbRoqbQG0RUUtLe10QBWtxUdShaxcbRVUwaN/RuhSCi6oS0uQyBR2a7YZkZlbBAz+YAUR4EoQo2wEIlYolnMnmCrohUwEgxYrUjQFiOY0tpMNEKosUBVmmFs1MvsBZqmKqMknBsNjLrTkrAWmwfNCUs5lgqKiHm8NMPDWdtCJwcxnENY5OB7N7MGAQpSqfRUDkoppqXsJ+43aEBspHHY9FSasVHnI/djsGF2VQNxZf2EkEAXZbML6KHios/uv9fDiCghaMY9tQ+mSxvH0wkOnncsSk4IbLQg0ewKANWAybEmj7kkCrlCgeWKWY4/PiE0JHoLK2KawTzIHck0UIUoSGTzkFDEHdahodFlg9ti1I2EjfYoFQue/zqeXo+PV1aNSz0rupwKZ55aDaUChheYGtzM0NRFDF9cUiSU8AuZimpvtyedxvtQnZJeujRGgGpVlpmLuCiHUSOUEp6HTkS/fbxineZXlZBC2PTbQHW0jma0iOO4/rxHInW6GQqyMkYFl8v1P3FpZyAxj1n1sTzP8oI3XaWwrp95mOfoA5PmE7P4UEa5j0CO88mgmUei/4PPwnWJNGlWkcyT9NvH8aVevM6vlVVt3FwceKW+pnCVJq0Q6g41K8BM8A6eCWIcVOFRTznrAfTJYOtT6pvx5WtrSqsrPd1r2Drsx7QNXkDbhTCCsXqo04EzE6KKwxJdYR3GqHtd6Vrz2GJYyAmLBaEY+BcL/mIX+xLdjMwcjOkctfY/9ShvjY0+PH1ZG57fNc2W+k16bdWqqjPLZvyzoGLDls/fCg/W/loN24c6klsPv3x2oPvUzdbjg9f3Gbe/rPrk6m/zc+9+scW3e97QY3MvHTw/9azq+iD/h5+vX8xhv41/dKLvalPrvemz7/R2ZZflvF7JnHZfzOYmP/cMu61j4ClpWSnisi9VRa5t2N46J3LmtPbujB2ezk73OenZS8O/b8q7WHHuVnv7CUFcXhZY8KRj5+41Wpn97SvvwGT+TztPrnE5b8h9PRUfDne656Pvht4beVX0LZm5a29H/p97r1Rq2wuONbh88xqD7jfcPw5/6t8aWXL7oPnmnn3C2hk39w82DSwJbJPqdlyfFh/uG7nw/fD7W27kud1Tp2cP71k9O7g0e31isHxqePK1P2qy5/61qG1K9UheTu/lwH6OHJhz98gs+emzNyZ/Uy7mfnXr8V/u9HQmL3c+ceACKThd9mJPQ271yBSb7d69SbYVd/6Wr2bZbP8COXvwZg==
1 change: 1 addition & 0 deletions docs/docs/concepts/output_parsers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ LangChain has lots of different types of output parsers. This is a list of outpu

| Name | Supports Streaming | Has Format Instructions | Calls LLM | Input Type | Output Type | Description |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|-------------------------|-----------|--------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Str](https://python.langchain.com/api_reference/core/output_parsers/langchain_core.output_parsers.string.StrOutputParser.html) || | | `str` \| `Message` | String | Parses texts from message objects. Useful for handling variable formats of message content (e.g., extracting text from content blocks). |
| [JSON](https://python.langchain.com/api_reference/core/output_parsers/langchain_core.output_parsers.json.JSONOutputParser.html#langchain_core.output_parsers.json.JSONOutputParser) ||| | `str` \| `Message` | JSON object | Returns a JSON object as specified. You can specify a Pydantic model and it will return JSON for that model. Probably the most reliable output parser for getting structured data that does NOT use function calling. |
| [XML](https://python.langchain.com/api_reference/core/output_parsers/langchain_core.output_parsers.xml.XMLOutputParser.html#langchain_core.output_parsers.xml.XMLOutputParser) ||| | `str` \| `Message` | `dict` | Returns a dictionary of tags. Use when XML output is needed. Use with models that are good at writing XML (like Anthropic's). |
| [CSV](https://python.langchain.com/api_reference/core/output_parsers/langchain_core.output_parsers.list.CommaSeparatedListOutputParser.html#langchain_core.output_parsers.list.CommaSeparatedListOutputParser) ||| | `str` \| `Message` | `List[str]` | Returns a list of comma separated values. |
Expand Down
1 change: 1 addition & 0 deletions docs/docs/how_to/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ What LangChain calls [LLMs](/docs/concepts/text_llms) are older forms of languag

[Output Parsers](/docs/concepts/output_parsers) are responsible for taking the output of an LLM and parsing into more structured format.

- [How to: parse text from message objects](/docs/how_to/output_parser_string)
- [How to: use output parsers to parse an LLM response into structured format](/docs/how_to/output_parser_structured)
- [How to: parse JSON output](/docs/how_to/output_parser_json)
- [How to: parse XML output](/docs/how_to/output_parser_xml)
Expand Down
202 changes: 202 additions & 0 deletions docs/docs/how_to/output_parser_string.ipynb
Original file line number Diff line number Diff line change
@@ -0,0 +1,202 @@
{
"cells": [
{
"cell_type": "markdown",
"id": "1d6024e0-3847-4418-b8a8-6b8f83adf4c2",
"metadata": {},
"source": [
"# How to parse text from message objects\n",
"\n",
":::info Prerequisites\n",
"\n",
"This guide assumes familiarity with the following concepts:\n",
"- [Chat models](/docs/concepts/chat_models/)\n",
"- [Messages](/docs/concepts/messages/)\n",
"- [Output parsers](/docs/concepts/output_parsers/)\n",
"- [LangChain Expression Language (LCEL)](/docs/concepts/lcel/)\n",
"\n",
":::\n",
"\n",
"LangChain [message](/docs/concepts/messages/) objects support content in a [variety of formats](/docs/concepts/messages/#content), including text, [multimodal data](/docs/concepts/multimodality/), and a list of [content block](/docs/concepts/messages/#aimessage) dicts.\n",
"\n",
"The format of [Chat model](/docs/concepts/chat_models/) response content may depend on the provider. For example, the chat model for [Anthropic](/docs/integrations/chat/anthropic/) will return string content for typical string input:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "8ac74999-0740-4178-8efd-32a855592f71",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"'Hi there! How are you doing today? Is there anything I can help you with?'"
]
},
"execution_count": 1,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from langchain_anthropic import ChatAnthropic\n",
"\n",
"llm = ChatAnthropic(model=\"claude-3-5-haiku-latest\")\n",
"\n",
"response = llm.invoke(\"Hello\")\n",
"response.content"
]
},
{
"cell_type": "markdown",
"id": "69b7c3ae-0022-4737-9db7-f44db3402de2",
"metadata": {},
"source": [
"But when tool calls are generated, the response content is structured into content blocks that convey the model's reasoning process:"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "8c87553e-4f85-46c4-8f1e-666f6a261a50",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"[{'text': \"I'll help you get the current weather for San Francisco, California. Let me check that for you right away.\",\n",
" 'type': 'text'},\n",
" {'id': 'toolu_015PwwcKxWYctKfY3pruHFyy',\n",
" 'input': {'location': 'San Francisco, CA'},\n",
" 'name': 'get_weather',\n",
" 'type': 'tool_use'}]"
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from langchain_core.tools import tool\n",
"\n",
"\n",
"@tool\n",
"def get_weather(location: str) -> str:\n",
" \"\"\"Get the weather from a location.\"\"\"\n",
"\n",
" return \"Sunny.\"\n",
"\n",
"\n",
"llm_with_tools = llm.bind_tools([get_weather])\n",
"\n",
"response = llm_with_tools.invoke(\"What's the weather in San Francisco, CA?\")\n",
"response.content"
]
},
{
"cell_type": "markdown",
"id": "039f6d62-098f-42c9-8b07-43cb1f2a831b",
"metadata": {},
"source": [
"To automatically parse text from message objects irrespective of the format of the underlying content, we can use [StrOutputParser](https://python.langchain.com/api_reference/core/output_parsers/langchain_core.output_parsers.string.StrOutputParser.html). We can compose it with a chat model as follows:"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "0bb9b4dd-64a9-463d-9c71-df147630f3c3",
"metadata": {},
"outputs": [],
"source": [
"from langchain_core.output_parsers import StrOutputParser\n",
"\n",
"chain = llm_with_tools | StrOutputParser()"
]
},
{
"cell_type": "markdown",
"id": "4929c724-471f-4f77-a231-36e9af9418a3",
"metadata": {},
"source": [
"[StrOutputParser](https://python.langchain.com/api_reference/core/output_parsers/langchain_core.output_parsers.string.StrOutputParser.html) simplifies the extraction of text from message objects:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "9cbb8848-9101-465e-b230-0f7af6fb4105",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"I'll help you check the weather in San Francisco, CA right away.\n"
]
}
],
"source": [
"response = chain.invoke(\"What's the weather in San Francisco, CA?\")\n",
"print(response)"
]
},
{
"cell_type": "markdown",
"id": "13642ad5-325d-4d9b-b97e-cac40345bfbc",
"metadata": {},
"source": [
"This is particularly useful in streaming contexts:"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "28eeace3-3896-497f-93ad-544cbfb7f15c",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"|I'll| help| you get| the current| weather for| San Francisco, California|. Let| me retrieve| that| information for you.||||||||||"
]
}
],
"source": [
"for chunk in chain.stream(\"What's the weather in San Francisco, CA?\"):\n",
" print(chunk, end=\"|\")"
]
},
{
"cell_type": "markdown",
"id": "858e2071-a483-404e-9eca-c73a4466fd83",
"metadata": {},
"source": [
"See the [API Reference](https://python.langchain.com/api_reference/core/output_parsers/langchain_core.output_parsers.string.StrOutputParser.html) for more information."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.4"
}
},
"nbformat": 4,
"nbformat_minor": 5
}

0 comments on commit 940e93e

Please sign in to comment.