Skip to content

"Vibe-Trading: Your Personal Trading Agent"

refactor(grounding): declare the identity and figure gate checks in the registry

Yufeng He34ee8afbf4cf
diff --git a/agent/src/agent/grounding/figures_checks.py b/agent/src/agent/grounding/figures_checks.py
new file mode 100644
index 000000000..d80dde48c
--- /dev/null
+++ b/agent/src/agent/grounding/figures_checks.py
@@ -0,0 +1,96 @@
+"""Declared figure checks for the grounding gate (#1622).
+
+Second slice of the migration off the inline rule list in ``policies.py``:
+the malformed-declaration finding and the unsourced-symbol finding, moved
+byte-for-byte and declared with stable names. Both read the parsed figures
+state the ledger stashes for the duration of a validation walk, which is
+what the registry contract means by figure state living on the ledger.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src.agent.grounding.figures import FiguresBlock, _lines_with_offsets
+from src.agent.grounding.identity import _scan_symbols
+from src.agent.grounding.registry import grounding_check
+
+
+def _active_block(ledger: Any) -> FiguresBlock:
+ block = ledger._active_block
+ if block is None:
+ raise RuntimeError("figure checks only run inside a validation walk")
+ return block
+
+
+@grounding_check(
+ name="figures-block-malformed",
+ code="figures_block_malformed",
+ description="A figures block line could not be read as `value | role | note | ref`.",
+)
+def _figures_block_malformed(ledger: Any, content: str) -> list[dict[str, Any]]:
+ return [
+ {
+ "code": "figures_block_malformed",
+ "line": line_no,
+ "claim": raw,
+ "value": None,
+ "role": None,
+ "span": None,
+ "symbol": None,
+ "reason": "unparseable_declaration",
+ "message": (f"figures block line {line_no} could not be read as `value | role | note | ref`: " + raw),
+ }
+ for line_no, raw in _active_block(ledger).malformed
+ ]
+
+
+@grounding_check(
+ name="unsourced-symbol-figures",
+ code="unsourced_symbol_figures",
+ description=(
+ "A line pairs a symbol no tool call in this session passed in or "
+ "returned with a measured figure, so its only origin is model memory."
+ ),
+)
+def _unsourced_symbol_figures(ledger: Any, content: str) -> list[dict[str, Any]]:
+ block = _active_block(ledger)
+ figures = ledger._active_figures
+ issues: list[dict[str, Any]] = []
+ reported: set[str] = set()
+ for index, (line, offset) in enumerate(_lines_with_offsets(content)):
+ unknown = sorted(
+ symbol
+ for symbol in _scan_symbols(line) - ledger._session_symbols - reported
+ if symbol.rsplit(".", 1)[0] not in ledger._session_symbol_roots
+ )
+ if not unknown:
+ continue
+ carried = [figure for figure in figures if figure.line == index and figure.shape == "measured"]
+ if not carried:
+ continue
+ # A figure declared ``cited`` is exempt, since a citation is an origin.
+ if all(
+ (match := block.match(figure.value, figure.percent, figure.digits)) is not None and match.role == "cited"
+ for figure in carried
+ ):
+ continue
+ for symbol in unknown:
+ reported.add(symbol)
+ issues.append(
+ {
+ "code": "unsourced_symbol_figures",
+ "symbol": symbol,
+ "value": None,
+ "role": None,
+ "reason": "symbol_never_handled",
+ "claim": line.strip()[:200],
+ "span": [offset, offset + len(line)],
+ "message": (
+ f"No tool call in this session passed in or returned {symbol}, "
+ "yet the answer attaches figures to it. Retrieve it, or report "
+ "it as not retrieved."
+ ),
+ }
+ )
+ return issues
diff --git a/agent/src/agent/grounding/identity_checks.py b/agent/src/agent/grounding/identity_checks.py
index 32a7a0046..59a0c12d8 100644
--- a/agent/src/agent/grounding/identity_checks.py
+++ b/agent/src/agent/grounding/identity_checks.py
@@ -54,3 +54,34 @@ def _listed_identity_relabelled_private(ledger: Any, content: str) -> list[dict[
),
}
]
+
+
+@grounding_check(
+ name="identity-not-locked",
+ code="identity_not_locked",
+ description=(
+ "A run that named an instrument concluded while its identity stayed unresolved, conflicting, or invalidated."
+ ),
+)
+def _identity_not_locked(ledger: Any, content: str) -> list[dict[str, Any]]:
+ # 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``.
+ status = ledger.identity_status
+ if not (
+ ledger._identity_required and ledger._identities and status in {"unresolved", "conflicting", "invalidated"}
+ ):
+ return []
+ return [
+ {
+ "code": "identity_not_locked",
+ "status": status,
+ "value": None,
+ "role": None,
+ "span": None,
+ "symbol": None,
+ "reason": "identity_not_locked",
+ "message": (f"Instrument identity is {status}; a final market conclusion requires locked identity."),
+ }
+ ]
diff --git a/agent/src/agent/grounding/ledger.py b/agent/src/agent/grounding/ledger.py
index 10761234f..4ad013412 100644
--- a/agent/src/agent/grounding/ledger.py
+++ b/agent/src/agent/grounding/ledger.py
@@ -19,7 +19,7 @@ from src.agent.grounding.identity import (
_utc_now,
)
from src.agent.grounding.evidence import EvidenceRecord, _EvidenceMixin, _json_object
-from src.agent.grounding.figures import Figure, parse_figures_block, scan_figures, strip_figures_block
+from src.agent.grounding.figures import Figure, FiguresBlock, parse_figures_block, scan_figures, strip_figures_block
from src.agent.grounding.policies import ValidationResult, _PolicyMixin
from src.agent.grounding.registry import GROUNDING_CHECKS
from src.agent.grounding.release import (
@@ -130,6 +130,12 @@ class GroundingLedger(
# any. Not a draft, so it stays out of ``validation_count``.
self._released: dict[str, Any] | None = None
self._recovery_rounds = 0
+ # Parsed figures state of the answer under validation. Declared checks
+ # receive only (ledger, content), so the gate stashes it here for the
+ # walk; that is what the registry contract means by figure state
+ # living on the ledger.
+ self._active_block: FiguresBlock | None = None
+ self._active_figures: Sequence[Figure] = ()
self._symbol_resolution_attempts = 0
self._price_evidence_attempts = 0
self._ingested_csvs: set[str] = set()
@@ -365,9 +371,11 @@ class GroundingLedger(
self._ingest_run_dir_ohlc_csvs()
block = parse_figures_block(content)
figures = scan_figures(content, block)
+ self._active_block = block
+ self._active_figures = figures
issues: list[dict[str, Any]] = []
issues.extend(self._validate_identity(content))
- issues.extend(self._validate_unsourced_symbols(content, figures, block))
+ issues.extend(GROUNDING_CHECKS.run("unsourced-symbol-figures", self, content))
issues.extend(self._validate_figures(content, block, figures))
issues = self._dedupe_issues(issues)
result = ValidationResult(
diff --git a/agent/src/agent/grounding/policies.py b/agent/src/agent/grounding/policies.py
index 179f6bd41..96e3c5447 100644
--- a/agent/src/agent/grounding/policies.py
+++ b/agent/src/agent/grounding/policies.py
@@ -21,6 +21,7 @@ from src.agent.grounding.identity import (
_scan_symbols,
)
from src.agent.grounding import identity_checks # noqa: F401 (registers declared checks)
+from src.agent.grounding import figures_checks # noqa: F401 (registers declared checks)
from src.agent.grounding.registry import GROUNDING_CHECKS
from src.agent.grounding.evidence import (
EvidenceRecord,
@@ -432,31 +433,7 @@ class _PolicyMixin:
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
- # 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
- and status in {"unresolved", "conflicting", "invalidated"}
- ):
- issues.append(
- {
- "code": "identity_not_locked",
- "status": status,
- "value": None,
- "role": None,
- "span": None,
- "symbol": None,
- "reason": "identity_not_locked",
- "message": (
- f"Instrument identity is {status}; a final market conclusion "
- "requires locked identity."
- ),
- }
- )
+ issues.extend(GROUNDING_CHECKS.run("identity-not-locked", self, content))
issues.extend(GROUNDING_CHECKS.run("listed-identity-relabelled-private", self, content))
return issues
@@ -477,23 +454,7 @@ class _PolicyMixin:
One issue per figure that its role does not survive, plus one per
malformed declaration line and the provenance findings.
"""
- issues: list[dict[str, Any]] = [
- {
- "code": "figures_block_malformed",
- "line": line_no,
- "claim": raw,
- "value": None,
- "role": None,
- "span": None,
- "symbol": None,
- "reason": "unparseable_declaration",
- "message": (
- f"figures block line {line_no} could not be read as "
- "`value | role | note | ref`: " + raw
- ),
- }
- for line_no, raw in block.malformed
- ]
+ issues: list[dict[str, Any]] = GROUNDING_CHECKS.run("figures-block-malformed", self, content)
records = self._comparable_price_records()
# Symbol resolution is broader than price comparison. A session may hold
# quotes for the primary listing and only non-price evidence for another
@@ -2033,66 +1994,6 @@ class _PolicyMixin:
]
return []
- def _validate_unsourced_symbols(
- self,
- content: str,
- figures: Sequence[Figure],
- block: FiguresBlock,
- ) -> list[dict[str, Any]]:
- """Reject figures attached to an instrument no tool in this run handled.
-
- 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()
- for index, (line, offset) in enumerate(_lines_with_offsets(content)):
- unknown = sorted(
- symbol
- for symbol in _scan_symbols(line)
- - self._session_symbols
- - reported
- if symbol.rsplit(".", 1)[0] not in self._session_symbol_roots
- )
- if not unknown:
- continue
- carried = [
- figure
- for figure in figures
- if figure.line == index and figure.shape == "measured"
- ]
- if not carried:
- continue
- if all(
- (
- block.match(figure.value, figure.percent, figure.digits)
- or _NO_DECLARATION
- ).role
- == "cited"
- for figure in carried
- ):
- continue
- for symbol in unknown:
- reported.add(symbol)
- issues.append(
- {
- "code": "unsourced_symbol_figures",
- "symbol": symbol,
- "value": None,
- "role": None,
- "reason": "symbol_never_handled",
- "claim": line.strip()[:200],
- "span": [offset, offset + len(line)],
- "message": (
- f"No tool call in this session passed in or returned {symbol}, "
- "yet the answer attaches figures to it. Retrieve it, or report "
- "it as not retrieved."
- ),
- }
- )
- return issues
-
@staticmethod
def _symbol_for_claim(
content: str,
diff --git a/agent/tests/test_grounding_registry.py b/agent/tests/test_grounding_registry.py
index df58069b7..35044d911 100644
--- a/agent/tests/test_grounding_registry.py
+++ b/agent/tests/test_grounding_registry.py
@@ -114,3 +114,79 @@ def test_fired_checks_empty_for_a_clean_answer(tmp_path: Path) -> None:
ledger = _ledger_with_locked_listed_identity(tmp_path)
ledger.validate_final_answer("GLD 是上市 ETF,维持观察。")
assert _recorded_validations(tmp_path)[-1]["fired_checks"] == []
+
+
+def _ledger_with_invalidated_identity(tmp_path: Path) -> GroundingLedger:
+ """A failed resolution leaves identity invalidated (#1622 identity slice)."""
+ ledger = GroundingLedger(run_dir=tmp_path, user_message="分析机器人ETF并给出买入价")
+ ledger.ingest_tool_result(
+ tool_name="search_symbol",
+ arguments={"query": "机器人ETF"},
+ result=json.dumps({"ok": False, "error": "timeout"}),
+ call_id="resolve",
+ success=False,
+ )
+ return ledger
+
+
+def test_declared_checks_cover_identity_and_figure_slices_in_order() -> None:
+ assert [d["name"] for d in GROUNDING_CHECKS.describe()] == [
+ "listed-identity-relabelled-private",
+ "identity-not-locked",
+ "figures-block-malformed",
+ "unsourced-symbol-figures",
+ ]
+
+
+def test_identity_not_locked_fires_identically_through_the_gate(tmp_path: Path) -> None:
+ ledger = _ledger_with_invalidated_identity(tmp_path)
+ answer = "机器人ETF 可以买入。"
+ result = ledger.validate_final_answer(answer)
+ assert "identity_not_locked" in [str(issue.get("code")) for issue in result.issues]
+ direct = GROUNDING_CHECKS.run("identity-not-locked", ledger, answer)
+ assert [issue["code"] for issue in direct] == ["identity_not_locked"]
+
+
+def test_identity_not_locked_is_silent_once_locked(tmp_path: Path) -> None:
+ ledger = _ledger_with_locked_listed_identity(tmp_path)
+ assert GROUNDING_CHECKS.run("identity-not-locked", ledger, "GLD 是上市 ETF。") == []
+
+
+def test_figures_block_malformed_fires_identically_through_the_gate(tmp_path: Path) -> None:
+ ledger = GroundingLedger(run_dir=tmp_path, user_message="随便聊聊")
+ answer = "一些文字\n\n```figures\n0.95 is my entry\n```"
+ result = ledger.validate_final_answer(answer)
+ assert "figures_block_malformed" in [str(issue.get("code")) for issue in result.issues]
+ # The walk just stashed this answer's figure state on the ledger, which is
+ # what a direct registry run reads.
+ direct = GROUNDING_CHECKS.run("figures-block-malformed", ledger, answer)
+ assert [issue["code"] for issue in direct] == ["figures_block_malformed"]
+
+
+def test_unsourced_symbol_figures_fires_identically_through_the_gate(tmp_path: Path) -> None:
+ ledger = _ledger_with_locked_listed_identity(tmp_path)
+ answer = "GLD 维持观察。000858.SZ 现价 15.20 元,可以买入。"
+ result = ledger.validate_final_answer(answer)
+ assert "unsourced_symbol_figures" in [str(issue.get("code")) for issue in result.issues]
+ direct = GROUNDING_CHECKS.run("unsourced-symbol-figures", ledger, answer)
+ assert [issue["code"] for issue in direct] == ["unsourced_symbol_figures"]
+
+
+def test_unsourced_symbol_figures_ignores_session_symbols(tmp_path: Path) -> None:
+ ledger = _ledger_with_locked_listed_identity(tmp_path)
+ answer = "GLD 现价 999.99 美元,建议买入。"
+ ledger.validate_final_answer(answer)
+ assert GROUNDING_CHECKS.run("unsourced-symbol-figures", ledger, answer) == []
+
+
+def test_fired_checks_name_the_identity_and_figure_slices(tmp_path: Path) -> None:
+ ledger = _ledger_with_invalidated_identity(tmp_path)
+ ledger.validate_final_answer("机器人ETF 可以买入。")
+ assert _recorded_validations(tmp_path)[-1]["fired_checks"] == ["identity-not-locked"]
+
+ figure_ledger = GroundingLedger(run_dir=tmp_path / "figs", user_message="随便聊聊")
+ figure_ledger.validate_final_answer("一些文字\n\n```figures\n0.95 is my entry\n```")
+ artifact = json.loads(
+ (tmp_path / "figs" / "artifacts" / "grounding_evidence.json").read_text(encoding="utf-8")
+ )
+ assert artifact["validations"][-1]["fired_checks"] == ["figures-block-malformed"]