# Phase 3 — Vector Search & Graph Algorithms

> Embedding-based similarity search, hybrid retrieval, and graph analytics.

## Status: In Progress

## Research-Informed Changes

- Added `vector_graph_search` — hybrid vector + graph expansion (key differentiator)
- Added `betweenness_centrality` — finds bridge/bottleneck nodes
- Added `connected_components` — finds disconnected subgraphs
- Renamed `shortest_path` to `dijkstra` (matches real GrafeoDB API)
- Renamed `community_detection` to `louvain` (matches real API, more precise)
- `vector_search` now includes `ef` parameter for HNSW beam width tuning
- `create_vector_index` exposes `m` and `ef_construction` HNSW params
- Large vector properties (>32 elements) are stripped from result summaries
- Token truncation via `_truncate()` on all algorithm outputs

## Tools (8 total)

### Vector tools

| Tool                  | Description                                            |
| --------------------- | ------------------------------------------------------ |
| `vector_search`       | k-NN search by cosine/euclidean/dot-product distance   |
| `create_vector_index` | Create HNSW index on a label+property                  |
| `vector_graph_search` | Hybrid: vector search + graph neighborhood expansion   |

### Algorithm tools

| Tool                      | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `pagerank`                | Rank nodes by importance (top-k)               |
| `dijkstra`                | Shortest weighted path between two nodes       |
| `louvain`                 | Community detection (modularity optimization)  |
| `betweenness_centrality`  | Find bridge/bottleneck nodes                   |
| `connected_components`    | Find disconnected subgraphs                    |

## Tasks

- [x] Implement `vector_search` with `ef` param and truncation
- [x] Implement `create_vector_index` with `m` and `ef_construction`
- [x] Implement `vector_graph_search` (vector seed + GQL expansion)
- [x] Implement `pagerank` with `top_k` limiting
- [x] Implement `dijkstra` (not `shortest_path`) with path node summaries
- [x] Implement `louvain` (not `community_detection`) with grouped output
- [x] Implement `betweenness_centrality` with `top_k` limiting
- [x] Implement `connected_components`
- [x] Write `tests/test_tools_vector.py` (12 tests)
- [x] Write `tests/test_tools_algorithms.py` (13 tests)

## Design Decisions

### Vector search returns similarity score

Results include both raw `distance` and `similarity` (1.0 - distance) since agents
often want the intuitive "higher = more similar" number.

### Hybrid search uses GQL for expansion (not Cypher)

`vector_graph_search` uses `db.execute()` (GQL) for graph expansion since GQL is
always available. Cypher requires a feature flag and might not be compiled in.

### Algorithm tools operate on the full graph

No subgraph filtering — algorithms run on all nodes/edges.
Subgraph projection can be added in a future phase if needed.
