Conversation
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
Aligns the documentation under docs/ with the Ruby SDK’s actual behavior for stale-while-revalidate (SWR) caching and prompt management APIs, so that configuration and API reference match what the runtime supports.
Changes:
- Clarifies SWR activation semantics: runtime SWR is active when
cache_stale_ttl > 0, not solely viacache_stale_while_revalidate. - Expands API reference to include
Client#create_promptandClient#update_prompt. - Corrects/extends type documentation for
get_promptfallback andcache_stale_ttl(including:indefinite).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/CONFIGURATION.md | Updates SWR documentation and test snippet to reflect cache_stale_ttl-based activation. |
| docs/API_REFERENCE.md | Adds prompt write APIs and corrects several parameter/type definitions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - `false` (default): Cache expires at TTL, next request waits for API (~100ms) | ||
| - `true`: After TTL, serves stale data instantly (~1ms) + refreshes in background | ||
| - `cache_stale_ttl <= 0` (default): Cache expires at TTL, next request waits for API (~100ms) |
There was a problem hiding this comment.
Docs state cache_stale_ttl <= 0 disables SWR, but cache_stale_ttl is validated as non-negative in runtime config (negative values raise ConfigurationError). Consider documenting the disabled case as cache_stale_ttl == 0 (default) to avoid implying negative values are supported.
| - `cache_stale_ttl <= 0` (default): Cache expires at TTL, next request waits for API (~100ms) | |
| - `cache_stale_ttl == 0` (default): Cache expires at TTL, next request waits for API (~100ms) |
| - **Description:** Advisory SWR intent flag (effective SWR behavior is controlled by `cache_stale_ttl`) | ||
|
|
||
| ```ruby | ||
| config.cache_stale_while_revalidate = true # Enable SWR | ||
| config.cache_stale_while_revalidate = true # Optional intent flag | ||
| ``` | ||
|
|
||
| When enabled, serves stale cached data immediately while refreshing in the background. This dramatically reduces P99 latency by avoiding synchronous API waits after cache expiration. | ||
| This flag does not independently turn SWR on/off in runtime cache behavior. SWR is active when `cache_stale_ttl > 0`. | ||
|
|
There was a problem hiding this comment.
This section clarifies SWR activation depends on cache_stale_ttl > 0, but later in this document the Production example still suggests cache_stale_while_revalidate = true “Enable SWR” without setting cache_stale_ttl. Please update the examples/comments below to match the new semantics (e.g., set cache_stale_ttl in the Production snippet or adjust the wording).
| **Raises:** | ||
|
|
||
| - `NotFoundError` if the prompt version does not exist | ||
| - `UnauthorizedError` if authentication fails | ||
| - `ApiError` for other API errors | ||
|
|
There was a problem hiding this comment.
Client#update_prompt can raise ArgumentError when labels is not an Array (enforced in ApiClient#update_prompt). Please document this in the Raises section so callers know what to expect for invalid inputs.
TL;DRAlign docs with actual SDK behavior for SWR activation and prompt APIs.
Whydocs/claimed SWR behavior was controlled bycache_stale_while_revalidate, but runtime behavior is activated bycache_stale_ttl > 0. API reference also omitted public prompt write APIs and under-specified fallback/config types.ChecklistCloses ML-896
Summary
docs/CONFIGURATION.mdto describe SWR runtime behavior correctly (cache_stale_ttl > 0controls activation).docs/API_REFERENCE.mdto:Client#create_promptandClient#update_prompt.get_promptfallback type (StringorArray<Hash>).cache_stale_ttltype to include:indefinite.Fixes addressed
Validation checklist
npx langfuse-cli api __schema)bundle exec rspec(blocked by local bundler mismatch)bundle exec rubocop(blocked by local bundler mismatch)