everalgo-rank 0.1.0__tar.gz

everalgo_rank-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+
+# Environments
+.env
+.env.local
+.venv
+env/
+venv/
+
+# uv
+.uv/
+
+# Test / coverage / cache
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+report.xml
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Logs
+*.log
+
+# Project local artifacts (placed under local/ per project convention)
+local/
+
+# Claude Code session-local state (scheduled tasks, agent caches, locks)
+.claude/

everalgo_rank-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this package are documented here. Format follows
+[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/). Versioning
+follows [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `arank(rank_input, **kwargs) -> RankOutput`: async unified entry point; dispatches to the appropriate algorithm via an `_ALGO_REGISTRY` keyed by memory type.
+- `rank(rank_input, **kwargs) -> RankOutput`: sync bridge via `asgiref.async_to_sync`.
+- `EpisodicRanker`, `CaseRanker`, `SkillRanker`, `ProfileRanker`: facade classes that accept `llm=` at construction time and delegate to algorithm-layer functions.
+- `aagentic_rank(query, candidates, *, llm, config) -> RankOutput`: multi-round agentic retrieval — LLM-guided sufficiency check followed by multi-query expansion, then RRF fusion over all rounds.
+- `arerank(query, candidates, *, llm, prompt, config) -> list[Candidate]` and sync `rerank` bridge: LLM-scored pointwise reranker.
+- `RankConfig` and `AgenticConfig` pydantic models for tuning rerank and agentic retrieval parameters.
+- `FusionMode` enum: `rrf`, `lr`, `mrag`, `agentic`.
+- `fusion.rrf(*sources, k) -> list[Candidate]`: Reciprocal Rank Fusion over multiple recall lists.
+- `fusion.lr(candidates, *, weights) -> list[Candidate]`: linear-rank combination.
+- `fusion.cosine_to_lr_score`, `fusion.score_propagation`, `fusion.expand`: score normalisation and episode-to-fact cross-memory expansion helpers.
+- `weight` module: per-route weight configuration helpers.
+- English rerank prompts for episodic, case, and skill memory types in `rank/prompts/en/`.
+
+### Removed
+
+- Silent fallback returns in `_acheck_sufficiency` and `_agen_multi_queries`: both functions now raise on unexpected LLM response shapes instead of returning empty / default values.
+- Silent fallback in `_apply_rerank_scores`: the function raises `ValueError` when the LLM response cannot be parsed into a valid score list.
+- Outer `try/except` block in `aagentic_rank`: errors from sub-steps propagate to the caller unchanged.
+
+[Unreleased]: https://github.com/EverMind-AI/EverAlgo/compare/main...HEAD

everalgo_rank-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EverMind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

everalgo_rank-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: everalgo-rank
+Version: 0.1.0
+Summary: EverAlgo rank: 4 business-facing rankers (episodic / profile / case / skill) over a shared fusion / weight / rerank toolkit.
+Project-URL: Homepage, https://github.com/EverMind-AI/EverAlgo
+Project-URL: Repository, https://github.com/EverMind-AI/EverAlgo
+Project-URL: Issues, https://github.com/EverMind-AI/EverAlgo/issues
+Project-URL: Documentation, https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-rank
+Project-URL: Changelog, https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-rank/CHANGELOG.md
+Author: EverMind
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: asgiref>=3.0
+Requires-Dist: everalgo-core<2.0.0,>=0.1.0
+Description-Content-Type: text/markdown
+
+# everalgo-rank
+
+Memory ranking for EverAlgo — four business-facing ranker classes (`EpisodicRanker` / `CaseRanker` / `SkillRanker` / profile `rank`) composed over a shared toolkit (`fusion` / `weight` / `rerank`). Pure in-memory rank, no storage I/O.
+
+See the umbrella project: [EverAlgo monorepo](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
+
+## Install
+
+```bash
+pip install everalgo-rank
+```
+
+## What this distribution provides
+
+| Symbol | Role |
+|---|---|
+| `EpisodicRanker` | Class facade — episodic memory ranking; LLM bound at construction |
+| `CaseRanker` | Class facade — agent case ranking; LLM bound at construction |
+| `SkillRanker` | Class facade — agent skill ranking; LLM bound at construction |
+| `profile.rank` | Module-level sync function — profile ranking; cosine sort + dedup, no LLM |
+| `RankConfig` | Frozen pydantic config: `fusion_mode`, `rrf_k`, `alpha`, etc. |
+| `FusionMode` | Literal type: `"rrf"` / `"lr"` / `"mrag"` / `"agentic"` |
+| `DEFAULT_RANK_CONFIG` | `RankConfig()` with defaults (`fusion_mode="rrf"`, `rrf_k=60`) |
+| `arank` / `rank` | Top-level async / sync dispatch — routes to the registered ranker by `RankInput.memory_type` |
+| `arerank` / `rerank` | Low-level LLM rerank step; used by the ranker facades internally |
+
+## Quick start
+
+```python
+import asyncio
+import json
+
+from everalgo.llm.types import ChatResponse
+from everalgo.rank import EpisodicRanker, DEFAULT_RANK_CONFIG
+from everalgo.testing.fake_llm import FakeLLMClient
+from everalgo.types import Candidate, RankInput
+
+_RERANK_JSON = json.dumps({"ranked": [{"id": "ep_a", "score": 0.95}]})
+
+async def main() -> None:
+    fake = FakeLLMClient(responses=[ChatResponse(content=_RERANK_JSON, model="fake")])
+    ranker = EpisodicRanker(llm=fake)
+
+    rank_input = RankInput(
+        query="Python async retry patterns",
+        memory_type="episodic",
+        dense_candidates=[
+            Candidate(id="ep_a", score=0.9, metadata={"episode": "Alice asked about async retries."}),
+            Candidate(id="ep_b", score=0.5, metadata={"episode": "Team discussed lunch."}),
+        ],
+        top_k=1,
+    )
+
+    output = await ranker.arank(rank_input, config=DEFAULT_RANK_CONFIG, enable_rerank=True)
+    for item in output.items:
+        print(f"{item.id}  score={item.score:.2f}")
+
+asyncio.run(main())
+```
+
+## LLM rerank step
+
+`arerank` is the standalone LLM reranking primitive used internally by the ranker facades and exposed for direct use:
+
+```python
+from everalgo.rank.rerank import arerank
+from everalgo.rank.prompts.en.episodic import EPISODIC_RERANK_PROMPT_EN
+from everalgo.types import Candidate
+
+reranked = await arerank(
+    candidates,
+    prompt=EPISODIC_RERANK_PROMPT_EN,
+    top_k=5,
+    llm=client,
+)
+```
+
+## API surface
+
+| Symbol | Module | Signature summary |
+|---|---|---|
+| `EpisodicRanker` | `everalgo.rank` | `__init__(*, llm)` → `arank(rank_input, *, config, prompt, enable_rerank, ...) → RankOutput` |
+| `CaseRanker` | `everalgo.rank` | Same shape as `EpisodicRanker` |
+| `SkillRanker` | `everalgo.rank` | Same shape as `EpisodicRanker` |
+| `profile.rank` | `everalgo.rank.profile` | `(rank_input, *, threshold=0.0) → RankOutput` — sync, no LLM |
+| `RankConfig` | `everalgo.rank` | `fusion_mode: FusionMode = "rrf"`, `rrf_k: int = 60`, `alpha: float = 1.0`, `expand_limit: int = 3` |
+| `arank` | `everalgo.rank` | Top-level async dispatch by `rank_input.memory_type` |
+| `arerank` | `everalgo.rank.rerank` | `(items, *, prompt, top_k, llm) → list[Candidate]` |
+
+## Cross-links
+
+- [`everalgo-core`](../everalgo-core/) — `RankInput`, `RankOutput`, `Candidate`, `ScoredItem`, `LLMClient`
+- [`everalgo-user-memory`](../everalgo-user-memory/) — produces `Episode` / `AtomicFact` / `Profile` that EverOS Recall packages into `Candidate` for ranking
+- [`everalgo-agent-memory`](../everalgo-agent-memory/) — produces `AgentCase` / `AgentSkill` candidates

everalgo_rank-0.1.0/README.md

@@ -0,0 +1,94 @@
+# everalgo-rank
+
+Memory ranking for EverAlgo — four business-facing ranker classes (`EpisodicRanker` / `CaseRanker` / `SkillRanker` / profile `rank`) composed over a shared toolkit (`fusion` / `weight` / `rerank`). Pure in-memory rank, no storage I/O.
+
+See the umbrella project: [EverAlgo monorepo](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
+
+## Install
+
+```bash
+pip install everalgo-rank
+```
+
+## What this distribution provides
+
+| Symbol | Role |
+|---|---|
+| `EpisodicRanker` | Class facade — episodic memory ranking; LLM bound at construction |
+| `CaseRanker` | Class facade — agent case ranking; LLM bound at construction |
+| `SkillRanker` | Class facade — agent skill ranking; LLM bound at construction |
+| `profile.rank` | Module-level sync function — profile ranking; cosine sort + dedup, no LLM |
+| `RankConfig` | Frozen pydantic config: `fusion_mode`, `rrf_k`, `alpha`, etc. |
+| `FusionMode` | Literal type: `"rrf"` / `"lr"` / `"mrag"` / `"agentic"` |
+| `DEFAULT_RANK_CONFIG` | `RankConfig()` with defaults (`fusion_mode="rrf"`, `rrf_k=60`) |
+| `arank` / `rank` | Top-level async / sync dispatch — routes to the registered ranker by `RankInput.memory_type` |
+| `arerank` / `rerank` | Low-level LLM rerank step; used by the ranker facades internally |
+
+## Quick start
+
+```python
+import asyncio
+import json
+
+from everalgo.llm.types import ChatResponse
+from everalgo.rank import EpisodicRanker, DEFAULT_RANK_CONFIG
+from everalgo.testing.fake_llm import FakeLLMClient
+from everalgo.types import Candidate, RankInput
+
+_RERANK_JSON = json.dumps({"ranked": [{"id": "ep_a", "score": 0.95}]})
+
+async def main() -> None:
+    fake = FakeLLMClient(responses=[ChatResponse(content=_RERANK_JSON, model="fake")])
+    ranker = EpisodicRanker(llm=fake)
+
+    rank_input = RankInput(
+        query="Python async retry patterns",
+        memory_type="episodic",
+        dense_candidates=[
+            Candidate(id="ep_a", score=0.9, metadata={"episode": "Alice asked about async retries."}),
+            Candidate(id="ep_b", score=0.5, metadata={"episode": "Team discussed lunch."}),
+        ],
+        top_k=1,
+    )
+
+    output = await ranker.arank(rank_input, config=DEFAULT_RANK_CONFIG, enable_rerank=True)
+    for item in output.items:
+        print(f"{item.id}  score={item.score:.2f}")
+
+asyncio.run(main())
+```
+
+## LLM rerank step
+
+`arerank` is the standalone LLM reranking primitive used internally by the ranker facades and exposed for direct use:
+
+```python
+from everalgo.rank.rerank import arerank
+from everalgo.rank.prompts.en.episodic import EPISODIC_RERANK_PROMPT_EN
+from everalgo.types import Candidate
+
+reranked = await arerank(
+    candidates,
+    prompt=EPISODIC_RERANK_PROMPT_EN,
+    top_k=5,
+    llm=client,
+)
+```
+
+## API surface
+
+| Symbol | Module | Signature summary |
+|---|---|---|
+| `EpisodicRanker` | `everalgo.rank` | `__init__(*, llm)` → `arank(rank_input, *, config, prompt, enable_rerank, ...) → RankOutput` |
+| `CaseRanker` | `everalgo.rank` | Same shape as `EpisodicRanker` |
+| `SkillRanker` | `everalgo.rank` | Same shape as `EpisodicRanker` |
+| `profile.rank` | `everalgo.rank.profile` | `(rank_input, *, threshold=0.0) → RankOutput` — sync, no LLM |
+| `RankConfig` | `everalgo.rank` | `fusion_mode: FusionMode = "rrf"`, `rrf_k: int = 60`, `alpha: float = 1.0`, `expand_limit: int = 3` |
+| `arank` | `everalgo.rank` | Top-level async dispatch by `rank_input.memory_type` |
+| `arerank` | `everalgo.rank.rerank` | `(items, *, prompt, top_k, llm) → list[Candidate]` |
+
+## Cross-links
+
+- [`everalgo-core`](../everalgo-core/) — `RankInput`, `RankOutput`, `Candidate`, `ScoredItem`, `LLMClient`
+- [`everalgo-user-memory`](../everalgo-user-memory/) — produces `Episode` / `AtomicFact` / `Profile` that EverOS Recall packages into `Candidate` for ranking
+- [`everalgo-agent-memory`](../everalgo-agent-memory/) — produces `AgentCase` / `AgentSkill` candidates

everalgo_rank-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "everalgo-rank"
+version = "0.1.0"
+description = "EverAlgo rank: 4 business-facing rankers (episodic / profile / case / skill) over a shared fusion / weight / rerank toolkit."
+requires-python = ">=3.12"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "EverMind" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "asgiref>=3.0",
+  "everalgo-core>=0.1.0,<2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/EverMind-AI/EverAlgo"
+Repository = "https://github.com/EverMind-AI/EverAlgo"
+Issues = "https://github.com/EverMind-AI/EverAlgo/issues"
+Documentation = "https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-rank"
+Changelog = "https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-rank/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/everalgo"]

everalgo_rank-0.1.0/src/everalgo/rank/__init__.py

@@ -0,0 +1,76 @@
+"""Memory ranking — public surface of the rank package."""
+
+import logging
+
+from asgiref.sync import sync_to_async
+
+from everalgo.rank import case, episodic, fusion, profile, rerank, skill, weight
+from everalgo.rank.case import CaseRanker
+from everalgo.rank.episodic import EpisodicRanker
+from everalgo.rank.prompts.en.case import CASE_RERANK_PROMPT_EN
+from everalgo.rank.prompts.en.episodic import EPISODIC_RERANK_PROMPT_EN
+from everalgo.rank.prompts.en.skill import SKILL_RERANK_PROMPT_EN
+from everalgo.rank.rerank import (
+    _ALGO_REGISTRY,
+    DEFAULT_RANK_CONFIG,
+    FusionMode,
+    RankConfig,
+    _RankerSpec,
+)
+from everalgo.rank.rerank import (
+    _arank as arank,
+)
+from everalgo.rank.rerank import (
+    _rank as rank,
+)
+from everalgo.rank.skill import SkillRanker
+
+__all__ = [
+    "DEFAULT_RANK_CONFIG",
+    "CaseRanker",
+    "EpisodicRanker",
+    "FusionMode",
+    "RankConfig",
+    "SkillRanker",
+    "arank",
+    "case",
+    "episodic",
+    "fusion",
+    "profile",
+    "rank",
+    "rerank",
+    "skill",
+    "weight",
+]
+
+# Library logging setup (ADR-013): NullHandler on each subpackage logger.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+_ALGO_REGISTRY.update(
+    {
+        "case": _RankerSpec(
+            arank=case.arank,
+            modes=("rrf", "lr", "agentic"),
+            rerank_prompt=CASE_RERANK_PROMPT_EN,
+            item_type="case",
+        ),
+        "skill": _RankerSpec(
+            arank=skill.arank,
+            modes=("rrf", "lr", "agentic"),
+            rerank_prompt=SKILL_RERANK_PROMPT_EN,
+            item_type="skill",
+        ),
+        "episodic": _RankerSpec(
+            arank=episodic.arank,
+            modes=("rrf", "lr", "mrag", "agentic"),
+            rerank_prompt=EPISODIC_RERANK_PROMPT_EN,
+            item_type="episode",
+        ),
+        "profile": _RankerSpec(
+            arank=sync_to_async(profile.rank),
+            modes=(),
+            rerank_prompt="",
+            item_type="profile",
+        ),
+    }
+)

everalgo_rank-0.1.0/src/everalgo/rank/case.py

@@ -0,0 +1,87 @@
+"""Case ranker facade — thin wrapper over ``rerank._basic_arank``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from asgiref.sync import async_to_sync
+
+from everalgo.rank.rerank import DEFAULT_RANK_CONFIG, RankConfig, _basic_arank
+
+if TYPE_CHECKING:
+    from everalgo.llm.protocols import LLMClient
+    from everalgo.rank.fusion import RerankFn, RetrieveFn
+    from everalgo.types import RankInput, RankOutput
+
+__all__ = ["CaseRanker"]
+
+
+class CaseRanker:
+    """Class-style facade for the case ranker.
+
+    The LLM client is bound to the instance at construction time.
+    """
+
+    def __init__(self, *, llm: LLMClient) -> None:
+        self._llm = llm
+
+    async def arank(
+        self,
+        rank_input: RankInput,
+        *,
+        config: RankConfig = DEFAULT_RANK_CONFIG,
+        prompt: str | None = None,
+        enable_rerank: bool = False,
+        retrieve_fn: RetrieveFn | None = None,
+        rerank_fn: RerankFn | None = None,
+    ) -> RankOutput:
+        """Case ranker — see ``rerank._basic_arank`` for the pipeline body.
+
+        Args:
+            rank_input: Query + candidate sets for agent-case memory ranking.
+            config: Fusion mode and hyperparameters.
+            prompt: Per-call rerank prompt override; ``None`` uses the built-in default.
+            enable_rerank: When ``True``, run the LLM rerank stage after fusion.
+            retrieve_fn: Optional retrieval callback for the ``'agentic'`` fusion mode Round 2.
+            rerank_fn: Required for ``fusion_mode='agentic'``; cross-encoder callback for Round 1 rerank.
+
+        Returns:
+            Ranked and optionally LLM-reranked case items.
+        """
+        return await _basic_arank(
+            rank_input,
+            config=config,
+            llm=self._llm,
+            prompt=prompt,
+            enable_rerank=enable_rerank,
+            retrieve_fn=retrieve_fn,
+            rerank_fn=rerank_fn,
+        )
+
+    rank = async_to_sync(arank)
+    """Sync bridge — only callable from non-event-loop contexts."""
+
+
+async def arank(
+    rank_input: RankInput,
+    *,
+    config: RankConfig = DEFAULT_RANK_CONFIG,
+    llm: LLMClient | None = None,
+    prompt: str | None = None,
+    enable_rerank: bool = False,
+    retrieve_fn: RetrieveFn | None = None,
+    rerank_fn: RerankFn | None = None,
+) -> RankOutput:
+    """Case module-level ranker — delegates to ``rerank._basic_arank``."""
+    return await _basic_arank(
+        rank_input,
+        config=config,
+        llm=llm,
+        prompt=prompt,
+        enable_rerank=enable_rerank,
+        retrieve_fn=retrieve_fn,
+        rerank_fn=rerank_fn,
+    )
+
+
+rank = async_to_sync(arank)

everalgo_rank-0.1.0/src/everalgo/rank/episodic.py

@@ -0,0 +1,87 @@
+"""Episodic ranker facade — thin wrapper over ``rerank._basic_arank``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from asgiref.sync import async_to_sync
+
+from everalgo.rank.rerank import DEFAULT_RANK_CONFIG, RankConfig, _basic_arank
+
+if TYPE_CHECKING:
+    from everalgo.llm.protocols import LLMClient
+    from everalgo.rank.fusion import RerankFn, RetrieveFn
+    from everalgo.types import RankInput, RankOutput
+
+__all__ = ["EpisodicRanker"]
+
+
+class EpisodicRanker:
+    """Class-style facade for the episodic ranker.
+
+    The LLM client is bound to the instance at construction time.
+    """
+
+    def __init__(self, *, llm: LLMClient) -> None:
+        self._llm = llm
+
+    async def arank(
+        self,
+        rank_input: RankInput,
+        *,
+        config: RankConfig = DEFAULT_RANK_CONFIG,
+        prompt: str | None = None,
+        enable_rerank: bool = False,
+        retrieve_fn: RetrieveFn | None = None,
+        rerank_fn: RerankFn | None = None,
+    ) -> RankOutput:
+        """Episodic ranker — see ``rerank._basic_arank`` for the pipeline body.
+
+        Args:
+            rank_input: Query + candidate sets for episodic memory ranking.
+            config: Fusion mode and hyperparameters.
+            prompt: Per-call rerank prompt override; ``None`` uses the built-in default.
+            enable_rerank: When ``True``, run the LLM rerank stage after fusion.
+            retrieve_fn: Optional retrieval callback for the ``'agentic'`` fusion mode Round 2.
+            rerank_fn: Required for ``fusion_mode='agentic'``; cross-encoder callback for Round 1 rerank.
+
+        Returns:
+            Ranked and optionally LLM-reranked episodic items.
+        """
+        return await _basic_arank(
+            rank_input,
+            config=config,
+            llm=self._llm,
+            prompt=prompt,
+            enable_rerank=enable_rerank,
+            retrieve_fn=retrieve_fn,
+            rerank_fn=rerank_fn,
+        )
+
+    rank = async_to_sync(arank)
+    """Sync bridge — only callable from non-event-loop contexts."""
+
+
+async def arank(
+    rank_input: RankInput,
+    *,
+    config: RankConfig = DEFAULT_RANK_CONFIG,
+    llm: LLMClient | None = None,
+    prompt: str | None = None,
+    enable_rerank: bool = False,
+    retrieve_fn: RetrieveFn | None = None,
+    rerank_fn: RerankFn | None = None,
+) -> RankOutput:
+    """Episodic module-level ranker — delegates to ``rerank._basic_arank``."""
+    return await _basic_arank(
+        rank_input,
+        config=config,
+        llm=llm,
+        prompt=prompt,
+        enable_rerank=enable_rerank,
+        retrieve_fn=retrieve_fn,
+        rerank_fn=rerank_fn,
+    )
+
+
+rank = async_to_sync(arank)