code

Author: KSemenenko

AGENTS.md

@@ -48,7 +48,9 @@ Target capabilities:
 ## Durable Project Rules
 
 - 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.
 - 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.
 - The product/library name is `Markdown-LD Knowledge Bank`; do not rename it to a shorter marketing name.
 - The C# root namespace, assembly identity, and package ID MUST be `ManagedCode.MarkdownLd.Kb`.
@@ -85,7 +87,7 @@ List only the skills this solution actually uses.
 - `build`: `dotnet build MarkdownLd.Kb.slnx --no-restore`
 - `test`: `dotnet test MarkdownLd.Kb.slnx --no-build`
 - `format`: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
-- `coverage`: `dotnet test MarkdownLd.Kb.slnx --collect:"XPlat Code Coverage"`
+- `coverage`: `dotnet test MarkdownLd.Kb.slnx --no-build --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory TestResults/CoverletMtpFiltered`
 
 `.NET` runner policy:
 
@@ -94,7 +96,7 @@ List only the skills this solution actually uses.
 - Test framework: TUnit.
 - Assertion library: Shouldly.
 - Test runner model: TUnit through `dotnet test` / Microsoft.Testing.Platform-compatible execution.
-- Coverage: Coverlet XPlat collector unless a later ADR moves coverage to `coverlet.MTP` or another .NET 10-compatible collector.
+- Coverage: `coverlet.MTP` through `dotnet test --coverlet` with the production assembly include filter.
 
 ### Project AGENTS Policy
 

docs/ADR/ADR-0001-rdf-sparql-library.md

@@ -10,10 +10,10 @@ Related Features: `docs/Architecture.md`
 
 - [x] Analyze upstream graph stack and .NET options.
 - [x] Choose the RDF/SPARQL dependency.
-- [ ] Add dotNetRDF to the production project.
-- [ ] Add flow tests that query generated graphs through SPARQL.
-- [ ] Run build, test, format, and coverage commands.
-- [ ] Update `docs/Architecture.md` if dependency boundaries change.
+- [x] Add dotNetRDF to the production project.
+- [x] Add flow tests that query generated graphs through SPARQL.
+- [x] Run build, test, format, and coverage commands.
+- [x] Update `docs/Architecture.md` if dependency boundaries change.
 
 ## Context
 
@@ -46,6 +46,7 @@ Use dotNetRDF as the RDF graph, serialization, and SPARQL engine for the first .
 Key points:
 
 - dotNetRDF replaces Python RDFLib for the C# port.
+- The selected package supports RDF/SPARQL in .NET and the user guide documents in-memory RDF data and in-memory SPARQL querying, which matches the no-server core runtime boundary.
 - Markdig and YamlDotNet will handle Markdown/front matter parsing separately.
 - AI extraction remains behind an extraction port that uses `Microsoft.Extensions.AI.IChatClient`; provider/orchestration packages are not part of this RDF dependency decision.
 
@@ -98,7 +99,7 @@ flowchart LR
 
 Mitigations:
 
-- Hide dependency details behind `KnowledgeGraph`, `KnowledgeQueryService`, and serialization methods where practical.
+- Hide dependency details behind `KnowledgeGraph` query methods, `KnowledgeSearchService`, and serialization methods where practical.
 - Add tests for serialization and SPARQL query paths.
 - Keep remote/federated SPARQL out of the first slice.
 
@@ -165,7 +166,7 @@ Mitigations:
 - build: `dotnet build MarkdownLd.Kb.slnx --no-restore`
 - test: `dotnet test MarkdownLd.Kb.slnx --no-build`
 - format: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
-- coverage: `dotnet test MarkdownLd.Kb.slnx --collect:"XPlat Code Coverage"`
+- coverage: `dotnet test --solution MarkdownLd.Kb.slnx --no-build --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory TestResults/CoverletMtpFiltered`
 
 ### New or changed tests
 
