Skip to content

Add dedicated KeyValueCache documentation page with worked examples#32

Draft
Copilot wants to merge 8 commits into
mainfrom
copilot/add-documentation-for-keyvaluecache
Draft

Add dedicated KeyValueCache documentation page with worked examples#32
Copilot wants to merge 8 commits into
mainfrom
copilot/add-documentation-for-keyvaluecache

Conversation

Copy link
Copy Markdown

Copilot AI commented May 8, 2026

This PR adds first-class documentation for KeyValueCache, comparable to the existing Scorer/Indexer/Retriever cache docs. It introduces a dedicated page with practical usage patterns and wires it into the main docs navigation.

  • New KeyValueCache docs page

    • Added pyterrier_caching/pt_docs/key-value-cache.rst.
    • Covers:
      • what KeyValueCache is for (general transformer output caching by key columns),
      • caveats around key design and cache validity,
      • behavior when backing transformer is absent on cache miss.
    • Includes API sections for:
      • pyterrier_caching.KeyValueCache
      • pyterrier_caching.Sqlite3KeyValueCache
  • Worked examples

    • Added example for caching an LTR-style features output keyed by ['query', 'docno'], with features stored as NumPy array values.
    • Added example for caching multiple value columns (feature-style outputs) for the same key, including a query-derived question-word feature.
from pyterrier_caching import KeyValueCache

cached_features = KeyValueCache(
    "path/to/feature-cache",
    feature_builder,
    key=["query", "docno"],
    value=["qlen", "has_question_word"],
)
  • Docs discoverability updates
    • Updated pyterrier_caching/pt_docs/index.rst to include key-value-cache in the toctree and component list.
    • Updated README.md overview links to include the new KeyValueCache documentation page.

Copilot AI linked an issue May 8, 2026 that may be closed by this pull request
Copilot AI and others added 2 commits May 8, 2026 15:51
Copilot AI changed the title [WIP] Add documentation page for KeyValueCache with examples Add dedicated KeyValueCache documentation page with worked examples May 8, 2026
Copilot AI requested a review from cmacdonald May 8, 2026 15:53
Comment thread pyterrier_caching/pt_docs/key-value-cache.rst Outdated
Comment thread pyterrier_caching/pt_docs/key-value-cache.rst Outdated
Copilot AI requested a review from cmacdonald May 8, 2026 16:21
import pyterrier as pt
from pyterrier_caching import KeyValueCache

feature_transformer = pt.apply.generic(lambda df: df.assign(feature=1.0))
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

To better match the PyTerrier LTR data model, column should nane be features, not feature.
also the value should be an numpy array, not a single value.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Implemented in commit 9f174e5: the example now uses features (not feature) and populates it with NumPy arrays (np.array([...], dtype=np.float32)), with value=['features']. Screenshot: updated docs snippet is visible in the PR file diff for key-value-cache.rst.

Copilot AI requested a review from cmacdonald May 8, 2026 16:38
@cmacdonald cmacdonald requested a review from seanmacavaney May 8, 2026 16:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

document KeyValueCache

2 participants