TorbatYar/docs/reference/recommendation-contracts.md

Recommendation Engine Contracts (Rule-Based)

No AI. No implementation. Contracts for a future rule evaluator.
ADR: ADR-023
Contract version: recommendation.v1

---

1. Purpose

Produce recommendations for bundles, services, modules, features, and pricing from structured business inputs. Outputs never activate entitlements.

---

2. Input — RecommendationRequest

Field	Type	Meaning
business_type_code	string	From Business Type Catalog
company_size	enum	solo | small | medium | large | enterprise
employees	int?	Headcount hint
branches	int?	Location count
needs[]	string[]	Free-form need tags (open registry)
online_sales	bool
delivery	bool
appointments	bool
crm	bool
loyalty	bool
website	bool
locale	string?
ext	object	Additive

Need tag examples (open)

menu, pos, fleet, sms, accounting, membership, forms, b2b_pipeline

---

3. Output — RecommendationResult

Field	Type	Meaning
recommended_bundles[]	RankedRef	{ code, score, reason }
recommended_services[]	RankedRef	service_identifier
recommended_modules[]	RankedRef	module_key
recommended_features[]	RankedRef	feature_key
recommended_pricing[]	RankedRef	pricing_item_code
rule_trace[]	string[]	Which rules fired (debug)
version	string	recommendation.v1

---

4. Rule — RecommendationRule

Field	Type	Meaning
rule_id	string
priority	int	Higher evaluated first / stronger weight
active	bool
match	object	Predicates over RecommendationRequest
emit	object	What to add to result with score + reason
stop	bool	If true, halt further rules after match

Match predicates (documented operators)

Operator	Example
eq	business_type_code eq restaurant
gte	branches gte 2
in	company_size in [medium, large, enterprise]
flag_true	delivery == true
needs_contains	needs contains fleet

Example rules (illustrative)

rule_id	Match	Emit
r.restaurant.base	type=restaurant	bundle bundle.restaurant.starter score 100
r.delivery.need	delivery=true	service delivery score 80
r.crm.need	crm=true OR type=corporate_company	service crm score 80
r.website.need	website=true	service experience score 70
r.loyalty.need	loyalty=true	service loyalty score 70
r.multi.branch	branches≥3	prefer *.growth bundle variants score +20
r.enterprise.size	company_size=enterprise	pricing price.enterprise.custom score 90

---

5. Invariants

1. Rules MUST NOT call Payment, Accounting, or vertical write APIs.
2. Scores are relative; UI may sort but MUST present as recommendations.
3. No ML / LLM required or permitted by this contract version.