markdown-flow 0.3.1__tar.gz → 0.3.2__tar.gz

{markdown_flow-0.3.1 → markdown_flow-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-flow
-Version: 0.3.1
+Version: 0.3.2
 Summary: An agent library designed to parse and process MarkdownFlow documents
 Project-URL: Homepage, https://github.com/ai-shifu/markdown-flow-agent-py
 Project-URL: Bug Tracker, https://github.com/ai-shifu/markdown-flow-agent-py/issues

{markdown_flow-0.3.1 → markdown_flow-0.3.2}/markdown_flow/__init__.py

@@ -106,4 +106,4 @@ __all__ = [
     "replace_variables_in_text",
 ]
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

{markdown_flow-0.3.1 → markdown_flow-0.3.2}/markdown_flow/constants.py

@@ -13,9 +13,18 @@ COMPILED_PERCENT_VARIABLE_REGEX = re.compile(
 )
 
 # Interaction regex base patterns
-INTERACTION_PATTERN = r"(?<!\\)\?\[([^\]]*)\](?!\()"  # Base pattern with capturing group for content extraction, excludes escaped \?[]
-INTERACTION_PATTERN_NON_CAPTURING = r"(?<!\\)\?\[[^\]]*\](?!\()"  # Non-capturing version for block splitting, excludes escaped \?[]
-INTERACTION_PATTERN_SPLIT = r"((?<!\\)\?\[[^\]]*\](?!\())"  # Pattern for re.split() with outer capturing group, excludes escaped \?[]
+#
+# The bracket content accepts an escaped delimiter as one unit, so a `\]` inside an option does
+# not end the interaction. The three alternatives are mutually exclusive on purpose: a backslash
+# before a delimiter can only be read as an escape, so the pattern cannot backtrack into reading
+# it as plain text and then closing on the very bracket it escapes. Without that, this regex and
+# a left-to-right scanner disagree about `?[a\\]`, and two parsers of one grammar must not.
+# A backslash before anything else -- LaTeX such as `$\pi$`, or `\\` as a line break -- stays
+# ordinary text, exactly as it was before escapes existed. See markdown_flow.escaping.
+_INTERACTION_CONTENT = r"(?:\\[|/.\]]|\\(?![|/.\]])|[^\]\\])*"
+INTERACTION_PATTERN = rf"(?<!\\)\?\[({_INTERACTION_CONTENT})\](?!\()"  # Base pattern with capturing group for content extraction, excludes escaped \?[]
+INTERACTION_PATTERN_NON_CAPTURING = rf"(?<!\\)\?\[{_INTERACTION_CONTENT}\](?!\()"  # Non-capturing version for block splitting, excludes escaped \?[]
+INTERACTION_PATTERN_SPLIT = rf"((?<!\\)\?\[{_INTERACTION_CONTENT}\](?!\())"  # Pattern for re.split() with outer capturing group, excludes escaped \?[]
 
 # InteractionParser specific regex patterns
 COMPILED_INTERACTION_REGEX = re.compile(INTERACTION_PATTERN)  # Main interaction pattern matcher

markdown_flow-0.3.2/markdown_flow/escaping.py

@@ -0,0 +1,141 @@
+"""Backslash escapes for the delimiters inside an interaction's brackets.
+
+`?[A|B]` gives `|`, `//`, `...` and `]` structural meaning, so option text that contains one of
+them is reshaped: a bar splits one choice into two, a double slash gives half the display away to
+the stored value, an ellipsis turns the rest into a text box, and a bracket ends the interaction
+early. An option carrying a URL or a regular expression could not be written at all.
+
+A backslash before one of those characters now makes it ordinary text.
+
+The escape is deliberately *selective*: a backslash is an escape only when the character after it
+is a delimiter, and is literal text everywhere else. `\\\\` is not an escape either. That matters
+for content that already exists: of 110,685 interactions in published courses, 97 contain a
+backslash and every one of them is LaTeX -- `$\\pi_\\theta$`, `\\beta`, `\\nabla`, and `\\\\` as a
+line break. A general "backslash escapes the next character" rule would render those as
+`$pi_theta$`. Under this rule, none of them change.
+
+The cost is that a literal backslash cannot sit immediately before a literal delimiter: `\\|` is
+an escaped bar, not a backslash and a separator. Nothing in the measured corpus writes that.
+"""
+
+# The characters a backslash may make ordinary. `/` covers `//`, `.` covers `...`.
+ESCAPABLE = "|/.]"
+
+
+def is_escape(text: str, index: int) -> bool:
+    """Whether the backslash at `index` escapes the character after it."""
+    return index + 1 < len(text) and text[index] == "\\" and text[index + 1] in ESCAPABLE
+
+
+def escape_interaction_text(text: str) -> str:
+    """Make `text` safe to write inside `?[...]`, keeping every character it has.
+
+    Escaping each delimiter rather than the backslashes as well is what keeps existing content
+    readable: a script that writes `$\\pi$` in an option still writes `$\\pi$` afterwards.
+    """
+    out: list[str] = []
+    for char in text:
+        if char in ESCAPABLE:
+            out.append("\\")
+        out.append(char)
+    return "".join(out)
+
+
+def unescape_interaction_text(text: str) -> str:
+    """Resolve the escapes in one option's text, leaving every other backslash alone."""
+    out: list[str] = []
+    index = 0
+    while index < len(text):
+        if is_escape(text, index):
+            out.append(text[index + 1])
+            index += 2
+            continue
+        out.append(text[index])
+        index += 1
+    return "".join(out)
+
+
+def find_unescaped(text: str, needle: str, start: int = 0) -> int:
+    """Index of the first `needle` that is not escaped and does not begin inside an escape.
+
+    Returns -1 when there is none. `needle` is matched whole: a `//` whose first slash is escaped
+    is not a separator even though its second slash is bare, because that second slash is the
+    escaped character of the pair.
+    """
+    index = start
+    while index < len(text):
+        if is_escape(text, index):
+            index += 2
+            continue
+        if text.startswith(needle, index):
+            return index
+        index += 1
+    return -1
+
+
+def split_unescaped(text: str, separator: str) -> list[str]:
+    """Split on every unescaped `separator`, leaving the escapes themselves in place."""
+    parts: list[str] = []
+    start = 0
+    while True:
+        found = find_unescaped(text, separator, start)
+        if found < 0:
+            parts.append(text[start:])
+            return parts
+        parts.append(text[start:found])
+        start = found + len(separator)
+
+
+def split_on_single_pipe(text: str) -> list[str]:
+    """Split on unescaped single bars, leaving `||` joined as the multi-select separator."""
+    parts: list[str] = []
+    start = 0
+    index = 0
+    while index < len(text):
+        if is_escape(text, index):
+            index += 2
+            continue
+        if text[index] == "|":
+            if text.startswith("||", index):
+                index += 2
+                continue
+            if index > 0 and text[index - 1] == "|" and not is_escape(text, index - 1):
+                index += 1
+                continue
+            parts.append(text[start:index])
+            start = index + 1
+        index += 1
+    parts.append(text[start:])
+    return parts
+
+
+def rfind_unescaped(text: str, needle: str) -> int:
+    """Index of the *last* unescaped `needle`, or -1."""
+    found = -1
+    start = 0
+    while True:
+        at = find_unescaped(text, needle, start)
+        if at < 0:
+            return found
+        found = at
+        start = at + 1
+
+
+def split_on_ellipsis(content: str) -> tuple[str, str] | None:
+    """Split an interaction's content at the `...` that opens its text box, or None.
+
+    Two details are inherited rather than chosen, because changing either would rewrite questions
+    in courses that are already published:
+
+    * the ellipsis counts only on the first line. The regex this replaces was anchored and its
+      `.` did not cross a newline, so `A\n| ...hint` has always been read as two buttons, one of
+      them named `...hint`. 122 published interactions depend on that reading.
+    * the *last* ellipsis on that line wins, which is what the greedy group matched.
+
+    What is new is only that an escaped ellipsis no longer counts.
+    """
+    head = content.split("\n", 1)[0]
+    at = rfind_unescaped(head, "...")
+    if at < 0:
+        return None
+    return head[:at], head[at + 3 :]

{markdown_flow-0.3.1 → markdown_flow-0.3.2}/markdown_flow/parser/interaction.py

@@ -12,8 +12,13 @@ from ..constants import (
     COMPILED_INTERACTION_REGEX,
     COMPILED_LAYER1_INTERACTION_REGEX,
     COMPILED_LAYER2_VARIABLE_REGEX,
-    COMPILED_LAYER3_ELLIPSIS_REGEX,
-    COMPILED_SINGLE_PIPE_SPLIT_REGEX,
+)
+from ..escaping import (
+    find_unescaped,
+    split_on_ellipsis,
+    split_on_single_pipe,
+    split_unescaped,
+    unescape_interaction_text,
 )
 
 
@@ -46,12 +51,10 @@ def extract_interaction_question(content: str) -> str | None:
     # Extract interaction content (remove ?[ and ])
     interaction_content = match.group(1) if match.groups() else match.group(0)[2:-1]
 
-    # Find ... separator, question text follows
-    if "..." in interaction_content:
-        # Split and get question part
-        parts = interaction_content.split("...", 1)
-        if len(parts) > 1:
-            return parts[1].strip()
+    # Find ... separator, question text follows. An ellipsis an option escaped is not one.
+    at = find_unescaped(interaction_content, "...")
+    if at >= 0:
+        return unescape_interaction_text(interaction_content[at + 3 :]).strip()
 
     return None  # type: ignore[unreachable]
 
@@ -153,13 +156,13 @@ class InteractionParser:
         Returns:
             Parsing result dictionary
         """
-        # Detect ... separator
-        ellipsis_match = COMPILED_LAYER3_ELLIPSIS_REGEX.match(content)
+        # Detect ... separator, ignoring any an option escaped.
+        ellipsis = split_on_ellipsis(content)
 
-        if ellipsis_match:
+        if ellipsis is not None:
             # Has ... separator
-            before_ellipsis = ellipsis_match.group(1).strip()
-            question = ellipsis_match.group(2).strip()
+            before_ellipsis = ellipsis[0].strip()
+            question = unescape_interaction_text(ellipsis[1]).strip()
 
             if before_ellipsis:
                 # Has prefix content (buttons or single option) + text input
@@ -180,7 +183,7 @@ class InteractionParser:
                 "is_multi_select": False,
             }
         # No ... separator
-        if ("|" in content or "||" in content) and content:  # type: ignore[unreachable]
+        if content and find_unescaped(content, "|") >= 0:  # type: ignore[unreachable]
             # Pure button group
             buttons, is_multi_select = self._parse_buttons(content)
             interaction_type = InteractionType.BUTTONS_MULTI_SELECT if is_multi_select else InteractionType.BUTTONS_ONLY
@@ -229,10 +232,10 @@ class InteractionParser:
                 "buttons": [{"display": "", "value": ""}],
             }
 
-        ellipsis_match = COMPILED_LAYER3_ELLIPSIS_REGEX.match(content)
-        if ellipsis_match:
-            before_ellipsis = ellipsis_match.group(1).strip()
-            question = ellipsis_match.group(2).strip()
+        ellipsis = split_on_ellipsis(content)
+        if ellipsis is not None:
+            before_ellipsis = ellipsis[0].strip()
+            question = unescape_interaction_text(ellipsis[1]).strip()
 
             if before_ellipsis:
                 # Buttons + text input: ?[A | B | ...question]
@@ -251,7 +254,7 @@ class InteractionParser:
                 "is_multi_select": False,
             }
 
-        if "|" in content:  # type: ignore[unreachable]
+        if find_unescaped(content, "|") >= 0:  # type: ignore[unreachable]
             # Button group: ?[A | B] or ?[A || B]
             buttons, is_multi_select = self._parse_buttons(content)
             return {
@@ -287,11 +290,10 @@ class InteractionParser:
             # Use different splitting logic based on separator type
             if is_multi_select:
                 # Multi-select mode: split on ||, preserve single |
-                button_parts = content.split("||")
+                button_parts = split_unescaped(content, "||")
             else:
                 # Single-select mode: split on single |, but preserve ||
-                # Use pre-compiled regex from constants
-                button_parts = COMPILED_SINGLE_PIPE_SPLIT_REGEX.split(content)
+                button_parts = split_on_single_pipe(content)
 
             for button_text in button_parts:
                 button_text = button_text.strip()
@@ -300,7 +302,8 @@ class InteractionParser:
                     buttons.append(button)
         except (TypeError, ValueError):
             # Fallback to treating entire content as single button
-            return [{"display": content.strip(), "value": content.strip()}], False
+            whole = unescape_interaction_text(content).strip()
+            return [{"display": whole, "value": whole}], False
 
         # For empty content (like just separators), return empty list
         if not buttons and (content.strip() == "||" or content.strip() == "|"):
@@ -308,7 +311,8 @@ class InteractionParser:
 
         # Ensure at least one button exists (but only if there's actual content)
         if not buttons and content.strip():
-            buttons = [{"display": content.strip(), "value": content.strip()}]
+            whole = unescape_interaction_text(content).strip()
+            buttons = [{"display": whole, "value": whole}]
 
         return buttons, is_multi_select
 
@@ -330,18 +334,19 @@ class InteractionParser:
             return {"display": "", "value": ""}
 
         try:
-            # Detect Button//value format - split only on first //
-            if "//" in button_text:
-                parts = button_text.split("//", 1)  # Split only on first //
-                display = parts[0].strip()
-                value = parts[1] if len(parts) > 1 else ""
+            # Detect Button//value format - split only on the first unescaped //
+            at = find_unescaped(button_text, "//")
+            if at >= 0:
+                display = unescape_interaction_text(button_text[:at]).strip()
                 # Don't strip value to preserve intentional spacing/formatting
+                value = unescape_interaction_text(button_text[at + 2 :])
                 return {"display": display, "value": value}
         except (ValueError, IndexError):
             # Fallback: use text as both display and value
             pass
 
-        return {"display": button_text, "value": button_text}
+        resolved = unescape_interaction_text(button_text)
+        return {"display": resolved, "value": resolved}
 
     def _detect_separator_type(self, content: str) -> tuple[str, bool]:
         """
@@ -359,9 +364,9 @@ class InteractionParser:
         if not content or not isinstance(content, str):
             return "|", False
 
-        # Find first occurrence of separators
-        single_pos = content.find("|")
-        double_pos = content.find("||")
+        # Find first occurrence of separators. A bar an option escaped is not one.
+        single_pos = find_unescaped(content, "|")
+        double_pos = find_unescaped(content, "||")
 
         # If no separators found
         if single_pos == -1 and double_pos == -1:

{markdown_flow-0.3.1 → markdown_flow-0.3.2}/markdown_flow.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-flow
-Version: 0.3.1
+Version: 0.3.2
 Summary: An agent library designed to parse and process MarkdownFlow documents
 Project-URL: Homepage, https://github.com/ai-shifu/markdown-flow-agent-py
 Project-URL: Bug Tracker, https://github.com/ai-shifu/markdown-flow-agent-py/issues

{markdown_flow-0.3.1 → markdown_flow-0.3.2}/markdown_flow.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ markdown_flow/constants.py
 markdown_flow/constants_system_prompt.py
 markdown_flow/core.py
 markdown_flow/enums.py
+markdown_flow/escaping.py
 markdown_flow/exceptions.py
 markdown_flow/higher_priority_prompt.md
 markdown_flow/llm.py