From 87f5e5d4ad28b243614573cb9bf79962d97e4c64 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Fri, 11 Sep 2026 10:15:29 -0600 Subject: [PATCH] feat: Add resolve block to filterable facets for enhanced value retrieval --- demo/AgentCore.Demo/config/example.yaml | 18 +++ .../Schema/ProvidersConfiguration.cs | 36 ++++++ .../Schema/agentcore-v1.schema.json | 28 +++++ .../Validation/KnowledgeFilterValidator.cs | 67 +++++++++++ .../Knowledge/FacetFilterSchema.cs | 14 ++- .../PublicAPI.Unshipped.txt | 30 +++++ .../Configuration/FacetResolveSchemaTests.cs | 62 ++++++++++ .../KnowledgeFilterValidatorTests.cs | 107 ++++++++++++++++++ .../Knowledge/FacetFilterTests.cs | 55 +++++++++ 9 files changed, 415 insertions(+), 2 deletions(-) create mode 100644 tests/AgentCore.Application.Tests/Configuration/FacetResolveSchemaTests.cs create mode 100644 tests/AgentCore.Application.Tests/Configuration/Validation/KnowledgeFilterValidatorTests.cs diff --git a/demo/AgentCore.Demo/config/example.yaml b/demo/AgentCore.Demo/config/example.yaml index a97804b0..44671eec 100644 --- a/demo/AgentCore.Demo/config/example.yaml +++ b/demo/AgentCore.Demo/config/example.yaml @@ -432,6 +432,24 @@ providers: # filters on values no card carries and the retry pays for a second search most times out. # A facet worth filtering by is usually worth a vocabulary: slot of its own. # + # When the vocabulary is too big for a slot or a prompt — thousands of machine tags — give the + # facet a resolve: block instead. It names a lookup the MODEL runs before it filters: one + # search narrowed to the index cards under another facet, then the value copied off the card + # it finds. The host prints the recipe on the search tool and runs nothing itself. + # + # - key: lookup + # description: "The only value is model-numbers. It returns the model cards and nothing else." + # - key: model + # description: "One machine and the year it was built, as one tag, such as lcr-2023." + # resolve: + # via: { key: lookup, value: model-numbers } + # query: " model number" + # read: the Tag column of the row for the person's year + # + # via must name another filterable facet, and that one may not resolve in turn: one hop only. + # The start refuses a resolve that points at itself, at a key not listed here, or at a facet + # that has a resolve of its own. + # # Prefetch agents ignore this block: they advertise no function, so there is no argument to fill. links: diff --git a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs index 005d349b..a07f9b67 100644 --- a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs @@ -72,6 +72,42 @@ public sealed record KnowledgeFilterableFacetConfiguration /// Gets what this facet means, in the words the model reads before it picks a value. public required string Description { get; init; } + + /// + /// Gets how the model finds an exact value for this facet, or when the + /// description alone is enough to pick one. + /// + public KnowledgeFacetResolveConfiguration? Resolve { get; init; } +} + +/// +/// The lookup that turns what the person said into the one value a facet is stored under. +/// +/// +/// A vocabulary of thousands cannot sit in a prompt. The model instead searches a small index — the +/// cards under one other facet — and copies the value off the card it finds. This block is printed +/// on the search tool, not run by the host: the model does the lookup itself. +/// +public sealed record KnowledgeFacetResolveConfiguration +{ + /// Gets the facet and value that narrow the lookup search to the index cards. + public required KnowledgeFacetValueConfiguration Via { get; init; } + + /// Gets what the model searches for, with placeholders in angle brackets for what the person said. + public required string Query { get; init; } + + /// Gets where on the card the value is, in the words the model reads. + public required string Read { get; init; } +} + +/// One facet key and the value it must carry. +public sealed record KnowledgeFacetValueConfiguration +{ + /// Gets the facet key. + public required string Key { get; init; } + + /// Gets the value the cards must carry. + public required string Value { get; init; } } /// Which facets a card may opt out of, and the value it opts out with. diff --git a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json index 8aecb095..5636e7b2 100644 --- a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json +++ b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json @@ -1225,6 +1225,34 @@ "type": "string", "minLength": 1, "description": "What this facet means, in the words the model reads before it picks a value." + }, + "resolve": { + "type": "object", + "description": "How the model finds an exact value for this facet when the vocabulary is too big to describe: one filtered search of the cards under another facet, then a value copied off the card. Printed on the search tool; the model runs it. Absent means the description alone is enough to pick a value.", + "additionalProperties": false, + "required": ["via", "query", "read"], + "properties": { + "via": { + "type": "object", + "description": "The facet and value that narrow the lookup search to the index cards. Must name another filterable facet, one without a resolve of its own.", + "additionalProperties": false, + "required": ["key", "value"], + "properties": { + "key": { "type": "string", "minLength": 1, "description": "The filterable facet the lookup filters on." }, + "value": { "type": "string", "minLength": 1, "description": "The value the index cards carry under that facet." } + } + }, + "query": { + "type": "string", + "minLength": 1, + "description": "What the model searches for, with placeholders in angle brackets for what the person said, such as \" model number\"." + }, + "read": { + "type": "string", + "minLength": 1, + "description": "Where on the card the value is, in the words the model reads, such as \"the Tag column of the row for the person's year\"." + } + } } } } diff --git a/src/AgentCore.Application/Configuration/Validation/KnowledgeFilterValidator.cs b/src/AgentCore.Application/Configuration/Validation/KnowledgeFilterValidator.cs index 7183ca35..bc66c56e 100644 --- a/src/AgentCore.Application/Configuration/Validation/KnowledgeFilterValidator.cs +++ b/src/AgentCore.Application/Configuration/Validation/KnowledgeFilterValidator.cs @@ -59,6 +59,73 @@ internal static void Check(KnowledgeScopeConfiguration? scope, List + /// The lookup runs one hop: a facet resolves through the cards of another facet, and that one + /// must be pickable from its description alone, or the model would chase a chain of lookups. + /// + private static void CheckResolve( + KnowledgeFilterableFacetConfiguration facet, + KnowledgeFacetResolveConfiguration resolve, + IReadOnlyList filterable, + string pointer, + List errors) + { + var via = ConfigurationError.AppendPointer(pointer, "via"); + var viaKey = ConfigurationError.AppendPointer(via, "key"); + + if (string.Equals(resolve.Via.Key, facet.Key, StringComparison.Ordinal)) + { + errors.Add(Reference( + viaKey, + $"the facet '{facet.Key}' resolves through itself. The lookup must search the cards " + + "of another facet, one whose value the model can pick without a lookup.")); + } + else if (filterable.FirstOrDefault(other => string.Equals(other.Key, resolve.Via.Key, StringComparison.Ordinal)) + is not { } index) + { + errors.Add(Reference( + viaKey, + $"the facet '{facet.Key}' resolves through '{resolve.Via.Key}', which is not a " + + "filterable facet. The lookup is a filtered search, so the facet it filters on must " + + "be one the model may set.")); + } + else if (index.Resolve is not null) + { + errors.Add(Reference( + viaKey, + $"the facet '{facet.Key}' resolves through '{index.Key}', which resolves through " + + "something else in turn. One hop only: the facet a lookup filters on must be " + + "pickable from its description alone.")); + } + + if (string.IsNullOrWhiteSpace(resolve.Via.Value)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(via, "value"), + $"the facet '{facet.Key}' resolves through '{resolve.Via.Key}' with a blank value, so " + + "the lookup would filter on nothing.")); + } + + if (string.IsNullOrWhiteSpace(resolve.Query)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "query"), + $"the facet '{facet.Key}' has a blank resolve query, so the model has nothing to search for.")); + } + + if (string.IsNullOrWhiteSpace(resolve.Read)) + { + errors.Add(Reference( + ConfigurationError.AppendPointer(pointer, "read"), + $"the facet '{facet.Key}' does not say where on the card the value is read from.")); } } diff --git a/src/AgentCore.Application/Knowledge/FacetFilterSchema.cs b/src/AgentCore.Application/Knowledge/FacetFilterSchema.cs index c57ed600..14dce185 100644 --- a/src/AgentCore.Application/Knowledge/FacetFilterSchema.cs +++ b/src/AgentCore.Application/Knowledge/FacetFilterSchema.cs @@ -65,8 +65,8 @@ private static JsonObject Argument(IReadOnlyList $"To find the value: search once for \"{resolve.Query}\" with filters " + + $"[{{key: {resolve.Via.Key}, value: {resolve.Via.Value}}}], and read {resolve.Read}. " + + "Copy it exactly; never build one."; } diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index 9ea185ea..62ff50a4 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -507,6 +507,24 @@ AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.Probe AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ProbeDeadlineSeconds.init -> void AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ProbeWaitMarginSeconds.get -> int AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ProbeWaitMarginSeconds.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.$() -> AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration! +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.Equals(AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration? other) -> bool +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.KnowledgeFacetResolveConfiguration() -> void +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.Query.get -> string! +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.Query.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.Read.get -> string! +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.Read.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.Via.get -> AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration! +AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.Via.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration +AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.$() -> AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration! +AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.Equals(AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration? other) -> bool +AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.Key.get -> string! +AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.Key.init -> void +AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.KnowledgeFacetValueConfiguration() -> void +AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.Value.get -> string! +AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.Value.init -> void AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.$() -> AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration! AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.Authority.get -> string? @@ -531,6 +549,8 @@ AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration.Key.get -> string! AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration.Key.init -> void AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration.KnowledgeFilterableFacetConfiguration() -> void +AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration.Resolve.get -> AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration? +AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration.Resolve.init -> void AgentCore.Application.Configuration.Schema.KnowledgeLinkLookup AgentCore.Application.Configuration.Schema.KnowledgeLinkLookup.Direct = 1 -> AgentCore.Application.Configuration.Schema.KnowledgeLinkLookup AgentCore.Application.Configuration.Schema.KnowledgeLinkLookup.Filter = 2 -> AgentCore.Application.Configuration.Schema.KnowledgeLinkLookup @@ -1468,6 +1488,12 @@ override AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.ToS override AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.GetHashCode() -> int override AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.ToString() -> string! override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.GetHashCode() -> int override AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.ToString() -> string! @@ -1677,6 +1703,10 @@ static AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.opera static AgentCore.Application.Configuration.Schema.HttpRequestConfiguration.operator ==(AgentCore.Application.Configuration.Schema.HttpRequestConfiguration? left, AgentCore.Application.Configuration.Schema.HttpRequestConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeAmbiguityConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFacetResolveConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFacetValueConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.operator ==(AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration.operator !=(AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration? left, AgentCore.Application.Configuration.Schema.KnowledgeFilterableFacetConfiguration? right) -> bool diff --git a/tests/AgentCore.Application.Tests/Configuration/FacetResolveSchemaTests.cs b/tests/AgentCore.Application.Tests/Configuration/FacetResolveSchemaTests.cs new file mode 100644 index 00000000..8a47a466 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Configuration/FacetResolveSchemaTests.cs @@ -0,0 +1,62 @@ +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Validation; +using Xunit; + +namespace AgentCore.Application.Tests.Configuration; + +/// +/// The document schema knows the resolve block on a filterable facet. +/// +public sealed class FacetResolveSchemaTests +{ + private const string Facets = """ + apiVersion: agentcore/v1 + name: plain + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + knowledge: + kind: qdrant + collection: kb + scope: + template: "facets.{key}" + filterable: + - key: lookup + description: The only value is model-numbers. + - key: model + description: One machine and its year, as one tag. + resolve: + """; + + [Fact] + public void AFacetWithResolve_PassesTheSchema() + { + var document = ConfigurationLoader.ReadDocument( + Facets + """ + + via: { key: lookup, value: model-numbers } + query: " model number" + read: the Tag column of the row for the person's year + """, + ConfigurationFormat.Yaml); + + Assert.Empty(ConfigurationSchemaValidator.Evaluate(document)); + } + + [Fact] + public void AResolveMissingItsRead_FailsTheSchema() + { + var document = ConfigurationLoader.ReadDocument( + Facets + """ + + via: { key: lookup, value: model-numbers } + query: " model number" + """, + ConfigurationFormat.Yaml); + + var failure = Assert.Single(ConfigurationSchemaValidator.Evaluate(document)); + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + } +} diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/KnowledgeFilterValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/KnowledgeFilterValidatorTests.cs new file mode 100644 index 00000000..98adb70b --- /dev/null +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/KnowledgeFilterValidatorTests.cs @@ -0,0 +1,107 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Configuration.Validation; +using Xunit; + +namespace AgentCore.Application.Tests.Configuration.Validation; + +/// +/// The resolve block a filterable facet may carry: it names the lookup the model runs to find +/// an exact value, so every part of it must point at something real. +/// +public sealed class KnowledgeFilterValidatorTests +{ + private const string Pointer = "/providers/knowledge/scope/filterable/1/resolve"; + + [Fact] + public void Resolve_ViaAnotherFilterableFacet_Passes() + { + var result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("lookup")))); + + Assert.Empty(result.Errors); + } + + [Fact] + public void Resolve_ViaAKeyNobodyDeclared_Fails() + { + var result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("family")))); + + var error = Assert.Single(result.Errors); + Assert.Equal(Pointer + "/via/key", error.Pointer); + Assert.Contains("family", error.Message, StringComparison.Ordinal); + } + + [Fact] + public void Resolve_ViaItself_Fails() + { + var result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(Via("model")))); + + var error = Assert.Single(result.Errors); + Assert.Equal(Pointer + "/via/key", error.Pointer); + } + + [Fact] + public void Resolve_ViaAFacetThatResolvesToo_Fails() + { + var lookup = Lookup() with + { + Resolve = new() + { + Via = new() { Key = "model", Value = "x" }, + Query = "q", + Read = "r", + }, + }; + + var result = ConfigurationValidator.EvaluateStructure(Filterable(lookup, Model(Via("lookup")))); + + Assert.Contains(result.Errors, e => e.Pointer == Pointer + "/via/key"); + } + + [Theory] + [InlineData("value", "/via/value")] + [InlineData("query", "/query")] + [InlineData("read", "/read")] + public void Resolve_ABlankPart_Fails(string blank, string suffix) + { + var resolve = Via("lookup") with + { + Via = new() { Key = "lookup", Value = blank == "value" ? " " : "model-numbers" }, + Query = blank == "query" ? " " : " model number", + Read = blank == "read" ? " " : "the Tag column", + }; + + var result = ConfigurationValidator.EvaluateStructure(Filterable(Lookup(), Model(resolve))); + + var error = Assert.Single(result.Errors); + Assert.Equal(Pointer + suffix, error.Pointer); + } + + private static KnowledgeFacetResolveConfiguration Via(string key) => new() + { + Via = new() { Key = key, Value = "model-numbers" }, + Query = " model number", + Read = "the Tag column of the row for the person's year", + }; + + private static KnowledgeFilterableFacetConfiguration Lookup() => + new() { Key = "lookup", Description = "The only value is model-numbers." }; + + private static KnowledgeFilterableFacetConfiguration Model(KnowledgeFacetResolveConfiguration resolve) => + new() { Key = "model", Description = "One machine and its year, as one tag.", Resolve = resolve }; + + private static AgentCoreConfiguration Filterable(params KnowledgeFilterableFacetConfiguration[] facets) => new() + { + ApiVersion = "agentcore/v1", + Name = "doc", + Providers = new() + { + Knowledge = new() + { + Kind = "qdrant", + Collection = "kb", + Fields = new() { Body = "text" }, + Scope = new() { Template = "facets.{key}", Filterable = facets }, + }, + }, + }; +} diff --git a/tests/AgentCore.Application.Tests/Knowledge/FacetFilterTests.cs b/tests/AgentCore.Application.Tests/Knowledge/FacetFilterTests.cs index 39b5f73c..82352a69 100644 --- a/tests/AgentCore.Application.Tests/Knowledge/FacetFilterTests.cs +++ b/tests/AgentCore.Application.Tests/Knowledge/FacetFilterTests.cs @@ -69,6 +69,61 @@ public async Task ToolMode_FilterableDeclared_TellsTheModelWhatEachKeyMeans() Assert.Contains("section: Which part of the manual.", wording, StringComparison.Ordinal); } + [Fact] + public async Task ToolMode_FacetWithResolve_TellsTheModelHowToFindTheValue() + { + KnowledgeScopeConfiguration scope = new() + { + Template = "facets.{key}", + Filterable = + [ + new() { Key = "lookup", Description = "The only value is model-numbers." }, + new() + { + Key = "model", + Description = "The machine and the year, as one tag.", + Resolve = new() + { + Via = new() { Key = "lookup", Value = "model-numbers" }, + Query = " model number", + Read = "the Tag column of the row for the person's year", + }, + }, + ], + }; + + var tool = await SearchToolAsync(new StubKnowledgePort([]), scope); + + var wording = tool.JsonSchema + .GetProperty("properties").GetProperty("filters") + .GetProperty("description") + .GetString(); + + Assert.Contains( + "model: The machine and the year, as one tag. To find the value: search once for " + + "\" model number\" with filters [{key: lookup, value: model-numbers}], and read " + + "the Tag column of the row for the person's year. Copy it exactly; never build one.", + wording, + StringComparison.Ordinal); + } + + [Fact] + public async Task ToolMode_FilterableDeclared_SaysTheValueIsMatchedExactly() + { + var tool = await SearchToolAsync(new StubKnowledgePort([]), Declared); + + var wording = tool.JsonSchema + .GetProperty("properties").GetProperty("filters") + .GetProperty("items").GetProperty("properties").GetProperty("value") + .GetProperty("description") + .GetString(); + + Assert.Equal( + "The value, exactly as the cards store it; it is matched exactly. A key that says how to " + + "find its value must be found that way first.", + wording); + } + [Fact] public async Task Filters_NarrowTheScopeTheStoreSees() {