# Phase 3 — Advanced

> Extended capabilities: retriever adapters, async, batch operations, graph algorithms, and observability.

## Tasks

- [ ] **`langchain-graph-retriever` adapter** — Eager/BFS strategy support
- [ ] **Async support** — `async_similarity_search`, `async_traversal_search`, etc.
- [ ] **Batch embedding ingestion** — efficient large-scale document loading
- [ ] **Graph algorithm integration** — PageRank scoring, community detection in retrieval
- [ ] **LangSmith tracing** — observability and debugging integration

---

## langchain-graph-retriever Adapter

The `langchain-graph-retriever` package provides advanced traversal strategies (BFS, Eager, MMR) on top of any `GraphVectorStore`. Grafeo should work as a drop-in backend.

Key integration points:
- `GraphVectorStore` must support the `get_adjacent` or edge-traversal interface expected by graph-retriever strategies
- Edge definitions: `edges=[("entity", "RELATES_TO")]` — map metadata keys to Grafeo edge types
- Strategy compatibility: `Eager(k, start_k, depth)`, `BFS`, custom strategies

Open questions:
- Does `langchain-graph-retriever` require specific methods beyond what `VectorStore` provides?
- How are edge types discovered/mapped from Grafeo's schema?

---

## Async Support

LangChain's `VectorStore` has async variants for all main methods. Grafeo may need async wrappers.

Methods to implement:
- `asimilarity_search`
- `asimilarity_search_by_vector`
- `aadd_texts`
- `aadd_documents`
- `atraversal_search`
- `ammr_traversal_search`

Approach options:
1. **Run sync in executor** — wrap sync methods with `asyncio.to_thread()` (simplest)
2. **Native async** — if Grafeo provides async APIs in the future

---

## Batch Embedding Ingestion

For large document sets, the current one-at-a-time ingestion is slow. Improvements:

- Batch `embed_documents()` calls (already batched by provider)
- Batch node creation in Grafeo (if supported)
- Progress reporting via callbacks
- Chunked processing to manage memory

---

## Graph Algorithm Integration

Grafeo has built-in graph algorithms. These could enhance retrieval:

- **PageRank** — score documents by graph centrality, use as a retrieval signal
- **Community detection (Louvain)** — group related documents, scope traversal to communities
- **Shortest path** — find paths between query-relevant documents
- **Node similarity** — alternative to/complement for vector similarity

Potential API:
```python
# Score documents by PageRank centrality
store.similarity_search(query, k=4, rerank_by="pagerank")

# Scope traversal to a community
store.traversal_search(query, k=4, depth=2, community_id=3)
```

---

## LangSmith Tracing

Integration with LangSmith for observability:

- Trace vector search calls (query, k, results, latency)
- Trace graph traversal (depth, nodes visited, edges followed)
- Trace MMR re-ranking (candidate set size, selected indices)
- Custom metadata in traces (db_path, index stats)

Approach: use LangChain's callback system / `run_manager` pattern.
