> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Semantic disambiguation and hybrid retrieval.

Before reasoning about facts, agents must find the correct starting point.
Hybrid search disambiguates natural language queries and resolves them to the
correct semantic entity (IRI) before executing symbolic logic.

## Why not only vector search?

Standard vector search retrieves semantically similar text, but agents require
factual precision. If an agent searches for "Ethan's manager", a pure vector
query might return "Gregory's manager" because their text embeddings are nearly
identical in vector space.

## Hybrid retrieval

Worlds combines three signals for accurate retrieval. Hybrid search layers
keyword matching and structural graph filters over vector embeddings, so the
agent resolves the exact item it needs.

| Signal        | Technique                    | What it captures         |
| :------------ | :--------------------------- | :----------------------- |
| Semantic      | Vector embeddings (1536-dim) | Conceptual meaning       |
| Keyword       | FTS5 / BM25                  | Exact term matches       |
| Graph context | RDF relationship filters     | Structural relationships |

## Reciprocal rank fusion

Results from each signal are merged using Reciprocal Rank Fusion (RRF), an
algorithm that produces a single relevance ranking:

$score = \sum_{d \in D} \frac{1}{60 + rank(d)}$

This lifts results ranked highly by multiple signals to the top and suppresses
noise from any single signal.

## Execute a search

Use the data-plane search endpoint to perform hybrid retrieval across a world.
Data-plane requests authenticate with a `wzw_` world token:

```bash theme={null}
curl -s -X POST "https://worlds-api.wazoo.dev/worlds/my-world-id/search" \
  -H "Authorization: Bearer $WORLDS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Ethan's manager",
    "limit": 5
  }'
```

Results return the matching subject and predicate IRIs plus the literal
`content`, so an agent can bind the exact entity before running
[SPARQL](/worlds/query).