HKUDS/Vibe-Trading · warning · ValueError

quarter year {year} is outside {_MIN_QUARTER_YEAR}..{date.to

Error message

quarter year {year} is outside {_MIN_QUARTER_YEAR}..{date.today().year + 1}

What it means

After parsing, the year must fall between _MIN_QUARTER_YEAR and the current year + 1. Years outside that window — historical data before the tool's coverage or far-future quarters — are rejected before any network call.

Source

Thrown at agent/src/tools/institutional_holdings_tool.py:365

    """
    text = str(value).strip().upper().replace(" ", "")
    match = re.fullmatch(r"(\d{4})-?Q([1-4])", text)
    if match:
        year, quarter = int(match.group(1)), int(match.group(2))
    else:
        match = re.fullmatch(r"(\d{4})-(\d{1,2})-(\d{1,2})", text)
        if not match:
            raise ValueError(
                f"quarter {value!r} is not recognizable; use '2026Q1' or a quarter-end date '2026-03-31'"
            )
        year, month, day = (int(g) for g in match.groups())
        quarter = next((q for q, md in _QUARTER_ENDS.items() if md == (month, day)), None)
        if quarter is None:
            raise ValueError(
                f"quarter {value!r} is not a calendar quarter end; use 03-31, 06-30, 09-30 or 12-31"
            )
    if not _MIN_QUARTER_YEAR <= year <= date.today().year + 1:
        raise ValueError(f"quarter year {year} is outside {_MIN_QUARTER_YEAR}..{date.today().year + 1}")
    month, day = _QUARTER_ENDS[quarter]
    return f"{year:04d}-{month:02d}-{day:02d}"


def _quarter_label(period_end: Optional[str]) -> Optional[str]:
    """Render a ``YYYY-MM-DD`` quarter end as ``YYYYQn``, or ``None`` if unusable."""
    if not period_end or len(str(period_end)) < 7:
        return None
    text = str(period_end)
    try:
        year, month = int(text[:4]), int(text[5:7])
    except ValueError:
        return None
    quarter = next((q for q, md in _QUARTER_ENDS.items() if md[0] == month), None)
    return f"{year}Q{quarter}" if quarter else None


def _latest_reportable_quarter(today: Optional[date] = None) -> str:

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Correct the year to a supported range
2. Check _MIN_QUARTER_YEAR in the module for the exact floor
3. Validate the year client-side before invoking the tool

Example fix

# before
execute(quarter="1998Q1")
# after
execute(quarter="2024Q1")

from datetime import date
y = int(q[:4])
assert _MIN_QUARTER_YEAR <= y <= date.today().year + 1, f"year {y} out of range"

def quarter_year_in_range(q: str, min_year: int) -> bool:
    from datetime import date
    try:
        y = int(q.split("Q")[0])
    except (ValueError, IndexError):
        return False
    return min_year <= y <= date.today().year + 1

try:
    qn = _parse_quarter(q)
except ValueError as e:
    if "outside" in str(e):
        raise UserInputError("quarter not covered by the data source")
    raise

When it happens

Trigger: quarter='1990Q2' (below _MIN_QUARTER_YEAR) or '2035Q1' (beyond next year).

Common situations: Typos in years ('2206Q1'); querying periods predating SEC 13F electronic data; speculative future quarters beyond the allowed lookahead.

Related errors

• vintage_year={self.vintage_year!r} is outside the plausible
• today must be an ISO date string or None, got {today!r}
• quarter {value!r} is not recognizable; use '2026Q1' or a qua
• quarter {value!r} is not a calendar quarter end; use 03-31,
• invalid alpha_id

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/520314149113cac3. Report an issue: GitHub.