maggraph 0.2.5__cp39-abi3-win_amd64.whl

maggraph/__init__.py

@@ -0,0 +1,53 @@
+"""MagGraph — Python bindings for the Rust graph engine."""
+
+from maggraph._maggraph import (
+    GraphIndex,
+    LakehouseReader,
+    MagGraphError,
+    Node,
+    NodeWithContent,
+    ResolvedConfig,
+    ResolvedContent,
+    TraversalNode,
+    TraversalResult,
+    load_config,
+    open_index,
+)
+
+async def _graph_read_node_async(self: GraphIndex, node_id: str) -> Node:
+    return self.read_node(node_id)
+
+
+async def _graph_traverse_async(
+    self: GraphIndex, from_id: str, depth: int = 2, order: str = "bfs"
+) -> TraversalResult:
+    return self.traverse(from_id, depth, order)
+
+
+async def _lakehouse_read_node_async(
+    self: LakehouseReader, index: GraphIndex, node_id: str
+) -> NodeWithContent:
+    return self.read_node(index, node_id)
+
+
+# Keep async convenience methods on the Python side so they follow Python 3.14
+# asyncio semantics while reusing the Rust sync methods as the source of truth.
+GraphIndex.read_node_async = _graph_read_node_async
+GraphIndex.traverse_async = _graph_traverse_async
+LakehouseReader.read_node_async = _lakehouse_read_node_async
+
+__all__ = [
+    "GraphIndex",
+    "LakehouseReader",
+    "MagGraphError",
+    "Node",
+    "NodeWithContent",
+    "ResolvedConfig",
+    "ResolvedContent",
+    "TraversalNode",
+    "TraversalResult",
+    "load_config",
+    "open_index",
+]
+
+__version__ = "0.2.5"

maggraph/__init__.pyi

