Skip to content

Commit e5140f4

Browse files
fm1320fm1320
committed
add docs and quickstart examples
1 parent 8673d73 commit e5140f4

File tree

4 files changed

+1500
-23
lines changed

4 files changed

+1500
-23
lines changed

‎README.md‎

Lines changed: 101 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,117 @@
1-
# langchain-superlinked
1+
## langchain-superlinked
22

3-
This package contains the LangChain integration with Superlinked
3+
Integration package that exposes Superlinked retrieval capabilities via the standard LangChain retriever interface. It lets you plug a Superlinked-powered retriever into LangChain RAG pipelines while keeping your vector storage and schema choices flexible.
44

5-
## Installation
5+
### Install
66

77
```bash
8-
pip install -U langchain-superlinked
8+
pip install -U langchain-superlinked superlinked
99
```
1010

11-
And you should configure credentials by setting the following environment variables:
11+
### Quickstart
1212

13-
* TODO: fill this out
13+
```python
14+
import superlinked.framework as sl
15+
from langchain_superlinked import SuperlinkedRetriever
1416

15-
## Chat Models
17+
class DocumentSchema(sl.Schema):
18+
id: sl.IdField
19+
content: sl.String
1620

17-
`ChatSuperlinked` class exposes chat models from Superlinked.
21+
doc_schema = DocumentSchema()
22+
text_space = sl.TextSimilaritySpace(text=doc_schema.content, model="sentence-transformers/all-MiniLM-L6-v2")
23+
index = sl.Index([text_space])
24+
query = (
25+
sl.Query(index)
26+
.find(doc_schema)
27+
.similar(text_space.text, sl.Param("query_text"))
28+
.select([doc_schema.content])
29+
)
1830

19-
```python
20-
from langchain_superlinked import SuperlinkedRetriever
21-
print(SuperlinkedRetriever)
31+
source = sl.InMemorySource(schema=doc_schema)
32+
executor = sl.InMemoryExecutor(sources=[source], indices=[index])
33+
app = executor.run()
34+
source.put([
35+
{"id": "1", "content": "Machine learning processes data efficiently."},
36+
{"id": "2", "content": "NLP understands human language."},
37+
])
38+
39+
retriever = SuperlinkedRetriever(sl_client=app, sl_query=query, page_content_field="content")
40+
docs = retriever.invoke("artificial intelligence", k=2)
2241
```
2342

24-
## Embeddings
43+
See more end-to-end examples in `docs/`.
2544

26-
`SuperlinkedEmbeddings` class exposes embeddings from Superlinked.
45+
---
2746

28-
```python
29-
from langchain_superlinked import SuperlinkedRetriever
30-
print(SuperlinkedRetriever)
31-
```
47+
## Local development
3248

33-
## LLMs
34-
`SuperlinkedLLM` class exposes LLMs from Superlinked.
49+
Prerequisites: Python 3.10–3.13, `uv` installed.
3550

36-
```python
37-
from langchain_superlinked import SuperlinkedRetriever
38-
print(SuperlinkedRetriever)
39-
```
51+
- Setup: `uv sync --all-extras --dev && uv run pre-commit install`
52+
- Lint & type-check: `uv run ruff check . && uv run ruff format --check . && uv run mypy langchain_superlinked`
53+
- Unit tests: `make test`
54+
- Integration tests: `make integration_tests` (skips if `langchain_tests` isn’t installed)
55+
- Smoke test: `make smoke`
56+
- Run examples: `uv run python docs/quickstart_examples.py`
57+
58+
---
59+
60+
## CI/CD overview
61+
62+
On push/PR to `main`, GitHub Actions runs (matrix: 3.10/3.11/3.12):
63+
- Lint: `ruff check .` and `ruff format --check .`
64+
- Type-check: `mypy langchain_superlinked`
65+
- Tests: unit (network disabled) and integration (skips if standard tests unavailable)
66+
- Smoke test: imports the package and symbols
67+
- Build: `python -m build` to produce sdist and wheel (no publish)
68+
69+
Workflow file: `.github/workflows/ci.yml`.
70+
71+
---
72+
73+
## Releasing
74+
75+
- Bump version in `pyproject.toml` using semantic versioning.
76+
- Build artifacts: `make dist`
77+
- Validate: `uv run twine check dist/*`
78+
- Publish to PyPI: `uv run twine upload -r pypi dist/*`
79+
80+
After publish, open/refresh the docs PR in the LangChain monorepo to reference the new version if needed. See LangChain’s integration guide for the process: [How to contribute an integration](https://python.langchain.com/docs/contributing/how_to/integrations/#how-to-contribute-an-integration).
81+
82+
---
83+
84+
## Implementation overview
85+
86+
- Primary entrypoint: `langchain_superlinked/retrievers.py` exposes `SuperlinkedRetriever`, a `BaseRetriever`.
87+
- Construction:
88+
- `sl_client`: Superlinked App (e.g., from `InMemoryExecutor.run()`).
89+
- `sl_query`: Superlinked `QueryDescriptor` built via `sl.Query(...).find(...).similar(...).select(...)`.
90+
- `page_content_field`: field from Superlinked results mapped to `Document.page_content`.
91+
- Optional `metadata_fields`: copied into `Document.metadata` in addition to the always-present `id`.
92+
- Behavior:
93+
- Accepts runtime parameters (e.g., `k`, weights, filters) and forwards them to the Superlinked query.
94+
- Handles missing fields gracefully; returns an empty list on upstream exceptions.
95+
96+
---
97+
98+
## Scope and non-goals
99+
100+
This package aims to be the minimal, well-typed LangChain integration layer for Superlinked retrievers. It intentionally does not include:
101+
102+
- Dynamic schema inference or auto-generation for arbitrary datasets. Rationale: datasets vary widely; a robust solution requires additional assumptions (typing, transforms, index strategy), which goes beyond the minimal integration. We recommend implementing this in a separate helper package or cookbook code layered on top (e.g., “schema builders” that emit Superlinked schemas and indices for your domain). The examples in `docs/` illustrate patterns for composing spaces (text, categorical, numeric, recency) that such builders could automate.
103+
- Non-retriever integrations (custom LLMs, embeddings, caches, loaders). These can live in separate packages if needed.
104+
105+
If you have concrete requirements for dynamic schema construction, please open an issue with sample data and desired retrieval behavior so we can discuss an extensible approach that stays decoupled from the core integration.
106+
107+
---
108+
109+
## Links
110+
111+
- Usage examples and scenarios: `docs/`
112+
- LangChain integration guide: [How to contribute an integration](https://python.langchain.com/docs/contributing/how_to/integrations/#how-to-contribute-an-integration)
113+
- Superlinked: `https://superlinked.com`
114+
115+
## License
116+
117+
MIT (see `LICENSE`)

‎docs/provider.ipynb‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Superlinked\n",
8+
"\n",
9+
"Superlinked is a platform that offers users to build AI search and recommendation pipelines at scale. Have a look at [our repo](https://github.com/superlinked/superlinked) which has resources on docs, notebooks, and other details. \n",
10+
"We also have an end-to-end demo example using financial reporting data and an article explaining the process of integrating Superlinked with LangChain.\n"
11+
]
12+
}
13+
],
14+
"metadata": {
15+
"colab": {
16+
"provenance": []
17+
},
18+
"kernelspec": {
19+
"display_name": "Python 3 (ipykernel)",
20+
"language": "python",
21+
"name": "python3"
22+
},
23+
"language_info": {
24+
"codemirror_mode": {
25+
"name": "ipython",
26+
"version": 3
27+
},
28+
"file_extension": ".py",
29+
"mimetype": "text/x-python",
30+
"name": "python",
31+
"nbconvert_exporter": "python",
32+
"pygments_lexer": "ipython3",
33+
"version": "3.10.11"
34+
}
35+
},
36+
"nbformat": 4,
37+
"nbformat_minor": 1
38+
}

0 commit comments

Comments
 (0)