logseq-matryca-parser 0.3.0__py3-none-any.whl

logseq_matryca_parser/NOTICE

@@ -0,0 +1,7 @@
+Logseq Matryca Parser (Logos Protocol)
+Copyright 2026 Marco Porcellato & Matryca.ai
+
+Architect: Marco Porcellato
+Protocol Name: Logos
+This module provides deterministic parsing for the Matryca ecosystem.
+Released under Apache 2.0.

logseq_matryca_parser/__init__.py

@@ -0,0 +1,61 @@
+"""Public package exports for logseq_matryca_parser."""
+
+from __future__ import annotations
+
+import sys
+
+__version__ = "0.3.0"
+
+from .agent_writer import LogseqConfigReader, logseq_agent_write
+from .exceptions import BlockReferenceError, LogseqIndentationError, LogseqParserError
+from .forge import (
+    FlatListForgeVisitor,
+    ForgeExporter,
+    JSONForgeVisitor,
+    MarkdownForgeVisitor,
+    ObsidianForgeVisitor,
+)
+from .graph import LogseqGraph
+from .logos_core import ASTVisitor, LogseqNode, LogseqPage, LogosNode, SovereignNotePackage
+from .logos_parser import (
+    LOGSEQ_PATTERNS,
+    LogosParser,
+    PageRegistry,
+    StackMachineParser,
+    clean_node_content,
+    is_system_block,
+)
+
+
+def ensure_aot_compatibility() -> None:
+    """Best-effort runtime check for AOT-unsafe dynamic metadata imports."""
+    if "importlib.metadata" in sys.modules:
+        return
+
+
+__all__ = [
+    "__version__",
+    "ASTVisitor",
+    "BlockReferenceError",
+    "FlatListForgeVisitor",
+    "ForgeExporter",
+    "JSONForgeVisitor",
+    "LOGSEQ_PATTERNS",
+    "LogosNode",
+    "LogosParser",
+    "LogseqConfigReader",
+    "LogseqGraph",
+    "LogseqIndentationError",
+    "LogseqNode",
+    "LogseqPage",
+    "LogseqParserError",
+    "PageRegistry",
+    "SovereignNotePackage",
+    "StackMachineParser",
+    "clean_node_content",
+    "ensure_aot_compatibility",
+    "is_system_block",
+    "logseq_agent_write",
+    "MarkdownForgeVisitor",
+    "ObsidianForgeVisitor",
+]

