Navegador

navegador / docs / api / sdk.md
Source Blame History 486 lines
89816aa… lmata 1 # Python SDK Reference
89816aa… lmata 2
89816aa… lmata 3 Full API reference for the navegador Python SDK.
89816aa… lmata 4
89816aa… lmata 5 ```python
89816aa… lmata 6 from navegador.graph import GraphStore
89816aa… lmata 7 from navegador.context import ContextLoader, ContextBundle, ContextNode, ContextEdge
89816aa… lmata 8 from navegador.ingest import RepoIngester, KnowledgeIngester, WikiIngester, PlanopticonIngester
89816aa… lmata 9 ```
89816aa… lmata 10
89816aa… lmata 11 ---
89816aa… lmata 12
89816aa… lmata 13 ## GraphStore
89816aa… lmata 14
89816aa… lmata 15 Database abstraction layer. Both SQLite and Redis backends implement this interface.
89816aa… lmata 16
89816aa… lmata 17 ```python
89816aa… lmata 18 class GraphStore:
89816aa… lmata 19 @classmethod
89816aa… lmata 20 def sqlite(cls, path: str | Path = "navegador.db") -> "GraphStore": ...
89816aa… lmata 21
89816aa… lmata 22 @classmethod
89816aa… lmata 23 def redis(cls, url: str = "redis://localhost:6379") -> "GraphStore": ...
89816aa… lmata 24 ```
89816aa… lmata 25
89816aa… lmata 26 ### Class methods
89816aa… lmata 27
89816aa… lmata 28 #### `GraphStore.sqlite`
89816aa… lmata 29
89816aa… lmata 30 ```python
89816aa… lmata 31 @classmethod
89816aa… lmata 32 def sqlite(cls, path: str | Path = "navegador.db") -> "GraphStore"
89816aa… lmata 33 ```
89816aa… lmata 34
89816aa… lmata 35 Open a local SQLite-backed graph. The file is created if it does not exist. Uses `falkordblite` (embedded engine — no daemon required).
89816aa… lmata 36
89816aa… lmata 37 **Parameters:**
89816aa… lmata 38
89816aa… lmata 39 | Name | Type | Default | Description |
89816aa… lmata 40 |---|---|---|---|
89816aa… lmata 41 | `path` | `str \| Path` | `"navegador.db"` | Path to the `.db` file |
89816aa… lmata 42
89816aa… lmata 43 **Returns:** `GraphStore`
89816aa… lmata 44
89816aa… lmata 45 #### `GraphStore.redis`
89816aa… lmata 46
89816aa… lmata 47 ```python
89816aa… lmata 48 @classmethod
89816aa… lmata 49 def redis(cls, url: str = "redis://localhost:6379") -> "GraphStore"
89816aa… lmata 50 ```
89816aa… lmata 51
89816aa… lmata 52 Connect to a Redis-backed FalkorDB instance.
89816aa… lmata 53
89816aa… lmata 54 **Parameters:**
89816aa… lmata 55
89816aa… lmata 56 | Name | Type | Default | Description |
89816aa… lmata 57 |---|---|---|---|
89816aa… lmata 58 | `url` | `str` | `"redis://localhost:6379"` | Redis connection URL |
89816aa… lmata 59
89816aa… lmata 60 **Returns:** `GraphStore`
89816aa… lmata 61
89816aa… lmata 62 ---
89816aa… lmata 63
89816aa… lmata 64 ### Instance methods
89816aa… lmata 65
89816aa… lmata 66 #### `query`
89816aa… lmata 67
89816aa… lmata 68 ```python
89816aa… lmata 69 def query(self, cypher: str, params: dict | None = None) -> list[dict]
89816aa… lmata 70 ```
89816aa… lmata 71
89816aa… lmata 72 Execute a Cypher query and return all result rows.
89816aa… lmata 73
89816aa… lmata 74 **Parameters:**
89816aa… lmata 75
89816aa… lmata 76 | Name | Type | Default | Description |
89816aa… lmata 77 |---|---|---|---|
89816aa… lmata 78 | `cypher` | `str` | — | Cypher query string |
89816aa… lmata 79 | `params` | `dict \| None` | `None` | Optional query parameters |
89816aa… lmata 80
89816aa… lmata 81 **Returns:** `list[dict]` — one dict per result row, keyed by return variable name.
89816aa… lmata 82
89816aa… lmata 83 ---
89816aa… lmata 84
89816aa… lmata 85 #### `create_node`
89816aa… lmata 86
89816aa… lmata 87 ```python
89816aa… lmata 88 def create_node(self, label: str, properties: dict) -> str
89816aa… lmata 89 ```
89816aa… lmata 90
89816aa… lmata 91 Create a new node and return its ID.
89816aa… lmata 92
89816aa… lmata 93 **Parameters:**
89816aa… lmata 94
89816aa… lmata 95 | Name | Type | Description |
89816aa… lmata 96 |---|---|---|
89816aa… lmata 97 | `label` | `str` | Node label (e.g., `"Function"`, `"Concept"`) |
89816aa… lmata 98 | `properties` | `dict` | Node properties |
89816aa… lmata 99
89816aa… lmata 100 **Returns:** `str` — node ID
89816aa… lmata 101
89816aa… lmata 102 ---
89816aa… lmata 103
89816aa… lmata 104 #### `merge_node`
89816aa… lmata 105
89816aa… lmata 106 ```python
89816aa… lmata 107 def merge_node(
89816aa… lmata 108 self,
89816aa… lmata 109 label: str,
89816aa… lmata 110 match_properties: dict,
89816aa… lmata 111 set_properties: dict | None = None,
89816aa… lmata 112 ) -> str
89816aa… lmata 113 ```
89816aa… lmata 114
89816aa… lmata 115 Upsert a node: create it if no node with `match_properties` exists; otherwise update `set_properties` on the existing node.
89816aa… lmata 116
89816aa… lmata 117 **Parameters:**
89816aa… lmata 118
89816aa… lmata 119 | Name | Type | Default | Description |
89816aa… lmata 120 |---|---|---|---|
89816aa… lmata 121 | `label` | `str` | — | Node label |
89816aa… lmata 122 | `match_properties` | `dict` | — | Properties to match on (identity key) |
89816aa… lmata 123 | `set_properties` | `dict \| None` | `None` | Properties to set on create or update |
89816aa… lmata 124
89816aa… lmata 125 **Returns:** `str` — node ID
89816aa… lmata 126
89816aa… lmata 127 ---
89816aa… lmata 128
89816aa… lmata 129 #### `create_edge`
89816aa… lmata 130
89816aa… lmata 131 ```python
89816aa… lmata 132 def create_edge(
89816aa… lmata 133 self,
89816aa… lmata 134 from_id: str,
89816aa… lmata 135 to_id: str,
89816aa… lmata 136 edge_type: str,
89816aa… lmata 137 properties: dict | None = None,
89816aa… lmata 138 ) -> None
89816aa… lmata 139 ```
89816aa… lmata 140
89816aa… lmata 141 Create a directed edge between two nodes.
89816aa… lmata 142
89816aa… lmata 143 **Parameters:**
89816aa… lmata 144
89816aa… lmata 145 | Name | Type | Default | Description |
89816aa… lmata 146 |---|---|---|---|
89816aa… lmata 147 | `from_id` | `str` | — | Source node ID |
89816aa… lmata 148 | `to_id` | `str` | — | Target node ID |
89816aa… lmata 149 | `edge_type` | `str` | — | Relationship type (e.g., `"CALLS"`, `"ANNOTATES"`) |
89816aa… lmata 150 | `properties` | `dict \| None` | `None` | Optional edge properties |
89816aa… lmata 151
89816aa… lmata 152 ---
89816aa… lmata 153
89816aa… lmata 154 #### `merge_edge`
89816aa… lmata 155
89816aa… lmata 156 ```python
89816aa… lmata 157 def merge_edge(
89816aa… lmata 158 self,
89816aa… lmata 159 from_label: str,
89816aa… lmata 160 from_match: dict,
89816aa… lmata 161 to_label: str,
89816aa… lmata 162 to_match: dict,
89816aa… lmata 163 edge_type: str,
89816aa… lmata 164 properties: dict | None = None,
89816aa… lmata 165 ) -> None
89816aa… lmata 166 ```
89816aa… lmata 167
89816aa… lmata 168 Upsert an edge between two nodes matched by label and properties.
89816aa… lmata 169
89816aa… lmata 170 ---
89816aa… lmata 171
89816aa… lmata 172 #### `clear`
89816aa… lmata 173
89816aa… lmata 174 ```python
89816aa… lmata 175 def clear(self) -> None
89816aa… lmata 176 ```
89816aa… lmata 177
89816aa… lmata 178 Delete all nodes and edges from the graph.
89816aa… lmata 179
89816aa… lmata 180 ---
89816aa… lmata 181
89816aa… lmata 182 #### `close`
89816aa… lmata 183
89816aa… lmata 184 ```python
89816aa… lmata 185 def close(self) -> None
89816aa… lmata 186 ```
89816aa… lmata 187
89816aa… lmata 188 Release the database connection. Called automatically when used as a context manager.
89816aa… lmata 189
89816aa… lmata 190 ---
89816aa… lmata 191
89816aa… lmata 192 #### Context manager
89816aa… lmata 193
89816aa… lmata 194 `GraphStore` implements `__enter__` / `__exit__`. Use with `with` to ensure the connection is closed:
89816aa… lmata 195
89816aa… lmata 196 ```python
89816aa… lmata 197 with GraphStore.sqlite(".navegador/navegador.db") as store:
89816aa… lmata 198 results = store.query("MATCH (n) RETURN count(n) AS total")
89816aa… lmata 199 ```
89816aa… lmata 200
89816aa… lmata 201 ---
89816aa… lmata 202
89816aa… lmata 203 ## ContextLoader
89816aa… lmata 204
89816aa… lmata 205 Builds structured context bundles from graph queries.
89816aa… lmata 206
89816aa… lmata 207 ```python
89816aa… lmata 208 class ContextLoader:
89816aa… lmata 209 def __init__(self, store: GraphStore) -> None: ...
89816aa… lmata 210 ```
89816aa… lmata 211
89816aa… lmata 212 ### Methods
89816aa… lmata 213
89816aa… lmata 214 #### `load_file`
89816aa… lmata 215
89816aa… lmata 216 ```python
89816aa… lmata 217 def load_file(self, path: str) -> ContextBundle
89816aa… lmata 218 ```
89816aa… lmata 219
89816aa… lmata 220 Return the full context bundle for a source file: the file node, its modules, classes, functions, imports, and their relationships.
89816aa… lmata 221
89816aa… lmata 222 **Parameters:**
89816aa… lmata 223
89816aa… lmata 224 | Name | Type | Description |
89816aa… lmata 225 |---|---|---|
89816aa… lmata 226 | `path` | `str` | Relative or absolute path to the source file |
89816aa… lmata 227
89816aa… lmata 228 **Returns:** `ContextBundle`
89816aa… lmata 229
89816aa… lmata 230 ---
89816aa… lmata 231
89816aa… lmata 232 #### `load_function`
89816aa… lmata 233
89816aa… lmata 234 ```python
89816aa… lmata 235 def load_function(
89816aa… lmata 236 self,
89816aa… lmata 237 name: str,
89816aa… lmata 238 *,
89816aa… lmata 239 file: str = "",
89816aa… lmata 240 depth: int = 1,
89816aa… lmata 241 ) -> ContextBundle
89816aa… lmata 242 ```
89816aa… lmata 243
89816aa… lmata 244 Return a function node with its callers, callees, decorators, containing class, and source.
89816aa… lmata 245
89816aa… lmata 246 **Parameters:**
89816aa… lmata 247
89816aa… lmata 248 | Name | Type | Default | Description |
89816aa… lmata 249 |---|---|---|---|
89816aa… lmata 250 | `name` | `str` | — | Function name |
89816aa… lmata 251 | `file` | `str` | `""` | Optional file path to disambiguate |
89816aa… lmata 252 | `depth` | `int` | `1` | Call graph traversal depth (1 = direct callers/callees only) |
89816aa… lmata 253
89816aa… lmata 254 **Returns:** `ContextBundle`
89816aa… lmata 255
89816aa… lmata 256 ---
89816aa… lmata 257
89816aa… lmata 258 #### `load_class`
89816aa… lmata 259
89816aa… lmata 260 ```python
89816aa… lmata 261 def load_class(
89816aa… lmata 262 self,
89816aa… lmata 263 name: str,
89816aa… lmata 264 *,
89816aa… lmata 265 file: str = "",
89816aa… lmata 266 ) -> ContextBundle
89816aa… lmata 267 ```
89816aa… lmata 268
89816aa… lmata 269 Return a class node with its methods, base classes, subclasses, and references from other files.
89816aa… lmata 270
89816aa… lmata 271 **Parameters:**
89816aa… lmata 272
89816aa… lmata 273 | Name | Type | Default | Description |
89816aa… lmata 274 |---|---|---|---|
89816aa… lmata 275 | `name` | `str` | — | Class name |
89816aa… lmata 276 | `file` | `str` | `""` | Optional file path to disambiguate |
89816aa… lmata 277
89816aa… lmata 278 **Returns:** `ContextBundle`
89816aa… lmata 279
89816aa… lmata 280 ---
89816aa… lmata 281
89816aa… lmata 282 #### `explain`
89816aa… lmata 283
89816aa… lmata 284 ```python
89816aa… lmata 285 def explain(
89816aa… lmata 286 self,
89816aa… lmata 287 name: str,
89816aa… lmata 288 *,
89816aa… lmata 289 file: str = "",
89816aa… lmata 290 ) -> ContextBundle
89816aa… lmata 291 ```
89816aa… lmata 292
89816aa… lmata 293 Universal lookup: explain any node (function, class, file, concept, rule, decision) by name.
89816aa… lmata 294
89816aa… lmata 295 **Parameters:**
89816aa… lmata 296
89816aa… lmata 297 | Name | Type | Default | Description |
89816aa… lmata 298 |---|---|---|---|
89816aa… lmata 299 | `name` | `str` | — | Node name or file path |
89816aa… lmata 300 | `file` | `str` | `""` | Optional file path to disambiguate code nodes |
89816aa… lmata 301
89816aa… lmata 302 **Returns:** `ContextBundle`
89816aa… lmata 303
89816aa… lmata 304 ---
89816aa… lmata 305
89816aa… lmata 306 #### `load_concept`
89816aa… lmata 307
89816aa… lmata 308 ```python
89816aa… lmata 309 def load_concept(self, name: str) -> ContextBundle
89816aa… lmata 310 ```
89816aa… lmata 311
89816aa… lmata 312 Return a concept node with its rules, linked wiki pages, and annotated code nodes.
89816aa… lmata 313
89816aa… lmata 314 ---
89816aa… lmata 315
89816aa… lmata 316 #### `load_domain`
89816aa… lmata 317
89816aa… lmata 318 ```python
89816aa… lmata 319 def load_domain(self, name: str) -> ContextBundle
89816aa… lmata 320 ```
89816aa… lmata 321
89816aa… lmata 322 Return a domain and all nodes belonging to it: concepts, rules, decisions, people, and annotated code.
89816aa… lmata 323
89816aa… lmata 324 ---
89816aa… lmata 325
89816aa… lmata 326 #### `search`
89816aa… lmata 327
89816aa… lmata 328 ```python
89816aa… lmata 329 def search(
89816aa… lmata 330 self,
89816aa… lmata 331 query: str,
89816aa… lmata 332 *,
89816aa… lmata 333 all_layers: bool = False,
89816aa… lmata 334 docs_only: bool = False,
89816aa… lmata 335 limit: int = 20,
89816aa… lmata 336 ) -> list[ContextNode]
89816aa… lmata 337 ```
89816aa… lmata 338
89816aa… lmata 339 Search the graph by text query.
89816aa… lmata 340
89816aa… lmata 341 **Parameters:**
89816aa… lmata 342
89816aa… lmata 343 | Name | Type | Default | Description |
89816aa… lmata 344 |---|---|---|---|
89816aa… lmata 345 | `query` | `str` | — | Search string |
89816aa… lmata 346 | `all_layers` | `bool` | `False` | Search all layers including knowledge and docs |
89816aa… lmata 347 | `docs_only` | `bool` | `False` | Search docstrings and wiki content only |
89816aa… lmata 348 | `limit` | `int` | `20` | Maximum number of results |
89816aa… lmata 349
89816aa… lmata 350 **Returns:** `list[ContextNode]`
89816aa… lmata 351
89816aa… lmata 352 ---
89816aa… lmata 353
89816aa… lmata 354 #### `search_by_docstring`
89816aa… lmata 355
89816aa… lmata 356 ```python
89816aa… lmata 357 def search_by_docstring(self, query: str, *, limit: int = 20) -> list[ContextNode]
89816aa… lmata 358 ```
89816aa… lmata 359
89816aa… lmata 360 Search docstrings and wiki page content. Equivalent to `search(query, docs_only=True)`.
89816aa… lmata 361
89816aa… lmata 362 ---
89816aa… lmata 363
89816aa… lmata 364 #### `decorated_by`
89816aa… lmata 365
89816aa… lmata 366 ```python
89816aa… lmata 367 def decorated_by(self, decorator: str) -> list[ContextNode]
89816aa… lmata 368 ```
89816aa… lmata 369
89816aa… lmata 370 Find all functions and classes that use a specific decorator.
89816aa… lmata 371
89816aa… lmata 372 **Parameters:**
89816aa… lmata 373
89816aa… lmata 374 | Name | Type | Description |
89816aa… lmata 375 |---|---|---|
89816aa… lmata 376 | `decorator` | `str` | Decorator name (e.g., `"login_required"`, `"pytest.mark.parametrize"`) |
89816aa… lmata 377
89816aa… lmata 378 **Returns:** `list[ContextNode]`
89816aa… lmata 379
89816aa… lmata 380 ---
89816aa… lmata 381
89816aa… lmata 382 ## ContextBundle
89816aa… lmata 383
89816aa… lmata 384 Structured result returned by `ContextLoader` methods.
89816aa… lmata 385
89816aa… lmata 386 ```python
89816aa… lmata 387 @dataclass
89816aa… lmata 388 class ContextBundle:
89816aa… lmata 389 root: ContextNode
89816aa… lmata 390 nodes: list[ContextNode]
89816aa… lmata 391 edges: list[ContextEdge]
89816aa… lmata 392 metadata: dict
89816aa… lmata 393 ```
89816aa… lmata 394
89816aa… lmata 395 ### Fields
89816aa… lmata 396
89816aa… lmata 397 | Field | Type | Description |
89816aa… lmata 398 |---|---|---|
89816aa… lmata 399 | `root` | `ContextNode` | The primary node (function, class, file, etc.) |
89816aa… lmata 400 | `nodes` | `list[ContextNode]` | All nodes in the bundle, including `root` |
89816aa… lmata 401 | `edges` | `list[ContextEdge]` | All edges between nodes in the bundle |
89816aa… lmata 402 | `metadata` | `dict` | Query metadata (depth, timing, node counts) |
89816aa… lmata 403
89816aa… lmata 404 ### Methods
89816aa… lmata 405
89816aa… lmata 406 #### `to_json`
89816aa… lmata 407
89816aa… lmata 408 ```python
89816aa… lmata 409 def to_json(self) -> str
89816aa… lmata 410 ```
89816aa… lmata 411
89816aa… lmata 412 Serialize the bundle to a JSON string.
89816aa… lmata 413
89816aa… lmata 414 #### `to_markdown`
89816aa… lmata 415
89816aa… lmata 416 ```python
89816aa… lmata 417 def to_markdown(self) -> str
89816aa… lmata 418 ```
89816aa… lmata 419
89816aa… lmata 420 Render the bundle as a Markdown string. Suitable for pasting into agent context.
89816aa… lmata 421
89816aa… lmata 422 #### `to_dict`
89816aa… lmata 423
89816aa… lmata 424 ```python
89816aa… lmata 425 def to_dict(self) -> dict
89816aa… lmata 426 ```
89816aa… lmata 427
89816aa… lmata 428 Return the bundle as a plain Python dict.
89816aa… lmata 429
89816aa… lmata 430 ---
89816aa… lmata 431
89816aa… lmata 432 ## ContextNode
89816aa… lmata 433
89816aa… lmata 434 A single node in a context bundle.
89816aa… lmata 435
89816aa… lmata 436 ```python
89816aa… lmata 437 @dataclass
89816aa… lmata 438 class ContextNode:
89816aa… lmata 439 id: str
89816aa… lmata 440 label: str # e.g. "Function", "Concept"
89816aa… lmata 441 name: str
89816aa… lmata 442 properties: dict # all node properties from the graph
89816aa… lmata 443 layer: str # "code" or "knowledge"
89816aa… lmata 444 score: float # relevance score (search results only)
89816aa… lmata 445 ```
89816aa… lmata 446
89816aa… lmata 447 ---
89816aa… lmata 448
89816aa… lmata 449 ## ContextEdge
89816aa… lmata 450
89816aa… lmata 451 A relationship between two nodes in a context bundle.
89816aa… lmata 452
89816aa… lmata 453 ```python
89816aa… lmata 454 @dataclass
89816aa… lmata 455 class ContextEdge:
89816aa… lmata 456 from_id: str
89816aa… lmata 457 to_id: str
89816aa… lmata 458 edge_type: str # e.g. "CALLS", "ANNOTATES", "INHERITS"
89816aa… lmata 459 properties: dict
89816aa… lmata 460 ```
89816aa… lmata 461
89816aa… lmata 462 ---
89816aa… lmata 463
89816aa… lmata 464 ## IngestionResult
89816aa… lmata 465
89816aa… lmata 466 Returned by all ingest methods.
89816aa… lmata 467
89816aa… lmata 468 ```python
89816aa… lmata 469 @dataclass
89816aa… lmata 470 class IngestionResult:
89816aa… lmata 471 nodes_created: int
89816aa… lmata 472 nodes_updated: int
89816aa… lmata 473 edges_created: int
89816aa… lmata 474 files_processed: int
89816aa… lmata 475 errors: list[str]
89816aa… lmata 476 duration_seconds: float
89816aa… lmata 477 ```
89816aa… lmata 478
89816aa… lmata 479 | Field | Type | Description |
89816aa… lmata 480 |---|---|---|
89816aa… lmata 481 | `nodes_created` | `int` | New nodes written to the graph |
89816aa… lmata 482 | `nodes_updated` | `int` | Existing nodes updated |
89816aa… lmata 483 | `edges_created` | `int` | New edges written |
89816aa… lmata 484 | `files_processed` | `int` | Source files walked |
89816aa… lmata 485 | `errors` | `list[str]` | Per-file parse errors (non-fatal) |
89816aa… lmata 486 | `duration_seconds` | `float` | Wall time for the ingest operation |

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button