attachments 0.2.0__tar.gz → 0.2.1__tar.gz

{attachments-0.2.0/src/attachments.egg-info → attachments-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: attachments
-Version: 0.2.0
+Version: 0.2.1
 Summary: A Python library to handle various file types for LLMs.
 Author-email: Maxim Rivest <mrive052@gmail.com>
 License-Expression: MIT
@@ -38,7 +38,54 @@ Requires-Dist: filelock; extra == "dev"
 Dynamic: license-file
 
 # Attachments
-## Quickstart
+## Easiest way to give context to LLMs
+
+Attachments has the ambition to be the general funnel for any files to be transformed into images+text for large language models context. For this to be true we, has a community, have to stop implementing this funnel (file -> images+text) each on our own. If you have a detector + parser + renderer contibute it! This will help you and us. Don't let your code alone in a dark corner of you computer.
+
+## Very quickstart
+
+```python
+from attachments import Attachments
+
+a = Attachment("/the/path/or/url/to/your/to/the/content/you/want/to/give/the/llm.xlsx", "another.pdf", "another.pptx"...)
+
+prompt_ready_context = str(a)
+images_ready_for_llm = a.images
+```
+
+That is really just it!
+
+You can print it `print(a)`, you can interpolate it `f"the content is {a}"` you can string it `str(a)`. This will give you something very good to give the llm so that the AI can consider you content. 
+
+Nowadays, most genAI models comes with the ability to see images too. So you also have all attachments in images forms by using `a.images`.
+This is a list of base64 encoded images, this is the fundamental format the most llm provider accept. 
+
+The simplest way to use and think about attachments is that if you want to put you best foot forward and up you chances that the llm grok your content you should pass all of the text in `a` to the prompt and all of the images in `a.images` in the image input. We aim for making those two as 'prompt engineered' as possible. *Attachments* is young but already very powerful and used in production. The api will not change. Maybe advanced feature and syntax will be added but the core will stay the same. Mostly we will support more file types and we will have better rendering for better performance and with less extreneous tokens.
+
+## How to give attachments to openai llms?
+
+```python
+from openai import OpenAI
+from attachments import Attachments
+
+pdf_attachment = Attachments("https://github.com/microsoft/markitdown/raw/refs/heads/main/packages/markitdown/tests/test_files/test.pdf")
+
+prompt = f"""
+Analyze the following documents:
+{pdf_attachment}
+"""
+
+content = [{"type": "input_image","image_url": image} for image in pdf_attachment.images] + \
+          [{"type": "input_text", "text": prompt}]
+
+response = OpenAI().responses.create(model="gpt-4.1-nano", input=[{"role": "user", "content": content}])
+response.output_text
+```
+
+
+
+
+
 A Python library designed to seamlessly handle various file types (local or URLs), process them, and present them in formats suitable for Large Language Models (LLMs).
 
 It is meant to be very minimal.

{attachments-0.2.0 → attachments-0.2.1}/README.md

@@ -1,5 +1,52 @@
 # Attachments
-## Quickstart
+## Easiest way to give context to LLMs
+
+Attachments has the ambition to be the general funnel for any files to be transformed into images+text for large language models context. For this to be true we, has a community, have to stop implementing this funnel (file -> images+text) each on our own. If you have a detector + parser + renderer contibute it! This will help you and us. Don't let your code alone in a dark corner of you computer.
+
+## Very quickstart
+
+```python
+from attachments import Attachments
+
+a = Attachment("/the/path/or/url/to/your/to/the/content/you/want/to/give/the/llm.xlsx", "another.pdf", "another.pptx"...)
+
+prompt_ready_context = str(a)
+images_ready_for_llm = a.images
+```
+
+That is really just it!
+
+You can print it `print(a)`, you can interpolate it `f"the content is {a}"` you can string it `str(a)`. This will give you something very good to give the llm so that the AI can consider you content. 
+
+Nowadays, most genAI models comes with the ability to see images too. So you also have all attachments in images forms by using `a.images`.
+This is a list of base64 encoded images, this is the fundamental format the most llm provider accept. 
+
+The simplest way to use and think about attachments is that if you want to put you best foot forward and up you chances that the llm grok your content you should pass all of the text in `a` to the prompt and all of the images in `a.images` in the image input. We aim for making those two as 'prompt engineered' as possible. *Attachments* is young but already very powerful and used in production. The api will not change. Maybe advanced feature and syntax will be added but the core will stay the same. Mostly we will support more file types and we will have better rendering for better performance and with less extreneous tokens.
+
+## How to give attachments to openai llms?
+
+```python
+from openai import OpenAI
+from attachments import Attachments
+
+pdf_attachment = Attachments("https://github.com/microsoft/markitdown/raw/refs/heads/main/packages/markitdown/tests/test_files/test.pdf")
+
+prompt = f"""
+Analyze the following documents:
+{pdf_attachment}
+"""
+
+content = [{"type": "input_image","image_url": image} for image in pdf_attachment.images] + \
+          [{"type": "input_text", "text": prompt}]
+
+response = OpenAI().responses.create(model="gpt-4.1-nano", input=[{"role": "user", "content": content}])
+response.output_text
+```
+
+
+
+
+
 A Python library designed to seamlessly handle various file types (local or URLs), process them, and present them in formats suitable for Large Language Models (LLMs).
 
 It is meant to be very minimal.

{attachments-0.2.0 → attachments-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "attachments"
-version = "0.2.0"
+version = "0.2.1"
 authors = [
   { name="Maxim Rivest", email="mrive052@gmail.com" },
 ]

{attachments-0.2.0 → attachments-0.2.1}/src/attachments/renderers.py

@@ -3,6 +3,7 @@
 from abc import ABC, abstractmethod
 from typing import List, Dict, Any
 import xml.etree.ElementTree as ET
+import re
 
 class BaseRenderer(ABC):
     """Abstract base class for content renderers."""
@@ -51,12 +52,35 @@ class RendererRegistry:
 
 class DefaultXMLRenderer(BaseRenderer):
     """Renders parsed content into a default XML-like string format."""
+    def _sanitize_xml_attr(self, value):
+        """Ensure value is a string and escape/replace invalid XML attribute characters."""
+        if value is None:
+            return ""
+        value = str(value)
+        # Remove control characters except tab, newline, carriage return
+        value = re.sub(r'[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]', '', value)
+        # Replace invalid XML attribute chars (", <, >, &, ')
+        value = value.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
+        value = value.replace('"', '&quot;').replace("'", '&apos;')
+        return value
+
+    def _sanitize_xml_text(self, value):
+        """Ensure value is a string and escape/replace invalid XML text characters."""
+        if value is None:
+            return ""
+        value = str(value)
+        # Remove control characters except tab, newline, carriage return
+        value = re.sub(r'[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]', '', value)
+        # ElementTree will escape &, <, > automatically in text, but we can pre-escape for safety
+        value = value.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
+        return value
+
     def render(self, attachments_data: List[Dict[str, Any]]) -> str:
         root = ET.Element("attachments")
         for item_data in attachments_data:
-            item_id = item_data.get("id", "unknown")
-            item_type = item_data.get("type", "unknown")
-            original_path = item_data.get("original_path_str", item_data.get("file_path", "N/A"))
+            item_id = self._sanitize_xml_attr(item_data.get("id", "unknown"))
+            item_type = self._sanitize_xml_attr(item_data.get("type", "unknown"))
+            original_path = self._sanitize_xml_attr(item_data.get("original_path_str", item_data.get("file_path", "N/A")))
 
             attachment_element = ET.SubElement(root, "attachment")
             attachment_element.set("id", item_id)
@@ -64,31 +88,21 @@ class DefaultXMLRenderer(BaseRenderer):
             attachment_element.set("original_path", original_path)
 
             content_text = item_data.get("text", "")
-            
             content_element = ET.SubElement(attachment_element, "content")
-            # Using a direct assignment for CDATA. 
-            # ET doesn't have a specific CDATA type, but this is a common way to handle it.
-            # Actual CDATA wrapping might need to happen during serialization if the library doesn't do it.
-            if content_text: # Only add text if it's not empty
-                content_element.text = content_text # Store as regular text; XML serializer should handle escaping.
-                                                # For literal CDATA, one might need a custom serializer or to build the string manually.
+            if content_text:
+                content_element.text = self._sanitize_xml_text(content_text)
             else:
-                # If there's no text content, we can leave the content tag empty
-                # or add a comment, or omit it. For now, an empty tag is fine.
                 pass
 
-        # Serialize to string with pretty print
-        # ET.indent(root) # Available in Python 3.9+
         xml_str = ET.tostring(root, encoding="utf-8").decode("utf-8")
-        
-        # Basic pretty printing for older Python versions or if ET.indent is not sufficient
         try:
             import xml.dom.minidom
             dom = xml.dom.minidom.parseString(xml_str)
             return dom.toprettyxml(indent="  ")
-        except ImportError:
-            # Fallback if minidom is not available (though it's standard)
-            return xml_str
+        except Exception as e:
+            print("[attachments] XML rendering error. Invalid XML string was:\n", xml_str)
+            print("Exception:", e)
+            raise
 
 class PlainTextRenderer(BaseRenderer):
     """Renders parsed content into a simple plain text string, 

{attachments-0.2.0 → attachments-0.2.1/src/attachments.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: attachments
-Version: 0.2.0
+Version: 0.2.1
 Summary: A Python library to handle various file types for LLMs.
 Author-email: Maxim Rivest <mrive052@gmail.com>
 License-Expression: MIT
@@ -38,7 +38,54 @@ Requires-Dist: filelock; extra == "dev"
 Dynamic: license-file
 
 # Attachments
-## Quickstart
+## Easiest way to give context to LLMs
+
+Attachments has the ambition to be the general funnel for any files to be transformed into images+text for large language models context. For this to be true we, has a community, have to stop implementing this funnel (file -> images+text) each on our own. If you have a detector + parser + renderer contibute it! This will help you and us. Don't let your code alone in a dark corner of you computer.
+
+## Very quickstart
+
+```python
+from attachments import Attachments
+
+a = Attachment("/the/path/or/url/to/your/to/the/content/you/want/to/give/the/llm.xlsx", "another.pdf", "another.pptx"...)
+
+prompt_ready_context = str(a)
+images_ready_for_llm = a.images
+```
+
+That is really just it!
+
+You can print it `print(a)`, you can interpolate it `f"the content is {a}"` you can string it `str(a)`. This will give you something very good to give the llm so that the AI can consider you content. 
+
+Nowadays, most genAI models comes with the ability to see images too. So you also have all attachments in images forms by using `a.images`.
+This is a list of base64 encoded images, this is the fundamental format the most llm provider accept. 
+
+The simplest way to use and think about attachments is that if you want to put you best foot forward and up you chances that the llm grok your content you should pass all of the text in `a` to the prompt and all of the images in `a.images` in the image input. We aim for making those two as 'prompt engineered' as possible. *Attachments* is young but already very powerful and used in production. The api will not change. Maybe advanced feature and syntax will be added but the core will stay the same. Mostly we will support more file types and we will have better rendering for better performance and with less extreneous tokens.
+
+## How to give attachments to openai llms?
+
+```python
+from openai import OpenAI
+from attachments import Attachments
+
+pdf_attachment = Attachments("https://github.com/microsoft/markitdown/raw/refs/heads/main/packages/markitdown/tests/test_files/test.pdf")
+
+prompt = f"""
+Analyze the following documents:
+{pdf_attachment}
+"""
+
+content = [{"type": "input_image","image_url": image} for image in pdf_attachment.images] + \
+          [{"type": "input_text", "text": prompt}]
+
+response = OpenAI().responses.create(model="gpt-4.1-nano", input=[{"role": "user", "content": content}])
+response.output_text
+```
+
+
+
+
+
 A Python library designed to seamlessly handle various file types (local or URLs), process them, and present them in formats suitable for Large Language Models (LLMs).
 
 It is meant to be very minimal.