@@ -187,4 +188,5 @@ No migration exists yet. This is the initial implementation decision.
 - `external/lqdev-markdown-ld-kb/tools/postprocess.py`
 - `external/lqdev-markdown-ld-kb/api/function_app.py`
 - `external/lqdev-markdown-ld-kb/.ai-memex/blog-post-zero-cost-knowledge-graph-from-markdown.md`
-- `https://github.com/dotnetrdf/dotnetrdf`
+- dotNetRDF upstream repository: `https://github.com/dotnetrdf/dotnetrdf`
+- dotNetRDF user guide: `https://dotnetrdf.org/docs/stable/user_guide/index.html`

docs/ADR/ADR-0002-llm-extraction-ichatclient.md

@@ -114,7 +114,7 @@ Mitigations:
 - build: `dotnet build MarkdownLd.Kb.slnx --no-restore`
 - test: `dotnet test MarkdownLd.Kb.slnx --no-build`
 - format: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
-- coverage: `dotnet test MarkdownLd.Kb.slnx --collect:"XPlat Code Coverage"`
+- coverage: `dotnet test --solution MarkdownLd.Kb.slnx --no-build --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory TestResults/CoverletMtpFiltered`
 
 ## References
 

docs/Architecture.md

@@ -4,22 +4,26 @@ Date: 2026-04-11
 
 ## Purpose
 
-Markdown-LD Knowledge Bank is a .NET 10 library for converting human-authored Markdown knowledge-base files into an RDF knowledge graph and querying that graph through SPARQL or higher-level search APIs.
+Markdown-LD Knowledge Bank is a .NET 10 library for converting human-authored Markdown knowledge-base files into an in-memory RDF knowledge graph and querying that graph through SPARQL or higher-level search APIs.
 
 The upstream reference repository is kept as a read-only submodule at `external/lqdev-markdown-ld-kb`. This C# implementation ports the technology, not the Python file layout.
 
+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 first-slice graph/search model does not require embeddings. The only AI boundary in the core pipeline is `Microsoft.Extensions.AI.IChatClient` for optional entity/assertion extraction. 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
 
 ```mermaid
 flowchart LR
     Author["Markdown author"] --> MarkdownFiles["Markdown files"]
-    MarkdownFiles --> Loader["Document loader"]
+    MarkdownFiles --> Loader["In-memory document converter and loader"]
     Loader --> Parser["Markdown parser and chunker"]
     Parser --> Extractor["Fact extractor port"]
     Extractor --> Builder["RDF graph builder"]
-    Builder --> Graph["Knowledge graph"]
-    Graph --> Sparql["SPARQL query service"]
-    Graph --> Search["Graph search service"]
+    Builder --> Graph["In-memory knowledge graph"]
+    Graph --> Sparql["In-memory SPARQL executor API"]
+    Graph --> Search["In-memory graph search API"]
     Graph --> Serializers["Turtle and JSON-LD serializers"]
     IChatClient["Microsoft.Extensions.AI IChatClient"] --> Extractor
     AgentFramework["Future Microsoft Agent Framework orchestration"] -. "wraps IChatClient" .-> IChatClient
@@ -35,7 +39,7 @@ sequenceDiagram
     participant Extractor as IKnowledgeFactExtractor
     participant Chat as IChatClient
     participant Graph as KnowledgeGraphBuilder
-    participant Query as KnowledgeQueryService
+    participant Query as InMemorySparqlExecutor
 
     Caller->>Pipeline: BuildAsync(documents, options)
     Pipeline->>Parser: Parse Markdown and front matter
@@ -45,7 +49,7 @@ sequenceDiagram
     Chat-->>Extractor: Knowledge extraction result
     Extractor-->>Pipeline: Article, entities, assertions
     Pipeline->>Graph: Add facts as RDF triples
-    Graph-->>Pipeline: KnowledgeGraph
+    Graph-->>Pipeline: In-memory KnowledgeGraph
     Caller->>Query: ExecuteSelect(graph, sparql)
     Query-->>Caller: SPARQL bindings
 ```
