Skip to content

Commit 89588f8

Browse files
comharcomhar
authored
Merge pull request #7 from AnswerDotAI/anthropic-citations
add anthropic citations support
2 parents bee47c1 + a76c97a commit 89588f8

File tree

5 files changed

+218
-12
lines changed

5 files changed

+218
-12
lines changed

‎README.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,35 @@ Note: this feature is currently in beta so you’ll need to:
214214
(e.g. `anthropic.Anthropic(default_headers={'anthropic-beta': 'pdfs-2024-09-25'})`)
215215
- use the `claude-3-5-sonnet-20241022` model
216216

217+
#### Citations
218+
219+
*msglm* supports Anthropic
220+
[citations](https://docs.anthropic.com/en/docs/build-with-claude/citations).
221+
All you need to do is pass the content of your document to *mk_ant_doc*
222+
and then pass the output to *mk_msg* along with your question as shown
223+
in the example below.
224+
225+
``` python
226+
from msglm import mk_ant_doc, mk_msg_anthropic as mk_msg
227+
from anthropic import Anthropic
228+
229+
client = Anthropic()
230+
231+
doc = mk_ant_doc("The grass is green. The sky is blue.", title="My Document")
232+
233+
r = client.messages.create(
234+
model="claude-3-5-sonnet-20241022",
235+
max_tokens=1024,
236+
messages=[mk_msg([doc, "What color is the grass and sky?"])]
237+
)
238+
for o in r.content:
239+
if c:=getattr(o, 'citations', None): print(f"{o.text}. source: {c[0]['cited_text']} from {c[0]['document_title']}")
240+
else: print(o.text)
241+
```
242+
243+
*Note: The citations feature is currently available on Claude 3.5 Sonnet
244+
(new) and 3.5 Haiku.*
245+
217246
### Summary
218247

219248
We hope *msglm* will make your life a little easier when chatting to

‎msglm/_modidx.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
'msglm.core._mk_img': ('core.html#_mk_img', 'msglm/core.py'),
2929
'msglm.core._mk_pdf': ('core.html#_mk_pdf', 'msglm/core.py'),
3030
'msglm.core._remove_cache_ckpts': ('core.html#_remove_cache_ckpts', 'msglm/core.py'),
31+
'msglm.core.mk_ant_doc': ('core.html#mk_ant_doc', 'msglm/core.py'),
3132
'msglm.core.mk_msg': ('core.html#mk_msg', 'msglm/core.py'),
3233
'msglm.core.mk_msg_anthropic': ('core.html#mk_msg_anthropic', 'msglm/core.py'),
3334
'msglm.core.mk_msgs': ('core.html#mk_msgs', 'msglm/core.py'),

‎msglm/core.py

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
# %% auto 0
66
__all__ = ['mk_msg_openai', 'mk_msgs_openai', 'mk_msg', 'mk_msgs', 'Msg', 'AnthropicMsg', 'OpenAiMsg', 'mk_msg_anthropic',
7-
'mk_msgs_anthropic']
7+
'mk_msgs_anthropic', 'mk_ant_doc']
88

99
# %% ../nbs/00_core.ipynb
1010
import base64
@@ -164,3 +164,11 @@ def mk_msgs_anthropic(*args, cache=False, cache_last_ckpt_only=False, **kwargs):
164164
if cache_last_ckpt_only: msgs = [_remove_cache_ckpts(m) for m in msgs]
165165
msgs[-1] = _add_cache_control(msgs[-1], cache=cache)
166166
return msgs
167+
168+
# %% ../nbs/00_core.ipynb
169+
def mk_ant_doc(content, title=None, context=None, citation=True, **kws):
170+
"Create an Anthropic document."
171+
if _is_pdf(content): src = {"type":"base64", "media_type":"application/pdf", "data":_mk_pdf(content)}
172+
elif isinstance(content,list): src = {"type":"content", "content":content}
173+
else: src = {"type":"text", "media_type":"text/plain", "data":content}
174+
return {"type":"document", "source":src, "citations":{"enabled":citation}, "title":title, "context":context, **kws}

