Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(signals): build personal inbox rankings in the background (#126644)

posthog[bot]6c0d45bf5238
diff --git a/products/signals/backend/management/AGENTS.md b/products/signals/backend/management/AGENTS.md
index 70473cab3183..00dac1324c3d 100644
--- a/products/signals/backend/management/AGENTS.md
+++ b/products/signals/backend/management/AGENTS.md
@@ -300,7 +300,9 @@ A person with no ready activity summary still gets a list, marked `personalized:
When the model call fails or answers outside the schema, the list is in model order and `fallback_reason` says why.
`GET /api/projects/:id/signals/reports/for_me/` (`../personal_ranking/serve.py`) serves the same list to the user it describes, when the flag is on for that user.
-It reuses the latest row for `freshness_minutes` while the input hash matches, and limits builds per person with `build_burst`, `builds_per_hour` and `builds_per_day` from the same payload.
+It reuses the latest row for `freshness_minutes` while the input hash matches.
+Otherwise it queues one `build_personal_inbox_ranking` Celery task per person behind a cache lock, and serves the latest row as stale, or the candidates in inbox order with `fallback_reason: building`.
+It limits builds per person with `build_burst`, `builds_per_hour` and `builds_per_day` from the same payload.
## Tips
diff --git a/products/signals/backend/personal_ranking/logic.py b/products/signals/backend/personal_ranking/logic.py
index db6d3c760fc0..180a0512ff00 100644
--- a/products/signals/backend/personal_ranking/logic.py
+++ b/products/signals/backend/personal_ranking/logic.py
@@ -15,13 +15,13 @@ from typing import Any, Literal
from django.utils import timezone
import structlog
-import posthoganalytics
from openai import APITimeoutError, OpenAI
from openai.types.chat import ChatCompletionMessageParam
from posthog.dataclasses import frozen
from posthog.llm.gateway_client import build_openai_client, trace_id_from_seed
from posthog.models import Team, User
+from posthog.ph_client import ph_scoped_capture
from products.signals.backend.activity_summary.read import ActivitySummaryStatus, get_summary
from products.signals.backend.models import PersonalInboxRanking
@@ -224,32 +224,34 @@ def _capture(team: Team, user: User, build: PersonalRankingBuild, *, has_focus:
for candidate in build.candidates:
for pool in candidate.pools:
pools[pool] = pools.get(pool, 0) + 1
- posthoganalytics.capture(
- distinct_id=user.distinct_id or PIPELINE_DISTINCT_ID,
- event=BUILT_EVENT,
- properties={
- "team_id": team.id,
- "user_id": user.id,
- "ranking_id": build.ranking_id,
- "status": build.status,
- "personalized": build.personalized,
- "fallback_reason": build.fallback_reason,
- "model": build.model,
- "prompt_version": PROMPT_VERSION,
- "activity_summary_version": build.activity_summary_version,
- "has_focus": has_focus,
- "limit": build.limit,
- "candidate_count": len(build.candidates),
- "ranked_by_llm_count": sum(1 for entry in build.entries if entry.ranked_by == "llm"),
- "folded_count": len(build.folded),
- "pool_counts": pools,
- **dataclasses.asdict(build.counts),
- "tokens_in": build.tokens_in,
- "tokens_out": build.tokens_out,
- "latency_ms": build.latency_ms,
- },
- groups={"organization": str(team.organization_id), "project": str(team.uuid)},
- )
+ # The build runs in a Celery task, where the global client can drop events before it flushes.
+ with ph_scoped_capture() as capture:
+ capture(
+ distinct_id=user.distinct_id or PIPELINE_DISTINCT_ID,
+ event=BUILT_EVENT,
+ properties={
+ "team_id": team.id,
+ "user_id": user.id,
+ "ranking_id": build.ranking_id,
+ "status": build.status,
+ "personalized": build.personalized,
+ "fallback_reason": build.fallback_reason,
+ "model": build.model,
+ "prompt_version": PROMPT_VERSION,
+ "activity_summary_version": build.activity_summary_version,
+ "has_focus": has_focus,
+ "limit": build.limit,
+ "candidate_count": len(build.candidates),
+ "ranked_by_llm_count": sum(1 for entry in build.entries if entry.ranked_by == "llm"),
+ "folded_count": len(build.folded),
+ "pool_counts": pools,
+ **dataclasses.asdict(build.counts),
+ "tokens_in": build.tokens_in,
+ "tokens_out": build.tokens_out,
+ "latency_ms": build.latency_ms,
+ },
+ groups={"organization": str(team.organization_id), "project": str(team.uuid)},
+ )
except Exception:
logger.exception("signals.personal_ranking.capture_failed", team_id=team.id, user_id=user.id)
diff --git a/products/signals/backend/personal_ranking/serve.py b/products/signals/backend/personal_ranking/serve.py
index e52f61c3b510..ebf0a4def782 100644
--- a/products/signals/backend/personal_ranking/serve.py
+++ b/products/signals/backend/personal_ranking/serve.py
@@ -1,20 +1,26 @@
-"""Serve one person's ranked inbox list to the `for_me` endpoint: reuse a stored list, or build a new one.
+"""Serve one person's ranked inbox list to the `for_me` endpoint. A request never waits on the model.
A stored list is reused while it is younger than `freshness_minutes` and its input hash matches the current
-inputs. A request with `focus` always builds. The focus is part of the hash, so an unfocused request never
-reuses a focused list. Builds spend two per-person token buckets. A throttled request gets the latest stored
-list, or `BuildThrottledError` when there is none.
+inputs. Otherwise, and for every `refresh` or `focus` request, the read queues one background build per person
+and serves the latest stored list as stale, or the candidates in inbox order when there is none. The focus is
+part of the hash, so an unfocused request never reuses a focused list. A lock lets one build per person run at a
+time, and each queued build spends two per-person token buckets. `wait_seconds` waits a bounded time for the
+queued build to store its list.
"""
+import time
import datetime
from collections.abc import Mapping, Sequence
+from contextlib import suppress
from typing import Any, Literal
+from django.core.cache import cache
from django.utils import timezone
import structlog
from posthog.dataclasses import frozen
+from posthog.exceptions_capture import capture_exception
from posthog.models import Team, User
from posthog.token_bucket import BucketDecision, BucketUnavailable, Budget, consume, refund
@@ -22,7 +28,13 @@ from products.signals.backend.activity_summary.read import ActivitySummaryStatus
from products.signals.backend.models import PersonalInboxRanking
from products.signals.backend.personal_ranking.candidates import Candidate, gather_candidates
from products.signals.backend.personal_ranking.config import PersonalRankingConfig, read_config
-from products.signals.backend.personal_ranking.logic import build_personal_ranking, input_hash, normalize_focus
+from products.signals.backend.personal_ranking.logic import input_hash, model_order_reason, normalize_focus
+from products.signals.backend.personal_ranking.validation import model_order
+from products.signals.backend.personal_ranking_tasks import (
+ BUILD_LOCK_TTL_SECONDS,
+ build_lock_key,
+ build_personal_inbox_ranking,
+)
from products.signals.backend.ranking.report_predictions import ReportPredictions
logger = structlog.get_logger(__name__)
@@ -31,12 +43,15 @@ ServeStatus = Literal["ready", "unavailable"]
_BUCKET_PREFIX = "personal_ranking_build_rate"
_DAILY_BUILD_COST = 24
+MAX_WAIT_SECONDS = 30
+_WAIT_POLL_SECONDS = 0.5
+# Why a list with no stored build is in inbox order.
+FALLBACK_BUILDING = "building"
+FALLBACK_RATE_LIMITED = "rate_limited"
+FALLBACK_BUILD_FAILED = "build_failed"
-class BuildThrottledError(Exception):
- def __init__(self, retry_after: int | None) -> None:
- super().__init__("Personal inbox ranking build throttled.")
- self.retry_after = retry_after
+BuildStart = Literal["started", "running", "rate_limited", "failed"]
@frozen
@@ -73,10 +88,12 @@ class ServedFold:
class ServedRanking:
status: ServeStatus
personalized: bool
- # True when the list comes from storage, False when this request built it.
+ # True when the list comes from storage, False when it is the inbox-order fallback or a build this request waited on.
cached: bool
- # True when the list does not reflect the current inputs, because a build was throttled.
+ # True when the list does not reflect the current inputs.
stale: bool
+ # True when a build for the person is queued or running.
+ building: bool
fallback_reason: str | None
generated_at: datetime.datetime | None
latency_ms: int | None
@@ -92,6 +109,7 @@ UNAVAILABLE = ServedRanking(
personalized=False,
cached=False,
stale=False,
+ building=False,
fallback_reason=None,
generated_at=None,
latency_ms=None,
@@ -124,6 +142,45 @@ def _spend_build(team_id: int, user_id: int, config: PersonalRankingConfig) -> i
return None
+def _start_build(team: Team, user: User, config: PersonalRankingConfig, focus: str | None, limit: int) -> BuildStart:
+ """Queue one background build, unless one is already running for the person or the buckets refuse it."""
+ lock_key = build_lock_key(team.id, user.id)
+ locked = False
+ try:
+ locked = cache.add(lock_key, "1", timeout=BUILD_LOCK_TTL_SECONDS)
+ if not locked:
+ return "running"
+ if _spend_build(team.id, user.id, config) is not None:
+ cache.delete(lock_key)
+ return "rate_limited"
+ build_personal_inbox_ranking.delay(team.id, user.id, focus, limit)
+ return "started"
+ except Exception as error:
+ # A broker or cache failure must not fail the read, which still has a list to serve.
+ capture_exception(error, {"team_id": team.id, "user_id": user.id})
+ if locked:
+ with suppress(Exception):
+ cache.delete(lock_key)
+ return "failed"
+
+
+def _latest_row(team: Team, user: User) -> PersonalInboxRanking | None:
+ return PersonalInboxRanking.objects.for_team(team.id).filter(user_id=user.id).order_by("-created_at", "-id").first()
+
+
+def _wait_for_new_row(
+ team: Team, user: User, previous: PersonalInboxRanking | None, wait_seconds: int
+) -> PersonalInboxRanking | None:
+ deadline = time.monotonic() + wait_seconds
+ while True:
+ row = _latest_row(team, user)
+ if row is not None and (previous is None or row.id != previous.id):
+ return row
+ if time.monotonic() >= deadline:
+ return None
+ time.sleep(_WAIT_POLL_SECONDS)
+
+
def _ready_summary_version(team: Team, user: User) -> int | None:
summary = get_summary(team, user.id)
return summary.version if summary is not None and summary.status == ActivitySummaryStatus.READY else None
@@ -167,7 +224,13 @@ def _entries(ranked: Sequence[Mapping[str, Any]], by_id: Mapping[str, Candidate]
def _serve_row(
- row: PersonalInboxRanking, candidates: Sequence[Candidate], *, limit: int, cached: bool, stale: bool
+ row: PersonalInboxRanking,
+ candidates: Sequence[Candidate],
+ *,
+ limit: int,
+ cached: bool,
+ stale: bool,
+ building: bool,
) -> ServedRanking:
result = row.result or {}
ranked = result.get("ranked") or []
@@ -177,6 +240,7 @@ def _serve_row(
personalized=row.personalized,
cached=cached,
stale=stale,
+ building=building,
fallback_reason=row.fallback_reason,
generated_at=row.created_at,
latency_ms=row.latency_ms,
@@ -191,6 +255,43 @@ def _serve_row(
)
+def _serve_inbox_order(candidates: Sequence[Candidate], *, limit: int, building: bool, reason: str) -> ServedRanking:
+ """The list before any build is stored: every candidate in inbox order, with no model call."""
+ by_ref = {candidate.ref: candidate for candidate in candidates}
+ ranked = model_order(
+ [candidate.ref for candidate in candidates],
+ {candidate.ref: model_order_reason(candidate) for candidate in candidates},
+ limit,
+ )
+ return ServedRanking(
+ status="ready",
+ personalized=False,
+ cached=False,
+ stale=False,
+ building=building,
+ fallback_reason=reason,
+ generated_at=None,
+ latency_ms=None,
+ activity_summary_version=None,
+ candidates_considered=len(candidates),
+ ranked_count=len(ranked),
+ results=tuple(
+ ServedEntry(
+ rank=entry.rank,
+ tier=entry.tier,
+ reason=entry.reason,
+ next_step=None,
+ matched_theme=None,
+ needs_you=by_ref[entry.ref].needs_you,
+ ranked_by=entry.ranked_by,
+ report=_served_report(by_ref[entry.ref]),
+ )
+ for entry in ranked[:limit]
+ ),
+ folded=(),
+ )
+
+
def serve_personal_ranking(
team: Team,
user: User,
@@ -198,6 +299,7 @@ def serve_personal_ranking(
limit: int | None = None,
refresh: bool = False,
focus: str | None = None,
+ wait_seconds: int = 0,
config: PersonalRankingConfig | None = None,
) -> ServedRanking:
config = config or read_config()
@@ -205,11 +307,10 @@ def serve_personal_ranking(
return UNAVAILABLE
limit = min(max(limit or config.default_limit, 1), config.max_limit)
focus = normalize_focus(focus, config.focus_max_chars)
+ wait_seconds = min(max(wait_seconds, 0), MAX_WAIT_SECONDS)
now = timezone.now()
- latest = (
- PersonalInboxRanking.objects.for_team(team.id).filter(user_id=user.id).order_by("-created_at", "-id").first()
- )
+ latest = _latest_row(team, user)
candidates = gather_candidates(team, user, config, now=now, with_sources=False)
current_hash = input_hash(candidates, activity_summary_version=_ready_summary_version(team, user), focus=focus)
current = (
@@ -218,16 +319,18 @@ def serve_personal_ranking(
and latest.input_hash == current_hash
)
if latest is not None and current and not refresh and focus is None:
- return _serve_row(latest, candidates, limit=limit, cached=True, stale=False)
-
- retry_after = _spend_build(team.id, user.id, config)
- if retry_after is not None:
- if latest is None:
- raise BuildThrottledError(retry_after)
- return _serve_row(latest, candidates, limit=limit, cached=True, stale=not current)
-
- build = build_personal_ranking(team, user, focus=focus, limit=limit, config=config)
- if build.ranking_id is None:
- return UNAVAILABLE
- row = PersonalInboxRanking.objects.for_team(team.id).get(id=build.ranking_id, team_id=team.id, user_id=user.id)
- return _serve_row(row, build.candidates, limit=limit, cached=False, stale=False)
+ return _serve_row(latest, candidates, limit=limit, cached=True, stale=False, building=False)
+
+ start = _start_build(team, user, config, focus, limit)
+ building = start in ("started", "running")
+ if building and wait_seconds:
+ built = _wait_for_new_row(team, user, latest, wait_seconds)
+ if built is not None:
+ stale = built.input_hash != current_hash
+ return _serve_row(built, candidates, limit=limit, cached=False, stale=stale, building=False)
+ if latest is not None:
+ return _serve_row(latest, candidates, limit=limit, cached=True, stale=not current, building=building)
+ reason = (
+ FALLBACK_BUILDING if building else FALLBACK_RATE_LIMITED if start == "rate_limited" else FALLBACK_BUILD_FAILED
+ )
+ return _serve_inbox_order(candidates, limit=limit, building=building, reason=reason)
diff --git a/products/signals/backend/personal_ranking_tasks.py b/products/signals/backend/personal_ranking_tasks.py
new file mode 100644
index 000000000000..bbc76d197da4
--- /dev/null
+++ b/products/signals/backend/personal_ranking_tasks.py
@@ -0,0 +1,29 @@
+from django.core.cache import cache
+
+from celery import shared_task
+
+from posthog.models import Team, User
+from posthog.models.scoping import with_team_scope
+
+from products.signals.backend.personal_ranking.logic import build_personal_ranking
+
+# Above the task's time_limit, so a live build never loses its lock. It also frees the lock of a worker that died.
+BUILD_LOCK_TTL_SECONDS = 5 * 60
+
+
+def build_lock_key(team_id: int, user_id: int) -> str:
+ return f"signals_personal_ranking_build/{team_id}/{user_id}"
+
+
+@shared_task(ignore_result=True, max_retries=0, soft_time_limit=3 * 60, time_limit=4 * 60)
+@with_team_scope()
+def build_personal_inbox_ranking(team_id: int, user_id: int, focus: str | None, limit: int | None) -> None:
+ """Build and store one person's ranked inbox list. The `for_me` read takes the lock before it queues this task."""
+ try:
+ team = Team.objects.filter(id=team_id).first()
+ user = User.objects.filter(id=user_id).first()
+ if team is None or user is None:
+ return
+ build_personal_ranking(team, user, focus=focus, limit=limit)
+ finally:
+ cache.delete(build_lock_key(team_id, user_id))
diff --git a/products/signals/backend/serializers.py b/products/signals/backend/serializers.py
index 23f8f2dca6ba..ec76f0a9b773 100644
--- a/products/signals/backend/serializers.py
+++ b/products/signals/backend/serializers.py
@@ -1479,7 +1479,10 @@ class PersonalRankingQuerySerializer(serializers.Serializer):
)
refresh = serializers.BooleanField(
default=False,
- help_text="Build a new list even when the stored one is current. A build calls a model and can take 30 seconds or more.",
+ help_text=(
+ "Start a new build even when the stored one is current. The build runs in the background, so the "
+ "response has `building: true`. Pass `wait_seconds` to wait for it."
+ ),
)
focus = serializers.CharField(
required=False,
@@ -1487,7 +1490,17 @@ class PersonalRankingQuerySerializer(serializers.Serializer):
max_length=2000,
help_text=(
"Free text about what to put first, such as `error tracking` or `billing reports`. A request with "
- "focus always builds a new list, and an unfocused request never reuses it."
+ "focus always starts a new build, and an unfocused request never reuses it. Pass `wait_seconds` to "
+ "wait for it."
+ ),
+ )
+ wait_seconds = serializers.IntegerField(
+ default=0,
+ min_value=0,
+ max_value=30,
+ help_text=(
+ "When the request starts a build or one is running, wait up to this many seconds for its list. "
+ "Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds."
),
)
@@ -1550,19 +1563,31 @@ class PersonalRankingSerializer(serializers.Serializer):
)
)
cached = serializers.BooleanField(
- help_text="True when the list comes from storage, false when this request built it."
+ help_text=(
+ "True when the list is a stored one. False when it is the inbox order fallback or the new list "
+ "that `wait_seconds` waited for."
+ )
)
stale = serializers.BooleanField(
help_text=(
- "True when the list does not match your current inbox, because you reached the build limit. "
- "Try `refresh` again later."
+ "True when the list does not match your current inbox or focus. When `building` is true, a newer "
+ "list is on the way. Otherwise you reached the build limit, so try again later."
+ )
+ )
+ building = serializers.BooleanField(
+ help_text=(
+ "True when a new list is being built in the background. Call again in a few seconds, or pass "
+ "`wait_seconds`, to get it."
)
)
fallback_reason = serializers.CharField(
allow_null=True,
help_text=(
- "Why the list is in inbox order and not ranked by the language model: llm_error, timeout, "
- "malformed_output, truncated_output, no_candidates or ai_not_approved. Null when the model ranked it."
+ "Why the list is in inbox order and not ranked by the language model. building: no list is stored "
+ "yet and one is being built. rate_limited: no list is stored yet and you reached the build limit. "
+ "build_failed: no list is stored yet and the build could not start. llm_error, timeout, "
+ "malformed_output, truncated_output, no_candidates or ai_not_approved: the stored build fell back. "
+ "Null when the model ranked it."
),
)
generated_at = serializers.DateTimeField(allow_null=True, help_text="When the list was built.")
diff --git a/products/signals/backend/tasks.py b/products/signals/backend/tasks.py
index ee57940875b7..5e9af3cb1ee0 100644
--- a/products/signals/backend/tasks.py
+++ b/products/signals/backend/tasks.py
@@ -54,6 +54,7 @@ from products.signals.backend.models import (
SignalScoutRun,
SignalScratchpad,
)
+from products.signals.backend.personal_ranking_tasks import build_personal_inbox_ranking as build_personal_inbox_ranking
from products.signals.backend.pr_origin import write_origin_section
from products.signals.backend.pull_request_body import BodyEditOutcome
from products.signals.backend.pull_request_label import apply_pull_request_label
diff --git a/products/signals/backend/test/test_personal_ranking.py b/products/signals/backend/test/test_personal_ranking.py
index 0f6ea345f35b..edf054a07806 100644
--- a/products/signals/backend/test/test_personal_ranking.py
+++ b/products/signals/backend/test/test_personal_ranking.py
@@ -9,6 +9,7 @@ import time_machine
from posthog.test.base import APIBaseTest, BaseTest
from unittest.mock import MagicMock, patch
+from django.core.cache import cache
from django.core.management import call_command
from django.test import SimpleTestCase
from django.utils import timezone
@@ -43,6 +44,7 @@ from products.signals.backend.personal_ranking.config import (
from products.signals.backend.personal_ranking.logic import BUILT_EVENT, build_personal_ranking
from products.signals.backend.personal_ranking.prompt import render_person, user_message
from products.signals.backend.personal_ranking.validation import MalformedRankingError, validate_ranking
+from products.signals.backend.personal_ranking_tasks import build_lock_key, build_personal_inbox_ranking
from products.signals.backend.ranking.report_predictions import OutcomePrediction, ReportPredictions
REFS = ["c1", "c2", "c3", "c4"]
@@ -299,10 +301,11 @@ class TestBuildPersonalRanking(BaseTest):
def setUp(self) -> None:
super().setUp()
self.llm = MagicMock()
- self.capture = MagicMock()
+ scoped_capture = MagicMock()
+ self.capture = scoped_capture.return_value.__enter__.return_value
for target, value in (
("products.signals.backend.personal_ranking.logic.build_openai_client", MagicMock(return_value=self.llm)),
- ("products.signals.backend.personal_ranking.logic.posthoganalytics.capture", self.capture),
+ ("products.signals.backend.personal_ranking.logic.ph_scoped_capture", scoped_capture),
(
"products.signals.backend.personal_ranking.candidates.fetch_source_products_for_reports",
MagicMock(return_value={}),
@@ -557,10 +560,13 @@ class TestForMeEndpoint(APIBaseTest):
super().setUp()
TEST_clear_clients()
TEST_reset_scripts()
+ cache.delete(build_lock_key(self.team.id, self.user.id))
self.organization.is_ai_data_processing_approved = False
self.organization.save()
self.payload: dict[str, Any] = {"build_burst": 10}
self.flag_enabled = True
+ self.queued: list[tuple[Any, ...]] = []
+ self.delay = MagicMock(side_effect=lambda *args: self.queued.append(args))
for target, value in (
(
"products.signals.backend.personal_ranking.config.read_flag_payload",
@@ -574,7 +580,8 @@ class TestForMeEndpoint(APIBaseTest):
"products.signals.backend.personal_ranking.candidates.fetch_source_products_for_reports",
MagicMock(return_value={}),
),
- ("products.signals.backend.personal_ranking.logic.posthoganalytics.capture", MagicMock()),
+ ("products.signals.backend.personal_ranking.logic.ph_scoped_capture", MagicMock()),
+ ("products.signals.backend.personal_ranking.serve.build_personal_inbox_ranking.delay", self.delay),
):
patcher = patch(target, value)
patcher.start()
@@ -599,63 +606,108 @@ class TestForMeEndpoint(APIBaseTest):
assert response.status_code == 200, response.json()
return response.json()
- def test_reuses_a_current_list_and_builds_when_inputs_change(self) -> None:
+ def _run_builds(self) -> None:
+ queued, self.queued = self.queued, []
+ for args in queued:
+ build_personal_inbox_ranking(*args)
+
+ def _state(self, body: dict[str, Any]) -> tuple[bool, bool, bool]:
+ return body["cached"], body["stale"], body["building"]
+
+ def test_serves_without_building_and_queues_one_build_per_user(self) -> None:
first = self._claimed_report("First")
body = self._get()
- assert (body["cached"], body["fallback_reason"], self._rows()) == (False, "ai_not_approved", 1)
+ assert (body["fallback_reason"], self._state(body), self._rows()) == ("building", (False, False, True), 0)
assert [entry["report"]["id"] for entry in body["results"]] == [str(first.id)]
assert body["results"][0]["matched"]["needs_you"] == ["claimed"]
+ assert self._get()["building"] is True
+ assert len(self.queued) == 1
+
+ self._run_builds()
+ body = self._get()
+ assert (body["fallback_reason"], self._state(body), self._rows()) == (
+ "ai_not_approved",
+ (True, False, False),
+ 1,
+ )
+ assert self.queued == []
- assert (self._get()["cached"], self._rows()) == (True, 1)
- assert (self._get(refresh="true")["cached"], self._rows()) == (False, 2)
+ assert self._state(self._get(refresh="true")) == (True, False, True)
+ self._run_builds()
+ assert self._rows() == 2
first.title = "First, edited"
first.save()
- assert (self._get()["cached"], self._rows()) == (False, 3)
+ assert self._state(self._get()) == (True, True, True)
+ self._run_builds()
+ assert (self._state(self._get()), self._rows()) == ((True, False, False), 3)
second = self._claimed_report("Second")
+ assert self._state(self._get()) == (True, True, True)
+ self._run_builds()
body = self._get()
- assert (body["cached"], self._rows()) == (False, 4)
assert {entry["report"]["id"] for entry in body["results"]} == {str(first.id), str(second.id)}
- assert (self._get(focus="checkout")["cached"], self._rows()) == (False, 5)
- assert (self._get()["cached"], self._rows()) == (False, 6)
+ assert self._state(self._get(focus="checkout")) == (True, True, True)
+ self._run_builds()
+ assert (self._state(self._get()), self._rows()) == ((True, True, True), 5)
+ self._run_builds()
+
+ self.delay.side_effect = build_personal_inbox_ranking
+ body = self._get(refresh="true", wait_seconds=5)
+ assert (self._state(body), self._rows()) == ((False, False, False), 7)
- def test_throttled_build_returns_the_stored_list_or_429(self) -> None:
+ def test_throttled_build_serves_the_stored_list_or_the_inbox_order(self) -> None:
self.payload = {"build_burst": 1, "builds_per_hour": 1}
first = self._claimed_report("First")
self._get()
+ self._run_builds()
- assert (self._get(refresh="true")["cached"], self._rows()) == (True, 1)
+ assert (self._state(self._get(refresh="true")), self.queued) == ((True, False, False), [])
self._claimed_report("Second")
body = self._get()
- assert (body["cached"], body["stale"], self._rows()) == (True, True, 1)
+ assert (self._state(body), self._rows()) == ((True, True, False), 1)
assert [entry["report"]["id"] for entry in body["results"]] == [str(first.id)]
PersonalInboxRanking.objects.for_team(self.team.id).all().delete()
- assert self.client.get(self._url()).status_code == 429
+ body = self._get()
+ assert (body["fallback_reason"], body["building"], len(body["results"])) == ("rate_limited", False, 2)
+
+ def test_failed_enqueue_serves_the_inbox_order_and_frees_the_lock(self) -> None:
+ self._claimed_report("First")
+ self.delay.side_effect = RuntimeError("broker down")
+
+ body = self._get()
+
+ assert (body["fallback_reason"], body["building"], len(body["results"])) == ("build_failed", False, 1)
+ self.delay.side_effect = lambda *args: self.queued.append(args)
+ assert self._get()["building"] is True
def test_daily_cap_holds_across_hours(self) -> None:
self.payload = {"build_burst": 10, "builds_per_hour": 120, "builds_per_day": 2}
self._claimed_report("First")
with time_machine.travel(timezone.now(), tick=False) as traveller:
self._get()
+ self._run_builds()
self._get(refresh="true")
+ self._run_builds()
traveller.shift(datetime.timedelta(hours=3))
- assert (self._get(refresh="true")["cached"], self._rows()) == (True, 2)
+ assert (self._get(refresh="true")["building"], self._rows()) == (False, 2)
traveller.shift(datetime.timedelta(hours=9))
- assert (self._get(refresh="true")["cached"], self._rows()) == (False, 3)
+ assert self._get(refresh="true")["building"] is True
def test_another_user_never_reads_your_list(self) -> None:
self._get()
+ self._run_builds()
other = User.objects.create_and_join(self.organization, "[email protected]", "password")
self.client.force_login(other)
body = self._get()
+ self._run_builds()
- assert body["cached"] is False
+ assert (body["cached"], body["fallback_reason"]) == (False, "building")
assert PersonalInboxRanking.objects.for_team(self.team.id).filter(user_id=other.id).count() == 1
@parameterized.expand([("flag_off", {"enabled": True}, False), ("kill_switch", {"enabled": False}, True)])
@@ -667,4 +719,4 @@ class TestForMeEndpoint(APIBaseTest):
assert (response.json()["status"], response.json()["results"]) == ("unavailable", [])
else:
assert response.status_code == 404
- assert self._rows() == 0
+ assert (self._rows(), self.queued) == (0, [])
diff --git a/products/signals/backend/views.py b/products/signals/backend/views.py
index 959c837e1d99..44d26367e74c 100644
--- a/products/signals/backend/views.py
+++ b/products/signals/backend/views.py
@@ -155,7 +155,7 @@ from products.signals.backend.models import (
SignalUserAutonomyConfig,
)
from products.signals.backend.personal_ranking.config import PERSONAL_INBOX_RANKING_FLAG
-from products.signals.backend.personal_ranking.serve import BuildThrottledError, serve_personal_ranking
+from products.signals.backend.personal_ranking.serve import serve_personal_ranking
from products.signals.backend.pr_ci_status import pr_ci_statuses_for_references, rollup_ci_status
from products.signals.backend.presentation.scout_permissions import ScoutCanonicalTeamAccessPermission
from products.signals.backend.pull_requests import import_report_pull_requests
@@ -1735,14 +1735,15 @@ class SignalReportViewSet(
responses={
200: OpenApiResponse(response=PersonalRankingSerializer),
404: OpenApiResponse(description="Personal ranking is not available to the caller."),
- 429: OpenApiResponse(description="The build limit is reached and no stored list exists yet."),
},
summary="Get your personal ranked inbox",
description=(
"Your open inbox reports, ranked for you by one language model call over your activity summary, the "
"reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. "
- "A current stored list returns at once. Otherwise the request builds a new list, which can take 30 "
- "seconds or more. Only the user the list is about can read it."
+ "The request never waits on the model. A current stored list returns at once. Otherwise the request "
+ "starts a background build and returns the last stored list with `stale: true`, or your reports in inbox "
+ "order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time "
+ "for the new list. Only the user the list is about can read it."
),
)
@action(detail=False, methods=["get"], url_path="for_me", required_scopes=["task:read"], pagination_class=None)
@@ -1758,12 +1759,14 @@ class SignalReportViewSet(
raise NotFound()
query = request.validated_query_data
started = time.monotonic()
- try:
- served = serve_personal_ranking(
- self.team, user, limit=query.get("limit"), refresh=query["refresh"], focus=query.get("focus")
- )
- except BuildThrottledError as error:
- raise exceptions.Throttled(wait=error.retry_after)
+ served = serve_personal_ranking(
+ self.team,
+ user,
+ limit=query.get("limit"),
+ refresh=query["refresh"],
+ focus=query.get("focus"),
+ wait_seconds=query["wait_seconds"],
+ )
report_user_action(
user,
"personal inbox ranking read",
@@ -1772,10 +1775,12 @@ class SignalReportViewSet(
"status": served.status,
"cached": served.cached,
"stale": served.stale,
+ "building": served.building,
"personalized": served.personalized,
"fallback_reason": served.fallback_reason,
"refresh": query["refresh"],
"has_focus": bool(query.get("focus")),
+ "wait_seconds": query["wait_seconds"],
"result_count": len(served.results),
"duration_ms": round((time.monotonic() - started) * 1000),
},
diff --git a/products/signals/frontend/generated/api.schemas.ts b/products/signals/frontend/generated/api.schemas.ts
index 80ec49531b1a..8635e76aef51 100644
--- a/products/signals/frontend/generated/api.schemas.ts
+++ b/products/signals/frontend/generated/api.schemas.ts
@@ -6104,12 +6104,14 @@ export interface PersonalRankingApi {
status: PersonalRankingStatusEnumApi
/** True when the language model ranked the list with your activity summary. False when you have no summary yet or the build fell back to the inbox order. */
personalized: boolean
- /** True when the list comes from storage, false when this request built it. */
+ /** True when the list is a stored one. False when it is the inbox order fallback or the new list that `wait_seconds` waited for. */
cached: boolean
- /** True when the list does not match your current inbox, because you reached the build limit. Try `refresh` again later. */
+ /** True when the list does not match your current inbox or focus. When `building` is true, a newer list is on the way. Otherwise you reached the build limit, so try again later. */
stale: boolean
+ /** True when a new list is being built in the background. Call again in a few seconds, or pass `wait_seconds`, to get it. */
+ building: boolean
/**
- * Why the list is in inbox order and not ranked by the language model: llm_error, timeout, malformed_output, truncated_output, no_candidates or ai_not_approved. Null when the model ranked it.
+ * Why the list is in inbox order and not ranked by the language model. building: no list is stored yet and one is being built. rate_limited: no list is stored yet and you reached the build limit. build_failed: no list is stored yet and the build could not start. llm_error, timeout, malformed_output, truncated_output, no_candidates or ai_not_approved: the stored build fell back. Null when the model ranked it.
* @nullable
*/
fallback_reason: string | null
@@ -11075,7 +11077,7 @@ export type SignalsReportsAvailableReviewersRetrieve200 = {
export type SignalsReportsForMeRetrieveParams = {
/**
- * Free text about what to put first, such as `error tracking` or `billing reports`. A request with focus always builds a new list, and an unfocused request never reuses it.
+ * Free text about what to put first, such as `error tracking` or `billing reports`. A request with focus always starts a new build, and an unfocused request never reuses it. Pass `wait_seconds` to wait for it.
* @maxLength 2000
*/
focus?: string
@@ -11086,9 +11088,15 @@ export type SignalsReportsForMeRetrieveParams = {
*/
limit?: number
/**
- * Build a new list even when the stored one is current. A build calls a model and can take 30 seconds or more.
+ * Start a new build even when the stored one is current. The build runs in the background, so the response has `building: true`. Pass `wait_seconds` to wait for it.
*/
refresh?: boolean
+ /**
+ * When the request starts a build or one is running, wait up to this many seconds for its list. Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds.
+ * @minimum 0
+ * @maximum 30
+ */
+ wait_seconds?: number
}
export type SignalsReportsPrCiStatusesParams = {
diff --git a/products/signals/frontend/generated/api.ts b/products/signals/frontend/generated/api.ts
index 6e52ea5c76ac..1a9346ac527a 100644
--- a/products/signals/frontend/generated/api.ts
+++ b/products/signals/frontend/generated/api.ts
@@ -1561,7 +1561,7 @@ export const getSignalsReportsForMeRetrieveUrl = (projectId: string, params?: Si
}
/**
- * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. A current stored list returns at once. Otherwise the request builds a new list, which can take 30 seconds or more. Only the user the list is about can read it.
+ * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. A current stored list returns at once. Otherwise the request starts a background build and returns the last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
* @summary Get your personal ranked inbox
*/
export const signalsReportsForMeRetrieve = async (
diff --git a/products/signals/mcp/tools.yaml b/products/signals/mcp/tools.yaml
index 55e73e6f2719..99ffe8e6ef9f 100644
--- a/products/signals/mcp/tools.yaml
+++ b/products/signals/mcp/tools.yaml
@@ -423,10 +423,13 @@ tools:
highest, using their activity summary. Use it for "what should I work on" and "my top N" questions in place
of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries
and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is
- personal: only the user it describes can read it. A current stored list returns at once; otherwise the call
- builds one, which can take 30 seconds or more. `refresh` and `focus` always build a new list, and builds are
- rate limited. `personalized: false` means the user has no activity summary yet or the build fell back to the
- inbox order (see `fallback_reason`). `stale: true` means the build limit was reached and the list may miss
+ personal: only the user it describes can read it. The call returns at once and never waits on the model. A
+ current stored list comes back as is. Otherwise the call starts a background build and returns the last
+ stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets
+ `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. When `building`
+ is true, call again a little later, or pass `wait_seconds` (up to 30) to wait for the new list in the same
+ call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see
+ `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss
recent changes. `status: unavailable` means personal ranking is off for now.
feature_flag: personal-inbox-ranking
inbox-reports-leave-reviewers:
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index a39545b9e4d0..35b0456d12f1 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -7983,7 +7983,7 @@
}
},
"inbox-reports-for-me": {
- "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks the reports that need them (suggested reviewer, claimed, waiting on their input) and the reports the ranking model rates highest, using their activity summary. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. A current stored list returns at once; otherwise the call builds one, which can take 30 seconds or more. `refresh` and `focus` always build a new list, and builds are rate limited. `personalized: false` means the user has no activity summary yet or the build fell back to the inbox order (see `fallback_reason`). `stale: true` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
+ "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks the reports that need them (suggested reviewer, claimed, waiting on their input) and the reports the ranking model rates highest, using their activity summary. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call returns at once and never waits on the model. A current stored list comes back as is. Otherwise the call starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
"category": "Signals",
"feature": "signals",
"summary": "Get your personal ranked inbox",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index c6f85c53c624..17b4ca74e7af 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -8215,7 +8215,7 @@
}
},
"inbox-reports-for-me": {
- "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks the reports that need them (suggested reviewer, claimed, waiting on their input) and the reports the ranking model rates highest, using their activity summary. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. A current stored list returns at once; otherwise the call builds one, which can take 30 seconds or more. `refresh` and `focus` always build a new list, and builds are rate limited. `personalized: false` means the user has no activity summary yet or the build fell back to the inbox order (see `fallback_reason`). `stale: true` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
+ "description": "Get the current user's own open inbox reports, ranked for them. One language model call ranks the reports that need them (suggested reviewer, claimed, waiting on their input) and the reports the ranking model rates highest, using their activity summary. Use it for \"what should I work on\" and \"my top N\" questions in place of paging inbox-reports-list. Each entry has a rank, a tier, a short reason, a next step for the top entries and a compact report. Read the full report with inbox-reports-retrieve before you act on it. The list is personal: only the user it describes can read it. The call returns at once and never waits on the model. A current stored list comes back as is. Otherwise the call starts a background build and returns the last stored list with `stale: true`, or the reports in inbox order with `fallback_reason: building`, and sets `building: true`. `refresh` and `focus` always start a build, and builds are rate limited. When `building` is true, call again a little later, or pass `wait_seconds` (up to 30) to wait for the new list in the same call. `personalized: false` means the user has no activity summary yet or the list is in inbox order (see `fallback_reason`). `stale: true` without `building` means the build limit was reached and the list may miss recent changes. `status: unavailable` means personal ranking is off for now.",
"category": "Signals",
"feature": "signals",
"summary": "Get your personal ranked inbox",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 1622b39e95ce..75fb305892c2 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -96073,12 +96073,14 @@ export namespace Schemas {
status: PersonalRankingStatusEnum;
/** True when the language model ranked the list with your activity summary. False when you have no summary yet or the build fell back to the inbox order. */
personalized: boolean;
- /** True when the list comes from storage, false when this request built it. */
+ /** True when the list is a stored one. False when it is the inbox order fallback or the new list that `wait_seconds` waited for. */
cached: boolean;
- /** True when the list does not match your current inbox, because you reached the build limit. Try `refresh` again later. */
+ /** True when the list does not match your current inbox or focus. When `building` is true, a newer list is on the way. Otherwise you reached the build limit, so try again later. */
stale: boolean;
+ /** True when a new list is being built in the background. Call again in a few seconds, or pass `wait_seconds`, to get it. */
+ building: boolean;
/**
- * Why the list is in inbox order and not ranked by the language model: llm_error, timeout, malformed_output, truncated_output, no_candidates or ai_not_approved. Null when the model ranked it.
+ * Why the list is in inbox order and not ranked by the language model. building: no list is stored yet and one is being built. rate_limited: no list is stored yet and you reached the build limit. build_failed: no list is stored yet and the build could not start. llm_error, timeout, malformed_output, truncated_output, no_candidates or ai_not_approved: the stored build fell back. Null when the model ranked it.
* @nullable
*/
fallback_reason: string | null;
@@ -142201,7 +142203,7 @@ export namespace Schemas {
export type SignalsReportsForMeRetrieveParams = {
/**
- * Free text about what to put first, such as `error tracking` or `billing reports`. A request with focus always builds a new list, and an unfocused request never reuses it.
+ * Free text about what to put first, such as `error tracking` or `billing reports`. A request with focus always starts a new build, and an unfocused request never reuses it. Pass `wait_seconds` to wait for it.
* @maxLength 2000
*/
focus?: string;
@@ -142212,9 +142214,15 @@ export namespace Schemas {
*/
limit?: number;
/**
- * Build a new list even when the stored one is current. A build calls a model and can take 30 seconds or more.
+ * Start a new build even when the stored one is current. The build runs in the background, so the response has `building: true`. Pass `wait_seconds` to wait for it.
*/
refresh?: boolean;
+ /**
+ * When the request starts a build or one is running, wait up to this many seconds for its list. Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds.
+ * @minimum 0
+ * @maximum 30
+ */
+ wait_seconds?: number;
};
export type SignalsReportsPrCiStatusesParams = {
diff --git a/services/mcp/src/generated/signals/api.ts b/services/mcp/src/generated/signals/api.ts
index 85061a2f5392..0635a27bb2f4 100644
--- a/services/mcp/src/generated/signals/api.ts
+++ b/services/mcp/src/generated/signals/api.ts
@@ -1419,7 +1419,7 @@ export const SignalsReportsBulkStateCreateBody = () => zod.object({
})
/**
- * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. A current stored list returns at once. Otherwise the request builds a new list, which can take 30 seconds or more. Only the user the list is about can read it.
+ * Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. A current stored list returns at once. Otherwise the request starts a background build and returns the last stored list with `stale: true`, or your reports in inbox order with `fallback_reason: building`, and `building: true`. Pass `wait_seconds` to wait a short time for the new list. Only the user the list is about can read it.
* @summary Get your personal ranked inbox
*/
export const SignalsReportsForMeRetrieveParams = () => zod.object({
@@ -1435,6 +1435,9 @@ export const signalsReportsForMeRetrieveQueryFocusMax = 2000
export const signalsReportsForMeRetrieveQueryLimitMax = 100
export const signalsReportsForMeRetrieveQueryRefreshDefault = false
+export const signalsReportsForMeRetrieveQueryWaitSecondsDefault = 0
+export const signalsReportsForMeRetrieveQueryWaitSecondsMin = 0
+export const signalsReportsForMeRetrieveQueryWaitSecondsMax = 30
export const SignalsReportsForMeRetrieveQueryParams = () => zod.object({
focus: zod
@@ -1442,7 +1445,7 @@ export const SignalsReportsForMeRetrieveQueryParams = () => zod.object({
.max(signalsReportsForMeRetrieveQueryFocusMax)
.optional()
.describe(
- 'Free text about what to put first, such as `error tracking` or `billing reports`. A request with focus always builds a new list, and an unfocused request never reuses it.'
+ 'Free text about what to put first, such as `error tracking` or `billing reports`. A request with focus always starts a new build, and an unfocused request never reuses it. Pass `wait_seconds` to wait for it.'
),
limit: zod
.number()
@@ -1456,7 +1459,15 @@ export const SignalsReportsForMeRetrieveQueryParams = () => zod.object({
.boolean()
.default(signalsReportsForMeRetrieveQueryRefreshDefault)
.describe(
- 'Build a new list even when the stored one is current. A build calls a model and can take 30 seconds or more.'
+ 'Start a new build even when the stored one is current. The build runs in the background, so the response has `building: true`. Pass `wait_seconds` to wait for it.'
+ ),
+ wait_seconds: zod
+ .number()
+ .min(signalsReportsForMeRetrieveQueryWaitSecondsMin)
+ .max(signalsReportsForMeRetrieveQueryWaitSecondsMax)
+ .default(signalsReportsForMeRetrieveQueryWaitSecondsDefault)
+ .describe(
+ 'When the request starts a build or one is running, wait up to this many seconds for its list. Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds.'
),
})
diff --git a/services/mcp/src/tools/generated/signals.ts b/services/mcp/src/tools/generated/signals.ts
index f546ba1e232b..9ef65de4224f 100644
--- a/services/mcp/src/tools/generated/signals.ts
+++ b/services/mcp/src/tools/generated/signals.ts
@@ -653,6 +653,7 @@ const inboxReportsForMe = (): ToolBase<ReturnType<typeof InboxReportsForMeSchema
focus: params.focus,
limit: params.limit,
refresh: params.refresh,
+ wait_seconds: params.wait_seconds,
},
})
return result
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
index 263b5d25a77e..bda4906ce827 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/inbox-reports-for-me.json
@@ -2,7 +2,7 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"focus": {
- "description": "Free text about what to put first, such as `error tracking` or `billing reports`. A request with focus always builds a new list, and an unfocused request never reuses it.",
+ "description": "Free text about what to put first, such as `error tracking` or `billing reports`. A request with focus always starts a new build, and an unfocused request never reuses it. Pass `wait_seconds` to wait for it.",
"maxLength": 2000,
"type": "string"
},
@@ -14,8 +14,15 @@
},
"refresh": {
"default": false,
- "description": "Build a new list even when the stored one is current. A build calls a model and can take 30 seconds or more.",
+ "description": "Start a new build even when the stored one is current. The build runs in the background, so the response has `building: true`. Pass `wait_seconds` to wait for it.",
"type": "boolean"
+ },
+ "wait_seconds": {
+ "default": 0,
+ "description": "When the request starts a build or one is running, wait up to this many seconds for its list. Defaults to 0, which returns at once. A build usually takes 10 to 60 seconds.",
+ "maximum": 30,
+ "minimum": 0,
+ "type": "number"
}
},
"type": "object"