notionary 0.1.19__py3-none-any.whl → 0.1.21__py3-none-any.whl

notionary/elements/divider_element.py

@@ -1,10 +1,8 @@
-# File: elements/dividers.py
-
-from typing import Dict, Any, Optional
-from typing_extensions import override
 import re
+from typing import Dict, Any, Optional
 
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 
 
 class DividerElement(NotionBlockElement):
@@ -17,19 +15,16 @@ class DividerElement(NotionBlockElement):
 
     PATTERN = re.compile(r"^\s*-{3,}\s*$")
 
-    @override
     @staticmethod
     def match_markdown(text: str) -> bool:
         """Check if text is a markdown divider."""
         return bool(DividerElement.PATTERN.match(text))
 
-    @override
     @staticmethod
     def match_notion(block: Dict[str, Any]) -> bool:
         """Check if block is a Notion divider."""
         return block.get("type") == "divider"
 
-    @override
     @staticmethod
     def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown divider to Notion divider block."""
@@ -38,7 +33,6 @@ class DividerElement(NotionBlockElement):
 
         return {"type": "divider", "divider": {}}
 
-    @override
     @staticmethod
     def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion divider block to markdown divider."""
@@ -47,27 +41,16 @@ class DividerElement(NotionBlockElement):
 
         return "---"
 
-    @override
     @staticmethod
     def is_multiline() -> bool:
         return False
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
-        """
-        Returns a dictionary with all information needed for LLM prompts about this element.
-        Includes description, usage guidance, syntax options, and examples.
-        """
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """Returns compact LLM prompt metadata for the divider element."""
         return {
-            "description": "Creates a horizontal divider line that visually separates sections of content.",
-            "when_to_use": "Use dividers when you want to create clear visual breaks between different sections or topics in your document. Dividers help improve readability by organizing content into distinct sections without requiring headings.",
-            "syntax": ["---"],
-            "notes": [
-                "Dividers must be on their own line with no other content",
-                "Dividers work well when combined with headings to clearly separate major document sections",
-            ],
-            "examples": [
-                "## Introduction\nThis is the introduction section of the document.\n\n---\n\n## Main Content\nThis is the main content section.",
-                "Task List:\n- Complete project proposal\n- Review feedback\n\n---\n\nMeeting Notes:\n- Discussed timeline\n- Assigned responsibilities",
-            ],
+            "description": "Creates a horizontal divider line to visually separate sections of content.",
+            "when_to_use": "Use to create clear visual breaks between different sections without requiring headings.",
+            "syntax": "---",
+            "examples": ["## Section 1\nContent\n\n---\n\n## Section 2\nMore content"],
         }

notionary/elements/embed_element.py

@@ -1,6 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 
 
 class EmbedElement(NotionBlockElement):
@@ -97,26 +98,17 @@ class EmbedElement(NotionBlockElement):
         return result
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
-        """Returns information for LLM prompts about this element."""
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        Returns structured LLM prompt metadata for the embed element.
+        """
         return {
             "description": "Embeds external content from websites, PDFs, Google Maps, and other sources directly in your document.",
-            "when_to_use": "Use embeds when you want to include external content that isn't just a video or image. Embeds are great for interactive content, reference materials, or live data sources.",
-            "syntax": [
-                "<embed>(https://example.com) - Embed without caption",
-                "<embed:Caption text>(https://example.com) - Embed with caption",
-            ],
-            "supported_sources": [
-                "Websites and web pages",
-                "PDFs and documents",
-                "Google Maps",
-                "Google Drive files",
-                "Twitter/X posts",
-                "GitHub repositories and code",
-                "Figma designs",
-                "Miro boards",
-                "Many other services supported by Notion's embed feature",
-            ],
+            "when_to_use": (
+                "Use embeds when you want to include external content that isn't just a video or image. "
+                "Embeds are great for interactive content, reference materials, or live data sources."
+            ),
+            "syntax": "<embed:Caption>(https://example.com)",
             "examples": [
                 "<embed:Course materials>(https://drive.google.com/file/d/123456/view)",
                 "<embed:Our office location>(https://www.google.com/maps?q=San+Francisco)",

notionary/elements/heading_element.py

@@ -1,8 +1,8 @@
-from typing import Dict, Any, Optional
-from typing_extensions import override
 import re
+from typing import Dict, Any, Optional
 
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 from notionary.elements.text_inline_formatter import TextInlineFormatter
 
 
@@ -11,20 +11,17 @@ class HeadingElement(NotionBlockElement):
 
     PATTERN = re.compile(r"^(#{1,6})\s(.+)$")
 
-    @override
     @staticmethod
     def match_markdown(text: str) -> bool:
         """Check if text is a markdown heading."""
         return bool(HeadingElement.PATTERN.match(text))
 
-    @override
     @staticmethod
     def match_notion(block: Dict[str, Any]) -> bool:
         """Check if block is a Notion heading."""
         block_type: str = block.get("type", "")
         return block_type.startswith("heading_") and block_type[-1] in "123456"
 
-    @override
     @staticmethod
     def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown heading to Notion heading block."""
