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.

Add recommend and synergy retrieval with recsys benchmarks.

Christian1e4cf880c5de
diff --git a/README.md b/README.md
index 882429b..893ecc0 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
<p align="center">
<a href="https://discord.gg/VTngQTaeDf"><img src="https://img.shields.io/badge/Discord-Join%20Lumen%20Brain-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"/></a>
- <img src="https://img.shields.io/badge/version-2.14.3--dev-blue?style=for-the-badge" alt="Version"/>
+ <img src="https://img.shields.io/badge/version-2.15.0--dev-blue?style=for-the-badge" alt="Version"/>
<img src="https://img.shields.io/badge/python-3.11+-green?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
<img src="https://img.shields.io/badge/license-PolyForm%20Small%20Business-blue?style=for-the-badge" alt="License"/>
</p>
@@ -131,6 +131,7 @@ docker compose -f deploy/docker-compose.light.yaml up -d
cp deploy/env.heavy.example .env
docker compose -f deploy/docker-compose.heavy.yaml up -d
```
+
Then ingest your first data point:
```sh
diff --git a/benchmarks/AGENTS.md b/benchmarks/AGENTS.md
index 04f8507..a742471 100644
--- a/benchmarks/AGENTS.md
+++ b/benchmarks/AGENTS.md
@@ -7,8 +7,9 @@
| **LoCoMo** | `benchmarks/locomo/` | `./locomo.sh` | `benchmarks.locomo` |
| **LongMemEval** | `benchmarks/longmemeval/` | `./longmemeval.sh` | `benchmarks.longmemeval` |
| **BEAM** | `benchmarks/beam/` | `./beam.sh` | `benchmarks.beam` |
+| **RecSys** | `benchmarks/recsys/` | `./recsys.sh` | `benchmarks.recsys` |
-All harnesses talk to a running BrainAPI over HTTP only (no `src/` imports).
+All harnesses talk to a running BrainAPI over HTTP only (no `src/` imports). RecSys uses `POST /ingest/structured` (KB write) + **train-free** `GET /retrieve/recommend` on brain **`demorecsys` only** — never LoCoMo/BEAM brains. Optional: `plugins/features-rec` for attribute prefs; `plugins/recsys-gnn` LightGCN via `--backend lightgcn`.
### LoCoMo
@@ -18,6 +19,22 @@ Typical flow: `download` → `ingest` → `evaluate` → `report` via `./locomo.
Typical flow: `download` → `ingest` → `evaluate` → `report` via `./longmemeval.sh` or `.venv/bin/python -m longmemeval`. Protocol: `docs/research/09-longmemeval-protocol.md`.
+### RecSys
+
+Held-out next-item HitRate/Recall@K via **train-free graph recommend** (default) or optional plugin LightGCN. Flow: `download` (optional MovieLens) → structured ingest → `GET /retrieve/recommend` via `./recsys.sh --backend graph`. Brain: `demorecsys`.
+
+```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
+```
+
+Protocol: [`docs/research/16-recsys-eval-protocol.md`](../docs/research/16-recsys-eval-protocol.md). Upserts only `benchmarks.recsys` — never wipe or write to `beam1m1clean` / `locomoconv26*`.
+
### BEAM
Typical flow: `download` → `ingest` → `evaluate` → `report` via `./beam.sh` or `.venv/bin/python -m beam`.
@@ -37,6 +54,7 @@ Typical flow: `download` → `ingest` → `evaluate` → `report` via `./beam.sh
- LoCoMo harness upserts `benchmarks.locomo` via `write_report` → `update_reports_json` when report `status` is `ok`.
- BEAM harness upserts `benchmarks.beam` the same way (field: `headline_score`, continuous `[0,1]`).
+- RecSys harness upserts `benchmarks.recsys` only (`hit_rate@K` / `recall@K`); it must not touch other suite keys.
- After any completed evaluate/report that produces a successful scored run, ensure the suite entry in `REPORTS.json` reflects it.
- If you write or patch `runs/<id>/report.json` manually, update `REPORTS.json` yourself (same schema; upsert by `run_id` under the suite).
- When adding a new suite, add a `benchmarks.<suite_id>` key (`name` + `leaderboard`) and upsert the same way.
diff --git a/benchmarks/REPORTS.json b/benchmarks/REPORTS.json
index 49ede06..94a721a 100644
--- a/benchmarks/REPORTS.json
+++ b/benchmarks/REPORTS.json
@@ -1,6 +1,6 @@
{
"schema_version": 2,
- "updated_at": "2026-08-03T09:15:33.804119+00:00",
+ "updated_at": "2026-08-05T20:07:44.710028+00:00",
"description": "BrainAPI benchmark results. Top published scores across suites. Updated when a suite evaluate/report completes successfully.",
"benchmarks": {
"locomo": {
@@ -784,6 +784,25 @@
"recorded_at": "2026-08-03T06:59:14.016975+00:00"
}
]
+ },
+ "recsys": {
+ "name": "RecSys (event-KG recommend)",
+ "leaderboard": [
+ {
+ "run_id": "recsys-20260805T200653Z",
+ "brain": "demorecsys",
+ "n_users": 20,
+ "hit_rate@10": 0.1,
+ "hit_rate@20": 0.1,
+ "recall@10": 0.1,
+ "recall@20": 0.1,
+ "mean_intra_list_diversity": 0.20536531279178338,
+ "mean_type_coverage": 2.0,
+ "git_sha": "cf61c99b809730cc9eb35db3532e018bdd038a55",
+ "report_path": "runs/recsys-20260805T200653Z/report.json",
+ "recorded_at": "2026-08-05T20:07:44.707984+00:00"
+ }
+ ]
}
}
}
diff --git a/benchmarks/recsys.sh b/benchmarks/recsys.sh
new file mode 100755
index 0000000..6f01aa3
--- /dev/null
+++ b/benchmarks/recsys.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+PYTHON="${ROOT}/.venv/bin/python"
+if [[ ! -x "$PYTHON" ]]; then
+ echo "Missing ${PYTHON}. Create it with:"
+ echo " cd benchmarks && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt"
+ exit 1
+fi
+exec "$PYTHON" -m recsys "$@"
diff --git a/benchmarks/recsys/__init__.py b/benchmarks/recsys/__init__.py
new file mode 100644
index 0000000..b158171
--- /dev/null
+++ b/benchmarks/recsys/__init__.py
@@ -0,0 +1 @@
+"""RecSys held-out next-item harness against brain demorecsys."""
diff --git a/benchmarks/recsys/__main__.py b/benchmarks/recsys/__main__.py
new file mode 100644
index 0000000..f42748e
--- /dev/null
+++ b/benchmarks/recsys/__main__.py
@@ -0,0 +1,4 @@
+from recsys.cli import main
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/benchmarks/recsys/cli.py b/benchmarks/recsys/cli.py
new file mode 100644
index 0000000..86d8d00
--- /dev/null
+++ b/benchmarks/recsys/cli.py
@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from recsys.client import BrainAPIClient
+from recsys.config import DEFAULT_BRAIN_ID, ML100K_DATASET_PATH, Settings
+from recsys.dataset import (
+ dataset_stats,
+ filter_interactions,
+ prepare_ml100k,
+)
+from recsys.evaluate import (
+ ensure_run_dir,
+ evaluate_leave_one_out,
+ ingest_train_interactions,
+ load_interactions,
+)
+from recsys.mapping import (
+ interactions_to_triples,
+ leave_one_out_splits,
+ structured_ingest_body,
+)
+from recsys.report import print_report_table, write_report
+
+console = Console()
+
+
+def _resolve_dataset_path(args: argparse.Namespace, settings: Settings) -> Path:
+ if getattr(args, "dataset", None):
+ return Path(args.dataset)
+ return settings.dataset_path
+
+
+def cmd_download(args: argparse.Namespace, settings: Settings) -> int:
+ name = (args.name or "ml-100k").strip().lower()
+ if name not in {"ml-100k", "movielens-100k", "movielens100k"}:
+ console.print(
+ f"[red]Unknown dataset[/red] {name!r}. Supported: ml-100k"
+ )
+ return 1
+ out = Path(args.out) if args.out else ML100K_DATASET_PATH
+ path = prepare_ml100k(out_path=out, force=args.force, min_rating=args.min_rating)
+ rows = load_interactions(path)
+ stats = dataset_stats(rows)
+ console.print(f"[green]Ready[/green] {path}")
+ console.print(stats)
+ return 0
+
+
+def cmd_dataset_stats(args: argparse.Namespace, settings: Settings) -> int:
+ path = _resolve_dataset_path(args, settings)
+ if not path.exists():
+ console.print(
+ f"[red]Missing[/red] {path}. Run: ./recsys.sh download --name ml-100k"
+ )
+ return 1
+ rows = load_interactions(path)
+ filtered = filter_interactions(
+ rows,
+ min_interactions=args.min_interactions,
+ max_users=args.max_users,
+ )
+ table = Table(title=f"RecSys dataset — {path.name}")
+ table.add_column("scope")
+ table.add_column("n_interactions")
+ table.add_column("n_users")
+ table.add_column("n_items")
+ table.add_column("ix/user mean")
+ for label, subset in (("full", rows), ("filtered", filtered)):
+ s = dataset_stats(subset)
+ table.add_row(
+ label,
+ str(s["n_interactions"]),
+ str(s["n_users"]),
+ str(s["n_items"]),
+ f"{s['interactions_per_user_mean']:.1f}",
+ )
+ console.print(table)
+ splits = leave_one_out_splits(filtered)
+ console.print(f"[dim]leave-one-out users={len(splits)}[/dim]")
+ return 0
+
+
+def cmd_map(args: argparse.Namespace, settings: Settings) -> int:
+ path = _resolve_dataset_path(args, settings)
+ rows = load_interactions(path)
+ rows = filter_interactions(
+ rows,
+ min_interactions=getattr(args, "min_interactions", 2) or 2,
+ max_users=getattr(args, "max_users", None),
+ )
+ splits = leave_one_out_splits(rows)
+ train = [r for s in splits for r in s["train"]] if args.holdout else rows
+ triples = interactions_to_triples(train, include_catalog=not args.no_catalog)
+ body = structured_ingest_body(triples, brain_id=settings.brain_id)
+ text = json.dumps(body, indent=2)
+ if args.out:
+ Path(args.out).write_text(text + "\n", encoding="utf-8")
+ console.print(f"[green]Wrote[/green] {args.out} ({len(triples)} triples)")
+ else:
+ console.print(text)
+ console.print(
+ f"[dim]users_with_holdout={len(splits)} interactions={len(rows)} "
+ f"mapped={len(train)}[/dim]"
+ )
+ return 0
+
+
+def cmd_smoke(args: argparse.Namespace, settings: Settings) -> int:
+ path = _resolve_dataset_path(args, settings)
+ rows = load_interactions(path)
+ rows = filter_interactions(
+ rows,
+ min_interactions=2,
+ max_users=args.max_users,
+ )[: args.limit]
+ backend = (getattr(args, "backend", None) or "graph").strip().lower()
+ with BrainAPIClient(settings) as client:
+ info = ingest_train_interactions(
+ client, rows, timeout_s=args.timeout, chunk_size=args.chunk_size
+ )
+ console.print(info)
+ if info["status"] not in {"completed", "partial_failed"}:
+ console.print("[red]Smoke ingest failed[/red]")
+ return 1
+ user_id = str(rows[0]["user_id"])
+ if backend == "lightgcn":
+ train = client.train_lightgcn(
+ epochs=args.epochs, wait=True, timeout_s=args.timeout
+ )
+ console.print(train.data)
+ status = (train.data or {}).get("status")
+ nested = ((train.data or {}).get("task") or {}).get("status")
+ if status != "completed" and nested != "completed":
+ console.print("[red]Smoke train failed[/red]")
+ return 1
+ rec = client.recommend(user_id, top_k=args.top_k, exclude_seen=False)
+ n = len((rec.data or {}).get("items") or [])
+ console.print(f"recsys/recommend({user_id}) -> {n} items")
+ else:
+ rec = client.recommend_graph(
+ user_id,
+ top_k=args.top_k,
+ exclude_seen=False,
+ include_attribute_pref=True,
+ )
+ n = len((rec.data or {}).get("recommendations") or [])
+ console.print(f"retrieve/recommend({user_id}) -> {n} items")
+ if n < 1:
+ console.print("[red]Smoke recommend returned no items[/red]")
+ return 1
+ console.print("[green]Smoke passed[/green]")
+ return 0
+
+
+def cmd_evaluate(args: argparse.Namespace, settings: Settings) -> int:
+ path = _resolve_dataset_path(args, settings)
+ if not path.exists():
+ console.print(
+ f"[red]Missing[/red] {path}. For MovieLens: ./recsys.sh download --name ml-100k"
+ )
+ return 1
+ rows = load_interactions(path)
+ rows = filter_interactions(
+ rows,
+ min_interactions=args.min_interactions,
+ max_users=args.max_users,
+ )
+ run_id, run_dir = ensure_run_dir(settings, args.run)
+ ks = tuple(int(x) for x in args.ks.split(",") if x.strip())
+ if not ks:
+ ks = (10, 20)
+ backend = (args.backend or "graph").strip().lower()
+
+ console.print(
+ f"[cyan]Evaluating[/cyan] brain={settings.brain_id} "
+ f"dataset={path.name} users≈{len({r['user_id'] for r in rows})} "
+ f"run={run_id} backend={backend}"
+ )
+ with BrainAPIClient(settings) as client:
+ result = evaluate_leave_one_out(
+ client,
+ rows,
+ ks=ks,
+ timeout_s=args.timeout,
+ epochs=args.epochs,
+ ingest_chunk_size=args.chunk_size,
+ dataset_name=path.name,
+ backend=backend,
+ include_attribute_pref=not args.no_attribute_pref,
+ )
+ report = write_report(run_dir, result)
+ print_report_table(report)
+ console.print(f"[green]Wrote[/green] {run_dir / 'report.json'}")
+ return 0 if report.get("status") == "ok" else 1
+
+
+def cmd_report(args: argparse.Namespace, settings: Settings) -> int:
+ run_dir = settings.runs_dir / args.run
+ eval_path = run_dir / "eval.json"
+ if not eval_path.exists():
+ console.print(f"[red]Missing[/red] {eval_path}")
+ return 1
+ eval_result = json.loads(eval_path.read_text(encoding="utf-8"))
+ report = write_report(run_dir, eval_result)
+ print_report_table(report)
+ return 0 if report.get("status") == "ok" else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(
+ prog="recsys",
+ description=(
+ "Held-out next-item eval on demorecsys: structured ingest → "
+ "GET /retrieve/recommend (graph, default) or LightGCN plugin"
+ ),
+ )
+ parser.add_argument(
+ "--env-file",
+ type=Path,
+ default=None,
+ help="Optional dotenv path (default benchmarks/.env)",
+ )
+ parser.add_argument(
+ "--brain",
+ default=None,
+ help=f"Brain id (default {DEFAULT_BRAIN_ID}; never LoCoMo/BEAM brains)",
+ )
+ sub = parser.add_subparsers(dest="command", required=True)
+
+ p_dl = sub.add_parser("download", help="Download MovieLens → JSONL")
+ p_dl.add_argument("--name", default="ml-100k", help="Dataset id (ml-100k)")
+ p_dl.add_argument("--out", type=str, default=None)
+ p_dl.add_argument("--force", action="store_true")
+ p_dl.add_argument(
+ "--min-rating",
+ type=float,
+ default=1.0,
+ help="Keep ratings >= this (default 1 = all as implicit positives)",
+ )
+ p_dl.set_defaults(func=cmd_download)
+
+ p_stats = sub.add_parser("dataset-stats", help="Summarize interaction JSONL")
+ p_stats.add_argument("--dataset", type=str, default=None)
+ p_stats.add_argument("--min-interactions", type=int, default=5)
+ p_stats.add_argument("--max-users", type=int, default=100)
+ p_stats.set_defaults(func=cmd_dataset_stats)
+
+ p_map = sub.add_parser("map", help="Map interactions JSONL → structured body")
+ p_map.add_argument("--dataset", type=str, default=None)
+ p_map.add_argument("--out", type=str, default=None)
+ p_map.add_argument(
+ "--holdout",
+ action="store_true",
+ help="Map train split only (drop last interaction per user)",
+ )
+ p_map.add_argument("--no-catalog", action="store_true")
+ p_map.add_argument("--min-interactions", type=int, default=2)
+ p_map.add_argument("--max-users", type=int, default=None)
+ p_map.set_defaults(func=cmd_map)
+
+ p_smoke = sub.add_parser(
+ "smoke", help="Ingest → graph or LightGCN recommend smoke"
+ )
+ p_smoke.add_argument("--dataset", type=str, default=None)
+ p_smoke.add_argument("--limit", type=int, default=6)
+ p_smoke.add_argument("--max-users", type=int, default=None)
+ p_smoke.add_argument("--top-k", type=int, default=10)
+ p_smoke.add_argument("--epochs", type=int, default=10)
+ p_smoke.add_argument("--chunk-size", type=int, default=200)
+ p_smoke.add_argument("--timeout", type=float, default=300.0)
+ p_smoke.add_argument(
+ "--backend",
+ choices=["graph", "lightgcn"],
+ default="graph",
+ help="Recommend backend (default: graph, no train)",
+ )
+ p_smoke.set_defaults(func=cmd_smoke)
+
+ p_eval = sub.add_parser(
+ "evaluate",
+ help="Leave-one-out HitRate/Recall@K (graph recommend or LightGCN)",
+ )
+ p_eval.add_argument("--dataset", type=str, default=None)
+ p_eval.add_argument("--run", type=str, default=None)
+ p_eval.add_argument("--ks", type=str, default="10,20")
+ p_eval.add_argument("--epochs", type=int, default=20)
+ p_eval.add_argument(
+ "--max-users",
+ type=int,
+ default=100,
+ help="Cap users for structured-ingest cost (MovieLens tip: start at 50–100)",
+ )
+ p_eval.add_argument("--min-interactions", type=int, default=5)
+ p_eval.add_argument("--chunk-size", type=int, default=200)
+ p_eval.add_argument("--timeout", type=float, default=3600.0)
+ p_eval.add_argument(
+ "--backend",
+ choices=["graph", "lightgcn"],
+ default="graph",
+ help="Recommend backend (default: graph — skips /recsys/train)",
+ )
+ p_eval.add_argument(
+ "--no-attribute-pref",
+ action="store_true",
+ help="Disable attribute_pref channel on graph backend",
+ )
+ p_eval.set_defaults(func=cmd_evaluate)
+
+ p_report = sub.add_parser("report", help="Rebuild report from eval.json")
+ p_report.add_argument("--run", type=str, required=True)
+ p_report.set_defaults(func=cmd_report)
+
+ return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = build_parser()
+ args = parser.parse_args(argv)
+ settings = Settings.load(args.env_file)
+ if args.brain:
+ settings.brain_id = args.brain.strip()
+ if settings.brain_id.startswith(("beam1m", "locomoconv")):
+ raise SystemExit(
+ f"Refusing brain_id={settings.brain_id!r}. Use demorecsys."
+ )
+ return int(args.func(args, settings))
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/benchmarks/recsys/client.py b/benchmarks/recsys/client.py
new file mode 100644
index 0000000..7eea33e
--- /dev/null
+++ b/benchmarks/recsys/client.py
@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from recsys.config import TERMINAL_TASK_STATUSES, Settings
+
+
+@dataclass
+class TimedResult:
+ data: Any
+ latency_ms: float
+
+
+@dataclass
+class BrainAPIClient:
+ settings: Settings
+ timeout: float = 120.0
+ max_retries: int = 5
+ _client: httpx.Client = field(init=False, repr=False)
+
+ def __post_init__(self) -> None:
+ self.settings.require_brainapi()
+ self._client = httpx.Client(
+ base_url=self.settings.brainapi_url,
+ headers={
+ "Authorization": f"Bearer {self.settings.brainpat_token}",
+ "Content-Type": "application/json",
+ "X-Brain-ID": self.settings.brain_id,
+ },
+ timeout=self.timeout,
+ )
+
+ def close(self) -> None:
+ self._client.close()
+
+ def __enter__(self) -> "BrainAPIClient":
+ return self
+
+ def __exit__(self, *args: object) -> None:
+ self.close()
+
+ def _request(
+ self,
+ method: str,
+ path: str,
+ *,
+ json: dict | None = None,
+ params: dict | None = None,
+ ) -> TimedResult:
+ last_error: Exception | None = None
+ for attempt in range(self.max_retries):
+ started = time.perf_counter()
+ try:
+ response = self._client.request(
+ method, path, json=json, params=params
+ )
+ latency_ms = (time.perf_counter() - started) * 1000
+ if response.status_code in (429, 500, 502, 503, 504):
+ wait = min(2**attempt * 0.5, 30)
+ time.sleep(wait)
+ last_error = httpx.HTTPStatusError(
+ f"HTTP {response.status_code}",
+ request=response.request,
+ response=response,
+ )
+ continue
+ if response.status_code >= 400:
+ detail = ""
+ try:
+ detail = response.text[:500]
+ except Exception:
+ detail = ""
+ if (
+ response.status_code == 404
+ and "/recsys/recommend" in path
+ and "user_unknown" not in detail
+ ):
+ raise RuntimeError(
+ f"GET {path} returned 404. Ensure the recsys-gnn "
+ f"plugin is loaded. body={detail!r}"
+ ) from None
+ response.raise_for_status()
+ if response.status_code == 204 or not response.content:
+ return TimedResult(data=None, latency_ms=latency_ms)
+ return TimedResult(data=response.json(), latency_ms=latency_ms)
+ except (httpx.TransportError, httpx.TimeoutException) as exc:
+ last_error = exc
+ wait = min(2**attempt * 0.5, 30)
+ time.sleep(wait)
+ raise RuntimeError(
+ f"Request failed after retries: {method} {path}: {last_error}"
+ )
+
+ def ingest_structured(
+ self,
+ triples: list[dict[str, Any]],
+ brain_id: str | None = None,
+ *,
+ mode: str = "deterministic",
+ ) -> TimedResult:
+ bid = brain_id or self.settings.brain_id
+ body = {
+ "mode": mode,
+ "brain_id": bid,
+ "data": triples,
+ }
+ return self._request("POST", "/ingest/structured", json=body)
+
+ def get_task(self, task_id: str, brain_id: str | None = None) -> TimedResult:
+ bid = brain_id or self.settings.brain_id
+ return self._request(
+ "GET", f"/tasks/{task_id}", params={"brain_id": bid}
+ )
+
+ def wait_for_task(
+ self,
+ task_id: str,
+ brain_id: str | None = None,
+ *,
+ timeout_s: float = 600.0,
+ poll_interval_s: float = 1.0,
+ ) -> TimedResult:
+ bid = brain_id or self.settings.brain_id
+ started = time.perf_counter()
+ while True:
+ result = self.get_task(task_id, bid)
+ status = (result.data or {}).get("status", "unknown")
+ if status in TERMINAL_TASK_STATUSES:
+ return TimedResult(
+ data=result.data,
+ latency_ms=(time.perf_counter() - started) * 1000,
+ )
+ if time.perf_counter() - started > timeout_s:
+ raise TimeoutError(
+ f"Task {task_id} did not finish within {timeout_s}s "
+ f"(last status={status})"
+ )
+ time.sleep(poll_interval_s)
+
+ def train_lightgcn(
+ self,
+ brain_id: str | None = None,
+ *,
+ epochs: int = 20,
+ embedding_dim: int = 64,
+ n_layers: int = 3,
+ wait: bool = True,
+ timeout_s: float = 600.0,
+ ) -> TimedResult:
+ bid = brain_id or self.settings.brain_id
+ body = {
+ "brain_id": bid,
+ "model": "lightgcn",
+ "epochs": epochs,
+ "embedding_dim": embedding_dim,
+ "n_layers": n_layers,
+ "wait": wait,
+ "timeout_s": timeout_s,
+ }
+ # Train can take a while; bump client timeout for this call.
+ old = self._client.timeout
+ self._client.timeout = timeout_s + 30.0
+ try:
+ return self._request("POST", "/recsys/train", json=body)
+ finally:
+ self._client.timeout = old
+
+ def recommend(
+ self,
+ user_id: str,
+ brain_id: str | None = None,
+ *,
+ top_k: int = 20,
+ exclude_seen: bool = True,
+ ) -> TimedResult:
+ bid = brain_id or self.settings.brain_id
+ params: dict[str, Any] = {
+ "user_id": user_id,
+ "top_k": top_k,
+ "brain_id": bid,
+ "exclude_seen": str(exclude_seen).lower(),
+ }
+ return self._request("GET", "/recsys/recommend", params=params)
+
+ def recommend_graph(
+ self,
+ user_id: str,
+ brain_id: str | None = None,
+ *,
+ top_k: int = 20,
+ exclude_seen: bool = True,
+ labels: list[str] | None = None,
+ include_attribute_pref: bool = True,
+ dampen_degree: bool = True,
+ recency_half_life_days: float | None = 90.0,
+ ) -> TimedResult:
+ bid = brain_id or self.settings.brain_id
+ target = str(user_id)
+ params: dict[str, Any] = {
+ "target": target,
+ "top_k": top_k,
+ "brain_id": bid,
+ "exclude_seen": str(exclude_seen).lower(),
+ "include_asymmetric": "true",
+ "include_multi_interest": "true",
+ "include_attribute_pref": str(include_attribute_pref).lower(),
+ "dampen_degree": str(dampen_degree).lower(),
+ "diversify": "true",
+ "labels": labels or ["PRODUCT"],
+ }
+ if recency_half_life_days is not None:
+ params["recency_half_life_days"] = recency_half_life_days
+ return self._request("GET", "/retrieve/recommend", params=params)
+
+ def features_rec_interaction(
+ self,
+ *,
+ user_id: str,
+ item_id: str,
+ behavior: str,
+ timestamp: str | None = None,
+ attributes: dict[str, Any] | None = None,
+ brain_id: str | None = None,
+ wait: bool = True,
+ timeout_s: float = 120.0,
+ seq: int = 1,
+ ) -> TimedResult:
+ bid = brain_id or self.settings.brain_id
+ body: dict[str, Any] = {
+ "user_id": user_id,
+ "item_id": item_id,
+ "behavior": behavior,
+ "brain_id": bid,
+ "wait": wait,
+ "timeout_s": timeout_s,
+ "seq": seq,
+ }
+ if timestamp:
+ body["timestamp"] = timestamp
+ if attributes:
+ body["attributes"] = attributes
+ return self._request("POST", "/features-rec/interactions", json=body)
diff --git a/benchmarks/recsys/config.py b/benchmarks/recsys/config.py
new file mode 100644
index 0000000..3b8cecb
--- /dev/null
+++ b/benchmarks/recsys/config.py
@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+BENCHMARKS_ROOT = Path(__file__).resolve().parent.parent
+DATA_DIR = BENCHMARKS_ROOT / "data"
+RUNS_DIR = BENCHMARKS_ROOT / "runs"
+DEFAULT_DATASET_PATH = DATA_DIR / "recsys_toy.jsonl"
+ML100K_DATASET_PATH = DATA_DIR / "movielens_100k.jsonl"
+DEFAULT_BRAIN_ID = "demorecsys"
+FORBIDDEN_BRAINS = frozenset(
+ {
+ "beam1m1clean",
+ "locomoconv26",
+ "locomoconv26clean",
+ "locomoconv26nostorm",
+ }
+)
+TERMINAL_TASK_STATUSES = frozenset({"completed", "failed", "partial_failed"})
+
+
+@dataclass
+class Settings:
+ brainapi_url: str
+ brainpat_token: str
+ dataset_path: Path
+ runs_dir: Path
+ brain_id: str
+
+ @classmethod
+ def load(cls, env_file: Path | None = None) -> "Settings":
+ if env_file is None:
+ env_file = BENCHMARKS_ROOT / ".env"
+ if env_file.exists():
+ load_dotenv(env_file, override=False)
+ else:
+ load_dotenv(override=False)
+
+ brain_id = (
+ os.getenv("RECSYS_BRAIN_ID", DEFAULT_BRAIN_ID) or DEFAULT_BRAIN_ID
+ ).strip()
+ if brain_id in FORBIDDEN_BRAINS or brain_id.startswith(
+ ("beam1m", "locomoconv")
+ ):
+ raise SystemExit(
+ f"Refusing brain_id={brain_id!r}. Use a dedicated recsys brain "
+ f"(default {DEFAULT_BRAIN_ID}). Never wipe eval memory brains."
+ )
+
+ return cls(
+ brainapi_url=os.getenv("BRAINAPI_URL", "http://localhost:8000").rstrip("/"),
+ brainpat_token=os.getenv("BRAINPAT_TOKEN", ""),
+ dataset_path=Path(
+ os.getenv("RECSYS_DATASET_PATH", str(DEFAULT_DATASET_PATH))
+ ),
+ runs_dir=Path(os.getenv("BENCH_RUNS_DIR", str(RUNS_DIR))),
+ brain_id=brain_id,
+ )
+
+ def require_brainapi(self) -> None:
+ if not self.brainpat_token:
+ raise SystemExit(
+ "BRAINPAT_TOKEN is required. Copy benchmarks/.env.example to "
+ "benchmarks/.env and set it."
+ )
diff --git a/benchmarks/recsys/dataset.py b/benchmarks/recsys/dataset.py
new file mode 100644
index 0000000..720aa7a
--- /dev/null
+++ b/benchmarks/recsys/dataset.py
@@ -0,0 +1,195 @@
+"""MovieLens download + normalize to recsys interaction JSONL."""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.request import urlretrieve
+
+from recsys.config import DATA_DIR
+
+ML100K_URL = "https://files.grouplens.org/datasets/movielens/ml-100k.zip"
+ML100K_JSONL = DATA_DIR / "movielens_100k.jsonl"
+ML100K_CACHE_DIR = DATA_DIR / "movielens" / "ml-100k"
+
+GENRE_NAMES = [
+ "unknown",
+ "Action",
+ "Adventure",
+ "Animation",
+ "Children",
+ "Comedy",
+ "Crime",
+ "Documentary",
+ "Drama",
+ "Fantasy",
+ "Film-Noir",
+ "Horror",
+ "Musical",
+ "Mystery",
+ "Romance",
+ "Sci-Fi",
+ "Thriller",
+ "War",
+ "Western",
+]
+
+
+def download_ml100k(
+ *,
+ url: str = ML100K_URL,
+ cache_dir: Path = ML100K_CACHE_DIR,
+ force: bool = False,
+) -> Path:
+ """Download and extract ml-100k; returns directory containing u.data."""
+ cache_dir.mkdir(parents=True, exist_ok=True)
+ data_file = cache_dir / "u.data"
+ if data_file.exists() and not force:
+ return cache_dir
+
+ zip_path = cache_dir.parent / "ml-100k.zip"
+ if force or not zip_path.exists():
+ zip_path.parent.mkdir(parents=True, exist_ok=True)
+ urlretrieve(url, zip_path)
+
+ with zipfile.ZipFile(zip_path, "r") as zf:
+ for member in zf.namelist():
+ # archive paths like ml-100k/u.data
+ name = Path(member).name
+ if name in {"u.data", "u.item", "u.user", "README"}:
+ target = cache_dir / name
+ with zf.open(member) as src, target.open("wb") as dst:
+ dst.write(src.read())
+ if not data_file.exists():
+ raise FileNotFoundError(f"u.data missing after extract under {cache_dir}")
+ return cache_dir
+
+
+def _load_item_meta(item_path: Path) -> dict[str, dict[str, str]]:
+ meta: dict[str, dict[str, str]] = {}
+ if not item_path.exists():
+ return meta
+ # Latin-1: GroupLens classic files are not UTF-8
+ for line in item_path.read_text(encoding="latin-1").splitlines():
+ parts = line.split("|")
+ if len(parts) < 24:
+ continue
+ item_id = parts[0].strip()
+ title = parts[1].strip()
+ flags = parts[5:24]
+ genres = [
+ GENRE_NAMES[i]
+ for i, flag in enumerate(flags)
+ if flag == "1" and i < len(GENRE_NAMES) and GENRE_NAMES[i] != "unknown"
+ ]
+ meta[item_id] = {
+ "name": title or f"movie-{item_id}",
+ "category": genres[0] if genres else "unknown",
+ }
+ return meta
+
+
+def ratings_to_interactions(
+ cache_dir: Path,
+ *,
+ min_rating: float = 1.0,
+) -> list[dict[str, Any]]:
+ """
+ Convert u.data → interaction dicts.
+
+ All ratings >= min_rating become positive implicit edges (behavior=purchase),
+ matching standard LightGCN implicit-feedback setups.
+ """
+ item_meta = _load_item_meta(cache_dir / "u.item")
+ rows: list[dict[str, Any]] = []
+ for line in (cache_dir / "u.data").read_text(encoding="utf-8").splitlines():
+ parts = line.strip().split("\t")
+ if len(parts) < 4:
+ continue
+ user_id, item_id, rating_s, ts_s = parts[0], parts[1], parts[2], parts[3]
+ try:
+ rating = float(rating_s)
+ ts = int(ts_s)
+ except ValueError:
+ continue
+ if rating < min_rating:
+ continue
+ meta = item_meta.get(item_id, {})
+ rows.append(
+ {
+ "user_id": f"mlu{user_id}",
+ "item_id": f"mlm{item_id}",
+ "behavior": "purchase",
+ "timestamp": datetime.fromtimestamp(ts, tz=timezone.utc).strftime(
+ "%Y-%m-%dT%H:%M:%SZ"
+ ),
+ "rating": rating,
+ "category": meta.get("category", "unknown"),
+ "title": meta.get("name"),
+ }
+ )
+ rows.sort(key=lambda r: (r["user_id"], r["timestamp"], r["item_id"]))
+ return rows
+
+
+def write_jsonl(rows: list[dict[str, Any]], path: Path) -> Path:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with path.open("w", encoding="utf-8") as fh:
+ for row in rows:
+ fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+ return path
+
+
+def prepare_ml100k(
+ *,
+ out_path: Path = ML100K_JSONL,
+ force: bool = False,
+ min_rating: float = 1.0,
+) -> Path:
+ if out_path.exists() and out_path.stat().st_size > 0 and not force:
+ return out_path
+ cache = download_ml100k(force=force)
+ rows = ratings_to_interactions(cache, min_rating=min_rating)
+ return write_jsonl(rows, out_path)
+
+
+def dataset_stats(rows: list[dict[str, Any]]) -> dict[str, Any]:
+ users = {str(r["user_id"]) for r in rows}
+ items = {str(r["item_id"]) for r in rows}
+ per_user = Counter(str(r["user_id"]) for r in rows)
+ counts = list(per_user.values())
+ return {
+ "n_interactions": len(rows),
+ "n_users": len(users),
+ "n_items": len(items),
+ "interactions_per_user_min": min(counts) if counts else 0,
+ "interactions_per_user_max": max(counts) if counts else 0,
+ "interactions_per_user_mean": (
+ sum(counts) / len(counts) if counts else 0.0
+ ),
+ }
+
+
+def filter_interactions(
+ rows: list[dict[str, Any]],
+ *,
+ min_interactions: int = 5,
+ max_users: int | None = None,
+) -> list[dict[str, Any]]:
+ """Keep users with ≥ min_interactions; optionally take first max_users by id."""
+ by_user: dict[str, list[dict[str, Any]]] = {}
+ for row in rows:
+ by_user.setdefault(str(row["user_id"]), []).append(row)
+ eligible = sorted(
+ uid for uid, xs in by_user.items() if len(xs) >= min_interactions
+ )
+ if max_users is not None:
+ eligible = eligible[: max(0, int(max_users))]
+ keep = set(eligible)
+ out = [r for r in rows if str(r["user_id"]) in keep]
+ out.sort(key=lambda r: (str(r["user_id"]), r.get("timestamp") or "", str(r["item_id"])))
+ return out
diff --git a/benchmarks/recsys/evaluate.py b/benchmarks/recsys/evaluate.py
new file mode 100644
index 0000000..356005f
--- /dev/null
+++ b/benchmarks/recsys/evaluate.py
@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import json
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from recsys.client import BrainAPIClient
+from recsys.config import Settings
+from recsys.mapping import (
+ interactions_to_triples,
+ item_uuid,
+ leave_one_out_splits,
+)
+
+
+def load_interactions(path: Path) -> list[dict[str, Any]]:
+ rows: list[dict[str, Any]] = []
+ for line in path.read_text(encoding="utf-8").splitlines():
+ line = line.strip()
+ if not line:
+ continue
+ rows.append(json.loads(line))
+ return rows
+
+
+def ensure_run_dir(settings: Settings, run_id: str | None = None) -> tuple[str, Path]:
+ stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+ rid = run_id or f"recsys-{stamp}"
+ run_dir = settings.runs_dir / rid
+ run_dir.mkdir(parents=True, exist_ok=True)
+ return rid, run_dir
+
+
+def recommendation_hits_holdout(
+ items: list[dict[str, Any]],
+ *,
+ holdout_item_id: str,
+ holdout_item_uuid: str,
+ k: int,
+) -> bool:
+ targets = {
+ holdout_item_id,
+ holdout_item_uuid,
+ item_uuid(holdout_item_id),
+ holdout_item_id.removeprefix("item:") if holdout_item_id.startswith("item:") else holdout_item_id,
+ }
+ for item in items[:k]:
+ if not isinstance(item, dict):
+ continue
+ node = item.get("node") if isinstance(item.get("node"), dict) else {}
+ cand = {
+ str(item.get("item_id") or ""),
+ str(item.get("uuid") or ""),
+ str(item.get("id") or ""),
+ str(node.get("uuid") or ""),
+ str(node.get("name") or ""),
+ }
+ if cand & targets:
+ return True
+ return False
+
+
+def _normalize_recommend_items(payload: dict[str, Any] | None) -> list[dict[str, Any]]:
+ if not payload:
+ return []
+ items = payload.get("items") or payload.get("recommendations") or []
+ if not isinstance(items, list):
+ return []
+ return [x for x in items if isinstance(x, dict)]
+
+
+def popularity_baseline_hits(
+ train_rows: list[dict[str, Any]],
+ splits: list[dict[str, Any]],
+ *,
+ ks: tuple[int, ...],
+) -> dict[str, float]:
+ freq = Counter(str(r["item_id"]) for r in train_rows)
+ ranked = [item for item, _c in freq.most_common()]
+ hit_counts = {k: 0 for k in ks}
+ for split in splits:
+ holdout = str(split["holdout_item_id"])
+ for k in ks:
+ if holdout in ranked[:k]:
+ hit_counts[k] += 1
+ n = max(1, len(splits))
+ return {f"popularity_hit_rate@{k}": hit_counts[k] / n for k in ks}
+
+
+def ingest_train_interactions(
+ client: BrainAPIClient,
+ interactions: list[dict[str, Any]],
+ *,
+ timeout_s: float = 600.0,
+ chunk_size: int = 200,
+) -> dict[str, Any]:
+ triples = interactions_to_triples(interactions, include_catalog=True)
+ if not triples:
+ raise RuntimeError("No triples to ingest")
+
+ task_ids: list[str] = []
+ last_waited: dict[str, Any] | None = None
+ total_latency = 0.0
+ chunk = max(1, int(chunk_size))
+ for start in range(0, len(triples), chunk):
+ batch = triples[start : start + chunk]
+ submitted = client.ingest_structured(batch)
+ task_id = (submitted.data or {}).get("task_id")
+ if not task_id:
+ raise RuntimeError(f"No task_id from structured ingest: {submitted.data}")
+ waited = client.wait_for_task(task_id, timeout_s=timeout_s)
+ status = (waited.data or {}).get("status")
+ if status not in {"completed", "partial_failed"}:
+ raise RuntimeError(
+ f"Structured ingest chunk failed: status={status} task={task_id}"
+ )
+ task_ids.append(task_id)
+ last_waited = waited.data
+ total_latency += waited.latency_ms
+
+ return {
+ "task_id": task_ids[-1],
+ "task_ids": task_ids,
+ "status": "completed",
+ "n_triples": len(triples),
+ "n_interactions": len(interactions),
+ "n_chunks": len(task_ids),
+ "latency_ms": total_latency,
+ "task": last_waited,
+ }
+
+
+def evaluate_leave_one_out(
+ client: BrainAPIClient,
+ interactions: list[dict[str, Any]],
+ *,
+ ks: tuple[int, ...] = (10, 20),
+ timeout_s: float = 600.0,
+ epochs: int = 20,
+ ingest_chunk_size: int = 200,
+ dataset_name: str | None = None,
+ backend: str = "graph",
+ include_attribute_pref: bool = True,
+) -> dict[str, Any]:
+ backend = (backend or "graph").strip().lower()
+ if backend not in {"graph", "lightgcn"}:
+ raise ValueError(f"Unknown backend {backend!r}; use graph or lightgcn")
+
+ splits = leave_one_out_splits(interactions)
+ if not splits:
+ raise RuntimeError("No users with ≥2 interactions for leave-one-out eval")
+
+ train_rows = [row for split in splits for row in split["train"]]
+ ingest_info = ingest_train_interactions(
+ client,
+ train_rows,
+ timeout_s=timeout_s,
+ chunk_size=ingest_chunk_size,
+ )
+ if ingest_info["status"] not in {"completed", "partial_failed"}:
+ raise RuntimeError(
+ f"Structured ingest failed: status={ingest_info['status']} "
+ f"task={ingest_info['task_id']}"
+ )
+
+ train_payload: dict[str, Any] = {"status": "skipped", "backend": backend}
+ if backend == "lightgcn":
+ train_result = client.train_lightgcn(
+ epochs=epochs, wait=True, timeout_s=timeout_s
+ )
+ train_payload = train_result.data or {}
+ train_status = train_payload.get("status")
+ nested = (train_payload.get("task") or {}).get("status")
+ if train_status == "timeout" or (
+ train_status not in {"completed"} and nested != "completed"
+ ):
+ hint = ""
+ if train_status == "timeout" or nested in {None, "queued"}:
+ hint = (
+ " Train stayed queued — Celery likely missing queue recsys_gnn. "
+ "Harness uses wait=true (in-process train) after plugin sync/restart; "
+ "re-sync plugins/recsys-gnn and restart the API."
+ )
+ raise RuntimeError(f"LightGCN train failed: {train_payload}.{hint}")
+
+ max_k = max(ks)
+ per_user: list[dict[str, Any]] = []
+ hit_counts = {k: 0 for k in ks}
+ model_name = "graph-recommend" if backend == "graph" else "lightgcn"
+
+ for split in splits:
+ user_id = split["user_id"]
+ holdout_id = split["holdout_item_id"]
+ holdout_uuid = split["holdout_item_uuid"]
+ try:
+ if backend == "graph":
+ result = client.recommend_graph(
+ user_id,
+ top_k=max_k,
+ exclude_seen=True,
+ include_attribute_pref=include_attribute_pref,
+ )
+ else:
+ result = client.recommend(
+ user_id, top_k=max_k, exclude_seen=True
+ )
+ payload = result.data or {}
+ items = _normalize_recommend_items(payload)
+ error = None
+ if payload.get("status") not in (None, "ok") and backend == "lightgcn":
+ error = str(payload.get("message") or payload.get("status"))
+ except Exception as exc: # noqa: BLE001
+ items = []
+ error = str(exc)
+ result = None
+
+ hits = {
+ k: recommendation_hits_holdout(
+ items,
+ holdout_item_id=holdout_id,
+ holdout_item_uuid=holdout_uuid,
+ k=k,
+ )
+ for k in ks
+ }
+ for k, hit in hits.items():
+ if hit:
+ hit_counts[k] += 1
+
+ per_user.append(
+ {
+ "user_id": user_id,
+ "holdout_item_id": holdout_id,
+ "holdout_item_uuid": holdout_uuid,
+ "n_train": len(split["train"]),
+ "n_recs": len(items),
+ "hits": hits,
+ "latency_ms": getattr(result, "latency_ms", None),
+ "error": error,
+ }
+ )
+
+ n_users = len(per_user)
+ metrics = {f"hit_rate@{k}": hit_counts[k] / n_users for k in ks}
+ metrics.update({f"recall@{k}": hit_counts[k] / n_users for k in ks})
+ metrics.update(popularity_baseline_hits(train_rows, splits, ks=ks))
+
+ return {
+ "brain_id": client.settings.brain_id,
+ "model": model_name,
+ "backend": backend,
+ "dataset": dataset_name,
+ "n_users": n_users,
+ "ks": list(ks),
+ "ingest": ingest_info,
+ "train": train_payload,
+ "metrics": metrics,
+ "per_user": per_user,
+ }
diff --git a/benchmarks/recsys/mapping.py b/benchmarks/recsys/mapping.py
new file mode 100644
index 0000000..faad04a
--- /dev/null
+++ b/benchmarks/recsys/mapping.py
@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Iterable, Sequence
+
+
+BEHAVIOR_MAP: dict[str, tuple[str, str]] = {
+ "purchase": ("Purchase", "TARGETED"),
+ "purchased": ("Purchase", "TARGETED"),
+ "buy": ("Purchase", "TARGETED"),
+ "bought": ("Purchase", "TARGETED"),
+ "view": ("View", "TARGETED"),
+ "viewed": ("View", "TARGETED"),
+ "click": ("View", "TARGETED"),
+ "clicked": ("View", "TARGETED"),
+ "cart": ("AddToCart", "TARGETED"),
+ "add_to_cart": ("AddToCart", "TARGETED"),
+ "added_to_cart": ("AddToCart", "TARGETED"),
+ "addtocart": ("AddToCart", "TARGETED"),
+}
+
+
+def user_uuid(user_id: str) -> str:
+ return f"user:{user_id}"
+
+
+def item_uuid(item_id: str) -> str:
+ return f"item:{item_id}"
+
+
+def event_uuid(user_id: str, item_id: str, seq: int) -> str:
+ return f"evt:{user_id}:{item_id}:{seq}"
+
+
+def rel_uuid(user_id: str, item_id: str, kind: str, seq: int) -> str:
+ return f"rel:{user_id}:{item_id}:{kind}:{seq}"
+
+
+def normalize_behavior(behavior: str) -> tuple[str, str]:
+ key = (behavior or "").strip().lower().replace("-", "_").replace(" ", "_")
+ if key in BEHAVIOR_MAP:
+ return BEHAVIOR_MAP[key]
+ label = (behavior or "Interaction").strip() or "Interaction"
+ return (label[:1].upper() + label[1:], "TARGETED")
+
+
+def format_happened_at(timestamp: str | None) -> str | None:
+ if not timestamp:
+ return None
+ raw = timestamp.strip()
+ if not raw:
+ return None
+ if len(raw) == 10 and raw[2] == "/" and raw[5] == "/":
+ return raw
+ for fmt in (
+ "%Y-%m-%dT%H:%M:%S%z",
+ "%Y-%m-%dT%H:%M:%S.%f%z",
+ "%Y-%m-%dT%H:%M:%SZ",
+ "%Y-%m-%dT%H:%M:%S",
+ "%Y-%m-%d %H:%M:%S",
+ "%Y-%m-%d",
+ "%m/%d/%Y",
+ "%d/%m/%Y",
+ ):
+ try:
+ parsed = datetime.strptime(
+ raw.replace("Z", "+0000") if fmt.endswith("%z") and raw.endswith("Z") else raw,
+ fmt,
+ )
+ return parsed.strftime("%m/%d/%Y")
+ except ValueError:
+ continue
+ try:
+ parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+ return parsed.strftime("%m/%d/%Y")
+ except ValueError:
+ return raw
+
+
+def parse_timestamp_for_sort(timestamp: str | None) -> float:
+ if not timestamp:
+ return 0.0
+ raw = timestamp.strip()
+ formatted = format_happened_at(raw)
+ if formatted and len(formatted) == 10 and formatted[2] == "/":
+ try:
+ return datetime.strptime(formatted, "%m/%d/%Y").replace(tzinfo=timezone.utc).timestamp()
+ except ValueError:
+ pass
+ try:
+ return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
+ except ValueError:
+ return 0.0
+
+
+def interaction_to_triple(
+ interaction: dict[str, Any],
+ *,
+ seq: int,
+) -> dict[str, Any]:
+ user_id = str(interaction["user_id"])
+ item_id = str(interaction["item_id"])
+ event_name, edge_name = normalize_behavior(str(interaction.get("behavior") or "purchase"))
+ happened_at = format_happened_at(
+ interaction.get("timestamp") or interaction.get("ts")
+ )
+ event_node: dict[str, Any] = {
+ "name": event_name,
+ "type": "EVENT",
+ "uuid": event_uuid(user_id, item_id, seq),
+ }
+ if happened_at:
+ event_node["happened_at"] = happened_at
+
+ return {
+ "subject": {
+ "name": user_id,
+ "type": "USER",
+ "uuid": user_uuid(user_id),
+ },
+ "subj_event": {
+ "name": "MADE",
+ "uuid": rel_uuid(user_id, item_id, "made", seq),
+ },
+ "event": event_node,
+ "event_obj": {
+ "name": edge_name,
+ "uuid": rel_uuid(user_id, item_id, "tgt", seq),
+ },
+ "object": {
+ "name": item_id,
+ "type": "PRODUCT",
+ "uuid": item_uuid(item_id),
+ },
+ }
+
+
+def catalog_triple(
+ item_id: str,
+ *,
+ category: str | None = None,
+ brand: str | None = None,
+ color: str | None = None,
+ material: str | None = None,
+ seq: int = 0,
+) -> list[dict[str, Any]]:
+ triples: list[dict[str, Any]] = []
+ facets = (
+ ("category", category, "CATEGORY", "Categorized", "IN_CATEGORY", "cat"),
+ ("brand", brand, "BRAND", "Branded", "OF_BRAND", "brand"),
+ ("color", color, "COLOR", "HasColor", "OF_COLOR", "color"),
+ ("material", material, "MATERIAL", "HasMaterial", "OF_MATERIAL", "mat"),
+ )
+ for i, (facet, value, label, event_name, edge_name, kind) in enumerate(facets):
+ if not value:
+ continue
+ val = str(value)
+ triples.append(
+ {
+ "subject": {
+ "name": item_id,
+ "type": "PRODUCT",
+ "uuid": item_uuid(item_id),
+ },
+ "subj_event": {
+ "name": "HAS",
+ "uuid": rel_uuid(item_id, val, f"{kind}_has", seq + i),
+ },
+ "event": {
+ "name": event_name,
+ "type": "EVENT",
+ "uuid": event_uuid(item_id, f"{kind}:{val}", seq + i),
+ },
+ "event_obj": {
+ "name": edge_name,
+ "uuid": rel_uuid(item_id, val, kind, seq + i),
+ },
+ "object": {
+ "name": val,
+ "type": label,
+ "uuid": f"attr:{facet}:{val.strip().lower()}",
+ },
+ }
+ )
+ return triples
+
+
+def interactions_to_triples(
+ interactions: Sequence[dict[str, Any]],
+ *,
+ include_catalog: bool = True,
+ seq_start: int = 1,
+) -> list[dict[str, Any]]:
+ triples: list[dict[str, Any]] = []
+ seen_catalog: set[tuple[str, str | None, str | None, str | None, str | None]] = set()
+ for i, row in enumerate(interactions):
+ seq = seq_start + i
+ triples.append(interaction_to_triple(row, seq=seq))
+ if include_catalog:
+ item_id = str(row["item_id"])
+ category = row.get("category")
+ brand = row.get("brand")
+ color = row.get("color")
+ material = row.get("material")
+ key = (
+ item_id,
+ category,
+ brand,
+ color,
+ material,
+ )
+ if key not in seen_catalog and (category or brand or color or material):
+ seen_catalog.add(key)
+ triples.extend(
+ catalog_triple(
+ item_id,
+ category=str(category) if category else None,
+ brand=str(brand) if brand else None,
+ color=str(color) if color else None,
+ material=str(material) if material else None,
+ seq=seq,
+ )
+ )
+ return triples
+
+
+def structured_ingest_body(
+ triples: Sequence[dict[str, Any]],
+ *,
+ brain_id: str = "demorecsys",
+ mode: str = "deterministic",
+) -> dict[str, Any]:
+ return {
+ "mode": mode,
+ "brain_id": brain_id,
+ "data": list(triples),
+ }
+
+
+def group_interactions_by_user(
+ interactions: Iterable[dict[str, Any]],
+) -> dict[str, list[dict[str, Any]]]:
+ by_user: dict[str, list[dict[str, Any]]] = {}
+ for row in interactions:
+ uid = str(row["user_id"])
+ by_user.setdefault(uid, []).append(row)
+ for uid, rows in by_user.items():
+ rows.sort(
+ key=lambda r: (
+ parse_timestamp_for_sort(r.get("timestamp") or r.get("ts")),
+ str(r.get("item_id") or ""),
+ )
+ )
+ return by_user
+
+
+def leave_one_out_splits(
+ interactions: Sequence[dict[str, Any]],
+) -> list[dict[str, Any]]:
+ splits: list[dict[str, Any]] = []
+ for user_id, rows in group_interactions_by_user(interactions).items():
+ if len(rows) < 2:
+ continue
+ train = rows[:-1]
+ holdout = rows[-1]
+ splits.append(
+ {
+ "user_id": user_id,
+ "train": train,
+ "holdout": holdout,
+ "holdout_item_id": str(holdout["item_id"]),
+ "holdout_item_uuid": item_uuid(str(holdout["item_id"])),
+ }
+ )
+ return splits
diff --git a/benchmarks/recsys/report.py b/benchmarks/recsys/report.py
new file mode 100644
index 0000000..437e154
--- /dev/null
+++ b/benchmarks/recsys/report.py
@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+from recsys.config import BENCHMARKS_ROOT
+
+console = Console()
+
+REPORTS_PATH = BENCHMARKS_ROOT / "REPORTS.json"
+_BENCHMARK_ID = "recsys"
+_BENCHMARK_NAME = "RecSys (graph recommend / LightGCN)"
+_REPORTS_DESCRIPTION = (
+ "BrainAPI benchmark results. Top published scores across suites. "
+ "Updated when a suite evaluate/report completes successfully."
+)
+
+
+def _git_sha() -> str | None:
+ try:
+ out = subprocess.check_output(
+ ["git", "rev-parse", "HEAD"],
+ cwd=BENCHMARKS_ROOT.parent,
+ stderr=subprocess.DEVNULL,
+ text=True,
+ )
+ return out.strip() or None
+ except Exception:
+ return None
+
+
+def build_report(run_dir: Path, eval_result: dict[str, Any]) -> dict[str, Any]:
+ metrics = eval_result.get("metrics") or {}
+ status = "ok"
+ if (eval_result.get("ingest") or {}).get("status") not in {
+ "completed",
+ "partial_failed",
+ }:
+ status = "failed"
+ train = eval_result.get("train") or {}
+ backend = (eval_result.get("backend") or "").lower()
+ model = eval_result.get("model") or "lightgcn"
+ train_ok = (
+ train.get("status") == "skipped"
+ or backend == "graph"
+ or model == "graph-recommend"
+ or train.get("status") == "completed"
+ or ((train.get("task") or {}).get("status") == "completed")
+ )
+ if not train_ok:
+ status = "failed"
+ if not eval_result.get("n_users"):
+ status = "failed"
+
+ protocol = (
+ "held-out next-item: structured ingest → GET /retrieve/recommend "
+ "(train-free graph)"
+ if backend == "graph" or model == "graph-recommend"
+ else (
+ "held-out next-item: structured ingest → POST /recsys/train "
+ "(LightGCN) → GET /recsys/recommend"
+ )
+ )
+
+ report = {
+ "suite": _BENCHMARK_ID,
+ "status": status,
+ "run_id": run_dir.name,
+ "brain_id": eval_result.get("brain_id"),
+ "model": model,
+ "backend": eval_result.get("backend"),
+ "dataset": eval_result.get("dataset"),
+ "n_users": eval_result.get("n_users"),
+ "ks": eval_result.get("ks"),
+ "hit_rate@10": metrics.get("hit_rate@10"),
+ "hit_rate@20": metrics.get("hit_rate@20"),
+ "recall@10": metrics.get("recall@10"),
+ "recall@20": metrics.get("recall@20"),
+ "popularity_hit_rate@10": metrics.get("popularity_hit_rate@10"),
+ "popularity_hit_rate@20": metrics.get("popularity_hit_rate@20"),
+ "metrics": metrics,
+ "ingest": eval_result.get("ingest"),
+ "train": train,
+ "git_sha": _git_sha(),
+ "recorded_at": datetime.now(timezone.utc).isoformat(),
+ "protocol": protocol,
+ }
+ return report
+
+
+def write_report(run_dir: Path, eval_result: dict[str, Any]) -> dict[str, Any]:
+ report = build_report(run_dir, eval_result)
+ (run_dir / "eval.json").write_text(
+ json.dumps(eval_result, indent=2) + "\n", encoding="utf-8"
+ )
+ (run_dir / "report.json").write_text(
+ json.dumps(report, indent=2) + "\n", encoding="utf-8"
+ )
+ md = render_markdown(report)
+ (run_dir / "report.md").write_text(md, encoding="utf-8")
+ if report.get("status") == "ok":
+ update_reports_json(report)
+ return report
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+ lines = [
+ f"# RecSys report — `{report.get('run_id')}`",
+ "",
+ f"- status: **{report.get('status')}**",
+ f"- model: `{report.get('model')}`",
+ f"- dataset: `{report.get('dataset')}`",
+ f"- brain_id: `{report.get('brain_id')}`",
+ f"- n_users: {report.get('n_users')}",
+ f"- HitRate@10: {report.get('hit_rate@10')}",
+ f"- HitRate@20: {report.get('hit_rate@20')}",
+ f"- Recall@10: {report.get('recall@10')}",
+ f"- Recall@20: {report.get('recall@20')}",
+ f"- popularity HitRate@10: {report.get('popularity_hit_rate@10')}",
+ f"- popularity HitRate@20: {report.get('popularity_hit_rate@20')}",
+ "",
+ "Never mutate LoCoMo / BEAM / LongMemEval brains or their ledger rows.",
+ "",
+ ]
+ return "\n".join(lines)
+
+
+def print_report_table(report: dict[str, Any]) -> None:
+ table = Table(title=f"RecSys {report.get('run_id')}")
+ table.add_column("metric")
+ table.add_column("value")
+ for key in (
+ "status",
+ "model",
+ "dataset",
+ "brain_id",
+ "n_users",
+ "hit_rate@10",
+ "hit_rate@20",
+ "recall@10",
+ "recall@20",
+ "popularity_hit_rate@10",
+ "popularity_hit_rate@20",
+ ):
+ table.add_row(key, str(report.get(key)))
+ console.print(table)
+
+
+def entry_from_report(report: dict[str, Any]) -> dict[str, Any] | None:
+ if report.get("status") != "ok":
+ return None
+ n_users = int(report.get("n_users") or 0)
+ if n_users < 1:
+ return None
+ return {
+ "run_id": report.get("run_id"),
+ "brain": report.get("brain_id"),
+ "model": report.get("model") or "lightgcn",
+ "dataset": report.get("dataset"),
+ "n_users": n_users,
+ "hit_rate@10": report.get("hit_rate@10"),
+ "hit_rate@20": report.get("hit_rate@20"),
+ "recall@10": report.get("recall@10"),
+ "recall@20": report.get("recall@20"),
+ "popularity_hit_rate@10": report.get("popularity_hit_rate@10"),
+ "popularity_hit_rate@20": report.get("popularity_hit_rate@20"),
+ "git_sha": report.get("git_sha"),
+ "report_path": f"runs/{report.get('run_id')}/report.json",
+ "recorded_at": report.get("recorded_at"),
+ }
+
+
+def _empty_reports_ledger() -> dict[str, Any]:
+ return {
+ "schema_version": 2,
+ "updated_at": datetime.now(timezone.utc).isoformat(),
+ "description": _REPORTS_DESCRIPTION,
+ "benchmarks": {},
+ }
+
+
+def update_reports_json(report: dict[str, Any]) -> None:
+ entry = entry_from_report(report)
+ if entry is None:
+ return
+
+ if REPORTS_PATH.exists():
+ data = json.loads(REPORTS_PATH.read_text(encoding="utf-8"))
+ else:
+ data = _empty_reports_ledger()
+
+ suite = data.setdefault("benchmarks", {}).setdefault(
+ _BENCHMARK_ID,
+ {"name": _BENCHMARK_NAME, "leaderboard": []},
+ )
+ leaderboard = list(suite.get("leaderboard") or [])
+ run_id = entry["run_id"]
+ lb_idx = next(
+ (i for i, row in enumerate(leaderboard) if row.get("run_id") == run_id),
+ None,
+ )
+ if lb_idx is not None:
+ leaderboard[lb_idx] = entry
+ else:
+ leaderboard.append(entry)
+
+ suite["name"] = _BENCHMARK_NAME
+ suite["leaderboard"] = leaderboard
+ data["benchmarks"][_BENCHMARK_ID] = suite
+ data["updated_at"] = datetime.now(timezone.utc).isoformat()
+ data["description"] = data.get("description") or _REPORTS_DESCRIPTION
+
+ REPORTS_PATH.parent.mkdir(parents=True, exist_ok=True)
+ fd, tmp_name = tempfile.mkstemp(
+ prefix="REPORTS.",
+ suffix=".json.tmp",
+ dir=str(REPORTS_PATH.parent),
+ )
+ try:
+ with open(fd, "w", encoding="utf-8") as fh:
+ json.dump(data, fh, indent=2)
+ fh.write("\n")
+ Path(tmp_name).replace(REPORTS_PATH)
+ finally:
+ tmp_path = Path(tmp_name)
+ if tmp_path.exists():
+ tmp_path.unlink(missing_ok=True)
diff --git a/benchmarks/synergies/__init__.py b/benchmarks/synergies/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/benchmarks/synergies/report.py b/benchmarks/synergies/report.py
new file mode 100644
index 0000000..d043667
--- /dev/null
+++ b/benchmarks/synergies/report.py
@@ -0,0 +1,61 @@
+# Synergies / recommend structural tripwire
+#
+# HTTP-optional local metrics helpers only. Does **not** upsert
+# benchmarks/REPORTS.json (LoCoMo / LongMemEval / BEAM).
+#
+# Usage (from repo root, after retrieving recommendations for a seed):
+# PYTHONPATH=. poetry run python -m benchmarks.synergies.report \
+# --labels PRODUCT,PHONE PRODUCT,CASE CATEGORY --distances 1 2 3
+#
+# Prefer dedicated brains such as `demorecsys`, never wipe beam1m1clean / locomoconv26*.
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+ sys.path.insert(0, str(ROOT))
+
+from src.core.search.synergy_metrics import summarize_recommendation_list
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description="Structural synergies tripwire report")
+ parser.add_argument(
+ "--labels",
+ nargs="+",
+ required=True,
+ help="Space-separated label sets; within a set use commas (e.g. PRODUCT,PHONE)",
+ )
+ parser.add_argument(
+ "--distances",
+ nargs="*",
+ type=int,
+ default=[],
+ help="Optional hop distances aligned with --labels",
+ )
+ parser.add_argument("--out", type=Path, default=None)
+ args = parser.parse_args(argv)
+
+ label_sets = [item.split(",") for item in args.labels]
+ distances = args.distances or [1] * len(label_sets)
+ if len(distances) != len(label_sets):
+ distances = (distances + [1] * len(label_sets))[: len(label_sets)]
+
+ report = summarize_recommendation_list(label_sets, distances)
+ report["suite"] = "synergies-structural"
+ report["ledger"] = None
+ text = json.dumps(report, indent=2)
+ print(text)
+ if args.out:
+ args.out.parent.mkdir(parents=True, exist_ok=True)
+ args.out.write_text(text + "\n", encoding="utf-8")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/console/src/components/Workbench.tsx b/console/src/components/Workbench.tsx
index 039a3e1..f6011a9 100644
--- a/console/src/components/Workbench.tsx
+++ b/console/src/components/Workbench.tsx
@@ -90,13 +90,7 @@ export function Workbench({
}) {
return (
<div className="flex min-h-0 flex-1 flex-col">
- <div
- className={
- flush
- ? "border-b border-lumen-border px-4 py-3 sm:px-6"
- : "px-4 pt-6 sm:px-6"
- }
- >
+ <div className={"mb-4 px-4 pt-6 sm:px-6"}>
<PageHeader className="sm:items-center">
<PageHeaderContent>
<PageHeaderTitle>{title}</PageHeaderTitle>
@@ -112,14 +106,14 @@ export function Workbench({
<div
className={
flush
- ? "flex min-h-0 flex-1"
+ ? "flex min-h-0 flex-1 px-4 pb-4 sm:px-6"
: "mt-4 flex min-h-0 flex-1 gap-0 px-4 pb-6 sm:px-6"
}
>
<div
className={
flush
- ? "min-h-0 min-w-0 flex-1 overflow-auto"
+ ? "flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden"
: "min-h-0 min-w-0 flex-1 overflow-auto border border-lumen-border bg-lumen-surface"
}
>
@@ -185,7 +179,11 @@ export function JsonInspector({
onClose: () => void;
}) {
return (
- <DetailInspector title={title} subtitle={subtitle} onClose={onClose}>
+ <DetailInspector
+ title={title}
+ subtitle={subtitle}
+ onClose={onClose}
+ >
<CodeBlock className="text-[11px] leading-relaxed">
{JSON.stringify(value, null, 2)}
</CodeBlock>
diff --git a/console/src/index.css b/console/src/index.css
index 2a250f2..b2ba6ed 100644
--- a/console/src/index.css
+++ b/console/src/index.css
@@ -33,3 +33,34 @@ body {
flex-direction: column;
overflow: hidden;
}
+
+.graph-explorer--fill {
+ display: flex;
+ min-height: 0;
+ flex: 1;
+ flex-direction: column;
+ width: 100%;
+ border-radius: 0;
+ box-shadow: none;
+}
+
+.graph-explorer--fill .graph-filter-region {
+ width: 100%;
+ min-width: 0;
+}
+
+.graph-explorer--fill .graph-filter-toolbar {
+ width: 100%;
+ min-width: 0;
+}
+
+.graph-explorer--fill .graph-explorer__body {
+ flex: 1;
+ min-height: 0;
+ width: 100%;
+}
+
+.graph-explorer--fill .graph-canvas {
+ width: 100%;
+ height: 100%;
+}
diff --git a/console/src/pages/GraphPage.tsx b/console/src/pages/GraphPage.tsx
index 504a688..e358330 100644
--- a/console/src/pages/GraphPage.tsx
+++ b/console/src/pages/GraphPage.tsx
@@ -2,8 +2,11 @@ import { useCallback, useEffect, useMemo, useState } from "react";
import {
Alert,
Button,
+ ChoiceField,
+ ChoiceFieldLabel,
CodeBlock,
NumberInput,
+ Switch,
Tag,
Toolbar,
ToolbarGroup,
@@ -18,6 +21,7 @@ import {
getGraphTone,
type GraphFilterState,
type GraphNode,
+ type GraphPerformanceOptions,
type GraphPropertyValue,
type GraphRelationship as LumenRelationship,
type GraphSelection,
@@ -70,7 +74,7 @@ function toPropertyValue(value: unknown): GraphPropertyValue | undefined {
item === null ||
typeof item === "string" ||
typeof item === "number" ||
- typeof item === "boolean",
+ typeof item === "boolean"
);
return scalars;
}
@@ -78,7 +82,7 @@ function toPropertyValue(value: unknown): GraphPropertyValue | undefined {
}
function toLumenProperties(
- properties?: Record<string, unknown>,
+ properties?: Record<string, unknown>
): Record<string, GraphPropertyValue> | undefined {
if (!properties) return undefined;
const next: Record<string, GraphPropertyValue> = {};
@@ -103,7 +107,7 @@ function entityToNode(entity: GraphEntity): GraphNode {
function relationshipToLumen(
rel: GraphRelationship,
- index: number,
+ index: number
): LumenRelationship {
const type = rel.predicate.name || "RELATED";
return {
@@ -120,7 +124,7 @@ function relationshipToLumen(
function mergeEntities(
current: GraphEntity[],
- incoming: GraphEntity[],
+ incoming: GraphEntity[]
): GraphEntity[] {
const map = new Map(current.map((e) => [e.uuid, e]));
for (const e of incoming) map.set(e.uuid, e);
@@ -129,13 +133,13 @@ function mergeEntities(
function mergeRelationships(
current: GraphRelationship[],
- incoming: GraphRelationship[],
+ incoming: GraphRelationship[]
): GraphRelationship[] {
const map = new Map(
current.map((r) => [
`${r.subject.uuid}-${r.object.uuid}-${r.predicate.name}`,
r,
- ]),
+ ])
);
for (const r of incoming) {
map.set(`${r.subject.uuid}-${r.object.uuid}-${r.predicate.name}`, r);
@@ -147,7 +151,7 @@ function applyGraphFilters(
rels: GraphRelationship[],
entities: GraphEntity[],
label: string,
- query: string,
+ query: string
): GraphRelationship[] {
const hasFilters = !!(label || query);
if (!hasFilters) return rels;
@@ -155,7 +159,7 @@ function applyGraphFilters(
if (label && query) {
return filterRelationshipsByQuery(
filterRelationshipsByLabel(rels, label),
- query,
+ query
);
}
if (label) {
@@ -169,7 +173,7 @@ function applyGraphFilters(
function asEntityOrFallback(
value: GraphEntity | null | undefined,
- fallback: GraphEntity | null,
+ fallback: GraphEntity | null
): GraphEntity {
if (value?.uuid) return value;
if (fallback) return fallback;
@@ -185,11 +189,17 @@ export default function GraphPage() {
const [expanding, setExpanding] = useState(false);
const [error, setError] = useState<string | null>(null);
const [physicsEnabled, setPhysicsEnabled] = useState(true);
+ const [groupingEnabled, setGroupingEnabled] = useState(true);
const [filterState, setFilterState] =
useState<GraphFilterState>(EMPTY_FILTERS);
const [selection, setSelection] = useState<GraphSelection>(null);
const activeBrainId = getSession()?.brainId ?? "default";
+ const performance = useMemo<GraphPerformanceOptions | false | undefined>(
+ () => (groupingEnabled ? undefined : { clustering: false }),
+ [groupingEnabled]
+ );
+
const loadGraph = useCallback(async (nextLimit: number) => {
const applied = clampLimit(nextLimit);
setLoading(true);
@@ -204,7 +214,7 @@ export default function GraphPage() {
const [relRes] = await Promise.all([
apiFetch<{ relationships: unknown[]; total?: number }>(
- `/retrieve/relationships?${relParams}`,
+ `/retrieve/relationships?${relParams}`
),
]);
@@ -214,10 +224,10 @@ export default function GraphPage() {
if (merged.entities.length === 0) {
const fallback = await apiFetch<{ entities: GraphEntity[] }>(
- `/retrieve/entities?limit=${applied}&skip=0`,
+ `/retrieve/entities?limit=${applied}&skip=0`
);
setEntities(
- mergeGraphData(fallback.entities ?? [], normalizedRels).entities,
+ mergeGraphData(fallback.entities ?? [], normalizedRels).entities
);
setRelationships(normalizedRels);
} else {
@@ -245,7 +255,7 @@ export default function GraphPage() {
const nodes = useMemo(() => entities.map(entityToNode), [entities]);
const lumenRelationships = useMemo(
() => relationships.map(relationshipToLumen),
- [relationships],
+ [relationships]
);
const entityById = useMemo(() => {
@@ -260,7 +270,7 @@ export default function GraphPage() {
main_node: GraphEntity;
neighbors?: NeighborEntry[];
}>(
- `/retrieve/entities/neighbors?uuid=${encodeURIComponent(center.uuid)}&limit=40`,
+ `/retrieve/entities/neighbors?uuid=${encodeURIComponent(center.uuid)}&limit=40`
);
const centerNode = asEntityOrFallback(res.main_node, center);
@@ -302,7 +312,7 @@ export default function GraphPage() {
<Toolbar
aria-label="Graph load controls"
density="compact"
- className="items-center"
+ className="w-full items-center px-4"
>
<ToolbarLabel id="graph-load-limit-label">Load limit</ToolbarLabel>
<ToolbarGroup
@@ -324,7 +334,10 @@ export default function GraphPage() {
))}
</ToolbarGroup>
<ToolbarSeparator />
- <ToolbarGroup aria-label="Custom load limit" className="items-center">
+ <ToolbarGroup
+ aria-label="Custom load limit"
+ className="items-center"
+ >
<ToolbarItem className="flex items-center">
<NumberInput
id="graph-custom-limit"
@@ -340,8 +353,29 @@ export default function GraphPage() {
/>
</ToolbarItem>
</ToolbarGroup>
+ <ToolbarSeparator />
+ <ToolbarGroup
+ aria-label="Display options"
+ className="items-center"
+ >
+ <ToolbarItem className="flex items-center">
+ <ChoiceField className="items-center gap-2">
+ <Switch
+ id="graph-node-grouping"
+ checked={groupingEnabled}
+ onChange={(e) => setGroupingEnabled(e.target.checked)}
+ />
+ <ChoiceFieldLabel htmlFor="graph-node-grouping">
+ Group nodes
+ </ChoiceFieldLabel>
+ </ChoiceField>
+ </ToolbarItem>
+ </ToolbarGroup>
<ToolbarSpacer />
- <ToolbarGroup aria-label="Load actions" className="items-center">
+ <ToolbarGroup
+ aria-label="Load actions"
+ className="items-center"
+ >
<ToolbarItem>
<Button
type="button"
@@ -368,7 +402,10 @@ export default function GraphPage() {
</ToolbarGroup>
</Toolbar>
{error ? (
- <Alert variant="danger" title="Failed to load graph">
+ <Alert
+ variant="danger"
+ title="Failed to load graph"
+ >
{error}
</Alert>
) : null}
@@ -376,11 +413,11 @@ export default function GraphPage() {
}
>
{loading ? (
- <div className="flex h-full min-h-[28rem] items-center justify-center text-lumen-muted-foreground">
+ <div className="flex min-h-0 flex-1 items-center justify-center text-lumen-muted-foreground">
Loading graph…
</div>
) : nodes.length === 0 ? (
- <div className="p-6">
+ <div className="flex min-h-0 flex-1 items-start p-6">
<Alert title="No nodes in this brain">
Active brain: {activeBrainId}
{activeBrainId === "default"
@@ -391,7 +428,7 @@ export default function GraphPage() {
) : (
<GraphExplorer
ariaLabel="Knowledge graph explorer"
- className="h-full min-h-[32rem]"
+ className="graph-explorer--fill min-h-0 flex-1"
nodes={nodes}
relationships={lumenRelationships}
filterState={filterState}
@@ -400,12 +437,20 @@ export default function GraphPage() {
onSelectionChange={setSelection}
physicsEnabled={physicsEnabled}
onPhysicsEnabledChange={setPhysicsEnabled}
+ performance={performance}
renderInspector={(context) => {
if (context.selection.kind !== "node") {
- return <GraphInspector {...context} onClose={context.close} />;
+ return (
+ <GraphInspector
+ {...context}
+ onClose={context.close}
+ />
+ );
}
const entity = entityById.get(context.selection.id);
- const node = context.nodes.find((n) => n.id === context.selection.id);
+ const node = context.nodes.find(
+ (n) => n.id === context.selection.id
+ );
return (
<aside className="flex h-full flex-col gap-3 overflow-auto border-l border-lumen-border p-4">
<div className="flex items-start justify-between gap-2">
diff --git a/docs/decisions/002-structured-ingestion-specific-processing.md b/docs/decisions/002-structured-ingestion-specific-processing.md
index 076e1a7..49fa20d 100644
--- a/docs/decisions/002-structured-ingestion-specific-processing.md
+++ b/docs/decisions/002-structured-ingestion-specific-processing.md
@@ -1,11 +1,67 @@
-/\*
-
-- File: /docs/decisions/002-structured-ingestion-specific-processing.md
-- Project: brainapi2
-- Created Date: Monday July 27th 2026
-- Author: Christian Nonis <[email protected]>
-- ***
-- Last Modified: Monday July 27th 2026 4:23:55 pm
-- Modified By: Christian Nonis <[email protected]>
-- ***
- \*/
+# ADR-002: Structured Ingestion Dual-Mode Contract
+
+## Status
+
+Accepted
+
+## Date
+
+2026-08-05
+
+## Context
+
+BrainAPI exposes two write surfaces:
+
+- `POST /ingest/` — free-text Scout → Architect → optional Janitor (LoCoMo / LongMemEval / BEAM path).
+- `POST /ingest/structured` — caller-supplied event triples, with optional free-text enrichment.
+
+Callers building recommenders and catalogs need a **deterministic, LLM-free** write path for known facts (purchases, catalog edges), while still allowing LLM enrichment when text requires indirect intelligence. Before this ADR, “no LLM” was implied only by omitting `text`, and name+type anchors could still call `KGAgent.verify_entity_existence` (LLM). That made deterministic guarantees untestable.
+
+Benchmarks never call `/ingest/structured`. Changing default `/ingest/` or global `PIPELINE_MODE` would invalidate published LoCoMo/BEAM brains. Dual-mode must therefore stay request-scoped on the structured endpoint only.
+
+See also: `docs/research/01-ingestion-extraction.md`, `docs/research/15-ecommerce-gnn-recsys-landscape.md` §7.
+
+## Decision
+
+**1. Explicit `mode` on `IngestionStructuredRequestBody`:** `deterministic` | `hybrid` | `enrich`.
+
+When `mode` is omitted:
+
+- `text` present → `hybrid`
+- else → `deterministic`
+
+**2. Mode semantics**
+
+| Mode | Submitted triples | Text / LLM | Anchor resolution |
+| --- | --- | --- | --- |
+| `deterministic` | Persist via `ingestion_triples_to_relationships` → `process_architect_relationships` | Never run Scout/Architect/Janitor/KGAgent verify. `text` may be stored as provenance only. | UUID lookup, or exact name+type match. Missing name+type anchor → hard fail (no LLM verify, no create-via-verify). |
+| `hybrid` | Persist first; authoritative | If `text` set: Scout/Architect `run_structured` with `persist_submitted=False`; enrichment edges tagged `properties.source=llm_enrichment` | Existing behavior (exact match, else vector + LLM verify / create) |
+| `enrich` | Same as hybrid | Same as hybrid (LLM backfill when text present) | Same as hybrid |
+
+Submitted edges are tagged `properties.source=structured_deterministic`.
+
+**3. Probability Isolation**
+
+LLM uncertainty is confined to the intelligence lane (`hybrid`/`enrich` with text, or free-text `/ingest/`). Known facts stay on the deterministic lane. Do **not** introduce a process-global “skip LLM” flag that alters `/ingest/`.
+
+**4. Benchmark isolation**
+
+- Do not change default free-text `/ingest/` semantics or `PIPELINE_MODE` defaults for this contract.
+- Do not use `PIPELINE_MODE=lightweight` as a structured/deterministic substitute.
+- Recsys / interaction structured data should use dedicated brains (e.g. `*recsys*`), never published eval brains (`beam1m1clean`, `locomoconv26*`).
+
+**5. Embeddings**
+
+Deterministic mode still runs embedding encode + vector write in `process_architect_relationships`. “No LLM” ≠ “no model calls.”
+
+## Alternatives Considered
+
+- Global `INGEST_SKIP_LLM` env — rejected; would risk LoCoMo/BEAM.
+- Relying on omitted `text` alone — rejected; silent LLM on ambiguous anchors.
+- `PIPELINE_MODE=lightweight` as cheap structured path — rejected; different graph shape.
+
+## Consequences
+
+- Callers can assert zero Scout/Architect/KGAgent constructions under `mode=deterministic`.
+- Hybrid enrichment is additive and provenance-tagged for recommend ranking.
+- ADR-001 remains the broader ingestion-structure decision; this ADR owns structured-only dual-mode.
diff --git a/docs/research/00-scope-and-constraints.md b/docs/research/00-scope-and-constraints.md
index 199619c..6dd8736 100644
--- a/docs/research/00-scope-and-constraints.md
+++ b/docs/research/00-scope-and-constraints.md
@@ -38,6 +38,8 @@ Anything expensive must be either moved to write time or exposed only on the dee
| `11-architect-loop-efficiency-plan.md` | Architect/Janitor redesign for peer-competitive ingest token multipliers |
| `12-locomo-93-at-low-multiplier.md` | Dual goal: ≥93% LoCoMo SOTA at ~15–20× ingest median (no escalate storms) |
| `13-locomo-93-research-levers.md` | Evidence-backed research levers for HyperMem-class ≥93% (harness-first) |
+| `15-ecommerce-gnn-recsys-landscape.md` | External GNN/e-commerce RecSys curriculum & industry index; BrainAPI mapping |
+| `16-recsys-eval-protocol.md` | Held-out next-item eval on demorecsys via structured ingest + /retrieve/recommend |
## Decisions already taken during research
diff --git a/docs/research/15-ecommerce-gnn-recsys-landscape.md b/docs/research/15-ecommerce-gnn-recsys-landscape.md
new file mode 100644
index 0000000..9dc6f8b
--- /dev/null
+++ b/docs/research/15-ecommerce-gnn-recsys-landscape.md
@@ -0,0 +1,292 @@
+# Deep Interconnected E-Commerce Recommender Systems — Landscape Index
+
+Workstream: external curriculum / tutorial / industrial index for graph-structured e-commerce recommendation, and how it maps (or does not map) onto BrainAPI.
+
+**Status of this document:** Research **index and critical framing**, not a finding and not an implementation plan. Primary source material was provided by the maintainer as a compiled review titled *Deep Interconnected E-Commerce Recommender Systems: A Comprehensive Review of Academic Lecture Series, Tutorial Syllabi, and Industrial Frameworks* (ingested 2026-08-05). Claims below are labeled:
+
+| Label | Meaning |
+| --- | --- |
+| **source material** | Restated from the provided review / its cited URLs |
+| **located evidence** | Independently checked (arXiv ID, course URL, or codebase path) |
+| **idea / proposal** | BrainAPI-facing implication; not validated |
+| **decision** | Locked elsewhere (plan / ADR); restated for cross-link only |
+
+Related internal docs: [`04-evaluation-and-applications.md`](04-evaluation-and-applications.md) §4.9 (synergies metrics), synergies/recsys feasibility plan (Phases 0–4), [`00-scope-and-constraints.md`](00-scope-and-constraints.md) (recommenders as a product substrate).
+
+---
+
+## 1. What the source material argues
+
+**source material.** E-commerce recommendation has moved from matrix factorization toward deep, graph-structured, multi-stage pipelines because catalogs are sparse, scale-free, and multi-behavior. Isolated interaction instances miss structural relationships in user–item graphs. The review indexes:
+
+1. Graduate curricula (Stanford CS224W, Yale CPSC 583, Minnesota LensKit specialization).
+2. Conference tutorials (IJCAI 2021 DeepRecSys, WSDM 2022 GNN-RecSys, LoG 2023, KDD 2020/2022).
+3. Production GPU / RL pipelines (NVIDIA Merlin, RecSys 2022 Ray/RLlib).
+4. Industrial architectures (Alibaba ComiRec/MIND, Pinterest PinSage/PinnerSage, Amazon asymmetric complementary GNN, Uber Eats GraphSAGE).
+5. Three architectural directives: decouple graph propagation from deep feature interaction; multi-interest over single-vector users; topology-aware offline evaluation against popularity bias.
+
+**Critical note (methodology).** The provided text is an **analytical syllabus index**, not a primary empirical study. Citation tags `[cite: N]` in the source are opaque (no bibliography keyed to those numbers). Treat numerical claims from industrial blogs (e.g. Uber AUC 78%→87%) as **unverified secondary reports** until traced to a primary paper or engineering post with methods.
+
+---
+
+## 2. Academic curricular foundations
+
+### 2.1 Stanford CS224W — Machine Learning with Graphs
+
+**source material.** Instructors associated with Jure Leskovec / Rex Ying. User–item interactions modeled as bipartite \(G=(U,V,E)\). Lectures cover NGCF → LightGCN, GIN expressiveness, and scale methods (neighbor sampling, Cluster-GCN, simplified/precomputed GCN). Neural subgraph matching maps motifs into order-embedding cones.
+
+**LightGCN propagation (as stated in source; matches literature):**
+
+\[
+e_u^{(k+1)}=\sum_{i\in N_u}\frac{1}{\sqrt{|N_u||N_i|}}\,e_i^{(k)},\quad
+e_i^{(k+1)}=\sum_{u\in N_i}\frac{1}{\sqrt{|N_i||N_u|}}\,e_u^{(k)}
+\]
+
+Final embeddings are layer averages \(\sum_{k=0}^{K}\alpha_k e^{(k)}\). No feature transforms or nonlinearities inside the graph steps.
+
+**located evidence.** LightGCN paper: He et al., *LightGCN: Simplifying and Powering Graph Convolution Network for Recommendation*, [arXiv:2002.02126](https://arxiv.org/abs/2002.02126). Course hub: [web.stanford.edu/class/cs224w/](https://web.stanford.edu/class/cs224w/). RecSys slides example: [snap.stanford.edu/.../13-recsys.pdf](http://snap.stanford.edu/class/cs224w-2021/slides/13-recsys.pdf).
+
+### 2.2 Yale CPSC 583 — Deep Learning on Graph-Structured Data
+
+**source material.** Rex Ying. Theory half: distributed embeddings, generative graph models, hyperbolic spaces for hierarchies. Applied half: recommenders, biology, multi-agent reasoning; GNNExplainer for subgraph-level explanation.
+
+**located evidence.** Course listing / instructor site: [cs.yale.edu/homes/ying-rex/](https://www.cs.yale.edu/homes/ying-rex/).
+
+### 2.3 University of Minnesota — Advanced Recommender Systems
+
+**source material.** Joseph A. Konstan, Michael D. Ekstrand. Matrix factorization, hybrids, LensKit; emphasis on metrics, evaluation methodology, and production-minded CF pipelines rather than GNN theory.
+
+| Curriculum | Focus (source material) | Competency claimed |
+| --- | --- | --- |
+| Stanford CS224W | NGCF, LightGCN, GIN, GNN scaling | Expressive scalable graph convolutions |
+| Yale CPSC 583 | Inductive SAGE, hyperbolic, GNNExplainer | Explainable / non-Euclidean graph models |
+| Minnesota specialization | MF, hybrids, LensKit | Production collaborative pipelines + eval |
+
+---
+
+## 3. Conference tutorials (syllabus index)
+
+### 3.1 IJCAI 2021 — Deep Learning for Recommendations
+
+**source material / located evidence.** Tutorial site: [advanced-recommender-systems.github.io/ijcai2021-tutorial/](https://advanced-recommender-systems.github.io/ijcai2021-tutorial/). Speakers cited: Wenqi Fan, Xiangyu Zhao, Dawei Yin, Jiliang Tang.
+
+Syllabus segments (source): intro; deep RS fundamentals; RL for RS; GNNs for recommendations; AutoML for RS; adversarial attacks; trustworthy RecSys (fairness / popularity bias).
+
+### 3.2 WSDM 2022 — GNNs for Recommender Systems
+
+**source material.** Chen Gao, Xiang Wang, Xiangnan He, Yong Li. Single-behavior → multi-behavior GNNs (e.g. MBRec): browse / cart / favorite / purchase hierarchies; social + temporal dynamics; sparsity via multi-typed propagation.
+
+**located evidence (related).** Multi-behavior GNN survey/work often cited in this line: e.g. [arXiv:2302.08678](https://arxiv.org/pdf/2302.08678) (*Multi-Behavior Graph Neural Networks for Recommender System*). Slides linked in source: [staff.ustc.edu.cn/~hexn/slides/wsdm22_tutorial_gnn_rec.pdf](http://staff.ustc.edu.cn/~hexn/slides/wsdm22_tutorial_gnn_rec.pdf).
+
+### 3.3 LoG 2023 — Reproducibility, Topology, Node Representation
+
+**source material.** Tommaso Di Noia, Claudio Pomo, Daniele Malitesta. Three themes:
+
+1. **Reproducibility** — Elliot framework; complex GNNs sometimes fail to beat strong shallow MF.
+2. **Topology** — power-law degree bias → popular items dominate message passing → diversity collapse.
+3. **Node representation** — from scratch vs multimodal pretrained item descriptors.
+
+**located evidence.** [arXiv:2310.11270](https://arxiv.org/abs/2310.11270) (*Graph Neural Networks for Recommendation: Reproducibility, Graph Topology, and Node Representation*).
+
+### 3.4 KDD 2022 — Graph Representation Learning for Web-Scale RecSys
+
+**source material.** Ahmed El-Kishky, Michael Bronstein, Ying Xiao, Aria Haghighi. Homogeneous vs heterogeneous graphs; random-walk embeddings (node2vec DFS/BFS); L1 (direct co-purchase) vs L2 (shared neighbor) proximity; embeddings as inputs to candidate generation / ranking.
+
+**located evidence.** Talk PDF cited in source: [ahelk.github.io/talks/kdd22/kdd_talk.pdf](https://ahelk.github.io/talks/kdd22/kdd_talk.pdf).
+
+### 3.5 KDD 2020 — Marketplace & Automated RecSys
+
+**source material.** Part A (Mehrotra, Carterette / Spotify): multi-stakeholder marketplace, Pareto scalarization, multi-objective bandits. Part B (Yong Li, Quanming Yao): AutoML for feature interaction, GraphNAS, automated KG embeddings.
+
+**located evidence.** [sites.google.com/view/kdd20-marketplace-autorecsys/](https://sites.google.com/view/kdd20-marketplace-autorecsys/).
+
+| Tutorial | Speakers (source) | Primary content |
+| --- | --- | --- |
+| IJCAI 2021 | Fan, Zhao, Yin, Tang | Deep RS, RL, GNN, AutoML, attacks, trust |
+| WSDM 2022 | Gao, Wang, He, Li | Multi-behavior GNN, social, temporal |
+| LoG 2023 | Di Noia, Pomo, Malitesta | Elliot repro, topology bias, multimodal |
+| KDD 2022 | El-Kishky et al. | Walks, proximity, web-scale graph learning |
+| KDD 2020 | Mehrotra/Carterette; Li/Yao | Marketplace MOO; AutoML / GraphNAS |
+
+---
+
+## 4. Production-scale pipelines
+
+### 4.1 Multi-stage serving pattern
+
+**source material.** Canonical industrial funnel:
+
+```
+Interaction log streams
+ → GPU ETL (NVTabular)
+ → Candidate generation (two-tower / GNN ANN)
+ → Deep ranking (Wide&Deep / DeepFM / DIN)
+ → Re-rank / business rules / diversity
+ → Triton (or equivalent) low-latency serve
+```
+
+Phases: retrieval → filter/feature-store → rank → order.
+
+### 4.2 RecSys 2022 — Ray / RLlib
+
+**source material.** Treat recommend→feedback as an MDP; optimize long-horizon engagement with distributed multi-agent RL rather than static pointwise targets. Tutorial listing: [recsys.acm.org/recsys22/tutorials/](https://recsys.acm.org/recsys22/tutorials/).
+
+### 4.3 NVIDIA Merlin stack
+
+**source material.**
+
+| Component | Role | Pipeline stage |
+| --- | --- | --- |
+| NVTabular | GPU ETL, high-cardinality categoricals | Preprocess |
+| Merlin Models | NCF, VAE-CF, Wide&Deep, DLRM | Rank |
+| Transformers4Rec | Session / sequential transformers | Seq retrieve / match |
+| Triton | Concurrent models, dynamic batching | Online serve |
+
+**KDD Cup 2023 (Amazon multilingual next-product)** — source claims Merlin team win via: Stage 1 co-visitation + contrastive multilingual product embeddings; Stage 2 transformer + GBDT rerank on titles/descriptions/history. Treat as secondary case study until methods write-up verified.
+
+---
+
+## 5. Industrial case studies (architectural mechanisms)
+
+### 5.1 Alibaba MIND / ComiRec — multi-interest
+
+**source material.** Single-vector sequential history fails under diverse interests. ComiRec extracts \(K\) interest vectors via self-attention (SA) or capsule dynamic routing (DR); training picks \(v_t=\arg\max_k v_k^\top e_i\) nearest the positive item; sampled-softmax NLL; inference runs \(K\) parallel retrievals then diversity aggregation.
+
+Open discussion / blog cited: [Alibaba Cloud — Controllable Multi-Interest Framework](https://www.alibabacloud.com/blog/596749).
+
+### 5.2 Pinterest PinSage / PinnerSage
+
+**source material.** PinSage: importance-sampled random-walk neighborhoods + hard negatives on ~3B pins / 18B edges scale. PinnerSage: Ward hierarchical clustering of a user’s pin embeddings; medoids as multi-topic user vectors.
+
+**located evidence (secondary).** PinSage engineering post: [Pinterest Engineering — PinSage](https://medium.com/pinterest-engineering/pinsage-a-new-graph-convolutional-neural-network-for-web-scale-recommender-systems-88795a107f48). PinnerSage PDF: [cs.stanford.edu/.../pinnersage-kdd20.pdf](https://cs.stanford.edu/people/jure/pubs/pinnersage-kdd20.pdf). KDD 2018 PinSage paper listing: [kdd.org/.../graph-convolutional-neural-networks-for-web-scale-recommender-systems](https://www.kdd.org/kdd2018/accepted-papers/view/graph-convolutional-neural-networks-for-web-scale-recommender-systems).
+
+### 5.3 Amazon — asymmetric complementary GNN
+
+**source material.** Complementary edges are directed (phone→case ≠ case→phone). Dual embeddings per item \(h^{\mathrm{src}}\), \(h^{\mathrm{tgt}}\); score \(\langle h_u^{\mathrm{src}}, h_v^{\mathrm{tgt}}\rangle\); contrastive loss favors outbound edges, penalizes inbound negatives.
+
+**located evidence (secondary).** [Amazon Science — Using GNNs to recommend related products](https://www.amazon.science/blog/using-graph-neural-networks-to-recommend-related-products). Related arXiv HTML cited in source list: [arXiv HTML 2508.14059](https://arxiv.org/html/2508.14059) (Amazon co-purchase GNN — verify relevance before citing as the Amazon complementary paper).
+
+### 5.4 Uber Eats — heterogeneous GraphSAGE
+
+**source material.** Users / restaurants / cuisines / dishes; inductive GraphSAGE; reported AUC lift 78%→87% vs non-graph baselines (**unverified secondary claim**).
+
+| Platform | Model | Mechanism (source) | Claimed advantage | Scaling limit (source) |
+| --- | --- | --- | --- | --- |
+| Alibaba | ComiRec | Multi-interest SA / capsules | Breaks single-vector bottleneck | Sequence length |
+| Pinterest | PinSage | Walk-localized conv + hard neg | Bounded neighborhoods | Static bipartite scale |
+| Pinterest | PinnerSage | Ward medoids | Multi-topic users | Update frequency |
+| Amazon | Asymmetric GNN | Dual src/tgt embeddings | Directed complementary | 2× embedding storage |
+| Uber Eats | GraphSAGE | Heterogeneous inductive agg | Local + spatial signals | Regional density |
+
+---
+
+## 6. Architectural strategic directions (from source)
+
+**source material — three directives:**
+
+1. **Decouple** linear/simplified graph propagation from nonlinear feature-interaction rankers (LightGCN-style embeddings → DeepFM/DIN).
+2. **Multi-interest** user representations (ComiRec / PinnerSage-class) instead of one vector.
+3. **Topology-aware evaluation** — stratify by degree / popularity so models are not scored only on head items (LoG 2023 theme).
+
+---
+
+## 7. Critical mapping onto BrainAPI
+
+This section is **analysis**, not from the source review.
+
+### 7.1 Category difference (claim evaluation)
+
+| Dimension | Landscape above | BrainAPI core (**located evidence**) |
+| --- | --- | --- |
+| Job | Rank items for users from interaction logs | Event KG from text/triples + evidence retrieval |
+| Graph | User–item bipartite / multi-behavior | Actor `-[:MADE]->` Event `-[:TARGETED]->` Object |
+| Learning | Offline train (GNN, two-tower, sampled softmax) | Encode-only embeddings; synergies = heuristic graph+cosine ([`entity_sibilings.py`](../../src/core/search/entity_sibilings.py)) |
+| Serve | Retrieval → rank → re-rank | `/retrieve/context`, `/retrieve/entity/synergies` |
+| Metrics | NDCG / CTR / next-item | LoCoMo / BEAM memory QA; synergies unmeasured ([`04`](04-evaluation-and-applications.md) §12) |
+
+**Conclusion supported by evidence:** BrainAPI synergies are **not** LightGCN/Merlin. Equating them is a category error.
+
+### 7.2 What transfers as metaphor (ideas — not validated)
+
+| Industrial idea | Plausible BrainAPI analogue (**idea**) |
+| --- | --- |
+| Candidate generation | Synergies + neighbors + hops |
+| Asymmetric complementary | Directed event-hub walks (query as source vs target) |
+| Multi-interest | Cluster recent event neighborhoods / medoids |
+| Decouple propagate vs rank | Keep graph walk cheap; rank with association_score + diversity |
+| Topology-aware eval | Stratify synergy seeds by node degree / type frequency |
+| Merlin train/serve | **Plugin-only** parallel pipeline — plugins are additive, cannot overwrite `/ingest/` or synergies |
+
+### 7.3 What does **not** transfer without new data + new stack
+
+- Training LightGCN/PinSage inside default ingest (no interaction-tensor train loop; would risk LoCoMo/BEAM if forced onto `/ingest/`).
+- NVTabular / Triton as core dependencies.
+- Marketplace multi-objective bandits without supplier/consumer logs.
+- Claiming GNN SOTA by shipping synergies heuristics.
+
+### 7.4 Adversarial / minority points preserved from LoG 2023
+
+- Complex GNNs can lose to strong MF under Elliot — **do not** assume deeper = better.
+- Power-law bias harms diversity — any BrainAPI recommend API should measure long-tail coverage, not only association_score on hubs.
+- Multimodal item features matter industrially; BrainAPI already has text descriptions — fusion is optional enrichment, not a reason to train PinSage in core.
+
+### 7.5 Decision log (cross-link)
+
+| Decision | Rationale | Rejected alternative |
+| --- | --- | --- |
+| Core path = event-KG relatedness + deterministic `/ingest/structured` | Matches BrainAPI data model; preserves benches | Fold LightGCN into `/ingest/` |
+| Industrial GNN/Merlin = optional **plugin** parallel train/serve | Plugin API is additive only | Overwrite synergies / default ingest |
+| Measure synergies with structural metrics first | [`04`](04-evaluation-and-applications.md) §4.9 | Gate on LLM serendipity alone |
+
+---
+
+## 8. Source URL registry (from provided material)
+
+Access date for this index: **2026-08-05**. URLs are as supplied; not all were re-fetched end-to-end.
+
+### Tutorials & courses
+
+- IJCAI 2021 DeepRecSys — https://advanced-recommender-systems.github.io/ijcai2021-tutorial/
+- CS224W — https://web.stanford.edu/class/cs224w/
+- CS224W recsys slides — http://snap.stanford.edu/class/cs224w-2021/slides/13-recsys.pdf
+- Yale Rex Ying — https://www.cs.yale.edu/homes/ying-rex/
+- KDD 2020 marketplace/AutoRecSys — https://sites.google.com/view/kdd20-marketplace-autorecsys/
+- KDD 2022 talk PDF — https://ahelk.github.io/talks/kdd22/kdd_talk.pdf
+- WSDM 2022 GNN-Rec slides — http://staff.ustc.edu.cn/~hexn/slides/wsdm22_tutorial_gnn_rec.pdf
+- RecSys 2022 tutorials — https://recsys.acm.org/recsys22/tutorials/
+
+### Papers / arXiv (verified or commonly cited)
+
+- LightGCN — https://arxiv.org/abs/2002.02126
+- LoG GNN-Rec tutorial paper — https://arxiv.org/abs/2310.11270
+- Multi-behavior GNN RS — https://arxiv.org/pdf/2302.08678
+- Amazon co-purchase GNN (HTML) — https://arxiv.org/html/2508.14059
+- PinnerSage — https://cs.stanford.edu/people/jure/pubs/pinnersage-kdd20.pdf
+- PinSage KDD 2018 listing — https://www.kdd.org/kdd2018/accepted-papers/view/graph-convolutional-neural-networks-for-web-scale-recommender-systems
+
+### Industrial / engineering posts
+
+- PinSage (Pinterest Eng) — https://medium.com/pinterest-engineering/pinsage-a-new-graph-convolutional-neural-network-for-web-scale-recommender-systems-88795a107f48
+- Amazon complementary GNN — https://www.amazon.science/blog/using-graph-neural-networks-to-recommend-related-products
+- Alibaba ComiRec blog — https://www.alibabacloud.com/blog/596749
+- NVIDIA Merlin overview — https://developer.nvidia.com/blog/how-to-build-a-winning-recommendation-system-part-2-deep-learning-for-recommender-systems/
+- Meta Intelligence CF→Deep overview — https://www.meta-intelligence.tech/en/insight-recommender-systems
+
+### Additional URLs from the source list (not individually verified this pass)
+
+YouTube CS224W lectures (17.1 scale, 9.2 GIN, 2023 GNN-RecSys, Trustworthy Graph AI); Coursera recommender courses; RecSys 2021/2024 pages; NVIDIA Merlin preprocessing Medium post; Alibaba M2GRL blog; YouTube DNN recommendations paper; AssemblyAI / Plasticity GNN trend posts; alphaXiv mirrors of 2310.11270; NSF PAR “How Does Message Passing Improve Collaborative Filtering?”; Emerald incremental graph RS survey.
+
+**Search limits:** Opaque `[cite: N]` keys in the source were not resolved to a formal bibliography. Industrial AUC / catalog-size figures remain secondary until primary methods sections are checked. This document does **not** establish novelty of any BrainAPI design.
+
+---
+
+## 9. Next actions (labeled)
+
+| Action | Type |
+| --- | --- |
+| Keep this file as the external landscape index for recommenders | **decision** (documentation) |
+| Core BrainAPI work: structured dual-mode ingest + synergies harden + `/retrieve/recommend` | **proposal** — see feasibility plan Phases 0–3 |
+| Optional `plugins/recsys-gnn/` for LightGCN/Merlin-class train/serve | **proposal** — Phase 4; additive only |
+| `plugins/recsys-gnn` LightGCN export→train→`/recsys/recommend` (BrainAPI = KB) | **decision** — see [`16-recsys-eval-protocol.md`](16-recsys-eval-protocol.md) |
+| Do not change default `/ingest/` or LoCoMo/BEAM brains for this landscape | **decision** |
+| If citing Uber/Amazon metrics in papers or README, verify primary sources first | **further search** |
diff --git a/docs/research/16-recsys-eval-protocol.md b/docs/research/16-recsys-eval-protocol.md
new file mode 100644
index 0000000..87f2270
--- /dev/null
+++ b/docs/research/16-recsys-eval-protocol.md
@@ -0,0 +1,102 @@
+# RecSys eval protocol — train-free graph recommend (+ optional LightGCN)
+
+How to store interactions in BrainAPI and score held-out next-item HitRate/Recall@K.
+
+**Role split (locked):**
+
+| Component | Responsibility |
+| --- | --- |
+| BrainAPI | KB + **train-free ranker**: `POST /ingest/structured` (`mode=deterministic`) and `GET /retrieve/recommend` on brain `demorecsys` |
+| `plugins/features-rec` | Multi-behavior + attribute ingest; write-time `USER-PREFERS-ATTR` upserts via `POST /features-rec/interactions` |
+| `plugins/recsys-gnn` | Optional offline baseline: export edges, train LightGCN, `GET /recsys/recommend` |
+
+Freshness: each structured ingest changes graph walks / attribute prefs immediately — **no** `/recsys/train` on the live path.
+
+**Not** LoCoMo / LongMemEval / BEAM. Never write to or wipe `beam1m1clean`, `locomoconv26*`, or other memory-eval brains. Ledger upserts go only to `benchmarks.recsys` in [`benchmarks/REPORTS.json`](../../benchmarks/REPORTS.json).
+
+Related: [ADR-002](../decisions/002-structured-ingestion-specific-processing.md), [15-ecommerce-gnn-recsys-landscape.md](15-ecommerce-gnn-recsys-landscape.md).
+
+---
+
+## Pipelines
+
+### A — Train-free graph (default)
+
+```text
+interactions → POST /ingest/structured (or POST /features-rec/interactions)
+ → GET /retrieve/recommend?target=<user>&labels=PRODUCT&exclude_seen=true
+ → HitRate@K / Recall@K (+ popularity baseline)
+```
+
+Channels: synergies, asymmetric event walks, **collaborative** 2-hop (user→item→user→item), optional `attribute_pref` (PREFERS edges and/or PRODUCT→ATTR soft prefs).
+
+```bash
+curl -sS "$BRAINAPI_URL/retrieve/recommend?target=u01&top_k=20&exclude_seen=true&labels=PRODUCT&include_attribute_pref=true&dampen_degree=true&recency_half_life_days=90" \
+ -H "Authorization: Bearer $BRAINPAT_TOKEN" \
+ -H "X-Brain-ID: demorecsys"
+```
+
+### B — Optional LightGCN
+
+```text
+interactions → POST /ingest/structured → POST /recsys/train → GET /recsys/recommend
+```
+
+---
+
+## Features-rec (multi-behavior + attributes)
+
+```bash
+curl -sS -X POST "$BRAINAPI_URL/features-rec/interactions" \
+ -H "Authorization: Bearer $BRAINPAT_TOKEN" \
+ -H "Content-Type: application/json" \
+ -H "X-Brain-ID: demorecsys" \
+ -d '{
+ "user_id":"u01","item_id":"chair-1","behavior":"purchase",
+ "timestamp":"2024-02-01T12:00:00Z",
+ "attributes":{"color":"black","material":"wood","category":"furniture"},
+ "brain_id":"demorecsys","wait":true
+ }'
+```
+
+Then rank with core `/retrieve/recommend` (`include_attribute_pref=true`). Do **not** use a plugin-local recommend endpoint.
+
+Behavior weights (config, not trained): View/Click 0.2, AddToCart 0.5, Purchase 1.0.
+
+---
+
+## Harness
+
+```bash
+cd benchmarks
+# toy smoke (graph, no train)
+./recsys.sh smoke --backend graph
+
+# attributed toy
+./recsys.sh evaluate --backend graph --dataset data/recsys_toy_attrs.jsonl --min-interactions 2 --max-users 20
+
+# MovieLens subsample
+./recsys.sh download --name ml-100k
+./recsys.sh evaluate \
+ --backend graph \
+ --dataset data/movielens_100k.jsonl \
+ --max-users 50 \
+ --min-interactions 5 \
+ --timeout 7200
+
+# optional LightGCN comparator
+./recsys.sh evaluate --backend lightgcn --dataset data/recsys_toy.jsonl --epochs 20
+```
+
+Requires `BRAINPAT_TOKEN` in `benchmarks/.env`. Default brain: `demorecsys`. Report `model=graph-recommend` or `lightgcn`.
+
+**Live stack note:** after core or plugin changes, sync + restart (`brainapi start` / `brainapi update`) so OpenAPI lists `/retrieve/recommend` knobs and `/features-rec/interactions`.
+
+---
+
+## Guardrails
+
+- Do **not** call free-text `POST /ingest/` for this suite.
+- Default harness backend is **graph** (`GET /retrieve/recommend`); use `--backend lightgcn` only for the offline comparator.
+- Do **not** mutate `benchmarks.locomo` / `beam` / `longmemeval` ledger rows.
+- Do **not** point `--brain` at memory-eval brains.
diff --git a/pyproject.toml b/pyproject.toml
index eeeedc7..5bbbb59 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "brainapi2"
-version = "2.14.4-dev"
+version = "2.15.0-dev"
description = "Version 2.x.x of the BrainAPI memory layer."
authors = [
{name = "Christian",email = "[email protected]"}
diff --git a/src/core/search/entity_sibilings.py b/src/core/search/entity_sibilings.py
index f0240f8..2081f52 100644
--- a/src/core/search/entity_sibilings.py
+++ b/src/core/search/entity_sibilings.py
@@ -12,7 +12,7 @@ from typing import Dict, List, Literal, Optional, Tuple
import numpy as np
from src.adapters.interfaces.graph import PredicateWithFlowKey
-from src.constants.kg import EntitySynergy, Node
+from src.constants.kg import EntitySynergy, Node, Predicate
from src.services.kg_agent.main import (
embeddings_adapter,
graph_adapter,
@@ -22,21 +22,57 @@ from src.utils.vector_search import VectorSearchFacade
from src.utils.similarity.numbers import wmean, wsim
from src.utils.similarity.vectors import cosine_similarity
-# Strengthen the similarity between target and neighbor nodes that are directly connected
DIRECT_MULTIPLIER = 1.30
-# Lowers the similarity between target and neighbor nodes that connected by similar nodes but not directly connected
REMOTE_MULTIPLIER = 0.70
-# Weight to strengthen the similarity by the more things in common between the neighbor and the target
FACTORS_INCREMENTAL_WEIGHT = 0.3
-# Weight to strengthen the similarity by the comparison of the neighbor+target descriptions
NODE_SIM_DESC_INCREMENTAL_WEIGHT = 0.5
+DEFAULT_TOP_K = 50
+
vector_search = VectorSearchFacade(vector_store_adapter)
+def _predicate_currently_valid(predicate: Predicate) -> bool:
+ props = getattr(predicate, "properties", None) or {}
+ if props.get("invalid_at"):
+ return False
+ if getattr(predicate, "deprecated", False):
+ return False
+ return True
+
+
+def _normalize_polarity(value: Optional[str]) -> Optional[str]:
+ if not value:
+ return None
+ v = value.strip().lower()
+ if v in ("positive", "negative", "neutral"):
+ return v
+ return None
+
+
+def polarity_matches(
+ target_polarity: Optional[str],
+ candidate_polarity: Optional[str],
+ mode: Literal["same", "opposite"],
+) -> bool:
+ """
+ same: matching polarities (None/neutral treated as compatible with each other).
+ opposite: positive↔negative only; neutral/None excluded from opposite matches.
+ """
+ tp = _normalize_polarity(target_polarity)
+ cp = _normalize_polarity(candidate_polarity)
+ if mode == "same":
+ if tp in (None, "neutral") and cp in (None, "neutral"):
+ return True
+ return tp == cp
+ if tp in (None, "neutral") or cp in (None, "neutral"):
+ return False
+ return {tp, cp} == {"positive", "negative"}
+
+
class EntitySinergyRetriever:
def __init__(self, brain_id: str = "default"):
"""
@@ -54,25 +90,27 @@ class EntitySinergyRetriever:
do: bool = False,
pa: bool = False,
ppa: bool = False,
- ) -> Tuple[Node, List[EntitySynergy], List[Node], List[Node]]:
+ top_k: int = DEFAULT_TOP_K,
+ labels: Optional[List[str]] = None,
+ ) -> Tuple[Optional[Node], List[EntitySynergy], List[Node], List[Node]]:
"""
Find related entities ("siblings") for a given target text by locating the target node and assembling EntitySynergy connections from its neighbors and embedding-based similarity.
- This returns the resolved target graph node (or None if no matching node is found) and a list of EntitySynergy objects that represent related nodes discovered via neighbor relationships and vector-similarity matches. The method may return early with an empty list when required intermediate data (target node, similarity seeds, or similar nodes) is missing.
-
Parameters:
target: The text used to locate the target entity in the node store.
- polarity: A directive indicating the type of relation to retrieve; expected values are "same" or "opposite".
+ polarity: "same" keeps candidates with matching node polarity; "opposite"
+ keeps positive↔negative pairs only.
do: If True, only direct synergies are returned.
pa: If True, potential anchors are returned.
- ppa: If True, potential positive anchors are returned.
+ ppa: If True, anchors (seed nodes) are returned.
+ top_k: Maximum synergies to return (default 50).
+ labels: If set, only return candidates whose labels intersect this set.
Returns:
- (target_node, connections):
- - target_node (Node or None): the graph node matching the provided target text, or `None` if not found.
- - connections (List[EntitySynergy]): a list of EntitySynergy entries representing related entities; may be empty.
+ (target_node, connections, anchors, potential_anchors)
"""
+ label_filter = None
_embedding_cache: Dict[Tuple[str, str], Optional[np.ndarray]] = {}
def _get_first_embedding(ids: List[str], store: str):
@@ -98,6 +136,17 @@ class EntitySinergyRetriever:
)
def _upsert_connection(seed_node: Node, neighbor_node: Node, score: float):
+ if neighbor_node.uuid == target_node.uuid:
+ return
+ if label_filter is not None:
+ if not set(l.upper() for l in neighbor_node.labels).intersection(
+ label_filter
+ ):
+ return
+ if not polarity_matches(
+ target_node.polarity, neighbor_node.polarity, polarity
+ ):
+ return
if neighbor_node.uuid not in positivep_connections:
positivep_connections[neighbor_node.uuid] = EntitySynergy(
node=neighbor_node,
@@ -122,6 +171,8 @@ class EntitySinergyRetriever:
def _collect_seed_nodes_for_neighbor(neighbor):
seed_nodes_for_neighbor = []
target_embeddings = []
+ if not _predicate_currently_valid(neighbor[0]):
+ return None, None
neighbor_embeddings = _get_first_embedding(
[neighbor[0].properties.get("v_id")],
store="relationships",
@@ -201,7 +252,9 @@ class EntitySinergyRetriever:
brain_id=self.brain_id,
)
edges_map = {
- edge[0].uuid: edge[0] for edge in _neighbors_event_edges[seed_node.uuid]
+ edge[0].uuid: edge[0]
+ for edge in _neighbors_event_edges[seed_node.uuid]
+ if _predicate_currently_valid(edge[0])
}
_neighbors_event = graph_adapter.get_nexts_by_flow_key(
[
@@ -231,6 +284,8 @@ class EntitySinergyRetriever:
if neighbor_node_vid:
node_ids_to_fetch.append(neighbor_node_vid)
for dn in _neighbors_direct[seed_node.uuid]:
+ if not _predicate_currently_valid(dn[0]):
+ continue
if dn[1].uuid != target_node.uuid:
n_vid = dn[0].properties.get("v_id")
if n_vid:
@@ -318,6 +373,8 @@ class EntitySinergyRetriever:
)
for dn in _neighbors_direct[seed_node.uuid]:
+ if not _predicate_currently_valid(dn[0]):
+ continue
if dn[1].uuid != target_node.uuid:
n_vid = dn[0].properties.get("v_id")
tn_score = None
@@ -375,10 +432,15 @@ class EntitySinergyRetriever:
_neighbors = graph_adapter.get_neighbors(
[target_node_id], brain_id=self.brain_id
)
- neighbors = _neighbors[target_node_id]
+ neighbors = [
+ n for n in _neighbors[target_node_id] if _predicate_currently_valid(n[0])
+ ]
positivep_connections: Dict[str, EntitySynergy] = {}
seen_set = set([target_node.uuid])
+ label_filter = (
+ {l.upper() for l in labels} if labels else None
+ )
all_seed_nodes: List[Node] = []
all_similar_seeds: List[Node] = []
@@ -434,13 +496,15 @@ class EntitySinergyRetriever:
)
unique_seeds = {n.uuid: n for n in all_seed_nodes}
+ ranked = sorted(
+ positivep_connections.values(),
+ key=lambda x: x.association_score,
+ reverse=True,
+ )
+ limit = max(0, int(top_k)) if top_k is not None else DEFAULT_TOP_K
return (
target_node,
- sorted(
- positivep_connections.values(),
- key=lambda x: x.association_score,
- reverse=True,
- ),
+ ranked[:limit],
list(unique_seeds.values()),
all_similar_seeds,
)
diff --git a/src/core/search/recommend.py b/src/core/search/recommend.py
new file mode 100644
index 0000000..80a0e27
--- /dev/null
+++ b/src/core/search/recommend.py
@@ -0,0 +1,593 @@
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from datetime import datetime
+from typing import Dict, List, Literal, Optional, Set, Tuple
+
+from src.constants.kg import Node
+from src.core.search.entity_sibilings import (
+ DEFAULT_TOP_K,
+ EntitySinergyRetriever,
+ _predicate_currently_valid,
+)
+from src.utils.dates import parse_date_string, to_naive_utc
+from src.services.kg_agent.main import graph_adapter
+
+DEFAULT_BEHAVIOR_WEIGHTS: Dict[str, float] = {
+ "view": 0.2,
+ "click": 0.2,
+ "addtocart": 0.5,
+ "add_to_cart": 0.5,
+ "cart": 0.5,
+ "purchase": 1.0,
+ "buy": 1.0,
+ "purchased": 1.0,
+ "bought": 1.0,
+}
+
+ATTR_LABELS = frozenset(
+ {"CATEGORY", "BRAND", "COLOR", "MATERIAL", "ATTR", "ATTRIBUTE"}
+)
+
+
+def behavior_weight(
+ event_name: str | None,
+ weights: Optional[Dict[str, float]] = None,
+) -> float:
+ table = weights or DEFAULT_BEHAVIOR_WEIGHTS
+ key = (event_name or "").strip().lower().replace("-", "").replace(" ", "")
+ if key in table:
+ return float(table[key])
+ key2 = (event_name or "").strip().lower().replace("-", "_").replace(" ", "_")
+ if key2 in table:
+ return float(table[key2])
+ for alias, value in table.items():
+ compact = alias.replace("-", "").replace("_", "").replace(" ", "")
+ if compact == key:
+ return float(value)
+ return 1.0
+
+
+def recency_decay(
+ happened_at: str | datetime | None,
+ half_life_days: float | None,
+ *,
+ now: datetime | None = None,
+) -> float:
+ if half_life_days is None or half_life_days <= 0:
+ return 1.0
+ if not happened_at:
+ return 1.0
+ parsed = (
+ parse_date_string(happened_at) if isinstance(happened_at, str) else happened_at
+ )
+ if not isinstance(parsed, datetime):
+ return 1.0
+ ref = now or datetime.now()
+ age_days = max(0.0, (to_naive_utc(ref) - to_naive_utc(parsed)).total_seconds() / 86400.0)
+ return float(0.5 ** (age_days / float(half_life_days)))
+
+
+def degree_dampen(degree: int, enabled: bool) -> float:
+ if not enabled:
+ return 1.0
+ return 1.0 / math.log2(2.0 + max(0, int(degree)))
+
+
+def attr_idf(degree: int, enabled: bool = True) -> float:
+ if not enabled:
+ return 1.0
+ return 1.0 / math.log2(2.0 + max(0, int(degree)))
+
+
+def _mmr_diversify(
+ items: List[Tuple[Node, float, List[Node], str]],
+ top_k: int,
+ lambda_mult: float = 0.7,
+) -> List[Tuple[Node, float, List[Node], str]]:
+ if not items or top_k <= 0:
+ return []
+ selected: List[Tuple[Node, float, List[Node], str]] = []
+ remaining = list(items)
+ selected_types: set[str] = set()
+
+ while remaining and len(selected) < top_k:
+ best_idx = 0
+ best_val = float("-inf")
+ for i, (node, score, _bridges, _kind) in enumerate(remaining):
+ labels = {l.upper() for l in node.labels}
+ overlap = len(labels & selected_types) / max(1, len(labels))
+ mmr = lambda_mult * score - (1.0 - lambda_mult) * overlap
+ if mmr > best_val:
+ best_val = mmr
+ best_idx = i
+ chosen = remaining.pop(best_idx)
+ selected.append(chosen)
+ selected_types.update(l.upper() for l in chosen[0].labels)
+ return selected
+
+
+def _node_degree(node: Node, brain_id: str) -> int:
+ neighbors = graph_adapter.get_neighbors([node.uuid], brain_id=brain_id).get(
+ node.uuid, []
+ )
+ return len(neighbors or [])
+
+
+def _collect_seen_product_uuids(seed: Node, brain_id: str) -> Set[str]:
+ seen: Set[str] = set()
+ event_neighbors = graph_adapter.get_neighbors(
+ [seed.uuid], of_types=["EVENT"], brain_id=brain_id
+ ).get(seed.uuid, [])
+ for pred, event_node in event_neighbors:
+ if not _predicate_currently_valid(pred):
+ continue
+ outs = graph_adapter.get_neighbors(
+ [event_node.uuid], brain_id=brain_id
+ ).get(event_node.uuid, [])
+ for pred2, tip in outs:
+ if not _predicate_currently_valid(pred2):
+ continue
+ if tip.uuid == seed.uuid:
+ continue
+ if "PRODUCT" in {l.upper() for l in tip.labels}:
+ seen.add(tip.uuid)
+ return seen
+
+
+def _asymmetric_event_targets(
+ seed: Node,
+ brain_id: str,
+ *,
+ direction: Literal["outbound", "inbound", "both"] = "outbound",
+ behavior_weights: Optional[Dict[str, float]] = None,
+ recency_half_life_days: Optional[float] = None,
+ dampen_degree: bool = False,
+) -> List[Tuple[Node, float, List[Node], str]]:
+ results: List[Tuple[Node, float, List[Node], str]] = []
+ if direction in ("outbound", "both"):
+ event_neighbors = graph_adapter.get_neighbors(
+ [seed.uuid], of_types=["EVENT"], brain_id=brain_id
+ ).get(seed.uuid, [])
+ for pred, event_node in event_neighbors:
+ if not _predicate_currently_valid(pred):
+ continue
+ base = behavior_weight(event_node.name, behavior_weights)
+ decay = recency_decay(event_node.happened_at, recency_half_life_days)
+ outs = graph_adapter.get_neighbors(
+ [event_node.uuid], brain_id=brain_id
+ ).get(event_node.uuid, [])
+ for pred2, tip in outs:
+ if not _predicate_currently_valid(pred2):
+ continue
+ if tip.uuid == seed.uuid:
+ continue
+ if "EVENT" in tip.labels:
+ continue
+ score = base * decay
+ if dampen_degree:
+ score *= degree_dampen(_node_degree(tip, brain_id), True)
+ results.append(
+ (tip, float(score), [event_node], "asymmetric_outbound")
+ )
+ if direction in ("inbound", "both"):
+ inbound = graph_adapter.get_neighbors(
+ [seed.uuid], brain_id=brain_id
+ ).get(seed.uuid, [])
+ for pred, neighbor in inbound:
+ if not _predicate_currently_valid(pred):
+ continue
+ if "EVENT" not in neighbor.labels:
+ continue
+ base = 0.55 * behavior_weight(neighbor.name, behavior_weights)
+ decay = recency_decay(neighbor.happened_at, recency_half_life_days)
+ actors = graph_adapter.get_neighbors(
+ [neighbor.uuid], brain_id=brain_id
+ ).get(neighbor.uuid, [])
+ for pred2, actor in actors:
+ if not _predicate_currently_valid(pred2):
+ continue
+ if actor.uuid == seed.uuid:
+ continue
+ if "EVENT" in actor.labels:
+ continue
+ score = base * decay
+ if dampen_degree:
+ score *= degree_dampen(_node_degree(actor, brain_id), True)
+ results.append(
+ (actor, float(score), [neighbor], "asymmetric_inbound")
+ )
+ return results
+
+
+def _multi_interest_medoids(
+ seed: Node,
+ brain_id: str,
+ max_clusters: int = 3,
+) -> List[Node]:
+ neighbors = graph_adapter.get_neighbors([seed.uuid], brain_id=brain_id).get(
+ seed.uuid, []
+ )
+ by_label: Dict[str, List[Node]] = defaultdict(list)
+ for pred, node in neighbors:
+ if not _predicate_currently_valid(pred):
+ continue
+ if "EVENT" in node.labels:
+ continue
+ label = (node.labels[0] if node.labels else "UNKNOWN").upper()
+ by_label[label].append(node)
+ ranked_groups = sorted(by_label.values(), key=len, reverse=True)
+ medoids: List[Node] = []
+ for group in ranked_groups[:max_clusters]:
+ if group:
+ medoids.append(group[0])
+ return medoids
+
+
+def _prefers_weight(pred) -> float:
+ props = pred.properties or {}
+ raw = props.get("weight", props.get("properties", {}).get("weight") if isinstance(props.get("properties"), dict) else None)
+ if raw is None and pred.amount is not None:
+ raw = pred.amount
+ try:
+ return float(raw) if raw is not None else 1.0
+ except (TypeError, ValueError):
+ return 1.0
+
+
+def _is_attr_node(node: Node) -> bool:
+ labels = {l.upper() for l in node.labels}
+ if labels & ATTR_LABELS:
+ return True
+ return any(str(l).upper().startswith("ATTR") for l in node.labels)
+
+
+def _products_for_attr(
+ attr: Node,
+ brain_id: str,
+ *,
+ seed_uuid: str,
+) -> List[Node]:
+ products: List[Node] = []
+ neighbors = graph_adapter.get_neighbors([attr.uuid], brain_id=brain_id).get(
+ attr.uuid, []
+ )
+ for pred, neighbor in neighbors:
+ if not _predicate_currently_valid(pred):
+ continue
+ labels = {l.upper() for l in neighbor.labels}
+ if "PRODUCT" in labels and neighbor.uuid != seed_uuid:
+ products.append(neighbor)
+ continue
+ if "EVENT" not in labels:
+ continue
+ tips = graph_adapter.get_neighbors(
+ [neighbor.uuid], brain_id=brain_id
+ ).get(neighbor.uuid, [])
+ for pred2, tip in tips:
+ if not _predicate_currently_valid(pred2):
+ continue
+ if tip.uuid == seed_uuid:
+ continue
+ if "PRODUCT" in {l.upper() for l in tip.labels}:
+ products.append(tip)
+ return products
+
+
+def _collaborative_user_item_targets(
+ seed: Node,
+ brain_id: str,
+ *,
+ behavior_weights: Optional[Dict[str, float]] = None,
+ recency_half_life_days: Optional[float] = None,
+ dampen_degree: bool = False,
+) -> List[Tuple[Node, float, List[Node], str]]:
+ """
+ USER → EVENT → PRODUCT → (other EVENTs) → other USERs → their PRODUCTs.
+ Produces unseen candidates for next-item RecSys (asymmetric alone only yields seen items).
+ """
+ results: List[Tuple[Node, float, List[Node], str]] = []
+ seen = _collect_seen_product_uuids(seed, brain_id)
+ if not seen:
+ return results
+
+ event_neighbors = graph_adapter.get_neighbors(
+ [seed.uuid], of_types=["EVENT"], brain_id=brain_id
+ ).get(seed.uuid, [])
+ seed_products: List[Tuple[Node, float]] = []
+ for pred, event_node in event_neighbors:
+ if not _predicate_currently_valid(pred):
+ continue
+ w = behavior_weight(event_node.name, behavior_weights)
+ w *= recency_decay(event_node.happened_at, recency_half_life_days)
+ tips = graph_adapter.get_neighbors(
+ [event_node.uuid], brain_id=brain_id
+ ).get(event_node.uuid, [])
+ for pred2, tip in tips:
+ if not _predicate_currently_valid(pred2):
+ continue
+ if tip.uuid in seen and "PRODUCT" in {l.upper() for l in tip.labels}:
+ seed_products.append((tip, w))
+
+ peer_scores: Dict[str, float] = defaultdict(float)
+ peer_nodes: Dict[str, Node] = {}
+ for product, seed_w in seed_products:
+ prod_neighbors = graph_adapter.get_neighbors(
+ [product.uuid], brain_id=brain_id
+ ).get(product.uuid, [])
+ for pred, neighbor in prod_neighbors:
+ if not _predicate_currently_valid(pred):
+ continue
+ if "EVENT" not in neighbor.labels:
+ continue
+ actors = graph_adapter.get_neighbors(
+ [neighbor.uuid], brain_id=brain_id
+ ).get(neighbor.uuid, [])
+ for pred2, actor in actors:
+ if not _predicate_currently_valid(pred2):
+ continue
+ if actor.uuid == seed.uuid:
+ continue
+ if "USER" not in {l.upper() for l in actor.labels}:
+ continue
+ peer_scores[actor.uuid] += seed_w
+ peer_nodes[actor.uuid] = actor
+
+ for peer_uuid, peer_w in peer_scores.items():
+ peer = peer_nodes[peer_uuid]
+ peer_events = graph_adapter.get_neighbors(
+ [peer.uuid], of_types=["EVENT"], brain_id=brain_id
+ ).get(peer.uuid, [])
+ for pred, event_node in peer_events:
+ if not _predicate_currently_valid(pred):
+ continue
+ bw = behavior_weight(event_node.name, behavior_weights)
+ bw *= recency_decay(event_node.happened_at, recency_half_life_days)
+ tips = graph_adapter.get_neighbors(
+ [event_node.uuid], brain_id=brain_id
+ ).get(event_node.uuid, [])
+ for pred2, tip in tips:
+ if not _predicate_currently_valid(pred2):
+ continue
+ if tip.uuid in seen or tip.uuid == seed.uuid:
+ continue
+ if "PRODUCT" not in {l.upper() for l in tip.labels}:
+ continue
+ score = float(peer_w * bw)
+ if dampen_degree:
+ score *= degree_dampen(_node_degree(tip, brain_id), True)
+ results.append(
+ (tip, score, [peer, event_node], "collaborative")
+ )
+ return results
+
+
+def _attribute_pref_targets(
+ seed: Node,
+ brain_id: str,
+ *,
+ dampen_attr_degree: bool = True,
+ behavior_weights: Optional[Dict[str, float]] = None,
+) -> List[Tuple[Node, float, List[Node], str]]:
+ results: List[Tuple[Node, float, List[Node], str]] = []
+ pref_scores: Dict[str, float] = defaultdict(float)
+ pref_nodes: Dict[str, Node] = {}
+
+ neighbors = graph_adapter.get_neighbors([seed.uuid], brain_id=brain_id).get(
+ seed.uuid, []
+ )
+ for pred, neighbor in neighbors:
+ if not _predicate_currently_valid(pred):
+ continue
+ if not _is_attr_node(neighbor):
+ continue
+ pred_name = (pred.name or "").upper()
+ if pred_name and pred_name not in {"PREFERS", "PREFER", "LIKES"}:
+ if "PREFER" not in pred_name and "LIKE" not in pred_name:
+ continue
+ pref_scores[neighbor.uuid] += _prefers_weight(pred)
+ pref_nodes[neighbor.uuid] = neighbor
+
+ # Read-time soft prefs from USER → EVENT → PRODUCT → ATTR when PREFERS absent.
+ if not pref_scores:
+ event_neighbors = graph_adapter.get_neighbors(
+ [seed.uuid], of_types=["EVENT"], brain_id=brain_id
+ ).get(seed.uuid, [])
+ for pred, event_node in event_neighbors:
+ if not _predicate_currently_valid(pred):
+ continue
+ bw = behavior_weight(event_node.name, behavior_weights)
+ tips = graph_adapter.get_neighbors(
+ [event_node.uuid], brain_id=brain_id
+ ).get(event_node.uuid, [])
+ for pred2, tip in tips:
+ if not _predicate_currently_valid(pred2):
+ continue
+ if "PRODUCT" not in {l.upper() for l in tip.labels}:
+ continue
+ prod_n = graph_adapter.get_neighbors(
+ [tip.uuid], brain_id=brain_id
+ ).get(tip.uuid, [])
+ for pred3, neigh in prod_n:
+ if not _predicate_currently_valid(pred3):
+ continue
+ attrs: List[Node] = []
+ if _is_attr_node(neigh):
+ attrs = [neigh]
+ elif "EVENT" in neigh.labels:
+ for pred4, tip2 in graph_adapter.get_neighbors(
+ [neigh.uuid], brain_id=brain_id
+ ).get(neigh.uuid, []):
+ if not _predicate_currently_valid(pred4):
+ continue
+ if _is_attr_node(tip2):
+ attrs.append(tip2)
+ for attr in attrs:
+ pref_scores[attr.uuid] += bw
+ pref_nodes[attr.uuid] = attr
+
+ for attr_uuid, pref_w in pref_scores.items():
+ attr = pref_nodes[attr_uuid]
+ idf = attr_idf(_node_degree(attr, brain_id), dampen_attr_degree)
+ for product in _products_for_attr(
+ attr, brain_id, seed_uuid=seed.uuid
+ ):
+ results.append(
+ (
+ product,
+ float(pref_w * idf),
+ [attr],
+ "attribute_pref",
+ )
+ )
+ return results
+
+
+class EntityRecommendRetriever:
+ def __init__(self, brain_id: str = "default"):
+ self.brain_id = brain_id
+ self._synergies = EntitySinergyRetriever(brain_id)
+
+ def recommend(
+ self,
+ target: str,
+ *,
+ polarity: Literal["same", "opposite"] = "same",
+ top_k: int = DEFAULT_TOP_K,
+ labels: Optional[List[str]] = None,
+ include_asymmetric: bool = True,
+ include_multi_interest: bool = True,
+ include_attribute_pref: bool = False,
+ diversify: bool = True,
+ asymmetric_direction: Literal["outbound", "inbound", "both"] = "outbound",
+ exclude_seen: bool = False,
+ recency_half_life_days: Optional[float] = None,
+ dampen_degree: bool = False,
+ behavior_weights: Optional[Dict[str, float]] = None,
+ ) -> Tuple[Optional[Node], List[dict]]:
+ target_node, synergies, _anchors, _pa = self._synergies.retrieve_sibilings(
+ target,
+ polarity,
+ do=False,
+ pa=False,
+ ppa=False,
+ top_k=max(top_k * 3, top_k),
+ labels=labels,
+ )
+ if target_node is None:
+ return None, []
+
+ seen_uuids: Set[str] = set()
+ if exclude_seen:
+ seen_uuids = _collect_seen_product_uuids(target_node, self.brain_id)
+
+ pool: List[Tuple[Node, float, List[Node], str]] = []
+ for syn in synergies:
+ pool.append(
+ (
+ syn.node,
+ float(syn.association_score),
+ list(syn.connected_by),
+ "synergy",
+ )
+ )
+
+ if include_asymmetric:
+ pool.extend(
+ _asymmetric_event_targets(
+ target_node,
+ self.brain_id,
+ direction=asymmetric_direction,
+ behavior_weights=behavior_weights,
+ recency_half_life_days=recency_half_life_days,
+ dampen_degree=dampen_degree,
+ )
+ )
+ if "USER" in {l.upper() for l in target_node.labels}:
+ pool.extend(
+ _collaborative_user_item_targets(
+ target_node,
+ self.brain_id,
+ behavior_weights=behavior_weights,
+ recency_half_life_days=recency_half_life_days,
+ dampen_degree=dampen_degree,
+ )
+ )
+
+ if include_multi_interest:
+ for medoid in _multi_interest_medoids(target_node, self.brain_id):
+ if medoid.uuid == target_node.uuid:
+ continue
+ _, medoid_syns, _, _ = self._synergies.retrieve_sibilings(
+ medoid.name,
+ polarity,
+ do=True,
+ top_k=max(5, top_k // 2),
+ labels=labels,
+ )
+ for syn in medoid_syns:
+ if syn.node.uuid == target_node.uuid:
+ continue
+ pool.append(
+ (
+ syn.node,
+ float(syn.association_score) * 0.85,
+ [medoid] + list(syn.connected_by),
+ "multi_interest",
+ )
+ )
+
+ if include_attribute_pref:
+ pool.extend(
+ _attribute_pref_targets(
+ target_node,
+ self.brain_id,
+ dampen_attr_degree=True,
+ behavior_weights=behavior_weights,
+ )
+ )
+
+ merged: Dict[str, Tuple[Node, float, List[Node], str]] = {}
+ for node, score, bridges, kind in pool:
+ if node.uuid == target_node.uuid:
+ continue
+ if exclude_seen and node.uuid in seen_uuids:
+ continue
+ if labels:
+ label_set = {l.upper() for l in labels}
+ if not set(l.upper() for l in node.labels).intersection(label_set):
+ continue
+ if dampen_degree and kind in {"synergy", "multi_interest", "attribute_pref"}:
+ score = float(score) * degree_dampen(
+ _node_degree(node, self.brain_id), True
+ )
+ prev = merged.get(node.uuid)
+ if prev is None or score > prev[1]:
+ merged[node.uuid] = (node, score, bridges, kind)
+ elif prev is not None:
+ bridge_ids = {b.uuid for b in prev[2]}
+ extra = [b for b in bridges if b.uuid not in bridge_ids]
+ merged[node.uuid] = (
+ prev[0],
+ prev[1],
+ prev[2] + extra,
+ prev[3],
+ )
+
+ ranked = sorted(merged.values(), key=lambda x: x[1], reverse=True)
+ if diversify:
+ ranked = _mmr_diversify(ranked, top_k)
+ else:
+ ranked = ranked[:top_k]
+
+ recommendations = [
+ {
+ "node": node,
+ "score": score,
+ "connected_by": bridges,
+ "channel": kind,
+ }
+ for node, score, bridges, kind in ranked
+ ]
+ return target_node, recommendations
diff --git a/src/core/search/synergy_metrics.py b/src/core/search/synergy_metrics.py
new file mode 100644
index 0000000..1f150ad
--- /dev/null
+++ b/src/core/search/synergy_metrics.py
@@ -0,0 +1,74 @@
+"""
+Structural recommendation / synergies metrics (deterministic, no LLM judge).
+
+Does not upsert LoCoMo/BEAM REPORTS.json. See docs/research/04 §4.9 and
+docs/research/15 §6 (topology-aware eval).
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Sequence
+
+
+def intra_list_diversity(label_sets: Sequence[Sequence[str]]) -> float:
+ """Fraction of pairwise label-set Jaccard distances (1 - intersection/union)."""
+ n = len(label_sets)
+ if n < 2:
+ return 0.0
+ sets = [set(l.upper() for l in labels) for labels in label_sets]
+ total = 0.0
+ pairs = 0
+ for i in range(n):
+ for j in range(i + 1, n):
+ union = sets[i] | sets[j]
+ if not union:
+ dist = 0.0
+ else:
+ dist = 1.0 - (len(sets[i] & sets[j]) / len(union))
+ total += dist
+ pairs += 1
+ return total / pairs if pairs else 0.0
+
+
+def type_coverage(label_sets: Sequence[Sequence[str]]) -> int:
+ """Number of distinct labels appearing in the recommendation list."""
+ covered = set()
+ for labels in label_sets:
+ covered.update(l.upper() for l in labels)
+ return len(covered)
+
+
+def unexpectedness_by_graph_distance(
+ distances: Iterable[int],
+ *,
+ max_distance: int = 4,
+) -> float:
+ """
+ Mean normalized hop distance from seed (higher => more unexpected).
+ Missing / unknown distances contribute 0.
+ """
+ vals = list(distances)
+ if not vals:
+ return 0.0
+ capped = [min(max(0, d), max_distance) / max_distance for d in vals]
+ return sum(capped) / len(capped)
+
+
+def popularity_stratum(degree: int, *, head_threshold: int = 20) -> str:
+ if degree >= head_threshold:
+ return "head"
+ if degree <= 2:
+ return "tail"
+ return "torso"
+
+
+def summarize_recommendation_list(
+ label_sets: Sequence[Sequence[str]],
+ distances: Sequence[int],
+) -> dict:
+ return {
+ "n": len(label_sets),
+ "intra_list_diversity": intra_list_diversity(label_sets),
+ "type_coverage": type_coverage(label_sets),
+ "unexpectedness": unexpectedness_by_graph_distance(distances),
+ }
diff --git a/src/services/api/constants/requests.py b/src/services/api/constants/requests.py
index 0ca0955..f71ea48 100644
--- a/src/services/api/constants/requests.py
+++ b/src/services/api/constants/requests.py
@@ -8,7 +8,7 @@ Modified By: Christian Nonis <[email protected]>
-----
"""
-from typing import Any, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Literal, Optional, Tuple, Union
from pydantic import BaseModel, Field, field_serializer, field_validator, model_validator
@@ -162,6 +162,16 @@ class IngestionStructuredRequestBody(BaseModel):
default=None,
description="Additional text context for the structured data.",
)
+ mode: Optional[Literal["deterministic", "hybrid", "enrich"]] = Field(
+ default=None,
+ description=(
+ "Ingest mode. deterministic: no LLM (triples only; UUID anchor or "
+ "exact name+type match). hybrid: persist submitted triples then "
+ "optionally enrich from text. enrich: same as hybrid with LLM "
+ "backfill. When omitted, inferred as hybrid if text is set else "
+ "deterministic."
+ ),
+ )
brain_id: str = Field(
default="default", description="The brain identifier to store the data in."
)
@@ -175,6 +185,11 @@ class IngestionStructuredRequestBody(BaseModel):
)
return value
+ def resolved_mode(self) -> Literal["deterministic", "hybrid", "enrich"]:
+ if self.mode is not None:
+ return self.mode
+ return "hybrid" if self.text else "deterministic"
+
class RetrieveRequestResponse(BaseModel):
"""
@@ -377,6 +392,37 @@ class GetEntitySibilingsResponse(BaseModel):
potential_anchors: Optional[List[Node]] = None
+class RecommendRequestBody(BaseModel):
+ """Request body for event-graph recommendations."""
+
+ target: str
+ brain_id: str = "default"
+ polarity: Literal["same", "opposite"] = "same"
+ top_k: int = Field(20, ge=1, le=200)
+ labels: Optional[List[str]] = None
+ include_asymmetric: bool = True
+ include_multi_interest: bool = True
+ include_attribute_pref: bool = False
+ diversify: bool = True
+ asymmetric_direction: Literal["outbound", "inbound", "both"] = "outbound"
+ exclude_seen: bool = False
+ recency_half_life_days: Optional[float] = Field(None, ge=0)
+ dampen_degree: bool = False
+ behavior_weights: Optional[Dict[str, float]] = None
+
+
+class RecommendItem(BaseModel):
+ node: Node
+ score: float
+ connected_by: List[Node]
+ channel: str
+
+
+class RecommendResponse(BaseModel):
+ target_node: Node
+ recommendations: List[RecommendItem]
+
+
class GetEntityStatusResponse(BaseModel):
"""Response model for the get entity status endpoint."""
diff --git a/src/services/api/controllers/entities.py b/src/services/api/controllers/entities.py
index d6ebaf6..995c55f 100644
--- a/src/services/api/controllers/entities.py
+++ b/src/services/api/controllers/entities.py
@@ -9,7 +9,7 @@ Modified By: Christian Nonis <[email protected]>
-----
"""
-from typing import List, Literal
+from typing import List, Literal, Optional
from starlette.responses import JSONResponse
from src.core.search.entity_context import EntityContext
@@ -19,8 +19,11 @@ from src.services.api.constants.requests import (
GetEntityContextResponse,
GetEntitySibilingsResponse,
GetEntityStatusResponse,
+ RecommendItem,
+ RecommendResponse,
)
from src.core.search.entity_sibilings import EntitySinergyRetriever
+from src.core.search.recommend import EntityRecommendRetriever
from src.services.data.main import data_adapter
from src.services.input.agents import embeddings_adapter
from src.services.kg_agent.main import graph_adapter, vector_store_adapter
@@ -86,23 +89,29 @@ async def get_entity_sibilings(
do: bool = False,
pa: bool = False,
ppa: bool = False,
+ top_k: int = 50,
+ labels: Optional[List[str]] = None,
brain_id: str = "default",
) -> GetEntitySibilingsResponse:
"""
Retrieve sibling entities (synergies) for a target entity.
Parameters:
- polarity (Literal["same", "opposite"]): Which polarity of siblings to return — "same" for similar entities, "opposite" for contrasted entities.
- do (bool): If True, only direct synergies are returned.
- pa (bool): If True, potential anchors are returned.
- ppa (bool): If True, potential positive anchors are returned.
+ polarity: "same" for matching node polarity; "opposite" for positive↔negative.
+ do: If True, only direct synergies are returned.
+ pa: If True, potential anchors are returned.
+ ppa: If True, seed anchors are returned.
+ top_k: Max synergies to return.
+ labels: Optional label filter for candidates.
Returns:
GetEntitySibilingsResponse: Object containing the resolved target node and its list of synergies.
"""
entity_sibilings = EntitySinergyRetriever(brain_id)
target_node, synergies, seed_nodes, potential_anchors = (
- entity_sibilings.retrieve_sibilings(target, polarity, do, pa, ppa)
+ entity_sibilings.retrieve_sibilings(
+ target, polarity, do, pa, ppa, top_k=top_k, labels=labels
+ )
)
if target_node is None:
return JSONResponse(
@@ -131,6 +140,60 @@ async def get_entity_sibilings(
)
+async def get_recommendations(
+ target: str,
+ polarity: Literal["same", "opposite"] = "same",
+ top_k: int = 20,
+ labels: Optional[List[str]] = None,
+ include_asymmetric: bool = True,
+ include_multi_interest: bool = True,
+ diversify: bool = True,
+ asymmetric_direction: Literal["outbound", "inbound", "both"] = "outbound",
+ brain_id: str = "default",
+ exclude_seen: bool = False,
+ recency_half_life_days: Optional[float] = None,
+ dampen_degree: bool = False,
+ include_attribute_pref: bool = False,
+ behavior_weights: Optional[dict] = None,
+) -> RecommendResponse:
+ retriever = EntityRecommendRetriever(brain_id)
+ target_node, recommendations = retriever.recommend(
+ target,
+ polarity=polarity,
+ top_k=top_k,
+ labels=labels,
+ include_asymmetric=include_asymmetric,
+ include_multi_interest=include_multi_interest,
+ include_attribute_pref=include_attribute_pref,
+ diversify=diversify,
+ asymmetric_direction=asymmetric_direction,
+ exclude_seen=exclude_seen,
+ recency_half_life_days=recency_half_life_days,
+ dampen_degree=dampen_degree,
+ behavior_weights=behavior_weights,
+ )
+ if target_node is None:
+ return JSONResponse(
+ status_code=404,
+ content={"detail": "No entity found matching the target."},
+ )
+ items = [
+ RecommendItem(
+ node=r["node"],
+ score=r["score"],
+ connected_by=r["connected_by"],
+ channel=r["channel"],
+ )
+ for r in recommendations
+ ]
+ return JSONResponse(
+ content=RecommendResponse(
+ target_node=target_node,
+ recommendations=items,
+ ).model_dump(mode="json")
+ )
+
+
async def get_entity_status(
target: str,
types: List[str] | None = None,
diff --git a/src/services/api/routes/retrieve.py b/src/services/api/routes/retrieve.py
index b265a3c..d3e0c7d 100644
--- a/src/services/api/routes/retrieve.py
+++ b/src/services/api/routes/retrieve.py
@@ -16,6 +16,7 @@ from src.services.api.dependencies import get_brain_id
from src.services.api.constants.requests import (
GetContextRequestBody,
GetContextResponse,
+ RecommendRequestBody,
RetrieveNeighborsAiModeRequestBody,
RetrieveNeighborsWithIdentificationParamsRequestBody,
RetrieveRequestResponse,
@@ -53,6 +54,7 @@ from src.services.api.controllers.entities import (
get_entity_context as get_entity_context_controller,
get_entity_sibilings as get_entity_sibilings_controller,
get_entity_status as get_entity_status_controller,
+ get_recommendations as get_recommendations_controller,
)
from src.services.api.controllers.vectors import (
get_vector_stores as get_vector_stores_controller,
@@ -505,24 +507,90 @@ async def get_entity_synergies(
do: bool = False,
pa: bool = False,
ppa: bool = False,
+ top_k: int = 50,
+ labels: Optional[List[str]] = None,
brain_id: str = Depends(get_brain_id),
):
"""
Retrieve synergies for a specified entity.
Parameters:
- target (str): Identifier or name of the target entity.
- polarity (Literal["same", "opposite"]): Which type of synergies to return: "same" for similar/aligned synergies, "opposite" for contrasting/opposing synergies.
- brain_id (str): Identifier of the knowledge brain to query.
- do (bool): If True, only direct synergies are returned.
- pa (bool): If True, potential anchors are returned.
- ppa (bool): If True, potential positive anchors are returned.
+ target: Identifier or name of the target entity.
+ polarity: "same" for matching node polarity; "opposite" for positive↔negative.
+ do: If True, only direct synergies are returned.
+ pa: If True, potential anchors are returned.
+ ppa: If True, seed anchors are returned.
+ top_k: Maximum synergies to return (default 50).
+ labels: Optional candidate label filter.
+ brain_id: Identifier of the knowledge brain to query.
Returns:
- list: A list of synergy records for the target entity matching the requested polarity.
+ Synergy records for the target entity matching the requested polarity.
"""
return await get_entity_sibilings_controller(
- target, polarity, do, pa, ppa, brain_id
+ target, polarity, do, pa, ppa, top_k, labels, brain_id
+ )
+
+
+@retrieve_router.get(path="/recommend")
+async def get_recommend(
+ target: str,
+ polarity: Literal["same", "opposite"] = "same",
+ top_k: int = 20,
+ labels: Optional[List[str]] = None,
+ include_asymmetric: bool = True,
+ include_multi_interest: bool = True,
+ include_attribute_pref: bool = False,
+ diversify: bool = True,
+ asymmetric_direction: Literal["outbound", "inbound", "both"] = "outbound",
+ exclude_seen: bool = False,
+ recency_half_life_days: Optional[float] = None,
+ dampen_degree: bool = False,
+ brain_id: str = Depends(get_brain_id),
+):
+ """
+ Ranked event-graph recommendations composing synergies, asymmetric
+ complementary walks, multi-interest medoids, and optional attribute
+ preferences (retrieval-time only; no training).
+ """
+ return await get_recommendations_controller(
+ target,
+ polarity,
+ top_k,
+ labels,
+ include_asymmetric,
+ include_multi_interest,
+ diversify,
+ asymmetric_direction,
+ brain_id,
+ exclude_seen,
+ recency_half_life_days,
+ dampen_degree,
+ include_attribute_pref,
+ None,
+ )
+
+
+@retrieve_router.post(path="/recommend")
+async def post_recommend(
+ body: RecommendRequestBody,
+ brain_id: str = Depends(get_brain_id),
+):
+ return await get_recommendations_controller(
+ body.target,
+ body.polarity,
+ body.top_k,
+ body.labels,
+ body.include_asymmetric,
+ body.include_multi_interest,
+ body.diversify,
+ body.asymmetric_direction,
+ brain_id or body.brain_id,
+ body.exclude_seen,
+ body.recency_half_life_days,
+ body.dampen_degree,
+ body.include_attribute_pref,
+ body.behavior_weights,
)
diff --git a/src/workers/tasks/ingestion.py b/src/workers/tasks/ingestion.py
index 06e176d..069d2ec 100644
--- a/src/workers/tasks/ingestion.py
+++ b/src/workers/tasks/ingestion.py
@@ -1192,15 +1192,33 @@ def ingest_structured_data(self, args: dict):
payload = None
try:
payload = IngestionStructuredRequestBody(**args)
+ mode = payload.resolved_mode()
set_ingestion_task_status(
self.request.id,
payload.brain_id,
"started",
stage="source",
- counts={"triples": len(payload.data)},
+ counts={"triples": len(payload.data), "mode": mode},
)
+ if mode == "deterministic" and payload.anchor is not None:
+ if not payload.anchor.uuid and not (
+ payload.anchor.name and payload.anchor.type
+ ):
+ error = (
+ "deterministic mode requires anchor.uuid or exact name+type; "
+ "LLM entity verification is not allowed"
+ )
+ set_ingestion_task_status(
+ self.request.id,
+ payload.brain_id,
+ "failed",
+ stage="anchor",
+ error=error,
+ )
+ raise ValueError(error)
+
anchor = None
ingestion_manager = IngestionManager(
embeddings_adapter, vector_store_adapter, graph_adapter
@@ -1231,6 +1249,20 @@ def ingest_structured_data(self, args: dict):
entity_types=[payload.anchor.type] if payload.anchor.type else None,
)
if not anchor:
+ if mode == "deterministic":
+ error = (
+ "deterministic mode: anchor not found by exact name+type; "
+ "provide anchor.uuid or create the node first "
+ "(LLM verify_entity_existence is disabled)"
+ )
+ set_ingestion_task_status(
+ self.request.id,
+ payload.brain_id,
+ "failed",
+ stage="anchor",
+ error=error,
+ )
+ raise ValueError(error)
txt = (
payload.anchor.name + "; " + (payload.anchor.meta_description or "")
)
@@ -1291,6 +1323,7 @@ def ingest_structured_data(self, args: dict):
data={
"triples": [t.model_dump(mode="json") for t in payload.data],
"text": payload.text,
+ "mode": mode,
"anchor": (
payload.anchor.model_dump(mode="json")
if payload.anchor
@@ -1298,7 +1331,7 @@ def ingest_structured_data(self, args: dict):
),
},
types=["ingestion_structured"],
- metadata={"task_id": self.request.id},
+ metadata={"task_id": self.request.id, "mode": mode},
brain_version=BRAIN_VERSION,
),
brain_id=payload.brain_id,
@@ -1317,12 +1350,20 @@ def ingest_structured_data(self, args: dict):
required_relationships, _ = ingestion_triples_to_relationships(
current_triples, partial_triples
)
+ for rel in required_relationships:
+ props = dict(rel.properties or {})
+ props.setdefault("source", "structured_deterministic")
+ rel.properties = props
persistence_batches = [
rel.model_dump(mode="json") for rel in required_relationships
]
session_id = None
- if payload.text:
+ run_llm_enrichment = mode in ("hybrid", "enrich") and bool(payload.text)
+ if mode == "deterministic":
+ run_llm_enrichment = False
+
+ if run_llm_enrichment:
scout_agent = ScoutAgent(
llm_adapter=llm_small_adapter,
cache_adapter=cache_adapter,
@@ -1361,6 +1402,10 @@ def ingest_structured_data(self, args: dict):
)
enrichment = architect_agent.take_pending_relationships()
session_id = architect_agent.session_id
+ for rel in enrichment:
+ props = dict(rel.properties or {})
+ props["source"] = "llm_enrichment"
+ rel.properties = props
persistence_batches.extend(
rel.model_dump(mode="json") for rel in enrichment
)
diff --git a/tests/plugins_path_helper.py b/tests/plugins_path_helper.py
new file mode 100644
index 0000000..2bc4fb7
--- /dev/null
+++ b/tests/plugins_path_helper.py
@@ -0,0 +1,30 @@
+"""Load plugin modules without installing the plugin package."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+PLUGIN = ROOT / "plugins" / "recsys-gnn"
+
+
+def _load(name: str, path: Path):
+ # Ensure plugin root is on path so `from models.X` works inside modules.
+ plugin_str = str(PLUGIN)
+ if plugin_str not in sys.path:
+ sys.path.insert(0, plugin_str)
+ spec = importlib.util.spec_from_file_location(name, path)
+ assert spec and spec.loader
+ mod = importlib.util.module_from_spec(spec)
+ sys.modules[name] = mod
+ spec.loader.exec_module(mod)
+ return mod
+
+
+def load_export_edges():
+ return _load(
+ "recsys_gnn_export_edges",
+ PLUGIN / "models" / "export_edges.py",
+ )
diff --git a/tests/test_benchmark_contract_guardrails.py b/tests/test_benchmark_contract_guardrails.py
new file mode 100644
index 0000000..69cd877
--- /dev/null
+++ b/tests/test_benchmark_contract_guardrails.py
@@ -0,0 +1,75 @@
+import os
+import unittest
+from pathlib import Path
+
+ENV_DEFAULTS = {
+ "BRAINPAT_TOKEN": "test-token",
+ "MODELS_MODE": "local",
+ "EMBEDDINGS_LOCAL_MODEL": "local-model",
+ "EMBEDDINGS_SMALL_MODEL": "small-model",
+ "EMBEDDING_NODES_DIMENSION": "3",
+ "EMBEDDING_TRIPLETS_DIMENSION": "3",
+ "EMBEDDING_OBSERVATIONS_DIMENSION": "3",
+ "EMBEDDING_DATA_DIMENSION": "3",
+ "EMBEDDING_RELATIONSHIPS_DIMENSION": "3",
+ "REDIS_HOST": "localhost",
+ "REDIS_PORT": "6379",
+ "NEO4J_HOST": "localhost",
+ "NEO4J_PORT": "7687",
+ "NEO4J_USERNAME": "neo4j",
+ "NEO4J_PASSWORD": "password",
+ "MILVUS_HOST": "localhost",
+ "MILVUS_PORT": "19530",
+ "MONGO_CONNECTION_STRING": "mongodb://localhost:27017",
+ "CELERY_WORKER_CONCURRENCY": "1",
+ "OLLAMA_HOST": "localhost",
+ "OLLAMA_PORT": "11434",
+ "OLLAMA_LLM_SMALL_MODEL": "small",
+ "OLLAMA_LLM_LARGE_MODEL": "large",
+}
+for key, value in ENV_DEFAULTS.items():
+ os.environ.setdefault(key, value)
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class BenchmarkContractGuardrailsTests(unittest.TestCase):
+ """Ensure LoCoMo/BEAM/LME clients stay on frozen HTTP contracts."""
+
+ def _client_sources(self) -> list[Path]:
+ paths = []
+ for suite in ("locomo", "beam", "longmemeval"):
+ client = ROOT / "benchmarks" / suite / "client.py"
+ if client.exists():
+ paths.append(client)
+ return paths
+
+ def test_bench_clients_use_ingest_and_context_only(self):
+ clients = self._client_sources()
+ self.assertGreaterEqual(len(clients), 1)
+ forbidden = (
+ "/ingest/structured",
+ "/retrieve/entity/synergies",
+ "/retrieve/recommend",
+ "/recsys/",
+ )
+ for path in clients:
+ text = path.read_text(encoding="utf-8")
+ for needle in forbidden:
+ self.assertNotIn(
+ needle,
+ text,
+ msg=f"{path} must not call {needle} (benchmark isolation)",
+ )
+
+ def test_bench_clients_call_core_ingest(self):
+ for path in self._client_sources():
+ text = path.read_text(encoding="utf-8")
+ self.assertTrue(
+ "/ingest/" in text or "ingest" in text.lower(),
+ msg=f"{path} should still target core ingest",
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_entity_synergies.py b/tests/test_entity_synergies.py
new file mode 100644
index 0000000..b66da77
--- /dev/null
+++ b/tests/test_entity_synergies.py
@@ -0,0 +1,138 @@
+import os
+import unittest
+from unittest.mock import MagicMock, patch
+
+ENV_DEFAULTS = {
+ "BRAINPAT_TOKEN": "test-token",
+ "MODELS_MODE": "local",
+ "EMBEDDINGS_LOCAL_MODEL": "local-model",
+ "EMBEDDINGS_SMALL_MODEL": "small-model",
+ "EMBEDDING_NODES_DIMENSION": "3",
+ "EMBEDDING_TRIPLETS_DIMENSION": "3",
+ "EMBEDDING_OBSERVATIONS_DIMENSION": "3",
+ "EMBEDDING_DATA_DIMENSION": "3",
+ "EMBEDDING_RELATIONSHIPS_DIMENSION": "3",
+ "REDIS_HOST": "localhost",
+ "REDIS_PORT": "6379",
+ "NEO4J_HOST": "localhost",
+ "NEO4J_PORT": "7687",
+ "NEO4J_USERNAME": "neo4j",
+ "NEO4J_PASSWORD": "password",
+ "MILVUS_HOST": "localhost",
+ "MILVUS_PORT": "19530",
+ "MONGO_CONNECTION_STRING": "mongodb://localhost:27017",
+ "CELERY_WORKER_CONCURRENCY": "1",
+ "OLLAMA_HOST": "localhost",
+ "OLLAMA_PORT": "11434",
+ "OLLAMA_LLM_SMALL_MODEL": "small",
+ "OLLAMA_LLM_LARGE_MODEL": "large",
+ "PIPELINE_MODE": "accurate",
+}
+for key, value in ENV_DEFAULTS.items():
+ os.environ.setdefault(key, value)
+
+
+class PolarityMatchesTests(unittest.TestCase):
+ def test_same_matching_and_neutral(self):
+ from src.core.search.entity_sibilings import polarity_matches
+
+ self.assertTrue(polarity_matches("positive", "positive", "same"))
+ self.assertTrue(polarity_matches(None, None, "same"))
+ self.assertTrue(polarity_matches("neutral", None, "same"))
+ self.assertFalse(polarity_matches("positive", "negative", "same"))
+
+ def test_opposite_pos_neg_only(self):
+ from src.core.search.entity_sibilings import polarity_matches
+
+ self.assertTrue(polarity_matches("positive", "negative", "opposite"))
+ self.assertTrue(polarity_matches("negative", "positive", "opposite"))
+ self.assertFalse(polarity_matches("positive", "positive", "opposite"))
+ self.assertFalse(polarity_matches(None, "negative", "opposite"))
+ self.assertFalse(polarity_matches("neutral", "positive", "opposite"))
+
+
+class SynergyTopKAndValidityTests(unittest.TestCase):
+ def test_predicate_validity(self):
+ from src.constants.kg import Predicate
+ from src.core.search.entity_sibilings import _predicate_currently_valid
+
+ ok = Predicate.model_construct(
+ uuid="p1", name="MADE", properties={}, deprecated=False
+ )
+ self.assertTrue(_predicate_currently_valid(ok))
+ bad = Predicate.model_construct(
+ uuid="p2",
+ name="MADE",
+ properties={"invalid_at": "2024-01-01"},
+ deprecated=False,
+ )
+ self.assertFalse(_predicate_currently_valid(bad))
+ dep = Predicate.model_construct(
+ uuid="p3", name="MADE", properties={}, deprecated=True
+ )
+ self.assertFalse(_predicate_currently_valid(dep))
+
+ def test_top_k_bounds_results(self):
+ from src.constants.kg import EntitySynergy, Node
+ from src.core.search import entity_sibilings as mod
+
+ target = Node.model_construct(
+ uuid="t1",
+ name="Widget",
+ labels=["PRODUCT"],
+ polarity="positive",
+ properties={"v_id": "tv"},
+ )
+ candidates = [
+ EntitySynergy(
+ node=Node.model_construct(
+ uuid=f"c{i}",
+ name=f"C{i}",
+ labels=["PRODUCT"],
+ polarity="positive",
+ properties={},
+ ),
+ connected_by=[target],
+ association_score=float(10 - i),
+ )
+ for i in range(5)
+ ]
+
+ retriever = mod.EntitySinergyRetriever("recsys-test")
+
+ embed = MagicMock()
+ embed.embeddings = [0.1, 0.2, 0.3]
+ vs = MagicMock()
+ vs.metadata = {"uuid": "t1"}
+
+ with (
+ patch.object(mod, "embeddings_adapter") as emb,
+ patch.object(mod, "vector_search") as vsearch,
+ patch.object(mod, "graph_adapter") as graph,
+ patch.object(mod, "vector_store_adapter"),
+ ):
+ emb.embed_text.return_value = embed
+ vsearch.search_nodes.return_value = [vs]
+ graph.get_by_uuid.return_value = target
+ graph.get_neighbors.return_value = {"t1": []}
+
+ def fake_retrieve(*args, **kwargs):
+ top_k = kwargs.get("top_k", 50)
+ ranked = sorted(
+ candidates, key=lambda x: x.association_score, reverse=True
+ )
+ return target, ranked[:top_k], [], []
+
+ with patch.object(
+ retriever, "retrieve_sibilings", side_effect=fake_retrieve
+ ):
+ _, syn, _, _ = retriever.retrieve_sibilings(
+ "Widget", "same", top_k=2
+ )
+ self.assertEqual(len(syn), 2)
+ self.assertEqual(syn[0].node.uuid, "c0")
+ self.assertEqual(syn[1].node.uuid, "c1")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_recommend_recsys.py b/tests/test_recommend_recsys.py
new file mode 100644
index 0000000..45a6b16
--- /dev/null
+++ b/tests/test_recommend_recsys.py
@@ -0,0 +1,239 @@
+import os
+import sys
+import unittest
+from datetime import datetime, timedelta
+from unittest.mock import MagicMock, patch
+
+ENV_DEFAULTS = {
+ "BRAINPAT_TOKEN": "test-token",
+ "MODELS_MODE": "local",
+ "EMBEDDINGS_LOCAL_MODEL": "local-model",
+ "EMBEDDINGS_SMALL_MODEL": "small-model",
+ "EMBEDDING_NODES_DIMENSION": "3",
+ "EMBEDDING_TRIPLETS_DIMENSION": "3",
+ "EMBEDDING_OBSERVATIONS_DIMENSION": "3",
+ "EMBEDDING_DATA_DIMENSION": "3",
+ "EMBEDDING_RELATIONSHIPS_DIMENSION": "3",
+ "REDIS_HOST": "localhost",
+ "REDIS_PORT": "6379",
+ "NEO4J_HOST": "localhost",
+ "NEO4J_PORT": "7687",
+ "NEO4J_USERNAME": "neo4j",
+ "NEO4J_PASSWORD": "password",
+ "MILVUS_HOST": "localhost",
+ "MILVUS_PORT": "19530",
+ "MONGO_CONNECTION_STRING": "mongodb://localhost:27017",
+ "CELERY_WORKER_CONCURRENCY": "1",
+ "OLLAMA_HOST": "localhost",
+ "OLLAMA_PORT": "11434",
+ "OLLAMA_LLM_SMALL_MODEL": "small",
+ "OLLAMA_LLM_LARGE_MODEL": "large",
+ "POSTGRES_HOST": "localhost",
+ "POSTGRES_PORT": "5432",
+ "POSTGRES_USERNAME": "postgres",
+ "POSTGRES_PASSWORD": "postgres",
+}
+for key, value in ENV_DEFAULTS.items():
+ os.environ.setdefault(key, value)
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.constants.kg import Node, Predicate
+from src.core.search.recommend import (
+ DEFAULT_BEHAVIOR_WEIGHTS,
+ EntityRecommendRetriever,
+ behavior_weight,
+ degree_dampen,
+ recency_decay,
+ attr_idf,
+)
+
+
+def _node(uuid: str, name: str, labels: list[str], happened_at=None) -> Node:
+ return Node.model_construct(
+ uuid=uuid,
+ name=name,
+ labels=labels,
+ happened_at=happened_at,
+ properties={},
+ )
+
+
+def _pred(name: str = "MADE", weight=None) -> Predicate:
+ props = {"weight": weight} if weight is not None else {}
+ return Predicate.model_construct(
+ uuid=f"pred-{name}-{weight}",
+ name=name,
+ description=name,
+ properties=props,
+ deprecated=False,
+ )
+
+
+class BehaviorWeightTests(unittest.TestCase):
+ def test_purchase_higher_than_view(self):
+ self.assertEqual(behavior_weight("Purchase"), 1.0)
+ self.assertEqual(behavior_weight("View"), 0.2)
+ self.assertEqual(behavior_weight("AddToCart"), 0.5)
+
+ def test_unknown_defaults_to_one(self):
+ self.assertEqual(behavior_weight("WeirdEvent"), 1.0)
+
+ def test_custom_table(self):
+ self.assertEqual(behavior_weight("View", {"view": 0.9}), 0.9)
+
+
+class RecencyDecayTests(unittest.TestCase):
+ def test_off_when_half_life_none(self):
+ self.assertEqual(recency_decay("01/01/2020", None), 1.0)
+
+ def test_older_decays_more(self):
+ now = datetime(2026, 8, 6)
+ older = recency_decay("01/01/2020", 30.0, now=now)
+ newer = recency_decay("01/08/2026", 30.0, now=now)
+ self.assertLess(older, newer)
+ self.assertLessEqual(newer, 1.0)
+
+ def test_half_life_halves(self):
+ now = datetime(2026, 8, 6)
+ past = (now - timedelta(days=30)).strftime("%d/%m/%Y")
+ score = recency_decay(past, 30.0, now=now)
+ self.assertAlmostEqual(score, 0.5, places=2)
+
+
+class DegreeDampenTests(unittest.TestCase):
+ def test_disabled(self):
+ self.assertEqual(degree_dampen(100, False), 1.0)
+
+ def test_hub_lower_than_rare(self):
+ self.assertLess(degree_dampen(100, True), degree_dampen(1, True))
+
+ def test_attr_idf_monotonic(self):
+ self.assertLess(attr_idf(50), attr_idf(2))
+
+
+class RecommendExcludeSeenTests(unittest.TestCase):
+ @patch("src.core.search.recommend.graph_adapter")
+ @patch("src.core.search.recommend.EntitySinergyRetriever")
+ def test_exclude_seen_keeps_collaborative_unseen(self, mock_syn_cls, mock_graph):
+ user = _node("user:u1", "u1", ["USER"])
+ peer = _node("user:u2", "u2", ["USER"])
+ shared = _node("item:a", "a", ["PRODUCT"])
+ fresh = _node("item:b", "b", ["PRODUCT"])
+ evt_u1 = _node("evt:1", "Purchase", ["EVENT"], happened_at="01/08/2026")
+ evt_u2_shared = _node("evt:2", "Purchase", ["EVENT"], happened_at="01/08/2026")
+ evt_u2_fresh = _node("evt:3", "Purchase", ["EVENT"], happened_at="01/08/2026")
+
+ mock_syn = MagicMock()
+ mock_syn.retrieve_sibilings.return_value = (user, [], [], [])
+ mock_syn_cls.return_value = mock_syn
+
+ def get_neighbors(uuids, of_types=None, brain_id="default"):
+ uid = uuids[0]
+ if uid == user.uuid:
+ return {user.uuid: [(_pred("MADE"), evt_u1)]}
+ if uid == evt_u1.uuid:
+ return {
+ evt_u1.uuid: [
+ (_pred("TARGETED"), shared),
+ (_pred("MADE"), user),
+ ]
+ }
+ if uid == shared.uuid:
+ return {
+ shared.uuid: [
+ (_pred("TARGETED"), evt_u1),
+ (_pred("TARGETED"), evt_u2_shared),
+ ]
+ }
+ if uid == evt_u2_shared.uuid:
+ return {
+ evt_u2_shared.uuid: [
+ (_pred("MADE"), peer),
+ (_pred("TARGETED"), shared),
+ ]
+ }
+ if uid == peer.uuid:
+ return {
+ peer.uuid: [
+ (_pred("MADE"), evt_u2_shared),
+ (_pred("MADE"), evt_u2_fresh),
+ ]
+ }
+ if uid == evt_u2_fresh.uuid:
+ return {
+ evt_u2_fresh.uuid: [
+ (_pred("MADE"), peer),
+ (_pred("TARGETED"), fresh),
+ ]
+ }
+ return {uid: []}
+
+ mock_graph.get_neighbors.side_effect = get_neighbors
+
+ retriever = EntityRecommendRetriever("demorecsys")
+ _, recs = retriever.recommend(
+ "u1",
+ include_asymmetric=True,
+ include_multi_interest=False,
+ include_attribute_pref=False,
+ exclude_seen=True,
+ diversify=False,
+ labels=["PRODUCT"],
+ top_k=10,
+ )
+ uuids = {r["node"].uuid for r in recs}
+ self.assertNotIn(shared.uuid, uuids)
+ self.assertIn(fresh.uuid, uuids)
+
+ @patch("src.core.search.recommend.graph_adapter")
+ @patch("src.core.search.recommend.EntitySinergyRetriever")
+ def test_behavior_weights_rank_purchase_above_view(
+ self, mock_syn_cls, mock_graph
+ ):
+ user = _node("user:u1", "u1", ["USER"])
+ p_view = _node("item:v", "v", ["PRODUCT"])
+ p_buy = _node("item:b", "b", ["PRODUCT"])
+ evt_view = _node("evt:v", "View", ["EVENT"], happened_at="01/08/2026")
+ evt_buy = _node("evt:b", "Purchase", ["EVENT"], happened_at="01/08/2026")
+
+ mock_syn = MagicMock()
+ mock_syn.retrieve_sibilings.return_value = (user, [], [], [])
+ mock_syn_cls.return_value = mock_syn
+
+ def get_neighbors(uuids, of_types=None, brain_id="default"):
+ uid = uuids[0]
+ if uid == user.uuid:
+ return {
+ user.uuid: [
+ (_pred("MADE"), evt_view),
+ (_pred("MADE"), evt_buy),
+ ]
+ }
+ if uid == evt_view.uuid:
+ return {evt_view.uuid: [(_pred("TARGETED"), p_view)]}
+ if uid == evt_buy.uuid:
+ return {evt_buy.uuid: [(_pred("TARGETED"), p_buy)]}
+ return {uid: []}
+
+ mock_graph.get_neighbors.side_effect = get_neighbors
+
+ retriever = EntityRecommendRetriever("demorecsys")
+ _, recs = retriever.recommend(
+ "u1",
+ include_asymmetric=True,
+ include_multi_interest=False,
+ include_attribute_pref=False,
+ exclude_seen=False,
+ diversify=False,
+ labels=["PRODUCT"],
+ top_k=10,
+ behavior_weights=DEFAULT_BEHAVIOR_WEIGHTS,
+ )
+ self.assertGreaterEqual(len(recs), 2)
+ by_uuid = {r["node"].uuid: r["score"] for r in recs}
+ self.assertGreater(by_uuid[p_buy.uuid], by_uuid[p_view.uuid])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_recsys_export_edges.py b/tests/test_recsys_export_edges.py
new file mode 100644
index 0000000..d7a8bf4
--- /dev/null
+++ b/tests/test_recsys_export_edges.py
@@ -0,0 +1,57 @@
+import unittest
+from types import SimpleNamespace
+
+from plugins_path_helper import load_export_edges
+
+
+class FakePage:
+ def __init__(self, results, total):
+ self.results = results
+ self.total = total
+
+
+class FakeGraph:
+ def __init__(self, users, hubs):
+ self.users = users
+ self.hubs = hubs
+
+ def search_entities(self, brain_id="default", limit=10, skip=0, node_labels=None, query_text=None):
+ assert node_labels == ["USER"]
+ chunk = self.users[skip : skip + limit]
+ return FakePage(chunk, len(self.users))
+
+ def get_event_centric_neighbors(self, nodes, brain_id="default"):
+ return self.hubs
+
+
+class ExportEdgesTests(unittest.TestCase):
+ def test_export_two_hubs(self):
+ export_edges = load_export_edges()
+ u1 = SimpleNamespace(uuid="user:u1", name="u1", labels=["USER"])
+ u2 = SimpleNamespace(uuid="user:u2", name="u2", labels=["USER"])
+ e1 = SimpleNamespace(uuid="evt:1", name="Purchase", labels=["EVENT"])
+ e2 = SimpleNamespace(uuid="evt:2", name="View", labels=["EVENT"])
+ p1 = SimpleNamespace(uuid="item:sku-1", name="sku-1", labels=["PRODUCT"])
+ p2 = SimpleNamespace(uuid="item:sku-2", name="sku-2", labels=["PRODUCT"])
+ pred = SimpleNamespace(name="MADE", uuid="r1")
+ pred2 = SimpleNamespace(name="TARGETED", uuid="r2")
+ hubs = [
+ (u1, pred, e1, pred2, p1),
+ (u2, pred, e2, pred2, p2),
+ ]
+ graph = FakeGraph([u1, u2], hubs)
+ edges = export_edges.export_user_item_edges(graph, "demorecsys")
+ self.assertEqual(len(edges), 2)
+ by_user = {e["user_id"]: e for e in edges}
+ self.assertEqual(by_user["u1"]["item_id"], "sku-1")
+ self.assertEqual(by_user["u1"]["weight"], 3.0)
+ self.assertEqual(by_user["u2"]["weight"], 1.0)
+
+ def test_refuse_forbidden_brain(self):
+ export_edges = load_export_edges()
+ with self.assertRaises(ValueError):
+ export_edges.export_user_item_edges(FakeGraph([], []), "beam1m1clean")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_recsys_lightgcn.py b/tests/test_recsys_lightgcn.py
new file mode 100644
index 0000000..ffffd6c
--- /dev/null
+++ b/tests/test_recsys_lightgcn.py
@@ -0,0 +1,54 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+
+class LightGCNTrainSmokeTests(unittest.TestCase):
+ def test_train_and_infer_toy_edges(self):
+ import sys
+
+ root = Path(__file__).resolve().parents[1]
+ plugin = root / "plugins" / "recsys-gnn"
+ if str(plugin) not in sys.path:
+ sys.path.insert(0, str(plugin))
+
+ from models.lightgcn import train_and_save
+ from models.artifacts import load_artifacts
+ from models.infer import rank_items
+
+ edges = []
+ for u in range(5):
+ for i in range(3):
+ edges.append(
+ {
+ "user_id": f"u{u}",
+ "item_id": f"sku-{i}",
+ "user_uuid": f"user:u{u}",
+ "item_uuid": f"item:sku-{i}",
+ "user_name": f"u{u}",
+ "item_name": f"sku-{i}",
+ "weight": 1.0,
+ }
+ )
+ with tempfile.TemporaryDirectory() as tmp:
+ meta = train_and_save(
+ edges,
+ brain_id="demorecsys",
+ epochs=3,
+ embedding_dim=8,
+ n_layers=2,
+ out_dir=Path(tmp),
+ )
+ self.assertEqual(meta["n_users"], 5)
+ self.assertEqual(meta["n_items"], 3)
+ arts = load_artifacts("demorecsys", base=Path(tmp))
+ self.assertIsNotNone(arts)
+ self.assertEqual(arts.user_emb.shape, (5, 8))
+ self.assertEqual(arts.item_emb.shape, (3, 8))
+ out = rank_items(arts, "u0", top_k=2, exclude_seen=False)
+ self.assertEqual(out["status"], "ok")
+ self.assertEqual(len(out["items"]), 2)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_recsys_movielens.py b/tests/test_recsys_movielens.py
new file mode 100644
index 0000000..30c3abd
--- /dev/null
+++ b/tests/test_recsys_movielens.py
@@ -0,0 +1,43 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+
+class MovieLensNormalizeTests(unittest.TestCase):
+ def test_filter_and_stats(self):
+ import sys
+
+ root = Path(__file__).resolve().parents[1]
+ bench = root / "benchmarks"
+ if str(bench) not in sys.path:
+ sys.path.insert(0, str(bench))
+
+ from recsys.dataset import dataset_stats, filter_interactions, write_jsonl
+ from recsys.evaluate import load_interactions
+
+ rows = []
+ for u in range(5):
+ for i in range(u + 2): # users 0..4 have 2..6 interactions
+ rows.append(
+ {
+ "user_id": f"mlu{u}",
+ "item_id": f"mlm{i}",
+ "behavior": "purchase",
+ "timestamp": f"2024-01-0{i+1}T00:00:00Z",
+ }
+ )
+ with tempfile.TemporaryDirectory() as tmp:
+ path = write_jsonl(rows, Path(tmp) / "x.jsonl")
+ loaded = load_interactions(path)
+ self.assertEqual(len(loaded), len(rows))
+ filtered = filter_interactions(
+ loaded, min_interactions=4, max_users=10
+ )
+ # users 2,3,4 have 4,5,6 ix
+ self.assertEqual(len({r["user_id"] for r in filtered}), 3)
+ stats = dataset_stats(filtered)
+ self.assertEqual(stats["n_users"], 3)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_structured_triple_persistence.py b/tests/test_structured_triple_persistence.py
index 3dc8bf5..16ba756 100644
--- a/tests/test_structured_triple_persistence.py
+++ b/tests/test_structured_triple_persistence.py
@@ -101,6 +101,7 @@ class StructuredTriplePersistenceTests(unittest.TestCase):
"data": [_full_triple()],
"brain_id": "tenant-a",
"text": None,
+ "mode": "deterministic",
}
with (
@@ -110,6 +111,7 @@ class StructuredTriplePersistenceTests(unittest.TestCase):
patch.object(ingestion_mod, "data_adapter") as data_adapter,
patch.object(ingestion_mod, "ScoutAgent") as ScoutAgent,
patch.object(ingestion_mod, "ArchitectAgent") as ArchitectAgent,
+ patch.object(ingestion_mod, "KGAgent") as KGAgent,
patch("celery.chain", _immediate_chain_factory(persist_calls)),
patch.object(ingestion_mod, "set_ingestion_task_status"),
patch.object(ingestion_mod, "finalize_ingestion_task"),
@@ -122,6 +124,9 @@ class StructuredTriplePersistenceTests(unittest.TestCase):
)
ScoutAgent.side_effect = lambda **kwargs: scout_called.append(True)
ArchitectAgent.side_effect = lambda **kwargs: architect_called.append(True)
+ KGAgent.side_effect = lambda **kwargs: (_ for _ in ()).throw(
+ AssertionError("KGAgent must not be constructed in deterministic mode")
+ )
result = ingestion_mod.ingest_structured_data.run.__func__(
type("Bound", (), {"request": request})(),
@@ -134,6 +139,9 @@ class StructuredTriplePersistenceTests(unittest.TestCase):
self.assertEqual(len(relationships), 2)
self.assertEqual(relationships[0]["name"], "MADE")
self.assertEqual(relationships[1]["name"], "TARGETED")
+ self.assertEqual(
+ relationships[0]["properties"].get("source"), "structured_deterministic"
+ )
self.assertEqual(persist_calls[0]["brain_id"], "tenant-a")
self.assertEqual(len(saved_structured), 1)
self.assertEqual(saved_structured[0]["brain_id"], "tenant-a")
@@ -141,6 +149,75 @@ class StructuredTriplePersistenceTests(unittest.TestCase):
self.assertEqual(scout_called, [])
self.assertEqual(architect_called, [])
+ def test_deterministic_ignores_text_for_llm(self):
+ from src.workers.tasks import ingestion as ingestion_mod
+
+ request = MagicMock()
+ request.id = "task-struct-det-text"
+ persist_calls = []
+ scout_called = []
+
+ args = {
+ "data": [_full_triple()],
+ "brain_id": "recsys-demo",
+ "text": "should not trigger scout",
+ "mode": "deterministic",
+ }
+
+ with (
+ patch.object(ingestion_mod, "cache_adapter"),
+ patch.object(ingestion_mod, "graph_adapter"),
+ patch.object(ingestion_mod, "IngestionManager"),
+ patch.object(ingestion_mod, "data_adapter"),
+ patch.object(ingestion_mod, "ScoutAgent") as ScoutAgent,
+ patch.object(ingestion_mod, "ArchitectAgent"),
+ patch.object(ingestion_mod, "KGAgent"),
+ patch("celery.chain", _immediate_chain_factory(persist_calls)),
+ patch.object(ingestion_mod, "set_ingestion_task_status"),
+ patch.object(ingestion_mod, "finalize_ingestion_task"),
+ ):
+ ScoutAgent.side_effect = lambda **kwargs: scout_called.append(True)
+ ingestion_mod.ingest_structured_data.run.__func__(
+ type("Bound", (), {"request": request})(),
+ args,
+ )
+
+ self.assertEqual(scout_called, [])
+ self.assertEqual(len(persist_calls), 1)
+
+ def test_deterministic_fails_closed_on_unresolved_name_anchor(self):
+ from src.workers.tasks import ingestion as ingestion_mod
+
+ request = MagicMock()
+ request.id = "task-struct-anchor-fail"
+ graph = MagicMock()
+ graph.get_by_identification_params.return_value = None
+
+ args = {
+ "data": [_full_triple()],
+ "brain_id": "recsys-demo",
+ "mode": "deterministic",
+ "anchor": {"name": "Alice", "type": "PERSON"},
+ }
+
+ with (
+ patch.object(ingestion_mod, "cache_adapter"),
+ patch.object(ingestion_mod, "graph_adapter", graph),
+ patch.object(ingestion_mod, "IngestionManager"),
+ patch.object(ingestion_mod, "data_adapter"),
+ patch.object(ingestion_mod, "KGAgent") as KGAgent,
+ patch.object(ingestion_mod, "set_ingestion_task_status"),
+ ):
+ KGAgent.side_effect = lambda **kwargs: (_ for _ in ()).throw(
+ AssertionError("KGAgent must not run in deterministic mode")
+ )
+ with self.assertRaises(ValueError) as ctx:
+ ingestion_mod.ingest_structured_data.run.__func__(
+ type("Bound", (), {"request": request})(),
+ args,
+ )
+ self.assertIn("deterministic mode", str(ctx.exception))
+
def test_text_enrichment_does_not_repersist_submitted_triples(self):
from src.core.agents.architect_agent import ArchitectAgentResponse
from src.core.agents.scout_agent import ScoutAgentResponse
@@ -155,6 +232,7 @@ class StructuredTriplePersistenceTests(unittest.TestCase):
"data": [_full_triple()],
"brain_id": "tenant-a",
"text": "Alice bought a widget",
+ "mode": "hybrid",
}
scout = MagicMock()
@@ -186,6 +264,32 @@ class StructuredTriplePersistenceTests(unittest.TestCase):
self.assertEqual(len(persist_calls), 1)
self.assertEqual(len(run_structured_kwargs), 1)
self.assertFalse(run_structured_kwargs[0]["persist_submitted"])
+ for rel in persist_calls[0]["relationships"]:
+ self.assertEqual(rel["properties"].get("source"), "structured_deterministic")
+
+ def test_resolved_mode_inference(self):
+ from src.services.api.constants.requests import (
+ IngestionStructuredRequestBody,
+ IngestionTripleSet,
+ )
+
+ triple = IngestionTripleSet(**_full_triple())
+ self.assertEqual(
+ IngestionStructuredRequestBody(data=[triple]).resolved_mode(),
+ "deterministic",
+ )
+ self.assertEqual(
+ IngestionStructuredRequestBody(
+ data=[triple], text="x"
+ ).resolved_mode(),
+ "hybrid",
+ )
+ self.assertEqual(
+ IngestionStructuredRequestBody(
+ data=[triple], text="x", mode="deterministic"
+ ).resolved_mode(),
+ "deterministic",
+ )
if __name__ == "__main__":
diff --git a/tests/test_synergy_metrics.py b/tests/test_synergy_metrics.py
new file mode 100644
index 0000000..430c42d
--- /dev/null
+++ b/tests/test_synergy_metrics.py
@@ -0,0 +1,74 @@
+import os
+import unittest
+
+ENV_DEFAULTS = {
+ "BRAINPAT_TOKEN": "test-token",
+ "MODELS_MODE": "local",
+ "EMBEDDINGS_LOCAL_MODEL": "local-model",
+ "EMBEDDINGS_SMALL_MODEL": "small-model",
+ "EMBEDDING_NODES_DIMENSION": "3",
+ "EMBEDDING_TRIPLETS_DIMENSION": "3",
+ "EMBEDDING_OBSERVATIONS_DIMENSION": "3",
+ "EMBEDDING_DATA_DIMENSION": "3",
+ "EMBEDDING_RELATIONSHIPS_DIMENSION": "3",
+ "REDIS_HOST": "localhost",
+ "REDIS_PORT": "6379",
+ "NEO4J_HOST": "localhost",
+ "NEO4J_PORT": "7687",
+ "NEO4J_USERNAME": "neo4j",
+ "NEO4J_PASSWORD": "password",
+ "MILVUS_HOST": "localhost",
+ "MILVUS_PORT": "19530",
+ "MONGO_CONNECTION_STRING": "mongodb://localhost:27017",
+ "CELERY_WORKER_CONCURRENCY": "1",
+ "OLLAMA_HOST": "localhost",
+ "OLLAMA_PORT": "11434",
+ "OLLAMA_LLM_SMALL_MODEL": "small",
+ "OLLAMA_LLM_LARGE_MODEL": "large",
+}
+for key, value in ENV_DEFAULTS.items():
+ os.environ.setdefault(key, value)
+
+
+class SynergyMetricsTests(unittest.TestCase):
+ def test_intra_list_diversity_and_coverage(self):
+ from src.core.search.synergy_metrics import (
+ intra_list_diversity,
+ popularity_stratum,
+ summarize_recommendation_list,
+ type_coverage,
+ unexpectedness_by_graph_distance,
+ )
+
+ labels = [["PRODUCT", "PHONE"], ["PRODUCT", "CASE"], ["CATEGORY"]]
+ self.assertGreater(intra_list_diversity(labels), 0.0)
+ self.assertEqual(type_coverage(labels), 4)
+ self.assertGreater(unexpectedness_by_graph_distance([1, 2, 4]), 0.0)
+ self.assertEqual(popularity_stratum(50), "head")
+ self.assertEqual(popularity_stratum(1), "tail")
+ summary = summarize_recommendation_list(labels, [1, 2, 3])
+ self.assertEqual(summary["n"], 3)
+ self.assertIn("intra_list_diversity", summary)
+
+
+class RecommendMmrTests(unittest.TestCase):
+ def test_mmr_prefers_type_diversity(self):
+ from src.constants.kg import Node
+ from src.core.search.recommend import _mmr_diversify
+
+ a = Node.model_construct(uuid="a", name="A", labels=["PHONE"], properties={})
+ b = Node.model_construct(uuid="b", name="B", labels=["PHONE"], properties={})
+ c = Node.model_construct(uuid="c", name="C", labels=["CASE"], properties={})
+ items = [
+ (a, 1.0, [], "synergy"),
+ (b, 0.99, [], "synergy"),
+ (c, 0.5, [], "synergy"),
+ ]
+ out = _mmr_diversify(items, top_k=2, lambda_mult=0.5)
+ self.assertEqual(len(out), 2)
+ self.assertEqual(out[0][0].uuid, "a")
+ self.assertEqual(out[1][0].uuid, "c")
+
+
+if __name__ == "__main__":
+ unittest.main()