# RAG bundle (semantic memory)

GEDX402 sells self-serve RAG ingest and query across embed and search shards as one discoverable family. Agents pay USDC per route via x402 — no API keys.

**Discovery:** `GET https://gedx402.com/v1/models?bundle=rag` — three routes tagged `rag-bundle`.

| Step | Route | Shard | Method |
| --- | --- | --- | --- |
| Embed probe | `/v1/embed/small` | embed | `POST` |
| Ingest | `/v1/search/upsert` | search | `POST` |
| Query | `/v1/search/query` | search | `POST` |

Origins: `embed.gedx402.com`, `search.gedx402.com`. Each route returns `402` with x402 payment instructions until settled.

**Response cache (300s):** After a successful paid `POST /v1/embed/*` or `POST /v1/search/query`, identical requests (same route + text, or namespace + query) are served from the Workers Cache API for 5 minutes with `X-GED-Cache: hit` and **no second x402 charge**. First populate is paid; repeats within TTL are free to the agent (operator absorbs inference on cache hits).

**Starter routes:** `POST https://embed.gedx402.com/v1/embed/small` (embed shard) · `POST https://search.gedx402.com/v1/search/query` (search shard).

---

## Integration flow

```mermaid
sequenceDiagram
  participant Agent
  participant Embed as POST /v1/embed/small
  participant Upsert as POST /v1/search/upsert
  participant Query as POST /v1/search/query

  Agent->>Embed: text (optional standalone embed)
  Embed-->>Agent: 768-dim vector (BGE-base)
  Agent->>Upsert: namespace, id, text
  Upsert-->>Agent: mutationId (embeds + stores in semantic memory)
  Agent->>Query: namespace, query, top_k
  Query-->>Agent: matches[] with scores + metadata
```

### 1. Embed (optional standalone)

Use when you need vectors outside semantic memory (e.g. local reranking):

```http
POST https://embed.gedx402.com/v1/embed/small
Content-Type: application/json

{ "text": "GED inference runs at the edge." }
```

Returns a 768-dimensional BGE-base embedding. `search/upsert` embeds internally — you do not need a separate embed call for the standard ingest path.

### 2. Upsert documents

```http
POST https://search.gedx402.com/v1/search/upsert
Content-Type: application/json

{
  "namespace": "my-agent",
  "id": "doc-1",
  "text": "GED inference runs at the edge.",
  "metadata": { "source": "docs" }
}
```

`namespace` isolates agent collections (2–64 chars). Upsert embeds with BGE-base and stores in semantic memory.

### 3. Semantic query

```http
POST https://search.gedx402.com/v1/search/query
Content-Type: application/json

{
  "namespace": "my-agent",
  "query": "How does edge inference work?",
  "top_k": 5
}
```

Returns ranked matches with scores and optional metadata. Use retrieved chunks as context for your chat model.

---

## Pricing

Each route quotes one **USDC wire settlement** on Base. See `GET /v1/models?bundle=rag` for per-leg quotes.

---

## Agent discovery

- Hub catalog: `GET /v1/models?bundle=rag`
- OpenAPI: `https://embed.gedx402.com/openapi.json`, `https://search.gedx402.com/openapi.json`
- x402scan tags: `rag-bundle`, `search`
- MCP starters: `gedx402_embed_small`, `gedx402_search_query`
- vs managed RAG: see [MANAGED-RAG-BUNDLE.md](./MANAGED-RAG-BUNDLE.md) for managed RAG (`rag.gedx402.com`)