@@ -35,8 +32,6 @@ class HeadingElement(NotionBlockElement):
         level = len(header_match.group(1))
         content = header_match.group(2)
 
-        # Import here to avoid circular imports
-
         return {
             "type": f"heading_{level}",
             f"heading_{level}": {
@@ -44,7 +39,6 @@ class HeadingElement(NotionBlockElement):
             },
         }
 
-    @override
     @staticmethod
     def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion heading block to markdown heading."""
@@ -67,18 +61,22 @@ class HeadingElement(NotionBlockElement):
         prefix = "#" * level
         return f"{prefix} {text or ''}"
 
-    @override
     @staticmethod
     def is_multiline() -> bool:
         return False
 
-    @override
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
         """
-        Returns a dictionary with all information needed for LLM prompts about this element.
+        Returns structured LLM prompt metadata for the heading element.
         """
         return {
             "description": "Use Markdown headings (#, ##, ###, etc.) to structure content hierarchically.",
             "when_to_use": "Use to group content into sections and define a visual hierarchy.",
+            "syntax": "## Your Heading Text",
+            "examples": [
+                "# Main Title",
+                "## Section Title",
+                "### Subsection Title",
+            ],
         }

notionary/elements/image_element.py

@@ -1,7 +1,7 @@
 import re
 from typing import Dict, Any, Optional, List
-from typing_extensions import override
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 
 
 class ImageElement(NotionBlockElement):
@@ -22,7 +22,6 @@ class ImageElement(NotionBlockElement):
         + r"\)$"  # closing parenthesis
     )
 
-    @override
     @staticmethod
     def match_markdown(text: str) -> bool:
         """Check if text is a markdown image."""
@@ -30,13 +29,11 @@ class ImageElement(NotionBlockElement):
             ImageElement.PATTERN.match(text.strip())
         )
 
-    @override
     @staticmethod
     def match_notion(block: Dict[str, Any]) -> bool:
         """Check if block is a Notion image."""
         return block.get("type") == "image"
 
-    @override
     @staticmethod
     def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown image to Notion image block."""
@@ -64,7 +61,6 @@ class ImageElement(NotionBlockElement):
 
         return image_block
 
-    @override
     @staticmethod
     def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
         """Convert Notion image block to markdown image."""
@@ -103,25 +99,23 @@ class ImageElement(NotionBlockElement):
                 result += text_obj.get("plain_text", "")
         return result
 
-    @override
     @staticmethod
     def is_multiline() -> bool:
         return False
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
         """
-        Returns a dictionary with all information needed for LLM prompts about this element.
-        Includes description, usage guidance, syntax options, and examples.
+        Returns structured LLM prompt metadata for the image element.
         """
         return {
             "description": "Embeds an image from an external URL into your document.",
-            "when_to_use": "Use images to include visual content such as diagrams, screenshots, charts, photos, or illustrations that enhance your document. Images can make complex information easier to understand, create visual interest, or provide evidence for your points.",
-            "syntax": [
-                "![](https://example.com/image.jpg) - Image without caption",
-                "![Caption text](https://example.com/image.jpg) - Image with caption",
-                '![Caption text](https://example.com/image.jpg "Alt text") - Image with caption and alt text',
-            ],
+            "when_to_use": (
+                "Use images to include visual content such as diagrams, screenshots, charts, photos, or illustrations "
+                "that enhance your document. Images can make complex information easier to understand, create visual interest, "
+                "or provide evidence for your points."
+            ),
+            "syntax": "![Caption](https://example.com/image.jpg)",
             "examples": [
                 "![Data visualization showing monthly trends](https://example.com/chart.png)",
                 "![](https://example.com/screenshot.jpg)",

notionary/elements/mention_element.py

@@ -3,6 +3,7 @@ from typing import Dict, Any, Optional, List
 from typing_extensions import override
 
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 
 
 class MentionElement(NotionBlockElement):
@@ -45,7 +46,6 @@ class MentionElement(NotionBlockElement):
         },
     }
 
-    @override
     @staticmethod
     def match_markdown(text: str) -> bool:
         """Check if text contains a markdown mention."""
@@ -54,7 +54,6 @@ class MentionElement(NotionBlockElement):
                 return True
         return False
 
-    @override
     @staticmethod
     def match_notion(block: Dict[str, Any]) -> bool:
         """Check if block contains a mention."""
@@ -75,7 +74,6 @@ class MentionElement(NotionBlockElement):
 
         return any(text_item.get("type") == "mention" for text_item in rich_text)
 
-    @override
     @staticmethod
     def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
         """Convert markdown text with mentions to a Notion paragraph block."""
@@ -161,7 +159,6 @@ class MentionElement(NotionBlockElement):
             "color": "default",
         }
 
-    @override
     @staticmethod
     def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
         """Extract mentions from Notion block and convert to markdown format."""
@@ -200,28 +197,22 @@ class MentionElement(NotionBlockElement):
 
         return "".join(result)
 
-    @override
     @staticmethod
     def is_multiline() -> bool:
         return False
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
-        """Information about this element for LLM-based processing."""
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        Returns structured LLM prompt metadata for the mention element.
+        """
         return {
             "description": "References to Notion pages, databases, or dates within text content.",
             "when_to_use": "When you want to link to other Notion content within your text.",
-            "syntax": [
-                "@[page-id] - Reference to a Notion page",
-                "@date[YYYY-MM-DD] - Reference to a date",
-                "@db[database-id] - Reference to a Notion database",
-            ],
+            "syntax": "@[page-id]",
             "examples": [
                 "Check the meeting notes at @[1a6389d5-7bd3-80c5-9a87-e90b034989d0]",
                 "Deadline is @date[2023-12-31]",
                 "Use the structure in @db[1a6389d5-7bd3-80e9-b199-000cfb3fa0b3]",
             ],
-            "limitations": [
-                "Mentions require knowing the internal IDs of the pages or databases you want to reference"
-            ],
         }

notionary/elements/notion_block_element.py

@@ -2,6 +2,8 @@ import inspect
 from typing import Dict, Any, Optional
 from abc import ABC
 
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
+
 
 class NotionBlockElement(ABC):
     """Base class for elements that can be converted between Markdown and Notion."""
@@ -37,15 +39,14 @@ class NotionBlockElement(ABC):
         By default, returns the class docstring.
         """
 
+    @classmethod
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        Returns a dictionary with information for LLM prompts about this element.
+        This default implementation extracts information from the class docstring.
+        Subclasses should override this method to provide more structured information.
 
