The intelligence layer adds capabilities that go beyond structural graph queries: semantic similarity search, community detection, natural language queries, and documentation generation. These features require an LLM provider or embedding model.
4
5
---
6
7
## Setup
8
9
Install the intelligence extras:
10
11
```bash
12
pip install "navegador[intelligence]"
13
```
14
15
Configure your LLM provider:
16
17
=== "OpenAI"
18
19
```bash
20
export NAVEGADOR_LLM_PROVIDER=openai
21
export OPENAI_API_KEY=sk-...
22
```
23
24
=== "Anthropic"
25
26
```bash
27
export NAVEGADOR_LLM_PROVIDER=anthropic
28
export ANTHROPIC_API_KEY=sk-ant-...
29
```
30
31
=== "Local (Ollama)"
32
33
```bash
34
export NAVEGADOR_LLM_PROVIDER=ollama
35
export NAVEGADOR_LLM_MODEL=llama3.2
36
# no API key required; Ollama must be running on localhost:11434
37
```
38
39
Or set via `navegador.toml`:
40
41
```toml
42
[intelligence]
43
provider = "openai"
44
model = "text-embedding-3-small" # embedding model
45
llm_model = "gpt-4o-mini" # generation model
46
```
47
48
---
49
50
## Semantic search
51
52
Standard `navegador search` matches on names and text. Semantic search matches on **meaning**: a query for "billing" finds code about "invoices", "subscriptions", and "charges" even when those words don't appear in the query.
First run after ingestion builds the embedding index. This may take a minute on large codebases. The index is cached in the database and updated incrementally on re-ingest.
Community detection groups nodes in the graph into clusters based on structural connectivity. Clusters typically correspond to logical modules or subsystems, even when the code doesn't explicitly organize itself that way.
`navegador ask` lets you query the graph in plain English. The LLM translates your question into Cypher, executes it, and returns a natural language answer with citations.
navegador ask "What rules govern the Payments domain?"
149
navegador ask "Show me all classes that inherit from BaseProcessor"
150
navegador ask "What decisions have been made about the database?"
151
```
152
153
### How it works
154
155
1. Your question is embedded and matched against graph schema context
156
2. The LLM generates a Cypher query based on the question and schema
157
3. Navegador executes the query against the graph
158
4. The LLM formats the results as a natural language answer with source references
159
160
### Safety
161
162
Generated queries are run in read-only mode. Write operations (`CREATE`, `MERGE`, `DELETE`, `SET`) in generated queries are blocked.
163
164
```bash
165
# show the generated Cypher without executing
166
navegador ask "Which functions have no tests?" --show-query
167
168
# execute and show both Cypher and answer
169
navegador ask "Which functions have no tests?" --verbose
170
```
171
172
---
173
174
## Documentation generation
175
176
`navegador docgen` generates or improves docstrings for undocumented functions and classes, using graph context to produce accurate, context-aware descriptions.
177
178
```bash
179
# generate docs for all undocumented functions in a file
180
navegador docgen src/payments/processor.py
181
182
# generate docs for a specific function
183
navegador docgen --target process_payment
184
185
# dry run: show what would be generated without writing