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