context detemrinistic + randomized searches and fix for setup from stella-ops.local rather 127.1.0.*
This commit is contained in:
master
@@ -0,0 +1,170 @@
|
||||
# Sprint 20260306-001 - Contextual Search Suggestions (Page + Last Action)
|
||||
|
||||
## Topic & Scope
|
||||
- Extend global search and AdvisoryAI suggestion behavior so prompts/chips are influenced by the current page and the user's latest meaningful action.
|
||||
- Activate existing backend ambient-context capabilities end-to-end by sending ambient payloads from the Web client.
|
||||
- Add deterministic, bounded context-aware refinement logic without breaking offline-first behavior.
|
||||
- Working directory: `src/Web/StellaOps.Web`.
|
||||
- Expected evidence: Angular unit tests, AdvisoryAI unit/integration tests, updated module docs, and sprint execution log artifacts.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Upstream contracts and code paths:
|
||||
- `src/Web/StellaOps.Web/src/app/layout/global-search/global-search.component.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
|
||||
- `src/Web/StellaOps.Web/src/app/core/api/unified-search.client.ts`
|
||||
- `src/AdvisoryAI/StellaOps.AdvisoryAI/UnifiedSearch/UnifiedSearchModels.cs`
|
||||
- `src/AdvisoryAI/StellaOps.AdvisoryAI/UnifiedSearch/Context/AmbientContextProcessor.cs`
|
||||
- `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Endpoints/UnifiedSearchEndpoints.cs`
|
||||
- Cross-module edits are explicitly allowed for this sprint in:
|
||||
- `src/AdvisoryAI/**`
|
||||
- `docs/modules/ui/**`
|
||||
- `docs/modules/advisory-ai/**`
|
||||
- Safe parallelism:
|
||||
- FE context-capture and FE rendering tasks can run in parallel with backend DTO expansion once ambient payload shape is frozen.
|
||||
- Backend ranking/refinement logic should start only after DTO contract freeze.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/ui/architecture.md`
|
||||
- `docs/modules/advisory-ai/unified-search-architecture.md`
|
||||
- `docs/modules/advisory-ai/knowledge-search.md`
|
||||
- `docs/modules/ui/implementation_plan.md`
|
||||
- `docs/modules/advisory-ai/implementation_plan.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### WEB-CTX-001 - Baseline behavior and gap mapping
|
||||
Status: DONE
|
||||
Dependency: none
|
||||
Owners: Project Manager, Developer (FE), Developer (AdvisoryAI)
|
||||
Task description:
|
||||
- Capture the current behavior matrix for search suggestions and chat-to-search handoff.
|
||||
- Document concrete gaps discovered in implementation: no ambient payload emitted by Web client, route-only suggestion chips, no "last action" signal, and route-prefix mismatches between FE and AdvisoryAI route-domain mappings.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Gap matrix is written in sprint notes with file references.
|
||||
- [x] Confirmed list of required contract changes is frozen before implementation tasks start.
|
||||
|
||||
### WEB-CTX-002 - FE ambient context capture (page + last action)
|
||||
Status: DONE
|
||||
Dependency: WEB-CTX-001
|
||||
Owners: Developer (FE)
|
||||
Task description:
|
||||
- Extend FE context services to track and expose:
|
||||
- current route
|
||||
- recent search terms
|
||||
- visible entity keys (bounded set)
|
||||
- session id for follow-up search continuity
|
||||
- last action metadata (surface, action type, domain/entity, timestamp, optional query seed)
|
||||
- Wire context capture from key UX surfaces: global search result actions, chat "Search for more", chat "Search related", and Ask AI handoff actions.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Ambient context provider exposes deterministic snapshot API used by search.
|
||||
- [x] Last action tracking is bounded by TTL and max-history limits.
|
||||
- [x] Unit tests cover action capture and decay/reset semantics.
|
||||
|
||||
### WEB-CTX-003 - FE -> AdvisoryAI contract activation for ambient payload
|
||||
Status: DONE
|
||||
Dependency: WEB-CTX-002
|
||||
Owners: Developer (FE), Developer (AdvisoryAI)
|
||||
Task description:
|
||||
- Extend `UnifiedSearchClient` request DTO and serialization to include `ambient` object.
|
||||
- Include route, session, visible entities, recent queries, and last action fields in `/v1/search/query` requests.
|
||||
- Preserve backward compatibility if backend field support is partially deployed.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Search requests include ambient payload when context is available.
|
||||
- [x] Existing search behavior remains functional when ambient payload is absent.
|
||||
- [x] FE tests assert payload shape sent to `/api/v1/search/query`.
|
||||
|
||||
### WEB-CTX-004 - AdvisoryAI ambient contract and processor extension
|
||||
Status: TODO
|
||||
Dependency: WEB-CTX-003
|
||||
Owners: Developer (AdvisoryAI)
|
||||
Task description:
|
||||
- Extend `AmbientContext`/API DTO contracts to support last action hints.
|
||||
- Normalize and validate new ambient fields in `UnifiedSearchEndpoints`.
|
||||
- Update `AmbientContextProcessor` and related flow in `UnifiedSearchService` to apply deterministic boosts/refinements from last action context.
|
||||
- Align route-domain mapping prefixes with current FE routing patterns.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Backend accepts and normalizes last-action ambient metadata.
|
||||
- [ ] Route mapping parity tests cover FE route prefixes currently in use.
|
||||
- [ ] Unit/integration tests verify context-aware boosts/refinements are deterministic.
|
||||
|
||||
### WEB-CTX-005 - Context-aware suggestion UX updates
|
||||
Status: DOING
|
||||
Dependency: WEB-CTX-004
|
||||
Owners: Developer (FE), UX
|
||||
Task description:
|
||||
- Update global search empty-state and sparse-result suggestion chips so they blend:
|
||||
- route-aware defaults
|
||||
- last-action-aware suggestions
|
||||
- backend refinements/suggestions when present
|
||||
- Ensure chat onboarding suggestions remain consistent with shared context rules.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Empty-state suggestion chips adapt to route + last action.
|
||||
- [ ] No-results and sparse-results views surface contextual refinements clearly.
|
||||
- [ ] Accessibility and keyboard navigation behavior remains intact.
|
||||
|
||||
### WEB-CTX-006 - Quality telemetry and guardrails
|
||||
Status: TODO
|
||||
Dependency: WEB-CTX-004
|
||||
Owners: Developer (FE), Developer (AdvisoryAI)
|
||||
Task description:
|
||||
- Add bounded telemetry markers to evaluate contextual suggestion usefulness without storing sensitive raw prompts beyond existing policy.
|
||||
- Ensure no unbounded growth in in-memory/session context stores.
|
||||
- Keep deterministic ordering and offline behavior guarantees.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Telemetry and logs distinguish contextual vs non-contextual suggestion paths.
|
||||
- [ ] Privacy posture for stored query/action metadata is documented and validated.
|
||||
- [ ] No new external dependencies introduced.
|
||||
|
||||
### WEB-CTX-007 - Docs sync and rollout plan
|
||||
Status: DOING
|
||||
Dependency: WEB-CTX-005
|
||||
Owners: Documentation author, Project Manager
|
||||
Task description:
|
||||
- Update module docs with final contract and behavior:
|
||||
- `docs/modules/ui/architecture.md`
|
||||
- `docs/modules/advisory-ai/unified-search-architecture.md`
|
||||
- `docs/modules/advisory-ai/knowledge-search.md`
|
||||
- Record rollout strategy (feature flag/canary, fallback behavior, success metrics) and decision log.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Docs reflect final API payload and UI behavior.
|
||||
- [ ] Sprint Decisions & Risks includes rollout gates and fallback plan.
|
||||
- [ ] Execution log captures implementation and verification evidence links.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-06 | Sprint created from code-and-doc investigation of global search and AdvisoryAI ambient context flow. | Project Manager |
|
||||
| 2026-03-06 | WEB-CTX-001 marked DONE after baseline gap mapping; WEB-CTX-002 started for FE context capture implementation. | Developer (FE) |
|
||||
| 2026-03-06 | Implemented FE route + last-action ambient capture, wired chat/search action capture, and emitted ambient payloads from global search requests. | Developer (FE) |
|
||||
| 2026-03-06 | Verified FE behavior via targeted unit tests: `ambient-context.service.spec.ts`, `global-search.component.spec.ts`, `chat-message.component.spec.ts` (23/23 passing). | Test Automation |
|
||||
| 2026-03-06 | Added Playwright E2E coverage for contextual suggestions and ambient payload propagation (`tests/e2e/unified-search-contextual-suggestions.e2e.spec.ts`): 3/3 passing. | Test Automation |
|
||||
| 2026-03-06 | Upgraded suggestion logic to include strategic non-obvious cross-domain prompts per page scope and action-aware variants after user interactions. | Developer (FE) |
|
||||
| 2026-03-06 | Added typed chip-context registry contract (`search-context.registry.ts`) and shifted suggestion selection to route-context arrays + bounded last-few-action prioritization + deterministic rotation. | Developer (FE) |
|
||||
| 2026-03-06 | Synced architecture docs for automatic page-open suggestions and ambient `lastAction` contract: `docs/modules/ui/architecture.md`, `docs/modules/advisory-ai/knowledge-search.md`, `docs/modules/advisory-ai/unified-search-architecture.md`. | Documentation author |
|
||||
| 2026-03-06 | Added UI governance rule for chip ownership and page-context interface in `docs/modules/ui/search-chip-context-contract.md`. | Documentation author |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision needed: whether route context should remain a hard domain filter in FE (`buildContextFilter`) or become a soft ranking hint only via ambient payload.
|
||||
- Decision needed: final schema for `lastAction` ambient metadata and retention policy in FE memory/session scope.
|
||||
- Decision: FE emits `ambient.lastAction` now as a forward-compatible field; current backend deployments may ignore it without regressing behavior.
|
||||
- Decision: chip definitions are now governed by typed context arrays (`SEARCH_CONTEXT_DEFINITIONS`) and an explicit page-level interface contract (`SearchContextComponent`) instead of ad-hoc route conditionals.
|
||||
- Docs updated: `docs/modules/ui/architecture.md`, `docs/modules/ui/search-chip-context-contract.md`, `docs/modules/advisory-ai/knowledge-search.md`, `docs/modules/advisory-ai/unified-search-architecture.md`.
|
||||
- Risk: stale action context may bias suggestions toward irrelevant domains.
|
||||
- Mitigation: TTL + bounded history + explicit reset on session boundaries.
|
||||
- Risk: route-prefix drift between FE and backend route-domain maps can silently reduce context quality.
|
||||
- Mitigation: shared route mapping tests and explicit parity checks.
|
||||
- Risk: privacy leakage if raw action labels/queries are persisted beyond current controls.
|
||||
- Mitigation: preserve hashed analytics and limit persisted raw content to existing approved history paths only.
|
||||
|
||||
## Next Checkpoints
|
||||
- 2026-03-08: Contract freeze for FE ambient payload and AdvisoryAI DTO updates.
|
||||
- 2026-03-10: FE context-capture + payload emission complete with unit tests.
|
||||
- 2026-03-12: AdvisoryAI processor/refinement updates complete with integration tests.
|
||||
- 2026-03-13: Docs sync and rollout readiness review.
|
||||
Reference in New Issue
Block a user