@@ -0,0 +1,205 @@
+from typing import Awaitable, Literal, Optional, TypedDict
+
+class SearchResult(TypedDict):
+    id: str
+    type: str
+    relative_path: str
+    score: int
+    matched: list[str]
+    summary: str
+    modified_unix: Optional[int]
+
+class GraphChange(TypedDict):
+    id: str
+    relative_path: str
+    modified_unix: int
+
+class RecallBundle(TypedDict):
+    id: str
+    type: str
+    summary: str
+    body_excerpt: str
+    links: list[str]
+    backlinks: list[str]
+    metadata: dict[str, object]
+    relevance_reason: str
+    markdown: str
+
+class MagGraphError(Exception): ...
+
+class ResolvedConfig:
+    @property
+    def root_path(self) -> str: ...
+    @property
+    def config_path(self) -> str: ...
+    @property
+    def storage_mode(self) -> Literal["local", "lakehouse"]: ...
+    def open_index(self) -> GraphIndex: ...
+    def open_lakehouse_reader(self) -> LakehouseReader: ...
+
+class GraphIndex:
+    @classmethod
+    def open(cls, root_path: str) -> GraphIndex: ...
+    @property
+    def root_path(self) -> str: ...
+    def __len__(self) -> int: ...
+    def list_nodes(self) -> list[str]: ...
+    def read_node(self, node_id: str) -> Node: ...
+    def search(
+        self,
+        query: str = "",
+        node_type: str | None = None,
+        tags: list[str] | None = None,
+        include_suppressed: bool = False,
+        limit: int = 50,
+        modified_since_unix: int | None = None,
+    ) -> list[SearchResult]: ...
+    def backlinks(self, node_id: str) -> list[str]: ...
+    def changed_since(self, since_unix: int) -> list[GraphChange]: ...
+    def update_file(self, path: str) -> Optional[str]: ...
+    def read_node_async(self, node_id: str) -> Awaitable[Node]: ...
+    def create_node(
+        self,
+        node_id: str,
+        node_type: str = "note",
+        body: str = "",
+        links: list[str] | None = None,
+    ) -> Node: ...
+    def create_memory_node(
+        self,
+        node_id: str,
+        kind: Literal[
+            "preference",
+            "project_fact",
+            "decision",
+            "task",
+            "session_summary",
+            "bookmark",
+            "tool_failure",
+        ],
+        body: str = "",
+        links: list[str] | None = None,
+    ) -> Node: ...
+    def update_node(self, node_id: str, body: str) -> None: ...
+    def delete_node(self, node_id: str) -> None: ...
+    def suppress_node(self, node_id: str, reason: str | None = None) -> None: ...
+    def unsuppress_node(self, node_id: str) -> None: ...
+    def merge_nodes(self, target_id: str, source_id: str) -> None: ...
+    def recall_bundle(
+        self, node_id: str, reason: str = "", body_chars: int = 1200
+    ) -> RecallBundle: ...
+    def traverse(
+        self,
+        from_id: str,
+        depth: int = 2,
+        order: Literal["bfs", "dfs"] = "bfs",
+    ) -> TraversalResult: ...
+    def traverse_async(
+        self,
+        from_id: str,
+        depth: int = 2,
+        order: Literal["bfs", "dfs"] = "bfs",
+    ) -> Awaitable[TraversalResult]: ...
+    def read_node_with_content(
+        self, reader: LakehouseReader, node_id: str
+    ) -> NodeWithContent: ...
+
+class Node:
+    @property
+    def id(self) -> str: ...
+    @property
+    def node_type(self) -> str: ...
+    @property
+    def source(self) -> Optional[str]: ...
+    @property
+    def links(self) -> list[str]: ...
+    @property
+    def body(self) -> str: ...
+    @property
+    def relative_path(self) -> str: ...
+    def to_markdown(self) -> str: ...
+    def to_dict(self) -> dict[str, object]: ...
+
+class TraversalNode:
+    @property
+    def id(self) -> str: ...
+    @property
+    def depth(self) -> int: ...
+    @property
+    def path(self) -> list[str]: ...
+
+class TraversalResult:
+    @property
+    def start(self) -> str: ...
+    @property
+    def max_depth(self) -> int: ...
+    @property
+    def order(self) -> str: ...
+    @property
+    def nodes(self) -> list[TraversalNode]: ...
+    def to_markdown(self, index: GraphIndex) -> str: ...
+
+class ResolvedContent:
+    """Content resolved from a node source — local markdown or an external asset.
+
+    Check ``.kind`` to determine how to interpret the other attributes:
+
+    * ``"local"``          — ``.body`` is the markdown, ``.uri`` / ``.format`` are ``None``
+    * ``"text"``           — ``.uri`` and ``.body`` are set, ``.format`` is ``None``
+    * ``"external_asset"`` — ``.uri`` and ``.format`` are set, ``.body`` is ``None``
+    """
+    @property
+    def kind(self) -> Literal["local", "text", "external_asset"]: ...
+    @property
+    def body(self) -> Optional[str]: ...
+    """Markdown body (``"local"`` and ``"text"`` only; ``None`` for external assets)."""
+    @property
+    def uri(self) -> Optional[str]: ...
+    """External URI (``"text"`` and ``"external_asset"`` only)."""
+    @property
+    def format(self) -> Optional[str]: ...
+    """Detected format, e.g. ``"parquet"`` (``"external_asset"`` only)."""
+    @property
+    def size_bytes(self) -> Optional[int]: ...
+    """Size in bytes of the external asset, if known."""
+    @property
+    def parquet_magic_valid(self) -> Optional[bool]: ...
+    """Whether the PAR1 magic header is valid (Parquet assets only)."""
+    @property
+    def snippet(self) -> Optional[str]: ...
+    """Optional text snippet for external assets."""
+    def to_markdown(self) -> str: ...
+    """Markdown-friendly summary for agent consumption."""
+
+class NodeWithContent:
+    """A graph node paired with its resolved external content."""
+    @property
+    def node(self) -> Node: ...
+    @property
+    def content(self) -> ResolvedContent: ...
+
+class LakehouseReader:
+    """Resolves node content according to the configured storage mode.
+
+    Construct via :meth:`ResolvedConfig.open_lakehouse_reader`.
+
+    Example::
+
+        config = maggraph.load_config("maggraph.toml")
+        index  = config.open_index()
+        reader = config.open_lakehouse_reader()
+
+        result = reader.read_node(index, "my_asset")
+        print(result.content.to_markdown())
+    """
+    def read_node(self, index: GraphIndex, node_id: str) -> NodeWithContent: ...
+    def read_node_async(
+        self, index: GraphIndex, node_id: str
+    ) -> Awaitable[NodeWithContent]: ...
+    def cache_len(self) -> int: ...
+    """Number of entries in the in-memory content cache."""
+    def cache_bytes(self) -> int: ...
+    """Total bytes currently held in the cache."""
+
+def load_config(path: str) -> ResolvedConfig: ...
+def open_index(root_path: str) -> GraphIndex: ...

