Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions demo/AgentCore.Demo/config/example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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: "<product> 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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,42 @@ public sealed record KnowledgeFilterableFacetConfiguration

/// <summary>Gets what this facet means, in the words the model reads before it picks a value.</summary>
public required string Description { get; init; }

/// <summary>
/// Gets how the model finds an exact value for this facet, or <see langword="null"/> when the
/// description alone is enough to pick one.
/// </summary>
public KnowledgeFacetResolveConfiguration? Resolve { get; init; }
}

/// <summary>
/// The lookup that turns what the person said into the one value a facet is stored under.
/// </summary>
/// <remarks>
/// 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.
/// </remarks>
public sealed record KnowledgeFacetResolveConfiguration
{
/// <summary>Gets the facet and value that narrow the lookup search to the index cards.</summary>
public required KnowledgeFacetValueConfiguration Via { get; init; }

/// <summary>Gets what the model searches for, with placeholders in angle brackets for what the person said.</summary>
public required string Query { get; init; }

/// <summary>Gets where on the card the value is, in the words the model reads.</summary>
public required string Read { get; init; }
}

/// <summary>One facet key and the value it must carry.</summary>
public sealed record KnowledgeFacetValueConfiguration
{
/// <summary>Gets the facet key.</summary>
public required string Key { get; init; }

/// <summary>Gets the value the cards must carry.</summary>
public required string Value { get; init; }
}

/// <summary>Which facets a card may opt out of, and the value it opts out with.</summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 \"<product> 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\"."
}
}
}
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,73 @@ internal static void Check(KnowledgeScopeConfiguration? scope, List<Configuratio
+ "the model reads before it picks a value, so a facet without one is a key it "
+ "can only guess at."));
}

if (facet.Resolve is { } resolve)
{
CheckResolve(facet, resolve, filterable, ConfigurationError.AppendPointer(pointer, "resolve"), errors);
}
}
}

/// <summary>
/// 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.
/// </summary>
private static void CheckResolve(
KnowledgeFilterableFacetConfiguration facet,
KnowledgeFacetResolveConfiguration resolve,
IReadOnlyList<KnowledgeFilterableFacetConfiguration> filterable,
string pointer,
List<ConfigurationError> 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."));
}
}

Expand Down
14 changes: 12 additions & 2 deletions src/AgentCore.Application/Knowledge/FacetFilterSchema.cs
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@ private static JsonObject Argument(IReadOnlyList<KnowledgeFilterableFacetConfigu
{
["type"] = "string",
["description"] =
"The value the cards must carry, as the collection stores it. Write what "
+ "the person said and it will be matched against the stored values.",
"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.",
},
},
["required"] = new JsonArray(KeyProperty, ValueProperty),
Expand All @@ -89,8 +89,18 @@ private static string Wording(IReadOnlyList<KnowledgeFilterableFacetConfiguratio
foreach (var facet in facets)
{
wording.Append("\n- ").Append(facet.Key).Append(": ").Append(facet.Description);

if (facet.Resolve is { } resolve)
{
wording.Append(' ').Append(Recipe(resolve));
}
}

return wording.ToString();
}

private static string Recipe(KnowledgeFacetResolveConfiguration resolve)
=> $"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.";
}
30 changes: 30 additions & 0 deletions src/AgentCore.Application/PublicAPI.Unshipped.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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.<Clone>$() -> 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.<Clone>$() -> 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.<Clone>$() -> AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration!
AgentCore.Application.Configuration.Schema.KnowledgeFieldsConfiguration.Authority.get -> string?
Expand All @@ -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
Expand Down Expand Up @@ -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!
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading