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

logseq_matryca_parser/synapse.py

@@ -0,0 +1,329 @@
+"""SYNAPSE adapters implemented with AST visitors."""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from logseq_matryca_parser.logos_core import ASTVisitor, LogseqNode, LogseqPage
+from logseq_matryca_parser.logos_parser import LogosParser
+
+if TYPE_CHECKING:
+    from logseq_matryca_parser.graph import LogseqGraph
+
+logger = logging.getLogger(__name__)
+
+_BLOCK_EMBED_PATTERN = re.compile(
+    r"\{\{\s*embed\s+\(\((?P<uuid>[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\)\)\s*\}\}",
+    re.IGNORECASE,
+)
+_PAGE_EMBED_PATTERN = re.compile(r"\{\{\s*embed\s+\[\[(?P<title>[^\]]+)\]\]\s*\}\}")
+
+Document: type[Any] | None
+NodeRelationship: Any
+RelatedNodeInfo: type[Any] | None
+TextNode: type[Any] | None
+
+try:
+    from langchain_core.documents import Document  # type: ignore
+except ImportError:
+    Document = None
+
+try:
+    from llama_index.core.schema import (  # type: ignore
+        NodeRelationship,
+        RelatedNodeInfo,
+        TextNode,
+    )
+except ImportError:
+    NodeRelationship = None
+    RelatedNodeInfo = None
+    TextNode = None
+
+
+def _flatten_nodes_for_export(nodes: list[LogseqNode]) -> list[LogseqNode]:
+    """Depth-first flattening of a node tree (same order as graph indexing)."""
+    flat: list[LogseqNode] = []
+    for node in nodes:
+        flat.append(node)
+        if node.children:
+            flat.extend(_flatten_nodes_for_export(node.children))
+    return flat
+
+
+def _strip_markdown_for_embedding(text: str) -> str:
+    """Remove common markdown noise from breadcrumb fragments for embedding-friendly strings."""
+    s = text.strip()
+    s = re.sub(r"\[\[([^\]|]+)(?:\|[^\]]+)?\]\]", r"\1", s)
+    s = re.sub(r"\*\*([^*]+)\*\*", r"\1", s)
+    s = re.sub(r"(?<!\*)\*([^*]+)\*(?!\*)", r"\1", s)
+    s = re.sub(r"`([^`]+)`", r"\1", s)
+    s = re.sub(r"#([^\s#]+)", "", s)
+    s = re.sub(r"\s+", " ", s).strip()
+    return s
+
+
+def _expand_macros_and_embeds(text: str, graph: LogseqGraph, visited_uuids: set[str]) -> str:
+    """Expand ``{{embed ((uuid))}}`` / ``{{embed [[page]]}}`` for RAG text.
+
+    Operates on raw block ``content`` (not ``clean_text``) so ``((uuid))`` inside macros is
+    still visible to the scanner after parsing.
+    """
+    return _expand_macros_and_embeds_impl(text, graph, visited_uuids, set())
+
+
+def _expand_macros_and_embeds_impl(
+    text: str,
+    graph: LogseqGraph,
+    visited_uuids: set[str],
+    visited_pages: set[str],
+) -> str:
+    """Shared worker: ``visited_uuids`` breaks block cycles; ``visited_pages`` breaks page cycles."""
+    result = text
+    while True:
+        bm = _BLOCK_EMBED_PATTERN.search(result)
+        pm = _PAGE_EMBED_PATTERN.search(result)
+        if bm is None and pm is None:
+            break
+        use_block = bm is not None and (pm is None or bm.start() <= pm.start())
+        if use_block:
+            assert bm is not None
+            match = bm
+            uid = match.group("uuid")
+            if uid in visited_uuids:
+                logger.debug("Stack-Machine embed: cyclic block uuid=%s", uid)
+                replacement = ""
+            else:
+                target = graph.get_node_by_embed_ref(uid)
+                if target is None:
+                    logger.debug("Stack-Machine embed: unresolved block uuid=%s", uid)
+                    replacement = match.group(0)
+                else:
+                    next_seen = set(visited_uuids)
+                    next_seen.add(uid)
+                    replacement = _expand_macros_and_embeds_impl(
+                        target.content, graph, next_seen, visited_pages
+                    )
+            result = result[: match.start()] + replacement + result[match.end() :]
+        else:
+            assert pm is not None
+            match = pm
+            title = match.group("title").strip()
+            if title in visited_pages:
+                logger.debug("Stack-Machine embed: cyclic page title=%s", title)
+                replacement = ""
+            else:
+                page = graph.pages.get(title)
+                if page is None:
+                    logger.debug("Stack-Machine embed: unknown page title=%s", title)
+                    replacement = match.group(0)
+                else:
+                    visited_pages.add(title)
+                    try:
+                        shared_blocks = set(visited_uuids)
+                        pieces: list[str] = []
+                        for n in _flatten_nodes_for_export(page.root_nodes):
+                            frag = _expand_macros_and_embeds_impl(
+                                n.content, graph, shared_blocks, visited_pages
+                            )
+                            stripped = frag.strip()
+                            if stripped:
+                                pieces.append(stripped)
+                        replacement = "\n".join(pieces)
+                    finally:
+                        visited_pages.discard(title)
+            result = result[: match.start()] + replacement + result[match.end() :]
+    return result
+
+
+def _build_breadcrumbs(graph: LogseqGraph, node: LogseqNode) -> tuple[str, LogseqPage | None]:
+    """Build `Page > ancestor clean_text ...` using ``node.path`` and the graph registry."""
+    page = graph._page_for_node(node)
+    page_title = page.title if page is not None else ""
+    parts: list[str] = []
+    if page_title:
+        parts.append(_strip_markdown_for_embedding(page_title))
+    for ancestor_uuid in node.path[:-1]:
+        ancestor = graph.get_node_by_uuid(ancestor_uuid)
+        if ancestor is None:
+            continue
+        stripped = _strip_markdown_for_embedding(ancestor.clean_text)
+        if stripped:
+            parts.append(stripped)
+    return " > ".join(parts), page
+
+
+class LangChainVisitor(ASTVisitor):
+    """Build LangChain documents during AST traversal."""
+
+    def __init__(self, source_name: str, document_cls: type[Any]) -> None:
+        self._source_name = source_name
+        self._document_cls = document_cls
+        self._documents: list[Any] = []
+
+    def visit_node(self, node: LogseqNode) -> None:
+        metadata = {
+            **node.properties,
+            "uuid": node.uuid,
+            "parent_id": node.parent_id,
+            "indent_level": node.indent_level,
+            "source": self._source_name,
+            "path": node.path,
+            "left_id": node.left_id,
+            "refs": node.refs,
+            "task_status": node.task_status,
+            "repeater": node.repeater,
+            "created_at": node.created_at,
+        }
+        self._documents.append(
+            self._document_cls(
+                page_content=node.clean_text,
+                metadata=metadata,
+            )
+        )
+
+    def depart_node(self, node: LogseqNode) -> None:
+        _ = node
+
+    def get_documents(self) -> list[Any]:
+        return self._documents
+
+
+class LlamaIndexVisitor(ASTVisitor):
+    """Build LlamaIndex nodes and inject parent/child topology relationships."""
+
+    def __init__(
+        self,
+        text_node_cls: type[Any],
+        node_relationship: Any,
+        related_node_info_cls: type[Any],
+    ) -> None:
+        self._text_node_cls = text_node_cls
+        self._node_relationship = node_relationship
+        self._related_node_info_cls = related_node_info_cls
+        self._nodes_by_id: dict[str, Any] = {}
+        self._ordered_nodes: list[Any] = []
+
+    def visit_node(self, node: LogseqNode) -> None:
+        text_node = self._text_node_cls(
+            id_=node.uuid,
+            text=node.clean_text,
+            metadata={
+                **node.properties,
+                "uuid": node.uuid,
+                "indent_level": node.indent_level,
+                "path": node.path,
+                "left_id": node.left_id,
+                "refs": node.refs,
+                "task_status": node.task_status,
+                "repeater": node.repeater,
+                "created_at": node.created_at,
+            },
+        )
+        if not hasattr(text_node, "relationships") or text_node.relationships is None:
+            text_node.relationships = {}
+
+        if node.parent_id:
+            text_node.relationships[self._node_relationship.PARENT] = self._related_node_info_cls(
+                node_id=node.parent_id
+            )
+            parent_node = self._nodes_by_id.get(node.parent_id)
+            if parent_node is not None:
+                child_relationships = parent_node.relationships.get(
+                    self._node_relationship.CHILD, []
+                )
+                child_relationships.append(self._related_node_info_cls(node_id=node.uuid))
+                parent_node.relationships[self._node_relationship.CHILD] = child_relationships
+
+        self._nodes_by_id[node.uuid] = text_node
+        self._ordered_nodes.append(text_node)
+
+    def depart_node(self, node: LogseqNode) -> None:
+        _ = node
+
+    def get_nodes(self) -> list[Any]:
+        return self._ordered_nodes
+
+
+class SynapseAdapter:
+    """Transform Logseq hierarchy into framework-native AI objects."""
+
+    @staticmethod
+    def to_langchain_documents(nodes: list[LogseqNode], source_name: str) -> list[Any]:
+        """Convert AST nodes to LangChain documents using `LangChainVisitor`."""
+        if Document is None:
+            raise ImportError("LangChain non rilevato. Installa 'langchain-core' per usare Synapse.")
+        visitor = LangChainVisitor(source_name=source_name, document_cls=Document)
+        for node in nodes:
+            node.accept(visitor)
+        return visitor.get_documents()
+
+    @staticmethod
+    def to_llamaindex_nodes(nodes: list[LogseqNode]) -> list[Any]:
+        """Convert AST nodes to LlamaIndex nodes preserving topology links."""
+        if TextNode is None or NodeRelationship is None or RelatedNodeInfo is None:
+            raise ImportError("LlamaIndex non rilevato. Installa 'llama-index' per usare Synapse.")
+        visitor = LlamaIndexVisitor(
+            text_node_cls=TextNode,
+            node_relationship=NodeRelationship,
+            related_node_info_cls=RelatedNodeInfo,
+        )
+        for node in nodes:
+            node.accept(visitor)
+        return visitor.get_nodes()
+
+    @staticmethod
+    def to_context_enriched_chunks(
+        nodes: list[LogseqNode],
+        graph: LogseqGraph,
+        format_template: str = "[{breadcrumbs}] {content}",
+    ) -> list[Any]:
+        """Flatten ``nodes`` and emit LangChain ``Document``s with breadcrumb-enriched ``page_content``."""
+        if Document is None:
+            raise ImportError("LangChain non rilevato. Installa 'langchain-core' per usare Synapse.")
+        documents: list[Any] = []
+        flat = _flatten_nodes_for_export(nodes)
+        for node in flat:
+            breadcrumbs, page = _build_breadcrumbs(graph, node)
+            source_name = Path(node.source_path).name if node.source_path else str(graph.graph_path.name)
+            expanded_content = _expand_macros_and_embeds(node.content, graph, set())
+            page_content = format_template.format(
+                breadcrumbs=breadcrumbs,
+                content=expanded_content,
+            )
+            effective_properties = dict(graph.get_effective_properties(node.uuid))
+            metadata = {
+                **node.properties,
+                "uuid": node.uuid,
+                "parent_id": node.parent_id,
+                "indent_level": node.indent_level,
+                "source": source_name,
+                "path": node.path,
+                "left_id": node.left_id,
+                "refs": node.refs,
+                "task_status": node.task_status,
+                "repeater": node.repeater,
+                "created_at": node.created_at,
+                "clean_text": node.clean_text,
+                "page_title": page.title if page is not None else "",
+                "source_path": node.source_path,
+                "line_start": node.line_start,
+                "effective_properties": effective_properties,
+            }
+            documents.append(Document(page_content=page_content, metadata=metadata))
+            logger.debug(
+                "context chunk uuid=%s breadcrumbs_len=%s effective_keys=%s",
+                node.uuid,
+                len(breadcrumbs),
+                tuple(effective_properties.keys()),
+            )
+        return documents
+
+    @classmethod
+    def load_and_convert(cls, file_path: Path) -> list[Any]:
+        """Parse a file and convert it to LangChain documents."""
+        parser = LogosParser()
+        nodes = parser.parse_file(file_path)
+        return cls.to_langchain_documents(nodes, source_name=file_path.name)

