Intelligence Layer

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.

Setup

Install the intelligence extras:

pip install "navegador[intelligence]"

Configure your LLM provider:

=== "OpenAI"

```bash
export NAVEGADOR_LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-...
```

=== "Anthropic"

```bash
export NAVEGADOR_LLM_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
```

=== "Local (Ollama)"

```bash
export NAVEGADOR_LLM_PROVIDER=ollama
export NAVEGADOR_LLM_MODEL=llama3.2
# no API key required; Ollama must be running on localhost:11434
```

Or set via navegador.toml:

[intelligence]
provider = "openai"
model = "text-embedding-3-small"   # embedding model
llm_model = "gpt-4o-mini"          # generation model

Semantic search

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.

navegador search "handle payment failure" --semantic
navegador search "retry with backoff" --semantic --limit 10
navegador search "authentication middleware" --semantic --all

!!! note 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.

Combining semantic and text search

# semantic search scoped to a domain
navegador search "billing failure" --semantic --domain Payments

# hybrid: semantic ranking with text pre-filter
navegador search "rate limit" --semantic --all

Python API

from navegador.graph import GraphStore
from navegador.intelligence import SemanticSearch

store = GraphStore.sqlite(".navegador/navegador.db")
search = SemanticSearch(store)

results = search.query("handle payment failure", limit=10)
for node in results:
    print(f"[{node.label}] {node.name}  score={node.score:.3f}")

Community detection

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 intelligence communities
navegador intelligence communities --algorithm louvain
navegador intelligence communities --format json

Algorithms

Output

Detected 6 communities:

  Community 1 (47 nodes) — suggested name: Auth
    Core: AuthService, validate_token, JWTManager
    Files: src/auth/ (12 files)

  Community 2 (38 nodes) — suggested name: Payments
    Core: PaymentProcessor, charge_card, StripeClient
    Files: src/payments/ (9 files)

  Community 3 (22 nodes) — suggested name: Orders
    Core: OrderService, create_order, OrderRepository
    Files: src/orders/ (6 files)
  ...

Suggested names are generated by the LLM by inspecting the core nodes of each cluster.

Persisting communities

navegador intelligence communities --save

This writes Community nodes and MEMBER_OF edges into the graph, making communities queryable:

navegador query "MATCH (f:Function)-[:MEMBER_OF]->(c:Community) WHERE c.name = 'Payments' RETURN f.name, f.file"

Natural language queries

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 "Which functions call process_payment?"
navegador ask "What rules govern the Payments domain?"
navegador ask "Show me all classes that inherit from BaseProcessor"
navegador ask "What decisions have been made about the database?"

How it works

1. Your question is embedded and matched against graph schema context
2. The LLM generates a Cypher query based on the question and schema
3. Navegador executes the query against the graph
4. The LLM formats the results as a natural language answer with source references

Safety

Generated queries are run in read-only mode. Write operations (CREATE, MERGE, DELETE, SET) in generated queries are blocked.

# show the generated Cypher without executing
navegador ask "Which functions have no tests?" --show-query

# execute and show both Cypher and answer
navegador ask "Which functions have no tests?" --verbose

Documentation generation

navegador docgen generates or improves docstrings for undocumented functions and classes, using graph context to produce accurate, context-aware descriptions.

# generate docs for all undocumented functions in a file
navegador docgen src/payments/processor.py

# generate docs for a specific function
navegador docgen --target process_payment

# dry run: show what would be generated without writing
navegador docgen src/payments/processor.py --dry-run

# write directly to source files
navegador docgen src/payments/processor.py --write

What it includes

The generated docstring draws on:

• The function's call graph (what it calls and what calls it)
• Related concepts and rules from the knowledge layer
• The class or module context
• Existing docstrings in the same file as style examples

Output

def process_payment(order_id: str, amount: Decimal, idempotency_key: str) -> PaymentResult:
    """Process a payment for an order.

    Charges the card on file for the given order using the Stripe payment
    processor. Requires an idempotency key to prevent double-charging on
    client retries (see: RequireIdempotencyKey rule, UseStripeForPayments
    decision).

    Args:
        order_id: The unique identifier of the order to charge.
        amount: The amount to charge in the order's currency.
        idempotency_key: Client-supplied key for idempotent retries.

    Returns:
        PaymentResult with charge_id and status.

    Raises:
        PaymentError: If the charge fails or the card is declined.
        DuplicatePaymentError: If a payment with this idempotency_key
            already exists with a different amount.
    """

Batch generation

# generate docs for all undocumented functions in the repo
navegador docgen ./src --write --format google

# formats: google (default), numpy, sphinx

!!! warning --write modifies source files in place. Review changes with --dry-run first and commit before running with --write so you can diff and revert.

Python API

from navegador.graph import GraphStore
from navegador.intelligence import SemanticSearch, CommunityDetector, NaturalLanguageQuery, DocGenerator

store = GraphStore.sqlite(".navegador/navegador.db")

# semantic search
search = SemanticSearch(store)
results = search.query("retry logic", limit=5)

# community detection
detector = CommunityDetector(store)
communities = detector.detect(algorithm="louvain", save=True)

# natural language query
nlq = NaturalLanguageQuery(store)
answer = nlq.ask("What functions call process_payment?")
print(answer.text)
print(answer.cypher)  # generated Cypher

# doc generation
docgen = DocGenerator(store)
draft = docgen.generate_for_function("process_payment")
print(draft.docstring)