graph

Author: KSemenenko

AGENTS.md

@@ -49,6 +49,8 @@ Target capabilities:
 
 - Keep the core Markdown-to-graph pipeline deterministic and testable without network access.
 - Keep the core runtime in-memory. Do not introduce localhost, HTTP server, background service, database server, or hosted API dependencies into the production library.
+- Graph construction must support caller-supplied build rules so applications can turn Markdown corpora into structured capability/workflow graphs with groups, typed relationships, related-node expansion, and focused subgraphs instead of only flat document/topic graphs.
+- Graph search APIs must support sparse, high-precision retrieval and explainable related/next-step candidates so callers can select the smallest useful result set and request additional graph-neighbor results later.
 - Treat LLM/entity extraction as an adapter behind a small interface and implement that adapter through `Microsoft.Extensions.AI.IChatClient` from the start.
 - Do not add an embedding dependency to the core graph pipeline. If vector/semantic indexing is added later, expose it as an optional adapter boundary through `Microsoft.Extensions.AI.IEmbeddingGenerator<,>` or a similarly small port, with the concrete provider owned by the host app.
 - It is allowed for the production library to reference `Microsoft.Extensions.AI.Abstractions`; concrete OpenAI/Azure/Foundry providers must remain app-level dependencies unless an ADR says otherwise.

Directory.Build.props

@@ -25,8 +25,8 @@
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <EnablePackageValidation>true</EnablePackageValidation>
     <Product>Markdown-LD Knowledge Bank</Product>
-    <Version>0.1.0</Version>
-    <PackageVersion>0.1.0</PackageVersion>
+    <Version>0.1.1</Version>
+    <PackageVersion>0.1.1</PackageVersion>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">

README.md

@@ -55,6 +55,7 @@ Tiktoken mode is deterministic and network-free. It uses lexical token-distance
 - `ExecuteSelectAsync(sparql)` — read-only SPARQL SELECT returning `SparqlQueryResult`
 - `ExecuteAskAsync(sparql)` — read-only SPARQL ASK returning `bool`
 - `SearchAsync(term)` — case-insensitive search across `schema:name`, `schema:description`, and `schema:keywords`, returning matching graph subjects as `SparqlQueryResult`
+- `SearchFocusedAsync(term)` — sparse graph search that returns primary, related, and next-step matches plus a bounded focused graph snapshot
 
 All async methods accept an optional `CancellationToken`.
 
@@ -144,6 +145,61 @@ You do not need to pass a base URI for normal use. Document identity is resolved
 
 The library uses `urn:managedcode:markdown-ld-kb:/` as an internal default base URI only to create valid RDF IRIs when the source does not provide `KnowledgeDocumentConversionOptions.CanonicalUri`. Pass `new MarkdownKnowledgePipeline(new Uri("https://your-domain/"))` only when you want generated document/entity IRIs to live under your own domain.
 
+## Capability Graph Rules
+
+Markdown can include deterministic graph rules in front matter. These rules are useful for capability catalogs, tool catalogs, workflow graphs, and any corpus where related and next-step nodes matter more than broad top-N search.
+
+```markdown
+---
+title: Story Delete Tool
+summary: Delete a story after the caller identifies the exact story item.
+graph_groups:
+  - Story tools
+  - Delete operation
+graph_related:
+  - https://kb.example/tools/story-feed-detail/
+graph_next_steps:
+  - https://kb.example/tools/story-comments/
+---
+# Story Delete Tool
+
+Use this capability to remove an existing story.
+```
+
+`graph_groups` creates `kb:memberOf` edges. `graph_related` creates `kb:relatedTo` edges. `graph_next_steps` creates `kb:nextStep` edges. For advanced graphs, use `graph_entities` and `graph_edges` to add explicit nodes and predicates. Absolute IRIs are preserved; plain labels become stable entity IRIs under the pipeline base URI.
+
+```csharp
+using ManagedCode.MarkdownLd.Kb.Pipeline;
+
+internal static class CapabilityGraphDemo
+{
+    public static async Task RunAsync(IReadOnlyList<MarkdownSourceDocument> documents)
+    {
+        var pipeline = new MarkdownKnowledgePipeline(
+            new Uri("https://kb.example/"),
+            extractionMode: MarkdownKnowledgeExtractionMode.Tiktoken);
+
+        var result = await pipeline.BuildAsync(documents);
+        var focused = await result.Graph.SearchFocusedAsync(
+            "remove the selected story from the feed",
+            new KnowledgeGraphFocusedSearchOptions
+            {
+                MaxPrimaryResults = 1,
+                MaxRelatedResults = 3,
+                MaxNextStepResults = 3,
+            });
+
+        var primary = focused.PrimaryMatches[0];
+        var mermaid = KnowledgeGraph.SerializeMermaidFlowchart(focused.FocusedGraph);
+
+        Console.WriteLine(primary.Label);
+        Console.WriteLine(mermaid);
+    }
+}
+```
+
+Use `BuildAsync(documents, KnowledgeGraphBuildOptions)` when graph rules are assembled by the host application instead of authored in Markdown front matter.
+
 ## Optional AI Extraction
 
 AI extraction builds graph facts from entities and assertions returned by an injected `Microsoft.Extensions.AI.IChatClient`. The package stays provider-neutral: it does not reference OpenAI, Azure OpenAI, Anthropic, or any other model-specific SDK. If no chat client is provided, `Auto` mode extracts no facts and reports a diagnostic; choose `Tiktoken` mode explicitly for local token-distance extraction.

docs/ADR/ADR-0004-capability-graph-rules.md

@@ -0,0 +1,80 @@
+# ADR-0004: Add Deterministic Capability Graph Rules
+
+Status: Accepted
+Date: 2026-04-15
+Related Features: `docs/Features/CapabilityGraphRules.md`
+
+---
+
+## Context
+
+The library can already build document metadata, AI-extracted facts, and Tiktoken token-distance graph structure. That is useful for document knowledge graphs, but capability catalogs need more explicit topology. A tool catalog should expose domain groups, operation groups, related tools, and next-step tools without relying on broad semantic top-N retrieval.
+
+Constraints:
+
+- The core library must remain in-memory and network-free.
+- Graph construction must be deterministic and testable.
+- Applications must be able to provide graph rules without hard-coding their domain into the package.
+- Search must support sparse high-confidence results and explainable expansion.
+
+## Decision
+
+Add deterministic capability graph rules to the pipeline.
+
+Rules can come from Markdown front matter or `KnowledgeGraphBuildOptions`. The first shipped front matter keys are:
+
+- `graph_entities`
+- `graph_edges`
+- `graph_groups`
+- `graph_related`
+- `graph_next_steps`
+
+The pipeline merges rule-derived facts with extraction-derived facts before graph construction. The graph API also exposes `SearchFocusedAsync`, which returns primary matches, related matches, next-step matches, and a bounded focused graph snapshot.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Markdown["Markdown"] --> Parser["Parser"]
+    Parser --> RuleExtractor["Capability rule extractor"]
+    Parser --> Extractor["Existing extraction mode"]
+    RuleExtractor --> RuleFacts["Rule facts"]
+    Extractor --> ExtractedFacts["Extracted facts"]
+    RuleFacts --> Merge["Fact merge"]
+    ExtractedFacts --> Merge
+    Merge --> Graph["RDF graph"]
+    Graph --> FocusedSearch["Focused search"]
+    FocusedSearch --> Primary["Primary"]
+    FocusedSearch --> Related["Related"]
+    FocusedSearch --> NextStep["Next step"]
+```
+
+## Consequences
+
+### Positive
+
+- Applications can build capability/workflow graphs directly from Markdown.
+- Tool catalogs can retrieve fewer, more relevant primary tools.
+- Related and next-step candidates are explicit and explainable.
+- Focused graph snapshots make graph debugging readable.
+- The library remains provider-neutral and deterministic.
+
+### Negative / Risks
+
+- Capability graph rules add a public API surface that must stay stable.
+- Poor caller-authored rules can still create noisy graphs.
+- Focused search is not a planner; it exposes graph neighborhood candidates for the caller to decide how to use.
+
+## Verification
+
+Testing methodology:
+
+- Build a realistic Markdown tool corpus with capability front matter.
+- Run the real `MarkdownKnowledgePipeline` in Tiktoken mode.
+- Assert primary, related, and next-step matches.
+- Assert focused graph export contains group and edge labels and excludes unrelated nodes.
+
+Commands:
+
+- `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --treenode-filter "/*/*/*/Capability_graph_front_matter_builds_focused_search_with_related_and_next_step_results" --no-progress`
+- `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release`

docs/Architecture.md

@@ -10,7 +10,7 @@ The upstream reference repository is kept as a read-only submodule at `external/
 
 The core runtime has no localhost, HTTP server, background service, database server, or hosted API dependency. Callers pass files, directories, or in-memory document content into the library, and the library returns in-memory graph/search/query results.
 
