Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

Merge remote-tracking branch 'origin/main' into codex/production-readiness

Christian7813ab47ece1
diff --cc README.md
index cf418d0,23b5f73..c5b7777
--- a/README.md
+++ b/README.md
@@@ -220,11 -218,10 +220,11 @@@ Once your data is in, BrainAPI exposes
| Endpoint | Method | What you get |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
- | `/retrieve/context` | `POST` | **Relevant information for a piece of text** — one-shot graph and passage context; p50 target < 1000 ms |
-| `/retrieve/context` | `POST` | **Relevant information for a piece of text** — graph triples, passages, historical context, and optional provenance |
++| `/retrieve/context` | `POST` | **Relevant information for a piece of text** — one-shot graph triples, passages, historical context, and optional provenance; p50 target < 1000 ms |
+| `/retrieve/search` | `GET`/`POST` | **Ranked search hits** (opt-in: `SEARCH_ENABLED=true`) — passages (BM25 ∪ dense) by default; optional `entities` / `events` / `communities` channels and `expand=neighbors`; p50 < 200 ms excluding embed |
| `/retrieve/entity/status` | `GET` | **Existence check** for a specific entity — returns whether it exists, its node, relationships, and observations |
- | `/retrieve/entity/synergies` | `GET` | **Similar things (Preview)** related to a given one; quality thresholds are not yet release-stable |
- | `/retrieve/recommend` | `GET`/`POST` | **Ranked recommendations (Preview)**; endpoint compatibility is retained while the quality gate is defined |
-| `/retrieve/entity/synergies` | `GET` | **Sibling entities** of the same type — shared event hubs + embedding similarity (`top_k`, `labels`, `polarity`) |
-| `/retrieve/recommend` | `GET`/`POST` | **Train-free recommendations** — synergies plus asymmetric walks, multi-interest, optional attribute prefs |
++| `/retrieve/entity/synergies` | `GET` | **Sibling entities (Preview)** — shared event hubs + embedding similarity (`top_k`, `labels`, `polarity`); quality thresholds are not yet release-stable |
++| `/retrieve/recommend` | `GET`/`POST` | **Train-free recommendations (Preview)** — synergies plus asymmetric walks, multi-interest, and optional attribute preferences; endpoint compatibility is retained while the quality gate is defined |
**Get context for a question:**
@@@ -244,15 -242,25 +245,24 @@@ curl "http://localhost:8000/retrieve/en
# → { "exists": true, "node": {...}, "relationships": [...], "observations": [...] }
```
- **Find synergies (recommendations, Preview):**
-**Find synergies (same-type siblings):**
++**Find synergies (same-type siblings, Preview):**
```sh
- curl "http://localhost:8000/retrieve/entity/synergies?target=Neural%20Networks%20101" \
+ curl "http://localhost:8000/retrieve/entity/synergies?target=Neural%20Networks%20101&top_k=20" \
-H "Authorization: Bearer $BRAINPAT_TOKEN"
- # → similar entities ranked by how strongly they connect to the target
+ # → similar entities ranked by association_score
```
- These endpoints cover the most common needs, but there are more (`/retrieve/hops`, `/retrieve/entities/neighbors`, `/retrieve/text-chunks`, …). Full list → [REST API Reference](https://brainapi.lumen-labs.ai/docs/rest).
-
+ **Rank recommendations (product / next-item style):**
+
+ ```sh
+ curl "http://localhost:8000/retrieve/recommend?target=u01&top_k=20&labels=PRODUCT&exclude_seen=true" \
+ -H "Authorization: Bearer $BRAINPAT_TOKEN"
+ # → ranked recommendations with channel provenance (synergy / asymmetric / multi_interest / …)
+ ```
+
+
-These three cover the most common needs, but there are more (`/retrieve/hops`, `/retrieve/entities/neighbors`, `/retrieve/text-chunks`, …). Start with [Context retrieval](https://brainapi.lumen-labs.ai/docs/v2/retrieval/context) and the [docs hub](https://brainapi.lumen-labs.ai/docs/v2).
++These endpoints cover the most common needs, but there are more (`/retrieve/hops`, `/retrieve/entities/neighbors`, `/retrieve/text-chunks`, …). Start with [Context retrieval](https://brainapi.lumen-labs.ai/docs/v2/retrieval/context) and the [docs hub](https://brainapi.lumen-labs.ai/docs/v2).
---
diff --cc benchmarks/README.md
index de7b60f,536302b..26bf46a
--- a/benchmarks/README.md
+++ b/benchmarks/README.md
@@@ -6,8 -6,8 +6,9 @@@ Standalone HTTP-only harnesses (no `src
| --- | --- | --- |
| [LoCoMo](https://github.com/snap-research/LoCoMo) | `locomo/` | `./locomo.sh` |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | `longmemeval/` | `./longmemeval.sh` |
- | RecSys | `recsys/` | `./recsys.sh` |
+ | [BEAM](https://github.com/mohammadtavakoli78/BEAM) | `beam/` | `./beam.sh` |
+ | RecSys (train-free `/retrieve/recommend`) | `recsys/` | `./recsys.sh` |
+| Search | `search/` | `./search.sh` |
Shared setup: `requirements.txt`, `.env` (`BRAINPAT_TOKEN`, LLM keys). Results ledger: [`REPORTS.json`](REPORTS.json). Agent notes: [`AGENTS.md`](AGENTS.md).
@@@ -332,53 -334,31 +335,84 @@@ Do **not** ingest probing questions, ru
---
+ # RecSys benchmark for BrainAPI
+
+ Held-out next-item HitRate/Recall@K against **train-free** `GET /retrieve/recommend` (default) or optional plugin LightGCN. Uses structured ingest into brain `demorecsys` only — never LoCoMo/BEAM brains.
+
+ 1. Optional MovieLens download (`ml-100k`) or toy JSONL fixtures under `data/`
+ 2. Maps interactions → `POST /ingest/structured` (`mode=deterministic`)
+ 3. Ranks with `GET /retrieve/recommend` (`--backend graph`) or LightGCN (`--backend lightgcn`)
+ 4. Scores HitRate@K / Recall@K (+ diversity); upserts only `benchmarks.recsys`
+
+ Protocol: [`docs/research/16-recsys-eval-protocol.md`](../docs/research/16-recsys-eval-protocol.md).
+
+ ## Quickstart
+
+ ```bash
+ ./recsys.sh smoke --backend graph
+ ./recsys.sh download --name ml-100k
+ ./recsys.sh evaluate --backend graph --dataset data/movielens_100k.jsonl --max-users 50
+ # attributed fixture (color/material):
+ ./recsys.sh evaluate --backend graph --dataset data/recsys_toy_attrs.jsonl --min-interactions 2
+ # optional offline CF:
+ ./recsys.sh evaluate --backend lightgcn --dataset data/recsys_toy.jsonl --epochs 20
+ ```
+
+ ### Scoring
+
+ - **Headline**: `hit_rate@K` / `recall@K` (K typically 10/20).
+ - Also: intra-list diversity, type coverage; report `model=graph-recommend` or `lightgcn`.
+ - Successful scored runs upsert `benchmarks.recsys` only — do not touch other suite keys.
++
++---
++
+# Search benchmark for BrainAPI
+
+Standalone HTTP-only harness for `POST /retrieve/search` (hybrid BM25 + dense). It does **not** import `src/` and does **not** call `/retrieve/context`.
+
+Protocol: [`docs/research/18-search-eval-protocol.md`](../docs/research/18-search-eval-protocol.md).
+
+## Prerequisites
+
+- BrainAPI running with `SEARCH_ENABLED=true`, `DATA_DB=postgresql`, `BRAIN_CREATION_ALLOWED=true`
+- `BRAINPAT_TOKEN` in `benchmarks/.env`
+- Brain id starting with `searchbench` (default `searchbenchsmoke`)
+
+A 404 on `/retrieve/search` means search is disabled — fix the server env; it is not a ranking miss.
+
+## Quickstart
+
+```bash
+cd benchmarks
+./search.sh dataset-stats
+./search.sh smoke
+./search.sh evaluate --fusion rrf
+./search.sh evaluate --rerank plugin:cross-encoder
+./search.sh report --run <run_id>
+```
+
+Toy corpus: [`data/search_toy.jsonl`](data/search_toy.jsonl) (keyword + paraphrase queries; gold via `DOCID` markers). Search ingest defaults to **chunk + embed only** (`skip_enrichment`); pass `--enrich` for Scout/Architect.
+
+Product-search corpora (LLM-free ingest; dedicated `searchbench*` brains, not `demorecsys`):
+
+```bash
+./search.sh download --name esci
+./search.sh download --name wands
+./search.sh dataset-stats --dataset data/search_esci.jsonl
+./search.sh evaluate --dataset data/search_esci.jsonl --brain searchbenchesci --run search-esci
+./search.sh --brain searchbenchwands evaluate --dataset data/search_wands.jsonl --run search-wands-passages-k50 --channels passages --k 50 --ks 5,10,20,50
+./search.sh --brain searchbenchwands evaluate --dataset data/search_wands.jsonl --run search-wands-passages-k50 --channels passages --k 50 --ks 5,10,20,50 --skip-ingest
+./search.sh --brain searchbenchwandsgraph evaluate --dataset data/search_wands.jsonl --run search-wandsgraph-communities-k50 --channels communities --k 50 --ks 5,10,20,50 --ingest-graph
+```
+
+`download` writes a **subset** under `data/` (gitignored): Amazon ESCI / Shopping Queries (KDD Cup 2022, US Task 1 test) and WANDS (Wayfair). Defaults: 80 queries, 2000 products, 40 candidates per query. Frozen WANDS quality slice is `data/search_wands.jsonl` (**66** queries / **2000** docs); `--force` cannot clobber it. Raw caches live in `data/esci/` and `data/wands/`. nDCG@10 is graded (ESCI E=1 / S=0.1 / C=0.01 / I=0; WANDS Exact=1 / Partial=0.5 / Irrelevant=0). WANDS first-stage control: passages, k=50, `rerank=none`, brain `searchbenchwands`, then `--skip-ingest`. Opt-in catalog graph: new brain `searchbenchwandsgraph` only; architecture demo, do not mix with ESCI nDCG or frozen WANDS 0.823.
+
+Optional plugins (core hybrid works if they are absent; unknown `plugin:<name>` is 400):
+
+- `plugins/search-rerank` — `--rerank plugin:cross-encoder` (K≤10)
+- `plugins/search-splade` — `--channels plugin:splade` after `POST /search-splade/index`
+- `plugins/search-colbert` — `--channels plugin:colbert` after `POST /search-colbert/index`
+
+Metrics: Recall@{5,10,20}, nDCG@10, MRR; p50/p95 of retrieve **excluding** embed RTT. Successful `evaluate` upserts `benchmarks.search` in [`REPORTS.json`](REPORTS.json). Smoke does not publish scores.
+
+Never ingest into or wipe `locomoconv*`, `beam*`, or `demorecsys`.
diff --cc src/core/search/entity_info.py
index c459f62,c459f62..881644b
--- a/src/core/search/entity_info.py
+++ b/src/core/search/entity_info.py
@@@ -56,7 -56,7 +56,10 @@@ def _recency_score(node: Node) -> float
f"on node {node.uuid}, recency left neutral"
)
return 1.0
-- days_ago = max(0, (datetime.now() - to_naive_utc(happened_at)).days)
++ days_ago = max(
++ 0,
++ (datetime.now().date() - to_naive_utc(happened_at).date()).days,
++ )
if days_ago <= 0:
return 1.0
return 1 / (1 + np.log1p(days_ago))