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.
|
||||
@@ -119,6 +119,10 @@ Implemented in `src/AdvisoryAI/StellaOps.AdvisoryAI/KnowledgeSearch/KnowledgeSea
|
||||
- Supported `filters.domains`: `knowledge`, `findings`, `vex`, `policy`, `platform`.
|
||||
- Supported `filters.entityTypes`: `docs`, `api`, `doctor`, `finding`, `vex_statement`, `policy_rule`, `platform_entity`.
|
||||
- Unsupported domain/entity filter values are rejected with HTTP 400; they are not silently broadened to an unfiltered query.
|
||||
- Web ambient contract:
|
||||
- Global search emits ambient context with each unified query: `currentRoute`, `visibleEntityKeys`, `recentSearches`, `sessionId`, and optional `lastAction` (`action`, `source`, `queryHint`, `domain`, `entityKey`, `route`, `occurredAt`).
|
||||
- Contract remains backward-compatible: if an API deployment does not yet consume `lastAction`, unknown ambient fields are ignored and base search behavior remains unchanged.
|
||||
- UI suggestion behavior now combines obvious route defaults with one strategic non-obvious suggestion and action-aware variants (for example, policy/VEX impact and incident timeline pivots).
|
||||
- Unified index lifecycle:
|
||||
- Manual rebuild endpoint: `POST /v1/search/index/rebuild`.
|
||||
- Optional background refresh loop is available via `KnowledgeSearchOptions` (`UnifiedAutoIndexEnabled`, `UnifiedAutoIndexOnStartup`, `UnifiedIndexRefreshIntervalSeconds`).
|
||||
|
||||
@@ -21,6 +21,7 @@ flowchart LR
|
||||
|
||||
### Layer 1: Query Understanding
|
||||
- Input: `UnifiedSearchRequest` (`q`, filters, ambient context, session id).
|
||||
- Ambient context envelope from Web clients includes route/session continuity fields and optional last-action metadata (`action`, `source`, `queryHint`, `domain`, `entityKey`, `route`, `occurredAt`) for follow-up ranking/refinement.
|
||||
- Components:
|
||||
- `EntityExtractor`
|
||||
- `IntentClassifier`
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
## Active Sprint Links
|
||||
- `docs/implplan/SPRINT_20260221_041_FE_prealpha_ia_ops_setup_rewire.md`
|
||||
- `docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md`
|
||||
|
||||
## Delivery Tasks
|
||||
- [DONE] 041-T1 Root IA/nav rewrite (Mission Control + Ops + Setup)
|
||||
@@ -16,3 +17,9 @@
|
||||
- [DONE] 041-T10 Integrations consolidation for advisory + VEX
|
||||
- [DONE] 041-T11 Docs sync for new pre-alpha IA
|
||||
- [DONE] 041-T12 Targeted tests and verification evidence
|
||||
- [DONE] WEB-CTX-002 FE ambient context capture (page + last action)
|
||||
- [DONE] WEB-CTX-003 FE -> AdvisoryAI ambient payload activation
|
||||
- [DOING] WEB-CTX-005 Context-aware suggestion UX updates
|
||||
- [DOING] WEB-CTX-007 Docs sync and rollout plan
|
||||
- [DONE] WEB-CTX-E2E Playwright coverage for contextual suggestions + ambient last-action payload
|
||||
- [DONE] WEB-CTX-NONOBVIOUS Strategic non-obvious suggestion recipes (cross-domain + action-aware)
|
||||
|
||||
@@ -193,7 +193,11 @@ Each feature folder builds as a **standalone route** (lazy loaded). All HTTP sha
|
||||
* **Assistant host**: `/security/triage` mounts `SecurityTriageChatHostComponent`, which consumes `openChat` intent deterministically and opens the chat drawer in the primary shell.
|
||||
* **Assistant -> search return**: assistant responses expose `Search for more` and `Search related` actions; these populate global search query/domain context and focus the search surface.
|
||||
* **Guided discovery empty state**: when global search is focused with an empty query, the panel renders an 8-domain guide (findings, VEX, policy, docs, API, health, operations, timeline), contextual suggestion chips, and quick actions (`Getting Started`, `Run Health Check`, `View Recent Scans`).
|
||||
* **Shared route-context suggestions**: `AmbientContextService` is the single source for route-aware suggestion sets used by both global search and AdvisoryAI chat onboarding prompts, ensuring consistent context shifts as navigation changes.
|
||||
* **Automatic page-open suggestions**: `AmbientContextService` tracks router navigation and updates global-search suggestion chips/placeholders automatically for every opened page without requiring manual refresh.
|
||||
* **Last-action follow-up suggestions**: the same service keeps a per-route scoped last action (search result open/action, Ask AI handoff, chat return actions) with deterministic TTL bounds; empty-state chips prepend a contextual `follow up: ...` suggestion when available.
|
||||
* **Strategic non-obvious suggestions**: each page scope injects at least one cross-domain guidance query (for example, findings -> policy/VEX impact, policy -> impacted findings, doctor -> release blockers) and switches to action-aware variants after meaningful user actions.
|
||||
* **Ambient payload activation**: each global search request sends ambient context (`currentRoute`, `visibleEntityKeys`, `recentSearches`, `sessionId`, optional `lastAction`) so AdvisoryAI can apply contextual ranking/refinement.
|
||||
* **Chip contract governance**: page-owned chip arrays and route mappings are defined by `docs/modules/ui/search-chip-context-contract.md` and implemented in `search-context.registry.ts`.
|
||||
* **Fallback transparency**: when unified search drops to legacy fallback, global search displays an explicit degraded banner and emits enter/exit telemetry markers for operator visibility.
|
||||
|
||||
---
|
||||
|
||||
45
docs/modules/ui/search-chip-context-contract.md
Normal file
45
docs/modules/ui/search-chip-context-contract.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user