pendingExtraction(String bufferKey, Message message) {
+ recentConversationBuffer.append(bufferKey, message);
+ if (message.role() == Message.Role.ASSISTANT) {
+ appendToPendingBuffer(bufferKey, message);
+ return Optional.empty();
+ }
+
+ var snapshot = pendingConversationBuffer.load(bufferKey);
+ if (snapshot.isEmpty()) {
+ appendToPendingBuffer(bufferKey, message);
+ return Optional.empty();
+ }
+
+ var detectionInput =
+ new CommitDetectionInput(
+ snapshot, List.of(message), CommitDetectionContext.empty());
+ var decision =
+ contextCommitDetector
+ .shouldCommit(detectionInput)
+ .defaultIfEmpty(CommitDecision.hold())
+ .block();
+
+ if (decision == null || !decision.shouldSeal()) {
+ appendToPendingBuffer(bufferKey, message);
+ return Optional.empty();
+ }
+
+ log.debug(
+ "Boundary detection triggered sealing: memoryId={}, reason={}, confidence={}",
+ bufferKey,
+ decision.reason(),
+ decision.confidence());
+
+ var sealedMessages = List.copyOf(snapshot);
+ pendingConversationBuffer.clear(bufferKey);
+ pendingConversationBuffer.append(bufferKey, message);
+
+ return Optional.of(new PendingExtraction(sealedMessages, new HashMap<>()));
}
private void appendToPendingBuffer(String bufferKey, Message message) {
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/MemoryExtractor.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/MemoryExtractor.java
index ce72f54a..5ea6c865 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/MemoryExtractor.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/MemoryExtractor.java
@@ -23,8 +23,8 @@
* Defines the memory extraction contract: batch extraction via {@link #extract(ExtractionRequest)}
* and context single-message extraction via {@link #addMessage(MemoryId, Message, ExtractionConfig)}.
*
- *
The primary implementation is {@link DefaultMemoryExtractor}. Decorators (e.g., tracing) wrap this
- * interface to add cross-cutting concerns.
+ *
The primary implementation is {@link DefaultMemoryExtractor}. Implementations publish observability signals at
+ * the relevant pipeline stages.
*/
public interface MemoryExtractor {
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/InsightLayer.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/InsightLayer.java
index f8df7092..1a535c5b 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/InsightLayer.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/InsightLayer.java
@@ -18,11 +18,13 @@
import com.openmemind.ai.memory.core.data.MemoryItem;
import com.openmemind.ai.memory.core.data.enums.InsightAnalysisMode;
import com.openmemind.ai.memory.core.data.enums.MemoryItemType;
+import com.openmemind.ai.memory.core.extraction.insight.observation.InsightLayerObservation;
import com.openmemind.ai.memory.core.extraction.insight.scheduler.InsightBuildScheduler;
import com.openmemind.ai.memory.core.extraction.result.InsightResult;
import com.openmemind.ai.memory.core.extraction.result.MemoryItemResult;
import com.openmemind.ai.memory.core.extraction.step.InsightExtractStep;
import com.openmemind.ai.memory.core.store.MemoryStore;
+import io.micrometer.observation.ObservationRegistry;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
@@ -48,11 +50,19 @@ public class InsightLayer implements InsightExtractStep {
private final MemoryStore memoryStore;
private final InsightBuildScheduler scheduler;
private final Set unsupportedContentTypes;
+ private final ObservationRegistry observationRegistry;
public InsightLayer(MemoryStore memoryStore, InsightBuildScheduler scheduler) {
this(memoryStore, scheduler, Set.of());
}
+ public InsightLayer(
+ MemoryStore memoryStore,
+ InsightBuildScheduler scheduler,
+ ObservationRegistry observationRegistry) {
+ this(memoryStore, scheduler, Set.of(), observationRegistry);
+ }
+
/**
* @param memoryStore memory store
* @param scheduler insight build scheduler
@@ -63,10 +73,20 @@ public InsightLayer(
MemoryStore memoryStore,
InsightBuildScheduler scheduler,
Set unsupportedContentTypes) {
+ this(memoryStore, scheduler, unsupportedContentTypes, ObservationRegistry.NOOP);
+ }
+
+ public InsightLayer(
+ MemoryStore memoryStore,
+ InsightBuildScheduler scheduler,
+ Set unsupportedContentTypes,
+ ObservationRegistry observationRegistry) {
this.memoryStore = Objects.requireNonNull(memoryStore);
this.scheduler = Objects.requireNonNull(scheduler);
this.unsupportedContentTypes =
unsupportedContentTypes != null ? Set.copyOf(unsupportedContentTypes) : Set.of();
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
@@ -77,6 +97,14 @@ public Mono extract(MemoryId memoryId, MemoryItemResult memoryIte
@Override
public Mono extract(
MemoryId memoryId, MemoryItemResult memoryItemResult, String language) {
+ return InsightLayerObservation.observe(
+ observationRegistry,
+ memoryId,
+ () -> extractInternal(memoryId, memoryItemResult, language));
+ }
+
+ private Mono extractInternal(
+ MemoryId memoryId, MemoryItemResult memoryItemResult, String language) {
// Only take FACT type items whose content type supports insight building
var factItems =
memoryItemResult.newItems().stream()
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/generator/LlmInsightGenerator.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/generator/LlmInsightGenerator.java
index 6dce10b3..9c4fe2fd 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/generator/LlmInsightGenerator.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/generator/LlmInsightGenerator.java
@@ -17,6 +17,8 @@
import com.openmemind.ai.memory.core.data.MemoryInsight;
import com.openmemind.ai.memory.core.data.MemoryInsightType;
import com.openmemind.ai.memory.core.data.MemoryItem;
+import com.openmemind.ai.memory.core.extraction.insight.generator.observation.LlmInsightGeneratorObservation;
+import com.openmemind.ai.memory.core.extraction.insight.generator.observation.LlmInsightGeneratorObservation.InsightGenerateDocument;
import com.openmemind.ai.memory.core.llm.ChatMessages;
import com.openmemind.ai.memory.core.llm.StructuredChatClient;
import com.openmemind.ai.memory.core.prompt.PromptRegistry;
@@ -24,6 +26,7 @@
import com.openmemind.ai.memory.core.prompt.extraction.insight.InsightLeafPrompts;
import com.openmemind.ai.memory.core.prompt.extraction.insight.InteractionGuideSynthesisPrompts;
import com.openmemind.ai.memory.core.prompt.extraction.insight.RootSynthesisPrompts;
+import io.micrometer.observation.ObservationRegistry;
import java.time.Duration;
import java.util.List;
import java.util.Objects;
@@ -45,18 +48,33 @@ public class LlmInsightGenerator implements InsightGenerator {
private final StructuredChatClient structuredChatClient;
private final PromptRegistry promptRegistry;
+ private final ObservationRegistry observationRegistry;
public LlmInsightGenerator(StructuredChatClient structuredChatClient) {
this(structuredChatClient, PromptRegistry.EMPTY);
}
+ public LlmInsightGenerator(
+ StructuredChatClient structuredChatClient, ObservationRegistry observationRegistry) {
+ this(structuredChatClient, PromptRegistry.EMPTY, observationRegistry);
+ }
+
public LlmInsightGenerator(
StructuredChatClient structuredChatClient, PromptRegistry promptRegistry) {
+ this(structuredChatClient, promptRegistry, ObservationRegistry.NOOP);
+ }
+
+ public LlmInsightGenerator(
+ StructuredChatClient structuredChatClient,
+ PromptRegistry promptRegistry,
+ ObservationRegistry observationRegistry) {
this.structuredChatClient =
Objects.requireNonNull(
structuredChatClient, "structuredChatClient must not be null");
this.promptRegistry =
Objects.requireNonNull(promptRegistry, "promptRegistry must not be null");
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
@@ -68,6 +86,29 @@ public Mono generatePoints(
int targetTokens,
String additionalContext,
String language) {
+ return LlmInsightGeneratorObservation.observeLeafPointGeneration(
+ observationRegistry,
+ insightType,
+ groupName,
+ () ->
+ generatePointsInternal(
+ insightType,
+ groupName,
+ existingPoints,
+ newItems,
+ targetTokens,
+ additionalContext,
+ language));
+ }
+
+ private Mono generatePointsInternal(
+ MemoryInsightType insightType,
+ String groupName,
+ List existingPoints,
+ List newItems,
+ int targetTokens,
+ String additionalContext,
+ String language) {
var template =
InsightLeafPrompts.build(
@@ -109,6 +150,29 @@ public Mono generateLeafPointOps(
int targetTokens,
String additionalContext,
String language) {
+ return LlmInsightGeneratorObservation.observeLeafPointOperations(
+ observationRegistry,
+ insightType,
+ groupName,
+ () ->
+ generateLeafPointOpsInternal(
+ insightType,
+ groupName,
+ existingPoints,
+ newItems,
+ targetTokens,
+ additionalContext,
+ language));
+ }
+
+ private Mono generateLeafPointOpsInternal(
+ MemoryInsightType insightType,
+ String groupName,
+ List existingPoints,
+ List newItems,
+ int targetTokens,
+ String additionalContext,
+ String language) {
var template =
InsightLeafPrompts.buildPointOps(
@@ -160,6 +224,28 @@ public Mono generateBranchSummary(
int targetTokens,
String additionalContext,
String language) {
+ return LlmInsightGeneratorObservation.observeAggregatePointGeneration(
+ observationRegistry,
+ InsightGenerateDocument.BRANCH,
+ insightType,
+ leafInsights,
+ () ->
+ generateBranchSummaryInternal(
+ insightType,
+ existingPoints,
+ leafInsights,
+ targetTokens,
+ additionalContext,
+ language));
+ }
+
+ private Mono generateBranchSummaryInternal(
+ MemoryInsightType insightType,
+ List existingPoints,
+ List leafInsights,
+ int targetTokens,
+ String additionalContext,
+ String language) {
var promptResult =
BranchAggregationPrompts.build(
@@ -209,6 +295,28 @@ public Mono generateBranchPointOps(
int targetTokens,
String additionalContext,
String language) {
+ return LlmInsightGeneratorObservation.observeAggregatePointOperations(
+ observationRegistry,
+ InsightGenerateDocument.BRANCH,
+ insightType,
+ leafInsights,
+ () ->
+ generateBranchPointOpsInternal(
+ insightType,
+ existingPoints,
+ leafInsights,
+ targetTokens,
+ additionalContext,
+ language));
+ }
+
+ private Mono generateBranchPointOpsInternal(
+ MemoryInsightType insightType,
+ List existingPoints,
+ List leafInsights,
+ int targetTokens,
+ String additionalContext,
+ String language) {
var promptResult =
BranchAggregationPrompts.buildPointOps(
@@ -258,6 +366,28 @@ public Mono generateRootSynthesis(
int targetTokens,
String additionalContext,
String language) {
+ return LlmInsightGeneratorObservation.observeAggregatePointGeneration(
+ observationRegistry,
+ InsightGenerateDocument.ROOT,
+ rootInsightType,
+ branchInsights,
+ () ->
+ generateRootSynthesisInternal(
+ rootInsightType,
+ existingPoints,
+ branchInsights,
+ targetTokens,
+ additionalContext,
+ language));
+ }
+
+ private Mono generateRootSynthesisInternal(
+ MemoryInsightType rootInsightType,
+ List existingPoints,
+ List branchInsights,
+ int targetTokens,
+ String additionalContext,
+ String language) {
var template =
switch (rootInsightType.name()) {
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/generator/observation/LlmInsightGeneratorObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/generator/observation/LlmInsightGeneratorObservation.java
new file mode 100644
index 00000000..970b5caf
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/generator/observation/LlmInsightGeneratorObservation.java
@@ -0,0 +1,390 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.insight.generator.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryInsight;
+import com.openmemind.ai.memory.core.data.MemoryInsightType;
+import com.openmemind.ai.memory.core.data.PointOperation;
+import com.openmemind.ai.memory.core.extraction.insight.generator.InsightPointGenerateResponse;
+import com.openmemind.ai.memory.core.extraction.insight.generator.InsightPointOpsResponse;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.List;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for LlmInsightGenerator. */
+public final class LlmInsightGeneratorObservation {
+
+ private LlmInsightGeneratorObservation() {}
+
+ public static Mono observeLeafPointGeneration(
+ ObservationRegistry observationRegistry,
+ MemoryInsightType insightType,
+ String groupName,
+ Supplier> operation) {
+ return observeLeafPointGeneration(
+ observationRegistry, insightType, groupName, ignored -> operation.get());
+ }
+
+ public static Mono observeLeafPointGeneration(
+ ObservationRegistry observationRegistry,
+ MemoryInsightType insightType,
+ String groupName,
+ Function>
+ operation) {
+ return observePointGeneration(
+ observationRegistry,
+ InsightGenerateDocument.LEAF,
+ () -> InsightGenerateObservationContext.leaf(insightType, groupName),
+ operation);
+ }
+
+ public static Mono observeLeafPointOperations(
+ ObservationRegistry observationRegistry,
+ MemoryInsightType insightType,
+ String groupName,
+ Supplier> operation) {
+ return observeLeafPointOperations(
+ observationRegistry, insightType, groupName, ignored -> operation.get());
+ }
+
+ public static Mono observeLeafPointOperations(
+ ObservationRegistry observationRegistry,
+ MemoryInsightType insightType,
+ String groupName,
+ Function> operation) {
+ return observePointOperations(
+ observationRegistry,
+ InsightGenerateDocument.LEAF,
+ () -> InsightGenerateObservationContext.leaf(insightType, groupName),
+ operation);
+ }
+
+ public static Mono observeAggregatePointGeneration(
+ ObservationRegistry observationRegistry,
+ InsightGenerateDocument document,
+ MemoryInsightType insightType,
+ List insights,
+ Supplier> operation) {
+ return observeAggregatePointGeneration(
+ observationRegistry, document, insightType, insights, ignored -> operation.get());
+ }
+
+ public static Mono observeAggregatePointGeneration(
+ ObservationRegistry observationRegistry,
+ InsightGenerateDocument document,
+ MemoryInsightType insightType,
+ List insights,
+ Function>
+ operation) {
+ return observePointGeneration(
+ observationRegistry,
+ document,
+ () -> InsightGenerateObservationContext.aggregate(document, insightType, insights),
+ operation);
+ }
+
+ public static Mono observeAggregatePointOperations(
+ ObservationRegistry observationRegistry,
+ InsightGenerateDocument document,
+ MemoryInsightType insightType,
+ List insights,
+ Supplier> operation) {
+ return observeAggregatePointOperations(
+ observationRegistry, document, insightType, insights, ignored -> operation.get());
+ }
+
+ public static Mono observeAggregatePointOperations(
+ ObservationRegistry observationRegistry,
+ InsightGenerateDocument document,
+ MemoryInsightType insightType,
+ List insights,
+ Function> operation) {
+ return observePointOperations(
+ observationRegistry,
+ document,
+ () -> InsightGenerateObservationContext.aggregate(document, insightType, insights),
+ operation);
+ }
+
+ private static Mono observePointGeneration(
+ ObservationRegistry observationRegistry,
+ InsightGenerateDocument document,
+ Supplier contextFactory,
+ Function>
+ operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ document,
+ InsightGenerateConvention.of(document),
+ contextFactory,
+ context -> operation.apply(context).doOnNext(context::recordPointResponse));
+ }
+
+ private static Mono observePointOperations(
+ ObservationRegistry observationRegistry,
+ InsightGenerateDocument document,
+ Supplier contextFactory,
+ Function> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ document,
+ InsightGenerateConvention.of(document),
+ contextFactory,
+ context -> operation.apply(context).doOnNext(context::recordOpsResponse));
+ }
+
+ public enum InsightGenerateDocument implements ObservationDocumentation {
+ LEAF("memind.extraction.insight.generate.leaf"),
+ BRANCH("memind.extraction.insight.generate.branch"),
+ ROOT("memind.extraction.insight.generate.root");
+
+ private final String name;
+
+ InsightGenerateDocument(String name) {
+ this.name = name;
+ }
+
+ @Override
+ public String getName() {
+ return name;
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return InsightGenerateConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return switch (this) {
+ case LEAF ->
+ new KeyName[] {
+ HighCardinalityKeyNames.INSIGHT_TYPE,
+ HighCardinalityKeyNames.GROUP_NAME,
+ HighCardinalityKeyNames.POINT_COUNT,
+ HighCardinalityKeyNames.ADD_COUNT,
+ HighCardinalityKeyNames.UPDATE_COUNT,
+ HighCardinalityKeyNames.DELETE_COUNT
+ };
+ case BRANCH ->
+ new KeyName[] {
+ HighCardinalityKeyNames.INSIGHT_TYPE,
+ HighCardinalityKeyNames.LEAF_COUNT,
+ HighCardinalityKeyNames.POINT_COUNT,
+ HighCardinalityKeyNames.ADD_COUNT,
+ HighCardinalityKeyNames.UPDATE_COUNT,
+ HighCardinalityKeyNames.DELETE_COUNT
+ };
+ case ROOT ->
+ new KeyName[] {
+ HighCardinalityKeyNames.INSIGHT_TYPE,
+ HighCardinalityKeyNames.LEAF_COUNT,
+ HighCardinalityKeyNames.POINT_COUNT
+ };
+ };
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ INSIGHT_TYPE {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_type";
+ }
+ },
+ GROUP_NAME {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_group_name";
+ }
+ },
+ LEAF_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_leaf_count";
+ }
+ },
+ POINT_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_point_count";
+ }
+ },
+ ADD_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_add_count";
+ }
+ },
+ UPDATE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_update_count";
+ }
+ },
+ DELETE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_delete_count";
+ }
+ };
+ }
+
+ public static final class InsightGenerateObservationContext extends Observation.Context {
+
+ private final InsightGenerateDocument document;
+ private final String insightTypeName;
+ private final String groupName;
+ private final Integer leafCount;
+ private Integer pointCount;
+ private Integer addCount;
+ private Integer updateCount;
+ private Integer deleteCount;
+
+ public InsightGenerateObservationContext(
+ InsightGenerateDocument document,
+ String insightTypeName,
+ String groupName,
+ Integer leafCount) {
+ this.document = document;
+ this.insightTypeName = insightTypeName;
+ this.groupName = groupName;
+ this.leafCount = leafCount;
+ }
+
+ public static InsightGenerateObservationContext leaf(
+ MemoryInsightType insightType, String groupName) {
+ return new InsightGenerateObservationContext(
+ InsightGenerateDocument.LEAF,
+ insightType == null ? "" : insightType.name(),
+ groupName == null ? "" : groupName,
+ null);
+ }
+
+ public static InsightGenerateObservationContext aggregate(
+ InsightGenerateDocument document,
+ MemoryInsightType insightType,
+ List insights) {
+ return new InsightGenerateObservationContext(
+ document,
+ insightType == null ? "" : insightType.name(),
+ null,
+ insights == null ? 0 : insights.size());
+ }
+
+ public void recordPointResponse(InsightPointGenerateResponse response) {
+ this.pointCount =
+ response == null || response.points() == null ? 0 : response.points().size();
+ }
+
+ public void recordOpsResponse(InsightPointOpsResponse response) {
+ var operations = response == null ? List.of() : response.operations();
+ this.addCount = countOperations(operations, PointOperation.OpType.ADD);
+ this.updateCount = countOperations(operations, PointOperation.OpType.UPDATE);
+ this.deleteCount = countOperations(operations, PointOperation.OpType.DELETE);
+ }
+
+ private static int countOperations(
+ List operations, PointOperation.OpType opType) {
+ return (int) operations.stream().filter(operation -> operation.op() == opType).count();
+ }
+ }
+
+ public static final class InsightGenerateConvention
+ implements ObservationConvention {
+
+ public static final InsightGenerateConvention LEAF =
+ new InsightGenerateConvention(InsightGenerateDocument.LEAF);
+ public static final InsightGenerateConvention BRANCH =
+ new InsightGenerateConvention(InsightGenerateDocument.BRANCH);
+ public static final InsightGenerateConvention ROOT =
+ new InsightGenerateConvention(InsightGenerateDocument.ROOT);
+
+ private final InsightGenerateDocument document;
+
+ public InsightGenerateConvention(InsightGenerateDocument document) {
+ this.document = document;
+ }
+
+ public static InsightGenerateConvention of(InsightGenerateDocument document) {
+ return switch (document) {
+ case LEAF -> LEAF;
+ case BRANCH -> BRANCH;
+ case ROOT -> ROOT;
+ };
+ }
+
+ @Override
+ public String getName() {
+ return document.getName();
+ }
+
+ @Override
+ public String getContextualName(InsightGenerateObservationContext context) {
+ return context.document.getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(InsightGenerateObservationContext context) {
+ var values =
+ KeyValues.of(
+ HighCardinalityKeyNames.INSIGHT_TYPE.withValue(
+ context.insightTypeName));
+ if (context.groupName != null) {
+ values =
+ values.and(HighCardinalityKeyNames.GROUP_NAME.withValue(context.groupName));
+ }
+ if (context.leafCount != null) {
+ values =
+ values.and(
+ HighCardinalityKeyNames.LEAF_COUNT.withValue(
+ String.valueOf(context.leafCount)));
+ }
+ if (context.pointCount != null) {
+ values =
+ values.and(
+ HighCardinalityKeyNames.POINT_COUNT.withValue(
+ String.valueOf(context.pointCount)));
+ }
+ if (context.addCount != null) {
+ values =
+ values.and(
+ HighCardinalityKeyNames.ADD_COUNT.withValue(
+ String.valueOf(context.addCount)))
+ .and(
+ HighCardinalityKeyNames.UPDATE_COUNT.withValue(
+ String.valueOf(context.updateCount)))
+ .and(
+ HighCardinalityKeyNames.DELETE_COUNT.withValue(
+ String.valueOf(context.deleteCount)));
+ }
+ return values;
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof InsightGenerateObservationContext generateContext
+ && generateContext.document == document;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/group/LlmInsightGroupClassifier.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/group/LlmInsightGroupClassifier.java
index c5eb0c86..fb0eea20 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/group/LlmInsightGroupClassifier.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/group/LlmInsightGroupClassifier.java
@@ -15,10 +15,12 @@
import com.openmemind.ai.memory.core.data.MemoryInsightType;
import com.openmemind.ai.memory.core.data.MemoryItem;
+import com.openmemind.ai.memory.core.extraction.insight.group.observation.LlmInsightGroupClassifierObservation;
import com.openmemind.ai.memory.core.llm.ChatMessages;
import com.openmemind.ai.memory.core.llm.StructuredChatClient;
import com.openmemind.ai.memory.core.prompt.PromptRegistry;
import com.openmemind.ai.memory.core.prompt.extraction.insight.InsightGroupPrompts;
+import io.micrometer.observation.ObservationRegistry;
import java.time.Duration;
import java.util.ArrayList;
import java.util.Comparator;
@@ -81,18 +83,33 @@ public class LlmInsightGroupClassifier implements InsightGroupClassifier {
private final StructuredChatClient structuredChatClient;
private final PromptRegistry promptRegistry;
+ private final ObservationRegistry observationRegistry;
public LlmInsightGroupClassifier(StructuredChatClient structuredChatClient) {
this(structuredChatClient, PromptRegistry.EMPTY);
}
+ public LlmInsightGroupClassifier(
+ StructuredChatClient structuredChatClient, ObservationRegistry observationRegistry) {
+ this(structuredChatClient, PromptRegistry.EMPTY, observationRegistry);
+ }
+
public LlmInsightGroupClassifier(
StructuredChatClient structuredChatClient, PromptRegistry promptRegistry) {
+ this(structuredChatClient, promptRegistry, ObservationRegistry.NOOP);
+ }
+
+ public LlmInsightGroupClassifier(
+ StructuredChatClient structuredChatClient,
+ PromptRegistry promptRegistry,
+ ObservationRegistry observationRegistry) {
this.structuredChatClient =
Objects.requireNonNull(
structuredChatClient, "structuredChatClient must not be null");
this.promptRegistry =
Objects.requireNonNull(promptRegistry, "promptRegistry must not be null");
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
@@ -119,6 +136,25 @@ public Mono>> classify(
List existingGroupNames,
String additionalContext,
String language) {
+ return LlmInsightGroupClassifierObservation.observe(
+ observationRegistry,
+ insightType,
+ items,
+ () ->
+ classifyInternal(
+ insightType,
+ items,
+ existingGroupNames,
+ additionalContext,
+ language));
+ }
+
+ private Mono>> classifyInternal(
+ MemoryInsightType insightType,
+ List items,
+ List existingGroupNames,
+ String additionalContext,
+ String language) {
if (items.isEmpty()) {
return Mono.just(Map.of());
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/group/observation/LlmInsightGroupClassifierObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/group/observation/LlmInsightGroupClassifierObservation.java
new file mode 100644
index 00000000..9e4ebe6c
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/group/observation/LlmInsightGroupClassifierObservation.java
@@ -0,0 +1,152 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.insight.group.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryInsightType;
+import com.openmemind.ai.memory.core.data.MemoryItem;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for LlmInsightGroupClassifier. */
+public final class LlmInsightGroupClassifierObservation {
+
+ private LlmInsightGroupClassifierObservation() {}
+
+ public static Mono>> observe(
+ ObservationRegistry observationRegistry,
+ MemoryInsightType insightType,
+ List items,
+ Supplier>>> operation) {
+ return observe(observationRegistry, insightType, items, ignored -> operation.get());
+ }
+
+ public static Mono>> observe(
+ ObservationRegistry observationRegistry,
+ MemoryInsightType insightType,
+ List items,
+ Function>>>
+ operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ GroupClassifyDocument.CLASSIFY,
+ GroupClassifyConvention.INSTANCE,
+ () -> new GroupClassifyObservationContext(insightType, items),
+ context -> operation.apply(context).doOnNext(context::recordResult));
+ }
+
+ public enum GroupClassifyDocument implements ObservationDocumentation {
+ CLASSIFY;
+
+ @Override
+ public String getName() {
+ return "memind.extraction.insight.group.classify";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return GroupClassifyConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ INSIGHT_TYPE {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_type";
+ }
+ },
+ ITEM_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.item_count";
+ }
+ },
+ GROUP_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_group_count";
+ }
+ };
+ }
+
+ public static final class GroupClassifyObservationContext extends Observation.Context {
+
+ private final String insightTypeName;
+ private final int itemCount;
+ private Integer groupCount;
+
+ public GroupClassifyObservationContext(
+ MemoryInsightType insightType, List items) {
+ this.insightTypeName = insightType == null ? "" : insightType.name();
+ this.itemCount = items == null ? 0 : items.size();
+ }
+
+ public void recordResult(Map> result) {
+ this.groupCount = result.size();
+ }
+ }
+
+ public static final class GroupClassifyConvention
+ implements ObservationConvention {
+
+ public static final GroupClassifyConvention INSTANCE = new GroupClassifyConvention();
+
+ @Override
+ public String getName() {
+ return GroupClassifyDocument.CLASSIFY.getName();
+ }
+
+ @Override
+ public String getContextualName(GroupClassifyObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(GroupClassifyObservationContext context) {
+ var values =
+ KeyValues.of(
+ HighCardinalityKeyNames.INSIGHT_TYPE.withValue(context.insightTypeName),
+ HighCardinalityKeyNames.ITEM_COUNT.withValue(
+ String.valueOf(context.itemCount)));
+ if (context.groupCount != null) {
+ values =
+ values.and(
+ HighCardinalityKeyNames.GROUP_COUNT.withValue(
+ String.valueOf(context.groupCount)));
+ }
+ return values;
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof GroupClassifyObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/observation/InsightLayerObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/observation/InsightLayerObservation.java
new file mode 100644
index 00000000..bb64bc32
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/observation/InsightLayerObservation.java
@@ -0,0 +1,117 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.insight.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryId;
+import com.openmemind.ai.memory.core.extraction.result.InsightResult;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for InsightLayer. */
+public final class InsightLayerObservation {
+
+ private InsightLayerObservation() {}
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Supplier> operation) {
+ return observe(observationRegistry, memoryId, ignored -> operation.get());
+ }
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Function> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ InsightDocument.EXTRACT,
+ InsightConvention.INSTANCE,
+ () -> new InsightObservationContext(memoryId),
+ operation);
+ }
+
+ public enum InsightDocument implements ObservationDocumentation {
+ EXTRACT;
+
+ @Override
+ public String getName() {
+ return "memind.extraction.insight";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return InsightConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ MEMORY_ID {
+ @Override
+ public String asString() {
+ return "memind.memory_id";
+ }
+ };
+ }
+
+ public static final class InsightObservationContext extends Observation.Context {
+
+ private final MemoryId memoryId;
+
+ public InsightObservationContext(MemoryId memoryId) {
+ this.memoryId = memoryId;
+ }
+ }
+
+ public static final class InsightConvention
+ implements ObservationConvention {
+
+ public static final InsightConvention INSTANCE = new InsightConvention();
+
+ @Override
+ public String getName() {
+ return InsightDocument.EXTRACT.getName();
+ }
+
+ @Override
+ public String getContextualName(InsightObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(InsightObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(context.memoryId.toIdentifier()));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof InsightObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/reference/InsightReferences.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/reference/InsightReferences.java
index 278044a9..a461629f 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/reference/InsightReferences.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/reference/InsightReferences.java
@@ -21,7 +21,7 @@
* Insight reference parsing tool
*
* Parse and manipulate the {@code [ref:ITEM_ID]} reference tags in the summary,
- * supporting tracing the source item of each summary information.
+ * supporting tracking the source item of each summary information.
*
*/
public final class InsightReferences {
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/scheduler/InsightBuildScheduler.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/scheduler/InsightBuildScheduler.java
index d979aaba..9b63b5b3 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/scheduler/InsightBuildScheduler.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/scheduler/InsightBuildScheduler.java
@@ -31,17 +31,14 @@
import com.openmemind.ai.memory.core.extraction.insight.group.InsightGroupClassifier;
import com.openmemind.ai.memory.core.extraction.insight.group.InsightGroupRouter;
import com.openmemind.ai.memory.core.extraction.insight.operation.PointOperationResolver;
+import com.openmemind.ai.memory.core.extraction.insight.scheduler.observation.InsightBuildSchedulerObservation;
import com.openmemind.ai.memory.core.extraction.insight.support.InsightPointEvidenceNormalizer;
import com.openmemind.ai.memory.core.extraction.insight.support.InsightPointIdentityManager;
import com.openmemind.ai.memory.core.extraction.insight.tree.InsightTreeReorganizer;
import com.openmemind.ai.memory.core.store.MemoryStore;
-import com.openmemind.ai.memory.core.tracing.MemoryAttributes;
-import com.openmemind.ai.memory.core.tracing.MemoryObserver;
-import com.openmemind.ai.memory.core.tracing.MemorySpanNames;
-import com.openmemind.ai.memory.core.tracing.NoopMemoryObserver;
-import com.openmemind.ai.memory.core.tracing.ObservationContext;
import com.openmemind.ai.memory.core.utils.IdUtils;
import com.openmemind.ai.memory.core.vector.MemoryVector;
+import io.micrometer.observation.ObservationRegistry;
import java.io.Closeable;
import java.time.Instant;
import java.util.ArrayList;
@@ -62,7 +59,6 @@
import java.util.stream.Collectors;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-import reactor.core.publisher.Mono;
/**
* Insight Build Scheduler
@@ -87,7 +83,7 @@ public class InsightBuildScheduler implements Closeable {
private final InsightBuildConfig config;
private final InsightPointIdentityManager pointIdentityManager;
private final InsightPointEvidenceNormalizer evidenceNormalizer;
- private final MemoryObserver observer;
+ private final ObservationRegistry observationRegistry;
private final ExecutorService executor;
private final Semaphore semaphore;
@@ -157,7 +153,7 @@ public InsightBuildScheduler(
MemoryVector memoryVector,
IdUtils.SnowflakeIdGenerator idGenerator,
InsightBuildConfig config,
- MemoryObserver observer) {
+ ObservationRegistry observationRegistry) {
this(
bufferStore,
store,
@@ -171,7 +167,7 @@ public InsightBuildScheduler(
new InsightPointIdentityManager(),
new InsightPointEvidenceNormalizer(),
NoOpInsightGraphAssistant.INSTANCE,
- observer);
+ observationRegistry);
}
public InsightBuildScheduler(
@@ -185,7 +181,7 @@ public InsightBuildScheduler(
IdUtils.SnowflakeIdGenerator idGenerator,
InsightBuildConfig config,
InsightGraphAssistant graphAssistant,
- MemoryObserver observer) {
+ ObservationRegistry observationRegistry) {
this(
bufferStore,
store,
@@ -199,7 +195,7 @@ public InsightBuildScheduler(
new InsightPointIdentityManager(),
new InsightPointEvidenceNormalizer(),
graphAssistant,
- observer);
+ observationRegistry);
}
public InsightBuildScheduler(
@@ -214,7 +210,7 @@ public InsightBuildScheduler(
InsightBuildConfig config,
InsightPointIdentityManager pointIdentityManager,
InsightPointEvidenceNormalizer evidenceNormalizer,
- MemoryObserver observer) {
+ ObservationRegistry observationRegistry) {
this(
bufferStore,
store,
@@ -228,7 +224,7 @@ public InsightBuildScheduler(
pointIdentityManager,
evidenceNormalizer,
NoOpInsightGraphAssistant.INSTANCE,
- observer);
+ observationRegistry);
}
public InsightBuildScheduler(
@@ -244,7 +240,7 @@ public InsightBuildScheduler(
InsightPointIdentityManager pointIdentityManager,
InsightPointEvidenceNormalizer evidenceNormalizer,
InsightGraphAssistant graphAssistant,
- MemoryObserver observer) {
+ ObservationRegistry observationRegistry) {
this.bufferStore = Objects.requireNonNull(bufferStore);
this.store = Objects.requireNonNull(store);
this.generator = Objects.requireNonNull(generator);
@@ -258,7 +254,8 @@ public InsightBuildScheduler(
this.config = Objects.requireNonNull(config);
this.pointIdentityManager = Objects.requireNonNull(pointIdentityManager);
this.evidenceNormalizer = Objects.requireNonNull(evidenceNormalizer);
- this.observer = observer != null ? observer : new NoopMemoryObserver();
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
this.executor = Executors.newVirtualThreadPerTaskExecutor();
this.semaphore = new Semaphore(config.concurrency());
}
@@ -405,23 +402,11 @@ private void runPipeline(
List itemIds,
boolean force,
String language) {
- observer.observeMono(
- ObservationContext.of(
- MemorySpanNames.EXTRACTION_INSIGHT_PIPELINE,
- Map.of(
- MemoryAttributes.MEMORY_ID,
- memoryId.toIdentifier(),
- MemoryAttributes.EXTRACTION_INSIGHT_TYPE,
- insightTypeName)),
- () ->
- Mono.fromRunnable(
- () ->
- doRunPipeline(
- memoryId,
- insightTypeName,
- itemIds,
- force,
- language)))
+ InsightBuildSchedulerObservation.observePipeline(
+ observationRegistry,
+ memoryId,
+ insightTypeName,
+ () -> doRunPipeline(memoryId, insightTypeName, itemIds, force, language))
.block();
}
@@ -894,28 +879,21 @@ private void phaseTreeReorganize(
List builtLeafs,
String language) {
try {
- observer.observeMono(
- ObservationContext.of(
- MemorySpanNames.EXTRACTION_INSIGHT_TREE_REORGANIZE,
- Map.of(
- MemoryAttributes.MEMORY_ID,
- memoryId.toIdentifier(),
- MemoryAttributes.EXTRACTION_INSIGHT_TYPE,
- insightTypeName,
- MemoryAttributes.EXTRACTION_INSIGHT_LEAF_COUNT,
- builtLeafs.size())),
- () ->
- Mono.fromRunnable(
- () -> {
- var treeConfig = insightType.resolveTreeConfig();
- treeReorganizer.onLeafsUpdated(
- memoryId,
- insightTypeName,
- insightType,
- builtLeafs,
- treeConfig,
- language);
- }))
+ InsightBuildSchedulerObservation.observeTreeReorganize(
+ observationRegistry,
+ memoryId,
+ insightTypeName,
+ builtLeafs.size(),
+ () -> {
+ var treeConfig = insightType.resolveTreeConfig();
+ treeReorganizer.onLeafsUpdated(
+ memoryId,
+ insightTypeName,
+ insightType,
+ builtLeafs,
+ treeConfig,
+ language);
+ })
.block();
log.debug(
"Phase 4 Tree Reorganize completed [type={}, leafs={}]",
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/scheduler/observation/InsightBuildSchedulerObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/scheduler/observation/InsightBuildSchedulerObservation.java
new file mode 100644
index 00000000..72980b0e
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/insight/scheduler/observation/InsightBuildSchedulerObservation.java
@@ -0,0 +1,215 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.insight.scheduler.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryId;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for InsightBuildScheduler. */
+public final class InsightBuildSchedulerObservation {
+
+ private InsightBuildSchedulerObservation() {}
+
+ public static Mono observePipeline(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ String insightTypeName,
+ Runnable operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ PipelineDocument.RUN,
+ PipelineConvention.INSTANCE,
+ () -> new PipelineObservationContext(memoryId, insightTypeName),
+ ignored -> Mono.fromRunnable(operation).then());
+ }
+
+ public static Mono observeTreeReorganize(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ String insightTypeName,
+ int leafCount,
+ Runnable operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ TreeReorganizeDocument.RUN,
+ TreeReorganizeConvention.INSTANCE,
+ () -> new TreeReorganizeObservationContext(memoryId, insightTypeName, leafCount),
+ ignored -> Mono.fromRunnable(operation).then());
+ }
+
+ public enum PipelineDocument implements ObservationDocumentation {
+ RUN("memind.extraction.insight.pipeline");
+
+ private final String name;
+
+ PipelineDocument(String name) {
+ this.name = name;
+ }
+
+ @Override
+ public String getName() {
+ return name;
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return PipelineConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return new KeyName[] {
+ HighCardinalityKeyNames.MEMORY_ID, HighCardinalityKeyNames.INSIGHT_TYPE
+ };
+ }
+ }
+
+ public enum TreeReorganizeDocument implements ObservationDocumentation {
+ RUN("memind.extraction.insight.tree.reorganize");
+
+ private final String name;
+
+ TreeReorganizeDocument(String name) {
+ this.name = name;
+ }
+
+ @Override
+ public String getName() {
+ return name;
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return TreeReorganizeConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ MEMORY_ID {
+ @Override
+ public String asString() {
+ return "memind.memory_id";
+ }
+ },
+ INSIGHT_TYPE {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_type";
+ }
+ },
+ LEAF_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.insight_leaf_count";
+ }
+ };
+ }
+
+ public static final class PipelineObservationContext extends Observation.Context {
+
+ private final String memoryId;
+ private final String insightTypeName;
+
+ public PipelineObservationContext(MemoryId memoryId, String insightTypeName) {
+ this.memoryId = memoryId == null ? "" : memoryId.toIdentifier();
+ this.insightTypeName = insightTypeName == null ? "" : insightTypeName;
+ }
+ }
+
+ public static final class TreeReorganizeObservationContext extends Observation.Context {
+
+ private final String memoryId;
+ private final String insightTypeName;
+ private final int leafCount;
+
+ public TreeReorganizeObservationContext(
+ MemoryId memoryId, String insightTypeName, int leafCount) {
+ this.memoryId = memoryId == null ? "" : memoryId.toIdentifier();
+ this.insightTypeName = insightTypeName == null ? "" : insightTypeName;
+ this.leafCount = leafCount;
+ }
+ }
+
+ public static final class PipelineConvention
+ implements ObservationConvention {
+
+ public static final PipelineConvention INSTANCE = new PipelineConvention();
+
+ @Override
+ public String getName() {
+ return PipelineDocument.RUN.getName();
+ }
+
+ @Override
+ public String getContextualName(PipelineObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(PipelineObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(context.memoryId),
+ HighCardinalityKeyNames.INSIGHT_TYPE.withValue(context.insightTypeName));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof PipelineObservationContext;
+ }
+ }
+
+ public static final class TreeReorganizeConvention
+ implements ObservationConvention {
+
+ public static final TreeReorganizeConvention INSTANCE = new TreeReorganizeConvention();
+
+ @Override
+ public String getName() {
+ return TreeReorganizeDocument.RUN.getName();
+ }
+
+ @Override
+ public String getContextualName(TreeReorganizeObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(TreeReorganizeObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(context.memoryId),
+ HighCardinalityKeyNames.INSIGHT_TYPE.withValue(context.insightTypeName),
+ HighCardinalityKeyNames.LEAF_COUNT.withValue(
+ String.valueOf(context.leafCount)));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof TreeReorganizeObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/MemoryItemLayer.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/MemoryItemLayer.java
index 9650cdd9..3e868a36 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/MemoryItemLayer.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/MemoryItemLayer.java
@@ -23,6 +23,7 @@
import com.openmemind.ai.memory.core.extraction.item.extractor.MemoryItemExtractor;
import com.openmemind.ai.memory.core.extraction.item.graph.ItemGraphMaterializer;
import com.openmemind.ai.memory.core.extraction.item.graph.NoOpItemGraphMaterializer;
+import com.openmemind.ai.memory.core.extraction.item.observation.MemoryItemLayerObservation;
import com.openmemind.ai.memory.core.extraction.item.support.ExtractedMemoryEntry;
import com.openmemind.ai.memory.core.extraction.item.support.ItemEmbeddingTextResolver;
import com.openmemind.ai.memory.core.extraction.rawdata.ParsedSegment;
@@ -32,6 +33,7 @@
import com.openmemind.ai.memory.core.store.MemoryStore;
import com.openmemind.ai.memory.core.utils.IdUtils;
import com.openmemind.ai.memory.core.vector.MemoryVector;
+import io.micrometer.observation.ObservationRegistry;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Comparator;
@@ -60,6 +62,7 @@ public class MemoryItemLayer implements MemoryItemExtractStep {
private final IdUtils.SnowflakeIdGenerator idGenerator;
private final LlmSelfVerificationStep selfVerificationStep; // nullable
private final ItemGraphMaterializer graphMaterializer;
+ private final ObservationRegistry observationRegistry;
public MemoryItemLayer(
MemoryItemExtractor extractor,
@@ -76,6 +79,23 @@ public MemoryItemLayer(
NoOpItemGraphMaterializer.persistItemsOnly(memoryStore.itemOperations()));
}
+ public MemoryItemLayer(
+ MemoryItemExtractor extractor,
+ MemoryItemDeduplicator deduplicator,
+ MemoryStore memoryStore,
+ MemoryVector vector,
+ ObservationRegistry observationRegistry) {
+ this(
+ extractor,
+ deduplicator,
+ memoryStore,
+ vector,
+ IdUtils.snowflake(),
+ null,
+ NoOpItemGraphMaterializer.persistItemsOnly(memoryStore.itemOperations()),
+ observationRegistry);
+ }
+
public MemoryItemLayer(
MemoryItemExtractor extractor,
MemoryItemDeduplicator deduplicator,
@@ -89,7 +109,8 @@ public MemoryItemLayer(
vector,
IdUtils.snowflake(),
selfVerificationStep,
- NoOpItemGraphMaterializer.persistItemsOnly(memoryStore.itemOperations()));
+ NoOpItemGraphMaterializer.persistItemsOnly(memoryStore.itemOperations()),
+ ObservationRegistry.NOOP);
}
public MemoryItemLayer(
@@ -105,7 +126,8 @@ public MemoryItemLayer(
vector,
IdUtils.snowflake(),
null,
- graphMaterializer);
+ graphMaterializer,
+ ObservationRegistry.NOOP);
}
public MemoryItemLayer(
@@ -122,7 +144,8 @@ public MemoryItemLayer(
vector,
idGenerator,
selfVerificationStep,
- NoOpItemGraphMaterializer.persistItemsOnly(memoryStore.itemOperations()));
+ NoOpItemGraphMaterializer.persistItemsOnly(memoryStore.itemOperations()),
+ ObservationRegistry.NOOP);
}
public MemoryItemLayer(
@@ -133,6 +156,26 @@ public MemoryItemLayer(
IdUtils.SnowflakeIdGenerator idGenerator,
LlmSelfVerificationStep selfVerificationStep,
ItemGraphMaterializer graphMaterializer) {
+ this(
+ extractor,
+ deduplicator,
+ memoryStore,
+ vector,
+ idGenerator,
+ selfVerificationStep,
+ graphMaterializer,
+ ObservationRegistry.NOOP);
+ }
+
+ public MemoryItemLayer(
+ MemoryItemExtractor extractor,
+ MemoryItemDeduplicator deduplicator,
+ MemoryStore memoryStore,
+ MemoryVector vector,
+ IdUtils.SnowflakeIdGenerator idGenerator,
+ LlmSelfVerificationStep selfVerificationStep,
+ ItemGraphMaterializer graphMaterializer,
+ ObservationRegistry observationRegistry) {
this.extractor = extractor;
this.deduplicator = deduplicator;
this.memoryStore = memoryStore;
@@ -143,11 +186,21 @@ public MemoryItemLayer(
graphMaterializer != null
? graphMaterializer
: NoOpItemGraphMaterializer.persistItemsOnly(memoryStore.itemOperations());
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
public Mono extract(
MemoryId memoryId, RawDataResult rawDataResult, ItemExtractionConfig config) {
+ return MemoryItemLayerObservation.observe(
+ observationRegistry,
+ memoryId,
+ () -> extractInternal(memoryId, rawDataResult, config));
+ }
+
+ private Mono extractInternal(
+ MemoryId memoryId, RawDataResult rawDataResult, ItemExtractionConfig config) {
List resolvedInsightTypes = resolveInsightTypes();
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/CompositeDeduplicator.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/CompositeDeduplicator.java
index dad6dd03..2e50f0fe 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/CompositeDeduplicator.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/CompositeDeduplicator.java
@@ -14,7 +14,9 @@
package com.openmemind.ai.memory.core.extraction.item.dedup;
import com.openmemind.ai.memory.core.data.MemoryId;
+import com.openmemind.ai.memory.core.extraction.item.dedup.observation.CompositeDeduplicatorObservation;
import com.openmemind.ai.memory.core.extraction.item.support.ExtractedMemoryEntry;
+import io.micrometer.observation.ObservationRegistry;
import java.util.ArrayList;
import java.util.List;
import reactor.core.publisher.Flux;
@@ -30,14 +32,28 @@
public class CompositeDeduplicator implements MemoryItemDeduplicator {
private final List deduplicators;
+ private final ObservationRegistry observationRegistry;
public CompositeDeduplicator(List deduplicators) {
+ this(deduplicators, ObservationRegistry.NOOP);
+ }
+
+ public CompositeDeduplicator(
+ List deduplicators, ObservationRegistry observationRegistry) {
this.deduplicators = List.copyOf(deduplicators);
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
public Mono deduplicate(
MemoryId memoryId, List entries) {
+ return CompositeDeduplicatorObservation.observe(
+ observationRegistry, memoryId, () -> deduplicateInternal(memoryId, entries));
+ }
+
+ private Mono deduplicateInternal(
+ MemoryId memoryId, List entries) {
var seed = Mono.just(new DeduplicationResult(entries, List.of()));
return Flux.fromIterable(deduplicators)
@@ -55,11 +71,6 @@ public Mono deduplicate(
.flatMap(mono -> mono);
}
- @Override
- public String spanName() {
- return "memind.extraction.item.dedup";
- }
-
private DeduplicationResult merge(DeduplicationResult acc, DeduplicationResult stage) {
var allMatched = new ArrayList<>(acc.matchedItems());
allMatched.addAll(stage.matchedItems());
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/HashBasedDeduplicator.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/HashBasedDeduplicator.java
index f72ae687..f350af24 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/HashBasedDeduplicator.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/HashBasedDeduplicator.java
@@ -17,7 +17,6 @@
import com.openmemind.ai.memory.core.data.MemoryItem;
import com.openmemind.ai.memory.core.extraction.item.support.ExtractedMemoryEntry;
import com.openmemind.ai.memory.core.store.MemoryStore;
-import com.openmemind.ai.memory.core.tracing.MemorySpanNames;
import com.openmemind.ai.memory.core.utils.HashUtils;
import java.util.ArrayList;
import java.util.List;
@@ -95,9 +94,4 @@ public Mono deduplicate(
List.copyOf(newEntries), List.copyOf(matchedItems));
});
}
-
- @Override
- public String spanName() {
- return MemorySpanNames.EXTRACTION_ITEM_DEDUP;
- }
}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/MemoryItemDeduplicator.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/MemoryItemDeduplicator.java
index ff61fd98..1f769892 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/MemoryItemDeduplicator.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/MemoryItemDeduplicator.java
@@ -32,9 +32,4 @@ public interface MemoryItemDeduplicator {
* @return Deduplication result
*/
Mono deduplicate(MemoryId memoryId, List entries);
-
- /**
- * The span name corresponding to this deduplicator
- */
- String spanName();
}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/SemanticDeduplicator.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/SemanticDeduplicator.java
index d8eb133b..63a62f9b 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/SemanticDeduplicator.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/SemanticDeduplicator.java
@@ -17,7 +17,6 @@
import com.openmemind.ai.memory.core.data.MemoryItem;
import com.openmemind.ai.memory.core.extraction.item.support.ExtractedMemoryEntry;
import com.openmemind.ai.memory.core.store.MemoryStore;
-import com.openmemind.ai.memory.core.tracing.MemorySpanNames;
import com.openmemind.ai.memory.core.vector.MemoryVector;
import java.util.ArrayList;
import java.util.List;
@@ -106,10 +105,5 @@ public Mono deduplicate(
});
}
- @Override
- public String spanName() {
- return MemorySpanNames.EXTRACTION_ITEM_SEMANTIC_DEDUP;
- }
-
private record EntryMatch(ExtractedMemoryEntry entry, String vectorId, float score) {}
}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/observation/CompositeDeduplicatorObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/observation/CompositeDeduplicatorObservation.java
new file mode 100644
index 00000000..1a74499c
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/dedup/observation/CompositeDeduplicatorObservation.java
@@ -0,0 +1,117 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.item.dedup.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryId;
+import com.openmemind.ai.memory.core.extraction.item.dedup.DeduplicationResult;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for CompositeDeduplicator. */
+public final class CompositeDeduplicatorObservation {
+
+ private CompositeDeduplicatorObservation() {}
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Supplier> operation) {
+ return observe(observationRegistry, memoryId, ignored -> operation.get());
+ }
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Function> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ DeduplicationDocument.DEDUPLICATE,
+ DeduplicationConvention.INSTANCE,
+ () -> new DeduplicationObservationContext(memoryId),
+ operation);
+ }
+
+ public enum DeduplicationDocument implements ObservationDocumentation {
+ DEDUPLICATE;
+
+ @Override
+ public String getName() {
+ return "memind.extraction.item.dedup";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return DeduplicationConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ MEMORY_ID {
+ @Override
+ public String asString() {
+ return "memind.memory_id";
+ }
+ };
+ }
+
+ public static final class DeduplicationObservationContext extends Observation.Context {
+
+ private final MemoryId memoryId;
+
+ public DeduplicationObservationContext(MemoryId memoryId) {
+ this.memoryId = memoryId;
+ }
+ }
+
+ public static final class DeduplicationConvention
+ implements ObservationConvention {
+
+ public static final DeduplicationConvention INSTANCE = new DeduplicationConvention();
+
+ @Override
+ public String getName() {
+ return DeduplicationDocument.DEDUPLICATE.getName();
+ }
+
+ @Override
+ public String getContextualName(DeduplicationObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(DeduplicationObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(context.memoryId.toIdentifier()));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof DeduplicationObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/graph/pipeline/DefaultItemGraphMaterializer.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/graph/pipeline/DefaultItemGraphMaterializer.java
index 41056496..c7409159 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/graph/pipeline/DefaultItemGraphMaterializer.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/graph/pipeline/DefaultItemGraphMaterializer.java
@@ -20,9 +20,11 @@
import com.openmemind.ai.memory.core.extraction.item.graph.ItemGraphMaterializer;
import com.openmemind.ai.memory.core.extraction.item.graph.commit.ExtractionBatchId;
import com.openmemind.ai.memory.core.extraction.item.graph.derived.GraphDerivedMaintainer;
+import com.openmemind.ai.memory.core.extraction.item.graph.pipeline.observation.DefaultItemGraphMaterializerObservation;
import com.openmemind.ai.memory.core.extraction.item.graph.plan.DefaultItemGraphPlanner;
import com.openmemind.ai.memory.core.extraction.item.support.ExtractedMemoryEntry;
import com.openmemind.ai.memory.core.store.graph.ItemGraphCommitOperations;
+import io.micrometer.observation.ObservationRegistry;
import java.util.List;
import java.util.Objects;
import reactor.core.publisher.Mono;
@@ -36,21 +38,42 @@ public final class DefaultItemGraphMaterializer implements ItemGraphMaterializer
private final ItemGraphCommitOperations commitOperations;
private final GraphDerivedMaintainer derivedMaintainer;
private final ItemGraphOptions options;
+ private final ObservationRegistry observationRegistry;
public DefaultItemGraphMaterializer(
DefaultItemGraphPlanner planner,
ItemGraphCommitOperations commitOperations,
GraphDerivedMaintainer derivedMaintainer,
ItemGraphOptions options) {
+ this(planner, commitOperations, derivedMaintainer, options, ObservationRegistry.NOOP);
+ }
+
+ public DefaultItemGraphMaterializer(
+ DefaultItemGraphPlanner planner,
+ ItemGraphCommitOperations commitOperations,
+ GraphDerivedMaintainer derivedMaintainer,
+ ItemGraphOptions options,
+ ObservationRegistry observationRegistry) {
this.planner = Objects.requireNonNull(planner, "planner");
this.commitOperations = Objects.requireNonNull(commitOperations, "commitOperations");
this.derivedMaintainer = Objects.requireNonNull(derivedMaintainer, "derivedMaintainer");
this.options = Objects.requireNonNull(options, "options");
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
public Mono materialize(
MemoryId memoryId, List items, List sourceEntries) {
+ return DefaultItemGraphMaterializerObservation.observe(
+ observationRegistry,
+ memoryId,
+ items,
+ () -> materializeInternal(memoryId, items, sourceEntries));
+ }
+
+ private Mono materializeInternal(
+ MemoryId memoryId, List items, List sourceEntries) {
if (!options.enabled() || items == null || items.isEmpty()) {
return Mono.just(ItemGraphMaterializationResult.empty());
}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/graph/pipeline/observation/DefaultItemGraphMaterializerObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/graph/pipeline/observation/DefaultItemGraphMaterializerObservation.java
new file mode 100644
index 00000000..67032c44
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/graph/pipeline/observation/DefaultItemGraphMaterializerObservation.java
@@ -0,0 +1,618 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.item.graph.pipeline.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryId;
+import com.openmemind.ai.memory.core.data.MemoryItem;
+import com.openmemind.ai.memory.core.extraction.item.graph.ItemGraphMaterializationResult;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.List;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for DefaultItemGraphMaterializer. */
+public final class DefaultItemGraphMaterializerObservation {
+
+ private DefaultItemGraphMaterializerObservation() {}
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ List items,
+ Supplier> operation) {
+ return observe(observationRegistry, memoryId, items, ignored -> operation.get());
+ }
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ List items,
+ Function>
+ operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ GraphMaterializeDocument.GRAPH_MATERIALIZE,
+ GraphMaterializeConvention.INSTANCE,
+ () -> new GraphMaterializeObservationContext(memoryId, items),
+ context -> operation.apply(context).doOnNext(context::recordResult));
+ }
+
+ public enum GraphMaterializeDocument implements ObservationDocumentation {
+ GRAPH_MATERIALIZE;
+
+ @Override
+ public String getName() {
+ return "memind.graph.materialize";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return GraphMaterializeConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ MEMORY_ID {
+ @Override
+ public String asString() {
+ return "memind.memory_id";
+ }
+ },
+ EXTRACTION_ITEM_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.item_count";
+ }
+ },
+ ENTITY_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.entity_count";
+ }
+ },
+ MENTION_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.mention_count";
+ }
+ },
+ STRUCTURED_LINK_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.structured_link_count";
+ }
+ },
+ TEMPORAL_SOURCE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_source_count";
+ }
+ },
+ TEMPORAL_HISTORY_QUERY_BATCH_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_history_query_batch_count";
+ }
+ },
+ TEMPORAL_HISTORY_CANDIDATE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_history_candidate_count";
+ }
+ },
+ TEMPORAL_INTRA_BATCH_CANDIDATE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_intra_batch_candidate_count";
+ }
+ },
+ TEMPORAL_SELECTED_PAIR_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_selected_pair_count";
+ }
+ },
+ TEMPORAL_CREATED_LINK_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_created_link_count";
+ }
+ },
+ TEMPORAL_QUERY_DURATION_MS {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_query_duration_ms";
+ }
+ },
+ TEMPORAL_BUILD_DURATION_MS {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_build_duration_ms";
+ }
+ },
+ TEMPORAL_UPSERT_DURATION_MS {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_upsert_duration_ms";
+ }
+ },
+ TEMPORAL_BELOW_RETRIEVAL_FLOOR_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_below_retrieval_floor_count";
+ }
+ },
+ TEMPORAL_MIN_STRENGTH {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_min_strength";
+ }
+ },
+ TEMPORAL_MAX_STRENGTH {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_max_strength";
+ }
+ },
+ TEMPORAL_STRENGTH_BUCKET_SUMMARY {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_strength_bucket_summary";
+ }
+ },
+ TEMPORAL_DEGRADED {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.temporal_degraded";
+ }
+ },
+ RESOLUTION_CANDIDATE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_candidate_count";
+ }
+ },
+ RESOLUTION_SOURCE_DISTRIBUTION {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_source_distribution";
+ }
+ },
+ RESOLUTION_SCORE_HISTOGRAM {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_score_histogram";
+ }
+ },
+ RESOLUTION_CANDIDATE_REJECTED_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_candidate_rejected_count";
+ }
+ },
+ RESOLUTION_MERGE_ACCEPTED_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_merge_accepted_count";
+ }
+ },
+ RESOLUTION_MERGE_REJECTED_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_merge_rejected_count";
+ }
+ },
+ RESOLUTION_CREATE_NEW_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_create_new_count";
+ }
+ },
+ RESOLUTION_EXACT_FALLBACK_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_exact_fallback_count";
+ }
+ },
+ RESOLUTION_CANDIDATE_CAP_HIT_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_candidate_cap_hit_count";
+ }
+ },
+ ALIAS_EVIDENCE_OBSERVED_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.alias_evidence_observed_count";
+ }
+ },
+ ALIAS_EVIDENCE_MERGED_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.alias_evidence_merged_count";
+ }
+ },
+ RESOLUTION_SPECIAL_BYPASS_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.resolution_special_bypass_count";
+ }
+ },
+ SEMANTIC_SEARCH_REQUEST_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_search_request_count";
+ }
+ },
+ SEMANTIC_SEARCH_INVOCATION_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_search_invocation_count";
+ }
+ },
+ SEMANTIC_SEARCH_HIT_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_search_hit_count";
+ }
+ },
+ SEMANTIC_RESOLVED_CANDIDATE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_resolved_candidate_count";
+ }
+ },
+ SEMANTIC_LINK_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_link_count";
+ }
+ },
+ SEMANTIC_UPSERT_BATCH_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_upsert_batch_count";
+ }
+ },
+ SEMANTIC_SOURCE_WINDOW_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_source_window_count";
+ }
+ },
+ SEMANTIC_FAILED_RESOLVE_CHUNK_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_failed_resolve_chunk_count";
+ }
+ },
+ SEMANTIC_FAILED_WINDOW_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_failed_window_count";
+ }
+ },
+ SEMANTIC_FAILED_UPSERT_BATCH_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_failed_upsert_batch_count";
+ }
+ },
+ SEMANTIC_SAME_BATCH_HIT_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_same_batch_hit_count";
+ }
+ },
+ SEMANTIC_SEARCH_FALLBACK_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_search_fallback_count";
+ }
+ },
+ SEMANTIC_INTRA_BATCH_CANDIDATE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_intra_batch_candidate_count";
+ }
+ },
+ SEMANTIC_SEARCH_PHASE_DURATION_MS {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_search_phase_duration_ms";
+ }
+ },
+ SEMANTIC_RESOLVE_PHASE_DURATION_MS {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_resolve_phase_duration_ms";
+ }
+ },
+ SEMANTIC_UPSERT_PHASE_DURATION_MS {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_upsert_phase_duration_ms";
+ }
+ },
+ SEMANTIC_INTRA_BATCH_PHASE_DURATION_MS {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_intra_batch_phase_duration_ms";
+ }
+ },
+ SEMANTIC_DEGRADED {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.semantic_degraded";
+ }
+ },
+ TYPE_FALLBACK_TO_OTHER_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.type_fallback_to_other_count";
+ }
+ },
+ TOP_UNRESOLVED_TYPE_LABELS {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.top_unresolved_type_labels";
+ }
+ },
+ DROPPED_BLANK_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.dropped_blank_count";
+ }
+ },
+ DROPPED_PUNCTUATION_ONLY_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.dropped_punctuation_only_count";
+ }
+ },
+ DROPPED_PRONOUN_LIKE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.dropped_pronoun_like_count";
+ }
+ },
+ DROPPED_TEMPORAL_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.dropped_temporal_count";
+ }
+ },
+ DROPPED_DATE_LIKE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.dropped_date_like_count";
+ }
+ },
+ DROPPED_RESERVED_SPECIAL_COLLISION_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.dropped_reserved_special_collision_count";
+ }
+ },
+ STRUCTURED_BATCH_DEGRADED {
+ @Override
+ public String asString() {
+ return "memind.extraction.graph.structured_batch_degraded";
+ }
+ };
+ }
+
+ public static final class GraphMaterializeObservationContext extends Observation.Context {
+
+ private final MemoryId memoryId;
+ private final int itemCount;
+
+ public GraphMaterializeObservationContext(MemoryId memoryId, List items) {
+ this.memoryId = memoryId;
+ this.itemCount = items == null ? 0 : items.size();
+ }
+
+ public void recordResult(ItemGraphMaterializationResult result) {
+ var stats = result.stats();
+ add(HighCardinalityKeyNames.ENTITY_COUNT, stats.entityCount());
+ add(HighCardinalityKeyNames.MENTION_COUNT, stats.mentionCount());
+ add(HighCardinalityKeyNames.STRUCTURED_LINK_COUNT, stats.structuredItemLinkCount());
+ add(HighCardinalityKeyNames.TEMPORAL_SOURCE_COUNT, stats.temporalSourceCount());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_HISTORY_QUERY_BATCH_COUNT,
+ stats.temporalHistoryQueryBatchCount());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_HISTORY_CANDIDATE_COUNT,
+ stats.temporalHistoryCandidateCount());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_INTRA_BATCH_CANDIDATE_COUNT,
+ stats.temporalIntraBatchCandidateCount());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_SELECTED_PAIR_COUNT,
+ stats.temporalSelectedPairCount());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_CREATED_LINK_COUNT,
+ stats.temporalCreatedLinkCount());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_QUERY_DURATION_MS,
+ stats.temporalQueryDurationMs());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_BUILD_DURATION_MS,
+ stats.temporalBuildDurationMs());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_UPSERT_DURATION_MS,
+ stats.temporalUpsertDurationMs());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_BELOW_RETRIEVAL_FLOOR_COUNT,
+ stats.temporalBelowRetrievalFloorCount());
+ add(HighCardinalityKeyNames.TEMPORAL_MIN_STRENGTH, stats.temporalMinStrength());
+ add(HighCardinalityKeyNames.TEMPORAL_MAX_STRENGTH, stats.temporalMaxStrength());
+ add(
+ HighCardinalityKeyNames.TEMPORAL_STRENGTH_BUCKET_SUMMARY,
+ stats.temporalStrengthBucketSummary());
+ add(HighCardinalityKeyNames.TEMPORAL_DEGRADED, stats.temporalDegraded());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_CANDIDATE_COUNT,
+ stats.resolutionCandidateCount());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_SOURCE_DISTRIBUTION,
+ stats.resolutionCandidateSourceSummary());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_SCORE_HISTOGRAM,
+ stats.resolutionMergeScoreHistogramSummary());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_CANDIDATE_REJECTED_COUNT,
+ stats.resolutionCandidateRejectedCount());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_MERGE_ACCEPTED_COUNT,
+ stats.resolutionMergeAcceptedCount());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_MERGE_REJECTED_COUNT,
+ stats.resolutionMergeRejectedCount());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_CREATE_NEW_COUNT,
+ stats.resolutionCreateNewCount());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_EXACT_FALLBACK_COUNT,
+ stats.resolutionExactFallbackCount());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_CANDIDATE_CAP_HIT_COUNT,
+ stats.resolutionCandidateCapHitCount());
+ add(
+ HighCardinalityKeyNames.ALIAS_EVIDENCE_OBSERVED_COUNT,
+ stats.aliasEvidenceObservedCount());
+ add(
+ HighCardinalityKeyNames.ALIAS_EVIDENCE_MERGED_COUNT,
+ stats.aliasEvidenceMergedCount());
+ add(
+ HighCardinalityKeyNames.RESOLUTION_SPECIAL_BYPASS_COUNT,
+ stats.resolutionSpecialBypassCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_SEARCH_REQUEST_COUNT,
+ stats.semanticSearchRequestCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_SEARCH_INVOCATION_COUNT,
+ stats.semanticSearchInvocationCount());
+ add(HighCardinalityKeyNames.SEMANTIC_SEARCH_HIT_COUNT, stats.semanticSearchHitCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_RESOLVED_CANDIDATE_COUNT,
+ stats.semanticResolvedCandidateCount());
+ add(HighCardinalityKeyNames.SEMANTIC_LINK_COUNT, stats.semanticLinkCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_UPSERT_BATCH_COUNT,
+ stats.semanticUpsertBatchCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_SOURCE_WINDOW_COUNT,
+ stats.semanticSourceWindowCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_FAILED_RESOLVE_CHUNK_COUNT,
+ stats.semanticFailedResolveChunkCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_FAILED_WINDOW_COUNT,
+ stats.semanticFailedWindowCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_FAILED_UPSERT_BATCH_COUNT,
+ stats.semanticFailedUpsertBatchCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_SAME_BATCH_HIT_COUNT,
+ stats.semanticSameBatchHitCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_SEARCH_FALLBACK_COUNT,
+ stats.semanticSearchFallbackCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_INTRA_BATCH_CANDIDATE_COUNT,
+ stats.semanticIntraBatchCandidateCount());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_SEARCH_PHASE_DURATION_MS,
+ stats.semanticSearchPhaseDurationMs());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_RESOLVE_PHASE_DURATION_MS,
+ stats.semanticResolvePhaseDurationMs());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_UPSERT_PHASE_DURATION_MS,
+ stats.semanticUpsertPhaseDurationMs());
+ add(
+ HighCardinalityKeyNames.SEMANTIC_INTRA_BATCH_PHASE_DURATION_MS,
+ stats.semanticIntraBatchPhaseDurationMs());
+ add(HighCardinalityKeyNames.SEMANTIC_DEGRADED, stats.semanticDegraded());
+ add(
+ HighCardinalityKeyNames.TYPE_FALLBACK_TO_OTHER_COUNT,
+ stats.typeFallbackToOtherCount());
+ add(
+ HighCardinalityKeyNames.TOP_UNRESOLVED_TYPE_LABELS,
+ stats.topUnresolvedTypeLabelsSummary());
+ add(HighCardinalityKeyNames.DROPPED_BLANK_COUNT, stats.droppedBlankCount());
+ add(
+ HighCardinalityKeyNames.DROPPED_PUNCTUATION_ONLY_COUNT,
+ stats.droppedPunctuationOnlyCount());
+ add(
+ HighCardinalityKeyNames.DROPPED_PRONOUN_LIKE_COUNT,
+ stats.droppedPronounLikeCount());
+ add(HighCardinalityKeyNames.DROPPED_TEMPORAL_COUNT, stats.droppedTemporalCount());
+ add(HighCardinalityKeyNames.DROPPED_DATE_LIKE_COUNT, stats.droppedDateLikeCount());
+ add(
+ HighCardinalityKeyNames.DROPPED_RESERVED_SPECIAL_COLLISION_COUNT,
+ stats.droppedReservedSpecialCollisionCount());
+ add(HighCardinalityKeyNames.STRUCTURED_BATCH_DEGRADED, stats.structuredBatchDegraded());
+ }
+
+ private void add(HighCardinalityKeyNames key, Object value) {
+ if (value != null) {
+ addHighCardinalityKeyValue(key.withValue(String.valueOf(value)));
+ }
+ }
+ }
+
+ public static final class GraphMaterializeConvention
+ implements ObservationConvention {
+
+ public static final GraphMaterializeConvention INSTANCE = new GraphMaterializeConvention();
+
+ @Override
+ public String getName() {
+ return GraphMaterializeDocument.GRAPH_MATERIALIZE.getName();
+ }
+
+ @Override
+ public String getContextualName(GraphMaterializeObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(GraphMaterializeObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(context.memoryId.toIdentifier()),
+ HighCardinalityKeyNames.EXTRACTION_ITEM_COUNT.withValue(
+ String.valueOf(context.itemCount)));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof GraphMaterializeObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/observation/MemoryItemLayerObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/observation/MemoryItemLayerObservation.java
new file mode 100644
index 00000000..e6dd179a
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/item/observation/MemoryItemLayerObservation.java
@@ -0,0 +1,151 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.item.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryId;
+import com.openmemind.ai.memory.core.extraction.result.MemoryItemResult;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for MemoryItemLayer. */
+public final class MemoryItemLayerObservation {
+
+ private MemoryItemLayerObservation() {}
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Supplier> operation) {
+ return observe(observationRegistry, memoryId, ignored -> operation.get());
+ }
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Function> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ MemoryItemDocument.EXTRACT,
+ MemoryItemConvention.INSTANCE,
+ () -> new MemoryItemObservationContext(memoryId),
+ context -> operation.apply(context).doOnNext(context::recordResult));
+ }
+
+ public enum MemoryItemDocument implements ObservationDocumentation {
+ EXTRACT;
+
+ @Override
+ public String getName() {
+ return "memind.extraction.item";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return MemoryItemConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ MEMORY_ID {
+ @Override
+ public String asString() {
+ return "memind.memory_id";
+ }
+ },
+ ITEM_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.item_count";
+ }
+ },
+ NEW_ITEM_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.new_item_count";
+ }
+ };
+ }
+
+ public static final class MemoryItemObservationContext extends Observation.Context {
+
+ private final MemoryId memoryId;
+ private Integer itemCount;
+ private Integer newItemCount;
+
+ public MemoryItemObservationContext(MemoryId memoryId) {
+ this.memoryId = memoryId;
+ }
+
+ public void recordResult(MemoryItemResult result) {
+ this.itemCount = result.newCount();
+ this.newItemCount = result.newItems().size();
+ }
+ }
+
+ public static final class MemoryItemConvention
+ implements ObservationConvention {
+
+ public static final MemoryItemConvention INSTANCE = new MemoryItemConvention();
+
+ @Override
+ public String getName() {
+ return MemoryItemDocument.EXTRACT.getName();
+ }
+
+ @Override
+ public String getContextualName(MemoryItemObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(MemoryItemObservationContext context) {
+ var values =
+ KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(
+ context.memoryId.toIdentifier()));
+ if (context.itemCount != null) {
+ values =
+ values.and(
+ HighCardinalityKeyNames.ITEM_COUNT.withValue(
+ String.valueOf(context.itemCount)));
+ }
+ if (context.newItemCount != null) {
+ values =
+ values.and(
+ HighCardinalityKeyNames.NEW_ITEM_COUNT.withValue(
+ String.valueOf(context.newItemCount)));
+ }
+ return values;
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof MemoryItemObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/observation/DefaultMemoryExtractorObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/observation/DefaultMemoryExtractorObservation.java
new file mode 100644
index 00000000..4e91f8c9
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/observation/DefaultMemoryExtractorObservation.java
@@ -0,0 +1,224 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryId;
+import com.openmemind.ai.memory.core.extraction.ExtractionResult;
+import com.openmemind.ai.memory.core.extraction.ExtractionStatus;
+import com.openmemind.ai.memory.core.extraction.item.graph.ItemGraphMaterializationResult;
+import com.openmemind.ai.memory.core.extraction.result.MemoryItemResult;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import com.openmemind.ai.memory.core.observation.MemoryObservationContext;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for DefaultMemoryExtractor. */
+public final class DefaultMemoryExtractorObservation {
+
+ private DefaultMemoryExtractorObservation() {}
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Supplier> operation) {
+ return observe(observationRegistry, memoryId, ignored -> operation.get());
+ }
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Function> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ ExtractionDocument.EXTRACTION,
+ ExtractionObservationConvention.INSTANCE,
+ () -> new ExtractionObservationContext(memoryId),
+ context -> operation.apply(context).doOnNext(context::recordResult));
+ }
+
+ public enum ExtractionDocument implements ObservationDocumentation {
+ EXTRACTION;
+
+ @Override
+ public String getName() {
+ return "memind.extraction";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return ExtractionObservationConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ MEMORY_ID {
+ @Override
+ public String asString() {
+ return "memind.memory_id";
+ }
+ };
+ }
+
+ public static final class ExtractionObservationContext extends MemoryObservationContext {
+
+ private final MemoryId memoryId;
+ private boolean hasResult;
+ private String resultStatus = "unknown";
+ private int rawDataCount;
+ private Integer segmentCount;
+ private int newItemCount;
+ private Integer reinforcedItemCount;
+ private int insightCount;
+ private Integer graphEntityCount;
+ private Integer graphMentionCount;
+ private Integer graphRelationCount;
+ private String source = "core";
+
+ public ExtractionObservationContext(MemoryId memoryId) {
+ this.memoryId = memoryId;
+ }
+
+ public void recordResult(ExtractionResult result) {
+ hasResult = true;
+ if (result == null) {
+ return;
+ }
+ resultStatus = status(result.status());
+ rawDataCount =
+ result.rawDataResult() == null || result.rawDataResult().rawDataList() == null
+ ? 0
+ : result.rawDataResult().rawDataList().size();
+ segmentCount =
+ result.rawDataResult() == null || result.rawDataResult().segments() == null
+ ? null
+ : result.rawDataResult().segments().size();
+
+ MemoryItemResult itemResult = result.memoryItemResult();
+ newItemCount = itemResult == null ? 0 : itemResult.newCount();
+ insightCount = result.totalInsights();
+
+ ItemGraphMaterializationResult graph =
+ itemResult == null ? null : itemResult.graphMaterializationResult();
+ ItemGraphMaterializationResult.Stats stats = graph == null ? null : graph.stats();
+ graphEntityCount = stats == null ? null : stats.entityCount();
+ graphMentionCount = stats == null ? null : stats.mentionCount();
+ graphRelationCount = finalRelationCount(stats);
+ }
+
+ public boolean hasResult() {
+ return hasResult;
+ }
+
+ @Override
+ public String status() {
+ String terminalStatus = errorOrCancellationStatus();
+ if (terminalStatus != null) {
+ return terminalStatus;
+ }
+ return resultStatus;
+ }
+
+ public int rawDataCount() {
+ return rawDataCount;
+ }
+
+ public Integer segmentCount() {
+ return segmentCount;
+ }
+
+ public int newItemCount() {
+ return newItemCount;
+ }
+
+ public Integer reinforcedItemCount() {
+ return reinforcedItemCount;
+ }
+
+ public int insightCount() {
+ return insightCount;
+ }
+
+ public Integer graphEntityCount() {
+ return graphEntityCount;
+ }
+
+ public Integer graphMentionCount() {
+ return graphMentionCount;
+ }
+
+ public Integer graphRelationCount() {
+ return graphRelationCount;
+ }
+
+ public String source() {
+ return source;
+ }
+
+ private static Integer finalRelationCount(ItemGraphMaterializationResult.Stats stats) {
+ if (stats == null || stats.finalRelationStats() == null) {
+ return null;
+ }
+ var finalStats = stats.finalRelationStats();
+ return finalStats.semanticRelationCount()
+ + finalStats.temporalRelationCount()
+ + finalStats.causalRelationCount()
+ + finalStats.itemLinkCount();
+ }
+
+ private static String status(ExtractionStatus status) {
+ return status == null ? "unknown" : status.name().toLowerCase();
+ }
+ }
+
+ public static final class ExtractionObservationConvention
+ implements ObservationConvention {
+
+ public static final ExtractionObservationConvention INSTANCE =
+ new ExtractionObservationConvention();
+
+ @Override
+ public String getName() {
+ return ExtractionDocument.EXTRACTION.getName();
+ }
+
+ @Override
+ public String getContextualName(ExtractionObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(ExtractionObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(context.memoryId.toIdentifier()));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof ExtractionObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/rawdata/RawDataLayer.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/rawdata/RawDataLayer.java
index f2cc68c5..2651131b 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/rawdata/RawDataLayer.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/rawdata/RawDataLayer.java
@@ -19,6 +19,7 @@
import com.openmemind.ai.memory.core.extraction.rawdata.caption.CaptionGenerator;
import com.openmemind.ai.memory.core.extraction.rawdata.content.ConversationContent;
import com.openmemind.ai.memory.core.extraction.rawdata.content.RawContent;
+import com.openmemind.ai.memory.core.extraction.rawdata.observation.RawDataLayerObservation;
import com.openmemind.ai.memory.core.extraction.rawdata.segment.CharBoundary;
import com.openmemind.ai.memory.core.extraction.rawdata.segment.MessageBoundary;
import com.openmemind.ai.memory.core.extraction.rawdata.segment.Segment;
@@ -29,6 +30,7 @@
import com.openmemind.ai.memory.core.store.MemoryStore;
import com.openmemind.ai.memory.core.utils.HashUtils;
import com.openmemind.ai.memory.core.vector.MemoryVector;
+import io.micrometer.observation.ObservationRegistry;
import java.time.Instant;
import java.util.ArrayList;
import java.util.HashMap;
@@ -54,6 +56,7 @@ public class RawDataLayer implements RawDataExtractStep, SegmentProcessor {
private final MemoryStore memoryStore;
private final MemoryVector vector;
private final int vectorBatchSize;
+ private final ObservationRegistry observationRegistry;
/**
* Creates a RawDataLayer with a list of content processors.
@@ -83,12 +86,29 @@ public RawDataLayer(
MemoryStore memoryStore,
MemoryVector vector,
int vectorBatchSize) {
+ this(
+ processorList,
+ defaultCaptionGenerator,
+ memoryStore,
+ vector,
+ vectorBatchSize,
+ ObservationRegistry.NOOP);
+ }
+
+ public RawDataLayer(
+ List> processorList,
+ CaptionGenerator defaultCaptionGenerator,
+ MemoryStore memoryStore,
+ MemoryVector vector,
+ int vectorBatchSize,
+ ObservationRegistry observationRegistry) {
this(
new RawContentProcessorRegistry(processorList),
defaultCaptionGenerator,
memoryStore,
vector,
- vectorBatchSize);
+ vectorBatchSize,
+ observationRegistry);
}
public RawDataLayer(
@@ -97,6 +117,22 @@ public RawDataLayer(
MemoryStore memoryStore,
MemoryVector vector,
int vectorBatchSize) {
+ this(
+ processorRegistry,
+ defaultCaptionGenerator,
+ memoryStore,
+ vector,
+ vectorBatchSize,
+ ObservationRegistry.NOOP);
+ }
+
+ public RawDataLayer(
+ RawContentProcessorRegistry processorRegistry,
+ CaptionGenerator defaultCaptionGenerator,
+ MemoryStore memoryStore,
+ MemoryVector vector,
+ int vectorBatchSize,
+ ObservationRegistry observationRegistry) {
this.processorRegistry =
java.util.Objects.requireNonNull(processorRegistry, "processorRegistry");
this.defaultCaptionGenerator = defaultCaptionGenerator;
@@ -106,6 +142,8 @@ public RawDataLayer(
throw new IllegalArgumentException("vectorBatchSize must be > 0");
}
this.vectorBatchSize = vectorBatchSize;
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
@@ -124,6 +162,18 @@ public Mono extract(
String contentType,
Map metadata,
String language) {
+ return RawDataLayerObservation.observe(
+ observationRegistry,
+ memoryId,
+ () -> extractInternal(memoryId, content, contentType, metadata, language));
+ }
+
+ private Mono extractInternal(
+ MemoryId memoryId,
+ RawContent content,
+ String contentType,
+ Map metadata,
+ String language) {
RawDataInput input = new RawDataInput(memoryId, content, contentType, metadata);
return process(input, language)
.map(
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/rawdata/observation/RawDataLayerObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/rawdata/observation/RawDataLayerObservation.java
new file mode 100644
index 00000000..acfd50d5
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/extraction/rawdata/observation/RawDataLayerObservation.java
@@ -0,0 +1,137 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.extraction.rawdata.observation;
+
+import com.openmemind.ai.memory.core.data.MemoryId;
+import com.openmemind.ai.memory.core.extraction.result.RawDataResult;
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+
+/** Observation contracts for RawDataLayer. */
+public final class RawDataLayerObservation {
+
+ private RawDataLayerObservation() {}
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Supplier> operation) {
+ return observe(observationRegistry, memoryId, ignored -> operation.get());
+ }
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ MemoryId memoryId,
+ Function> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ RawDataDocument.EXTRACT,
+ RawDataConvention.INSTANCE,
+ () -> new RawDataObservationContext(memoryId),
+ context -> operation.apply(context).doOnNext(context::recordResult));
+ }
+
+ public enum RawDataDocument implements ObservationDocumentation {
+ EXTRACT;
+
+ @Override
+ public String getName() {
+ return "memind.extraction.rawdata";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return RawDataConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ MEMORY_ID {
+ @Override
+ public String asString() {
+ return "memind.memory_id";
+ }
+ },
+ SEGMENT_COUNT {
+ @Override
+ public String asString() {
+ return "memind.extraction.segment_count";
+ }
+ };
+ }
+
+ public static final class RawDataObservationContext extends Observation.Context {
+
+ private final MemoryId memoryId;
+ private Integer segmentCount;
+
+ public RawDataObservationContext(MemoryId memoryId) {
+ this.memoryId = memoryId;
+ }
+
+ public void recordResult(RawDataResult result) {
+ this.segmentCount = result.segments().size();
+ }
+ }
+
+ public static final class RawDataConvention
+ implements ObservationConvention {
+
+ public static final RawDataConvention INSTANCE = new RawDataConvention();
+
+ @Override
+ public String getName() {
+ return RawDataDocument.EXTRACT.getName();
+ }
+
+ @Override
+ public String getContextualName(RawDataObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(RawDataObservationContext context) {
+ var values =
+ KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(
+ context.memoryId.toIdentifier()));
+ if (context.segmentCount != null) {
+ values =
+ values.and(
+ HighCardinalityKeyNames.SEGMENT_COUNT.withValue(
+ String.valueOf(context.segmentCount)));
+ }
+ return values;
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof RawDataObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/llm/rerank/LlmReranker.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/llm/rerank/LlmReranker.java
index 1b77851c..fb6deda6 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/llm/rerank/LlmReranker.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/llm/rerank/LlmReranker.java
@@ -15,8 +15,10 @@
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
+import com.openmemind.ai.memory.core.llm.rerank.observation.LlmRerankerObservation;
import com.openmemind.ai.memory.core.retrieval.RetrievalConfig.RerankConfig;
import com.openmemind.ai.memory.core.retrieval.scoring.ScoredResult;
+import io.micrometer.observation.ObservationRegistry;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
@@ -49,12 +51,22 @@ public class LlmReranker implements Reranker {
private final String rerankUrl;
private final String apiKey;
private final String model;
+ private final ObservationRegistry observationRegistry;
public LlmReranker(String baseUrl, String apiKey) {
this(baseUrl, apiKey, DEFAULT_MODEL);
}
+ public LlmReranker(String baseUrl, String apiKey, ObservationRegistry observationRegistry) {
+ this(baseUrl, apiKey, DEFAULT_MODEL, observationRegistry);
+ }
+
public LlmReranker(String baseUrl, String apiKey, String model) {
+ this(baseUrl, apiKey, model, ObservationRegistry.NOOP);
+ }
+
+ public LlmReranker(
+ String baseUrl, String apiKey, String model, ObservationRegistry observationRegistry) {
Objects.requireNonNull(baseUrl, "baseUrl must not be null");
Objects.requireNonNull(apiKey, "apiKey must not be null");
this.rerankUrl = baseUrl.replaceAll("/+$", "") + "/v1/rerank";
@@ -62,10 +74,32 @@ public LlmReranker(String baseUrl, String apiKey, String model) {
this.model = Objects.requireNonNull(model, "model must not be null");
this.httpClient = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
this.objectMapper = new ObjectMapper();
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
public Mono> rerank(String query, List results, int topK) {
+ return LlmRerankerObservation.observe(
+ observationRegistry,
+ query,
+ results,
+ topK,
+ context ->
+ rerankInternal(query, results, topK)
+ .onErrorResume(
+ e -> {
+ context.markDegraded();
+ log.warn(
+ "Rerank failed after 3 retries, returning"
+ + " original sorted topK slice",
+ e);
+ return Mono.just(fallback(results, topK));
+ }));
+ }
+
+ private Mono> rerankInternal(
+ String query, List results, int topK) {
if (results.isEmpty()) {
return Mono.just(results);
}
@@ -73,15 +107,7 @@ public Mono> rerank(String query, List results,
return Mono.fromCallable(() -> doRerank(query, results, topK))
.subscribeOn(Schedulers.boundedElastic())
.retryWhen(
- Retry.backoff(3, Duration.ofSeconds(2)).maxBackoff(Duration.ofSeconds(10)))
- .onErrorResume(
- e -> {
- log.warn(
- "Rerank failed after 3 retries, returning original sorted topK"
- + " slice",
- e);
- return Mono.just(fallback(results, topK));
- });
+ Retry.backoff(3, Duration.ofSeconds(2)).maxBackoff(Duration.ofSeconds(10)));
}
private List doRerank(String query, List results, int topK)
@@ -192,6 +218,27 @@ public static double blendScore(
*/
public Mono> rerank(
String query, List results, RerankConfig rerankConfig) {
+ return LlmRerankerObservation.observe(
+ observationRegistry,
+ query,
+ results,
+ rerankConfig.topK(),
+ context ->
+ rerankInternal(query, results, rerankConfig)
+ .onErrorResume(
+ e -> {
+ context.markDegraded();
+ log.warn(
+ "Rerank failed after 3 retries, returning"
+ + " original sorted topK slice",
+ e);
+ return Mono.just(
+ fallback(results, rerankConfig.topK()));
+ }));
+ }
+
+ private Mono> rerankInternal(
+ String query, List results, RerankConfig rerankConfig) {
if (results.isEmpty() || !rerankConfig.enabled()) {
return Mono.just(results);
}
@@ -199,15 +246,7 @@ public Mono> rerank(
return Mono.fromCallable(() -> doRerank(query, results, rerankConfig))
.subscribeOn(Schedulers.boundedElastic())
.retryWhen(
- Retry.backoff(3, Duration.ofSeconds(2)).maxBackoff(Duration.ofSeconds(10)))
- .onErrorResume(
- e -> {
- log.warn(
- "Rerank failed after 3 retries, returning original sorted topK"
- + " slice",
- e);
- return Mono.just(fallback(results, rerankConfig.topK()));
- });
+ Retry.backoff(3, Duration.ofSeconds(2)).maxBackoff(Duration.ofSeconds(10)));
}
private List doRerank(
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/llm/rerank/observation/LlmRerankerObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/llm/rerank/observation/LlmRerankerObservation.java
new file mode 100644
index 00000000..b097ab24
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/llm/rerank/observation/LlmRerankerObservation.java
@@ -0,0 +1,253 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.llm.rerank.observation;
+
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import com.openmemind.ai.memory.core.observation.MemoryObservationContext;
+import com.openmemind.ai.memory.core.retrieval.scoring.ScoredResult;
+import com.openmemind.ai.memory.core.retrieval.trace.ObservationTiming;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceEvent;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceEventSource;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceOptions;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+import reactor.util.context.ContextView;
+
+/** Observation contracts for LlmReranker. */
+public final class LlmRerankerObservation {
+
+ private LlmRerankerObservation() {}
+
+ public static Mono> observe(
+ ObservationRegistry observationRegistry,
+ String query,
+ List results,
+ int topK,
+ Supplier>> operation) {
+ return observe(observationRegistry, query, results, topK, ignored -> operation.get());
+ }
+
+ public static Mono> observe(
+ ObservationRegistry observationRegistry,
+ String query,
+ List results,
+ int topK,
+ Function>> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ RerankDocument.RERANK,
+ RerankConvention.INSTANCE,
+ reactorContext ->
+ new RerankObservationContext(query, results, topK, reactorContext),
+ context -> operation.apply(context).doOnNext(context::recordResult));
+ }
+
+ public enum RerankDocument implements ObservationDocumentation {
+ RERANK;
+
+ @Override
+ public String getName() {
+ return "memind.retrieval.rerank";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return RerankConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ QUERY {
+ @Override
+ public String asString() {
+ return "memind.retrieval.query";
+ }
+ },
+ CANDIDATES {
+ @Override
+ public String asString() {
+ return "memind.retrieval.rerank.candidates";
+ }
+ },
+ TOP_K {
+ @Override
+ public String asString() {
+ return "memind.retrieval.top_k";
+ }
+ },
+ RESULT_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.result_count";
+ }
+ };
+ }
+
+ public static final class RerankObservationContext extends MemoryObservationContext
+ implements RetrievalTraceEventSource {
+
+ private final String query;
+ private final int candidateCount;
+ private final int topK;
+ private List results = List.of();
+ private boolean degraded;
+
+ public RerankObservationContext(String query, List results, int topK) {
+ this(query, results, topK, null);
+ }
+
+ public RerankObservationContext(
+ String query, List results, int topK, ContextView reactorContext) {
+ super(reactorContext);
+ this.query = query;
+ this.candidateCount = results == null ? 0 : results.size();
+ this.topK = topK;
+ }
+
+ public void recordResult(List results) {
+ this.results = results == null ? List.of() : List.copyOf(results);
+ addHighCardinalityKeyValue(
+ HighCardinalityKeyNames.RESULT_COUNT.withValue(String.valueOf(resultCount())));
+ }
+
+ public int inputCount() {
+ return candidateCount;
+ }
+
+ public int candidateCount() {
+ return candidateCount;
+ }
+
+ public int resultCount() {
+ return results.size();
+ }
+
+ public void markDegraded() {
+ degraded = true;
+ }
+
+ public boolean degraded() {
+ return degraded;
+ }
+
+ public boolean skipped() {
+ return topK <= 0 || candidateCount == 0;
+ }
+
+ public String stage() {
+ return "rerank";
+ }
+
+ public String tier() {
+ return "item";
+ }
+
+ public String method() {
+ return "rerank";
+ }
+
+ public String source() {
+ return "core";
+ }
+
+ @Override
+ public String status() {
+ String terminalStatus = errorOrCancellationStatus();
+ return terminalStatus == null && degraded ? "degraded" : super.status();
+ }
+
+ @Override
+ public Optional toRetrievalTraceEvent(
+ ObservationTiming timing, RetrievalTraceOptions options) {
+ return Optional.of(
+ new RetrievalTraceEvent(
+ RerankDocument.RERANK.getName(),
+ RerankDocument.RERANK.getName(),
+ status(),
+ timing.startedAt(),
+ timing.completedAt(),
+ timing.durationMillis(),
+ Map.of("operation", "retrieval", "stage", stage()),
+ Map.of(
+ HighCardinalityKeyNames.CANDIDATES.asString(),
+ String.valueOf(candidateCount),
+ HighCardinalityKeyNames.RESULT_COUNT.asString(),
+ String.valueOf(resultCount())),
+ new RetrievalTraceEvent.StagePayload(
+ stage(),
+ tier(),
+ method(),
+ inputCount(),
+ candidateCount(),
+ resultCount(),
+ degraded(),
+ skipped(),
+ Map.of("topK", topK),
+ RetrievalTraceEvent.candidates(
+ results,
+ options.maxCandidatesPerStage(),
+ options.maxTextLength()))));
+ }
+ }
+
+ public static final class RerankConvention
+ implements ObservationConvention {
+
+ public static final RerankConvention INSTANCE = new RerankConvention();
+
+ @Override
+ public String getName() {
+ return RerankDocument.RERANK.getName();
+ }
+
+ @Override
+ public String getContextualName(RerankObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(RerankObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.QUERY.withValue(safe(context.query)),
+ HighCardinalityKeyNames.CANDIDATES.withValue(
+ String.valueOf(context.candidateCount)),
+ HighCardinalityKeyNames.TOP_K.withValue(String.valueOf(context.topK)));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof RerankObservationContext;
+ }
+ }
+
+ private static String safe(String value) {
+ return value == null ? "" : value;
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/ExtractionMetrics.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/ExtractionMetrics.java
deleted file mode 100644
index 1fecbda8..00000000
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/ExtractionMetrics.java
+++ /dev/null
@@ -1,26 +0,0 @@
-/*
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.openmemind.ai.memory.core.metrics;
-
-public record ExtractionMetrics(
- String status,
- int rawDataCount,
- Integer segmentCount,
- int newItemCount,
- Integer reinforcedItemCount,
- int insightCount,
- Integer graphEntityCount,
- Integer graphMentionCount,
- Integer graphRelationCount,
- String source) {}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/ExtractionMetricsExtractor.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/ExtractionMetricsExtractor.java
deleted file mode 100644
index e3b48367..00000000
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/ExtractionMetricsExtractor.java
+++ /dev/null
@@ -1,65 +0,0 @@
-/*
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.openmemind.ai.memory.core.metrics;
-
-import com.openmemind.ai.memory.core.extraction.ExtractionResult;
-import com.openmemind.ai.memory.core.extraction.ExtractionStatus;
-import com.openmemind.ai.memory.core.extraction.item.graph.ItemGraphMaterializationResult;
-import com.openmemind.ai.memory.core.extraction.result.MemoryItemResult;
-
-public final class ExtractionMetricsExtractor {
-
- private ExtractionMetricsExtractor() {}
-
- public static ExtractionMetrics extract(ExtractionResult result, String source) {
- if (result == null) {
- return new ExtractionMetrics(
- "unknown", 0, null, 0, null, 0, null, null, null, sourceOrCore(source));
- }
- MemoryItemResult itemResult = result.memoryItemResult();
- ItemGraphMaterializationResult graph =
- itemResult == null ? null : itemResult.graphMaterializationResult();
- ItemGraphMaterializationResult.Stats stats = graph == null ? null : graph.stats();
- return new ExtractionMetrics(
- status(result.status()),
- result.rawDataResult() == null ? 0 : result.rawDataResult().rawDataList().size(),
- result.rawDataResult() == null ? null : result.rawDataResult().segments().size(),
- itemResult == null ? 0 : itemResult.newCount(),
- null,
- result.totalInsights(),
- stats == null ? null : stats.entityCount(),
- stats == null ? null : stats.mentionCount(),
- finalRelationCount(stats),
- sourceOrCore(source));
- }
-
- private static Integer finalRelationCount(ItemGraphMaterializationResult.Stats stats) {
- if (stats == null || stats.finalRelationStats() == null) {
- return null;
- }
- var finalStats = stats.finalRelationStats();
- return finalStats.semanticRelationCount()
- + finalStats.temporalRelationCount()
- + finalStats.causalRelationCount()
- + finalStats.itemLinkCount();
- }
-
- private static String status(ExtractionStatus status) {
- return status == null ? "unknown" : status.name().toLowerCase();
- }
-
- private static String sourceOrCore(String source) {
- return source == null || source.isBlank() ? "core" : source;
- }
-}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/MemoryMetricsRecorder.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/MemoryMetricsRecorder.java
deleted file mode 100644
index d3f76b5c..00000000
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/MemoryMetricsRecorder.java
+++ /dev/null
@@ -1,25 +0,0 @@
-/*
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.openmemind.ai.memory.core.metrics;
-
-public interface MemoryMetricsRecorder {
-
- void recordExtractionSummary(ExtractionMetrics metrics);
-
- void recordRetrievalStage(RetrievalStageMetrics metrics);
-
- void recordRetrievalMerge(RetrievalMergeMetrics metrics);
-
- void recordRetrievalSummary(RetrievalSummaryMetrics metrics);
-}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/NoopMemoryMetricsRecorder.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/NoopMemoryMetricsRecorder.java
deleted file mode 100644
index ee15433b..00000000
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/NoopMemoryMetricsRecorder.java
+++ /dev/null
@@ -1,30 +0,0 @@
-/*
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.openmemind.ai.memory.core.metrics;
-
-public enum NoopMemoryMetricsRecorder implements MemoryMetricsRecorder {
- INSTANCE;
-
- @Override
- public void recordExtractionSummary(ExtractionMetrics metrics) {}
-
- @Override
- public void recordRetrievalStage(RetrievalStageMetrics metrics) {}
-
- @Override
- public void recordRetrievalMerge(RetrievalMergeMetrics metrics) {}
-
- @Override
- public void recordRetrievalSummary(RetrievalSummaryMetrics metrics) {}
-}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalMetricsSupport.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalMetricsSupport.java
deleted file mode 100644
index 4bc8382c..00000000
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalMetricsSupport.java
+++ /dev/null
@@ -1,54 +0,0 @@
-/*
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.openmemind.ai.memory.core.metrics;
-
-import com.openmemind.ai.memory.core.retrieval.RetrievalResult;
-
-public final class RetrievalMetricsSupport {
-
- private RetrievalMetricsSupport() {}
-
- public static RetrievalSummaryMetrics summary(
- String strategy, RetrievalResult result, String source) {
- String status = result == null ? "empty" : result.status().name().toLowerCase();
- return new RetrievalSummaryMetrics(
- strategyOrUnknown(strategy),
- status,
- result == null || result.items() == null ? 0 : result.items().size(),
- result == null || result.insights() == null ? 0 : result.insights().size(),
- result == null || result.rawData() == null ? 0 : result.rawData().size(),
- result == null || result.evidences() == null ? 0 : result.evidences().size(),
- sourceOrCore(source));
- }
-
- public static int deduplicatedCount(int inputCount, int outputCount) {
- return Math.max(0, inputCount - outputCount);
- }
-
- public static void safeRecord(Runnable recorder) {
- try {
- recorder.run();
- } catch (RuntimeException ignored) {
- // Metrics collection must never affect memory operations.
- }
- }
-
- public static String strategyOrUnknown(String strategy) {
- return strategy == null || strategy.isBlank() ? "unknown" : strategy;
- }
-
- public static String sourceOrCore(String source) {
- return source == null || source.isBlank() ? "core" : source;
- }
-}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalStageMetrics.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalStageMetrics.java
deleted file mode 100644
index d68ee4f0..00000000
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalStageMetrics.java
+++ /dev/null
@@ -1,27 +0,0 @@
-/*
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.openmemind.ai.memory.core.metrics;
-
-public record RetrievalStageMetrics(
- String strategy,
- String stage,
- String tier,
- String method,
- String status,
- Integer inputCount,
- Integer candidateCount,
- Integer resultCount,
- boolean degraded,
- boolean skipped,
- String source) {}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalSummaryMetrics.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalSummaryMetrics.java
deleted file mode 100644
index 70e9e596..00000000
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/metrics/RetrievalSummaryMetrics.java
+++ /dev/null
@@ -1,33 +0,0 @@
-/*
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.openmemind.ai.memory.core.metrics;
-
-public record RetrievalSummaryMetrics(
- String strategy,
- String status,
- int itemCount,
- int insightCount,
- int rawDataCount,
- int evidenceCount,
- String source) {
-
- public int countFor(RetrievalResultType type) {
- return switch (type) {
- case ITEM -> itemCount;
- case INSIGHT -> insightCount;
- case RAW_DATA -> rawDataCount;
- case EVIDENCE -> evidenceCount;
- };
- }
-}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/observation/MemoryObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/observation/MemoryObservation.java
new file mode 100644
index 00000000..7291a936
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/observation/MemoryObservation.java
@@ -0,0 +1,138 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.observation;
+
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.Objects;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.observability.micrometer.Micrometer;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+import reactor.util.context.ContextView;
+
+/** Shared Reactor + Micrometer Observation template for memory components. */
+public final class MemoryObservation {
+
+ private MemoryObservation() {}
+
+ public static Mono mono(
+ ObservationRegistry observationRegistry,
+ ObservationDocumentation document,
+ ObservationConvention convention,
+ Supplier contextFactory,
+ Function> operation) {
+ Objects.requireNonNull(contextFactory, "contextFactory");
+ return mono(
+ observationRegistry,
+ document,
+ convention,
+ ignored -> contextFactory.get(),
+ operation);
+ }
+
+ public static Mono mono(
+ ObservationRegistry observationRegistry,
+ ObservationDocumentation document,
+ ObservationConvention convention,
+ Function contextFactory,
+ Function> operation) {
+ Objects.requireNonNull(document, "document");
+ Objects.requireNonNull(convention, "convention");
+ Objects.requireNonNull(contextFactory, "contextFactory");
+ Objects.requireNonNull(operation, "operation");
+ ObservationRegistry registry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
+ return Mono.deferContextual(
+ reactorContext -> {
+ ContextT context = contextFactory.apply(reactorContext);
+ Mono publisher;
+ try {
+ publisher =
+ Objects.requireNonNull(
+ operation.apply(context), "operation returned null");
+ } catch (Throwable error) {
+ publisher = Mono.error(error);
+ }
+ return publisher
+ .doOnError(context::setError)
+ .name(document.getName())
+ .tap(
+ Micrometer.observation(
+ registry,
+ actualRegistry ->
+ document.observation(
+ null,
+ convention,
+ () -> context,
+ actualRegistry)));
+ });
+ }
+
+ public static Flux flux(
+ ObservationRegistry observationRegistry,
+ ObservationDocumentation document,
+ ObservationConvention convention,
+ Supplier contextFactory,
+ Function> operation) {
+ Objects.requireNonNull(contextFactory, "contextFactory");
+ return flux(
+ observationRegistry,
+ document,
+ convention,
+ ignored -> contextFactory.get(),
+ operation);
+ }
+
+ public static Flux flux(
+ ObservationRegistry observationRegistry,
+ ObservationDocumentation document,
+ ObservationConvention convention,
+ Function contextFactory,
+ Function> operation) {
+ Objects.requireNonNull(document, "document");
+ Objects.requireNonNull(convention, "convention");
+ Objects.requireNonNull(contextFactory, "contextFactory");
+ Objects.requireNonNull(operation, "operation");
+ ObservationRegistry registry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
+ return Flux.deferContextual(
+ reactorContext -> {
+ ContextT context = contextFactory.apply(reactorContext);
+ Flux publisher;
+ try {
+ publisher =
+ Objects.requireNonNull(
+ operation.apply(context), "operation returned null");
+ } catch (Throwable error) {
+ publisher = Flux.error(error);
+ }
+ return publisher
+ .doOnError(context::setError)
+ .name(document.getName())
+ .tap(
+ Micrometer.observation(
+ registry,
+ actualRegistry ->
+ document.observation(
+ null,
+ convention,
+ () -> context,
+ actualRegistry)));
+ });
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/observation/MemoryObservationContext.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/observation/MemoryObservationContext.java
new file mode 100644
index 00000000..b714e82a
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/observation/MemoryObservationContext.java
@@ -0,0 +1,55 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.observation;
+
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceRecorder;
+import io.micrometer.observation.Observation;
+import java.util.Optional;
+import reactor.util.context.ContextView;
+
+/** Base observation context with request-scoped memory observability state. */
+public abstract class MemoryObservationContext extends Observation.Context {
+
+ private static final String REACTOR_STATUS = "reactor.status";
+ private static final String CANCELLED = "cancelled";
+
+ protected MemoryObservationContext() {}
+
+ protected MemoryObservationContext(ContextView reactorContext) {
+ if (reactorContext != null) {
+ reactorContext
+ .getOrEmpty(RetrievalTraceRecorder.class)
+ .ifPresent(recorder -> put(RetrievalTraceRecorder.class, recorder));
+ }
+ }
+
+ public Optional traceRecorder() {
+ return Optional.ofNullable(get(RetrievalTraceRecorder.class));
+ }
+
+ public String status() {
+ String terminalStatus = errorOrCancellationStatus();
+ return terminalStatus == null ? "success" : terminalStatus;
+ }
+
+ protected String errorOrCancellationStatus() {
+ if (getError() != null) {
+ return "error";
+ }
+ var reactorStatus = getLowCardinalityKeyValue(REACTOR_STATUS);
+ return reactorStatus != null && CANCELLED.equals(reactorStatus.getValue())
+ ? CANCELLED
+ : null;
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/DefaultMemoryRetriever.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/DefaultMemoryRetriever.java
index 0c08db8a..f2d2bca5 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/DefaultMemoryRetriever.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/DefaultMemoryRetriever.java
@@ -19,12 +19,14 @@
import com.openmemind.ai.memory.core.retrieval.admission.RetrievalAdmissionOptions;
import com.openmemind.ai.memory.core.retrieval.admission.RetrievalAdmissionPolicy;
import com.openmemind.ai.memory.core.retrieval.admission.RetrievalAdmissionResult;
+import com.openmemind.ai.memory.core.retrieval.observation.DefaultMemoryRetrieverObservation;
import com.openmemind.ai.memory.core.retrieval.query.LongQueryCondenser;
import com.openmemind.ai.memory.core.retrieval.query.QueryContext;
import com.openmemind.ai.memory.core.retrieval.query.QueryRewriter;
import com.openmemind.ai.memory.core.retrieval.strategy.RetrievalStrategy;
import com.openmemind.ai.memory.core.store.MemoryStore;
import com.openmemind.ai.memory.core.textsearch.MemoryTextSearch;
+import io.micrometer.observation.ObservationRegistry;
import java.util.List;
import java.util.Map;
import java.util.Objects;
@@ -52,6 +54,7 @@ public class DefaultMemoryRetriever implements MemoryRetriever {
private final RetrievalAdmissionPolicy admissionPolicy;
private final RetrievalAdmissionOptions admissionOptions;
private final LongQueryCondenser longQueryCondenser; // nullable for legacy constructors
+ private final ObservationRegistry observationRegistry;
public DefaultMemoryRetriever(MemoryStore memoryStore) {
this(memoryStore, null, null);
@@ -93,6 +96,24 @@ public DefaultMemoryRetriever(
RetrievalAdmissionPolicy admissionPolicy,
RetrievalAdmissionOptions admissionOptions,
LongQueryCondenser longQueryCondenser) {
+ this(
+ memoryStore,
+ textSearch,
+ queryRewriter,
+ admissionPolicy,
+ admissionOptions,
+ longQueryCondenser,
+ ObservationRegistry.NOOP);
+ }
+
+ public DefaultMemoryRetriever(
+ MemoryStore memoryStore,
+ MemoryTextSearch textSearch,
+ QueryRewriter queryRewriter,
+ RetrievalAdmissionPolicy admissionPolicy,
+ RetrievalAdmissionOptions admissionOptions,
+ LongQueryCondenser longQueryCondenser,
+ ObservationRegistry observationRegistry) {
this.memoryStore = Objects.requireNonNull(memoryStore, "memoryStore must not be null");
this.textSearch = textSearch; // nullable
this.queryRewriter = queryRewriter; // nullable
@@ -101,6 +122,8 @@ public DefaultMemoryRetriever(
this.admissionOptions =
Objects.requireNonNull(admissionOptions, "admissionOptions must not be null");
this.longQueryCondenser = longQueryCondenser;
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
this.strategies = new ConcurrentHashMap<>();
}
@@ -131,6 +154,12 @@ public Mono retrieve(RetrievalRequest request) {
+ " query, strategy)");
}
+ return DefaultMemoryRetrieverObservation.observe(
+ observationRegistry, request.memoryId(), () -> retrieveInternal(request, config));
+ }
+
+ private Mono retrieveInternal(
+ RetrievalRequest request, RetrievalConfig config) {
RetrievalAdmissionResult admission = admissionPolicy.evaluate(request);
if (admission.decision() == RetrievalAdmissionDecision.SKIP
|| admission.decision() == RetrievalAdmissionDecision.REJECT) {
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/deep/LlmTypedQueryExpander.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/deep/LlmTypedQueryExpander.java
index 7a5d8038..795a2c30 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/deep/LlmTypedQueryExpander.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/deep/LlmTypedQueryExpander.java
@@ -18,6 +18,8 @@
import com.openmemind.ai.memory.core.prompt.PromptRegistry;
import com.openmemind.ai.memory.core.prompt.retrieval.TypedQueryExpandPrompts;
import com.openmemind.ai.memory.core.retrieval.deep.ExpandedQuery.QueryType;
+import com.openmemind.ai.memory.core.retrieval.deep.observation.LlmTypedQueryExpanderObservation;
+import io.micrometer.observation.ObservationRegistry;
import java.time.Duration;
import java.util.List;
import java.util.Objects;
@@ -40,6 +42,7 @@ public class LlmTypedQueryExpander implements TypedQueryExpander {
private final StructuredChatClient structuredChatClient;
private final PromptRegistry promptRegistry;
+ private final ObservationRegistry observationRegistry;
public LlmTypedQueryExpander(StructuredChatClient structuredChatClient) {
this(structuredChatClient, PromptRegistry.EMPTY);
@@ -47,11 +50,20 @@ public LlmTypedQueryExpander(StructuredChatClient structuredChatClient) {
public LlmTypedQueryExpander(
StructuredChatClient structuredChatClient, PromptRegistry promptRegistry) {
+ this(structuredChatClient, promptRegistry, ObservationRegistry.NOOP);
+ }
+
+ public LlmTypedQueryExpander(
+ StructuredChatClient structuredChatClient,
+ PromptRegistry promptRegistry,
+ ObservationRegistry observationRegistry) {
this.structuredChatClient =
Objects.requireNonNull(
structuredChatClient, "structuredChatClient must not be null");
this.promptRegistry =
Objects.requireNonNull(promptRegistry, "promptRegistry must not be null");
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
@@ -61,35 +73,51 @@ public Mono> expand(
List keyInformation,
List conversationHistory,
int maxExpansions) {
- return Mono.defer(
- () -> {
- var promptResult =
- TypedQueryExpandPrompts.build(
- promptRegistry,
- query,
- gaps,
- keyInformation,
- conversationHistory,
- maxExpansions)
- .render("English");
- var messages =
- ChatMessages.systemUser(
- promptResult.systemPrompt(), promptResult.userPrompt());
- return structuredChatClient
- .call(messages, TypedExpandResponse.class)
- .map(response -> toExpandedQueries(response, maxExpansions))
- .switchIfEmpty(Mono.just(List.of()));
- })
- .subscribeOn(Schedulers.boundedElastic())
- .retryWhen(
- Retry.backoff(3, Duration.ofSeconds(2)).maxBackoff(Duration.ofSeconds(10)))
- .onErrorResume(
- e -> {
- log.warn(
- "Type-annotated query expansion failed, returning empty list",
- e);
- return Mono.just(List.of());
- });
+ Mono> operation =
+ Mono.defer(
+ () -> {
+ var promptResult =
+ TypedQueryExpandPrompts.build(
+ promptRegistry,
+ query,
+ gaps,
+ keyInformation,
+ conversationHistory,
+ maxExpansions)
+ .render("English");
+ var messages =
+ ChatMessages.systemUser(
+ promptResult.systemPrompt(),
+ promptResult.userPrompt());
+ return structuredChatClient
+ .call(messages, TypedExpandResponse.class)
+ .map(
+ response ->
+ toExpandedQueries(
+ response, maxExpansions))
+ .switchIfEmpty(Mono.just(List.of()));
+ })
+ .subscribeOn(Schedulers.boundedElastic())
+ .retryWhen(
+ Retry.backoff(3, Duration.ofSeconds(2))
+ .maxBackoff(Duration.ofSeconds(10)));
+ return LlmTypedQueryExpanderObservation.observe(
+ observationRegistry,
+ query,
+ gaps,
+ keyInformation,
+ conversationHistory,
+ maxExpansions,
+ context ->
+ operation.onErrorResume(
+ e -> {
+ context.markDegraded();
+ log.warn(
+ "Type-annotated query expansion failed, returning empty"
+ + " list",
+ e);
+ return Mono.just(List.of());
+ }));
}
private List toExpandedQueries(TypedExpandResponse response, int maxExpansions) {
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/deep/observation/LlmTypedQueryExpanderObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/deep/observation/LlmTypedQueryExpanderObservation.java
new file mode 100644
index 00000000..b3e87c21
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/deep/observation/LlmTypedQueryExpanderObservation.java
@@ -0,0 +1,310 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.retrieval.deep.observation;
+
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import com.openmemind.ai.memory.core.observation.MemoryObservationContext;
+import com.openmemind.ai.memory.core.retrieval.deep.ExpandedQuery;
+import com.openmemind.ai.memory.core.retrieval.trace.ObservationTiming;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceEvent;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceEventSource;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceOptions;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+import reactor.util.context.ContextView;
+
+/** Observation contracts for LlmTypedQueryExpander. */
+public final class LlmTypedQueryExpanderObservation {
+
+ private LlmTypedQueryExpanderObservation() {}
+
+ public static Mono> observe(
+ ObservationRegistry observationRegistry,
+ String query,
+ List gaps,
+ List keyInformation,
+ List conversationHistory,
+ int maxExpansions,
+ Supplier>> operation) {
+ return observe(
+ observationRegistry,
+ query,
+ gaps,
+ keyInformation,
+ conversationHistory,
+ maxExpansions,
+ ignored -> operation.get());
+ }
+
+ public static Mono> observe(
+ ObservationRegistry observationRegistry,
+ String query,
+ List gaps,
+ List keyInformation,
+ List conversationHistory,
+ int maxExpansions,
+ Function>> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ MultiQueryExpandDocument.EXPAND,
+ MultiQueryExpandConvention.INSTANCE,
+ reactorContext ->
+ new MultiQueryExpandObservationContext(
+ query,
+ gaps,
+ keyInformation,
+ conversationHistory,
+ maxExpansions,
+ reactorContext),
+ context -> operation.apply(context).doOnNext(context::recordResult));
+ }
+
+ public enum MultiQueryExpandDocument implements ObservationDocumentation {
+ EXPAND;
+
+ @Override
+ public String getName() {
+ return "memind.retrieval.multi_query_expand";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return MultiQueryExpandConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ QUERY {
+ @Override
+ public String asString() {
+ return "memind.retrieval.query";
+ }
+ },
+ GAP_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.gap_count";
+ }
+ },
+ KEY_INFORMATION_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.key_information_count";
+ }
+ },
+ CONVERSATION_HISTORY_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.conversation_history_count";
+ }
+ },
+ MAX_EXPANSIONS {
+ @Override
+ public String asString() {
+ return "memind.retrieval.max_expansions";
+ }
+ },
+ RESULT_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.result_count";
+ }
+ };
+ }
+
+ public static final class MultiQueryExpandObservationContext extends MemoryObservationContext
+ implements RetrievalTraceEventSource {
+
+ private final String query;
+ private final int gapCount;
+ private final int keyInformationCount;
+ private final int conversationHistoryCount;
+ private final int maxExpansions;
+ private List results = List.of();
+ private boolean degraded;
+
+ public MultiQueryExpandObservationContext(
+ String query,
+ List gaps,
+ List keyInformation,
+ List conversationHistory,
+ int maxExpansions) {
+ this(query, gaps, keyInformation, conversationHistory, maxExpansions, null);
+ }
+
+ public MultiQueryExpandObservationContext(
+ String query,
+ List gaps,
+ List keyInformation,
+ List conversationHistory,
+ int maxExpansions,
+ ContextView reactorContext) {
+ super(reactorContext);
+ this.query = query;
+ this.gapCount = gaps == null ? 0 : gaps.size();
+ this.keyInformationCount = keyInformation == null ? 0 : keyInformation.size();
+ this.conversationHistoryCount =
+ conversationHistory == null ? 0 : conversationHistory.size();
+ this.maxExpansions = maxExpansions;
+ }
+
+ public void recordResult(List results) {
+ this.results = results == null ? List.of() : List.copyOf(results);
+ addHighCardinalityKeyValue(
+ HighCardinalityKeyNames.RESULT_COUNT.withValue(String.valueOf(resultCount())));
+ }
+
+ public int inputCount() {
+ return gapCount;
+ }
+
+ public int candidateCount() {
+ return maxExpansions;
+ }
+
+ public int resultCount() {
+ return results.size();
+ }
+
+ public void markDegraded() {
+ degraded = true;
+ }
+
+ public String stage() {
+ return "query_expand";
+ }
+
+ public String tier() {
+ return "none";
+ }
+
+ public String method() {
+ return "llm";
+ }
+
+ public boolean degraded() {
+ return degraded;
+ }
+
+ public boolean skipped() {
+ return maxExpansions <= 0;
+ }
+
+ public String source() {
+ return "core";
+ }
+
+ @Override
+ public String status() {
+ String terminalStatus = errorOrCancellationStatus();
+ return terminalStatus == null && degraded ? "degraded" : super.status();
+ }
+
+ @Override
+ public Optional toRetrievalTraceEvent(
+ ObservationTiming timing, RetrievalTraceOptions options) {
+ return Optional.of(
+ new RetrievalTraceEvent(
+ MultiQueryExpandDocument.EXPAND.getName(),
+ MultiQueryExpandDocument.EXPAND.getName(),
+ status(),
+ timing.startedAt(),
+ timing.completedAt(),
+ timing.durationMillis(),
+ Map.of("operation", "retrieval", "stage", stage()),
+ Map.of(
+ HighCardinalityKeyNames.GAP_COUNT.asString(),
+ String.valueOf(gapCount),
+ HighCardinalityKeyNames.RESULT_COUNT.asString(),
+ String.valueOf(resultCount())),
+ new RetrievalTraceEvent.StagePayload(
+ stage(),
+ tier(),
+ method(),
+ inputCount(),
+ candidateCount(),
+ resultCount(),
+ degraded(),
+ skipped(),
+ attributes(),
+ List.of())));
+ }
+
+ private Map attributes() {
+ return Map.of(
+ "gapCount",
+ gapCount,
+ "keyInformationCount",
+ keyInformationCount,
+ "conversationHistoryCount",
+ conversationHistoryCount,
+ "maxExpansions",
+ maxExpansions);
+ }
+ }
+
+ public static final class MultiQueryExpandConvention
+ implements ObservationConvention {
+
+ public static final MultiQueryExpandConvention INSTANCE = new MultiQueryExpandConvention();
+
+ @Override
+ public String getName() {
+ return MultiQueryExpandDocument.EXPAND.getName();
+ }
+
+ @Override
+ public String getContextualName(MultiQueryExpandObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(MultiQueryExpandObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.QUERY.withValue(safe(context.query)),
+ HighCardinalityKeyNames.GAP_COUNT.withValue(String.valueOf(context.gapCount)),
+ HighCardinalityKeyNames.KEY_INFORMATION_COUNT.withValue(
+ String.valueOf(context.keyInformationCount)),
+ HighCardinalityKeyNames.CONVERSATION_HISTORY_COUNT.withValue(
+ String.valueOf(context.conversationHistoryCount)),
+ HighCardinalityKeyNames.MAX_EXPANSIONS.withValue(
+ String.valueOf(context.maxExpansions)));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof MultiQueryExpandObservationContext;
+ }
+ }
+
+ private static String safe(String value) {
+ return value == null ? "" : value;
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/DefaultGraphItemChannel.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/DefaultGraphItemChannel.java
index 82c51fc0..02df1e91 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/DefaultGraphItemChannel.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/DefaultGraphItemChannel.java
@@ -14,9 +14,11 @@
package com.openmemind.ai.memory.core.retrieval.graph;
import com.openmemind.ai.memory.core.retrieval.RetrievalConfig;
+import com.openmemind.ai.memory.core.retrieval.graph.observation.DefaultGraphItemChannelObservation;
import com.openmemind.ai.memory.core.retrieval.query.QueryContext;
import com.openmemind.ai.memory.core.retrieval.scoring.ScoredResult;
import com.openmemind.ai.memory.core.store.graph.GraphQueryBudgetContext;
+import io.micrometer.observation.ObservationRegistry;
import java.time.Duration;
import java.util.List;
import java.util.concurrent.TimeoutException;
@@ -30,9 +32,17 @@ public final class DefaultGraphItemChannel implements GraphItemChannel {
private static final Logger log = LoggerFactory.getLogger(DefaultGraphItemChannel.class);
private final GraphExpansionEngine engine;
+ private final ObservationRegistry observationRegistry;
public DefaultGraphItemChannel(GraphExpansionEngine engine) {
+ this(engine, ObservationRegistry.NOOP);
+ }
+
+ public DefaultGraphItemChannel(
+ GraphExpansionEngine engine, ObservationRegistry observationRegistry) {
this.engine = engine;
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
@@ -41,6 +51,19 @@ public Mono retrieve(
RetrievalConfig config,
RetrievalGraphSettings settings,
List seeds) {
+ return DefaultGraphItemChannelObservation.observe(
+ observationRegistry,
+ context,
+ settings,
+ seeds,
+ () -> retrieveInternal(context, config, settings, seeds));
+ }
+
+ private Mono retrieveInternal(
+ QueryContext context,
+ RetrievalConfig config,
+ RetrievalGraphSettings settings,
+ List seeds) {
boolean enabled = settings != null && settings.enabled();
if (!enabled || seeds == null || seeds.isEmpty() || engine == null) {
return Mono.just(GraphExpansionResult.empty(enabled));
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/DefaultRetrievalGraphAssistant.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/DefaultRetrievalGraphAssistant.java
index 76c2b226..5dd0d183 100644
--- a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/DefaultRetrievalGraphAssistant.java
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/DefaultRetrievalGraphAssistant.java
@@ -14,10 +14,12 @@
package com.openmemind.ai.memory.core.retrieval.graph;
import com.openmemind.ai.memory.core.retrieval.RetrievalConfig;
+import com.openmemind.ai.memory.core.retrieval.graph.observation.DefaultRetrievalGraphAssistantObservation;
import com.openmemind.ai.memory.core.retrieval.query.QueryContext;
import com.openmemind.ai.memory.core.retrieval.scoring.ScoredResult;
import com.openmemind.ai.memory.core.store.MemoryStore;
import com.openmemind.ai.memory.core.store.graph.GraphQueryBudgetContext;
+import io.micrometer.observation.ObservationRegistry;
import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
@@ -37,14 +39,22 @@
public final class DefaultRetrievalGraphAssistant implements RetrievalGraphAssistant {
private final GraphExpansionEngine graphExpansionEngine;
+ private final ObservationRegistry observationRegistry;
public DefaultRetrievalGraphAssistant(MemoryStore store) {
this(new GraphExpansionEngine(store));
}
public DefaultRetrievalGraphAssistant(GraphExpansionEngine graphExpansionEngine) {
+ this(graphExpansionEngine, ObservationRegistry.NOOP);
+ }
+
+ public DefaultRetrievalGraphAssistant(
+ GraphExpansionEngine graphExpansionEngine, ObservationRegistry observationRegistry) {
this.graphExpansionEngine =
Objects.requireNonNull(graphExpansionEngine, "graphExpansionEngine");
+ this.observationRegistry =
+ observationRegistry == null ? ObservationRegistry.NOOP : observationRegistry;
}
@Override
@@ -53,6 +63,19 @@ public Mono assist(
RetrievalConfig config,
RetrievalGraphSettings graphSettings,
List directItems) {
+ return DefaultRetrievalGraphAssistantObservation.observe(
+ observationRegistry,
+ context,
+ graphSettings,
+ directItems,
+ () -> assistInternal(context, config, graphSettings, directItems));
+ }
+
+ private Mono assistInternal(
+ QueryContext context,
+ RetrievalConfig config,
+ RetrievalGraphSettings graphSettings,
+ List directItems) {
boolean enabled = graphSettings != null && graphSettings.enabled();
if (!enabled || directItems == null || directItems.isEmpty()) {
return Mono.just(RetrievalGraphAssistResult.directOnly(directItems, enabled));
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/observation/DefaultGraphItemChannelObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/observation/DefaultGraphItemChannelObservation.java
new file mode 100644
index 00000000..8cb8472d
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/observation/DefaultGraphItemChannelObservation.java
@@ -0,0 +1,352 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.retrieval.graph.observation;
+
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import com.openmemind.ai.memory.core.observation.MemoryObservationContext;
+import com.openmemind.ai.memory.core.retrieval.graph.GraphExpansionResult;
+import com.openmemind.ai.memory.core.retrieval.graph.RetrievalGraphSettings;
+import com.openmemind.ai.memory.core.retrieval.query.QueryContext;
+import com.openmemind.ai.memory.core.retrieval.scoring.ScoredResult;
+import com.openmemind.ai.memory.core.retrieval.trace.ObservationTiming;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceEvent;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceEventSource;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceOptions;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+import reactor.util.context.ContextView;
+
+/** Observation contracts for DefaultGraphItemChannel. */
+public final class DefaultGraphItemChannelObservation {
+
+ private DefaultGraphItemChannelObservation() {}
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ QueryContext queryContext,
+ RetrievalGraphSettings settings,
+ List seeds,
+ Supplier> operation) {
+ return observe(
+ observationRegistry, queryContext, settings, seeds, ignored -> operation.get());
+ }
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ QueryContext queryContext,
+ RetrievalGraphSettings settings,
+ List seeds,
+ Function> operation) {
+ return MemoryObservation.mono(
+ observationRegistry,
+ GraphItemChannelDocument.RETRIEVE,
+ GraphItemChannelConvention.INSTANCE,
+ reactorContext ->
+ new GraphItemChannelObservationContext(
+ queryContext, settings, seeds, reactorContext),
+ context -> operation.apply(context).doOnNext(context::recordResult));
+ }
+
+ public enum GraphItemChannelDocument implements ObservationDocumentation {
+ RETRIEVE;
+
+ @Override
+ public String getName() {
+ return "memind.retrieval.channel.graph";
+ }
+
+ @Override
+ public Class>
+ getDefaultConvention() {
+ return GraphItemChannelConvention.class;
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+ MEMORY_ID {
+ @Override
+ public String asString() {
+ return "memind.memory_id";
+ }
+ },
+ CHANNEL {
+ @Override
+ public String asString() {
+ return "memind.retrieval.channel";
+ }
+ },
+ GRAPH_ENABLED {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.enabled";
+ }
+ },
+ GRAPH_SEED_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.seed_count";
+ }
+ },
+ RESULT_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.result_count";
+ }
+ },
+ GRAPH_LINK_EXPANSION_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.link_expansion_count";
+ }
+ },
+ GRAPH_ENTITY_EXPANSION_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.entity_expansion_count";
+ }
+ },
+ GRAPH_DEDUPED_CANDIDATE_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.deduped_candidate_count";
+ }
+ },
+ GRAPH_OVERLAP_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.overlap_count";
+ }
+ },
+ GRAPH_SKIPPED_OVERFANOUT_ENTITY_COUNT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.skipped_overfanout_entity_count";
+ }
+ },
+ GRAPH_TIMEOUT {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.timeout";
+ }
+ },
+ GRAPH_DEGRADED {
+ @Override
+ public String asString() {
+ return "memind.retrieval.graph.degraded";
+ }
+ };
+ }
+
+ public static final class GraphItemChannelObservationContext extends MemoryObservationContext
+ implements RetrievalTraceEventSource {
+
+ private final QueryContext queryContext;
+ private final RetrievalGraphSettings settings;
+ private final int seedCount;
+ private GraphExpansionResult result;
+
+ public GraphItemChannelObservationContext(
+ QueryContext queryContext,
+ RetrievalGraphSettings settings,
+ List seeds) {
+ this(queryContext, settings, seeds, null);
+ }
+
+ public GraphItemChannelObservationContext(
+ QueryContext queryContext,
+ RetrievalGraphSettings settings,
+ List seeds,
+ ContextView reactorContext) {
+ super(reactorContext);
+ this.queryContext = queryContext;
+ this.settings = settings;
+ this.seedCount = seeds == null ? 0 : seeds.size();
+ }
+
+ public void recordResult(GraphExpansionResult result) {
+ this.result = result;
+ add(HighCardinalityKeyNames.RESULT_COUNT, resultCount(result));
+ add(
+ HighCardinalityKeyNames.GRAPH_LINK_EXPANSION_COUNT,
+ result == null ? 0 : result.linkExpansionCount());
+ add(
+ HighCardinalityKeyNames.GRAPH_ENTITY_EXPANSION_COUNT,
+ result == null ? 0 : result.entityExpansionCount());
+ add(
+ HighCardinalityKeyNames.GRAPH_DEDUPED_CANDIDATE_COUNT,
+ result == null ? 0 : result.dedupedCandidateCount());
+ add(
+ HighCardinalityKeyNames.GRAPH_OVERLAP_COUNT,
+ result == null ? 0 : result.overlapCount());
+ add(
+ HighCardinalityKeyNames.GRAPH_SKIPPED_OVERFANOUT_ENTITY_COUNT,
+ result == null ? 0 : result.skippedOverFanoutEntityCount());
+ add(HighCardinalityKeyNames.GRAPH_TIMEOUT, result != null && result.timedOut());
+ add(HighCardinalityKeyNames.GRAPH_DEGRADED, result != null && result.degraded());
+ }
+
+ private int resultCount(GraphExpansionResult result) {
+ return result == null || result.graphItems() == null ? 0 : result.graphItems().size();
+ }
+
+ public int resultCount() {
+ return resultCount(result);
+ }
+
+ public int candidateCount() {
+ return result == null ? 0 : result.dedupedCandidateCount();
+ }
+
+ public boolean degraded() {
+ return result != null && result.degraded();
+ }
+
+ public boolean skipped() {
+ return result == null || !result.enabled();
+ }
+
+ public String strategyName() {
+ return null;
+ }
+
+ public String stage() {
+ return "channel";
+ }
+
+ public String tier() {
+ return "item";
+ }
+
+ public String method() {
+ return "graph";
+ }
+
+ public String source() {
+ return "core";
+ }
+
+ @Override
+ public String status() {
+ String terminalStatus = errorOrCancellationStatus();
+ if (terminalStatus != null) {
+ return terminalStatus;
+ }
+ return degraded() ? "degraded" : "success";
+ }
+
+ @Override
+ public Optional toRetrievalTraceEvent(
+ ObservationTiming timing, RetrievalTraceOptions options) {
+ List results = result == null ? List.of() : result.graphItems();
+ return Optional.of(
+ new RetrievalTraceEvent(
+ GraphItemChannelDocument.RETRIEVE.getName(),
+ GraphItemChannelDocument.RETRIEVE.getName(),
+ status(),
+ timing.startedAt(),
+ timing.completedAt(),
+ timing.durationMillis(),
+ Map.of("operation", "retrieval", "stage", "channel"),
+ Map.of(
+ HighCardinalityKeyNames.RESULT_COUNT.asString(),
+ String.valueOf(resultCount()),
+ HighCardinalityKeyNames.GRAPH_DEDUPED_CANDIDATE_COUNT
+ .asString(),
+ String.valueOf(candidateCount())),
+ new RetrievalTraceEvent.StagePayload(
+ "channel",
+ "item",
+ "graph",
+ seedCount,
+ candidateCount(),
+ resultCount(),
+ degraded(),
+ skipped(),
+ attributes(),
+ RetrievalTraceEvent.candidates(
+ results,
+ options.maxCandidatesPerStage(),
+ options.maxTextLength()))));
+ }
+
+ private Map attributes() {
+ if (result == null) {
+ return Map.of();
+ }
+ return Map.of(
+ "linkExpansionCount",
+ result.linkExpansionCount(),
+ "entityExpansionCount",
+ result.entityExpansionCount(),
+ "overlapCount",
+ result.overlapCount(),
+ "timedOut",
+ result.timedOut());
+ }
+
+ private void add(HighCardinalityKeyNames key, Object value) {
+ if (value != null) {
+ addHighCardinalityKeyValue(key.withValue(String.valueOf(value)));
+ }
+ }
+ }
+
+ public static final class GraphItemChannelConvention
+ implements ObservationConvention {
+
+ public static final GraphItemChannelConvention INSTANCE = new GraphItemChannelConvention();
+
+ @Override
+ public String getName() {
+ return GraphItemChannelDocument.RETRIEVE.getName();
+ }
+
+ @Override
+ public String getContextualName(GraphItemChannelObservationContext context) {
+ return getName();
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(GraphItemChannelObservationContext context) {
+ return KeyValues.of(
+ HighCardinalityKeyNames.MEMORY_ID.withValue(
+ context.queryContext.memoryId().toIdentifier()),
+ HighCardinalityKeyNames.CHANNEL.withValue("graph"),
+ HighCardinalityKeyNames.GRAPH_ENABLED.withValue(
+ String.valueOf(context.settings != null && context.settings.enabled())),
+ HighCardinalityKeyNames.GRAPH_SEED_COUNT.withValue(
+ String.valueOf(context.seedCount)));
+ }
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return context instanceof GraphItemChannelObservationContext;
+ }
+ }
+}
diff --git a/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/observation/DefaultRetrievalGraphAssistantObservation.java b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/observation/DefaultRetrievalGraphAssistantObservation.java
new file mode 100644
index 00000000..d363475a
--- /dev/null
+++ b/memind-core/src/main/java/com/openmemind/ai/memory/core/retrieval/graph/observation/DefaultRetrievalGraphAssistantObservation.java
@@ -0,0 +1,384 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.openmemind.ai.memory.core.retrieval.graph.observation;
+
+import com.openmemind.ai.memory.core.observation.MemoryObservation;
+import com.openmemind.ai.memory.core.observation.MemoryObservationContext;
+import com.openmemind.ai.memory.core.retrieval.graph.RetrievalGraphAssistResult;
+import com.openmemind.ai.memory.core.retrieval.graph.RetrievalGraphSettings;
+import com.openmemind.ai.memory.core.retrieval.query.QueryContext;
+import com.openmemind.ai.memory.core.retrieval.scoring.ScoredResult;
+import com.openmemind.ai.memory.core.retrieval.trace.ObservationTiming;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceEvent;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceEventSource;
+import com.openmemind.ai.memory.core.retrieval.trace.RetrievalTraceOptions;
+import io.micrometer.common.KeyValues;
+import io.micrometer.common.docs.KeyName;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationConvention;
+import io.micrometer.observation.ObservationRegistry;
+import io.micrometer.observation.docs.ObservationDocumentation;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import reactor.core.publisher.Mono;
+import reactor.util.context.ContextView;
+
+/** Observation contracts for DefaultRetrievalGraphAssistant. */
+public final class DefaultRetrievalGraphAssistantObservation {
+
+ private DefaultRetrievalGraphAssistantObservation() {}
+
+ public static Mono observe(
+ ObservationRegistry observationRegistry,
+ QueryContext queryContext,
+ RetrievalGraphSettings graphSettings,
+ List directItems,
+ Supplier> operation) {
+ return observe(
+ observationRegistry,
+ queryContext,
+ graphSettings,
+ directItems,
+ ignored -> operation.get());
+ }
+
+ public static Mono