logseq_matryca_parser/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running the CLI via ``python -m logseq_matryca_parser``."""
+
+from __future__ import annotations
+
+from logseq_matryca_parser.kinetic import app
+
+if __name__ == "__main__":
+    app(prog_name="matryca-parse")

logseq_matryca_parser/agent_press.py

@@ -0,0 +1,99 @@
+"""Agent-native "Printing Press" exports: UUID aliases and ultra-dense X-Ray AST text."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from logseq_matryca_parser.logos_core import LogseqNode
+
+logger = logging.getLogger(__name__)
+
+
+def _flatten_subtrees(nodes: list[LogseqNode]) -> list[LogseqNode]:
+    """Depth-first list of nodes under each root, preserving outline order."""
+    flat: list[LogseqNode] = []
+    seen: set[str] = set()
+
+    def walk(node: LogseqNode) -> None:
+        if node.uuid in seen:
+            return
+        seen.add(node.uuid)
+        flat.append(node)
+        for child in node.children:
+            walk(child)
+
+    for root in nodes:
+        walk(root)
+    return flat
+
+
+class SessionAliasRegistry:
+    """Maps sequential integer aliases to Logseq block UUIDs for a single agent session."""
+
+    def __init__(self) -> None:
+        self._alias_to_uuid: dict[int, str] = {}
+        self._uuid_to_alias: dict[str, int] = {}
+
+    def generate_aliases(self, nodes: list[LogseqNode]) -> dict[int, str]:
+        """Assign ``0..n-1`` to each unique node UUID (including nested children)."""
+        self._alias_to_uuid.clear()
+        self._uuid_to_alias.clear()
+        next_alias = 0
+        for node in _flatten_subtrees(nodes):
+            if node.uuid in self._uuid_to_alias:
+                continue
+            self._alias_to_uuid[next_alias] = node.uuid
+            self._uuid_to_alias[node.uuid] = next_alias
+            logger.debug("SessionAliasRegistry alias=%s uuid=%s", next_alias, node.uuid)
+            next_alias += 1
+        return dict(self._alias_to_uuid)
+
+    def resolve_alias(self, alias: int) -> str | None:
+        """Return the Logseq UUID for ``alias``, or ``None`` if unknown."""
+        return self._alias_to_uuid.get(alias)
+
+    def alias_for_uuid(self, node_uuid: str) -> int | None:
+        """Return the session alias for ``node_uuid``, or ``None`` if unregistered."""
+        return self._uuid_to_alias.get(node_uuid)
+
+    def save_to_disk(self, filepath: Path) -> None:
+        """Persist ``alias -> uuid`` mapping as JSON for cross-invocation state."""
+        payload = {str(alias): uuid for alias, uuid in self._alias_to_uuid.items()}
+        filepath.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+        logger.debug("SessionAliasRegistry saved %s aliases to %s", len(payload), filepath)
+
+    @classmethod
+    def load_from_disk(cls, filepath: Path) -> SessionAliasRegistry:
+        """Reconstruct a registry from a JSON file written by :meth:`save_to_disk`."""
+        raw = json.loads(filepath.read_text(encoding="utf-8"))
+        registry = cls()
+        for alias_str, node_uuid in raw.items():
+            alias = int(alias_str)
+            registry._alias_to_uuid[alias] = node_uuid
+            registry._uuid_to_alias[node_uuid] = alias
+        logger.debug("SessionAliasRegistry loaded %s aliases from %s", len(registry._alias_to_uuid), filepath)
+        return registry
+
+
+def to_xray_markdown(nodes: list[LogseqNode], registry: SessionAliasRegistry) -> str:
+    """Serialize outline topology as ``{indent}[{alias}] {clean_text}`` lines only."""
+    lines: list[str] = []
+
+    def emit(node: LogseqNode) -> None:
+        alias = registry.alias_for_uuid(node.uuid)
+        if alias is None:
+            logger.debug("to_xray_markdown skip unregistered uuid=%s", node.uuid)
+            return
+        indent = "  " * node.indent_level
+        text = node.clean_text.strip()
+        if text:
+            lines.append(f"{indent}[{alias}] {text}")
+        for child in node.children:
+            emit(child)
+
+    for root in nodes:
+        emit(root)
+
+    return "\n".join(lines)

logseq_matryca_parser/agent_writer.py

