PlotDirector/PlotLine/Services/StoryMemoryServices.cs

514 lines
30 KiB
C#

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using PlotLine.Data;
using PlotLine.Models;
namespace PlotLine.Services;
public interface IStoryMemoryService
{
Task<StoryMemoryRebuildResult> RebuildImportSessionAsync(int importSessionId, int userId, StoryMemoryRebuildOptions options, CancellationToken cancellationToken = default);
Task ProcessSceneResultAsync(int importSessionId, int userId, int sceneResultId, StoryMemoryResolveOptions options, CancellationToken cancellationToken = default);
Task ResolveIllustrationsAsync(int importSessionId, StoryMemoryResolveOptions options, CancellationToken cancellationToken = default);
}
public sealed class StoryMemoryService(
IStoryIntelligenceResultRepository results,
IStoryIntelligencePipelineRepository pipelines,
IStoryMemoryRepository memory,
IIllustrationLibraryRepository illustrationLibrary,
IUploadStorageService uploadStorage,
ILogger<StoryMemoryService> logger) : IStoryMemoryService
{
private const string ProcessorVersion = "21S";
private static readonly JsonSerializerOptions JsonOptions = new()
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
PropertyNameCaseInsensitive = true,
WriteIndented = false
};
public async Task<StoryMemoryRebuildResult> RebuildImportSessionAsync(int importSessionId, int userId, StoryMemoryRebuildOptions options, CancellationToken cancellationToken = default)
{
var session = await pipelines.GetByIdForUserAsync(importSessionId, userId)
?? throw new InvalidOperationException($"Import Session {importSessionId} could not be found for this user.");
var runScenes = await LoadImportScenesAsync(session, cancellationToken);
var completedScenes = runScenes.Where(item => item.Scene is not null).ToList();
if (options.DryRun)
{
return new StoryMemoryRebuildResult
{
ImportSessionID = importSessionId,
DryRun = true,
SceneResultsRead = runScenes.Count,
SceneResultsProcessed = completedScenes.Count,
CharactersDiscovered = completedScenes.Sum(item => item.Scene!.Characters?.Count ?? 0),
LocationsDiscovered = completedScenes.Sum(item => (item.Scene!.Locations?.Count ?? 0) + (string.IsNullOrWhiteSpace(item.Scene.Setting?.LocationName) ? 0 : 1)),
AssetsDiscovered = completedScenes.Sum(item => item.Scene!.Assets?.Count ?? 0),
RelationshipsDiscovered = completedScenes.Sum(item => item.Scene!.Relationships?.Count ?? 0),
AiCalls = 0,
Warnings = runScenes.Where(item => item.Scene is null && !string.IsNullOrWhiteSpace(item.ParseError)).Select(item => item.ParseError!).Take(20).ToList()
};
}
if (options.RebuildAll)
{
await memory.ClearDerivedStateAsync(importSessionId);
}
await memory.SetAppearancePreferenceAsync(importSessionId, options.AppearancePreference);
var processed = await memory.ListProcessedSceneResultIdsAsync(importSessionId, ProcessorVersion);
var processedCount = 0;
foreach (var scene in completedScenes)
{
cancellationToken.ThrowIfCancellationRequested();
if (!options.RebuildAll && processed.Contains(scene.Result.SceneResultID))
{
continue;
}
await UpsertSceneMemoryAsync(session, scene.Result, scene.Scene!, cancellationToken);
await memory.MarkSceneResultProcessedAsync(importSessionId, scene.Result.SceneResultID, ProcessorVersion, StableContentHash(scene.Result.ParsedJson));
processedCount++;
}
await ResolveIllustrationsAsync(importSessionId, new StoryMemoryResolveOptions
{
QueueDemand = options.QueueDemand,
MaxDemandToQueue = options.MaxDemandToQueue,
AppearancePreference = options.AppearancePreference
}, cancellationToken);
var diagnostics = await memory.GetDiagnosticsAsync(importSessionId);
return new StoryMemoryRebuildResult
{
ImportSessionID = importSessionId,
DryRun = false,
SceneResultsRead = runScenes.Count,
SceneResultsProcessed = processedCount,
CharactersDiscovered = diagnostics.CharacterCount,
LocationsDiscovered = diagnostics.LocationCount,
AssetsDiscovered = diagnostics.AssetCount,
RelationshipsDiscovered = diagnostics.RelationshipCount,
AssignmentsCreatedOrValidated = diagnostics.AssignmentCount,
DemandsCreated = diagnostics.DemandCount,
FallbacksRemaining = diagnostics.FallbackCount,
AiCalls = 0
};
}
public async Task ProcessSceneResultAsync(int importSessionId, int userId, int sceneResultId, StoryMemoryResolveOptions options, CancellationToken cancellationToken = default)
{
var session = await pipelines.GetByIdForUserAsync(importSessionId, userId);
if (session is null)
{
logger.LogWarning("Story Memory skipped scene result {SceneResultId}: import session {ImportSessionId} was not visible to user {UserId}.", sceneResultId, importSessionId, userId);
return;
}
var scene = (await LoadImportScenesAsync(session, cancellationToken)).FirstOrDefault(item => item.Result.SceneResultID == sceneResultId);
if (scene is null || scene.Scene is null)
{
return;
}
await UpsertSceneMemoryAsync(session, scene.Result, scene.Scene, cancellationToken);
await memory.MarkSceneResultProcessedAsync(importSessionId, sceneResultId, ProcessorVersion, StableContentHash(scene.Result.ParsedJson));
await ResolveIllustrationsAsync(importSessionId, options, cancellationToken);
}
public async Task ResolveIllustrationsAsync(int importSessionId, StoryMemoryResolveOptions options, CancellationToken cancellationToken = default)
{
var characters = await memory.ListCharactersAsync(importSessionId);
var attributes = await memory.ListCharacterAttributesAsync(importSessionId);
var locations = await memory.ListLocationsAsync(importSessionId);
var assets = await memory.ListAssetsAsync(importSessionId);
var assignments = await memory.ListAssignmentsAsync(importSessionId);
var catalogue = (await illustrationLibrary.ListAsync(new IllustrationLibraryFilter()))
.Where(item => item.Status is IllustrationLibraryStatuses.Approved or IllustrationLibraryStatuses.Generated)
.Where(item => ResolveUploadUrl(item) is not null)
.ToList();
var usedItemIds = assignments
.Where(item => item.IllustrationLibraryItemID.HasValue)
.Select(item => item.IllustrationLibraryItemID!.Value)
.ToHashSet();
foreach (var character in characters.Where(item => item.EntityContext == "Story" && !item.IsGroupEntity))
{
cancellationToken.ThrowIfCancellationRequested();
var evidence = CharacterEvidence(character, attributes.Where(item => item.StoryMemoryCharacterID == character.StoryMemoryCharacterID));
var existing = assignments.FirstOrDefault(item => item.EntityType == StoryMemoryEntityTypes.Character && item.EntityID == character.StoryMemoryCharacterID);
var existingItem = existing?.IllustrationLibraryItemID is int existingId
? catalogue.FirstOrDefault(item => item.IllustrationLibraryItemID == existingId)
: null;
var existingValid = existingItem is not null && StoryIntelligenceIllustrationCompatibility
.CharacterHardRejections(evidence, StoryIntelligenceIllustrationCompatibility.CharacterMetadataFrom(existingItem), character.IsNamed, false)
.Count == 0;
var candidates = catalogue
.Where(item => item.Category == IllustrationLibraryCategories.Character)
.Select(item => ScoreCharacter(item, evidence, character.IsNamed, usedItemIds.Contains(item.IllustrationLibraryItemID) && item.IllustrationLibraryItemID != existing?.IllustrationLibraryItemID))
.Where(item => item.IsCompatible)
.OrderByDescending(item => item.Score)
.ThenBy(item => item.Item!.StableCode)
.ToList();
var chosen = candidates.FirstOrDefault();
if (chosen.Item is not null)
{
usedItemIds.Add(chosen.Item.IllustrationLibraryItemID);
await memory.UpsertAssignmentAsync(new StoryMemoryIllustrationAssignmentSave(
importSessionId,
StoryMemoryEntityTypes.Character,
character.StoryMemoryCharacterID,
chosen.Item.IllustrationLibraryItemID,
chosen.Item.StableCode,
"Assigned",
false,
chosen.Score,
Math.Min(0.99m, chosen.Score / 200m),
existingValid && existingItem?.IllustrationLibraryItemID == chosen.Item.IllustrationLibraryItemID
? $"Retained {chosen.Item.StableCode}; durable evidence passed hard revalidation."
: $"Assigned {chosen.Item.StableCode}; durable Story Memory was resolved against hard character constraints.",
ProcessorVersion));
continue;
}
await RecordDemandAsync(importSessionId, character.ProjectID, StoryMemoryEntityTypes.Character, DemandKey(character.CanonicalIdentityKey, evidence.AgeBand, evidence.Presentation), cancellationToken);
await memory.UpsertAssignmentAsync(new StoryMemoryIllustrationAssignmentSave(importSessionId, StoryMemoryEntityTypes.Character, character.StoryMemoryCharacterID, null, null, "DemandRecorded", true, 0, 0, "No compatible character illustration exists; durable demand recorded.", ProcessorVersion));
}
foreach (var location in locations)
{
cancellationToken.ThrowIfCancellationRequested();
var requestedType = StoryIntelligenceIllustrationCompatibility.LocationType($"{location.DisplayName} {location.SemanticType} {location.Subtype}");
var chosen = catalogue
.Where(item => item.Category == IllustrationLibraryCategories.Location)
.Select(item => (Item: item, Type: StoryIntelligenceIllustrationCompatibility.LocationType($"{item.StableCode} {item.DisplayTitle} {item.ShortDescription} {item.MetadataJson} {item.SpecificationJson}")))
.Where(item => StoryIntelligenceIllustrationCompatibility.LocationCompatible(requestedType, item.Type))
.OrderByDescending(item => string.Equals(item.Type, requestedType, StringComparison.OrdinalIgnoreCase) ? 100 : 50)
.ThenBy(item => item.Item.StableCode)
.FirstOrDefault();
if (chosen.Item is not null)
{
await memory.UpsertAssignmentAsync(new StoryMemoryIllustrationAssignmentSave(importSessionId, StoryMemoryEntityTypes.Location, location.StoryMemoryLocationID, chosen.Item.IllustrationLibraryItemID, chosen.Item.StableCode, "Assigned", false, 100, 0.9m, $"Assigned {chosen.Item.StableCode}; location type {requestedType} matched {chosen.Type}.", ProcessorVersion));
}
else
{
await RecordDemandAsync(importSessionId, location.ProjectID, StoryMemoryEntityTypes.Location, DemandKey(location.CanonicalIdentityKey, requestedType), cancellationToken);
await memory.UpsertAssignmentAsync(new StoryMemoryIllustrationAssignmentSave(importSessionId, StoryMemoryEntityTypes.Location, location.StoryMemoryLocationID, null, null, "DemandRecorded", true, 0, 0, $"No compatible {requestedType} location illustration exists; demand recorded.", ProcessorVersion));
}
}
foreach (var asset in assets)
{
cancellationToken.ThrowIfCancellationRequested();
var requestedType = StoryIntelligenceIllustrationCompatibility.AssetType($"{asset.DisplayName} {asset.SemanticType} {asset.Subtype}");
var requestedColour = StoryIntelligenceIllustrationCompatibility.AssetColour($"{asset.DisplayName} {asset.Colour}");
var chosen = catalogue
.Where(item => item.Category == IllustrationLibraryCategories.Asset)
.Select(item => (Item: item, Type: StoryIntelligenceIllustrationCompatibility.AssetType($"{item.StableCode} {item.DisplayTitle} {item.ShortDescription} {item.MetadataJson} {item.SpecificationJson}"), Colour: StoryIntelligenceIllustrationCompatibility.AssetColour($"{item.StableCode} {item.DisplayTitle} {item.ShortDescription} {item.MetadataJson} {item.SpecificationJson}")))
.Where(item => StoryIntelligenceIllustrationCompatibility.AssetCompatible(requestedType, item.Type))
.Where(item => requestedColour == "Unknown" || item.Colour == "Unknown" || string.Equals(requestedColour, item.Colour, StringComparison.OrdinalIgnoreCase))
.OrderByDescending(item => string.Equals(item.Type, requestedType, StringComparison.OrdinalIgnoreCase) ? 100 : 50)
.ThenByDescending(item => string.Equals(item.Colour, requestedColour, StringComparison.OrdinalIgnoreCase) ? 10 : 0)
.ThenBy(item => item.Item.StableCode)
.FirstOrDefault();
if (chosen.Item is not null)
{
await memory.UpsertAssignmentAsync(new StoryMemoryIllustrationAssignmentSave(importSessionId, StoryMemoryEntityTypes.Asset, asset.StoryMemoryAssetID, chosen.Item.IllustrationLibraryItemID, chosen.Item.StableCode, "Assigned", false, 100, 0.9m, $"Assigned {chosen.Item.StableCode}; asset type {requestedType} matched {chosen.Type}.", ProcessorVersion));
}
else
{
await RecordDemandAsync(importSessionId, asset.ProjectID, StoryMemoryEntityTypes.Asset, DemandKey(asset.CanonicalIdentityKey, requestedType, requestedColour), cancellationToken);
await memory.UpsertAssignmentAsync(new StoryMemoryIllustrationAssignmentSave(importSessionId, StoryMemoryEntityTypes.Asset, asset.StoryMemoryAssetID, null, null, "DemandRecorded", true, 0, 0, $"No compatible {requestedType} asset illustration exists; demand recorded.", ProcessorVersion));
}
}
}
private async Task UpsertSceneMemoryAsync(StoryIntelligenceBookPipelineState session, StoryIntelligenceSavedSceneResult result, SceneIntelligenceScene scene, CancellationToken cancellationToken)
{
var context = SourceSectionType(result, scene);
var sourceSectionType = context == "Story" ? "Story" : "Authorial";
foreach (var sceneCharacter in scene.Characters ?? [])
{
cancellationToken.ThrowIfCancellationRequested();
if (string.IsNullOrWhiteSpace(sceneCharacter.Name))
{
continue;
}
var key = CharacterKey(sceneCharacter.Name);
var isGroup = StoryIntelligenceIllustrationCompatibility.IsGroupEntity(sceneCharacter.Name);
var character = await memory.UpsertCharacterAsync(new StoryMemoryCharacterSave(
session.StoryIntelligenceBookPipelineID,
session.ProjectID,
session.BookID,
key,
sceneCharacter.Name.Trim(),
context,
sourceSectionType,
IsNamedCharacter(sceneCharacter.Name),
isGroup,
true,
string.Equals(scene.PointOfView?.CharacterName, sceneCharacter.Name, StringComparison.OrdinalIgnoreCase),
string.Equals(scene.PointOfView?.CharacterName, sceneCharacter.Name, StringComparison.OrdinalIgnoreCase),
CharacterSignificance(sceneCharacter),
result.SceneResultID));
await memory.AddCharacterAliasAsync(character.StoryMemoryCharacterID, sceneCharacter.Name.Trim(), Normalise(sceneCharacter.Name), "Scene character name", result.SceneResultID, sceneCharacter.Confidence ?? 0.8m);
foreach (var alias in sceneCharacter.Aliases ?? [])
{
await memory.AddCharacterAliasAsync(character.StoryMemoryCharacterID, alias, Normalise(alias), "Scene character alias", result.SceneResultID, sceneCharacter.Confidence ?? 0.7m);
}
var identityEvidence = new[] { sceneCharacter.Name, sceneCharacter.RoleInScene, sceneCharacter.Notes }
.Concat(sceneCharacter.Actions ?? [])
.Where(value => !string.IsNullOrWhiteSpace(value))
.Select(value => value!);
var relationshipEvidence = (scene.Relationships ?? [])
.Where(item => string.Equals(item.CharacterA, sceneCharacter.Name, StringComparison.OrdinalIgnoreCase) || string.Equals(item.CharacterB, sceneCharacter.Name, StringComparison.OrdinalIgnoreCase))
.Select(item => $"{item.RelationshipSignal} {item.Evidence}");
var inferred = StoryIntelligenceIllustrationCompatibility.InferCharacterEvidence(sceneCharacter.Name, identityEvidence, relationshipEvidence);
await AddKnownAttributeAsync(character.StoryMemoryCharacterID, "AgeBand", inferred.AgeBand, inferred.AgeConfidence, false, "Deterministic evidence inference", result.SceneResultID);
await AddKnownAttributeAsync(character.StoryMemoryCharacterID, "Presentation", inferred.Presentation, inferred.PresentationConfidence, inferred.PresentationConfidence >= 0.8m, "Deterministic evidence inference", result.SceneResultID);
await AddKnownAttributeAsync(character.StoryMemoryCharacterID, "HairColour", inferred.HairColour, 0.7m, false, "Deterministic evidence inference", result.SceneResultID);
await AddKnownAttributeAsync(character.StoryMemoryCharacterID, "SkinTone", inferred.SkinTone, 0.7m, false, "Deterministic evidence inference", result.SceneResultID);
await AddKnownAttributeAsync(character.StoryMemoryCharacterID, "HairLength", inferred.HairLength, 0.6m, false, "Deterministic evidence inference", result.SceneResultID);
}
if (!string.IsNullOrWhiteSpace(scene.Setting?.LocationName))
{
await UpsertLocationAsync(session, result, context, sourceSectionType, scene.Setting.LocationName, scene.Setting.LocationType, scene.Setting.GenericRoomType, scene.Setting.ParentLocationHint, scene.Setting.Confidence);
}
foreach (var location in scene.Locations ?? [])
{
if (!string.IsNullOrWhiteSpace(location.Name))
{
await UpsertLocationAsync(session, result, context, sourceSectionType, location.Name, location.LocationType, location.GenericRoomType, location.ParentLocationHint, location.Confidence);
}
}
foreach (var asset in scene.Assets ?? [])
{
if (string.IsNullOrWhiteSpace(asset.Name))
{
continue;
}
var semantic = StoryIntelligenceIllustrationCompatibility.AssetType($"{asset.Name} {asset.AssetType} {asset.Notes}");
await memory.UpsertAssetAsync(new StoryMemoryAssetSave(
session.StoryIntelligenceBookPipelineID,
session.ProjectID,
session.BookID,
AssetKey(asset.Name),
asset.Name.Trim(),
semantic,
asset.AssetType,
StoryIntelligenceIllustrationCompatibility.AssetColour($"{asset.Name} {asset.Notes}"),
null,
result.SceneResultID));
}
foreach (var relationship in scene.Relationships ?? [])
{
if (string.IsNullOrWhiteSpace(relationship.CharacterA) || string.IsNullOrWhiteSpace(relationship.CharacterB))
{
continue;
}
var source = await memory.UpsertCharacterAsync(new StoryMemoryCharacterSave(session.StoryIntelligenceBookPipelineID, session.ProjectID, session.BookID, CharacterKey(relationship.CharacterA), relationship.CharacterA.Trim(), context, sourceSectionType, IsNamedCharacter(relationship.CharacterA), StoryIntelligenceIllustrationCompatibility.IsGroupEntity(relationship.CharacterA), true, false, false, 40, result.SceneResultID));
var target = await memory.UpsertCharacterAsync(new StoryMemoryCharacterSave(session.StoryIntelligenceBookPipelineID, session.ProjectID, session.BookID, CharacterKey(relationship.CharacterB), relationship.CharacterB.Trim(), context, sourceSectionType, IsNamedCharacter(relationship.CharacterB), StoryIntelligenceIllustrationCompatibility.IsGroupEntity(relationship.CharacterB), true, false, false, 40, result.SceneResultID));
await memory.UpsertRelationshipAsync(session.StoryIntelligenceBookPipelineID, StoryMemoryEntityTypes.Character, source.StoryMemoryCharacterID, StoryMemoryEntityTypes.Character, target.StoryMemoryCharacterID, relationship.RelationshipSignal ?? "related", relationship.Confidence ?? 0.6m, !string.IsNullOrWhiteSpace(relationship.Evidence), result.SceneResultID);
}
}
private async Task UpsertLocationAsync(StoryIntelligenceBookPipelineState session, StoryIntelligenceSavedSceneResult result, string context, string sourceSectionType, string name, string? locationType, string? genericRoomType, string? parent, decimal? confidence)
{
var semantic = StoryIntelligenceIllustrationCompatibility.LocationType($"{name} {locationType} {genericRoomType}");
await memory.UpsertLocationAsync(new StoryMemoryLocationSave(session.StoryIntelligenceBookPipelineID, session.ProjectID, session.BookID, LocationKey(name), name.Trim(), semantic, genericRoomType ?? locationType, InferInteriorExterior(semantic), result.SceneResultID));
}
private async Task AddKnownAttributeAsync(int characterId, string attributeType, string value, decimal confidence, bool isExplicit, string evidence, int sceneResultId)
{
if (string.IsNullOrWhiteSpace(value) || string.Equals(value, "Unknown", StringComparison.OrdinalIgnoreCase))
{
return;
}
await memory.AddCharacterAttributeAsync(characterId, attributeType, value, confidence <= 0 ? 0.6m : confidence, isExplicit, evidence, sceneResultId);
}
private async Task<IReadOnlyList<SceneResultWithParse>> LoadImportScenesAsync(StoryIntelligenceBookPipelineState session, CancellationToken cancellationToken)
{
var runs = (await results.ListRunsAsync())
.Where(run => run.ProjectID == session.ProjectID && run.BookID == session.BookID)
.Select(run => new StoryIntelligenceSavedRun
{
StoryIntelligenceRunID = run.StoryIntelligenceRunID,
UserID = run.UserID,
ProjectID = run.ProjectID,
ProjectTitle = run.ProjectTitle,
BookID = run.BookID,
BookTitle = run.BookTitle,
ChapterID = run.ChapterID,
ChapterNumber = run.ChapterNumber,
Status = run.Status,
SourceType = run.SourceType,
CreatedUtc = run.CreatedUtc,
UpdatedUtc = run.CreatedUtc
})
.ToList();
var items = new List<SceneResultWithParse>();
foreach (var run in runs.OrderBy(item => item.ChapterNumber ?? decimal.MaxValue).ThenBy(item => item.StoryIntelligenceRunID))
{
cancellationToken.ThrowIfCancellationRequested();
var sceneResults = await results.ListSceneResultsAsync(run.StoryIntelligenceRunID);
items.AddRange(sceneResults.Select(item => new SceneResultWithParse(run, item, TryReadScene(item, out var error), error)));
}
return items
.OrderBy(item => item.Run.ChapterNumber ?? decimal.MaxValue)
.ThenBy(item => item.Result.TemporarySceneNumber)
.ThenBy(item => item.Result.SceneResultID)
.ToList();
}
private static SceneIntelligenceScene? TryReadScene(StoryIntelligenceSavedSceneResult result, out string? safeError)
{
safeError = null;
try
{
if (!string.IsNullOrWhiteSpace(result.ParsedJson))
{
var parsed = JsonSerializer.Deserialize<SceneIntelligenceScene>(result.ParsedJson, JsonOptions);
if (parsed?.SceneReference is not null || parsed?.Summary is not null || parsed?.Characters is not null)
{
return parsed;
}
using var document = JsonDocument.Parse(result.ParsedJson);
if (document.RootElement.TryGetProperty("parsedScene", out var parsedScene))
{
return parsedScene.Deserialize<SceneIntelligenceScene>(JsonOptions);
}
}
if (!string.IsNullOrWhiteSpace(result.OutputTextJson))
{
return JsonSerializer.Deserialize<SceneIntelligenceScene>(result.OutputTextJson, JsonOptions);
}
}
catch (JsonException ex)
{
safeError = $"SceneResultID {result.SceneResultID} could not be parsed: {ex.Message}";
}
return null;
}
private CharacterEvidenceProfile CharacterEvidence(StoryMemoryCharacter character, IEnumerable<StoryMemoryCharacterAttribute> attributes)
{
var values = attributes.Select(item => $"{item.AttributeType} {item.NormalisedValue}").ToList();
return StoryIntelligenceIllustrationCompatibility.InferCharacterEvidence(character.DisplayName, values, []);
}
private (IllustrationLibraryItem? Item, int Score, bool IsCompatible) ScoreCharacter(IllustrationLibraryItem item, CharacterEvidenceProfile evidence, bool isNamed, bool alreadyUsed)
{
var metadata = StoryIntelligenceIllustrationCompatibility.CharacterMetadataFrom(item);
var rejections = StoryIntelligenceIllustrationCompatibility.CharacterHardRejections(evidence, metadata, isNamed, alreadyUsed);
if (rejections.Count > 0)
{
return (item, 0, false);
}
var score = 25;
if (string.Equals(evidence.AgeBand, metadata.AgeBand, StringComparison.OrdinalIgnoreCase)) score += 50;
if (string.Equals(evidence.Presentation, metadata.Presentation, StringComparison.OrdinalIgnoreCase)) score += 100;
if (string.Equals(evidence.HairColour, metadata.HairColour, StringComparison.OrdinalIgnoreCase)) score += 20;
if (string.Equals(evidence.SkinTone, metadata.SkinTone, StringComparison.OrdinalIgnoreCase)) score += 10;
if (item.Status == IllustrationLibraryStatuses.Approved) score += 10;
return (item, score, true);
}
private string? ResolveUploadUrl(IllustrationLibraryItem item)
=> ResolveExistingPublicUploadUrl(item.ThumbnailPath) ?? ResolveExistingPublicUploadUrl(item.FilePath);
private string? ResolveExistingPublicUploadUrl(string? storedPath)
{
var physicalPath = uploadStorage.TryResolvePublicPath(storedPath, "uploads/story-intelligence-library");
return physicalPath is not null && File.Exists(physicalPath) ? storedPath : null;
}
private async Task RecordDemandAsync(int importSessionId, int projectId, string entityType, string archetypeKey, CancellationToken cancellationToken)
{
cancellationToken.ThrowIfCancellationRequested();
await memory.UpsertDemandAsync(new StoryMemoryIllustrationDemandSave(importSessionId, projectId, entityType, archetypeKey, 1, "Recorded", null, null));
}
private static string CharacterKey(string? name) => $"character-result-{StableKey(CanonicalCharacterIdentity(name))}";
private static string LocationKey(string? name) => $"location-result-{StableKey(name)}";
private static string AssetKey(string? name) => $"asset-result-{StableKey(name)}";
private static string DemandKey(params string[] parts) => StableKey(string.Join("-", parts.Where(part => !string.IsNullOrWhiteSpace(part))));
private static string CanonicalCharacterIdentity(string? name)
{
var clean = (name ?? string.Empty).Trim();
if (clean.Length == 0) return "unknown";
var lower = clean.ToLowerInvariant();
return lower switch
{
"i" or "me" or "myself" or "narrator" => "pov-character",
"mother" or "mum" or "her mother" or "his mother" => "mother",
"father" or "dad" or "her father" or "his father" => "father",
_ => clean
};
}
private static string Normalise(string? value)
=> string.Join(' ', (value ?? string.Empty).Trim().ToLowerInvariant().Split(' ', StringSplitOptions.RemoveEmptyEntries));
private static string StableKey(string? value)
{
var normalised = Normalise(value);
if (normalised.Length == 0) return "unknown";
var sb = new StringBuilder(normalised.Length);
foreach (var character in normalised)
{
if (char.IsLetterOrDigit(character)) sb.Append(character);
else if (sb.Length == 0 || sb[^1] != '-') sb.Append('-');
}
return sb.ToString().Trim('-');
}
private static string StableContentHash(string? value)
{
var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(value ?? string.Empty));
return Convert.ToHexString(bytes).ToLowerInvariant();
}
private static bool IsNamedCharacter(string? name)
=> !string.IsNullOrWhiteSpace(name)
&& !StoryIntelligenceIllustrationCompatibility.IsGroupEntity(name)
&& char.IsUpper(name.Trim()[0]);
private static int CharacterSignificance(SceneIntelligenceCharacter character)
=> character.MentionedOnly == true ? 25 : string.Equals(character.RoleInScene, "POV", StringComparison.OrdinalIgnoreCase) ? 100 : 60;
private static string InferInteriorExterior(string semanticType)
=> semanticType is "Road" or "CarPark" or "Beach" or "Canal" or "HouseExterior" or "StreetFurniture" ? "Exterior" : "Interior";
private static string SourceSectionType(StoryIntelligenceSavedSceneResult result, SceneIntelligenceScene scene)
{
var text = $"{result.SourceLabel} {scene.Summary?.Short} {scene.ScenePurpose?.ObservedFunction}".ToLowerInvariant();
return text.Contains("author", StringComparison.Ordinal) || text.Contains("acknowledg", StringComparison.Ordinal) || text.Contains("copyright", StringComparison.Ordinal) || text.Contains("preface", StringComparison.Ordinal)
? "Authorial"
: "Story";
}
private sealed record SceneResultWithParse(StoryIntelligenceSavedRun Run, StoryIntelligenceSavedSceneResult Result, SceneIntelligenceScene? Scene, string? ParseError);
}