@@ -82,7 +86,7 @@ flowchart TB
 | `tools/chunker.py` | `MarkdownDocumentParser` | YAML front matter, stable document ID, heading sections, stable chunk IDs |
 | `tools/postprocess.py` | `DeterministicKnowledgeFactExtractor`, RDF builders | slug IDs, entity canonicalization, assertion de-duplication, schema.org/kb/prov vocabulary |
 | `tools/kg_build.py` | `MarkdownKnowledgePipeline` | orchestrates parse -> extract -> graph build -> query-ready graph |
-| `api/function_app.py` | `KnowledgeQueryService` | SELECT/ASK safety, SPARQL execution, JSON result shape at library level |
+| `api/function_app.py` | `KnowledgeGraph` query methods and `KnowledgeSearchService` | SELECT/ASK safety, in-memory SPARQL execution, JSON result shape at library level without a hosted function/server |
 | `tools/llm_client.py` | `ChatClientKnowledgeFactExtractor` | structured LLM extraction through `Microsoft.Extensions.AI.IChatClient` |
 | `api/nl_to_sparql.py` | future query adapter | schema-injected NL-to-SPARQL through `IChatClient`; Microsoft Agent Framework may orchestrate this later |
 | `ontology/*.ttl`, `ontology/context.jsonld` | `KnowledgeGraphNamespaces` | schema.org, kb, prov, rdf, xsd namespaces |
@@ -92,6 +96,7 @@ flowchart TB
 - Parsing depends on Markdig and YamlDotNet.
 - RDF graph building and SPARQL execution depend on dotNetRDF.
 - LLM extraction depends on `Microsoft.Extensions.AI.Abstractions` and accepts `IChatClient`.
+- Embeddings are not required for the core graph build/query flow.
 - Public API should prefer repository types over raw dependency types when feasible.
 - AI adapters depend on the core extraction port. The core library must not depend on concrete provider packages or agent orchestration packages in the first slice.
 
@@ -117,5 +122,7 @@ Coverage requirement: 95%+ line coverage for changed production code.
 - Upstream reference repository: `external/lqdev-markdown-ld-kb`
 - Blog pattern: `external/lqdev-markdown-ld-kb/.ai-memex/blog-post-zero-cost-knowledge-graph-from-markdown.md`
 - NL-to-SPARQL pattern: `external/lqdev-markdown-ld-kb/.ai-memex/pattern-nl-to-sparql-schema-injected-few-shot.md`
+- dotNetRDF upstream repository: `https://github.com/dotnetrdf/dotnetrdf`
+- dotNetRDF user guide: `https://dotnetrdf.org/docs/stable/user_guide/index.html`
 - RDF/SPARQL dependency decision: `docs/ADR/ADR-0001-rdf-sparql-library.md`
 - LLM extraction dependency decision: `docs/ADR/ADR-0002-llm-extraction-ichatclient.md`

src/MarkdownLd.Kb/AGENTS.md

@@ -16,13 +16,15 @@ Purpose: Production library for Markdown-LD Knowledge Bank.
 - The production library may reference `Microsoft.Extensions.AI` abstractions, Markdig, YamlDotNet, and dotNetRDF.
 - Do not add provider-specific LLM SDKs here.
 - Do not add Microsoft Agent Framework packages here without a new ADR.
+- Do not add localhost, HTTP server, background service, database server, or hosted API dependencies. The production pipeline must build, store, query, and serialize graphs in memory.
+- Do not add embedding/vector provider dependencies to the core pipeline. Future semantic/vector search must be optional and provider-neutral.
 - Keep the root namespace, assembly name, and package ID as `ManagedCode.MarkdownLd.Kb`.
 
 ## Commands
 
 - build: `dotnet build ../../MarkdownLd.Kb.slnx --no-restore`
 - test: `dotnet test ../../MarkdownLd.Kb.slnx --no-build`
-- coverage: `dotnet test ../../MarkdownLd.Kb.slnx --collect:"XPlat Code Coverage"`
+- coverage: `dotnet test ../../MarkdownLd.Kb.slnx --no-build --coverlet --coverlet-output-format cobertura --coverlet-include '[ManagedCode.MarkdownLd.Kb]*' --results-directory ../../TestResults/CoverletMtpFiltered`
 
 ## Local Risks
 