-@classmethod
-def get_llm_prompt_content(cls) -> dict:
-    """
-    Returns a dictionary with information for LLM prompts about this element.
-    This default implementation extracts information from the class docstring.
-    Subclasses should override this method to provide more structured information.
-
-    Returns:
-        Dictionary with documentation information
-    """
-    return {"description": inspect.cleandoc(cls.__doc__ or ""), "examples": []}
+        Returns:
+            Dictionary with documentation information
+        """
+        return {"description": inspect.cleandoc(cls.__doc__ or ""), "examples": []}

notionary/elements/numbered_list_element.py

@@ -0,0 +1,68 @@
+import re
+from typing import Dict, Any, Optional
+from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
+from notionary.elements.text_inline_formatter import TextInlineFormatter
+
+
+class NumberedListElement(NotionBlockElement):
+    """Class for converting between Markdown numbered lists and Notion numbered list items."""
+
+    @staticmethod
+    def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
+        """Convert markdown numbered list item to Notion block."""
+        pattern = re.compile(r"^\s*(\d+)\.\s+(.+)$")
+        numbered_match = pattern.match(text)
+        if not numbered_match:
+            return None
+
+        content = numbered_match.group(2)
+
+        # Use parse_inline_formatting to handle rich text
+        rich_text = TextInlineFormatter.parse_inline_formatting(content)
+
+        return {
+            "type": "numbered_list_item",
+            "numbered_list_item": {"rich_text": rich_text, "color": "default"},
+        }
+
+    @staticmethod
+    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+        """Convert Notion numbered list item block to markdown."""
+        if block.get("type") != "numbered_list_item":
+            return None
+
+        rich_text = block.get("numbered_list_item", {}).get("rich_text", [])
+        content = TextInlineFormatter.extract_text_with_formatting(rich_text)
+
+        return f"1. {content}"
+
+    @staticmethod
+    def match_markdown(text: str) -> bool:
+        """Check if this element can handle the given markdown text."""
+        pattern = re.compile(r"^\s*\d+\.\s+(.+)$")
+        return bool(pattern.match(text))
+
+    @staticmethod
+    def match_notion(block: Dict[str, Any]) -> bool:
+        """Check if this element can handle the given Notion block."""
+        return block.get("type") == "numbered_list_item"
+
+    @staticmethod
+    def is_multiline() -> bool:
+        return False
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        Returns structured LLM prompt metadata for the numbered list element.
+        """
+        return {
+            "description": "Creates numbered list items for ordered sequences.",
+            "when_to_use": "Use for lists where order matters, such as steps, rankings, or sequential items.",
+            "syntax": "1. Item text",
+            "examples": [
+                "1. First step\n2. Second step\n3. Third step",
+                "1. Gather materials\n2. Assemble parts\n3. Test the result",
+            ],
+        }

notionary/elements/paragraph_element.py

@@ -2,6 +2,7 @@ from typing import Dict, Any, Optional
 from typing_extensions import override
 
 from notionary.elements.notion_block_element import NotionBlockElement
+from notionary.elements.prompts.element_prompt_content import ElementPromptContent
 from notionary.elements.text_inline_formatter import TextInlineFormatter
 
 
@@ -57,17 +58,20 @@ class ParagraphElement(NotionBlockElement):
         return False
 
     @classmethod
-    def get_llm_prompt_content(cls) -> dict:
-        """Returns information for LLM prompts about this element."""
+    def get_llm_prompt_content(cls) -> ElementPromptContent:
+        """
+        Returns structured LLM prompt metadata for the paragraph element.
+        """
         return {
             "description": "Creates standard paragraph blocks for regular text content.",
-            "when_to_use": "Use paragraphs for normal text content. Paragraphs are the default block type and will be used when no other specific formatting is applied.",
-            "syntax": ["Just write text normally without any special prefix"],
-            "notes": [
-                "Paragraphs support inline formatting like **bold**, *italic*, ~~strikethrough~~, `code`, and [links](url)"
-            ],
+            "when_to_use": (
+                "Use paragraphs for normal text content. Paragraphs are the default block type and will be used "
+                "when no other specific formatting is applied."
+            ),
+            "syntax": "Just write text normally without any special prefix",
             "examples": [
                 "This is a simple paragraph with plain text.",
                 "This paragraph has **bold** and *italic* formatting.",
+                "You can also include [links](https://example.com) or `inline code`.",
             ],
         }

notionary/elements/prompts/element_prompt_content.py