@@ -0,0 +1,250 @@
+"""Agent write helpers: weekly append-only logging and headless AST markdown splicing."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import tempfile
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, NotRequired, TypedDict
+
+if TYPE_CHECKING:
+    from logseq_matryca_parser.graph import LogseqGraph
+
+from logseq_matryca_parser.logos_core import LogseqNode
+
+logger = logging.getLogger(__name__)
+
+
+class AgentWriteResult(TypedDict):
+    """Structured result from :func:`logseq_agent_write`."""
+
+    status: str
+    path: NotRequired[str]
+    entry: NotRequired[str]
+    message: NotRequired[str]
+
+_DEFAULT_JOURNAL_FORMAT = "%Y-%m-%d"
+_JOURNAL_PAGE_TITLE_FORMAT_RE = re.compile(
+    r':journal/page-title-format\s+"([^"]*)"',
+)
+
+_ENGLISH_MONTH_ABBR: tuple[str, ...] = (
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+)
+_ENGLISH_MONTH_FULL: tuple[str, ...] = (
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+)
+
+
+class LogseqConfigReader:
+    """Load ``config.edn`` and translate Clojure/Java-style date tokens to Python ``strftime``."""
+
+    # Longest tokens first to avoid partial replacements (e.g. ``yyyy`` before ``yy``).
+    TOKEN_MAP: dict[str, str] = {
+        "yyyy": "%Y",
+        "yy": "%y",
+        "MMMM": "%B",
+        "MMM": "%b",
+        "MM": "%m",
+        "dd": "%d",
+        "HH": "%H",
+        "mm": "%M",
+        "ss": "%S",
+        "do": "{day_ordinal}",
+    }
+
+    def __init__(self, config_path: str) -> None:
+        self.config_path = config_path
+
+    def load_journal_format(self) -> str:
+        """Return ``:journal/page-title-format`` from ``config.edn``."""
+        try:
+            with open(self.config_path, encoding="utf-8") as f:
+                content = f.read()
+        except OSError as exc:
+            logger.warning("Could not read Logseq config at %s: %s", self.config_path, exc)
+            return _DEFAULT_JOURNAL_FORMAT
+
+        match = _JOURNAL_PAGE_TITLE_FORMAT_RE.search(content)
+        if match:
+            return match.group(1)
+        return _DEFAULT_JOURNAL_FORMAT
+
+    @staticmethod
+    def get_day_ordinal(day: int) -> str:
+        """Return English ordinal suffix (``st``, ``nd``, ``rd``, ``th``) for ``day``."""
+        if 11 <= day <= 13:
+            return "th"
+        suffixes = {1: "st", 2: "nd", 3: "rd"}
+        return suffixes.get(day % 10, "th")
+
+    def translate_to_python(self, clojure_format: str) -> str:
+        """Map Logseq/Java-style pattern letters to a Python ``strftime``-compatible string."""
+        py_format = clojure_format
+        for clojure_token, python_token in sorted(
+            self.TOKEN_MAP.items(),
+            key=lambda item: len(item[0]),
+            reverse=True,
+        ):
+            py_format = py_format.replace(clojure_token, python_token)
+        return py_format
+
+    def format_timestamp(self, dt: datetime) -> str:
+        """Format ``dt`` using the journal title format from config (including ordinal days)."""
+        clojure_format = self.load_journal_format()
+        py_format = self.translate_to_python(clojure_format)
+        # Force English month tokens so strftime does not follow the process locale (Logseq links).
+        if "%B" in py_format:
+            py_format = py_format.replace("%B", _ENGLISH_MONTH_FULL[dt.month - 1])
+        if "%b" in py_format:
+            py_format = py_format.replace("%b", _ENGLISH_MONTH_ABBR[dt.month - 1])
+        base_date = dt.strftime(py_format)
+        if "{day_ordinal}" in base_date:
+            suffix = self.get_day_ordinal(dt.day)
+            base_date = re.sub(r"\{day_ordinal\}", f"{dt.day}{suffix}", base_date)
+        return base_date
+
+
+def logseq_agent_write(
+    content: str,
+    config_path: str,
+    pages_dir: str,
+    context_tags: list[str] | None = None,
+) -> AgentWriteResult:
+    """Append a single Logseq-style block to the weekly agent page (append-only, sandbox-friendly)."""
+    now = datetime.now()
+    reader = LogseqConfigReader(config_path)
+    title = reader.format_timestamp(now)
+    timestamp_tag = f"[[{title}]]"
+    week_id = now.strftime("%Y-W%W")
+    filename = f"{week_id}-agent.md"
+    file_path = os.path.join(pages_dir, filename)
+
+    tag_links = "".join(f" [[{tag}]]" for tag in (context_tags or []))
+    block_lines = [f"- {timestamp_tag}{tag_links}"]
+    if content.strip():
+        block_lines.append(content.rstrip("\n"))
+    block_text = "\n".join(block_lines) + "\n"
+
+    try:
+        os.makedirs(pages_dir, exist_ok=True)
+        with open(file_path, mode="a", encoding="utf-8") as out:
+            out.write(block_text)
+    except OSError as exc:
+        logger.exception("logseq_agent_write failed for path %s", file_path)
+        return {"status": "error", "message": str(exc)}
+    return {"status": "success", "path": file_path}
+
+
+def _deepest_line_end(node: LogseqNode) -> int:
+    """Return the 1-based ``line_end`` of the deepest last descendant (or ``node`` itself)."""
+    cursor = node
+    while cursor.children:
+        cursor = cursor.children[-1]
+    if cursor.line_end is None:
+        msg = f"Node uuid={node.uuid} has no line_end for markdown splice"
+        raise ValueError(msg)
+    return cursor.line_end
+
+
+def append_child_to_node(graph: LogseqGraph, target_uuid: str, content: str) -> None:
+    """Insert a child bullet under ``target_uuid`` in the on-disk source markdown file."""
+    target_node = graph.get_node_by_uuid(target_uuid)
+    if target_node is None:
+        msg = f"No node registered for uuid={target_uuid}"
+        raise ValueError(msg)
+    if not target_node.source_path:
+        msg = f"Node uuid={target_uuid} has no source_path"
+        raise ValueError(msg)
+
+    source_path = Path(target_node.source_path)
+    insert_after_line = _deepest_line_end(target_node)
+    child_level = target_node.indent_level + 1
+    indent = " " * (child_level * graph.tab_size)
+    new_line = f"{indent}- {content.rstrip()}"
+
+    raw_text = source_path.read_text(encoding="utf-8")
+    lines = raw_text.splitlines(keepends=True)
+    insert_index = insert_after_line
+    if insert_index < 0 or insert_index > len(lines):
+        msg = (
+            f"Insertion index {insert_index} out of range for {source_path} "
+            f"(lines={len(lines)}, target line_end={insert_after_line})"
+        )
+        raise ValueError(msg)
+
+    lines.insert(insert_index, f"{new_line}\n")
+    updated = "".join(lines)
+    logger.debug(
+        "append_child_to_node target=%s path=%s insert_index=%s indent_level=%s",
+        target_uuid,
+        source_path,
+        insert_index,
+        child_level,
+    )
+
+    fd, temp_path = tempfile.mkstemp(
+        dir=source_path.parent,
+        prefix=f".{source_path.name}.",
+        suffix=".tmp",
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(updated)
+        os.replace(temp_path, source_path)
+    except OSError:
+        if os.path.exists(temp_path):
+            os.unlink(temp_path)
+        raise
+
+
+def _demo() -> None:
+    """Print a small table for manual checks (``python -m logseq_matryca_parser.agent_writer``)."""
+
+    class _MockConfigReader(LogseqConfigReader):
+        def load_journal_format(self) -> str:
+            return "MMM do, yyyy"
+
+    reader = _MockConfigReader("/path/to/config.edn")
+    test_dates = [
+        datetime(2026, 5, 1),
+        datetime(2026, 5, 2),
+        datetime(2026, 5, 3),
+        datetime(2026, 5, 11),
+        datetime(2026, 5, 22),
+    ]
+    print(f"{'Data Originale':<20} | {'Formato Logseq':<15} | {'Output Finale'}")
+    print("-" * 60)
+    for dt in test_dates:
+        fmt = reader.load_journal_format()
+        output = reader.format_timestamp(dt)
+        print(f"{dt.strftime('%Y-%m-%d'):<20} | {fmt:<15} | {output}")
+
+
+if __name__ == "__main__":
+    _demo()

logseq_matryca_parser/exceptions.py

@@ -0,0 +1,13 @@
+"""Domain-specific parser exceptions."""
+
+
+class LogseqParserError(Exception):
+    """Base exception for parser failures."""
+
+
+class LogseqIndentationError(LogseqParserError):
+    """Raised when indentation jumps violate stack-machine constraints."""
+
+
+class BlockReferenceError(LogseqParserError):
+    """Raised when a block reference cannot be resolved."""