src/MarkdownLd.Kb/Ai/ChatClientKnowledgeFactExtractor.cs

@@ -58,7 +58,7 @@ public async Task<KnowledgeFactExtractionResult> ExtractAsync(
                 request.ChunkId,
                 [],
                 [],
-                string.Empty);
+                EmptyString);
         }
 
         var messages = new[]
@@ -81,7 +81,7 @@ public async Task<KnowledgeFactExtractionResult> ExtractAsync(
                 request.ChunkId,
                 [],
                 [],
-                response.Text ?? string.Empty);
+                response.Text ?? EmptyString);
         }
 
         var entities = NormalizeEntities(envelope.Entities);
@@ -92,7 +92,7 @@ public async Task<KnowledgeFactExtractionResult> ExtractAsync(
             request.ChunkId,
             entities,
             assertions,
-            response.Text ?? string.Empty);
+            response.Text ?? EmptyString);
     }
 
     private ChatOptions BuildChatOptions()
@@ -128,7 +128,7 @@ private static string BuildUserPrompt(KnowledgeFactExtractionRequest request)
                     .Append(FrontMatterItemPrefix)
                     .Append(pair.Key)
                     .Append(KeyValueSeparator)
-                    .AppendLine(pair.Value ?? string.Empty);
+                    .AppendLine(pair.Value ?? EmptyString);
             }
         }
 

src/MarkdownLd.Kb/Ai/KnowledgeFactConstants.cs

@@ -10,6 +10,7 @@ internal static class KnowledgeFactConstants
     internal const string SchemaCreativeWork = "schema:CreativeWork";
     internal const string SchemaArticle = "schema:Article";
     internal const string SchemaThing = "schema:Thing";
+    internal const string EmptyString = "";
 
     internal const string ArticleIdLabel = "ARTICLE_ID: ";
     internal const string ChunkIdLabel = "CHUNK_ID: ";

src/MarkdownLd.Kb/Extraction/MarkdownFrontMatterParser.cs

@@ -13,7 +13,7 @@ public static MarkdownFrontMatterParseResult Parse(string markdown)
     {
         if (string.IsNullOrWhiteSpace(markdown))
         {
-            return new MarkdownFrontMatterParseResult(new MarkdownFrontMatter(), string.Empty, false);
+            return new MarkdownFrontMatterParseResult(new MarkdownFrontMatter(), Empty, false);
         }
 
         var normalized = markdown.TrimStart('\uFEFF').Replace(CarriageReturnLineFeed, LineFeed);
@@ -78,7 +78,7 @@ private static (string FrontMatter, string Body, bool HasFrontMatter) SplitFront
         var firstLine = reader.ReadLine();
         if (!string.Equals(firstLine?.Trim(), FrontMatterFence, StringComparison.Ordinal))
         {
-            return (string.Empty, markdown, false);
+            return (Empty, markdown, false);
         }
 
         var frontMatter = new StringBuilder();
@@ -94,7 +94,7 @@ private static (string FrontMatter, string Body, bool HasFrontMatter) SplitFront
             frontMatter.AppendLine(line);
         }
 
-        return (string.Empty, markdown, false);
+        return (Empty, markdown, false);
     }
 
     private static string? ReadString(IReadOnlyDictionary<string, object?> values, string key)
@@ -164,19 +164,19 @@ private static IReadOnlyList<MarkdownAuthor> ReadAuthors(IReadOnlyDictionary<str
         {
             return new MarkdownAuthor
             {
-                Name = ReadString(map, NameKey) ?? ReadString(map, LabelKey) ?? string.Empty,
+                Name = ReadString(map, NameKey) ?? ReadString(map, LabelKey) ?? Empty,
                 SameAs = ReadString(map, SameAsKey) ?? ReadString(map, SameAsSnakeKey),
                 Type = ReadString(map, TypeKey),
             };
         }
 
         if (item is IDictionary<object, object?> dynamicMap)
         {
-            var dictionary = dynamicMap.ToDictionary(entry => entry.Key.ToString() ?? string.Empty, entry => entry.Value, StringComparer.OrdinalIgnoreCase);
+            var dictionary = dynamicMap.ToDictionary(entry => entry.Key.ToString() ?? Empty, entry => entry.Value, StringComparer.OrdinalIgnoreCase);
             return ReadAuthor(dictionary);
         }
 
-        return new MarkdownAuthor { Name = item.ToString()?.Trim() ?? string.Empty };
+        return new MarkdownAuthor { Name = item.ToString()?.Trim() ?? Empty };
     }
 
     private static IReadOnlyList<MarkdownTopic> ReadTopics(IReadOnlyDictionary<string, object?> values, string key)
