features-rec

Multi-behavior + product-attribute ingest for train-free RecSys on BrainAPI. This plugin writes interaction triples and USER -[:PREFERS]-> ATTR weights at write time. Ranking stays on core GET /retrieve/recommend?include_attribute_pref=true — there is no model to train.

Registry name	features-rec
Version	0.1.0
BrainAPI	>=2.14.0
Route prefix	/features-rec
Default brain	demorecsys
Extra pip deps	none

Use this when you want attribute-aware recommendations without LightGCN. For a trained CF baseline see recsys-gnn.

Install

git clone https://github.com/Lumen-Labs/brainapi-plugin-features-rec.git plugins/features-rec

Or:

./bin/brainapi install features-rec

Restart the API. Structured ingest still runs on the core Celery ingestion worker.

Quick start

curl -X POST "$BRAINAPI_URL/features-rec/interactions" \
  -H "Content-Type: application/json" \
  -H "BrainPAT: $BRAINPAT_TOKEN" \
  -d '{
    "user_id": "u1",
    "item_id": "sku-42",
    "behavior": "purchase",
    "timestamp": "2026-08-01T12:00:00Z",
    "attributes": {"color": "navy", "brand": "Acme", "category": "outerwear"},
    "brain_id": "demorecsys",
    "wait": true
  }'

Then rank (core API, not this plugin):

curl "$BRAINAPI_URL/retrieve/recommend?user_id=u1&include_attribute_pref=true" \
  -H "BrainPAT: $BRAINPAT_TOKEN" \
  -H "X-Brain-ID: demorecsys"

What it writes

Each POST /features-rec/interactions does two things:

1. Structured deterministic ingest — user MADE an event (View / AddToCart / Purchase / Favorite / Wishlist / …) TARGETED at a PRODUCT, plus HAS triples for catalog facets.
2. Preference upserts (after ingest completes) — USER -[:PREFERS]-> ATTR with accumulated weight, n, last_at, and optional exponential decay (preference_half_life_days, default 90).

Brain ids starting with beam1m or locomoconv are rejected. Use demorecsys or another dedicated *recsys* brain.

Request body

Field	Type	Default	Description
user_id	string	required	User id
item_id	string	required	Product / item id
behavior	string	required	See behavior table
timestamp	string	optional	Parsed to MM/DD/YYYY on the event node
attributes	object	optional	Facet map
category, brand, color, material	string	optional	Merged into attributes
brain_id	string	demorecsys	Target brain
wait	bool	true	Poll ingest until terminal status
timeout_s	float	120	Poll timeout
seq	int	1	Disambiguates event uuids
preference_half_life_days	float	90	Decay on existing PREFERS weights

Allowed attributes

Only these facets are written: color, material, category, brand, size, style. Node labels: COLOR, MATERIAL, CATEGORY, BRAND, or ATTR.

Behaviors and PREFERS increment

Behavior aliases	Event name	PREFERS increment
view, click, viewed, clicked	View	0.2
cart, add_to_cart, addtocart, …	AddToCart	0.5
favorite, wishlist, add_to_favorite, …	Favorite / Wishlist	0.7
purchase, buy, purchased, bought	Purchase	1.0
anything else	title-cased label	0.2

Response

{
  "status": "completed",
  "task_id": "…",
  "brain_id": "demorecsys",
  "n_triples": 4,
  "attributes": {"color": "navy", "brand": "Acme", "category": "outerwear"},
  "prefers": [
    {"user_id": "u1", "facet": "color", "value": "navy", "weight": 1.0, "n": 1}
  ],
  "task": { "status": "completed" }
}

prefers is only filled when ingest status is completed or partial_failed and attributes were supplied. Terminal statuses: completed, failed, partial_failed, timeout.

Ranking

This plugin does not expose a recommend route. Use core:

GET /retrieve/recommend?include_attribute_pref=true

Core graph walks + attribute preference weights are the product path (see BrainAPI recsys eval protocol). LightGCN is a separate, additive plugin.

Layout

features-rec/
  plugin.yaml
  main.py
  routes/interactions.py    # POST /features-rec/interactions
  models/mapping.py         # triples + PREFERS upsert

Publishing

Pushes to main publish to the BrainAPI registry via GitHub Actions.

License

Apache License, Version 2.0. See LICENSE.

Related

• recsys-gnn — optional LightGCN
• BrainAPI
• RecSys eval protocol in docs/research/16-recsys-eval-protocol.md on brainapi2