Skip to content

Conversation

@fm1320
Copy link
Contributor

@fm1320 fm1320 commented Aug 11, 2025

Description

Adds a new integration package: Superlinked Retriever, under llama-index-integrations/retrievers/llama-index-retrievers-superlinked. It exposes a LlamaIndex-compatible retriever that wraps a Superlinked App and QueryDescriptor, returning TextNode/NodeWithScore.

Includes:

  • Import path re-export: from llama_index.retrievers.superlinked import SuperlinkedRetriever
  • README with install/usage/example
  • LICENSE (MIT)
  • uv.lock
  • Unit/integration-style tests using mocks (no hard dependency on Superlinked)
  • Example script demonstrating end-to-end in-memory flow (requires Python 3.10–3.12)

Dependencies:

  • Runtime: llama-index-core>=0.13.1,<0.14
  • Example only: superlinked, pandas (Superlinked requires Python 3.10–3.12)

Fixes # (issue): N/A

New Package?

Did I fill in the tool.llamahub section in the pyproject.toml and provide a detailed README.md for my new integration or package?

  • Yes
  • No

Version Bump?

Did I bump the version in the pyproject.toml file of the package I am updating? (Except for the llama-index-core package)

  • Yes (set to 0.1.0)
  • No

Type of Change

Please delete options that are not relevant.

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

How Has This Been Tested?

Your pull-request will likely not be merged unless it is covered by some form of impactful unit testing.

  • I added new unit tests to cover this change
  • I believe this change is already covered by existing unit tests

Notes:

  • Tests mock Superlinked types so they run without installing Superlinked.
  • Verified locally with uv on Python 3.11: ruff, black, codespell (scoped), mypy (src), and pytest all green.
  • Example executed successfully with superlinked + pandas; optional QueryEngine path degrades gracefully if LLM extras are not installed.

Suggested Checklist:

  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • I have added Google Colab support for the newly added notebooks.
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I ran uv run make format; uv run make lint to appease the lint gods

Suggested PR title:
feat(retrievers-superlinked): add Superlinked retriever integration (new package)

@review-notebook-app
Copy link

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@fm1320 fm1320 marked this pull request as ready for review August 14, 2025 09:48
@dosubot dosubot bot added the size:XXL This PR changes 1000+ lines, ignoring generated files. label Aug 14, 2025
@fm1320
Copy link
Contributor Author

fm1320 commented Aug 14, 2025

@TuanaCelik


from typing import Any, List, Optional

try:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems weird. llama-index-core is a dependency of this package. We don't need this try/except statement, we can just import the classes since the core package is expected to be there

"""
LlamaIndex retriever for Superlinked.

Parameters
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we've bee using google-style docstrings, the API reference won't generate nicely without that specific style

) -> None:
# Import and validate types lazily to avoid hard dependency at import time
try:
from superlinked.framework.dsl.app.app import App # type: ignore
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't superlinked just be a package dependency? No need to hide the import


# Initialize BaseRetriever
try:
super().__init__(callback_manager)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: prefer explicit kwargs: super().__init__(callback_manager=callback_manager)

self.k = k

# Initialize BaseRetriever
try:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no need for this try/except

page_content_field: str,
query_text_param: str = "query_text",
metadata_fields: Optional[List[str]] = None,
k: int = 4,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: top_k instead of k ? (sims inconsistent otherwise)

query_text_param: str = "query_text",
metadata_fields: Optional[List[str]] = None,
k: int = 4,
callback_manager: Optional[Any] = None,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you could technically import the proper type here

Copy link
Collaborator

@logan-markewich logan-markewich left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems ok, but I think we can clean up the imports and dependencies

…oogle-style docs, rename k->top_k, deps, examples/tests, lint clean
@dosubot dosubot bot added size:XL This PR changes 500-999 lines, ignoring generated files. and removed size:XXL This PR changes 1000+ lines, ignoring generated files. labels Aug 14, 2025
@fm1320
Copy link
Contributor Author

fm1320 commented Aug 14, 2025

This seems ok, but I think we can clean up the imports and dependencies

@logan-markewich made some fixes

@dosubot dosubot bot added the lgtm This PR has been approved by a maintainer label Aug 14, 2025
@logan-markewich logan-markewich merged commit a121a47 into run-llama:main Aug 14, 2025
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

lgtm This PR has been approved by a maintainer size:XL This PR changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants