Skip to content

"Vibe-Trading: Your Personal Trading Agent"

refactor(grounding): cut history narratives and duplicated rationale from the package prose

Haozhe Wu55464e85efcf
diff --git a/agent/src/agent/grounding/evidence.py b/agent/src/agent/grounding/evidence.py
index ce4437138..8a6fb71c5 100644
--- a/agent/src/agent/grounding/evidence.py
+++ b/agent/src/agent/grounding/evidence.py
@@ -1,9 +1,7 @@
"""Evidence intake: what a tool result is allowed to ground.
-Every observed number the gate can validate against enters through this module
-— market-data rows, registered indicator leaves, backtest metrics, run-dir CSVs
-and generic numeric leaves. The kind map is keyed on TOOL FIELD NAMES, not on
-natural language.
+Every observed number the gate validates against enters here. Kind maps are
+keyed on tool field names, never on natural language.
"""
from __future__ import annotations
@@ -25,17 +23,12 @@ from src.agent.grounding.identity import (
_PRICE_FIELDS = {"open", "high", "low", "close", "adj_close", "price"}
-
_TIMESTAMP_FIELDS = ("trade_date", "date", "datetime", "timestamp", "time", "index")
-
_MAX_GENERIC_EVIDENCE = 2_000
-
-# CSV columns (case-insensitive) accepted from OHLC files the run wrote via
-# bash+yfinance, and their canonical price-field names. Everything else in the
-# file (Volume, Adj Close, etc.) is deliberately ignored so the contradiction
-# check does not gain values it would be willing to accept.
+# Only these CSV columns count; Volume, Adj Close etc. are ignored so the
+# contradiction check gains no values it would be willing to accept.
_CSV_PRICE_COLUMNS = {
"open": "open",
"high": "high",
@@ -44,36 +37,18 @@ _CSV_PRICE_COLUMNS = {
"price": "price",
}
-
_CSV_DATE_COLUMNS = {"date", "datetime", "trade_date", "timestamp", "index"}
-
-# Filename -> symbol mapping for run-dir CSVs. The bash workaround writes each
-# series with a filesystem-safe stem: ``BYN_V.csv`` for ``BYN.V``, ``PDI_TO.csv``
-# for ``PDI.TO``, ``GC_F.csv`` for ``GC=F``.
_CSV_FILENAME_SUFFIX_MAP = (
("_V", ".V"),
("_TO", ".TO"),
("_F", "=F"),
- # A US name is written ``INTC_US.csv`` by the same workaround, and
- # ``.US`` is the venue suffix the rest of the project resolves on. Without
- # this row the CSV was ingested as no evidence at all, so every price the
- # run had actually fetched came back "numeric_claim_unavailable".
("_US", ".US"),
)
-
-# Only ``get_market_data`` returns bars whose columns are already the canonical
-# OHLC field names. Every other market-sensitive tool nests its quote somewhere,
-# and ``_ingest_generic_numeric`` stores that JSON path verbatim — "data.last",
-# "quote[0].close_price". Without this map those observations never reach the
-# final-answer check, so a price the run genuinely retrieved is rejected as
-# "no matching observed tool evidence": measured against the live validator, an
-# answer quoting a ``get_stock_profile`` price failed with
-# ``numeric_claim_unavailable`` while the identical claim backed by
-# ``get_market_data`` passed. Only unambiguous quote fields are mapped; ratios,
-# volumes, strikes, and analyst targets stay out so the contradiction check does
-# not gain a wider set of values it is willing to accept.
+# Nested quote leaves of non-OHLC tools ("data.last", "quote[0].close_price")
+# mapped to canonical price fields. Only unambiguous quote fields: ratios,
+# volumes, strikes and analyst targets stay out so the check accepts no more.
_GENERIC_PRICE_FIELD_ALIASES = {
"open": "open",
"open_price": "open",
@@ -116,10 +91,8 @@ _GENERIC_PRICE_FIELD_ALIASES = {
"最新价": "price",
}
-
-# Metric family for a claim/evidence leaf, so a figure is only grounded by
-# evidence of its own kind: an observed price must never stand in for an
-# invented volatility (#1336).
+# Metric family per field name: a figure is grounded only by evidence of its
+# own kind, so an observed price never stands in for a volatility (#1336).
_ANALYSIS_KIND_ALIASES = {
"annualized_vol": "vol",
"annualized_volatility": "vol",
@@ -146,9 +119,7 @@ _ANALYSIS_KIND_ALIASES = {
"return": "return",
"returns": "return",
"ic_positive_ratio": "win_rate",
- # A-share tools key their JSON in Chinese. These are TOOL FIELD NAMES, in
- # the same category as ``max_drawdown`` above: they name what a leaf of a
- # result IS. Nothing here reads the answer's prose.
+ # Chinese TOOL FIELD NAMES from A-share tools, not answer prose.
"最大回撤": "drawdown",
"回撤": "drawdown",
"夏普": "sharpe",
@@ -165,20 +136,16 @@ _ANALYSIS_KIND_ALIASES = {
def _symbol_from_csv_filename(stem: str) -> str | None:
- """Map a run-dir CSV stem back to a canonical project symbol.
+ """Map a run-dir CSV stem (``BYN_V`` -> ``BYN.V``) to a canonical symbol.
- The bash workaround writes filesystem-safe stems: ``BYN_V.csv`` -> ``BYN.V``,
- ``PDI_TO.csv`` -> ``PDI.TO``, ``GC_F.csv`` -> ``GC=F``, ``INTC_US.csv`` ->
- ``INTC.US``. A stem without a recognized suffix (e.g. a bare US name
- ``AAPL``) maps to None because the project convention requires an explicit
- venue suffix.
+ A stem without a known venue suffix (a bare ``AAPL``) maps to None, because
+ the project requires an explicit venue suffix.
Args:
stem: CSV filename without the ``.csv`` extension.
Returns:
- The canonical symbol, or ``None`` when the stem has no recognizable
- venue suffix.
+ The canonical symbol, or None.
"""
upper = (stem or "").strip().upper()
if not upper:
@@ -212,12 +179,7 @@ def _is_number(value: Any) -> bool:
def _coerce_csv_number(value: Any) -> int | float | None:
- """Coerce a CSV cell to a finite number, or return None.
-
- CSV readers return every cell as text (``"0.375"``), so a bare
- ``_is_number`` check would discard them all. Values that do not parse as a
- finite number (blank cells, ``-``, ``N/A``) return ``None``.
- """
+ """Coerce a CSV text cell (``"0.375"``) to a finite number, or None."""
if _is_number(value):
return value
if isinstance(value, str):
@@ -230,11 +192,9 @@ def _coerce_csv_number(value: Any) -> int | float | None:
return None
-# "." is deliberately not a separator: a decimal price such as 8.5 would parse
-# A date CELL in a report carries annotations the bare ISO form does not:
-# "08-10(一)", "08-10(周一)盘中", "2026-08-10". Only the leading date matters,
-# so the year is optional and everything after the day is ignored — which is
-# also how the weekday/session annotations stopped needing a vocabulary.
+# "." is not a separator: a decimal price such as 8.5 would parse as a date.
+# Only the leading month-day (optional year) matters; annotations after the
+# day ("08-10(一)", "08-10盘中") are ignored.
_CLAIM_DATE_RE = re.compile(
r"^\s*(?:((?:19|20)\d{2})\s*[-/年]\s*)?"
r"(0?[1-9]|1[0-2])\s*[-/月]\s*([12]\d|3[01]|0?[1-9])"
@@ -242,17 +202,10 @@ _CLAIM_DATE_RE = re.compile(
def _claim_date_tuple(date_value: str) -> tuple[int, int] | None:
- """Extract the (month, day) named by a report-style date cell.
-
- Reports routinely annotate a trading day: the date column reads
- ``08-10(一)``, ``08-10(周一)盘中`` or ``08-10盘中`` rather than the bare
- ``08-10`` the strict full-cell matchers accept. Any leading month-day (or
- full ISO date) prefix is therefore accepted so such a claim still compares
- against the matching evidence row instead of being reported as
- unevidenced.
+ """Extract the (month, day) a report-style date cell names.
Args:
- date_value: Date cell as written in the answer.
+ date_value: Date cell as written in the answer, e.g. ``08-10(周一)``.
Returns:
The (month, day) tuple, or None when no date prefix is present.
@@ -266,19 +219,9 @@ def _claim_date_tuple(date_value: str) -> tuple[int, int] | None:
def _timestamp_matches_claim_date(timestamp: str, date_value: str) -> bool:
"""Match an evidence timestamp against the date cell of a claim.
- The comparison used to be ``timestamp.startswith(date_value)``, which can
- only succeed when the answer repeats the year. A table whose date column
- reads ``08-05`` — the ordinary way a report writes a trading day — matched
- nothing, so every cell in the row was reported as having no supporting
- evidence while that evidence sat right there (#983: 79 such rejections in
- one run, every value inside the observed range).
-
- A year-less date is matched on month and day, and a date cell may carry
- weekday or intraday annotations (``08-10(一)``, ``08-10盘中``) whose
- leading month-day is still recognized. Matching the wrong year is a
- smaller failure than matching nothing, but it is a real one, so the
- caller still compares the value against every record that matched rather
- than trusting the date.
+ A year-less cell (``08-05``) matches on month and day. That can match the
+ wrong year, so callers still compare the value against every matched record
+ rather than trusting the date.
Args:
timestamp: Evidence timestamp, normally ISO ``YYYY-MM-DD``.
@@ -319,20 +262,9 @@ def _price_field_for_path(path: str) -> str | None:
return _GENERIC_PRICE_FIELD_ALIASES.get(leaf)
-# Price-denominated indicator leaves, REGISTERED PER TOOL (spec §5). The
-# previous rule guessed from path tokens: a leaf counted as a price when its
-# name carried a family word ("sma", "band", "pivot") and no non-price word.
-# Guessing from a name is the same failure as guessing from prose — the family
-# list and the denylist both had to be complete, and they were not:
-# ``indicators.ma_diff``, ``indicators.sma_cross`` and
-# ``indicators.supertrend_direction`` were all admitted as observed prices,
-# so a payload with any of them set to 1.30 let the answer print "现价 1.30 元".
-#
-# A tool's output shape is a fact about that tool, so it is stated here per
-# tool and matched by path prefix. A leaf that is not registered is still
-# recorded as evidence — it simply cannot ground a price. Adding a tool that
-# returns price levels means adding a row here, which is the point: the
-# registration is a decision someone made, not a coincidence of naming.
+# Price-denominated indicator leaves, registered per tool and matched by path
+# prefix (spec §5). An unregistered leaf is still evidence but cannot ground a
+# price: inferring price-ness from leaf names admitted ``sma_cross`` as a price.
_REGISTERED_PRICE_INDICATORS: dict[str, tuple[str, ...]] = {
"technical_indicators": (
"latest_close",
@@ -364,11 +296,8 @@ def _is_registered_price_indicator(tool: str, path: str) -> bool:
return True
if not leaf.startswith(prefix):
continue
- # A registration ending in "_" names a parametrised family
- # (``indicators.sma_20``), so what follows must be the parameter.
- # Without that, ``indicators.sma_cross`` — a boolean — matched
- # ``indicators.sma_`` and became a price, which is the exact defect
- # the name-reading rule kept producing.
+ # A prefix ending in "_" names a parametrised family (``sma_20``): only a
+ # numeric parameter may follow, so ``sma_cross`` is not a price.
rest = leaf[len(prefix):]
if not prefix.endswith("_"):
return True
@@ -384,11 +313,8 @@ def _metric_kind_for_path(path: str) -> str | None:
kind = _ANALYSIS_KIND_ALIASES.get(leaf)
if kind is not None:
return kind
- # Compound leaves name the kind as a token ("reported_annualized_return",
- # "strategy_max_drawdown"). #1338 review: matching only the verbatim alias
- # table makes every other spelling silently ungroundable. Scan from the
- # right — English compounds put the head noun last, so "return_vol"
- # resolves to vol, never to return.
+ # Compound leaves ("strategy_max_drawdown"): scan tokens from the right,
+ # where English puts the head noun, so "return_vol" is vol, not return.
tokens = [token for token in re.split(r"[_.]", leaf) if token]
for size in (2, 1):
for start in range(len(tokens) - size, -1, -1):
@@ -425,12 +351,11 @@ class _EvidenceMixin:
payload: dict[str, Any] | None,
call_id: str,
) -> None:
- """Record metric numbers a completed analysis result actually produced.
+ """Record metric figures a completed analysis result actually produced.
- Success of the call envelope is not enough: ``backtest`` reports ok for
- any runner exit, and a deduplicated ("skipped") call carries no new
- result at all (#1336). Only results that yielded at least one
- recognisable metric figure count as completed analysis.
+ An ok envelope is not enough: ``backtest`` reports ok for any runner exit
+ and a skipped call carries no result (#1336). Only a result yielding at
+ least one recognisable metric counts as completed analysis.
"""
if payload is None or payload.get("skipped"):
return
@@ -602,14 +527,6 @@ class _EvidenceMixin:
recorded += 1
return recorded
- def _observed_price_values(self) -> list[float]:
- """Every observed price value the run holds, for redaction protection."""
- return [
- float(record.value)
- for record in self._comparable_price_records()
- if record.value is not None
- ]
-
def _record_tool_failure(self, tool_name: str, call_id: str, result: str) -> None:
"""Store structured unavailable evidence for failed business envelopes."""
payload = _json_object(result) or {}
@@ -764,19 +681,12 @@ class _EvidenceMixin:
visit(payload, "")
def _ingest_run_dir_ohlc_csvs(self) -> None:
- """Register OHLC rows from CSVs the run wrote via the bash workaround.
-
- The bash+yfinance escape hatch writes per-symbol OHLC CSVs into the run
- directory (e.g. ``data/raw/BYN_V.csv``) instead of returning them through
- ``get_market_data``. Those prices were genuinely observed tool output,
- but they never entered the ledger, so the final-answer gate rejected
- every one of them as ``numeric_claim_unavailable``. Scan the run dir for
- such CSVs and register their open/high/low/close/price rows as observed
- evidence, keyed to the symbol derived from the filename.
-
- Only files whose filename maps to a symbol already tracked in this run
- are accepted, so a stray CSV cannot mint new identity. Rows are bounded
- by ``_MAX_GENERIC_EVIDENCE`` and each file is ingested at most once.
+ """Register OHLC rows from per-symbol CSVs the run wrote via bash+yfinance.
+
+ Those prices were observed but bypassed ``get_market_data``. Only a file
+ whose name maps to a symbol already tracked in this run is accepted, so a
+ stray CSV cannot mint identity; rows are bounded by
+ ``_MAX_GENERIC_EVIDENCE`` and each file is ingested once.
"""
if not self.run_dir.is_dir():
return
@@ -854,11 +764,8 @@ class _EvidenceMixin:
def _comparable_price_records(self) -> list[EvidenceRecord]:
"""Return every observed quote a numeric claim may be checked against.
- ``_price_records`` only sees fields already named ``open``/``close``/…,
- which in practice means ``get_market_data``. Quotes returned by the
- other market-sensitive tools are re-keyed onto the same canonical field
- so the contradiction check compares like with like instead of reporting
- the claim as unevidenced.
+ Quotes from non-OHLC tools are re-keyed onto canonical price fields and
+ registered indicator leaves onto ``indicator``.
Returns:
Observed price evidence with canonical ``field`` values.
diff --git a/agent/src/agent/grounding/figures.py b/agent/src/agent/grounding/figures.py
index 85c5e4232..e0d35b987 100644
--- a/agent/src/agent/grounding/figures.py
+++ b/agent/src/agent/grounding/figures.py
@@ -1,21 +1,10 @@
"""The figures block, the shape of a number, and how the two are matched.
-This module is the whole "inference" surface of the gate, and it is
-deliberately tiny. It answers three questions and no others:
-
-* where is the model's ``figures`` block, and what did it declare;
-* what SHAPE is each run of digits in the prose — a date, a symbol, a list
- marker, a measurement, or a bare integer;
-* which declaration, if any, covers a given prose number.
-
-Nothing here reads a natural-language word. The predecessor of this module
-decided a number's ROLE from a catalogue of price words, target/stop words,
-ATH spellings, indicator names, order-book phrases and observation binders;
-every one of those catalogues was only as complete as the day it was typed,
-so the gate's verdict differed between two translations of one sentence and a
-correct draft was rejected for a phrasing the list had not seen. The role is
-now declared by the model and verified against evidence; shape is all that is
-left to infer, and shape is language-independent.
+This is the gate's whole inference surface: it finds the model's ``figures``
+declarations, classifies every prose number by SHAPE (date, symbol, list
+marker, measurement, bare integer) and matches prose numbers to declarations.
+It reads no natural-language word; roles are declared by the model and shape
+is language-independent.
"""
from __future__ import annotations
@@ -32,25 +21,15 @@ ROLES = ("observed", "derived", "proposed", "cited", "count")
#: The info string that marks the declaration block.
BLOCK_LANGUAGE = "figures"
-
-# SHAPE 1 — a number. Grouped thousands are one token, and the lookbehind
-# keeps an identifier's digits ("SMA20", "MA5") from being read as a value.
-#
-# The lookahead deliberately fences only DIGITS, not letters. Fencing letters
-# too truncated a figure glued to its unit: "3.6pp" failed the fence at "p",
-# backtracked, and matched the bare "3" — so the same statement was a decimal
-# in Chinese ("3.6 个百分点") and a bare integer in English, and the two
-# languages got different verdicts from a difference in spacing conventions.
+# SHAPE 1 — a number. Grouped thousands are one token and the lookbehind keeps
+# an identifier's digits ("SMA20") out. The lookahead fences only digits, so
+# "3.6pp" reads as 3.6 rather than backtracking to a bare "3".
_NUMBER_RE = re.compile(
r"(?<![A-Za-z0-9_])[-+]?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?(?!\d)"
)
-
-# SHAPE 2 — a calendar date or a bare year. Both are structural exemptions
-# (spec §3): a date's digits are never a measurement. Only the spellings that
-# could otherwise be read as a measurement need to be here — a year-less
-# "8/5" or "08-10" is a pair of bare integers, which this gate does not check
-# at all, so no mask is needed for them.
+# SHAPE 2 — a calendar date or a bare year: structure, never a measurement
+# (spec §3). A year-less "08-10" is two bare integers and needs no mask.
_DATE_RE = re.compile(
r"(?:19|20)\d{2}\s*[-/年]\s*\d{1,2}\s*[-/月]\s*\d{1,2}\s*[日号]?"
r"|\d{1,2}\s*月\s*\d{1,2}\s*[日号]"
@@ -58,25 +37,17 @@ _DATE_RE = re.compile(
r"|(?:19|20)\d{2}"
)
-
-# SHAPE 3 — a line-leading ordinal: an ordered-list marker or a numbered
-# heading. The punctuation is required, so a line that opens with a real
-# figure ("1.171 元是收盘价") is untouched.
+# SHAPE 3 — a line-leading list marker or numbered heading. The punctuation is
+# required, so a line opening with a figure ("1.171 元是收盘价") is untouched.
_ORDINAL_RE = re.compile(r"(?m)^[^\S\n]*(?:#{1,6}[^\S\n]*)?\d{1,3}[.)、.][^\S\n]+")
-
-# SHAPE 4 — a fenced block. Its contents are code or the figures block, and
-# neither is prose.
+# SHAPE 4 — a fenced block: code or the figures block, never prose.
_FENCE_RE = re.compile(r"(?m)^[^\S\n]*(?:`{3,}|~{3,})[^\n]*$")
-
-# A currency marker is a SYMBOL SET, not a vocabulary: the question is only
-# whether a character that denotes money touches the number, which is what
-# makes a bare integer ("$100", "820 CNY") measurement-shaped. Membership is
-# per character for the symbols and per token for the ISO codes.
+# Currency is a symbol set, not a vocabulary: a money character or ISO code
+# touching a bare integer ("$100", "820 CNY") makes it measurement-shaped.
_CURRENCY_CHARS = frozenset("$¥¥€£₩₹元币圆镑")
-
_CURRENCY_CODES = frozenset(
{
"USD", "CNY", "CNH", "RMB", "HKD", "JPY", "EUR", "GBP", "KRW", "INR",
@@ -84,13 +55,10 @@ _CURRENCY_CODES = frozenset(
}
)
-
_PERCENT_CHARS = "%%"
-
-# A CJK currency word is at most three characters (人民币 is the longest).
-# Bounding the run is what keeps 元宵/元件 from reading as money: those sit
-# inside a longer uninterrupted CJK run.
+# A CJK currency word is at most three characters (人民币); bounding the run
+# keeps 元宵/元件, inside longer CJK runs, from reading as money.
_MAX_CURRENCY_WORD = 3
@@ -120,10 +88,8 @@ class FiguresBlock:
def match(self, value: float, percent: bool) -> Declaration | None:
"""Return the declaration covering ``value``, or None.
- Matching is by NUMERIC value at the precision the figure was written
- with (tolerance 1e-9), and percent-ness must agree: ``37%`` and
- ``0.37`` are different assertions and never cover each other, while
- ``37%`` and ``37 %`` are the same one.
+ Matching is numeric (tolerance 1e-9) and percent-ness must agree:
+ ``37%`` and ``0.37`` are different assertions.
Args:
value: The prose figure's numeric value.
@@ -166,11 +132,8 @@ class TableRow:
date_column: int | None
symbol_column: int | None
-
-# Header spellings that bind a table column to an OHLC field or to a date.
-# These are the TABLE's own schema — the column header declares what its
-# cells are, exactly as a tool result's field name declares what its leaf is
-# — so they are a header map, not prose inference (spec §4).
+# Header spellings binding a table column to an OHLC field: the table's own
+# schema, like a tool field name, not prose inference (spec §4).
_TABLE_FIELD_ALIASES = {
"open": "open",
"opening": "open",
@@ -192,21 +155,13 @@ _TABLE_FIELD_ALIASES = {
"收盘价": "close",
}
-
_DATE_HEADERS = {"date", "datetime", "trade date", "timestamp", "日期", "交易日", "时间"}
-
_SYMBOL_HEADERS = {"symbol", "ticker", "code", "标的", "代码", "证券代码"}
def _lines_with_offsets(content: str) -> list[tuple[str, int]]:
- """Return each line of ``content`` with its character offset in it.
-
- ``str.splitlines`` discards the terminators, so an issue raised on a line
- could not say where in the document that line sits. Offsets are recovered
- by scanning forward, which is exact because only line terminators separate
- one line's end from the next line's start.
- """
+ """Return each line of ``content`` with its character offset in it."""
positions: list[tuple[str, int]] = []
cursor = 0
for line in content.splitlines():
@@ -258,11 +213,9 @@ def _parse_value(text: str) -> tuple[float, bool] | None:
def parse_figures_block(content: str) -> FiguresBlock:
"""Parse the model's ``figures`` block out of a draft.
- Parsing is lenient by contract (spec §2): a full-width pipe, run-on
- spacing and a missing ``ref`` are all accepted. What is NOT accepted is
- silence — a line that cannot be read as ``value | role | note | ref`` is
- reported as malformed, because a declaration the gate skipped is a figure
- the gate never checked.
+ Parsing is lenient (full-width pipe, run-on spacing, missing ``ref``), but a
+ line that cannot be read as ``value | role | note | ref`` is reported as
+ malformed: a skipped declaration is a figure the gate never checked.
Args:
content: The candidate answer.
@@ -349,10 +302,8 @@ def _is_separator_row(cells: Sequence[tuple[str, int, int]]) -> bool:
def table_rows(content: str) -> list[TableRow]:
"""Return every Markdown table row with its header's column roles.
- A table block is a maximal run of lines carrying at least two pipes. The
- first line is the header; its cells bind columns to OHLC fields, to the
- trade date and to the symbol, which is the only per-column semantics this
- gate has (spec §4).
+ A table is a maximal run of lines with at least two pipes; its first line is
+ the header, whose cells bind columns to OHLC fields, trade date and symbol.
"""
positions = _lines_with_offsets(content)
rows: list[TableRow] = []
@@ -398,9 +349,8 @@ def _currency_before(text: str, start: int) -> bool:
def _currency_after(text: str, end: int) -> bool:
"""Whether a currency symbol or ISO code touches the number on its right.
- The CJK branch takes the maximal run of CJK characters and accepts it only
- when it is short enough to BE a currency word: "美元" qualifies, the
- six-character run of "元宵节后关注" does not.
+ A CJK run counts only when short enough to be a currency word: "美元" does,
+ "元宵节后关注" does not.
"""
tail = text[end:].lstrip()
if not tail:
@@ -425,11 +375,7 @@ def _currency_after(text: str, end: int) -> bool:
def currency_prefix_start(text: str, start: int) -> int:
- """Where a currency symbol attached to the LEFT of a figure begins.
-
- Redacting "$1.10" has to take the "$" with it, or the released sentence
- reads "$(omitted)".
- """
+ """Where a currency symbol attached to the left of a figure ("$1.10") begins."""
head = text[:start]
stripped = head.rstrip()
if stripped and stripped[-1] in _CURRENCY_CHARS and not _is_cjk(stripped[-1]):
@@ -438,11 +384,10 @@ def currency_prefix_start(text: str, start: int) -> int:
def currency_suffix_end(text: str, end: int) -> int:
- """Where a currency unit attached to the RIGHT of a figure ends.
+ """Where a currency unit attached to the right of a figure ("0.95 元") ends.
- Redacting "0.95 元" has to take the 元 with it. It must NOT take the first
- half of a compound unit: 元/股 and USD/share are one unit, and swallowing
- only its numerator left a denominator with nothing above it.
+ A compound unit (元/股, USD/share) is left whole, or its denominator would be
+ left with nothing above it.
"""
tail = text[end:]
lead = len(tail) - len(tail.lstrip(" \t"))
@@ -477,11 +422,9 @@ def _is_cjk(char: str) -> bool:
return "㐀" <= char <= "鿿"
-# Punctuation that ends one statement and starts the next. This is the ONLY
-# segmentation the gate has, and it is made of characters: it decides which
-# instrument a figure is about (spec §4), never what the figure means. The
-# ASCII period counts only when whitespace follows it, which is what keeps a
-# decimal, a ticker suffix and an abbreviation inside one segment.
+# Statement-ending punctuation, the gate's only segmentation: it decides which
+# instrument a figure is about (spec §4), never what it means. "." counts only
+# before whitespace, so decimals and ticker suffixes stay in one segment.
_SEGMENT_BREAKS = frozenset(",,;;。、\n!!??")
@@ -521,20 +464,13 @@ def _within(span: tuple[int, int], spans: Sequence[tuple[int, int]]) -> bool:
def scan_figures(content: str, block: FiguresBlock) -> list[Figure]:
- """Locate and classify every number in the prose of a draft.
-
- Three classes, and only three (spec §3):
+ """Locate and classify every number in the prose of a draft (spec §3).
- * ``exempt`` — a date, a year, digits inside a security code, a
- line-leading ordinal, a table's own date/symbol column, or anything
- inside a fenced block. Structure, not measurement.
- * ``measured`` — carries a decimal point, a percent sign, a touching
- currency mark, or sits in a table cell. This is the shape a fabricated
- price, level or metric is written in, and it must be declared.
- * ``bare`` — a plain integer with none of those marks. Counts, horizons,
- window lengths, lot sizes and line numbers all live here and are not
- checked, which is what retires the mask catalogue that used to try to
- name each of them.
+ * ``exempt`` — a date, year, security-code digits, line-leading ordinal, a
+ table's date/symbol column, or anything fenced: structure.
+ * ``measured`` — a decimal point, percent sign, touching currency mark or
+ table cell: the shape a fabricated price or metric takes; must be declared.
+ * ``bare`` — a plain integer (counts, horizons, window lengths): unchecked.
Args:
content: The candidate answer.
@@ -547,8 +483,7 @@ def scan_figures(content: str, block: FiguresBlock) -> list[Figure]:
line_of: list[tuple[int, int, int]] = [
(start, start + len(line), index) for index, (line, start) in enumerate(positions)
]
- # Every fenced block is exempt, the ``figures`` block among them: its span
- # comes from the same scan, so it needs no entry of its own.
+ # Every fenced block is exempt, the figures block included.
exempt: list[tuple[int, int]] = [
(start, end) for start, end, _, _ in _fenced_blocks(content)
]
diff --git a/agent/src/agent/grounding/policies.py b/agent/src/agent/grounding/policies.py
index 43d720a7b..e596e8335 100644
--- a/agent/src/agent/grounding/policies.py
+++ b/agent/src/agent/grounding/policies.py
@@ -1,13 +1,8 @@
"""Per-role validation: what each declared figure has to survive.
-The model declares what every measurement-shaped number in its answer IS
-(spec §2); this module decides whether the evidence backs that declaration
-(spec §4). It reads no prose word. Its predecessor did — twenty-two masks and
-a dozen phrase catalogues — and the catalogues could never close: the same
-sentence passed in one language and failed in the other, a level word the list
-had not seen cost a revision round, and every new phrasing needed a new entry.
-Roles now come from the model, evidence comes from the ledger, and shape comes
-from :mod:`figures`.
+The model declares what each measurement-shaped number IS (spec §2); this
+module checks that declaration against ledger evidence (spec §4). It reads no
+prose word: roles come from the model, shape from :mod:`figures`.
"""
from __future__ import annotations
@@ -48,11 +43,8 @@ _PRIVATE_ASSERTION_RE = re.compile(
re.IGNORECASE,
)
-
-# A loader's id is ASCII, but the answer follows the user's language, so a
-# Chinese report names the same provider in Chinese. Demanding the ASCII id
-# verbatim rejected correct prose: "数据来源:腾讯财经" was reported as
-# ``data_source_not_surfaced`` against evidence sourced from ``tencent``.
+# Loader ids are ASCII but the answer follows the user's language, so a source
+# is surfaced by any alias ("数据来源:腾讯财经" for ``tencent``).
_SOURCE_ALIASES = {
"akshare": ("akshare", "ak share"),
"baostock": ("baostock",),
@@ -71,12 +63,10 @@ _SOURCE_ALIASES = {
"yfinance": ("yfinance", "yahoo", "雅虎"),
}
-
_CURRENCY_ALIASES = {
"USD": ("usd", "us$", "美元", "美金"),
- # ¥ is how a model actually writes a CNY quote. It is the yen sign too, but
- # ``_infer_currency`` maps no venue to JPY, so nothing in this system can
- # mean yen by it; adding a JPY venue means revisiting this entry.
+ # ¥ is also the yen sign, but ``_infer_currency`` maps no venue to JPY;
+ # adding a JPY venue means revisiting this entry.
"CNY": ("cny", "cnh", "rmb", "人民币", "¥", "¥"),
"HKD": ("hkd", "hk$", "港元", "港币"),
"KRW": ("krw", "韩元", "韩圜"),
@@ -84,14 +74,10 @@ _CURRENCY_ALIASES = {
"CAD": ("cad", "c$", "加元", "加拿大元"),
}
-
-# "元" is how a Chinese answer writes a CNY quote, but it is also the tail of
-# 港元/美元/日元, so accepting it unguarded would let an answer about a Hong
-# Kong listing satisfy a CNY requirement. It counts only when no other
-# currency's character owns it.
+# "元" counts as CNY only when no other currency's character precedes it
+# (港元/美元/日元), or a Hong Kong listing would satisfy a CNY requirement.
_OTHER_CURRENCY_PREFIXES = "港美日欧韩台新加澳"
-
#: Relative band a value must fall in to count as matching evidence.
_TOLERANCE = 0.005
@@ -100,9 +86,8 @@ _TOLERANCE = 0.005
class ValidationResult:
"""Final-answer grounding decision.
- ``released_text`` is the draft with its declaration block removed: the
- block is a contract between the model and this gate, not part of the
- answer, and it never reaches the user.
+ ``released_text`` is the draft without its declaration block, which is a
+ contract with the gate and never reaches the user.
"""
valid: bool
@@ -123,10 +108,6 @@ def _close_any(value: float, targets: Iterable[float]) -> bool:
def _nearest(value: float, targets: Iterable[float], limit: int = 3) -> list[float]:
"""The observed values closest to a rejected figure.
- A range ("0.567-1.053") tells the model the figure is outside the window;
- the nearest prints tell it what to write instead, which is what spec 6 asks
- the correction prompt to say.
-
Args:
value: The rejected figure's value.
targets: Every value the relevant evidence pool holds.
@@ -140,11 +121,7 @@ def _nearest(value: float, targets: Iterable[float], limit: int = 3) -> list[flo
def _written_half_unit(text: str) -> float:
- """Half a unit of the last digit a figure was WRITTEN with.
-
- "约 37%" for a derived 36.75% asserts that the value rounds to 37, and a
- flat relative band rejects every integer-percent rounding a model makes.
- """
+ """Half a unit of the last digit a figure was written with ("37%" -> 0.5)."""
body = text.strip().rstrip("%%").strip()
decimals = len(body.split(".", 1)[1]) if "." in body else 0
return 0.5 * 10.0 ** (-decimals)
@@ -218,11 +195,8 @@ def _evaluate_formula(expression: str) -> tuple[float, list[float]] | None:
def _formula_in_note(note: str) -> tuple[float, list[float]] | None:
"""Find the derivation a note states.
- A note is written either as the expression alone ("0.666 × 0.97") or as
- the expression together with its own result ("0.666 × 0.97 = 0.646"). The
- whole note is tried first, then each segment between result separators.
- Those separators are punctuation, not vocabulary, which is why the English
- and Chinese spellings of the same derivation now get the same verdict.
+ The whole note is tried first, then each segment between result separators
+ ("0.666 × 0.97 = 0.646"); separators are punctuation, not vocabulary.
Args:
note: The declaration's free-text note.
@@ -245,24 +219,14 @@ def _formula_in_note(note: str) -> tuple[float, list[float]] | None:
class _PolicyMixin:
"""Policy behaviour of :class:`GroundingLedger`."""
- # ------------------------------------------------------------------ #
- # identity
- # ------------------------------------------------------------------ #
-
def _validate_identity(self, content: str) -> list[dict[str, Any]]:
"""Validate aggregate state and listed/private contradictions."""
issues: list[dict[str, Any]] = []
status = self.identity_status
- # Two conditions, both load-bearing.
- #
- # ``self._identities`` — a run that never named an instrument has no
- # identity to get wrong. The trigger phrase is matched against the user
- # message, so "什么是市盈率估值法?" set identity_required and then failed
- # every draft it could ever produce, including the honest answer.
- #
- # ``ambiguous`` is deliberately absent. A shortlist is an answer, and
- # consumers stay blocked on it in ``authorize_tool_call``, so such a
- # run still cannot fetch a quote to misattribute.
+ # Only a run that named an instrument can get its identity wrong: the
+ # trigger phrase matches the user message, so "什么是市盈率估值法?" would
+ # otherwise fail every draft. ``ambiguous`` is absent on purpose: a
+ # shortlist is an answer and consumers stay blocked in ``authorize_tool_call``.
if (
self._identity_required
and self._identities
@@ -308,10 +272,6 @@ class _PolicyMixin:
)
return issues
- # ------------------------------------------------------------------ #
- # figures
- # ------------------------------------------------------------------ #
-
def _validate_figures(
self,
content: str,
@@ -413,12 +373,7 @@ class _PolicyMixin:
message: str,
**extra: Any,
) -> dict[str, Any]:
- """Build one figure-scoped issue.
-
- Every figure issue carries the same five fields — value, role, span,
- symbol and reason — so the correction prompt can name the exact number
- and the release path can cut exactly it.
- """
+ """Build one figure-scoped issue with value, role, span, symbol and reason."""
issue = {
"code": code,
"value": figure.text,
@@ -441,11 +396,12 @@ class _PolicyMixin:
document_symbol: str | None,
records: Sequence[EvidenceRecord],
) -> str | None:
- """Resolve which instrument a figure is about (spec §4 order).
+ """Resolve which instrument a figure is about (spec §4).
- The declaration's own ``ref``/``note`` wins, then the table row's
- symbol column, then the one canonical evidence symbol on the figure's
- line, then the one canonical evidence symbol in the whole answer.
+ Order: the declaration's ``ref``/``note``, the table row's symbol column,
+ the figure's punctuation segment, its line, then the whole answer. The
+ segment precedes the line because a comparison report names both
+ instruments on one header line and then writes about one of them.
"""
if declaration is not None:
declared = self._symbol_for_claim(
@@ -457,10 +413,6 @@ class _PolicyMixin:
normalized = _normalize_symbol(figure.symbol)
if normalized:
return normalized
- # Inside the figure's own segment first. A comparison report names both
- # instruments in its header and then writes about one of them, so the
- # LINE is too coarse an owner: 562500's moving average grounded a level
- # written under 600519 on the same line.
left, right = segment_bounds(content, figure.start, figure.end)
segment_symbol = self._symbol_for_claim(content[left:right], records)
if segment_symbol:
@@ -469,17 +421,11 @@ class _PolicyMixin:
return line_symbols[figure.line]
return document_symbol
- # ------------------------------------------------------------------ #
- # evidence pools
- # ------------------------------------------------------------------ #
-
def _referenced_values(self, ref: str) -> list[float] | None:
"""Every observed value one tool call produced, or None when unknown.
- A declaration whose ``ref`` names a call id says "this number came out
- of THAT call". That is the tightest scoping available and the only one
- that can ground a figure the price pool cannot hold — a filing's
- revenue, a factor's IC, a volume.
+ A ``ref`` naming a call id is the tightest scoping, and the only one that
+ can ground a non-price figure (revenue, IC, volume).
"""
key = (ref or "").strip()
if not key:
@@ -508,19 +454,15 @@ class _PolicyMixin:
) -> list[float]:
"""Observed price values a figure may be compared against.
- Filtered by symbol when one was resolved; further narrowed to the OHLC
- field and trade date when the figure sits under those table headers,
- which is the table semantics §4 preserves.
+ Filtered by symbol, then by OHLC field and trade date when the figure sits
+ under those table headers (spec §4).
"""
candidates = list(records)
if symbol:
candidates = [record for record in candidates if record.symbol == symbol]
elif len({record.symbol for record in records if record.symbol}) > 1:
- # An indicator reading is symbol-bound in a way an OHLC bar's union
- # is not. With evidence for two instruments and a figure attributed
- # to neither, 562500's sma_20 grounded a level written beside
- # 600519.SH; the union was argued for observed quotes, not for a
- # level attached to one symbol.
+ # Two instruments and no resolved symbol: an indicator reading is
+ # symbol-bound, so it cannot ground a figure attributed to neither.
candidates = [record for record in candidates if record.field != "indicator"]
if column:
candidates = [record for record in candidates if record.field == column]
@@ -534,12 +476,10 @@ class _PolicyMixin:
return [float(record.value) for record in candidates if record.value is not None]
def _row_pool(self, symbol: str | None) -> list[float]:
- """Non-price numbers a market-data ROW carried (volume, turnover, …).
+ """Non-price numbers a market-data row carried (volume, turnover, …).
- A row is one observation, and a report quoting its volume beside its
- close is quoting the same tool result. Only ``get_market_data`` rows
- and the run-dir CSVs the bash escape hatch writes are included, so a
- generic tool's hundreds of numeric leaves never widen the price check.
+ Only ``get_market_data`` and run-dir CSV rows count, so a generic tool's
+ numeric leaves never widen the check.
"""
return [
float(record.value)
@@ -551,12 +491,7 @@ class _PolicyMixin:
]
def _metric_pool(self, symbol: str | None) -> list[float]:
- """Analysis/risk metric values the run actually recorded.
-
- Two sources, both keyed on TOOL FIELD NAMES: metrics parsed from a
- completed analysis result, and observed leaves whose path maps to a
- metric kind (``annualized_vol``, ``max_drawdown``, …).
- """
+ """Metric values from completed analysis results and metric-named leaves."""
values = [
float(entry["value"])
for entry in self._analysis_metrics
@@ -580,12 +515,8 @@ class _PolicyMixin:
) -> bool:
"""Whether a figure equals evidence, at its own scale or a metric's.
- ``direct`` is compared literally; the caller decides what may go in it,
- and for a percent-written figure that is nothing at all — an OHLC close
- is never a ratio. ``scaled`` absorbs the two conventions tools and
- answers disagree on: fraction vs percent (0.182 vs 18.2%), and the sign
- a fall is written with (a drawdown is recorded as -0.094 and quoted as
- 9.4%).
+ ``direct`` is compared literally. ``scaled`` absorbs fraction vs percent
+ (0.182 vs 18.2%) and the sign of a fall (drawdown -0.094 quoted as 9.4%).
"""
if _close_any(figure.value, direct):
return True
@@ -593,10 +524,6 @@ class _PolicyMixin:
magnitudes = [abs(target) for target in scaled]
return any(_close_any(candidate, magnitudes) for candidate in candidates)
- # ------------------------------------------------------------------ #
- # roles
- # ------------------------------------------------------------------ #
-
def _check_observed(
self,
figure: Figure,
@@ -628,8 +555,7 @@ class _PolicyMixin:
symbol, records, column=figure.column, date=figure.date
)
if figure.percent:
- # A percent-written figure is a ratio, and a price or a volume is
- # not, so no amount of price evidence may answer one.
+ # A percent is a ratio; no price or volume may answer it.
direct: list[float] = []
elif figure.column:
direct = list(prices)
@@ -690,10 +616,8 @@ class _PolicyMixin:
return "formula_not_evaluable"
result, operands = evaluated
if not symbol and len({record.symbol for record in records if record.symbol}) > 1:
- # A comparison run holds two instruments' bars, and the expensive
- # one's close makes any arithmetic "anchored" no matter which
- # instrument the answer is about. Without a resolved symbol there
- # is nothing to anchor TO.
+ # Two instruments' bars and no resolved symbol: any arithmetic would
+ # look anchored, with nothing to anchor it to.
return "no_symbol"
anchors = (
self._price_pool(symbol, records)
@@ -713,20 +637,11 @@ class _PolicyMixin:
def _result_matches(declaration: Declaration, result: float) -> bool:
"""Whether a formula's result is the value the declaration states.
- The band is half a unit of the last digit the value was WRITTEN with,
- because "约 37%" for a derived 36.75% asserts that it rounds to 37 and
- a flat relative band rejects every rounding a model makes.
-
- A figure carrying "%" is percentage points and is compared ONLY
- against the derivation in those units. Running it against the fraction
- too gave an integer percent a half-unit band of 0.5 in FRACTION units
- — fifty percentage points — and "区间收益率约 0%" validated against a
- real +58% move. A figure written without "%" is genuinely ambiguous
- and is tried both ways.
-
- Magnitudes are compared because the note for a fall is written both as
- ``(low − high) / high`` and as the drop it produces; the note itself is
- what states which subtraction was taken.
+ The band is half a unit of the last written digit ("约 37%" for 36.75%
+ asserts rounding). A "%" figure is compared only in percentage points,
+ since against the fraction a half-unit band spans fifty points; a bare
+ figure is tried both ways. Magnitudes are compared because a fall is
+ noted either as ``(low − high) / high`` or as the drop.
"""
half_unit = _written_half_unit(declaration.value_text)
targets = (
@@ -764,10 +679,7 @@ class _PolicyMixin:
result, _ = derivation
if declaration is not None and self._result_matches(declaration, result):
return []
- # Reported in the figure's OWN units. ``_result_matches`` compares a
- # percent-written figure against ``result * 100``, so telling a model
- # that wrote "12%" that its formula "evaluates to -0.3675" names a
- # number that appears nowhere in the comparison it just failed.
+ # Reported in the figure's own units, as ``_result_matches`` compares it.
scaled = result * 100.0 if figure.percent else result
shown = f"{scaled:.6g}%" if figure.percent else f"{scaled:.6g}"
return [
@@ -789,14 +701,10 @@ class _PolicyMixin:
symbol: str | None,
records: Sequence[EvidenceRecord],
) -> list[dict[str, Any]]:
- """A proposed level is derived, or inside the observed range.
-
- An entry, a target or a stop is a number the answer proposes rather
- than one it observed, so it cannot be required to equal a print. It
- can be required to be anchored: either the note derives it from what
- the run observed, or it lies between the lowest and highest price this
- session actually saw for the instrument. A level far outside that
- window is the invention this gate exists to stop.
+ """A proposed level (entry, target, stop) is derived or inside the observed range.
+
+ It cannot be required to equal a print, only to be anchored; a level far
+ outside what the session saw is the invention this gate exists to stop.
"""
derivation = self._derivation(declaration, symbol, records)
if (
@@ -844,10 +752,8 @@ class _PolicyMixin:
) -> list[dict[str, Any]]:
"""A cited figure names its source and does not pose as a print.
- The value is not checked — the run could never have observed a paper's
- Sharpe — so the only thing to enforce is that the citation is not used
- to launder an observation: the same number may not also be declared
- observed, and it may not sit in a table's OHLC column.
+ Its value is unchecked, so the citation may not launder an observation:
+ the value may not also be declared observed or sit in an OHLC column.
"""
if declaration is not None and not declaration.note.strip():
return [
@@ -876,10 +782,6 @@ class _PolicyMixin:
]
return []
- # ------------------------------------------------------------------ #
- # symbols and provenance
- # ------------------------------------------------------------------ #
-
def _validate_unsourced_symbols(
self,
content: str,
@@ -888,16 +790,9 @@ class _PolicyMixin:
) -> list[dict[str, Any]]:
"""Reject figures attached to an instrument no tool in this run handled.
- This is the mechanically decidable half of "what the tools did not
- return, you do not supply" (#886/#887). Naming a symbol is left alone —
- prose may legitimately mention an index or a peer — but the moment a
- line pairs an unhandled canonical symbol with a figure, the figure has
- no possible origin other than model memory.
-
- A figure the model declared ``cited`` is exempt, because a citation is
- an origin. That replaces the phrase catalogue of attribution verbs the
- exemption used to be keyed on, which could not tell "the paper reports"
- from "the backtest reports" without listing every subject by hand.
+ Naming a symbol is fine, but a line pairing an unhandled canonical symbol
+ with a measured figure has no origin other than model memory (#886/#887).
+ A figure declared ``cited`` is exempt, since a citation is an origin.
"""
issues: list[dict[str, Any]] = []
reported: set[str] = set()
diff --git a/agent/src/agent/grounding/release.py b/agent/src/agent/grounding/release.py
index 887a7d567..9e06c3890 100644
--- a/agent/src/agent/grounding/release.py
+++ b/agent/src/agent/grounding/release.py
@@ -22,27 +22,15 @@ from src.agent.grounding.figures import (
)
from src.agent.grounding.policies import ValidationResult
-# Bounded read-only recovery (#1081): a missing instrument identity or price
-# evidence is often recoverable deterministically, so the loop should keep
-# driving the original task through `search_symbol` and `get_market_data`
-# instead of handing the user a terminal "confirm and continue" fallback.
-# These budgets are separate from the rejected-draft count so real recovery
-# progress is never cut off at the three-draft retry cap.
+# Bounded read-only recovery (#1081) through `search_symbol` / `get_market_data`,
+# budgeted separately from rejected drafts so real progress is never cut off.
MAX_GROUNDING_RECOVERY_ROUNDS = 6
-
-# Drafts the gate may reject on the correction path before the run stops
-# revising: the first is handed back with a correction prompt, the second is
-# released with its rejected figures cut (spec §0). Two, because a revision
-# costs a full model round on a report the user is already waiting for, and
-# the third and fourth rounds bought nothing measurable: the release
-# path now cuts the figures the gate objected to and ships the rest, so the
-# alternative to another round is a discounted answer, not a refusal.
+# Rejected drafts before the run stops revising: the first gets a correction
+# prompt, the second is released with its rejected figures cut (spec §0).
MAX_GROUNDING_REVISIONS = 2
-
-# Issue codes whose figure can be cut out of its clause and the draft released
-# (see ``redacted_release``), and the provenance codes a data note repairs.
+# Issue codes whose figure can be cut out and the draft released.
_REDACTABLE_CODES = frozenset(
{
"numeric_claim_conflict",
@@ -52,50 +40,33 @@ _REDACTABLE_CODES = frozenset(
}
)
-
-# The provenance codes a data note may fill in deterministically. The source
-# and the currency are metadata ABOUT a figure. ``canonical_symbol_not_surfaced``
-# is deliberately absent: the symbol is the figure's SUBJECT, and appending
-# "562500.SH: source yahoo" under a draft that calls the instrument 贵州茅台
-# footnotes a misattribution instead of repairing it — so the identity binding
-# keeps its model-correction round.
+# Provenance codes a data note repairs deterministically. The symbol is absent
+# on purpose: it is the figure's subject, and a footnote naming it under a draft
+# about another instrument would bless a misattribution.
_REPAIRABLE_PROVENANCE_CODES = frozenset(
{"data_source_not_surfaced", "currency_not_surfaced"}
)
-
_MAX_REDACTION_PASSES = 3
-
-# The in-text mark for an omitted figure. It replaces the number AND the unit
-# glued to it ("0.95 元" → "(略※)", "$1.10" → "(omitted※)") so the sentence
-# still reads as prose, and the ※ points at the one footnote that says how
-# many figures were omitted and why. A bracketed "[value removed]" left the
-# unit dangling and read like a redaction stamp.
+# The omission mark replaces the number and its glued unit so the sentence still
+# reads ("0.95 元" → "(略※)"); ※ points at the single footnote.
_REDACTION_MARKER_ZH = "(略※)"
-
_REDACTION_MARKER_EN = "(omitted※)"
-
MAX_SYMBOL_RESOLUTION_ATTEMPTS = 2
-
MAX_PRICE_EVIDENCE_ATTEMPTS = 3
def _format_price(value: float) -> str:
- """Render an observed price without scientific notation or lost digits.
-
- ``%g`` switches to scientific notation past six significant digits, so an
- index level printed in the release footnote read "1.23457e+06".
- """
+ """Render a price without scientific notation (``%g`` gives "1.23457e+06")."""
return format(value, ".10g")
-#: What the evidence says about a figure, keyed on the validator's reason. The
-#: reason is a state of the CHECK, never a word read out of the answer, so this
-#: table is language-independent the way the roles it reports on are.
+#: What the evidence says about a figure, keyed on the validator's reason: a
+#: state of the check, never a word read from the answer.
_CORRECTION_REASONS = {
"undeclared": "it is not declared at all",
"no_evidence": "this session holds no evidence of that kind to check it against",
@@ -150,11 +121,10 @@ def _correction_line(issue: dict[str, Any]) -> str:
def _digit_key(text: str) -> str:
- """The digits a figure was written with, ignoring how it was decorated.
+ """The digits a figure was written with, ignoring decoration.
- ``37%``, ``37 %`` and a bare ``37`` share one key; ``3`` and ``3.0`` do
- not, because they are not the same number as written and sweeping one for
- the other would cut an unrelated count.
+ ``37%``, ``37 %`` and ``37`` share a key; ``3`` and ``3.0`` do not, so a
+ sweep never cuts an unrelated count.
Args:
text: The figure exactly as it appears in the answer.
@@ -167,12 +137,10 @@ def _digit_key(text: str) -> str:
def _strip_release_markers(content: str) -> str:
- """Remove any redaction marker or release note the MODEL wrote.
+ """Remove redaction markers and ※ note lines the model wrote itself.
- The marker and the footnote are the gate's own statements about what it
- cut. A draft carrying "※ 略去 0 处……" of its own shipped both notes, one
- contradicting the other, and a "(略※)" pasted into the body read as a
- redaction that never happened.
+ Those are the gate's own statements about what it cut; a model-written copy
+ contradicts the real footnote or claims a redaction that never happened.
Args:
content: The rejected draft.
@@ -192,14 +160,11 @@ class _ReleaseMixin:
"""Release behaviour of :class:`GroundingLedger`."""
def correction_prompt(self, validation: ValidationResult) -> str:
- """Build bounded per-figure feedback for one rejected model draft.
+ """Build per-figure feedback for one rejected model draft (spec 6).
- The feedback is per NUMBER, not per rule (spec 6). Each rejected figure
- gets one line naming three things: the figure exactly as it was
- written, the role it was DECLARED under, and what the EVIDENCE says
- about it — the range that was observed, the values nearest to it, or
- the value its own note evaluates to. The three ways out are then stated
- once, because they are the same three for every figure.
+ Each rejected figure gets one line: the figure as written, the role it
+ was declared under, and what the evidence says. The three ways out are
+ stated once.
Args:
validation: The rejected draft's validation result.
@@ -279,11 +244,7 @@ class _ReleaseMixin:
return "\n".join(lines)
def _repeatedly_rejected(self, issues: Sequence[dict[str, Any]]) -> list[str]:
- """Figures this draft repeats that an earlier draft was already refused for.
-
- The model tends to restate a rejected figure in a new format rather
- than drop it; the gate refuses it again and the run burns its whole
- revision budget on one number.
+ """Figures in this draft that an earlier draft was already refused for.
Args:
issues: The current draft's figure issues.
@@ -301,17 +262,13 @@ class _ReleaseMixin:
return list(dict.fromkeys(repeated))
def recovery_action(self, validation: ValidationResult) -> str | None:
- """Decide the next safe read-only recovery step for a rejected draft.
-
- Returns ``search_symbol`` when instrument identity is unresolved and
- resolution attempts remain; ``get_market_data`` when identity is locked
- but a price claim has no observed evidence and fetch attempts remain;
- otherwise ``None`` (genuinely ambiguous, conflicting, or exhausted —
- the loop must then ask the user or fail closed).
+ """Decide the next safe read-only recovery step for a rejected draft (#1081).
- This is the deterministic half of #1081: recoverable missing evidence is
- often obtainable through read-only tools, so a rejected draft should
- drive the original task forward instead of stopping.
+ Returns:
+ ``search_symbol`` when identity is unresolved and resolution attempts
+ remain; ``get_market_data`` when identity is locked, a price claim
+ lacks evidence and fetch attempts remain; otherwise None, and the
+ loop must ask the user or fail closed.
"""
if self._recovery_rounds >= MAX_GROUNDING_RECOVERY_ROUNDS:
return None
@@ -373,10 +330,8 @@ class _ReleaseMixin:
f"The verified observed OHLC range is: {joined}. "
"I will not invent an entry price without a visible derivation or refreshed evidence."
)
- # No observed price evidence: distinguish "identity unresolved" from
- # "the draft cited prices this session never observed". Reporting the
- # identity message for the latter is misleading (the run may not even
- # have touched the market tools).
+ # No observed price: tell unresolved identity apart from a draft citing
+ # prices this session never observed.
issue_codes = {
code
for validation in self._validations
@@ -413,11 +368,8 @@ class _ReleaseMixin:
Args:
is_zh: Whether to join the facts with Chinese punctuation.
- content: The answer the summary is attached to, when there is one.
- The symbol is then printed the way that answer spells it — a
- footnote on an answer written throughout in ``562500.SS`` used
- to name ``562500.SH``, because the evidence record is
- canonicalised.
+ content: The answer the summary is attached to, if any; the symbol
+ is then printed the way that answer spells it.
Returns:
One fact per symbol, or None when the run observed no price.
@@ -498,27 +450,10 @@ class _ReleaseMixin:
) -> str | None:
"""Append a data note when the only defects are missing provenance words.
- ``data_source_not_surfaced`` and ``currency_not_surfaced`` mean the
- answer quoted a price without naming the source or the currency. Both
- are known to the ledger, so the omission is deterministic — and
- regenerating a multi-minute report to add the word "tencent" is a full
- model round for one word. Nothing here touches a figure: a draft
- carrying any other issue is returned as None so the numeric checks
- keep their round.
-
- ``canonical_symbol_not_surfaced`` is deliberately NOT repaired. That
- check's job is that a price claim surfaces the symbol it is about, and
- appending "562500.SH: price source yahoo" under a draft that reads
- "贵州茅台 最新收盘价 1.171 元" turns a misattribution into a released
- answer with a footnote naming a different instrument. It keeps its
- model round.
-
- The "unchecked price column" veto this used to carry is gone with the
- surface it guarded. It declined the repair whenever a table held a
- price column no validator read (``| 档位 | 挂单价 |``), because the
- note would attest to figures the gate never saw. Every cell of every
- table is now a measurement-shaped figure the gate checks, so no such
- column exists.
+ Source and currency are known to the ledger, so naming them should not
+ cost a model round. Any other issue returns None so the numeric checks
+ keep their round; see ``_REPAIRABLE_PROVENANCE_CODES`` for why a missing
+ symbol is not repaired.
Args:
content: The rejected draft.
@@ -539,38 +474,25 @@ class _ReleaseMixin:
def redacted_release(self, content: str, validation: ValidationResult) -> str | None:
"""Release the last rejected draft with its unverified figures cut out.
- Once the revision budget is spent, the draft is still the analysis the
- user waited through every revision for, and the gate objected to
- specific figures — not to the trend read, the indicator commentary, or
- the risk notes around them. Each rejected figure is replaced by a
- visible marker AT ITS OWN SPAN, the missing provenance words are
- appended if that is all that remains, and the cut document is
- re-validated by the same gate: only text that passes is returned.
-
- A document-wide sweep then removes any UNCHECKED restatement of a
- figure that was cut (see :meth:`_sweep_same_values`), so the footnote's
- count is the number of places the figure no longer appears, not the
- number of spans the validator happened to flag.
-
- Fail-closed by construction. None — leave the canned fallback in place
- — whenever the run never observed a price at all, an issue is not a
- cut-out-able figure (an identity finding is one), a flagged figure
- cannot be located, or the document still fails after the cut.
+ Each rejected figure becomes a marker at its own span, missing provenance
+ is appended, bare restatements of a cut figure are swept, and the result
+ and its footnote are re-validated by the same gate. Fail-closed: None when
+ no price was observed, an issue cannot be cut (an identity finding), a
+ flagged figure cannot be located, or the text still fails.
Args:
content: The rejected draft.
validation: Its validation result.
Returns:
- The redacted, re-validated answer with its declaration block
- stripped and a note stating how many figures were removed, or None.
+ The redacted, re-validated answer without its declaration block and
+ with a note stating how many figures were removed, or None.
"""
if not self._price_records():
return None
text = _strip_release_markers(content)
- # Stripping moves every offset after it, and the issue spans are the
- # only anchor the cuts have, so the verdict is retaken on the text the
- # cuts will actually be made in.
+ # Stripping shifts offsets and the cuts anchor on issue spans, so the
+ # verdict is retaken on the stripped text.
check = validation if text == content else self._validate(text, record=False)
removed = 0
keys: set[str] = set()
@@ -608,16 +530,13 @@ class _ReleaseMixin:
text, check, removed = swept, recheck, removed + len(swept_texts)
body = check.released_text
note = self._release_note(removed, body)
- # The note carries the observed range and the canonical symbols, so it
- # is answer text too, and it goes through the same gate — in undeclared
- # mode, since it has no block of its own. Shipping it unchecked would
- # contradict the fail-closed promise above.
+ # The note is answer text too (range, symbols), so it passes the same
+ # gate, in undeclared mode.
if not self._validate(note, record=False).valid:
return None
released = body.rstrip() + "\n\n" + note
- # Recorded beside the drafts but NOT as one: the artifact otherwise
- # held no evidence for the fail-closed promise above, because every
- # recheck on this path is deliberately unrecorded.
+ # Recorded beside the drafts, not as one: every recheck here is
+ # unrecorded, so this is the artifact's only evidence of the release.
self._released = {
"released_at": _utc_now(),
"content_sha256": hashlib.sha256(released.encode("utf-8")).hexdigest(),
@@ -629,11 +548,10 @@ class _ReleaseMixin:
@staticmethod
def _issue_span(text: str, issue: dict[str, Any]) -> tuple[int, int] | None:
- """Locate the flagged figure in ``text``.
+ """Locate the flagged figure in ``text`` by its recorded character span.
- The validators record the character span of the figure itself, which
- is the only reliable anchor: a stored claim string is normalised and
- a bare numeric cell ("1.10") matches inside a longer number ("21.10").
+ The span is the only reliable anchor: a bare cell "1.10" also matches
+ inside "21.10".
Args:
text: The document the issue was raised against.
@@ -660,19 +578,16 @@ class _ReleaseMixin:
) -> tuple[str | None, list[str]]:
"""Replace every flagged figure with the omission marker.
- An issue naming one figure cuts that figure. An issue with no value —
- ``unsourced_symbol_figures``, which says "every figure on this line
- belongs to an instrument no tool handled" — cuts every
- measurement-shaped figure inside its span.
+ An issue without a value (``unsourced_symbol_figures``) cuts every
+ measured figure inside its span.
Args:
text: The document to rewrite.
issues: The issues raised against it.
Returns:
- ``(rewritten text, figures replaced as written)``, or
- ``(None, [])`` when a flagged issue could not be located and the
- release must fail closed.
+ ``(rewritten text, figures replaced as written)``, or ``(None, [])``
+ when a flagged issue cannot be located and release must fail closed.
"""
block = parse_figures_block(text)
figures = scan_figures(text, block)
@@ -696,20 +611,11 @@ class _ReleaseMixin:
return self._apply_cuts(text, cuts)
def _sweep_same_values(self, text: str, keys: set[str]) -> tuple[str, list[str]]:
- """Cut every UNCHECKED restatement of a figure that was already cut.
-
- Cutting a figure at its own span leaves the same claim standing
- wherever the shape rules do not check it. A bare integer is the one
- such place: "回撤 37%" is a measurement and is verified, while the
- "37" of "回撤 37 个百分点" is a bare integer that spec 3 deliberately
- does not check, so the number the footnote says was removed would
- still be on the page.
+ """Cut every bare-integer restatement of a figure that was already cut.
- Only bare figures are swept. A measurement-shaped occurrence that
- survived the cuts is one this gate CHECKED and grounded, and removing
- it would delete a figure the evidence supports; an exempt occurrence
- is a date, a security code or fenced text, and cutting those corrupts
- the structure they belong to.
+ After "回撤 37%" is cut, "回撤 37 个百分点" still carries an unchecked bare
+ "37". Measured survivors were checked and grounded, and exempt ones are
+ structure (dates, codes, fenced text), so only bare figures are swept.
Args:
text: The already-cut document.
@@ -756,10 +662,8 @@ class _ReleaseMixin:
end = currency_suffix_end(text, end)
marker = self._marker_for(text, start)
if marker is _REDACTION_MARKER_ZH:
- # "建议买入价 0.95 元" → "建议买入价(略※)": a full-width
- # bracket sits flush against the preceding word. Not against a
- # table pipe, though — "| 第一档 |(略※) |" loses the column's
- # padding and reads as a broken row.
+ # "建议买入价 0.95 元" → "建议买入价(略※)": flush against the word,
+ # but not against a table pipe, which would break the row's padding.
while (
start > cursor
and text[start - 1] == " "
@@ -775,11 +679,7 @@ class _ReleaseMixin:
def _marker_for(self, text: str, position: int) -> str:
"""Pick the omission marker in the script of the line being cut.
- A Chinese user asking about a US name gets English tables, and running
- one marker over the whole document released
- "Suggested entry price(略※) per share." A stretch with neither script
- — a numeric table row — falls back to the user's language, which is
- what the footnote is written in.
+ A line with neither script (a numeric table row) uses the user's language.
"""
line = ""
for candidate, start in _lines_with_offsets(text):
@@ -797,13 +697,7 @@ class _ReleaseMixin:
)
def _release_note(self, removed: int, content: str | None = None) -> str:
- """Explain the redaction to the user, with the observed range.
-
- ``redacted_release`` returns None before this is reached when the run
- holds no price record, which is the only case in which the summary is
- None — so it is read directly rather than behind an ``or ""`` that
- described a state the caller cannot produce.
- """
+ """Explain the redaction to the user, with the observed range."""
is_zh = self._user_writes_chinese()
joined = self._observed_range_summary(is_zh, content)
if is_zh: