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.

Document recommend API and RecSys harness in README docs.

Cursor Agentb168cb766b45
diff --git a/README.md b/README.md
index 893ecc0..2e17762 100644
--- a/README.md
+++ b/README.md
@@ -220,7 +220,8 @@ Once your data is in, BrainAPI exposes purpose-built retrieval endpoints (REST,
| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `/retrieve/context` | `POST` | **Relevant information for a piece of text** — the matching graph triples plus historical context |
| `/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** related to a given one — effectively a recommendation algorithm over the graph |
+| `/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 |
**Get context for a question:**
@@ -240,15 +241,23 @@ curl "http://localhost:8000/retrieve/entity/status?target=Emily" \
# → { "exists": true, "node": {...}, "relationships": [...], "observations": [...] }
```
-**Find synergies (recommendations):**
+**Find synergies (same-type siblings):**
```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 three 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 cover the most common needs, but there are more (`/retrieve/hops`, `/retrieve/entities/neighbors`, `/retrieve/text-chunks`, …). Full list → [Docs v2](https://brainapi.lumen-labs.ai/docs/v2).
---
@@ -257,7 +266,7 @@ These three cover the most common needs, but there are more (`/retrieve/hops`, `
Out of the box BrainAPI is a general-purpose understanding engine. **Plugins** let you reshape it into something far more specific — without forking the core. Because plugins can add routes, swap agent prompts, and register MCP tools, the same engine can become:
- **A cheap semantic search engine** — extract entities once, then serve fast graph-backed search instead of paying for vector queries every time.
-- **A recommendation system** — build on `/retrieve/entity/synergies` and custom routes to surface related products, content or collaborators.
+- **A recommendation system** — use `/retrieve/recommend` (and `/retrieve/entity/synergies` for same-type siblings) or plugins like `features-rec` / `recsys-gnn`.
- **A domain-specific extractor** — override the Scout/Architect prompts so the swarm understands your ontology (CRM, legal, medical, …).
- **An agent toolset** — register custom MCP tools so any LLM runtime can read and write your brain.
diff --git a/benchmarks/README.md b/benchmarks/README.md
index 69ea41e..536302b 100644
--- a/benchmarks/README.md
+++ b/benchmarks/README.md
@@ -6,6 +6,8 @@ Standalone HTTP-only harnesses (no `src/` imports):
| --- | --- | --- |
| [LoCoMo](https://github.com/snap-research/LoCoMo) | `locomo/` | `./locomo.sh` |
| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | `longmemeval/` | `./longmemeval.sh` |
+| [BEAM](https://github.com/mohammadtavakoli78/BEAM) | `beam/` | `./beam.sh` |
+| RecSys (train-free `/retrieve/recommend`) | `recsys/` | `./recsys.sh` |
Shared setup: `requirements.txt`, `.env` (`BRAINPAT_TOKEN`, LLM keys). Results ledger: [`REPORTS.json`](REPORTS.json). Agent notes: [`AGENTS.md`](AGENTS.md).
@@ -219,11 +221,13 @@ Create a sibling package under `benchmarks/`:
benchmarks/
locomo/ # LoCoMo package
longmemeval/ # LongMemEval package
+ beam/ # BEAM package
+ recsys/ # RecSys / recommend package
yourbench/ # new package with its own cli / client / metrics
requirements.txt # shared deps, or a per-bench requirements file
```
-Reuse patterns from `locomo/` / `longmemeval/`:
+Reuse patterns from `locomo/` / `longmemeval/` / `recsys/`:
- HTTP-only `BrainAPIClient`
- JSONL resume files under `runs/`
@@ -327,3 +331,34 @@ Do **not** ingest probing questions, rubrics, or ideal answers.
**Cost warning:** even one 100K chat is ~100+ turns; start with `--limit-turns` / `--limit`.
**1M wall time:** ~40h at concurrency 1; ~20–25h at 2 with healthy API (see `docs/research/10-beam-protocol.md`).
+
+---
+
+# 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.