fix: normalize NeptuneDriver params and AOSS bulk actions

[cnYui]

Summary

Addresses part of #1529.

• initialize NeptuneDriver._database and implement clone(database=...) so group-scoped Graphiti.add_episode paths do not hit the base driver no-op clone
• normalize NeptuneDriver.execute_query() parameters by flattening Neo4j-style params={...} and dropping routing_ before calling Neptune
• stop sending custom _id values in AOSS bulk actions while keeping logical uuid in the indexed source fields
• add focused NeptuneDriver contract tests for params, AOSS bulk action shape, and clone behavior

Tests

• .\.venv\Scripts\python.exe -m pytest tests/driver/test_neptune_driver.py -q
• .\.venv\Scripts\python.exe -m pytest tests/driver -q
• .\.venv\Scripts\python.exe -m ruff format --check graphiti_core/driver/neptune_driver.py tests/driver/test_neptune_driver.py
• .\.venv\Scripts\python.exe -m ruff check graphiti_core/driver/neptune_driver.py tests/driver/test_neptune_driver.py
• .\.venv\Scripts\python.exe -m pyright --pythonpath .\.venv\Scripts\python.exe graphiti_core/driver/neptune_driver.py

Notes

This does not add a live Neptune/AOSS integration test. The new tests mock the driver clients so the contract is covered without requiring AWS resources.

[zep-cla-assistant]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. For privacy information, see our Privacy Notice. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA behalf on myself, e-mail: [email protected]

or

I have read the CLA Document and I hereby sign the CLA behalf of my company, e-mail: [email protected]

Signature is valid for 6 months.

---

_{This bot will be retriggered when the Contributor License Agreement comment has been provided. Posted by the CLA Assistant Lite bot.}

[github-actions]

PR Triage Assessment

Priority: MEDIUM | Category: bug-fix | Action: merge-ready

Summary

Fixes three concrete bugs in the existing NeptuneDriver: the base-driver no-op clone() (breaking group-scoped add_episode), un-normalized Neo4j-style params={...}/routing_ kwargs reaching Neptune, and custom _id values being sent in AOSS bulk actions. All changes are confined to the Neptune driver and ship with focused unit tests.

Quality Scores

Tests	Docs	Style	Scope	Total
2	3	3	2	10/12

Signals

• Follows patterns: yes
• Focused scope: yes
• RFC if needed: n/a

Maintainer Note

Solid, surgically-scoped bug fix on a non-primary backend (Neptune), with unit tests covering each behavioral change. No live AWS integration test (acknowledged by the author and reasonable given mocked clients). Worth a quick review of the clone()/copy.copy semantics and the AOSS _id removal; note the CLA is not yet signed, which blocks merge until resolved.

Note to Author

Thanks for the well-scoped bug fix and accompanying unit tests — this looks ready for maintainer review. One process item: please sign the Contributor License Agreement (see the bot comment above) so the PR can be merged.

Raw triage data (JSON)

{
  "pr": 1539,
  "category": "bug-fix",
  "priority": "MEDIUM",
  "recommended_action": "merge-ready",
  "quality_scores": { "tests": 2, "documentation": 3, "code_style": 3, "pr_scope": 2, "total": 10 },
  "signals": { "follows_patterns": "yes", "focused_scope": true, "has_rfc_if_needed": "n/a" },
  "slop_signals": [],
  "duplicate_of": null,
  "impact": { "references_issue": "#1529", "touches_core": false, "affects_primary_backend": false, "backend": "neptune (non-primary)" },
  "loc": { "additions": 142, "deletions": 5, "changed_files": 2 },
  "notes": "CLA not yet signed; no live Neptune/AOSS integration test (mocked unit tests only, acknowledged by author)."
}

[cnYui]

I have read the CLA Document and I hereby sign the CLA behalf on myself, e-mail: [email protected]

[bonajoy]

Thanks @cnYui for picking this up, and thanks for the focused unit tests. I opened #1529, and this PR covers the first failures I reported: the clone() no-op, params normalization / routing_, and the AOSS _id change.

