Improve Obsidian-style script graph metadata

Author: KSemenenko

src/PrompterOne.Core/AGENTS.md

@@ -46,5 +46,7 @@ It owns TPS parsing, compilation, export, RSVP helpers, preview and workspace st
 - AI script graph labels, descriptions, semantic scopes, tokenizer chunks, and knowledge-graph markdown input must come from compiled TPS display text through the TPS SDK so they match the clean prompter text; raw TPS source is allowed only for source ranges and structural metadata, not post-hoc string-cleaned visible prose.
 - AI script graph semantic extraction must use an available LLM/chat-client path as the primary extractor. Regex, stop-word, capitalization, keyword, or hardcoded-domain semantic heuristics are strictly forbidden; when no LLM graph extraction is configured, the app may either show no semantic graph or run only an explicit user-requested tokenizer/vector similarity fallback based on `Microsoft.ML.Tokenizers` token vectors and distance calculations.
 - Script graph tokenizer/vector fallback must use the tokenizer/vector primitives exposed by `ManagedCode.MarkdownLd.Kb` when that package provides them; do not keep a duplicate Core-owned tokenizer implementation.
+- Script graph extraction must track the current `ManagedCode.MarkdownLd.Kb` graph model and use its metadata/front matter primitives such as entity hints, graph groups, related links, next steps, focused graph/search, and token topics before adding PrompterOne-owned graph glue.
+- Script graph output should feel like an Obsidian-style writer knowledge graph: documents, people, topics, backlinks, related ideas, and neighborhood metadata are primary; TPS mechanics remain source metadata unless they explain writing meaning.
 - AI and agent services must not use ad-hoc language heuristics for semantic meaning, intent matching, or action similarity. Prefer LLM extraction; the only non-LLM fallback allowed for similarity or search is explicit tokenizer/vector similarity based on `Microsoft.ML.Tokenizers`.
 - Respect root maintainability limits. Large parser/compiler edits need explicit decomposition or documented exceptions.

src/PrompterOne.Core/AI/Services/ScriptKnowledgeGraphCompiledDocument.cs

@@ -10,12 +10,14 @@ private ScriptKnowledgeGraphCompiledDocument(
         TpsCompilationResult compilation,
         string displayText,
         string displayMarkdown,
+        string knowledgeMarkdown,
         IReadOnlyDictionary<string, string> segmentTextById,
         IReadOnlyDictionary<string, string> blockTextById)
     {
         Compilation = compilation;
         DisplayText = displayText;
         DisplayMarkdown = displayMarkdown;
+        KnowledgeMarkdown = knowledgeMarkdown;
         SegmentTextById = segmentTextById;
         BlockTextById = blockTextById;
     }
@@ -26,6 +28,8 @@ private ScriptKnowledgeGraphCompiledDocument(
 
     public string DisplayMarkdown { get; }
 
+    public string KnowledgeMarkdown { get; }
+
     public IReadOnlyDictionary<string, string> SegmentTextById { get; }
 
     public IReadOnlyDictionary<string, string> BlockTextById { get; }
@@ -45,11 +49,13 @@ public static ScriptKnowledgeGraphCompiledDocument Create(string sourceContent,
                 StringComparer.Ordinal);
         var displayText = BuildWordText(compilation.Script.Words);
         var displayMarkdown = BuildDisplayMarkdown(compilation.Script, title);
+        var knowledgeMarkdown = BuildKnowledgeMarkdown(compilation.Script, displayMarkdown, title);
 
         return new ScriptKnowledgeGraphCompiledDocument(
             compilation,
             displayText,
             displayMarkdown,
+            knowledgeMarkdown,
             segmentTextById,
             blockTextById);
     }
@@ -97,11 +103,158 @@ private static void AppendScopeText(StringBuilder builder, string text)
         builder.AppendLine(text).AppendLine();
     }
 
+    private static string BuildKnowledgeMarkdown(CompiledScript script, string displayMarkdown, string? title)
+    {
+        var frontMatter = BuildKnowledgeFrontMatter(script, title);
+        return string.IsNullOrWhiteSpace(frontMatter)
+            ? displayMarkdown
+            : string.Concat(frontMatter, Environment.NewLine, displayMarkdown);
+    }
+
+    private static string BuildKnowledgeFrontMatter(CompiledScript script, string? title)
+    {
+        var metadata = CollectGraphMetadata(script, title);
+        if (metadata.EntityHints.Count == 0 && metadata.Tags.Count == 0 && metadata.Groups.Count == 0)
+        {
+            return string.Empty;
+        }
+
+        var builder = new StringBuilder();
+        builder.AppendLine("---");
+        if (!string.IsNullOrWhiteSpace(title))
+        {
+            builder.Append("title: ").AppendLine(QuoteYaml(title.Trim()));
+        }
+
+        if (metadata.Tags.Count > 0)
+        {
+            builder.AppendLine("tags:");
+            foreach (var tag in metadata.Tags)
+            {
+                builder.Append("  - ").AppendLine(QuoteYaml(tag));
+            }
+        }
+
+        if (metadata.Groups.Count > 0)
+        {
+            builder.AppendLine("graph_groups:");
+            foreach (var group in metadata.Groups)
+            {
+                builder.Append("  - ").AppendLine(QuoteYaml(group));
+            }
+        }
+
+        if (metadata.EntityHints.Count > 0)
+        {
+            builder.AppendLine("graph_entities:");
+            foreach (var hint in metadata.EntityHints)
+            {
+                builder.Append("  - label: ").AppendLine(QuoteYaml(hint.Label));
+                builder.Append("    type: ").AppendLine(QuoteYaml(hint.Type));
+            }
+        }
+
+        if (metadata.Related.Count > 0)
+        {
+            builder.AppendLine("graph_related:");
+            foreach (var related in metadata.Related)
+            {
+                builder.Append("  - ").AppendLine(QuoteYaml(related));
+            }
+        }
+
+        if (metadata.EntityHints.Count > 0)
+        {
+            builder.AppendLine("entity_hints:");
+            foreach (var hint in metadata.EntityHints)
+            {
+                builder.Append("  - label: ").AppendLine(QuoteYaml(hint.Label));
+                builder.Append("    type: ").AppendLine(QuoteYaml(hint.Type));
+            }
+        }
+
+        builder.AppendLine("---");
+        return builder.ToString().TrimEnd();
+    }
+
+    private static KnowledgeGraphFrontMatter CollectGraphMetadata(CompiledScript script, string? title)
+    {
+        var entityHints = new Dictionary<string, KnowledgeEntityHint>(StringComparer.OrdinalIgnoreCase);
+        var tags = new SortedSet<string>(StringComparer.OrdinalIgnoreCase);
+        var groups = new SortedSet<string>(StringComparer.OrdinalIgnoreCase)
+        {
+            "PrompterOne scripts"
+        };
+        var related = new SortedSet<string>(StringComparer.OrdinalIgnoreCase);
+        AddValue(tags, "tps");
+        AddValue(tags, "script");
+        AddValue(groups, title);
+
+        foreach (var segment in script.Segments)
+        {
+            AddEntityHint(entityHints, segment.Speaker, "schema:Person");
+            AddEntityHint(entityHints, segment.Emotion, "schema:DefinedTerm");
+            AddEntityHint(entityHints, segment.Archetype, "schema:DefinedTerm");
+            AddValue(tags, segment.Emotion);
+            AddValue(tags, segment.Archetype);
+            AddValue(related, segment.Name);
+
+            foreach (var block in segment.Blocks)
+            {
+                AddEntityHint(entityHints, block.Speaker, "schema:Person");
+                AddEntityHint(entityHints, block.Emotion, "schema:DefinedTerm");
+                AddEntityHint(entityHints, block.Archetype, "schema:DefinedTerm");
+                AddValue(tags, block.Emotion);
+                AddValue(tags, block.Archetype);
+                AddValue(related, block.Name);
+            }
+        }
+
+        return new KnowledgeGraphFrontMatter(
+            entityHints.Values
+                .OrderBy(static hint => hint.Type, StringComparer.OrdinalIgnoreCase)
+                .ThenBy(static hint => hint.Label, StringComparer.OrdinalIgnoreCase)
+                .ToArray(),
+            tags.ToArray(),
+            groups.ToArray(),
+            related.Take(12).ToArray());
+    }
+
+    private static void AddEntityHint(IDictionary<string, KnowledgeEntityHint> hints, string? label, string type)
+    {
+        if (string.IsNullOrWhiteSpace(label))
+        {
+            return;
+        }
+
+        var normalized = label.Trim();
+        hints.TryAdd($"{type}:{normalized}", new KnowledgeEntityHint(normalized, type));
+    }
+
+    private static void AddValue(ISet<string> values, string? value)
+    {
+        if (!string.IsNullOrWhiteSpace(value))
+        {
+            values.Add(value.Trim());
+        }
+    }
+
+    private static string QuoteYaml(string value) =>
+        "\"" + value.Replace("\\", "\\\\", StringComparison.Ordinal).Replace("\"", "\\\"", StringComparison.Ordinal) + "\"";
+
     private static string BuildWordText(IEnumerable<CompiledWord> words) =>
         string.Join(
             ' ',
             words
                 .Where(static word => word.Metadata.IsPause == false)
                 .Select(static word => word.CleanText)
                 .Where(static text => !string.IsNullOrWhiteSpace(text)));