-The graph/search model does not require semantic embeddings. The AI boundary in the core pipeline is `Microsoft.Extensions.AI.IChatClient` for entity/assertion extraction. The library also exposes an explicit experimental Tiktoken mode that creates lexical sparse vectors from `Microsoft.ML.Tokenizers` token IDs and builds a local corpus graph. Its default weighting is corpus-fitted subword TF-IDF, with raw term frequency and binary presence kept as experimental baselines. Tiktoken mode also creates section/segment structure, local TF-IDF keyphrase topics, and explicit front matter entity hint nodes, but it is not a semantic embedding model. If semantic vector search is added later, it should be a separate optional adapter over `Microsoft.Extensions.AI.IEmbeddingGenerator<,>` or an equivalent small port, with the concrete provider owned by the host app.
+The graph/search model does not require semantic embeddings. The AI boundary in the core pipeline is `Microsoft.Extensions.AI.IChatClient` for entity/assertion extraction. The library also exposes an explicit experimental Tiktoken mode that creates lexical sparse vectors from `Microsoft.ML.Tokenizers` token IDs and builds a local corpus graph. Its default weighting is corpus-fitted subword TF-IDF, with raw term frequency and binary presence kept as experimental baselines. Tiktoken mode also creates section/segment structure, local TF-IDF keyphrase topics, and explicit front matter entity hint nodes, but it is not a semantic embedding model. Capability graph rules add deterministic caller-authored entities and edges for groups, related nodes, and next-step nodes so applications can build workflow/capability graphs without relying on a flat document-topic graph. If semantic vector search is added later, it should be a separate optional adapter over `Microsoft.Extensions.AI.IEmbeddingGenerator<,>` or an equivalent small port, with the concrete provider owned by the host app.
 
 ## System Boundaries
 
@@ -20,15 +20,18 @@ flowchart LR
     MarkdownFiles --> Loader["In-memory document converter and loader"]
     Loader --> Parser["Markdown parser and chunker"]
     Parser --> Router["Extraction mode router"]
+    Parser --> Rules["Capability graph rules"]
     Router --> ChatExtractor["IChatClient extractor"]
     Router --> TokenExtractor["Tiktoken token-distance extractor"]
     Router --> NoExtractor["No fact extractor"]
+    Rules --> Builder
     ChatExtractor --> Builder["RDF graph builder"]
     TokenExtractor --> Builder
     NoExtractor --> Builder
     Builder --> Graph["In-memory knowledge graph"]
     Graph --> Sparql["In-memory SPARQL executor API"]
     Graph --> Search["In-memory graph search API"]
+    Graph --> Focused["Focused graph search API"]
     Graph --> Serializers["Turtle and JSON-LD serializers"]
     Graph --> Merge["Thread-safe graph merge API"]
     IChatClient["Microsoft.Extensions.AI IChatClient"] --> ChatExtractor
@@ -53,6 +56,7 @@ sequenceDiagram
     Pipeline->>Parser: Parse Markdown and front matter
     Parser-->>Pipeline: Parsed document and sections
     Pipeline->>Router: Resolve Auto / None / ChatClient / Tiktoken
+    Pipeline->>Graph: Add deterministic capability graph rules
     alt ChatClient
         Router->>Chat: Structured LLM extraction
         Chat-->>Router: Knowledge extraction result
@@ -78,6 +82,7 @@ flowchart TB
         Parsing["Parsing: front matter, heading sections, wikilinks"]
         Ai["AI: IChatClient extraction port"]
         Tokens["Tiktoken: subword TF-IDF vectors, keyphrase topics, explicit entity hints, and token-distance search"]
+        Rules["Capability rules: graph_entities, graph_edges, graph_groups, graph_related, graph_next_steps"]
         Rdf["RDF: graph construction, namespaces, serialization"]
         Query["Query: SPARQL and graph search"]
     end
@@ -92,6 +97,7 @@ flowchart TB
     FlowTests --> Parsing
     FlowTests --> Ai
     FlowTests --> Tokens
+    FlowTests --> Rules
     FlowTests --> Rdf
     FlowTests --> Query
 ```
@@ -147,6 +153,7 @@ Required first-slice scenarios:
 - Markdown with front matter and headings builds a queryable document metadata graph without requiring fact extraction.
 - Empty Markdown input produces an empty graph without throwing.
 - Explicit Tiktoken mode builds section/segment/topic/entity-hint nodes plus `schema:hasPart`, `schema:about`, `schema:mentions`, and token-distance `kb:relatedTo` edges without network access.
+- Capability graph rules build `kb:memberOf`, `kb:relatedTo`, and `kb:nextStep` workflow edges from Markdown front matter or caller options, and focused search returns primary, related, and next-step result groups.
 - English, Ukrainian, French, and German queries over same-language token graphs produce a higher hit rate than cross-language translated-topic queries.
 - Term frequency, binary presence, and subword TF-IDF token weighting modes are covered by focused and flow tests.
 - SPARQL mutating queries are rejected before execution.
@@ -174,3 +181,5 @@ Coverage requirement: 95%+ line coverage for changed production code.
 - TextRank: `https://aclanthology.org/W04-3252/`
 - RDF/SPARQL dependency decision: `docs/ADR/ADR-0001-rdf-sparql-library.md`
 - LLM extraction dependency decision: `docs/ADR/ADR-0002-llm-extraction-ichatclient.md`
+- Capability graph rules decision: `docs/ADR/ADR-0004-capability-graph-rules.md`
+- Capability graph rules feature: `docs/Features/CapabilityGraphRules.md`

docs/Features/CapabilityGraphRules.md

@@ -0,0 +1,60 @@
+# Capability Graph Rules
+
+## Purpose
+
+Capability graph rules let callers build structured, sparse graphs from Markdown documents. They are intended for tool catalogs, workflow catalogs, and other corpora where a caller needs a small primary result set plus explainable related and next-step candidates.
+
+## Flow
+
+```mermaid
+flowchart LR
+    Source["Markdown documents"] --> Parser["MarkdownDocumentParser"]
+    Parser --> FrontMatter["graph_* front matter"]
+    Parser --> Extraction["None / ChatClient / Tiktoken extraction"]
+    FrontMatter --> Rules["KnowledgeGraphRuleExtractor"]
+    Rules --> RuleFacts["Entity and edge facts"]
+    Extraction --> Facts["Extraction facts"]
+    RuleFacts --> Merge["KnowledgeFactMerger"]
+    Facts --> Merge
+    Merge --> Graph["KnowledgeGraph"]
+    Graph --> Focused["SearchFocusedAsync"]
+    Focused --> Primary["Primary matches"]
+    Focused --> Related["Related matches"]
+    Focused --> Next["Next-step matches"]
+    Focused --> Snapshot["Focused graph snapshot"]
+```
+
+## Front Matter
+
+- `graph_entities` / `graphEntities` adds explicit graph entities.
+- `graph_edges` / `graphEdges` adds explicit assertions.
+- `graph_groups` / `graphGroups` adds group entities and `kb:memberOf` edges from the current document.
+- `graph_related` / `graphRelated` adds `kb:relatedTo` edges from the current document.
+- `graph_next_steps` / `graphNextSteps` adds `kb:nextStep` edges from the current document.
+
+Rule values can be strings or maps. Strings become node labels. Maps can use `id`, `label`, `name`, `type`, `sameAs`, `subject`, `predicate`, `object`, and `target` fields. Absolute IRIs are preserved, and labels become stable entity IRIs under the pipeline base URI.
+
+## Search Behavior
+
+`SearchFocusedAsync` returns:
+
+- primary matches from token-distance search when the graph was built in Tiktoken mode
+- primary matches from graph metadata search when no token index is present
+- related matches from direct `kb:relatedTo` edges and shared `kb:memberOf` groups
+- next-step matches from direct `kb:nextStep` edges
+- a bounded focused graph snapshot containing the selected neighborhood
+
+## Test Matrix
+
+| Case | Expected behavior |
+| --- | --- |
+| Capability front matter | Builds `kb:memberOf`, `kb:relatedTo`, and `kb:nextStep` edges |
+| Focused search | Returns a small primary set before related or next-step candidates |
+| Related expansion | Includes same-group and explicit related nodes |
+| Next-step expansion | Includes explicit `kb:nextStep` nodes |
+| Focused export | Mermaid/DOT export includes only selected graph neighborhood |
+
+## Verification
+
+- `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --treenode-filter "/*/*/*/Capability_graph_front_matter_builds_focused_search_with_related_and_next_step_results" --no-progress`
+- `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release`

src/MarkdownLd.Kb/Pipeline/KnowledgeGraph.Export.cs

@@ -7,6 +7,18 @@ namespace ManagedCode.MarkdownLd.Kb.Pipeline;
 
 public sealed partial class KnowledgeGraph
 {
+    public static string SerializeMermaidFlowchart(KnowledgeGraphSnapshot snapshot)
+    {
+        ArgumentNullException.ThrowIfNull(snapshot);
+        return BuildMermaidFlowchart(snapshot);
+    }
+
+    public static string SerializeDotGraph(KnowledgeGraphSnapshot snapshot)
+    {
+        ArgumentNullException.ThrowIfNull(snapshot);
+        return BuildDotGraph(snapshot);
+    }
+
     private static KnowledgeGraphSnapshot CreateGraphSnapshot(IEnumerable<Triple> triples)
     {
         var nodes = new Dictionary<string, KnowledgeGraphNode>(StringComparer.Ordinal);