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.
Python ai-agentsai-memoryknowledge-graphknowledge-managementknowledge-representationreccomendation-system
Add recommend and synergy retrieval with recsys benchmarks.
Christian1e4cf880c5de
diff --git a/README.md b/README.mdindex 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 -dcp deploy/env.heavy.example .envdocker compose -f deploy/docker-compose.heavy.yaml up -d```+Then ingest your first data point:```shdiff --git a/benchmarks/AGENTS.md b/benchmarks/AGENTS.mdindex 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*`.+### BEAMTypical 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.jsonindex 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.shnew file mode 100755index 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__.pynew file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 outdiff --git a/benchmarks/recsys/evaluate.py b/benchmarks/recsys/evaluate.pynew file mode 100644index 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.pynew file mode 100644index 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 splitsdiff --git a/benchmarks/recsys/report.py b/benchmarks/recsys/report.pynew file mode 100644index 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__.pynew file mode 100644index 0000000..e69de29diff --git a/benchmarks/synergies/report.py b/benchmarks/synergies/report.pynew file mode 100644index 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.tsxindex 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({<divclassName={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"}><divclassName={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.cssindex 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.tsxindex 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() {<Toolbararia-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"><NumberInputid="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><Buttontype="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() {) : (<GraphExplorerariaLabel="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.mdindex 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.mdindex 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 researchdiff --git a/docs/research/15-ecommerce-gnn-recsys-landscape.md b/docs/research/15-ecommerce-gnn-recsys-landscape.mdnew file mode 100644index 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.mdnew file mode 100644index 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.tomlindex 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.pyindex 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, Tupleimport numpy as npfrom src.adapters.interfaces.graph import PredicateWithFlowKey-from src.constants.kg import EntitySynergy, Node+from src.constants.kg import EntitySynergy, Node, Predicatefrom src.services.kg_agent.main import (embeddings_adapter,graph_adapter,@@ -22,21 +22,57 @@ from src.utils.vector_search import VectorSearchFacadefrom src.utils.similarity.numbers import wmean, wsimfrom src.utils.similarity.vectors import cosine_similarity-# Strengthen the similarity between target and neighbor nodes that are directly connectedDIRECT_MULTIPLIER = 1.30-# Lowers the similarity between target and neighbor nodes that connected by similar nodes but not directly connectedREMOTE_MULTIPLIER = 0.70-# Weight to strengthen the similarity by the more things in common between the neighbor and the targetFACTORS_INCREMENTAL_WEIGHT = 0.3-# Weight to strengthen the similarity by the comparison of the neighbor+target descriptionsNODE_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+ ):+ returnif 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, Noneneighbor_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]):+ continueif 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]):+ continueif 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_Kreturn (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.pynew file mode 100644index 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, recommendationsdiff --git a/src/core/search/synergy_metrics.py b/src/core/search/synergy_metrics.pynew file mode 100644index 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.pyindex 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, Unionfrom 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.pyindex 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, Optionalfrom starlette.responses import JSONResponsefrom 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 EntityRecommendRetrieverfrom src.services.data.main import data_adapterfrom src.services.input.agents import embeddings_adapterfrom 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.pyindex 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_idfrom 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.pyindex 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 = Nonetry: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 = Noneingestion_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 = propspersistence_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 = propspersistence_batches.extend(rel.model_dump(mode="json") for rel in enrichment)diff --git a/tests/plugins_path_helper.py b/tests/plugins_path_helper.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 ArchitectAgentResponsefrom 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.pynew file mode 100644index 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()