Repository navigation
Expand file tree
/
Copy path__init__.pyi
More file actions
249 lines (228 loc) · 7.67 KB
/
Copy path__init__.pyi
File metadata and controls
249 lines (228 loc) · 7.67 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
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 HybridSearchResult(TypedDict):
id: str
type: str
relative_path: str
score: float
signals: dict[str, float]
reasons: list[str]
summary: str
modified_unix: Optional[int]
canonical_id: str
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 MemoryBatchResult(TypedDict, total=False):
ok: bool
preview: bool
operations: int
applied: list[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 hybrid_search(
self,
query: str = "",
node_types: list[str] | None = None,
tags: list[str] | None = None,
project: str | None = None,
seed_ids: list[str] | None = None,
semantic_scores: dict[str, float] | None = None,
include_suppressed: bool = False,
include_superseded: bool = False,
limit: int = 20,
as_of_unix: int | None = None,
recency_half_life_days: float = 30.0,
) -> list[HybridSearchResult]: ...
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,
project: str | None = None,
source_task: str | None = None,
source_session: str | None = None,
source_tool: str | None = None,
extraction_method: str | None = None,
confidence: float | None = None,
valid_from: str | None = None,
valid_until: str | None = None,
supersedes: str | None = None,
canonical_id: 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 apply_memory_batch(
self, operations: list[dict[str, str]], preview: bool = False
) -> MemoryBatchResult: ...
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: ...