logseq_matryca_parser-0.3.0.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: logseq-matryca-parser
+Version: 0.3.0
+Summary: The Logos Protocol: Deterministic Logseq AST parsing for Matryca.ai.
+Project-URL: Homepage, https://github.com/MarcoPorcellato/logseq-matryca-parser
+Project-URL: Bug Tracker, https://github.com/MarcoPorcellato/logseq-matryca-parser/issues
+Project-URL: Matryca.ai, https://matryca.ai
+Author-email: Marco Porcellato <marco@matryca.ai>
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai,ast,knowledge-graph,logseq,parser,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7.1
+Requires-Dist: typer>=0.12.0
+Provides-Extra: ai
+Requires-Dist: langchain-core; extra == 'ai'
+Requires-Dist: llama-index-core; extra == 'ai'
+Provides-Extra: all
+Requires-Dist: langchain-core; extra == 'all'
+Requires-Dist: llama-index-core; extra == 'all'
+Requires-Dist: networkx>=3.0.0; extra == 'all'
+Requires-Dist: pyvis>=0.3.2; extra == 'all'
+Provides-Extra: viz
+Requires-Dist: networkx>=3.0.0; extra == 'viz'
+Requires-Dist: pyvis>=0.3.2; extra == 'viz'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🔱 Logseq Matryca Parser (The Logos Protocol)
+
+**Stop feeding broken Markdown to your AI.**
+
+[![CI/CD Status](https://github.com/MarcoPorcellato/logseq-matryca-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/MarcoPorcellato/logseq-matryca-parser/actions)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/MarcoPorcellato/logseq-matryca-parser/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/badge/PyPI-install%20via%20GitHub-3775A9?logo=pypi&logoColor=white)](https://github.com/MarcoPorcellato/logseq-matryca-parser#-quickstart)
+[![Status: Alpha](https://img.shields.io/badge/Status-Alpha-orange?style=for-the-badge)](#)
+![Origin: Matryca.ai](https://img.shields.io/badge/Origin-Matryca.ai-gold?style=for-the-badge)
+
+> *Turning a forest of local plain-text files into a unified semantic powerhouse.*
+
+<p align="center">
+  <video src="https://github.com/user-attachments/assets/24f73c6d-3eca-4adb-8442-981f2ba4cccd" autoplay loop muted playsinline width="800"></video>
+</p>
+
+[👉 **TRY THE LIVE INTERACTIVE DEMO**](https://MarcoPorcellato.github.io/logseq-matryca-parser/)
+
+[📘 **READ THE ARCHITECTURE (LLM OS Vision)**](docs/ARCHITECTURE.md)
+
+</div>
+
+---
+
+## 🌐 The Vision: Virtual Centralization vs. Binary Lock-in
+
+The PKM (Personal Knowledge Management) world is currently forcing users to make a painful choice between **Data Longevity** and **AI Power**.
+
+* **Vanilla Logseq / Obsidian** is a "Forest" of decentralized Markdown files. It guarantees the Lindy effect (plain-text lasts forever) and perfect Git versioning, but standard AI chunkers treat it like a blender, destroying the outliner hierarchy.
+* **Tana** is a centralized "Tree". It offers incredible semantic power, but traps your brain in a proprietary cloud database.
+* **The new Logseq DB (SQLite)** aims for database speed, but at a huge cost: it locks your notes inside a binary `.db` file. You lose human-readable files, you lose line-by-line Git diffs, and you lose the immortality of plain-text.
+
+### 🔱 The Matryca Solution: The Best of Both Worlds
+**Logseq Matryca Parser** is the ultimate bridge. It allows you to **keep your sovereign, future-proof Markdown files**, while synthesizing a **Virtual Global Graph** in RAM at runtime.
+
+It acts as the strict **File System Driver** for your LLM OS. By using a deterministic Stack-Machine to parse your outliner topology, it feeds LangChain or LlamaIndex with the exact parent-child context of every single block.
+
+*You get the reasoning power of a centralized relational database, without sacrificing the plain-text soul of your Second Brain in Logseq.*
+
+---
+
+## ⚖️ The PKM Landscape
+
+| Feature | Vanilla Markdown | **Matryca Parser** | Logseq DB (SQLite) | Tana |
+| :--- | :--- | :--- | :--- | :--- |
+| **Data Format** | Plain-text (.md) | **Plain-text (.md)** | Binary (.db) | Proprietary Cloud |
+| **Version Control** | Perfect (Git) | **Perfect (Git)** | Poor (Binary blob) | None |
+| **Data Structure** | Decentralized Forest | **Virtually Centralized Graph** | Relational Database | Centralized Tree |
+| **AI Readiness** | Low (Linear Chunks) | **High (Topological AST)** | TBD (Requires SQL) | High (Proprietary) |
+| **Sovereignty** | 100% Local | **100% Local (Sovereign AI)** | 100% Local | Cloud-Only |
+
+---
+
+## 🧭 Matryca vs. naive framework loaders
+
+| Capability | Typical LangChain / LlamaIndex Markdown loaders | **Matryca (LOGOS + SYNAPSE + graph)** |
+| :--- | :--- | :--- |
+| **Parent–child context** | Character or heading splits; children often orphaned from parents | **True outliner AST**: every block carries `parent_id`, `path`, `left_id` and visits in deterministic tree order |
+| **Block references `((uuid))`** | Treated as opaque text or dropped | **Resolved** against `LogseqGraph`; optional **embed expansion** and **Obsidian `[[Page#^anchor]]`** export |
+| **Property inheritance** | Page-level frontmatter at best | **`get_effective_properties`**: page + ancestor outline keys merged top-down (Org-mode style), then exposed on enriched chunks |
+| **Live sync** | Re-read whole tree or poll | **`LogseqGraph.start_watching()`** (optional `watchdog`): **per-file invalidation** — re-parse one page, purge stale UUIDs from registries, refresh backlinks |
+
+---
+
+### 🚀 The Problem
+Standard RAG pipelines treat your notes like a blender. They chop Markdown into random shards, destroying the **parent-child hierarchy** that makes Logseq powerful.
+
+```mermaid
+graph TD
+    Raw[(Logseq Markdown\nFiles)]
+
+    subgraph Standard RAG
+        Blender[Standard Text Splitter\n'The Blender']
+        Chunk1[Chunk 1: Orphan text]
+        Chunk2[Chunk 2: Lost context]
+        Blender --> Chunk1 & Chunk2
+    end
+
+    subgraph Matryca Parser
+        Architect[Logos Engine\nStack-Machine]
+        Parent[Parent Node\n+ Properties]
+        Child[Child Node\n+ Task State & Time]
+        Architect --> Parent --> Child
+    end
+
+    Raw --> Blender
+    Raw --> Architect
+
+    classDef bad fill:#fee2e2,stroke:#ef4444,color:#000;
+    classDef good fill:#dcfce7,stroke:#22c55e,color:#000;
+    class Chunk1,Chunk2 bad;
+    class Parent,Child good;
+```
+
+### 🔱 The Solution
+Logseq Matryca Parser is a deterministic **Stack-Machine engine** that acts as the **File System Driver** for your LLM. It preserves the true topology of your thoughts, ensuring AI understands spatial hierarchy, time, and block-lineage—including **structured task state** and **first-class temporal attributes** you can query in downstream graph databases and GraphRAG engines without re-parsing raw Markdown.
+
+---
+
+## ⚡ Recent superpowers (Waves 4–11)
+
+### Obsidian-native export
+Compile an entire Logseq graph into an **Obsidian vault layout**: YAML frontmatter from page properties, list body preserved, Logseq `((uuid))` links rewritten to **`[[Page#^anchor]]`**, and trailing **`^block-id`** on referenced blocks. Namespace titles become nested folders (e.g. `Projects/AI/Demo.md`).
+
+```bash
+matryca-parse export /path/to/logseq/graph /path/to/obsidian/vault --format obsidian
+```
+
+> **Note:** Wikilinks currently use the **Logseq page title** (e.g. `[[Target#^…]]`). Vault files may live under namespace folders (`Projects/AI/Demo.md`). Obsidian usually resolves unique titles; aligning link text to folder paths is a possible future refinement.
+
+### Live incremental watcher
+`LogseqGraph` supports **surgical file invalidation** (optional dependency: `pip install 'logseq-matryca-parser[watch]'`). `start_watching()` runs a recursive **watchdog** observer: on `created` / `modified` under `pages/` or `journals/`, only that file is re-parsed; stale synthetic UUIDs are purged from `_node_registry` and scrubbed from `_backlink_registry`—no full-graph cold reload.
+
+### Fluent topological queries
+Filter the global node registry with a **chainable** API (tags, task state, ancestry under a parent UUID):
+
+```python
+from logseq_matryca_parser.graph import LogseqGraph
+
+graph = LogseqGraph.load_directory("/path/to/logseq/graph")
+hits = (
+    graph.query()
+    .has_tag("idea")
+    .under_parent("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")
+    .is_task_state("TODO")
+    .execute()
+)
+```
+
+### Agent-Native X-Ray Mode (Token Optimization)
+For autonomous LLM agents, passing raw Markdown into the context window wastes thousands of tokens on **36-character UUIDs**, hidden `id::` properties, drawers, and collapsed directives that carry no immediate semantic signal. **X-Ray mode** compresses the parsed AST into **ultra-dense, zero-fluff plain text**: each block becomes `{indent}[{alias}] {clean_text}`, with heavy Logseq UUIDs replaced by **sequential integer aliases** (`[0]`, `[1]`, …) held in a session registry. On typical outlines this can reduce context consumption by **up to ~35×** compared to dumping full block payloads.
+
+```bash
+matryca-parse agent-read /path/to/graph --tag idea
+matryca-parse agent-read /path/to/graph --query "quantum"
+```
+
+The agent reads cheap topology now; the registry resolves aliases back to sovereign UUIDs when you wire targeted writes.
+
+---
+
+## 🏗️ Core Capabilities
+
+| Feature | Description |
+| :--- | :--- |
+| **LOGOS Engine** | Deterministic AST parsing. No regex-guessing. Handles `id::`, aliases, and multiline blocks. |
+| **Advanced Task Extraction** | Task **state** (TODO / DOING / …), **priority** markers `[#A]`–`[#C]` promoted to `task_priority`, and **SCHEDULED** / **DEADLINE** Logseq timestamps normalized to **UTC Unix epoch seconds** on `scheduled_at` / `deadline_at` for temporal graph and retrieval pipelines. |
+| **SYNAPSE Adapter** | Native exports for **LangChain** and **LlamaIndex** with automated lineage metadata; **context-enriched** chunks with breadcrumbs, embed expansion, and inherited properties. |
+| **FORGE** | JSON, clean Markdown, and **Obsidian** vault serialization (`ObsidianForgeVisitor`, `ForgeExporter.to_obsidian_markdown`). |
+| **LENS Visualizer** | 60FPS interactive graph rendering (10k+ nodes) with Glassmorphism HUD. |
+| **Agent-Native Printing Press** | [`agent_press.py`](src/logseq_matryca_parser/agent_press.py): **`SessionAliasRegistry`** maps session aliases ↔ block UUIDs; **`to_xray_markdown`** emits token-minimal outline text for autonomous agents (`matryca-parse agent-read`). |
+| **Sovereign AI** | 100% Local. Zero telemetry. Private by design. |
+
+### Data model — `LogseqNode` task fields
+
+Each AST block is a `LogseqNode`. Alongside `task_status`, the parser surfaces priority and schedule metadata as typed fields (epoch integers are **seconds since Unix epoch, UTC**):
+
+```json
+{
+  "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+  "task_status": "TODO",
+  "task_priority": "A",
+  "scheduled_at": 1641600000,
+  "deadline_at": 1641772800,
+  "clean_text": "Cut v0.3.0 release"
+}
+```
+
+Marker syntax (`[#A]`, `SCHEDULED: <...>`, `DEADLINE: <...>`) is stripped from `clean_text` so embeddings stay clean; the promoted fields carry the structured signal for downstream graph databases and GraphRAG engines.
+
+---
+
+## 🛠️ Quickstart
+
+```bash
+# Install from GitHub (PyPI distribution tracked on roadmap)
+pip install git+https://github.com/MarcoPorcellato/logseq-matryca-parser.git
+
+# Optional: filesystem watcher for live incremental graph updates
+pip install 'logseq-matryca-parser[watch]'
+
+# 1. Visualize your local graph (LENS)
+matryca-parse visualize /path/to/logseq/graph my-map.html
+
+# 2. Export for AI / RAG (SYNAPSE)
+matryca-parse export /path/to/logseq/graph output --format langchain
+
+# 3. Context-enriched LangChain JSON (graph + inheritance + embed expansion)
+matryca-parse export /path/to/logseq/graph output --format langchain-enriched
+
+# 4. Obsidian vault (YAML frontmatter + ^ block ids)
+matryca-parse export /path/to/logseq/graph output --format obsidian
+```
+
+### Python API
+```python
+from logseq_matryca_parser.logos_parser import LogosParser
+from logseq_matryca_parser.synapse import SynapseAdapter
+
+# Parse to AST
+page = LogosParser().parse_page_file("page.md")
+
+# Export to LangChain with lineage metadata
+docs = SynapseAdapter.to_langchain_documents(page.root_nodes, source_name=page.title)
+```
+
+### 🤖 Agentic Write Access (Append-Only)
+
+Agents such as Hermes or OpenClaw can record structured notes into a Logseq graph **without rewriting existing pages**. The helper `logseq_agent_write` only **opens the weekly agent page in append mode** (`"a"`), writes a new bullet (journal link + optional tag links + body), and never truncates or replaces prior content—so routine logging cannot wipe blocks that already live in that file.
+
+Point it at your graph’s **`pages`** directory and **`config.edn`** so journal titles match Logseq’s `:journal/page-title-format` (including ordinal days when you use `do` in the pattern).
+
+```python
+from logseq_matryca_parser import logseq_agent_write
+
+result = logseq_agent_write(
+    "Summarized user intent and proposed next steps.",
+    config_path="/path/to/logseq/config.edn",
+    pages_dir="/path/to/logseq/pages",
+    context_tags=["agent/hermes", "#session"],
+)
+assert result["status"] == "success"
+# result["path"] → e.g. .../pages/2026-18-agent.md
+```
+---
+
+## 🗺️ Roadmap
+- [ ] **Desktop GUI:** Standalone app for non-technical users. [(Join the RFC)](https://github.com/MarcoPorcellato/logseq-matryca-parser/issues/3)
+- [x] **Obsidian Adapter:** Native CLI export (`--format obsidian`) with YAML frontmatter and `^` block anchors.
+- [ ] **Ollama Integration:** One-click local RAG setup.
+
+## ☕ Support & Enterprise
+Logseq Matryca Parser is open-source. If it powers your pipeline, consider a star ⭐ or a sponsorship!
+
+**💖 [Sponsor me on GitHub](https://github.com/sponsors/MarcoPorcellato)**
+
+Need custom RAG integrations or consulting? Contact: [marco@marcoporcellato.it](mailto:marco@marcoporcellato.it)
+
+---
+Architected by **Marco Porcellato** | Powered by **Matryca.ai**

logseq_matryca_parser-0.3.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+logseq_matryca_parser/.gitignore,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+logseq_matryca_parser/NOTICE,sha256=maIqe2nNKdNAhLqgjIbO4Xa86EpLKqQwFiOgSze3ewY,230
+logseq_matryca_parser/__init__.py,sha256=yhAqWJMb-Dy62e_mBDYljqALTg3k5SXSCpyxGYGfGU0,1463
+logseq_matryca_parser/__main__.py,sha256=L_hCPkZR0DWIqEka-hrolxdjAczy5AbbUyAe3DIMh60,215
+logseq_matryca_parser/agent_press.py,sha256=LG_RIHBCaY6GG-4Q4jgemb4hiLtxC6q4W_zjcOJQb6s,3722
+logseq_matryca_parser/agent_writer.py,sha256=gDWYmmqjFpar_Iziq3gormj0MRrJraz27SD6rO3mODI,8000
+logseq_matryca_parser/exceptions.py,sha256=7RhkTwkcLT10YLPciD7ZJCnrRC2CZ776ZiZUhRAsWPY,359
+logseq_matryca_parser/forge.py,sha256=F-FCRrfTnm2o_z5LSDzHEBF9Vrnmypk1uXssyMOBpEY,13948
+logseq_matryca_parser/graph.py,sha256=oxnqRJjC-Tkrz_YJHrlyD2cqo0-Mgii0IBIrvBfeS7w,19433
+logseq_matryca_parser/kinetic.py,sha256=jFF_6ddjvQ0UDTSa7YwaUcPM3qfxnyBlE1TSmaRuMlY,19256
+logseq_matryca_parser/lens.py,sha256=2euDU4xU5OJglaeqzKhP9SdKyKZn5h9wyl3YmLULKQ4,16061
+logseq_matryca_parser/logos_core.py,sha256=WUR4ecFyrrvfdCu0V7NESHEL14ZXRdbfegsWYWxT5c4,5896
+logseq_matryca_parser/logos_parser.py,sha256=yRuec3Q6Rdh0OO0R7r8AQiCDdDLu98q_CnucoeMMnsU,40814
+logseq_matryca_parser/pyproject.toml,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+logseq_matryca_parser/synapse.py,sha256=N5N6iVv-7s5rsRW9cOaWPB904tLRSjGSVhXwZQXQoZs,12632
+logseq_matryca_parser-0.3.0.dist-info/METADATA,sha256=Slt5KLj-Pn5I_3882tyGFIwGGkJfS6FztemxkAsO1i8,14430
+logseq_matryca_parser-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+logseq_matryca_parser-0.3.0.dist-info/entry_points.txt,sha256=wQfdsO_DVmG_RIh9oBMv40OIV9nQ_tZaq_w2CAz6Vus,68
+logseq_matryca_parser-0.3.0.dist-info/licenses/LICENSE,sha256=E_Dz4jVCe2JdJH6VkLe7pKrCIr9mifszSIv1usGyLJ0,11334
+logseq_matryca_parser-0.3.0.dist-info/licenses/NOTICE,sha256=maIqe2nNKdNAhLqgjIbO4Xa86EpLKqQwFiOgSze3ewY,230
+logseq_matryca_parser-0.3.0.dist-info/RECORD,,

logseq_matryca_parser-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

logseq_matryca_parser-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+matryca-parse = logseq_matryca_parser.kinetic:app