| | | 1 | | namespace Intentum.Core.Behavior; |
| | | 2 | | |
| | | 3 | | /// <summary> |
| | | 4 | | /// Observed behavior space; replaces scenario-based tests. |
| | | 5 | | /// </summary> |
| | | 6 | | public sealed class BehaviorSpace |
| | | 7 | | { |
| | 350 | 8 | | private readonly List<BehaviorEvent> _events = []; |
| | 350 | 9 | | private readonly Dictionary<string, object> _metadata = new(); |
| | 350 | 10 | | private readonly Dictionary<string, BehaviorVector> _cachedVectors = new(); |
| | | 11 | | |
| | | 12 | | /// <summary>All observed behavior events in order.</summary> |
| | 363 | 13 | | public IReadOnlyCollection<BehaviorEvent> Events => _events; |
| | | 14 | | |
| | | 15 | | /// <summary>Metadata associated with this behavior space (e.g., sector, domain, session ID).</summary> |
| | 47 | 16 | | public IReadOnlyDictionary<string, object> Metadata => _metadata; |
| | | 17 | | |
| | | 18 | | /// <summary>Records a single behavior event (actor and action). Invalidates all cached vectors.</summary> |
| | | 19 | | public void Observe(BehaviorEvent behaviorEvent) |
| | 638 | 20 | | { |
| | 638 | 21 | | _cachedVectors.Clear(); |
| | 638 | 22 | | _events.Add(behaviorEvent); |
| | 638 | 23 | | } |
| | | 24 | | |
| | | 25 | | /// <summary>Sets metadata for this behavior space.</summary> |
| | | 26 | | public void SetMetadata(string key, object value) |
| | 29 | 27 | | => _metadata[key] = value; |
| | | 28 | | |
| | | 29 | | /// <summary>Gets metadata value by key.</summary> |
| | | 30 | | public T? GetMetadata<T>(string key) |
| | 52 | 31 | | => _metadata.TryGetValue(key, out var value) && value is T typed ? typed : default; |
| | | 32 | | |
| | | 33 | | /// <summary>Gets events within a time window.</summary> |
| | | 34 | | public IReadOnlyCollection<BehaviorEvent> GetEventsInWindow(DateTimeOffset start, DateTimeOffset end) |
| | 9 | 35 | | { |
| | 9 | 36 | | return _events |
| | 21 | 37 | | .Where(e => e.OccurredAt >= start && e.OccurredAt <= end) |
| | 9 | 38 | | .ToList(); |
| | 9 | 39 | | } |
| | | 40 | | |
| | | 41 | | /// <summary>Gets events within a time window relative to now.</summary> |
| | | 42 | | public IReadOnlyCollection<BehaviorEvent> GetEventsInWindow(TimeSpan window) |
| | 1 | 43 | | { |
| | 1 | 44 | | var end = DateTimeOffset.UtcNow; |
| | 1 | 45 | | var start = end - window; |
| | 1 | 46 | | return GetEventsInWindow(start, end); |
| | 1 | 47 | | } |
| | | 48 | | |
| | | 49 | | /// <summary>Gets the time span of all events.</summary> |
| | | 50 | | public TimeSpan? GetTimeSpan() |
| | 2 | 51 | | { |
| | 2 | 52 | | if (_events.Count == 0) |
| | 1 | 53 | | return null; |
| | | 54 | | |
| | 3 | 55 | | var earliest = _events.Min(e => e.OccurredAt); |
| | 3 | 56 | | var latest = _events.Max(e => e.OccurredAt); |
| | 1 | 57 | | return latest - earliest; |
| | 2 | 58 | | } |
| | | 59 | | |
| | | 60 | | /// <summary>Builds a behavior vector from observed events (actor:action keys with counts). Result is cached until O |
| | | 61 | | public BehaviorVector ToVector() |
| | 15 | 62 | | => ToVector(null); |
| | | 63 | | |
| | | 64 | | /// <summary>Builds a behavior vector with optional normalization/cap. Result is cached based on options hash.</summ |
| | | 65 | | public BehaviorVector ToVector(ToVectorOptions? options) |
| | 128 | 66 | | { |
| | 128 | 67 | | var cacheKey = GetCacheKey(options); |
| | | 68 | | |
| | 128 | 69 | | if (_cachedVectors.TryGetValue(cacheKey, out var cached)) |
| | 11 | 70 | | return cached; |
| | | 71 | | |
| | 117 | 72 | | var dimensions = new Dictionary<string, double>(); |
| | | 73 | | |
| | 945 | 74 | | foreach (var evt in _events) |
| | 297 | 75 | | { |
| | 297 | 76 | | var key = $"{evt.Actor}:{evt.Action}"; |
| | 297 | 77 | | dimensions[key] = dimensions.GetValueOrDefault(key) + 1; |
| | 297 | 78 | | } |
| | | 79 | | |
| | 117 | 80 | | dimensions = ApplyOptions(dimensions, options); |
| | 117 | 81 | | var result = new BehaviorVector(dimensions); |
| | 117 | 82 | | _cachedVectors[cacheKey] = result; |
| | 117 | 83 | | return result; |
| | 128 | 84 | | } |
| | | 85 | | |
| | | 86 | | /// <summary>Builds a behavior vector from events within a time window.</summary> |
| | | 87 | | public BehaviorVector ToVector(DateTimeOffset start, DateTimeOffset end) |
| | 1 | 88 | | => ToVector(start, end, null); |
| | | 89 | | |
| | | 90 | | /// <summary>Builds a behavior vector from events within a time window with optional normalization.</summary> |
| | | 91 | | public BehaviorVector ToVector(DateTimeOffset start, DateTimeOffset end, ToVectorOptions? options) |
| | 2 | 92 | | { |
| | 2 | 93 | | var dimensions = new Dictionary<string, double>(); |
| | 2 | 94 | | var eventsInWindow = GetEventsInWindow(start, end); |
| | | 95 | | |
| | 14 | 96 | | foreach (var evt in eventsInWindow) |
| | 4 | 97 | | { |
| | 4 | 98 | | var key = $"{evt.Actor}:{evt.Action}"; |
| | 4 | 99 | | dimensions[key] = dimensions.GetValueOrDefault(key) + 1; |
| | 4 | 100 | | } |
| | | 101 | | |
| | 2 | 102 | | dimensions = ApplyOptions(dimensions, options); |
| | 2 | 103 | | return new BehaviorVector(dimensions); |
| | 2 | 104 | | } |
| | | 105 | | |
| | | 106 | | private static string GetCacheKey(ToVectorOptions? options) |
| | 128 | 107 | | { |
| | 249 | 108 | | if (options == null) return "default"; |
| | 7 | 109 | | return $"{options.Normalization}_{options.CapPerDimension}"; |
| | 128 | 110 | | } |
| | | 111 | | |
| | | 112 | | private static bool UseCache(ToVectorOptions? options) |
| | 119 | 113 | | => options == null || options is { Normalization: VectorNormalization.None, CapPerDimension: <= 0 }; |
| | | 114 | | |
| | | 115 | | private static Dictionary<string, double> ApplyOptions(Dictionary<string, double> dimensions, ToVectorOptions? optio |
| | 119 | 116 | | { |
| | 119 | 117 | | if (UseCache(options)) |
| | 112 | 118 | | return dimensions; |
| | | 119 | | |
| | 7 | 120 | | var cap = options!.CapPerDimension > 0 ? options.CapPerDimension : (double?)null; |
| | | 121 | | |
| | 7 | 122 | | return options.Normalization switch |
| | 7 | 123 | | { |
| | 4 | 124 | | VectorNormalization.Cap when cap.HasValue => ApplyCap(dimensions, cap.Value), |
| | 2 | 125 | | VectorNormalization.SoftCap when cap.HasValue => ApplySoftCap(dimensions, cap.Value), |
| | 4 | 126 | | VectorNormalization.L1 => ApplyL1(dimensions), |
| | 0 | 127 | | _ when cap.HasValue && options.Normalization == VectorNormalization.None => ApplyCap(dimensions, cap.Value), |
| | 0 | 128 | | _ => dimensions |
| | 7 | 129 | | }; |
| | 119 | 130 | | } |
| | | 131 | | |
| | | 132 | | private static Dictionary<string, double> ApplyCap(Dictionary<string, double> dimensions, double cap) |
| | 2 | 133 | | { |
| | 12 | 134 | | foreach (var k in dimensions.Keys.ToList()) |
| | 3 | 135 | | { |
| | 3 | 136 | | if (dimensions[k] > cap) |
| | 1 | 137 | | dimensions[k] = cap; |
| | 3 | 138 | | } |
| | 2 | 139 | | return dimensions; |
| | 2 | 140 | | } |
| | | 141 | | |
| | | 142 | | private static Dictionary<string, double> ApplySoftCap(Dictionary<string, double> dimensions, double cap) |
| | 1 | 143 | | { |
| | 7 | 144 | | foreach (var k in dimensions.Keys.ToList()) |
| | 2 | 145 | | dimensions[k] = Math.Min(1.0, dimensions[k] / cap); |
| | 1 | 146 | | return dimensions; |
| | 1 | 147 | | } |
| | | 148 | | |
| | | 149 | | private static Dictionary<string, double> ApplyL1(Dictionary<string, double> dimensions) |
| | 4 | 150 | | { |
| | 4 | 151 | | var sum = dimensions.Values.Sum(); |
| | 4 | 152 | | if (sum <= 0) |
| | 0 | 153 | | return dimensions; |
| | 24 | 154 | | foreach (var k in dimensions.Keys.ToList()) |
| | 6 | 155 | | dimensions[k] /= sum; |
| | 4 | 156 | | return dimensions; |
| | 4 | 157 | | } |
| | | 158 | | } |