| | | 1 | | using Intentum.AI.Embeddings; |
| | | 2 | | |
| | | 3 | | namespace Intentum.AI.Catalog; |
| | | 4 | | |
| | | 5 | | /// <summary> |
| | | 6 | | /// Registry of known intent definitions with their reference embeddings. |
| | | 7 | | /// Used by CatalogIntentClassifier to perform nearest-neighbor intent classification. |
| | | 8 | | /// </summary> |
| | | 9 | | public sealed class IntentCatalog |
| | | 10 | | { |
| | 15 | 11 | | private readonly List<IntentDefinition> _definitions = []; |
| | 15 | 12 | | private readonly Dictionary<string, IReadOnlyList<double>> _resolvedEmbeddings = new(StringComparer.OrdinalIgnoreCas |
| | | 13 | | |
| | 8 | 14 | | public IReadOnlyList<IntentDefinition> Definitions => _definitions; |
| | | 15 | | |
| | | 16 | | /// <summary> |
| | | 17 | | /// Adds an intent definition to the catalog. |
| | | 18 | | /// </summary> |
| | | 19 | | public IntentCatalog Add(IntentDefinition definition) |
| | 4 | 20 | | { |
| | 4 | 21 | | _definitions.Add(definition ?? throw new ArgumentNullException(nameof(definition))); |
| | 3 | 22 | | return this; |
| | 3 | 23 | | } |
| | | 24 | | |
| | | 25 | | /// <summary> |
| | | 26 | | /// Adds an intent definition using a fluent builder pattern. |
| | | 27 | | /// </summary> |
| | | 28 | | public IntentCatalog Define(string name, string description, params string[] exampleBehaviorKeys) |
| | 14 | 29 | | { |
| | 14 | 30 | | _definitions.Add(new IntentDefinition(name, description, exampleBehaviorKeys)); |
| | 14 | 31 | | return this; |
| | 14 | 32 | | } |
| | | 33 | | |
| | | 34 | | /// <summary> |
| | | 35 | | /// Resolves reference embeddings for all definitions using the given provider. |
| | | 36 | | /// For each definition, the embedding is computed by averaging the embeddings of all example behavior keys. |
| | | 37 | | /// </summary> |
| | | 38 | | public async Task ResolveEmbeddingsAsync( |
| | | 39 | | IIntentEmbeddingProvider provider, |
| | | 40 | | CancellationToken cancellationToken = default) |
| | 8 | 41 | | { |
| | 8 | 42 | | _resolvedEmbeddings.Clear(); |
| | | 43 | | |
| | 46 | 44 | | foreach (var definition in _definitions) |
| | 11 | 45 | | { |
| | 11 | 46 | | if (definition.ReferenceEmbedding is { Count: > 0 }) |
| | 2 | 47 | | { |
| | 2 | 48 | | _resolvedEmbeddings[definition.Name] = definition.ReferenceEmbedding; |
| | 2 | 49 | | continue; |
| | | 50 | | } |
| | | 51 | | |
| | 9 | 52 | | if (definition.ExampleBehaviorKeys.Count == 0) |
| | 1 | 53 | | continue; |
| | | 54 | | |
| | 8 | 55 | | var embeddings = new List<IReadOnlyList<double>>(); |
| | 40 | 56 | | foreach (var key in definition.ExampleBehaviorKeys) |
| | 8 | 57 | | { |
| | 8 | 58 | | var result = await provider.EmbedAsync(key, cancellationToken); |
| | 8 | 59 | | if (result.Vector is { Count: > 0 }) |
| | 8 | 60 | | embeddings.Add(result.Vector); |
| | 8 | 61 | | } |
| | | 62 | | |
| | 8 | 63 | | if (embeddings.Count > 0) |
| | 8 | 64 | | _resolvedEmbeddings[definition.Name] = AverageVectors(embeddings); |
| | 8 | 65 | | } |
| | 8 | 66 | | } |
| | | 67 | | |
| | | 68 | | /// <summary> |
| | | 69 | | /// Gets the resolved embedding for a definition by name, or null if not resolved. |
| | | 70 | | /// </summary> |
| | | 71 | | public IReadOnlyList<double>? GetEmbedding(string intentName) |
| | 7 | 72 | | => _resolvedEmbeddings.TryGetValue(intentName, out var embedding) ? embedding : null; |
| | | 73 | | |
| | | 74 | | /// <summary> |
| | | 75 | | /// Finds the best matching intent by comparing a behavior embedding against all catalog entries. |
| | | 76 | | /// Returns the best match name and cosine similarity score, or null if no match found. |
| | | 77 | | /// </summary> |
| | | 78 | | public (string Name, double Score)? FindBestMatch(IReadOnlyList<double> behaviorEmbedding) |
| | 6 | 79 | | { |
| | 6 | 80 | | if (behaviorEmbedding.Count == 0 || _resolvedEmbeddings.Count == 0) |
| | 2 | 81 | | return null; |
| | | 82 | | |
| | 4 | 83 | | string? bestName = null; |
| | 4 | 84 | | var bestScore = -1.0; |
| | | 85 | | |
| | 24 | 86 | | foreach (var (name, refEmbedding) in _resolvedEmbeddings) |
| | 6 | 87 | | { |
| | 6 | 88 | | var score = EmbeddingScore.CosineSimilarity(behaviorEmbedding, refEmbedding); |
| | 6 | 89 | | if (score > bestScore) |
| | 4 | 90 | | { |
| | 4 | 91 | | bestScore = score; |
| | 4 | 92 | | bestName = name; |
| | 4 | 93 | | } |
| | 6 | 94 | | } |
| | | 95 | | |
| | 4 | 96 | | return bestName != null ? (bestName, bestScore) : null; |
| | 6 | 97 | | } |
| | | 98 | | |
| | | 99 | | private static double[] AverageVectors(List<IReadOnlyList<double>> vectors) |
| | 8 | 100 | | { |
| | 8 | 101 | | var dim = vectors[0].Count; |
| | 8 | 102 | | var avg = new double[dim]; |
| | | 103 | | |
| | 40 | 104 | | foreach (var vec in vectors) |
| | 8 | 105 | | { |
| | 144 | 106 | | for (var i = 0; i < Math.Min(dim, vec.Count); i++) |
| | 64 | 107 | | avg[i] += vec[i]; |
| | 8 | 108 | | } |
| | | 109 | | |
| | 144 | 110 | | for (var i = 0; i < dim; i++) |
| | 64 | 111 | | avg[i] /= vectors.Count; |
| | | 112 | | |
| | 8 | 113 | | return avg; |
| | 8 | 114 | | } |
| | | 115 | | } |