46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
# Search Chip Context Contract
|
|
|
|
## Purpose
|
|
- Define one deterministic contract for page-aware search chips.
|
|
- Let feature teams add page suggestions without editing `AmbientContextService` logic.
|
|
- Blend route context, last few page actions, and bounded suggestion randomization.
|
|
|
|
## Rule (mandatory for page teams)
|
|
- Every page that needs custom search chips must declare a context entry in `SEARCH_CONTEXT_DEFINITIONS`.
|
|
- Page components should implement `SearchContextComponent` with `searchContextId` so ownership is explicit.
|
|
- Context definitions must provide:
|
|
- `id`
|
|
- `routePrefixes`
|
|
- optional `domain`
|
|
- optional `searchSuggestions[]`
|
|
- optional `chatSuggestions[]`
|
|
- optional `chatRoutePattern`
|
|
- Suggestion arrays must stay deterministic and bounded:
|
|
- at most 3 base chips per page context
|
|
- short, action-oriented text
|
|
- no tenant/user secrets in fallback text
|
|
|
|
## Source of truth
|
|
- Contract and registry:
|
|
- `src/Web/StellaOps.Web/src/app/core/services/search-context.registry.ts`
|
|
- Runtime composition:
|
|
- `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
|
|
|
|
## Runtime behavior
|
|
- Base chips come from the page context array.
|
|
- A deterministic rotation (session + route scope + 5-minute bucket) varies chip order.
|
|
- Last few actions for the current page scope are tracked (bounded history, TTL 15 minutes).
|
|
- Up to 2 `follow up: ...` chips are generated from recent actions and prioritized above base chips.
|
|
- One strategic chip is generated from dominant/recent action intent.
|
|
|
|
## Page ownership workflow
|
|
1. Add/adjust a context in `SEARCH_CONTEXT_DEFINITIONS`.
|
|
2. Ensure page component exposes the same `searchContextId` (implements `SearchContextComponent`).
|
|
3. Add/adjust unit tests in `ambient-context.service.spec.ts`.
|
|
4. Add/adjust Playwright tests for route chips + action-driven chips.
|
|
|
|
## Non-goals
|
|
- No unbounded per-page suggestion memory.
|
|
- No runtime remote fetch for chip definitions.
|
|
- No randomization based on `Math.random()` (must remain replayable).
|