+
+    private sealed record KnowledgeGraphFrontMatter(
+        IReadOnlyList<KnowledgeEntityHint> EntityHints,
+        IReadOnlyList<string> Tags,
+        IReadOnlyList<string> Groups,
+        IReadOnlyList<string> Related);
+
+    private sealed record KnowledgeEntityHint(string Label, string Type);
 }

src/PrompterOne.Core/AI/Services/ScriptKnowledgeGraphService.cs

@@ -1,3 +1,4 @@
+using System.Globalization;
 using ManagedCode.MarkdownLd.Kb.Pipeline;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
@@ -13,6 +14,7 @@ public sealed class ScriptKnowledgeGraphService(
 {
     private const string DocumentNodeId = "prompterone:document";
     private const string ContainsEdgeLabel = "contains";
+    private const string MarkdownKnowledgeSource = "markdown-ld-kb";
     private readonly IScriptKnowledgeGraphSemanticExtractor? _semanticExtractor = semanticExtractor;
     private readonly ScriptKnowledgeGraphTokenizerSimilarityExtractor _tokenizerSimilarityExtractor = tokenizerSimilarityExtractor ?? new();
     private readonly ILogger<ScriptKnowledgeGraphService> _logger = logger ?? NullLogger<ScriptKnowledgeGraphService>.Instance;
@@ -28,7 +30,7 @@ public async Task<ScriptKnowledgeGraphArtifact> BuildAsync(
         var pipeline = new MarkdownKnowledgePipeline();
         var kbResult = await pipeline
             .BuildFromMarkdownAsync(
-                compiledDocument.DisplayMarkdown,
+                compiledDocument.KnowledgeMarkdown,
                 CreateSourcePath(request.DocumentId),
                 cancellationToken: cancellationToken)
             .ConfigureAwait(false);
@@ -57,7 +59,7 @@ public async Task<ScriptKnowledgeGraphArtifact> BuildAsync(
             nodes,
             edges,
             ranges);
-        AddKnowledgeBankGraph(kbResult.Graph.ToSnapshot(), content, nodes, edges, ranges);
+        AddKnowledgeBankGraph(kbResult, content, nodes, edges, ranges);
         var semanticStatus = request.SemanticMode == ScriptKnowledgeGraphSemanticMode.StructuralOnly
             ? ScriptKnowledgeGraphSemanticStatus.StructuralOnly
             : await TryAddModelSemanticGraphAsync(
@@ -74,7 +76,7 @@ public async Task<ScriptKnowledgeGraphArtifact> BuildAsync(
             await _tokenizerSimilarityExtractor
                 .AddTokenizerSimilarityAsync(
                     content,
-                    compiledDocument.DisplayMarkdown,
+                    compiledDocument.KnowledgeMarkdown,
                     nodes,
                     edges,
                     ranges,
@@ -145,21 +147,37 @@ private async Task<ScriptKnowledgeGraphSemanticStatus> TryAddModelSemanticGraphA
     }
 
     private static void AddKnowledgeBankGraph(
-        KnowledgeGraphSnapshot snapshot,
+        MarkdownKnowledgeBuildResult result,
         string content,
         IDictionary<string, ScriptKnowledgeGraphNode> nodes,
         IDictionary<string, ScriptKnowledgeGraphEdge> edges,
         IDictionary<string, ScriptKnowledgeGraphSourceRange> ranges)
     {
+        var snapshot = result.Graph.ToSnapshot();
+        var factsById = result.Facts.Entities
+            .Where(static entity => !string.IsNullOrWhiteSpace(entity.Id))
+            .GroupBy(static entity => entity.Id!, StringComparer.Ordinal)
+            .ToDictionary(static group => group.Key, static group => group.First(), StringComparer.Ordinal);
         foreach (var node in snapshot.Nodes)
         {
             if (IsVisualKnowledgeNoise(node))
             {
                 continue;
             }
 
-            nodes.TryAdd(node.Id, new ScriptKnowledgeGraphNode(node.Id, node.Label, node.Kind.ToString(), "knowledge"));
-            ScriptKnowledgeGraphSourceRanges.AddRangeIfFound(content, node.Id, node.Label, ranges);
+            factsById.TryGetValue(node.Id, out var fact);
+            var kind = ResolveKnowledgeKind(node, fact);
+            var label = string.IsNullOrWhiteSpace(fact?.Label) ? node.Label : fact!.Label;
+            nodes.TryAdd(
+                node.Id,
+                new ScriptKnowledgeGraphNode(
+                    node.Id,
+                    label,
+                    kind,
+                    "knowledge",
+                    CreateKnowledgeDetail(node, fact),
+                    CreateKnowledgeAttributes(node, fact)));
+            ScriptKnowledgeGraphSourceRanges.AddRangeIfFound(content, node.Id, label, ranges);
         }
 
         foreach (var edge in snapshot.Edges)
@@ -174,6 +192,97 @@ private static void AddKnowledgeBankGraph(
         }
     }
 
+    private static string ResolveKnowledgeKind(KnowledgeGraphNode node, KnowledgeEntityFact? fact)
+    {
+        var type = fact?.Type ?? string.Empty;
+        if (ContainsType(type, "Person"))
+        {
+            return "Character";
+        }
+
+        if (ContainsType(type, "DefinedTerm"))
+        {
+            return "Term";
+        }
+
+        if (ContainsType(type, "Claim"))
+        {
+            return "Claim";
+        }
+
+        if (ContainsType(type, "CreativeWork") ||
+            ContainsType(type, "Article") ||
+            ContainsType(type, "TextDigitalDocument"))
+        {
+            return "Story";
+        }
+
+        return node.Kind switch
+        {
+            KnowledgeGraphNodeKind.Literal => "Literal",
+            KnowledgeGraphNodeKind.Blank => "Custom",
+            _ => "Entity",
+        };
+    }
+
+    private static bool ContainsType(string type, string value) =>
+        type.Contains(value, StringComparison.OrdinalIgnoreCase);
+
+    private static string? CreateKnowledgeDetail(KnowledgeGraphNode node, KnowledgeEntityFact? fact)
+    {
+        var detailParts = new List<string>();
+        AddDetail(detailParts, "type", fact?.Type);
+        AddDetail(detailParts, "source", fact?.Source);
+        if (node.Kind != KnowledgeGraphNodeKind.Uri)
+        {
+            AddDetail(detailParts, "rdf", node.Kind.ToString());
+        }
+
+        return detailParts.Count == 0 ? null : string.Join(" | ", detailParts);
+    }
+
+    private static IReadOnlyDictionary<string, string> CreateKnowledgeAttributes(
+        KnowledgeGraphNode node,
+        KnowledgeEntityFact? fact)
+    {
+        var attributes = new Dictionary<string, string>(StringComparer.Ordinal)
+        {
+            ["source"] = MarkdownKnowledgeSource,
+            ["rdfKind"] = node.Kind.ToString(),
+        };
+        AddAttribute(attributes, "entityType", fact?.Type);
+        AddAttribute(attributes, "sourceDocument", fact?.Source);
+        if (fact is not null)
+        {
+            AddAttribute(
+                attributes,
+                "confidence",
+                fact.Confidence.ToString("0.###", CultureInfo.InvariantCulture));
+            if (fact.SameAs.Count > 0)
+            {
+                AddAttribute(attributes, "sameAs", string.Join(", ", fact.SameAs));
+            }
+        }
+
+        return attributes;
+    }
+
+    private static void AddDetail(ICollection<string> details, string label, string? value)
+    {
+        if (!string.IsNullOrWhiteSpace(value))
+        {
+            details.Add($"{label}: {value.Trim()}");
+        }
+    }
+
+    private static void AddAttribute(IDictionary<string, string> attributes, string key, string? value)
+    {
+        if (!string.IsNullOrWhiteSpace(value))
+        {
+            attributes[key] = value.Trim();
+        }
+    }
+
     private static bool IsVisualKnowledgeNoise(KnowledgeGraphNode node) =>
         IsTpsHeaderLabel(node.Label) || IsSchemaUriNode(node);
 

src/PrompterOne.Shared/AGENTS.md

@@ -44,6 +44,8 @@
 - Script graph UI must expose an intentional analysis path when richer extraction is needed, and every graph mode should answer a concrete writer question such as "what is this about", "how are blocks connected", "which terms recur", "which references matter", or "where should I edit this idea".
 - Script graph UI must not silently fall back to regex/keyword semantic extraction when LLM graph extraction is unavailable; regex, stop-word, capitalization, keyword, and hardcoded-domain semantic heuristics are strictly forbidden. In that state, show an explicit action to connect AI or run tokenizer/vector similarity analysis; the tokenizer path must be user-visible as a lower-fidelity fallback, not disguised as LLM semantic understanding.
 - Script graph UI should surface tokenizer/vector similarity through the `ManagedCode.MarkdownLd.Kb` tokenizer path when available; do not add a separate browser or Shared-owned tokenizer implementation for the same fallback.
+- Script graph UI should read like an Obsidian graph workspace: expose document metadata, tags/topics, people, backlinks/links, node neighborhoods, and source-jump affordances around the canvas instead of showing only a decorative graph renderer.
+- Script graph UI must stay aligned with the current `ManagedCode.MarkdownLd.Kb` model; when that package adds graph metadata, focused search, entity hints, graph groups, related links, next steps, or token-topic primitives, PrompterOne should surface those concepts rather than flattening them into generic nodes.
 - Assistant spotlight suggestions and script graph UI must not use ad-hoc language heuristics for intent or similarity. Use LLM-backed semantics when available, or explicit tokenizer/vector similarity over localized action descriptions and the user query when a non-LLM fallback is needed.
 - Script graph editing must support a split source/graph workflow: the user should be able to inspect the graph beside the editor, click a meaningful graph node, and have the owning source range revealed or highlighted without leaving the graph workspace.
 - Script graph split mode must expose a user-resizable divider between source and graph panes, and graph view must also support a graph-only workspace mode for focused exploration.