‎nbs/00_core.ipynb

Lines changed: 151 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@
7878
{
7979
"data": {
8080
"text/plain": [
81-
"ChatCompletion(id='chatcmpl-AWXWdjz55mygQ0I8rOdnPj58BmM3E', choices=[Choice(finish_reason='stop', index=0, logprobs=None, message=ChatCompletionMessage(content='Hello! How can I assist you today?', refusal=None, role='assistant', function_call=None, tool_calls=None))], created=1732318731, model='gpt-4o-mini-2024-07-18', object='chat.completion', service_tier=None, system_fingerprint='fp_0705bf87c0', usage=CompletionUsage(completion_tokens=9, prompt_tokens=11, total_tokens=20, completion_tokens_details=CompletionTokensDetails(reasoning_tokens=0, audio_tokens=0, accepted_prediction_tokens=0, rejected_prediction_tokens=0), prompt_tokens_details={'cached_tokens': 0, 'audio_tokens': 0}))"
81+
"ChatCompletion(id='chatcmpl-AwxutFvFrBvjSeejfih4WDfcIRNo1', choices=[Choice(finish_reason='stop', index=0, logprobs=None, message=ChatCompletionMessage(content='Hello! How can I assist you today?', refusal=None, role='assistant', function_call=None, tool_calls=None))], created=1738616707, model='gpt-4o-mini-2024-07-18', object='chat.completion', service_tier='default', system_fingerprint='fp_bd83329f63', usage=CompletionUsage(completion_tokens=10, prompt_tokens=11, total_tokens=21, completion_tokens_details=CompletionTokensDetails(reasoning_tokens=0, audio_tokens=0, accepted_prediction_tokens=0, rejected_prediction_tokens=0), prompt_tokens_details={'cached_tokens': 0, 'audio_tokens': 0}))"
8282
]
8383
},
8484
"execution_count": null,
@@ -119,7 +119,7 @@
119119
{
120120
"data": {
121121
"text/plain": [
122-
"Message(id='msg_01JAn3tJTJtuTL79eeDME2rr', content=[TextBlock(text=\"Hello! I'm Claude, an AI assistant created by Anthropic. It's nice to meet you. How can I help you today?\", type='text')], model='claude-3-haiku-20240307', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=Usage(input_tokens=11, output_tokens=32))"
122+
"Message(id='msg_01MJhQFAyz8RdH9C9jkm7tdi', content=[TextBlock(text=\"Hello! I'm an AI assistant created by Anthropic. How can I assist you today?\", type='text')], model='claude-3-haiku-20240307', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=Usage(input_tokens=11, output_tokens=23, cache_creation_input_tokens=0, cache_read_input_tokens=0))"
123123
]
124124
},
125125
"execution_count": null,
@@ -223,7 +223,7 @@
223223
{
224224
"data": {
225225
"text/plain": [
226-
"\"Hello! I am Claude, an AI assistant created by Anthropic. It's nice to meet you. How can I assist you today?\""
226+
"\"Hello! It's a pleasure to meet you. I'm an AI assistant created by Anthropic. I'm here to help with any questions or tasks you may have. Please let me know how I can be of assistance.\""
227227
]
228228
},
229229
"execution_count": null,
@@ -330,7 +330,7 @@
330330
{
331331
"data": {
332332
"text/plain": [
333-
"\"Hello! It's nice to meet you. I'm an AI assistant created by Anthropic. I'm here to help with a variety of tasks - feel free to ask me anything!\""
333+
"\"Hello! I'm an AI assistant created by Anthropic. I'm here to help with any questions or tasks you may have. How can I assist you today?\""
334334
]
335335
},
336336
"execution_count": null,
@@ -392,7 +392,7 @@
392392
{
393393
"data": {
394394
"text/plain": [
395-
"ChatCompletion(id='chatcmpl-AWXWjNJlLrQS8hECvDsOca0p00vqc', choices=[Choice(finish_reason='stop', index=0, logprobs=None, message=ChatCompletionMessage(content='The image contains a small puppy resting on grass. The puppy has a brown and white coat and is positioned near some purple flowers. It looks curious and attentive.', refusal=None, role='assistant', function_call=None, tool_calls=None))], created=1732318737, model='gpt-4o-mini-2024-07-18', object='chat.completion', service_tier=None, system_fingerprint='fp_3de1288069', usage=CompletionUsage(completion_tokens=32, prompt_tokens=8512, total_tokens=8544, completion_tokens_details=CompletionTokensDetails(reasoning_tokens=0, audio_tokens=0, accepted_prediction_tokens=0, rejected_prediction_tokens=0), prompt_tokens_details={'cached_tokens': 0, 'audio_tokens': 0}))"
395+
"ChatCompletion(id='chatcmpl-Awxv1j0M9xACPlg1X5VnUF5w25i8F', choices=[Choice(finish_reason='stop', index=0, logprobs=None, message=ChatCompletionMessage(content='The image features a cute puppy with brown and white fur lying on green grass. The puppy is resting near a patch of purple flowers, adding to the colorful and serene outdoor setting.', refusal=None, role='assistant', function_call=None, tool_calls=None))], created=1738616715, model='gpt-4o-mini-2024-07-18', object='chat.completion', service_tier='default', system_fingerprint='fp_bd83329f63', usage=CompletionUsage(completion_tokens=37, prompt_tokens=452, total_tokens=489, completion_tokens_details=CompletionTokensDetails(reasoning_tokens=0, audio_tokens=0, accepted_prediction_tokens=0, rejected_prediction_tokens=0), prompt_tokens_details={'cached_tokens': 0, 'audio_tokens': 0}))"
396396
]
397397
},
398398
"execution_count": null,
@@ -434,7 +434,7 @@
434434
{
435435
"data": {
436436
"text/plain": [
437-
"Message(id='msg_01A2qtvcrYZF6C22Jbujezuh', content=[TextBlock(text=\"This image shows a cute puppy lying in some grass and flowers. The puppy appears to be a Cavalier King Charles Spaniel, with its long, silky fur and floppy ears. The puppy has a friendly, sweet expression on its face as it looks directly at the camera. The background shows some purple flowers, creating a nice colorful contrast against the puppy's white and brown fur.\", type='text')], model='claude-3-haiku-20240307', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=Usage(input_tokens=104, output_tokens=89))"
437+
"Message(id='msg_01YZrV1h5fkdT27pXaiff99W', content=[TextBlock(text=\"This image shows a cute puppy lying in a grassy area with some purple flowers in the background. The puppy appears to be a Cavalier King Charles Spaniel, with its soft-looking fur and large, expressive eyes. The puppy looks relaxed and content, gazing out at the viewer. The vibrant purple flowers provide a lovely natural setting for the puppy's portrait.\", type='text')], model='claude-3-haiku-20240307', role='assistant', stop_reason='end_turn', stop_sequence=None, type='message', usage=Usage(input_tokens=104, output_tokens=86, cache_creation_input_tokens=0, cache_read_input_tokens=0))"
438438
]
439439
},
440440
"execution_count": null,
@@ -711,7 +711,7 @@
711711
{
712712
"data": {
713713
"text/plain": [
714-
"'The picture features an adorable puppy lying on the grass. It has a fluffy white coat with brown patches, particularly around its ears and eyes. The puppy has large, expressive eyes and a curious expression. In the background, there are purple flowers blooming, adding a vibrant touch to the scene. The overall setting looks peaceful and natural, conveying a sense of tranquility and playfulness.'"
714+
"'The image features a cute puppy laying in a grassy area, partially hidden by a cluster of purple flowers. The puppy has a mostly white coat with brown markings on its ears and around its eyes. Its large, expressive eyes give it an adorable appearance, and the overall setting looks peaceful and vibrant with the flowers surrounding the pup.'"
715715
]
716716
},
717717
"execution_count": null,
@@ -733,7 +733,7 @@
733733
{
734734
"data": {
735735
"text/plain": [
736-
"'The image shows a young puppy lying in a grassy area surrounded by purple daisy-like flowers. The puppy has a white and brown coat, with floppy ears and a friendly, alert expression on its face. The puppy appears to be relaxed and content, enjoying the warm, sunny environment. The vibrant colors of the flowers and the lush green grass create a charming, natural setting that complements the endearing presence of the puppy.'"
736+
"'The image shows a young, fluffy puppy lying on a grassy lawn. The puppy has a white and brown coat, with large, expressive eyes and floppy ears. The puppy appears to be looking directly at the camera with a curious and friendly expression. In the background, there are several vibrant purple flowers, adding a lovely, natural setting to the scene. Overall, the image captures the adorable and endearing nature of this puppy, inviting the viewer to appreciate the charming beauty of this young canine companion.'"
737737
]
738738
},
739739
"execution_count": null,
@@ -1039,7 +1039,7 @@
10391039
{
10401040
"data": {
10411041
"text/plain": [
1042-
"'Let me calculate the average monthly revenue for Product D by adding all monthly values and dividing by 12.\\n\\nMonthly revenues for Product D:\\nJan: ~900\\nFeb: ~500\\nMar: ~400\\nApr: ~700\\nMay: ~800\\nJun: ~900\\nJul: ~1000\\nAug: ~1050\\nSep: ~1200\\nOct: ~1300\\nNov: ~1300\\nDec: ~1300\\n\\nTotal = 11,350 (approximate)\\nAverage = 11,350 ÷ 12 = 946\\n\\nThe average monthly revenue for Product D was approximately $946 during fiscal year 2023.'"
1042+
"'Let me calculate the average monthly revenue for Product D by summing up all monthly values and dividing by 12.\\n\\nMonthly revenues for Product D:\\nJan: ~900\\nFeb: ~500\\nMar: ~400\\nApr: ~700\\nMay: ~800\\nJun: ~900\\nJul: ~1000\\nAug: ~1050\\nSep: ~1200\\nOct: ~1300\\nNov: ~1300\\nDec: ~1300\\n\\nTotal = 11,350 (approximately)\\nAverage = 11,350 ÷ 12 = 945.83\\n\\nThe average monthly revenue for Product D in fiscal year 2023 was approximately $946.'"
10431043
]
10441044
},
10451045
"execution_count": null,
@@ -1551,7 +1551,7 @@
15511551
{
15521552
"data": {
15531553
"text/plain": [
1554-
"'Why did the scarecrow win an award?\\n\\nBecause he was outstanding in his field!'"
1554+
"\"Why don't skeletons fight each other?\\n\\nThey don't have the guts!\""
15551555
]
15561556
},
15571557
"execution_count": null,
@@ -1573,7 +1573,7 @@
15731573
{
15741574
"data": {
15751575
"text/plain": [
1576-
"\"Why don't skeletons fight each other? \\n\\nThey don't have the guts!\""
1576+
"'Why did the scarecrow win an award?\\n\\nBecause he was outstanding in his field!'"
15771577
]
15781578
},
15791579
"execution_count": null,
@@ -1781,6 +1781,146 @@
17811781
"mk_msg_anthropic(\"Please cache my message\", cache=True)"
17821782
]
17831783
},
1784+
{
1785+
"cell_type": "markdown",
1786+
"metadata": {},
1787+
"source": [
1788+
"### Citations"
1789+
]
1790+
},
1791+
{
1792+
"cell_type": "markdown",
1793+
"metadata": {},
1794+
"source": [
1795+
"The Anthropic API provides detailed [citations](https://docs.anthropic.com/en/docs/build-with-claude/citations) when answering questions about documents.\n",
1796+
"\n",
1797+
"When citations are enabled a citations block like the one below will be included in the response.\n",
1798+
"\n",
1799+
"```js\n",
1800+
"{\n",
1801+
" \"content\": [\n",
1802+
" {\n",
1803+
" \"type\": \"text\",\n",
1804+
" \"text\": \"According to the document, \"\n",
1805+
" },\n",
1806+
" {\n",
1807+
" \"type\": \"text\",\n",
1808+
" \"text\": \"the grass is green\",\n",
1809+
" \"citations\": [{\n",
1810+
" \"type\": \"char_location\",\n",
1811+
" \"cited_text\": \"The grass is green.\",\n",
1812+
" \"document_index\": 0,\n",
1813+
" \"document_title\": \"Example Document\",\n",
1814+
" \"start_char_index\": 0,\n",
1815+
" \"end_char_index\": 20\n",
1816+
" }]\n",
1817+
" }\n",
1818+
" ]\n",
1819+
"}\n",
1820+
"```"
1821+
]
1822+
},
1823+
{
1824+
"cell_type": "markdown",
1825+
"metadata": {},
1826+
"source": [
1827+
"To enable citations you need to create an Anthropic document with the following structure.\n",
1828+
"\n",
1829+
"```js\n",
1830+
"{\n",
1831+
" \"type\": \"document\",\n",
1832+
" \"source\": {...},\n",
1833+
" \"title\": \"Document Title\", # optional\n",
1834+
" \"context\": \"Context about the document that will not be cited from\", # optional\n",
1835+
" \"citations\": {\"enabled\": True}\n",
1836+
"}\n",
1837+
"```"
1838+
]
1839+
},
1840+
{
1841+
"cell_type": "markdown",
1842+
"metadata": {},
1843+
"source": [
1844+
"Currently Anthropic supports citations on 3 document types:\n",
1845+
"- text\n",
1846+
"- pdfs\n",
1847+
"- custom\n",
1848+
"\n",
1849+
"A **text** document has the following source structure.\n",
1850+
"\n",
1851+
"```js\n",
1852+
"{\"type\": \"text\", \"media_type\": \"text/plain\", \"data\": \"Plain text content...\"}\n",
1853+
"```\n",
1854+
"\n",
1855+
"Here's the source structure for a **pdf**.\n",
1856+
"\n",
1857+
"```js\n",
1858+
"{\"type\": \"base64\", \"media_type\": \"application/pdf\", \"data\": b64_enc_data}\n",
1859+
"```\n",
1860+
"\n",
1861+
"Finally, here's the source structure for a **custom** document.\n",
1862+
"\n",
1863+
"```js\n",
1864+
"{\n",
1865+
" \"type\": \"content\",\n",
1866+
" \"content\": [\n",
1867+
" {\"type\": \"text\", \"text\": \"First chunk\"},\n",
1868+
" {\"type\": \"text\", \"text\": \"Second chunk\"}\n",
1869+
" ]\n",
1870+
"}\n",
1871+
"```"
1872+
]
1873+
},
1874+
{
1875+
"cell_type": "code",
1876+
"execution_count": null,
1877+
"metadata": {},
1878+
"outputs": [],
1879+
"source": [
1880+
"#| export\n",
1881+
"def mk_ant_doc(content, title=None, context=None, citation=True, **kws):\n",
1882+
" \"Create an Anthropic document.\"\n",
1883+
" if _is_pdf(content): src = {\"type\":\"base64\", \"media_type\":\"application/pdf\", \"data\":_mk_pdf(content)}\n",
1884+
" elif isinstance(content,list): src = {\"type\":\"content\", \"content\":content}\n",
1885+
" else: src = {\"type\":\"text\", \"media_type\":\"text/plain\", \"data\":content}\n",
1886+
" return {\"type\":\"document\", \"source\":src, \"citations\":{\"enabled\":citation}, \"title\":title, \"context\":context, **kws}"
1887+
]
1888+
},
1889+
{
1890+
"cell_type": "markdown",
1891+
"metadata": {},
1892+
"source": [
1893+
"Here's how you would implement the example from the citation's [docs](https://docs.anthropic.com/en/docs/build-with-claude/citations)."
1894+
]
1895+
},
1896+
{
1897+
"cell_type": "code",
1898+
"execution_count": null,
1899+
"metadata": {},
1900+
"outputs": [
1901+
{
1902+
"data": {
1903+
"text/markdown": [
1904+
"```json\n",
1905+
"{ 'content': [{'type': 'document', 'source': {'type': 'text', 'media_type': 'text/plain', 'data': 'The grass is green. The sky is blue.'}, 'citations': {'enabled': True}, 'title': 'My Document', 'context': 'This is a trustworthy document.'}, {'type': 'text', 'text': 'What color is the grass and sky?'}],\n",
1906+
" 'role': 'user'}\n",
1907+
"```"
1908+
],
1909+
"text/plain": [
1910+
"{'role': 'user',\n",
1911+
" 'content': (#2) [{'type': 'document', 'source': {'type': 'text', 'media_type': 'text/plain', 'data': 'The grass is green. The sky is blue.'}, 'citations': {'enabled': True}, 'title': 'My Document', 'context': 'This is a trustworthy document.'},{'type': 'text', 'text': 'What color is the grass and sky?'}]}"
1912+
]
1913+
},
1914+
"execution_count": null,
1915+
"metadata": {},
1916+
"output_type": "execute_result"
1917+
}
1918+
],
1919+
"source": [
1920+
"doc = mk_ant_doc(\"The grass is green. The sky is blue.\", title=\"My Document\", context=\"This is a trustworthy document.\")\n",
1921+
"mk_msg([doc, \"What color is the grass and sky?\"])"
1922+
]
1923+
},
17841924
{
17851925
"cell_type": "code",
17861926
"execution_count": null,

‎nbs/index.ipynb

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -300,6 +300,34 @@
300300
" - use the `claude-3-5-sonnet-20241022` model \n"
301301
]
302302
},
303+
{
304+
"cell_type": "markdown",
305+
"metadata": {},
306+
"source": [
307+
"#### Citations\n",
308+
"*msglm* supports Anthropic [citations](https://docs.anthropic.com/en/docs/build-with-claude/citations). All you need to do is pass the content of your document to *mk_ant_doc* and then pass the output to *mk_msg* along with your question as shown in the example below.\n",
309+
" \n",
310+
"```python\n",
311+
"from msglm import mk_ant_doc, mk_msg_anthropic as mk_msg\n",
312+
"from anthropic import Anthropic\n",
313+
"\n",
314+
"client = Anthropic()\n",
315+
"\n",
316+
"doc = mk_ant_doc(\"The grass is green. The sky is blue.\", title=\"My Document\")\n",
317+
"\n",
318+
"r = client.messages.create(\n",
319+
" model=\"claude-3-5-sonnet-20241022\",\n",
320+
" max_tokens=1024,\n",
321+
" messages=[mk_msg([doc, \"What color is the grass and sky?\"])]\n",
322+
")\n",
323+
"for o in r.content:\n",
324+
" if c:=getattr(o, 'citations', None): print(f\"{o.text}. source: {c[0]['cited_text']} from {c[0]['document_title']}\")\n",
325+
" else: print(o.text)\n",
326+
"```\n",
327+
"\n",
328+
"*Note: The citations feature is currently available on Claude 3.5 Sonnet (new) and 3.5 Haiku.*"
329+
]
330+
},
303331
{
304332
"cell_type": "markdown",
305333
"metadata": {},

0 commit comments

Comments
 (0)