@@ -210,18 +210,18 @@ private static IReadOnlyList<MarkdownTopic> ReadTopics(IReadOnlyDictionary<strin
         {
             return new MarkdownTopic
             {
-                Label = ReadString(map, LabelKey) ?? ReadString(map, NameKey) ?? ReadString(map, ValueKey) ?? string.Empty,
+                Label = ReadString(map, LabelKey) ?? ReadString(map, NameKey) ?? ReadString(map, ValueKey) ?? Empty,
                 SameAs = ReadString(map, SameAsKey) ?? ReadString(map, SameAsSnakeKey),
             };
         }
 
         if (item is IDictionary<object, object?> dynamicMap)
         {
-            var dictionary = dynamicMap.ToDictionary(entry => entry.Key.ToString() ?? string.Empty, entry => entry.Value, StringComparer.OrdinalIgnoreCase);
+            var dictionary = dynamicMap.ToDictionary(entry => entry.Key.ToString() ?? Empty, entry => entry.Value, StringComparer.OrdinalIgnoreCase);
             return ReadTopic(dictionary);
         }
 
-        return new MarkdownTopic { Label = NormalizeLabel(item.ToString() ?? string.Empty) };
+        return new MarkdownTopic { Label = NormalizeLabel(item.ToString() ?? Empty) };
     }
 
     private static IReadOnlyList<MarkdownEntityHint> ReadEntityHints(IReadOnlyDictionary<string, object?> values)
@@ -255,19 +255,19 @@ private static IReadOnlyList<MarkdownEntityHint> ReadEntityHints(IReadOnlyDictio
         {
             return new MarkdownEntityHint
             {
-                Label = ReadString(map, LabelKey) ?? ReadString(map, NameKey) ?? string.Empty,
+                Label = ReadString(map, LabelKey) ?? ReadString(map, NameKey) ?? Empty,
                 SameAs = ReadString(map, SameAsKey) ?? ReadString(map, SameAsSnakeKey),
                 Type = ReadString(map, TypeKey),
             };
         }
 
         if (item is IDictionary<object, object?> dynamicMap)
         {
-            var dictionary = dynamicMap.ToDictionary(entry => entry.Key.ToString() ?? string.Empty, entry => entry.Value, StringComparer.OrdinalIgnoreCase);
+            var dictionary = dynamicMap.ToDictionary(entry => entry.Key.ToString() ?? Empty, entry => entry.Value, StringComparer.OrdinalIgnoreCase);
             return ReadEntityHint(dictionary);
         }
 
-        return new MarkdownEntityHint { Label = NormalizeLabel(item.ToString() ?? string.Empty) };
+        return new MarkdownEntityHint { Label = NormalizeLabel(item.ToString() ?? Empty) };
     }
 
     private static string NormalizeLabel(string value)

src/MarkdownLd.Kb/Extraction/MarkdownKnowledgeCanonicalizer.cs

@@ -163,7 +163,7 @@ private static string ResolveEntityId(string value, IReadOnlyDictionary<string,
             return entityId;
         }
 
-        if (Uri.TryCreate(value, UriKind.Absolute, out var uri) || value.StartsWith(UrnSchemePrefix, StringComparison.OrdinalIgnoreCase))
+        if (Uri.TryCreate(value, UriKind.Absolute, out _) || value.StartsWith(UrnSchemePrefix, StringComparison.OrdinalIgnoreCase))
         {
             return value;
         }