feat(hooks): add cache hit/miss observability hooks

[anderson-ufrj]

Summary

Adds cache observability hooks to enable tracking cache performance metrics as requested in #1882.

• Add CACHE_HIT and CACHE_MISS events to the HookName enum
• Add CacheHandler protocol for type safety
• Emit hooks in load_cached_response() function
• Backward compatible: hooks parameter is optional

Changes

• instructor/core/hooks.py: Add new hook types and emit methods
• instructor/cache/__init__.py: Emit hooks on cache hit/miss
• instructor/core/patch.py: Pass hooks to cache functions
• tests/test_cache_hooks.py: Comprehensive test suite (10 tests)
• docs/concepts/hooks.md: Document new hooks with usage example

Usage

from instructor.core.hooks import HookName

client = instructor.from_provider("openai/gpt-4")

def on_cache_hit(key: str, response) -> None:
    print(f"Cache HIT: {key[:16]}...")

def on_cache_miss(key: str) -> None:
    print(f"Cache MISS: {key[:16]}...")

client.on(HookName.CACHE_HIT, on_cache_hit)
client.on(HookName.CACHE_MISS, on_cache_miss)

Test plan

• All 10 new tests passing
• Existing tests unaffected
• Backward compatible (hooks parameter optional)

Closes #1882

---

Important

Adds cache hit/miss observability hooks to track cache performance metrics, with tests and documentation updates.

• Behavior:
  • Adds CACHE_HIT and CACHE_MISS events to HookName enum in hooks.py.
  • Emits hooks in load_cached_response() in cache/__init__.py for cache hit/miss.
  • Backward compatible: hooks parameter is optional.
• Testing:
  • Adds test_cache_hooks.py with 10 tests for cache hooks.
• Documentation:
  • Updates hooks.md to document new cache hooks with examples.

^{This description was created by for 72f43a1. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 72f43a1 in 1 minute and 32 seconds. Click for details.

• Reviewed 746 lines of code in 6 files
• Skipped 0 files when reviewing.
• Skipped posting 6 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. docs/concepts/hooks.md:56

• Draft comment:
  The new cache hook sections (cache:hit and cache:miss) are clear and provide useful usage examples. Great job on updating the documentation!
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 85% None

2. docs/research/CODEBASE_STUDY.md:1

• Draft comment:
  The study notes are very detailed and provide a comprehensive analysis of the cache observability hooks. No issues found.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 85% None

3. instructor/cache/__init__.py:195

• Draft comment:
  Consider refining the type hint for the 'hooks' parameter in 'load_cached_response' from 'Any | None' to 'Hooks | None' for better type safety and clarity.
• Reason this comment was not posted:
  Confidence changes required: 80% <= threshold 85% None

4. instructor/core/hooks.py:204

• Draft comment:
  The new CACHE_HIT and CACHE_MISS events and the CacheHandler protocol are implemented correctly. The emit methods for these events are consistent with existing patterns.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 85% None

5. instructor/core/patch.py:184

• Draft comment:
  Hooks are properly propagated to cache lookup functions in both async and sync paths. The integration of 'hooks' into the patching logic appears consistent and correct.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 85% None

6. tests/test_cache_hooks.py:1

• Draft comment:
  The test suite comprehensively verifies cache hook emissions for both hit and miss events, including multi-handler integration and hit ratio tracking. Excellent coverage!
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 85% None

Workflow ID: wflow_1JY3v8D3pTm7bH42

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}