notionary 0.2.21__py3-none-any.whl → 0.2.23__py3-none-any.whl

notionary/blocks/file/file_element.py

@@ -10,32 +10,38 @@ from notionary.blocks.file.file_element_models import (
     FileBlock,
     FileType,
 )
+from notionary.blocks.mixins.captions import CaptionMixin
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult, BlockType
-from notionary.blocks.paragraph.paragraph_models import (
-    CreateParagraphBlock,
-    ParagraphBlock,
-)
-from notionary.blocks.rich_text.rich_text_models import RichTextObject
-from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
 
 
-class FileElement(BaseBlockElement):
+class FileElement(BaseBlockElement, CaptionMixin):
     """
     Handles conversion between Markdown file embeds and Notion file blocks.
 
     Markdown file syntax:
-    - [file](https://example.com/document.pdf "Caption")
-    - [file](https://example.com/document.pdf)
+    - [file](https://example.com/document.pdf) - URL only
+    - [file](https://example.com/document.pdf)(caption:Annual Report) - URL with caption
+    - (caption:Important document)[file](https://example.com/doc.pdf) - caption before URL
 
     Supports external file URLs with optional captions.
     """
 
-    PATTERN = re.compile(
-        r"^\[file\]\("  # prefix
-        r'(https?://[^\s\)"]+)'  # URL
-        r'(?:\s+"([^"]*)")?'  # optional caption
-        r"\)$"
-    )
+    # Simple pattern that matches just the file link, CaptionMixin handles caption separately
+    FILE_PATTERN = re.compile(r"\[file\]\((https?://[^\s\"]+)\)")
+
+    @classmethod
+    def _extract_file_url(cls, text: str) -> Optional[str]:
+        """Extract file URL from text, handling caption patterns."""
+        # First remove any captions to get clean text for URL extraction
+        clean_text = cls.remove_caption(text)
+
+        # Now extract the URL from clean text
+        match = cls.FILE_PATTERN.search(clean_text)
+        if match:
+            return match.group(1)
+
+        return None
 
     @classmethod
     def match_notion(cls, block: Block) -> bool:
@@ -43,31 +49,28 @@ class FileElement(BaseBlockElement):
         return block.type == BlockType.FILE and block.file
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
-        """Convert markdown file link to Notion FileBlock followed by an empty paragraph."""
-        match = cls.PATTERN.match(text.strip())
-        if not match:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown file link to Notion FileBlock."""
+        # Use our helper method to extract the URL
+        url = cls._extract_file_url(text.strip())
+        if not url:
             return None
 
-        url, caption_text = match.group(1), match.group(2) or ""
+        # Use mixin to extract caption (if present anywhere in text)
+        caption_text = cls.extract_caption(text.strip())
+        caption_rich_text = cls.build_caption_rich_text(caption_text or "")
 
         # Build FileBlock using FileType enum
         file_block = FileBlock(
-            type=FileType.EXTERNAL, external=ExternalFile(url=url), caption=[]
+            type=FileType.EXTERNAL,
+            external=ExternalFile(url=url),
+            caption=caption_rich_text,
         )
-        if caption_text.strip():
-            rt = RichTextObject.from_plain_text(caption_text)
-            file_block.caption = [rt]
 
-        empty_para = ParagraphBlock(rich_text=[])
-
-        return [
-            CreateFileBlock(file=file_block),
-            CreateParagraphBlock(paragraph=empty_para),
-        ]
+        return CreateFileBlock(file=file_block)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         if block.type != BlockType.FILE or not block.file:
             return None
 
@@ -84,10 +87,26 @@ class FileElement(BaseBlockElement):
         else:
             return None
 
-        if not fb.caption:
-            return f"[file]({url})"
+        result = f"[file]({url})"
+
+        # Add caption if present
+        caption_markdown = await cls.format_caption_for_markdown(fb.caption or [])
+        if caption_markdown:
+            result += caption_markdown
+
+        return result
 
-        caption_md = TextInlineFormatter.extract_text_with_formatting(fb.caption)
-        if caption_md:
-            return f'[file]({url} "{caption_md}")'
-        return f"[file]({url})"
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for file blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="File blocks embed downloadable files from external URLs with optional captions",
+            syntax_examples=[
+                "[file](https://example.com/document.pdf)",
+                "[file](https://example.com/document.pdf)(caption:Annual Report)",
+                "(caption:Q1 Data)[file](https://example.com/spreadsheet.xlsx)",
+                "[file](https://example.com/manual.docx)(caption:**User** manual)",
+            ],
+            usage_guidelines="Use for linking to downloadable files like PDFs, documents, spreadsheets. Supports various file formats. Caption supports rich text formatting and should describe the file content or purpose.",
+        )

notionary/blocks/file/file_element_markdown_node.py

@@ -5,6 +5,7 @@ from typing import Optional
 from pydantic import BaseModel
 
 from notionary.markdown.markdown_node import MarkdownNode
+from notionary.blocks.mixins.captions import CaptionMarkdownNodeMixin
 
 
 class FileMarkdownNodeParams(BaseModel):
@@ -12,10 +13,9 @@ class FileMarkdownNodeParams(BaseModel):
     caption: Optional[str] = None
 
 
-class FileMarkdownNode(MarkdownNode):
+class FileMarkdownNode(MarkdownNode, CaptionMarkdownNodeMixin):
     """
     Programmatic interface for creating Notion-style Markdown file embeds.
-    Example: [file](https://example.com/file.pdf "My Caption")
     """
 
     def __init__(self, url: str, caption: Optional[str] = None):
@@ -27,9 +27,11 @@ class FileMarkdownNode(MarkdownNode):
         return cls(url=params.url, caption=params.caption)
 
     def to_markdown(self) -> str:
+        """Return the Markdown representation.
+
+        Examples:
+        - [file](https://example.com/document.pdf)
+        - [file](https://example.com/document.pdf)(caption:User manual)
         """
-        Convert to markdown as [file](url "caption") or [file](url) if caption is empty.
-        """
-        if self.caption:
-            return f'[file]({self.url} "{self.caption}")'
-        return f"[file]({self.url})"
+        base_markdown = f"[file]({self.url})"
+        return self.append_caption_to_markdown(base_markdown, self.caption)

notionary/blocks/guards.py

@@ -0,0 +1,22 @@
+from typing import Protocol
+
+from notionary.blocks.models import BlockCreateRequest
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+
+
+class HasRichText(Protocol):
+    """Protocol for objects that have a rich_text attribute."""
+
+    rich_text: list[RichTextObject]
+
+
+class HasChildren(Protocol):
+    """Protocol for objects that have children blocks."""
+
+    children: list[BlockCreateRequest]
+
+
+class HasRichTextAndChildren(HasRichText, HasChildren, Protocol):
+    """Protocol for objects that have both rich_text and children."""
+
+    pass

notionary/blocks/heading/heading_element.py

@@ -10,6 +10,7 @@ from notionary.blocks.heading.heading_models import (
     CreateHeading3Block,
     HeadingBlock,
 )
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult, BlockType
 from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
 from notionary.blocks.types import BlockColor
@@ -33,7 +34,7 @@ class HeadingElement(BaseBlockElement):
         )
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """Convert markdown headings (#, ##, ###) to Notion HeadingBlock."""
         match = cls.PATTERN.match(text.strip())
         if not match:
@@ -47,7 +48,7 @@ class HeadingElement(BaseBlockElement):
         if not content:
             return None
 
-        rich_text = TextInlineFormatter.parse_inline_formatting(content)
+        rich_text = await TextInlineFormatter.parse_inline_formatting(content)
         heading_content = HeadingBlock(
             rich_text=rich_text, color=BlockColor.DEFAULT, is_toggleable=False
         )
@@ -60,7 +61,7 @@ class HeadingElement(BaseBlockElement):
             return CreateHeading3Block(heading_3=heading_content)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         # Only handle heading blocks via BlockType enum
         if block.type not in (
             BlockType.HEADING_1,
@@ -85,9 +86,27 @@ class HeadingElement(BaseBlockElement):
         if not heading_data.rich_text:
             return None
 
-        text = TextInlineFormatter.extract_text_with_formatting(heading_data.rich_text)
+        text = await TextInlineFormatter.extract_text_with_formatting(
+            heading_data.rich_text
+        )
         if not text:
             return None
 
         # Use hash-style for all heading levels
         return f"{('#' * level)} {text}"
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for heading blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Heading blocks create hierarchical document structure with different levels",
+            syntax_examples=[
+                "# Heading Level 1",
+                "## Heading Level 2",
+                "### Heading Level 3",
+                "# Heading with **bold text**",
+                "## Heading with *italic text*",
+            ],
+            usage_guidelines="Use # for main titles, ## for sections, ### for subsections. Supports inline formatting. Only levels 1-3 are supported in Notion.",
+        )

notionary/blocks/image_block/image_element.py

@@ -6,60 +6,52 @@ from typing import Optional
 from notionary.blocks.base_block_element import BaseBlockElement
 from notionary.blocks.file.file_element_models import ExternalFile, FileType
 from notionary.blocks.image_block.image_models import CreateImageBlock, FileBlock
+from notionary.blocks.mixins.captions import CaptionMixin
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult, BlockType
-from notionary.blocks.paragraph.paragraph_models import (
-    CreateParagraphBlock,
-    ParagraphBlock,
-)
-from notionary.blocks.rich_text.rich_text_models import RichTextObject
-from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
 
 
-class ImageElement(BaseBlockElement):
+class ImageElement(BaseBlockElement, CaptionMixin):
     """
     Handles conversion between Markdown images and Notion image blocks.
 
     Markdown image syntax:
     - [image](https://example.com/image.jpg) - URL only
-    - [image](https://example.com/image.jpg "Caption") - URL + caption
+    - [image](https://example.com/image.jpg)(caption:This is a caption) - URL with caption
+    - (caption:Profile picture)[image](https://example.com/avatar.jpg) - caption before URL
     """
 
-    PATTERN = re.compile(
-        r"^\[image\]\("  # prefix
-        r"(https?://[^\s\"]+)"  # URL (exclude whitespace and ")
-        r"(?:\s+\"([^\"]+)\")?"  # optional caption
-        r"\)$"
-    )
+    # Flexible pattern that can handle caption in any position
+    IMAGE_PATTERN = re.compile(r"\[image\]\((https?://[^\s\"]+)\)")
 
     @classmethod
     def match_notion(cls, block: Block) -> bool:
         return block.type == BlockType.IMAGE and block.image
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
-        """Convert markdown image syntax to Notion ImageBlock followed by an empty paragraph."""
-        match = cls.PATTERN.match(text.strip())
-        if not match:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+        """Convert markdown image syntax to Notion ImageBlock."""
+        clean_text = cls.remove_caption(text.strip())
+
+        # Use our own regex to find the image URL
+        image_match = cls.IMAGE_PATTERN.search(clean_text)
+        if not image_match:
             return None
 
-        url, caption_text = match.group(1), match.group(2) or ""
+        url = image_match.group(1)
+
+        caption_text = cls.extract_caption(text.strip())
+        caption_rich_text = cls.build_caption_rich_text(caption_text or "")
+
         # Build ImageBlock
         image_block = FileBlock(
-            type="external", external=ExternalFile(url=url), caption=[]
+            type="external", external=ExternalFile(url=url), caption=caption_rich_text
         )
-        if caption_text.strip():
-            rt = RichTextObject.from_plain_text(caption_text.strip())
-            image_block.caption = [rt]
-
-        empty_para = ParagraphBlock(rich_text=[])
 
-        return [
-            CreateImageBlock(image=image_block),
-            CreateParagraphBlock(paragraph=empty_para),
-        ]
+        return CreateImageBlock(image=image_block)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         if block.type != BlockType.IMAGE or not block.image:
             return None
 
@@ -72,13 +64,26 @@ class ImageElement(BaseBlockElement):
         else:
             return None
 
-        captions = fo.caption or []
-        if not captions:
-            return f"[image]({url})"
+        result = f"[image]({url})"
 
-        caption_text = "".join(
-            (rt.plain_text or TextInlineFormatter.extract_text_with_formatting([rt]))
-            for rt in captions
-        )
+        # Add caption if present
+        caption_markdown = await cls.format_caption_for_markdown(fo.caption or [])
+        if caption_markdown:
+            result += caption_markdown
+
+        return result
 
-        return f'[image]({url} "{caption_text}")'
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for image blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Image blocks display images from external URLs with optional captions",
+            syntax_examples=[
+                "[image](https://example.com/photo.jpg)",
+                "[image](https://example.com/diagram.png)(caption:Architecture Diagram)",
+                "(caption:Sales Chart)[image](https://example.com/chart.svg)",
+                "[image](https://example.com/screenshot.png)(caption:Dashboard **overview**)",
+            ],
+            usage_guidelines="Use for displaying images from external URLs. Supports common image formats (jpg, png, gif, svg, webp). Caption supports rich text formatting and describes the image content.",
+        )

notionary/blocks/image_block/image_markdown_node.py

@@ -5,6 +5,7 @@ from typing import Optional
 from pydantic import BaseModel
 
 from notionary.markdown.markdown_node import MarkdownNode
+from notionary.blocks.mixins.captions import CaptionMarkdownNodeMixin
 
 
 class ImageMarkdownBlockParams(BaseModel):
@@ -12,10 +13,9 @@ class ImageMarkdownBlockParams(BaseModel):
     caption: Optional[str] = None
 
 
-class ImageMarkdownNode(MarkdownNode):
+class ImageMarkdownNode(MarkdownNode, CaptionMarkdownNodeMixin):
     """
     Programmatic interface for creating Notion-style image blocks.
-    Example: [image](https://example.com/image.jpg "Optional caption")
     """
 
     def __init__(
@@ -30,6 +30,11 @@ class ImageMarkdownNode(MarkdownNode):
         return cls(url=params.url, caption=params.caption)
 
     def to_markdown(self) -> str:
-        if self.caption:
-            return f'[image]({self.url} "{self.caption}")'
-        return f"[image]({self.url})"
+        """Return the Markdown representation.
+
+        Examples:
+        - [image](https://example.com/screenshot.png)
+        - [image](https://example.com/screenshot.png)(caption:Dashboard overview)
+        """
+        base_markdown = f"[image]({self.url})"
+        return self.append_caption_to_markdown(base_markdown, self.caption)

notionary/blocks/mixins/captions/__init__.py

@@ -0,0 +1,4 @@
+from .caption_mixin import CaptionMixin
+from .caption_markdown_node_mixin import CaptionMarkdownNodeMixin
+
+__all__ = ["CaptionMixin", "CaptionMarkdownNodeMixin"]

notionary/blocks/mixins/captions/caption_markdown_node_mixin.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+
+class CaptionMarkdownNodeMixin:
+    """Mixin to add caption functionality to MarkdownNode classes."""
+
+    @classmethod
+    def append_caption_to_markdown(
+        cls, base_markdown: str, caption: Optional[str]
+    ) -> str:
+        """
+        Append caption to existing markdown if caption is present.
+        Returns: base_markdown + "(caption:...)" or just base_markdown
+        """
+        if not caption:
+            return base_markdown
+        return f"{base_markdown}(caption:{caption})"
+
+    @classmethod
+    def format_caption_for_markdown(cls, caption: Optional[str]) -> str:
+        """
+        Format caption text for markdown output.
+        Returns: "(caption:...)" or empty string
+        """
+        if not caption:
+            return ""
+        return f"(caption:{caption})"
+
+    def has_caption(self) -> bool:
+        """Check if this node has a caption."""
+        return hasattr(self, "caption") and bool(getattr(self, "caption", None))

notionary/blocks/mixins/captions/caption_mixin.py

@@ -0,0 +1,92 @@
+from typing import Optional
+import re
+from notionary.blocks.rich_text.rich_text_models import RichTextObject
+from notionary.blocks.rich_text.text_inline_formatter import TextInlineFormatter
+
+
+class CaptionMixin:
+    """Mixin to add caption parsing functionality to block elements."""
+
+    # Generic caption pattern - finds caption anywhere in text
+    CAPTION_PATTERN = re.compile(r"\(caption:([^)]*)\)")
+
+    @classmethod
+    def extract_caption(cls, text: str) -> Optional[str]:
+        """
+        Extract caption text from anywhere in the input text.
+        Returns only the caption content, preserving parentheses in content.
+        """
+        # Look for (caption: followed by content followed by )
+        # Handle cases where caption content contains parentheses
+        caption_start = text.find("(caption:")
+        if caption_start == -1:
+            return None
+
+        # Find the matching closing parenthesis
+        # Start after "(caption:"
+        content_start = caption_start + 9  # len("(caption:")
+        paren_count = 1
+        pos = content_start
+
+        while pos < len(text) and paren_count > 0:
+            if text[pos] == "(":
+                paren_count += 1
+            elif text[pos] == ")":
+                paren_count -= 1
+            pos += 1
+
+        if paren_count == 0:
+            # Found matching closing parenthesis
+            return text[content_start : pos - 1]
+
+        return None
+
+    @classmethod
+    def remove_caption(cls, text: str) -> str:
+        """
+        Remove caption from text and return clean text.
+        Uses the same balanced parentheses logic as extract_caption.
+        """
+        caption_start = text.find("(caption:")
+        if caption_start == -1:
+            return text.strip()
+
+        # Find the matching closing parenthesis
+        content_start = caption_start + 9  # len("(caption:")
+        paren_count = 1
+        pos = content_start
+
+        while pos < len(text) and paren_count > 0:
+            if text[pos] == "(":
+                paren_count += 1
+            elif text[pos] == ")":
+                paren_count -= 1
+            pos += 1
+
+        if paren_count == 0:
+            # Remove the entire caption including the outer parentheses
+            return (text[:caption_start] + text[pos:]).strip()
+
+        # Fallback to regex-based removal if balanced parsing fails
+        return cls.CAPTION_PATTERN.sub("", text).strip()
+
+    @classmethod
+    def build_caption_rich_text(cls, caption_text: str) -> list[RichTextObject]:
+        """Return caption as canonical rich text list (with annotations)."""
+        if not caption_text:
+            return []
+        # IMPORTANT: use the same formatter used elsewhere in the app
+        return [RichTextObject.for_caption(caption_text)]
+
+    @classmethod
+    async def format_caption_for_markdown(
+        cls, caption_list: list[RichTextObject]
+    ) -> str:
+        """Convert rich text caption back to markdown format."""
+        if not caption_list:
+            return ""
+        # Preserve markdown formatting (bold, italic, etc.)
+        caption_text = await TextInlineFormatter.extract_text_with_formatting(
+            caption_list
+        )
+        return f"(caption:{caption_text})" if caption_text else ""

notionary/blocks/models.py

@@ -48,6 +48,7 @@ if TYPE_CHECKING:
     from notionary.blocks.todo import CreateToDoBlock, ToDoBlock
     from notionary.blocks.toggle import CreateToggleBlock, ToggleBlock
     from notionary.blocks.video import CreateVideoBlock
+    from notionary.blocks.child_database import ChildDatabaseBlock
 
 
 class BlockChildrenResponse(BaseModel):
@@ -131,6 +132,7 @@ class Block(BaseModel):
     video: Optional[FileBlock] = None
     pdf: Optional[FileBlock] = None
     table_of_contents: Optional[TableOfContentsBlock] = None
+    child_database: Optional[ChildDatabaseBlock] = None
 
     def get_block_content(self) -> Optional[Any]:
         """Get the content object for this block based on its type."""
@@ -165,7 +167,7 @@ if TYPE_CHECKING:
         CreatePdfBlock,
         CreateTableBlock,
     ]
-    BlockCreateResult = Optional[Union[list[BlockCreateRequest], BlockCreateRequest]]
+    BlockCreateResult = Union[BlockCreateRequest]
 else:
     # at runtime there are no typings anyway
     BlockCreateRequest = Any

notionary/blocks/numbered_list/numbered_list_element.py

@@ -4,6 +4,7 @@ import re
 from typing import Optional
 
 from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult, BlockType
 from notionary.blocks.numbered_list.numbered_list_models import (
     CreateNumberedListItemBlock,
@@ -23,14 +24,14 @@ class NumberedListElement(BaseBlockElement):
         return block.type == BlockType.NUMBERED_LIST_ITEM and block.numbered_list_item
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """Convert markdown numbered list item to Notion NumberedListItemBlock."""
         match = cls.PATTERN.match(text.strip())
         if not match:
             return None
 
         content = match.group(2)
-        rich_text = TextInlineFormatter.parse_inline_formatting(content)
+        rich_text = await TextInlineFormatter.parse_inline_formatting(content)
 
         numbered_list_content = NumberedListItemBlock(
             rich_text=rich_text, color=BlockColor.DEFAULT
@@ -39,10 +40,26 @@ class NumberedListElement(BaseBlockElement):
 
     # FIX: Roundtrip conversions will never work this way here
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
         if block.type != BlockType.NUMBERED_LIST_ITEM or not block.numbered_list_item:
             return None
 
         rich = block.numbered_list_item.rich_text
-        content = TextInlineFormatter.extract_text_with_formatting(rich)
+        content = await TextInlineFormatter.extract_text_with_formatting(rich)
         return f"1. {content}"
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for numbered list blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Numbered list items create ordered lists with sequential numbering",
+            syntax_examples=[
+                "1. First item",
+                "2. Second item",
+                "3. Third item",
+                "1. Item with **bold text**",
+                "1. Item with *italic text*",
+            ],
+            usage_guidelines="Use numbers followed by periods to create ordered lists. Supports inline formatting like bold, italic, and links. Numbering is automatically handled by Notion.",
+        )

notionary/blocks/paragraph/paragraph_element.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import Optional
 
 from notionary.blocks.base_block_element import BaseBlockElement
+from notionary.blocks.syntax_prompt_builder import BlockElementMarkdownInformation
 from notionary.blocks.models import Block, BlockCreateResult
 from notionary.blocks.paragraph.paragraph_models import (
     CreateParagraphBlock,
@@ -22,21 +23,36 @@ class ParagraphElement(BaseBlockElement):
         return block.type == "paragraph" and block.paragraph
 
     @classmethod
-    def markdown_to_notion(cls, text: str) -> BlockCreateResult:
+    async def markdown_to_notion(cls, text: str) -> BlockCreateResult:
         """Convert markdown text to a Notion ParagraphBlock."""
         if not text.strip():
             return None
 
-        rich = TextInlineFormatter.parse_inline_formatting(text)
+        rich = await TextInlineFormatter.parse_inline_formatting(text)
 
         paragraph_content = ParagraphBlock(rich_text=rich, color=BlockColor.DEFAULT)
         return CreateParagraphBlock(paragraph=paragraph_content)
 
     @classmethod
-    def notion_to_markdown(cls, block: Block) -> Optional[str]:
-        if block.type != "paragraph" or not block.paragraph:
+    async def notion_to_markdown(cls, block: Block) -> Optional[str]:
+        if block.type != BlockType.PARAGRAPH or not block.paragraph:
             return None
 
         rich_list = block.paragraph.rich_text
-        markdown = TextInlineFormatter.extract_text_with_formatting(rich_list)
+        markdown = await TextInlineFormatter.extract_text_with_formatting(rich_list)
         return markdown or None
+
+    @classmethod
+    def get_system_prompt_information(cls) -> Optional[BlockElementMarkdownInformation]:
+        """Get system prompt information for paragraph blocks."""
+        return BlockElementMarkdownInformation(
+            block_type=cls.__name__,
+            description="Paragraph blocks contain regular text content with optional inline formatting",
+            syntax_examples=[
+                "This is a simple paragraph.",
+                "Paragraph with **bold text** and *italic text*.",
+                "Paragraph with [link](https://example.com) and `code`.",
+                "Multiple sentences in one paragraph. Each sentence flows naturally.",
+            ],
+            usage_guidelines="Use for regular text content. Supports inline formatting: **bold**, *italic*, `code`, [links](url). Default block type for plain text.",
+        )