I also ran a local compatibility shim against a live Amazon Neptune Database + Amazon OpenSearch Serverless setup. With that shim, Graphiti.add_episode(..., group_id=...) followed by Graphiti.search(..., group_ids=[...]) returned the ingested fact end-to-end, and I confirmed the Episodic node directly in Neptune. So the core direction here holds up on a real backend, not just mocks.

On top of what's already in this PR, I hit two more live-path points that don't seem covered yet:

1. execute_query() parameter filtering may need to go a step further than the current flattening and routing_ drop. In the shared search path, kwargs like search_vector, min_score, limit, or database_ can also reach Neptune. In my shim I dropped driver-only / None values and kept only parameters actually referenced as $param in the Cypher query, which avoided unrelated params hitting openCypher.
2. Community indexing may be worth checking. The normal Neptune operations path calls save_to_aoss("community_name", ...), but the fallback CommunityNode.save() path still calls save_to_aoss("communities", ...). It may be worth confirming that fallback is unreachable for Neptune, or aliasing the name.

These are additive and out of scope for this PR's clean fix. I'm happy to either add focused review suggestions here if you'd prefer to keep it in one PR, or open a small follow-up PR referencing #1529 and this one and rebase after this merges. Whichever you and the maintainers prefer.

[cnYui]

@bonajoy The live Neptune/AOSS validation is useful confirmation, especially because this PR only has mocked unit coverage.

I agree the two additional live-path points are worth addressing, but I would prefer to keep this PR focused on the first failures from #1529 so it stays easy to review and merge: the clone() no-op, params flattening / routing_ drop, and AOSS _id removal.

The execute_query() filtering behavior feels like it deserves a separate focused test set, since keeping only Cypher-referenced $param values needs to avoid edge cases around query construction and driver-only kwargs. The community_name / communities path also seems better handled as a small follow-up after confirming whether the fallback path is reachable for Neptune.

My preference is to open a follow-up PR after this one lands, referencing #1529 and #1539, for:

1. filtering driver-only / None / unreferenced parameters before sending queries to Neptune
2. confirming or normalizing the community_name / communities indexing path

If maintainers prefer to handle those as review suggestions on this PR, I can take that route, but I would avoid expanding this PR unless that is the preferred review path.

[bonajoy]

Thanks @cnYui — agreed on keeping this PR focused on the first failures so it stays easy to review and merge. Splitting the two live-path points into a follow-up after this lands makes sense to me.

Since I already have a live Amazon Neptune + AOSS environment available from validating #1529 and have these tweaks working locally, I'm happy to take the follow-up PR if that works for you and the maintainers. Otherwise, I'm also happy to help review or provide live validation for it.

I'd keep the follow-up small and focused on:

1. filtering driver-only / None / unreferenced query parameters before sending queries to Neptune, with focused unit coverage and live openCypher validation where useful
2. confirming or normalizing the community_name / communities AOSS indexing path

Either way, I'll wait for this PR to land so the follow-up can be rebased cleanly on main.

Thanks again for picking up the first fix set.

[jhurliman]

Independently arrived at the same two fixes while debugging #1529, and can confirm this PR resolves both root causes end-to-end.

Validated on current main against Amazon Neptune Serverless (neptune-db://) + OpenSearch Serverless (Bedrock Titan v2 embeddings + Haiku extraction via an OpenAI-compatible gateway):

• self._database = database (default '') fixes the AttributeError in add_episode when an explicit group_id is passed (graphiti.py if group_id != self.driver._database). The '' default lines up with get_default_group_id(GraphProvider.NEPTUNE) returning ''.
• Popping/normalizing params in execute_query fixes the MalformedQueryException: MissingParameter that otherwise hits every add_episode via search_utils.node_similarity_search (params=filter_params).

With both applied, add_episode, hybrid search, current-state recall, and explicit edge supersession all work on Neptune Serverless + AOSS. LGTM. (#1568 also addresses the params half, with the nice extra touch of filtering to only $-referenced params.)