⚡ Optimize Graph Entity Similarity Search

[Theory903]

💡 What: Refactored find_similar_entities in GraphManager to use a CTE instead of iterating through all other entities and executing individual SQL queries.
🎯 Why: The previous implementation suffered from an N+1 query problem, fetching relations individually for every entity to compare, significantly slowing down relationship discovery as the graph grows.
📊 Measured Improvement: Execution time on a benchmark with 1000 entities dropped from ~1.03s to ~0.02s.

---

PR created automatically by Jules for task 17118169448170855412 started by @Theory903

Summary by CodeRabbit

• Documentation

  • Added a note about improving graph similarity performance by using database-side queries instead of application loops.

• Refactor

  • Cleaned up graph management logic for readability and consistency.
  • Kept existing graph features and outputs the same while making the implementation more maintainable.

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR refactors GraphManager query paths without changing public methods, keeps triple insertion, path finding, context assembly, similarity search, and deletion behavior intact, and adds a short note about using SQL CTEs instead of Python loops for graph similarity.

Changes

Graph manager query flow

Layer / File(s)	Summary
Manager wiring and triple insertion src/ippoc/mnemosyne/graph/manager.py	Imports, ORM models, async engine/session wiring, triple insertion, relation existence checks, and neighbor lookup are reformatted while preserving the same control flow.
Relationship path lookup src/ippoc/mnemosyne/graph/manager.py	find_relationship_path and _find_paths_cte still resolve endpoints, run the recursive CTE, filter cyclic paths, and reconstruct node and relation names.
Context assembly and similarity handoff src/ippoc/mnemosyne/graph/manager.py	get_entity_context continues through metadata parsing, relationship and attribute fetching, and timestamping, then reaches the find_similar_entities setup boundary.
Similarity results and note src/ippoc/mnemosyne/graph/manager.py, .jules/bolt.md	find_similar_entities still executes the CTE and maps entity, similarity, and shared_relations, and the new note records the SQL CTE vs Python loop graph-similarity lesson.
Entity deletion src/ippoc/mnemosyne/graph/manager.py	delete_entity still looks up the entity, deletes incident relations, commits, and logs success.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Theory903/open-ippoc#31: Shares the same graph manager path-finding and context code, including _find_paths_cte and get_entity_context.
• Theory903/open-ippoc#34: Touches find_similar_entities, the same similarity flow that this PR reformats and rewires.
• Theory903/open-ippoc#159: Also updates _find_paths_cte, overlapping with the recursive path reconstruction logic here.

Poem

I hopped through CTEs by moonlit glow,
With SQL carrots and tidy flow.
Less looping nibble, more graphy cheer,
A whisker-twitching path is clear.
🐇✨ Hop, query, repeat!

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description only covers what/why/benchmark and omits most required template sections.	Fill in the required template sections: intent declaration, canon compliance, scope control, boundary declaration, safety/evolution impact, and the final assertion.
Docstring Coverage	⚠️ Warning	Docstring coverage is 70.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: optimizing graph entity similarity search.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf-graph-similarity-17118169448170855412

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/ippoc/mnemosyne/graph/manager.py (1)

61-104: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Initialize the database before the write path opens a session.

add_triple still skips await self.init_db(), so a fresh GraphManager can fail with no such table: kg_entities unless every caller remembers to bootstrap first.

🔧 Proposed fix

 async def add_triple(
     self,
     source: str,
     relation: str,
     target: str,
     source_type="Concept",
     target_type="Concept",
 ):
+    await self.init_db()
     """
     Adds (Source) -> [Relation] -> (Target) to the graph.
     Idempotent (get_or_create).
     """

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/ippoc/mnemosyne/graph/manager.py` around lines 61 - 104, The write path
in add_triple still opens a session without ensuring the schema exists, so a
fresh GraphManager can hit missing-table errors. Update GraphManager.add_triple
to initialize the database before any session work by awaiting self.init_db() at
the start of the method, and keep the rest of the get_or_create / Relation
insert logic unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/ippoc/mnemosyne/graph/manager.py`:
- Around line 61-104: The write path in add_triple still opens a session without
ensuring the schema exists, so a fresh GraphManager can hit missing-table
errors. Update GraphManager.add_triple to initialize the database before any
session work by awaiting self.init_db() at the start of the method, and keep the
rest of the get_or_create / Relation insert logic unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e8c0c992-7dca-4c8c-b125-a1a2d7fbc64f

📥 Commits

Reviewing files that changed from the base of the PR and between 29c13ba and 998a47a.

📒 Files selected for processing (2)

• .jules/bolt.md
• src/ippoc/mnemosyne/graph/manager.py