Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

feat: add context service with entity extraction, seeding, expansion, and ranking

riley02279bb79bced65f
diff --git a/memory-layer/src/main/scala/ix/memory/context/ClaimCollector.scala b/memory-layer/src/main/scala/ix/memory/context/ClaimCollector.scala
new file mode 100644
index 00000000..9b5e440e
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/context/ClaimCollector.scala
@@ -0,0 +1,15 @@
+package ix.memory.context
+
+import cats.effect.IO
+import cats.syntax.traverse._
+
+import ix.memory.db.GraphQueryApi
+import ix.memory.model._
+
+class ClaimCollector(queryApi: GraphQueryApi) {
+
+ def collect(tenant: TenantId, nodeIds: Vector[NodeId]): IO[Vector[Claim]] =
+ nodeIds
+ .traverse(id => queryApi.getClaims(tenant, id))
+ .map(_.flatten.distinctBy(_.id))
+}
diff --git a/memory-layer/src/main/scala/ix/memory/context/ConfidenceScorer.scala b/memory-layer/src/main/scala/ix/memory/context/ConfidenceScorer.scala
new file mode 100644
index 00000000..e645ef96
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/context/ConfidenceScorer.scala
@@ -0,0 +1,23 @@
+package ix.memory.context
+
+import ix.memory.model._
+
+trait ConfidenceScorer {
+ def score(claim: Claim, latestRev: Rev): ScoredClaim
+}
+
+/** Stub implementation for Phase 1 -- Task 8 will replace this. */
+class DefaultConfidenceScorer extends ConfidenceScorer {
+
+ def score(claim: Claim, latestRev: Rev): ScoredClaim = {
+ val baseAuth = SourceType.baseAuthority(claim.provenance.sourceType)
+ val breakdown = ConfidenceBreakdown(
+ baseAuthority = Factor(baseAuth, s"${claim.provenance.sourceType}"),
+ verification = Factor(1.0, "no verification data"),
+ recency = Factor(1.0, "default recency"),
+ corroboration = Factor(1.0, "default corroboration"),
+ conflictPenalty = Factor(1.0, "no conflicts detected")
+ )
+ ScoredClaim(claim, breakdown)
+ }
+}
diff --git a/memory-layer/src/main/scala/ix/memory/context/ConflictDetector.scala b/memory-layer/src/main/scala/ix/memory/context/ConflictDetector.scala
new file mode 100644
index 00000000..faba71b4
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/context/ConflictDetector.scala
@@ -0,0 +1,14 @@
+package ix.memory.context
+
+import ix.memory.model._
+
+trait ConflictDetector {
+ def detect(claims: Vector[ScoredClaim]): Vector[ConflictReport]
+}
+
+/** Stub implementation for Phase 1 -- Task 9 will replace this. */
+class DefaultConflictDetector extends ConflictDetector {
+
+ def detect(claims: Vector[ScoredClaim]): Vector[ConflictReport] =
+ Vector.empty // No conflict detection yet
+}
diff --git a/memory-layer/src/main/scala/ix/memory/context/ContextRanker.scala b/memory-layer/src/main/scala/ix/memory/context/ContextRanker.scala
new file mode 100644
index 00000000..1d639146
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/context/ContextRanker.scala
@@ -0,0 +1,9 @@
+package ix.memory.context
+
+import ix.memory.model.ScoredClaim
+
+object ContextRanker {
+
+ def rank(claims: Vector[ScoredClaim]): Vector[ScoredClaim] =
+ claims.sortBy(-_.confidence.score)
+}
diff --git a/memory-layer/src/main/scala/ix/memory/context/ContextService.scala b/memory-layer/src/main/scala/ix/memory/context/ContextService.scala
new file mode 100644
index 00000000..05273886
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/context/ContextService.scala
@@ -0,0 +1,56 @@
+package ix.memory.context
+
+import cats.effect.IO
+
+import ix.memory.db.GraphQueryApi
+import ix.memory.model._
+
+class ContextService(
+ queryApi: GraphQueryApi,
+ seeder: GraphSeeder,
+ expander: GraphExpander,
+ claimCollector: ClaimCollector,
+ confidenceScorer: ConfidenceScorer,
+ conflictDetector: ConflictDetector
+) {
+
+ def query(tenant: TenantId, question: String,
+ asOfRev: Option[Rev] = None): IO[StructuredContext] =
+ for {
+ // 1. Extract entity keywords from the natural language query
+ terms <- IO.pure(EntityExtractor.extract(question))
+
+ // 2. Seed: search the graph for nodes matching extracted terms
+ seeds <- seeder.seed(tenant, terms, asOfRev)
+
+ // 3. Expand: traverse the graph 1 hop from each seed
+ expanded <- expander.expand(tenant, seeds.map(_.id), hops = 1, asOfRev = asOfRev)
+
+ // 4. Collect claims for all discovered nodes
+ allNodeIds = (seeds.map(_.id) ++ expanded.nodes.map(_.id)).distinct
+ claims <- claimCollector.collect(tenant, allNodeIds)
+
+ // 5. Score each claim
+ rev <- asOfRev.fold(queryApi.getLatestRev(tenant))(IO.pure)
+ scored = claims.map(c => confidenceScorer.score(c, rev))
+
+ // 6. Detect conflicts among scored claims
+ conflicts = conflictDetector.detect(scored)
+
+ // 7. Rank claims by confidence (descending)
+ ranked = ContextRanker.rank(scored)
+
+ // 8. Assemble and return StructuredContext
+ } yield StructuredContext(
+ claims = ranked.toList,
+ conflicts = conflicts.toList,
+ nodes = (seeds ++ expanded.nodes).distinctBy(_.id).toList,
+ edges = expanded.edges.toList,
+ metadata = ContextMetadata(
+ query = question,
+ seedEntities = seeds.map(_.id).toList,
+ hopsExpanded = 1,
+ asOfRev = rev
+ )
+ )
+}
diff --git a/memory-layer/src/main/scala/ix/memory/context/EntityExtractor.scala b/memory-layer/src/main/scala/ix/memory/context/EntityExtractor.scala
new file mode 100644
index 00000000..dca489be
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/context/EntityExtractor.scala
@@ -0,0 +1,18 @@
+package ix.memory.context
+
+object EntityExtractor {
+
+ private val stopwords = Set(
+ "how", "does", "the", "is", "a", "an", "what", "when", "where", "why",
+ "do", "it", "in", "of", "to", "for", "and", "or", "not", "with", "by",
+ "from", "at", "on", "this", "that", "are", "was", "be", "has", "have", "can"
+ )
+
+ def extract(query: String): Vector[String] =
+ query.toLowerCase
+ .split("[\\s,;.!?]+")
+ .map(_.trim)
+ .filter(w => w.nonEmpty && w.length > 1 && !stopwords.contains(w))
+ .toVector
+ .distinct
+}
diff --git a/memory-layer/src/main/scala/ix/memory/context/GraphExpander.scala b/memory-layer/src/main/scala/ix/memory/context/GraphExpander.scala
new file mode 100644
index 00000000..d4e70046
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/context/GraphExpander.scala
@@ -0,0 +1,23 @@
+package ix.memory.context
+
+import cats.effect.IO
+import cats.syntax.traverse._
+
+import ix.memory.db.{GraphQueryApi, Direction, ExpandResult}
+import ix.memory.model._
+
+class GraphExpander(queryApi: GraphQueryApi) {
+
+ def expand(tenant: TenantId, seeds: Vector[NodeId], hops: Int = 1,
+ predicates: Option[Set[String]] = None,
+ asOfRev: Option[Rev] = None): IO[ExpandResult] =
+ seeds
+ .traverse { nodeId =>
+ queryApi.expand(tenant, nodeId, Direction.Both, predicates, hops, asOfRev)
+ }
+ .map { results =>
+ val allNodes = results.flatMap(_.nodes).distinctBy(_.id)
+ val allEdges = results.flatMap(_.edges).distinctBy(_.id)
+ ExpandResult(allNodes, allEdges)
+ }
+}
diff --git a/memory-layer/src/main/scala/ix/memory/context/GraphSeeder.scala b/memory-layer/src/main/scala/ix/memory/context/GraphSeeder.scala
new file mode 100644
index 00000000..9ab51aa3
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/context/GraphSeeder.scala
@@ -0,0 +1,16 @@
+package ix.memory.context
+
+import cats.effect.IO
+import cats.syntax.traverse._
+
+import ix.memory.db.GraphQueryApi
+import ix.memory.model._
+
+class GraphSeeder(queryApi: GraphQueryApi) {
+
+ def seed(tenant: TenantId, terms: Vector[String],
+ asOfRev: Option[Rev] = None): IO[Vector[GraphNode]] =
+ terms
+ .traverse(term => queryApi.searchNodes(tenant, term))
+ .map(_.flatten.distinctBy(_.id))
+}
diff --git a/memory-layer/src/test/scala/ix/memory/context/ContextServiceSpec.scala b/memory-layer/src/test/scala/ix/memory/context/ContextServiceSpec.scala
new file mode 100644
index 00000000..0677a958
--- /dev/null
+++ b/memory-layer/src/test/scala/ix/memory/context/ContextServiceSpec.scala
@@ -0,0 +1,241 @@
+package ix.memory.context
+
+import java.time.Instant
+import java.util.UUID
+
+import cats.effect.IO
+import cats.effect.testing.scalatest.AsyncIOSpec
+import io.circe.Json
+import org.scalatest.flatspec.AsyncFlatSpec
+import org.scalatest.matchers.should.Matchers
+
+import ix.memory.db._
+import ix.memory.model._
+
+class ContextServiceSpec extends AsyncFlatSpec with AsyncIOSpec with Matchers {
+
+ val clientResource = ArangoClient.resource(
+ host = "localhost", port = 8529,
+ database = "ix_memory_test", user = "root", password = ""
+ )
+
+ private def makePatch(
+ tenant: TenantId,
+ baseRev: Rev = Rev(0L),
+ ops: Vector[PatchOp] = Vector.empty,
+ patchId: PatchId = PatchId(UUID.randomUUID())
+ ): GraphPatch =
+ GraphPatch(
+ patchId = patchId,
+ tenant = tenant,
+ actor = "test-actor",
+ timestamp = Instant.parse("2025-06-01T12:00:00Z"),
+ source = PatchSource(
+ uri = "test://source",
+ sourceHash = Some("hash123"),
+ extractor = "test-extractor",
+ sourceType = SourceType.Code
+ ),
+ baseRev = baseRev,
+ ops = ops,
+ replaces = Vector.empty,
+ intent = Some("test intent")
+ )
+
+ private def buildContextService(queryApi: GraphQueryApi): ContextService = {
+ val seeder = new GraphSeeder(queryApi)
+ val expander = new GraphExpander(queryApi)
+ val collector = new ClaimCollector(queryApi)
+ val scorer = new DefaultConfidenceScorer()
+ val detector = new DefaultConflictDetector()
+ new ContextService(queryApi, seeder, expander, collector, scorer, detector)
+ }
+
+ // ── Test 1: Full pipeline returns structured context ───────────────
+
+ "ContextService" should "return structured context for a query" in {
+ clientResource.use { client =>
+ val writeApi = new ArangoGraphWriteApi(client)
+ val queryApi = new ArangoGraphQueryApi(client)
+ val tenant = TenantId(UUID.randomUUID())
+
+ val billingId = NodeId(UUID.nameUUIDFromBytes(s"${tenant.value}:test:billing_service".getBytes))
+ val retryId = NodeId(UUID.nameUUIDFromBytes(s"${tenant.value}:test:retry_handler".getBytes))
+ val edgeId = EdgeId(UUID.randomUUID())
+
+ val contextService = buildContextService(queryApi)
+
+ val patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(billingId, NodeKind.Function, "billing_service", Map.empty[String, Json]),
+ PatchOp.UpsertNode(retryId, NodeKind.Function, "retry_handler", Map.empty[String, Json]),
+ PatchOp.UpsertEdge(edgeId, billingId, retryId, EdgePredicate("calls"), Map.empty[String, Json]),
+ PatchOp.AssertClaim(billingId, "handles_billing", Json.fromString("true"), Some(0.9))
+ )
+ )
+
+ for {
+ _ <- client.ensureSchema()
+ _ <- writeApi.commitPatch(patch)
+ result <- contextService.query(tenant, "How does billing retry?")
+ } yield {
+ result.nodes should not be empty
+ result.metadata.query shouldBe "How does billing retry?"
+ // seedEntities is List[NodeId] — verify at least 1 seed was found
+ result.metadata.seedEntities should not be empty
+ result.metadata.hopsExpanded shouldBe 1
+ }
+ }
+ }
+
+ // ── Test 2: Empty context for unknown query ────────────────────────
+
+ it should "return empty context for unknown query" in {
+ clientResource.use { client =>
+ val queryApi = new ArangoGraphQueryApi(client)
+ val tenant = TenantId(UUID.randomUUID())
+ val contextService = buildContextService(queryApi)
+
+ for {
+ _ <- client.ensureSchema()
+ result <- contextService.query(tenant, "something totally unknown xyz123")
+ } yield {
+ result.nodes shouldBe empty
+ result.claims shouldBe empty
+ }
+ }
+ }
+
+ // ── Test 3: EntityExtractor extracts meaningful terms ──────────────
+
+ it should "extract meaningful terms from queries" in {
+ val terms = EntityExtractor.extract("How does billing retry?")
+ terms should contain("billing")
+ terms should contain("retry")
+ terms should not contain ("how")
+ terms should not contain ("does")
+ }
+
+ // ── Test 4: Claims are scored and ranked ───────────────────────────
+
+ it should "score and rank claims by confidence" in {
+ clientResource.use { client =>
+ val writeApi = new ArangoGraphWriteApi(client)
+ val queryApi = new ArangoGraphQueryApi(client)
+ val tenant = TenantId(UUID.randomUUID())
+
+ val nodeId = NodeId(UUID.randomUUID())
+
+ val contextService = buildContextService(queryApi)
+
+ val patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(nodeId, NodeKind.Function, "billing_func", Map.empty[String, Json]),
+ PatchOp.AssertClaim(nodeId, "returns_int", Json.fromString("true"), Some(0.9)),
+ PatchOp.AssertClaim(nodeId, "billing_logic", Json.fromString("complex"), Some(0.8))
+ )
+ )
+
+ for {
+ _ <- client.ensureSchema()
+ _ <- writeApi.commitPatch(patch)
+ result <- contextService.query(tenant, "What does billing do?")
+ } yield {
+ result.claims should not be empty
+ // All claims should have a score > 0
+ result.claims.foreach { sc =>
+ sc.confidence.score should be > 0.0
+ }
+ // Claims should be sorted descending by score
+ val scores = result.claims.map(_.confidence.score)
+ scores shouldBe scores.sorted.reverse
+ }
+ }
+ }
+
+ // ── Test 5: GraphExpander returns connected nodes ──────────────────
+
+ it should "expand seeds to find connected nodes" in {
+ clientResource.use { client =>
+ val writeApi = new ArangoGraphWriteApi(client)
+ val queryApi = new ArangoGraphQueryApi(client)
+ val tenant = TenantId(UUID.randomUUID())
+
+ val billingId = NodeId(UUID.randomUUID())
+ val retryId = NodeId(UUID.randomUUID())
+ val edgeId = EdgeId(UUID.randomUUID())
+
+ val contextService = buildContextService(queryApi)
+
+ val patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(billingId, NodeKind.Service, "billing_service", Map.empty[String, Json]),
+ PatchOp.UpsertNode(retryId, NodeKind.Function, "retry_logic", Map.empty[String, Json]),
+ PatchOp.UpsertEdge(edgeId, billingId, retryId, EdgePredicate("calls"), Map.empty[String, Json])
+ )
+ )
+
+ for {
+ _ <- client.ensureSchema()
+ _ <- writeApi.commitPatch(patch)
+ result <- contextService.query(tenant, "How does billing work?")
+ } yield {
+ // Should find billing_service as seed, then expand to find retry_logic
+ result.nodes.length should be >= 1
+ result.edges should not be empty
+ }
+ }
+ }
+
+ // ── Test 6: DefaultConflictDetector returns empty ──────────────────
+
+ it should "return empty conflicts with default detector" in {
+ clientResource.use { client =>
+ val writeApi = new ArangoGraphWriteApi(client)
+ val queryApi = new ArangoGraphQueryApi(client)
+ val tenant = TenantId(UUID.randomUUID())
+
+ val nodeId = NodeId(UUID.randomUUID())
+ val contextService = buildContextService(queryApi)
+
+ val patch = makePatch(
+ tenant = tenant,
+ ops = Vector(
+ PatchOp.UpsertNode(nodeId, NodeKind.Function, "billing_calc", Map.empty[String, Json]),
+ PatchOp.AssertClaim(nodeId, "billing_info", Json.fromString("test"), Some(0.9))
+ )
+ )
+
+ for {
+ _ <- client.ensureSchema()
+ _ <- writeApi.commitPatch(patch)
+ result <- contextService.query(tenant, "billing info")
+ } yield {
+ result.conflicts shouldBe empty
+ }
+ }
+ }
+
+ // ── Test 7: ContextRanker sorts correctly ──────────────────────────
+
+ it should "rank claims in descending confidence order" in {
+ val prov = Provenance("test://uri", None, "test", SourceType.Code, Instant.now())
+ val claim1 = Claim(ClaimId(UUID.randomUUID()), NodeId(UUID.randomUUID()), "field1",
+ ClaimStatus.Active, prov, Rev(1L), None)
+ val claim2 = Claim(ClaimId(UUID.randomUUID()), NodeId(UUID.randomUUID()), "field2",
+ ClaimStatus.Active, prov, Rev(1L), None)
+
+ val scored1 = ScoredClaim(claim1, ConfidenceBreakdown(
+ Factor(0.5, "low"), Factor(1.0, "ok"), Factor(1.0, "ok"), Factor(1.0, "ok"), Factor(1.0, "ok")
+ ))
+ val scored2 = ScoredClaim(claim2, ConfidenceBreakdown(
+ Factor(0.9, "high"), Factor(1.0, "ok"), Factor(1.0, "ok"), Factor(1.0, "ok"), Factor(1.0, "ok")
+ ))
+
+ val ranked = ContextRanker.rank(Vector(scored1, scored2))
+ ranked.head.confidence.score should be > ranked.last.confidence.score
+ }
+}