125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# Phase 21F - Story Intelligence Visualisation Snapshot
|
|
|
|
## Snapshot Architecture
|
|
|
|
Phase 21F adds a read-only real-data snapshot path for the existing Story Intelligence Experience prototype. The browser contract remains the existing `StoryIntelligenceExperiencePrototypeViewModel` shape so the renderer can display either simulation data or persisted Story Intelligence run data.
|
|
|
|
## Data Sources
|
|
|
|
The snapshot service reads:
|
|
|
|
- `StoryIntelligenceSavedRun`
|
|
- `StoryIntelligenceSavedSceneResult`
|
|
- parsed `SceneIntelligenceScene` JSON
|
|
- existing Illustration Library resolution through `IIllustrationLibraryService.ApplyApprovedIllustrationsAsync`
|
|
|
|
It deliberately does not expose source manuscript text, raw AI responses, prompts, or import write operations.
|
|
|
|
## DTO Contract
|
|
|
|
The model adds snapshot metadata:
|
|
|
|
- `mode`
|
|
- `runId`
|
|
- `runStatus`
|
|
- `changeToken`
|
|
- `generatedUtc`
|
|
- `isTerminal`
|
|
- `snapshotMessage`
|
|
- `availableRuns`
|
|
|
|
The renderer continues to consume `scenes`, `characters`, `location`, `assets`, `relationships`, `knowledgeThreads`, `observations`, `latestDiscoveries`, and `activityFeed`.
|
|
|
|
## Stable Visual IDs
|
|
|
|
Stable IDs are deterministic:
|
|
|
|
- scenes: `scene-result-{SceneResultID}`
|
|
- waiting scene: `run-{RunID}-waiting`
|
|
- characters: `character-result-{normalised-name}`
|
|
- locations: `location-result-{normalised-name}`
|
|
- assets: `asset-result-{normalised-name}`
|
|
- relationships: `relationship-result-{character-a}-{character-b}-{signal}`
|
|
- knowledge: `knowledge-result-{recipient}-{knowledge-item}` or `question-result-{question}`
|
|
- observations: `observation-result-{type}-{subject}-{predicate}`
|
|
|
|
Normalised names are lower-case, alphanumeric slug keys.
|
|
|
|
## Current Scene Selection
|
|
|
|
The current scene is the latest valid parsed scene at or below the run's completed-scene count. If no parsed scenes exist, the snapshot returns a waiting scene so the visual shell remains intact.
|
|
|
|
## Character Rules
|
|
|
|
The current scene maps parsed characters and point-of-view data. Explicit POV receives weight `100`. Mentioned-only characters are lower weight. No POV is invented if the parsed data does not provide one.
|
|
|
|
## Location Rules
|
|
|
|
The snapshot chooses one active location, preferring present, specific, high-confidence locations. If none exists, it returns a graceful "Location not yet identified" placeholder.
|
|
|
|
## Asset Rules
|
|
|
|
The snapshot returns up to five significant current-scene assets. Mentioned-only and clearly low-value/background assets are filtered.
|
|
|
|
## Relationship Rules
|
|
|
|
Relationships are limited to the current scene parsed relationships. They use deterministic IDs and confidence-derived weights. The renderer may suppress inline labels if there is no clean visual space.
|
|
|
|
## Knowledge Mapping
|
|
|
|
Questions raised and knowledge changes feed the Knowledge Threads panel. Parsed observations feed the Story Observations panel. Wording is concise and user-facing.
|
|
|
|
## Illustration Resolution
|
|
|
|
The snapshot assigns starter Illustration Library stable codes using simple non-manuscript heuristics and then reuses the existing Illustration Library resolver. It does not generate images.
|
|
|
|
## API Route
|
|
|
|
`GET /api/story-intelligence/runs/{runId}/visualisation-snapshot`
|
|
|
|
The endpoint is authenticated and returns only runs owned by the signed-in user in this phase.
|
|
|
|
## Development Route
|
|
|
|
- Simulation: `/Development/StoryIntelligenceExperience?mode=simulation`
|
|
- Real run: `/Development/StoryIntelligenceExperience?runId={runId}`
|
|
- Selector: `/Development/StoryIntelligenceExperience`
|
|
|
|
The selector is development/admin-only.
|
|
|
|
## Refresh Mechanism
|
|
|
|
Real mode uses restrained polling of the snapshot endpoint. It polls about every 7 seconds while visible, backs off while hidden, avoids overlapping requests, and stops once the run is terminal.
|
|
|
|
## Completion Behaviour
|
|
|
|
Completed and completed-with-warning runs show the final provisional snapshot and stop polling. Failed and cancelled runs show the available snapshot plus a clear status message.
|
|
|
|
## Performance Notes
|
|
|
|
The service parses scene result JSON once per snapshot request, limits central collections, does not load manuscript source text, and logs snapshot build duration.
|
|
|
|
## Tests
|
|
|
|
Added coverage for:
|
|
|
|
- simulation mode remaining available
|
|
- real snapshot contract metadata
|
|
- absence of raw manuscript text, raw AI responses, and prompts from the visualisation contract
|
|
|
|
Existing build and Story Intelligence/Illustration tests continue to run.
|
|
|
|
## Known Gaps
|
|
|
|
- Collaborator/project access beyond run ownership is not yet expanded for this development endpoint.
|
|
- Canonical uploaded entity images are not resolved ahead of Illustration Library images yet.
|
|
- The route is not linked from the production Story Intelligence progress workflow.
|
|
- Relationship/knowledge mapping uses current scene parsed data, not a durable replay history.
|
|
|
|
## Recommended Phase 21G Work
|
|
|
|
- Broaden access checks to full project collaborator semantics.
|
|
- Resolve canonical entity images before library fallbacks where canonical entity matches are available.
|
|
- Connect the real Story Intelligence workflow to this visualisation at the appropriate handoff point.
|
|
- Add a lightweight status-token endpoint if polling full snapshots becomes too heavy.
|