@@ -0,0 +1,20 @@
+from typing import TypedDict, List
+
+
+class ElementPromptContent(TypedDict):
+    """
+    Typed dictionary defining the standardized structure for element prompt content.
+    This ensures consistent formatting across all Notion block elements.
+    """
+
+    description: str
+    """Concise explanation of what the element is and its purpose in Notion."""
+
+    syntax: str
+    """The exact markdown syntax pattern used to create this element."""
+
+    examples: List[str]
+    """List of practical usage examples showing the element in context."""
+
+    when_to_use: str
+    """Guidelines explaining the appropriate scenarios for using this element."""

notionary/elements/prompts/synthax_prompt_builder.py

@@ -0,0 +1,92 @@
+from typing import Type, List
+from notionary.elements.notion_block_element import NotionBlockElement
+
+
+class MarkdownSyntaxPromptBuilder:
+    """
+    Generator for LLM system prompts that describe Notion-Markdown syntax.
+
+    This class extracts information about supported Markdown patterns
+    and formats them optimally for LLMs.
+    """
+
+    SYSTEM_PROMPT_TEMPLATE = """You are a knowledgeable assistant that helps users create content for Notion pages.
+Notion supports standard Markdown with some special extensions for creating rich content.
+
+{element_docs}
+
+Important usage guidelines:
+
+1. Do NOT start content with a level 1 heading (# Heading). In Notion, the page title is already displayed in the metadata, so starting with an H1 heading is redundant. Begin with H2 (## Heading) or lower for section headings.
+
+2. The backtick code fence syntax (```) should ONLY be used when creating actual code blocks or diagrams.
+Do not wrap examples or regular content in backticks unless you're showing code.
+
+3. Use inline formatting (bold, italic, etc.) across all content to enhance readability.
+Proper typography is essential for creating scannable, well-structured documents.
+
+4. Notion's extensions to Markdown provide richer formatting options than standard Markdown
+while maintaining the familiar Markdown syntax for basic elements.
+
+5. Always structure content with clear headings, lists, and paragraphs to create visually appealing
+and well-organized documents.
+"""
+
+    @staticmethod
+    def generate_element_doc(element_class: Type[NotionBlockElement]) -> str:
+        """
+        Generates documentation for a specific NotionBlockElement in a compact format.
+        Uses the element's get_llm_prompt_content method if available.
+        """
+        class_name = element_class.__name__
+        element_name = class_name.replace("Element", "")
+
+        # Check if the class has the get_llm_prompt_content method
+        if not hasattr(element_class, "get_llm_prompt_content") or not callable(
+            getattr(element_class, "get_llm_prompt_content")
+        ):
+            return f"## {element_name}"
+
+        # Get the element content
+        content = element_class.get_llm_prompt_content()
+
+        # Format the element documentation in a compact way
+        doc_parts = [
+            f"## {element_name}",
+            f"{content['description']}",
+            f"**Syntax:** {content['syntax']}",
+            f"**Example:** {content['examples'][0]}" if content["examples"] else "",
+            f"**When to use:** {content['when_to_use']}",
+        ]
+
+        # Filter out any empty parts and join with newlines
+        return "\n".join([part for part in doc_parts if part])
+
+    @classmethod
+    def generate_element_docs(
+        cls, element_classes: List[Type[NotionBlockElement]]
+    ) -> str:
+        """
+        Generates complete documentation for all provided element classes.
+        """
+        docs = [
+            "# Markdown Syntax for Notion Blocks",
+            "The following Markdown patterns are supported for creating Notion blocks:",
+        ]
+
+        # Generate docs for each element
+        for element in element_classes:
+            docs.append("\n" + cls.generate_element_doc(element))
+
+        return "\n".join(docs)
+
+    @classmethod
+    def generate_system_prompt(
+        cls,
+        element_classes: List[Type[NotionBlockElement]],
+    ) -> str:
+        """
+        Generates a complete system prompt for LLMs.
+        """
+        element_docs = cls.generate_element_docs(element_classes)
+        return cls.SYSTEM_PROMPT_TEMPLATE.format(element_docs=element_docs)