maggraph-0.2.5.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: maggraph
+Version: 0.2.5
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
+Requires-Dist: maturin>=1.7 ; extra == 'dev'
+Provides-Extra: dev
+Summary: In-process graph engine for AI semantic layers — powered by Rust
+Keywords: graph,knowledge-graph,agent,ai,mcp,lakehouse,rust
+Author-email: Alex Merced <alexmercedcoder@gmail.com>
+License: MIT OR Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/AlexMercedCoder/MagGraph/blob/main/planning/PROGRESS.md
+Project-URL: Documentation, https://github.com/AlexMercedCoder/MagGraph/tree/main/planning
+Project-URL: Homepage, https://github.com/AlexMercedCoder/MagGraph
+Project-URL: Issue Tracker, https://github.com/AlexMercedCoder/MagGraph/issues
+Project-URL: Repository, https://github.com/AlexMercedCoder/MagGraph
+
+# MagGraph
+
+**In-process Git-backed graph engine for AI semantic layers — powered by Rust**
+
+[![CI](https://github.com/AlexMercedCoder/MagGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexMercedCoder/MagGraph/actions)
+[![PyPI](https://img.shields.io/pypi/v/maggraph)](https://pypi.org/project/maggraph/)
+[![Python](https://img.shields.io/pypi/pyversions/maggraph)](https://pypi.org/project/maggraph/)
+[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](https://github.com/AlexMercedCoder/MagGraph)
+
+> **Why "MagGraph"?** The name is short for **Magpie** — a Corvid. Corvids (ravens,
+> crows, jays, and magpies) are renowned in animal cognition research for their
+> remarkable intelligence, long-term memory, and sophisticated tool use.
+> MagGraph is built to be the memory and knowledge layer for AI agents with those
+> same qualities: a graph that thinks, remembers, and uses tools.
+
+MagGraph stores knowledge as versioned Markdown nodes in your Git repository,
+with BFS/DFS traversal, Git-backed sync, external lakehouse content resolution,
+and a built-in MCP server scaffold — all from a zero-dependency `pip install`.
+
+---
+
+## Install
+
+```bash
+pip install maggraph
+```
+
+Pre-built wheels are available for:
+
+| Platform | Architectures |
+|----------|---------------|
+| Linux (manylinux_2_28) | x86\_64 · aarch64 |
+| macOS | Intel (x86\_64) · Apple Silicon (arm64) |
+| Windows | x86\_64 |
+
+> **No Rust toolchain required** — the Rust core is compiled into the wheel.
+
+---
+
+## Quick start
+
+```python
+import maggraph
+
+# Load config + open the graph index
+config = maggraph.load_config("maggraph.toml")
+index  = config.open_index()
+
+# List nodes
+print(index.list_nodes())          # ['getting_started', 'welcome', ...]
+
+# Read a node
+node = index.read_node("welcome")
+print(node.body)                   # full markdown body
+
+# Search, backlinks, and recall
+print(index.search("Welcome")[0]["id"])
+print(index.backlinks("welcome"))
+bundle = index.recall_bundle("welcome", reason="quick start")
+print(bundle["markdown"])
+
+# BFS traversal
+result = index.traverse("welcome", depth=2, order="bfs")
+print(result.to_markdown(index))   # formatted traversal report
+
+# CRUD and memory helpers
+index.create_memory_node("prefers_cli", "preference", "User prefers CLI-first UX.")
+index.create_node("new_note", node_type="note", body="# Hi\n", links=["welcome"])
+index.update_node("new_note", "# Updated\n")
+index.suppress_node("new_note", reason="example")
+index.unsuppress_node("new_note")
+index.delete_node("new_note")
+```
+
+---
+
+## Async support
+
+```python
+import asyncio, maggraph
+
+async def main():
+    index = maggraph.open_index("examples/basic/knowledge_graph")
+    node  = await index.read_node_async("welcome")
+    result = await index.traverse_async("welcome", depth=3, order="dfs")
+    print(result.to_markdown(index))
+
+asyncio.run(main())
+```
+
+Blocking Rust work runs on a Tokio thread pool — Python's event loop stays responsive.
+
+---
+
+## Lakehouse content resolution
+
+Resolve external data sources (S3, file://, HTTP) referenced from node frontmatter:
+
+```python
+import maggraph
+
+config = maggraph.load_config("maggraph.toml")  # mode = "lakehouse"
+index  = config.open_index()
+reader = config.open_lakehouse_reader()
+
+# Resolve a node's external source (e.g. s3://bucket/data.parquet)
+result = reader.read_node(index, "customer_churn_q2")
+print(result.content.kind)          # "external_asset"
+print(result.content.uri)           # "s3://corp-data/lake/churn.parquet"
+print(result.content.format)        # "parquet"
+print(result.content.to_markdown()) # agent-friendly summary
+
+# Cache stats
+print(reader.cache_len())    # 1
+print(reader.cache_bytes())  # ~128
+
+# Also callable directly on the index
+result2 = index.read_node_with_content(reader, "customer_churn_q2")
+```
+
+**`maggraph.toml`** for lakehouse mode:
+
+```toml
+[storage]
+mode = "lakehouse"
+root_path = "./knowledge_graph"
+
+[lakehouse]
+remote_sources = [
+  { uri = "s3://corp-data/lake", format = "parquet" }
+]
+```
+
+---
+
+## MCP server scaffold
+
+```bash
+maggraph scaffold --mcp --output ./mcp_server
+```
+
+Generates a ready-to-run FastMCP server at `./mcp_server/server.py` wired to
+your graph index — expose `list_nodes`, `read_node`, `traverse`, `create_node`,
+and `delete_node` as MCP tools with one command.
+
+---
+
+## Git-backed sync
+
+```bash
+# Leader pushes a snapshot
+maggraph sync push --message "Add Q2 analysis nodes"
+
+# Follower (read-only) pulls
+maggraph sync pull
+```
+
+---
+
+## API reference
+
+| Class / Function | Description |
+|-----------------|-------------|
+| `load_config(path)` | Load `maggraph.toml` → `ResolvedConfig` |
+| `open_index(root_path)` | Open graph index directly → `GraphIndex` |
+| `ResolvedConfig.open_index()` | Open index from config |
+| `ResolvedConfig.open_lakehouse_reader()` | Create a `LakehouseReader` |
+| `GraphIndex.list_nodes()` | All node ids (sorted) |
+| `GraphIndex.read_node(id)` | `Node` with metadata + body |
+| `GraphIndex.search(...)` | Structured search over ids, types, tags, frontmatter, links, body, and recency |
+| `GraphIndex.backlinks(id)` | Node ids that link to `id` |
+| `GraphIndex.changed_since(unix)` | Files modified after a Unix timestamp |
+| `GraphIndex.update_file(path)` | Refresh one changed markdown file in the index |
+| `GraphIndex.recall_bundle(id, ...)` | Compact agent retrieval dict with Markdown |
+| `GraphIndex.read_node_async(id)` | Async version |
+| `GraphIndex.traverse(id, depth, order)` | BFS/DFS → `TraversalResult` |
+| `GraphIndex.traverse_async(...)` | Async version |
+| `GraphIndex.create_node(...)` | Write new node to disk + index |
+| `GraphIndex.create_memory_node(...)` | Create typed memory nodes (`preference`, `project_fact`, `decision`, `task`, `session_summary`, `bookmark`, `tool_failure`) |
+| `GraphIndex.update_node(id, body)` | Update body on disk |
+| `GraphIndex.delete_node(id)` | Delete node from disk + index |
+| `GraphIndex.suppress_node(id)` / `unsuppress_node(id)` | Mark/unmark stale or duplicate nodes |
+| `GraphIndex.merge_nodes(target, source)` | Merge duplicate source into canonical target |
+| `GraphIndex.read_node_with_content(reader, id)` | Resolve external content |
+| `LakehouseReader.read_node(index, id)` | → `NodeWithContent` |
+| `LakehouseReader.read_node_async(index, id)` | Async version |
+| `LakehouseReader.cache_len()` | Entries in content cache |
+| `LakehouseReader.cache_bytes()` | Bytes in content cache |
+| `Node.id / .node_type / .body / .links / .source` | Node properties |
+| `Node.to_markdown()` | Full node as Markdown string |
+| `Node.to_dict()` | Node as plain Python dict |
+| `ResolvedContent.kind` | `"local"` / `"text"` / `"external_asset"` |
+| `ResolvedContent.body / .uri / .format` | Content details |
+| `ResolvedContent.to_markdown()` | Agent-friendly summary |
+| `NodeWithContent.node / .content` | Node + resolved content |
+
+---
+
+## Links
+
+- [GitHub](https://github.com/AlexMercedCoder/MagGraph)
+- [Architecture & planning docs](https://github.com/AlexMercedCoder/MagGraph/tree/main/planning)
+- [Examples](https://github.com/AlexMercedCoder/MagGraph/tree/main/examples)
+- [CONTRIBUTING.md](https://github.com/AlexMercedCoder/MagGraph/blob/main/CONTRIBUTING.md)
+
+---
+
+## License
+
+MIT OR Apache-2.0
+

maggraph-0.2.5.dist-info/RECORD

@@ -0,0 +1,8 @@
+maggraph/__init__.py,sha256=2bzbIbAF3Jdih7wP6zbpytJ1sAVEhoIklLjRshfU0_c,1386
+maggraph/__init__.pyi,sha256=Q6xSgvVNmvD1jtyMpm577qywuBYF0De4BKneo5hMbac,6659
+maggraph/_maggraph.pyd,sha256=cN88xofwCtexCOhZF6PrxGip0x1JzuWerEktYRx-fIo,3180032
+maggraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+maggraph-0.2.5.dist-info/METADATA,sha256=_TMfGgneOUWk0Y-Op52_SK9ppq0M6YKqZgNZp1p1fiA,9309
+maggraph-0.2.5.dist-info/WHEEL,sha256=dB50znGoqD95tHNeV5UBZvlfLNwgEh0iQcswp5YahQ4,95
+maggraph-0.2.5.dist-info/sboms/maggraph.cyclonedx.json,sha256=MYRV4-eyW85LDzL45X_Xt6gKRykSJr9TAaLPEh087iA,155112
+maggraph-0.2.5.dist-info/RECORD,,

maggraph-0.2.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.13.3)
+Root-Is-Purelib: false
+Tag: cp39-abi3-win_amd64