# Search Strategies

> **Status:** Coming soon

This document will cover the various search methods available in ModuleWrapper.

## Planned Topics

### Search Method Overview

| Method | Vector(s) | Use Case |
|--------|-----------|----------|
| `search()` | MiniLM | Basic semantic search |
| `colbert_search()` | ColBERT | Token-level matching |
| `search_named_vector()` | Single named | Targeted vector search |
| `search_hybrid()` | All 3 + RRF | Best overall results |
| `search_by_dsl()` | ColBERT | DSL-aware queries |
| `query_by_symbol()` | None (filter) | Exact symbol lookup |

### Simple Searches (Single Vector)

- `search(query, limit, score_threshold)` - MiniLM semantic search
- `search_async()` - Async version of basic search
- `colbert_search()` - ColBERT multi-vector with MaxSim
- `query_by_symbol()` - Exact match on symbol field

### Text Index Searches

- `search_by_text(field, query)` - Qdrant text index search
- `search_by_relationship_text()` - Search relationship descriptions
- `search_within_module()` - Module-scoped text search

### DSL-Aware Searches

```python
# Extract DSL and search
results = wrapper.search_by_dsl("§[δ, Ƀ[ᵬ×2]] Build a status card")

# Hybrid DSL search (classes + patterns)
results = wrapper.search_by_dsl_hybrid("§[δ] notification card")
# Returns: {"classes": [...], "patterns": [...], "query_info": {...}}
```

- DSL extraction from natural language
- DSL + description embedding
- Class vs pattern filtering

### Named-Vector Multi-Vector Searches

```python
# Search specific vector
results = wrapper.search_named_vector(
    query="button with icon",
    vector_name="components",  # or "inputs", "relationships"
    limit=10,
)

# Hybrid search with RRF fusion
classes, patterns, relationships = wrapper.search_hybrid(
    description="status card with action button",
    component_paths=["Section", "DecoratedText"],
    content_feedback="positive",  # Filter by feedback
)
```

### Vector Selection Guide

| Query Type | Best Vector | Why |
|------------|-------------|-----|
| "Find Button class" | `components` | Component identity |
| "card with status text" | `inputs` | Content/parameter matching |
| "Section containing Button" | `relationships` | Structural patterns |
| Complex queries | `search_hybrid` | RRF combines all |

### RRF Fusion

Reciprocal Rank Fusion combines results from multiple vectors:

```
RRF_score = Σ (1 / (k + rank))
```

- Default k=60 (higher = more weight to lower ranks)
- Deduplicates across result sets
- Preserves best results from each strategy

### Feedback Filtering

```python
# Filter by content feedback
classes, patterns, _ = wrapper.search_hybrid(
    description="notification card",
    content_feedback="positive",  # Only positive content matches
)

# Filter by form/structure feedback
_, _, relationships = wrapper.search_hybrid(
    description="grid layout",
    form_feedback="positive",  # Only positive structure matches
)
```

### Direct Component Lookup

Before vector search, methods check for exact matches:

1. Exact name match in `components` dict
2. Case-insensitive name match
3. Check `widgets` submodule
4. Fall back to vector search

### Result Processing

```python
# Standard result format
{
    "id": "point_id",
    "score": 0.85,
    "name": "Button",
    "type": "class",
    "full_path": "card_framework.v2.widgets.button.Button",
    "symbol": "ᵬ",
    "docstring": "...",
    "component": <class Button>,  # Resolved class object
}
```

### Performance Tips

- Use `token_ratio` < 1.0 for faster ColBERT searches
- Use `query_by_symbol()` for known symbols (fastest)
- Use `search_named_vector()` with specific vector for targeted queries
- Use `search_hybrid()` when unsure which vector is best

## Related Files

- `search_mixin.py` - SearchMixin implementation
- `embedding_mixin.py` - Embedding generation
- `symbols_mixin.py` - DSL extraction methods
