feat: add is_agentscore_test_address + AGENTSCORE_TEST_ADDRESSES

Python parity with the test-mode helper currently shipping in @agent-score/pay
and @agent-score/mcp. Recognizes the seven reserved AgentScore EVM test
fixtures (0x0000…0001 through 0x0000…0007) so dev/test interactions can be
labeled distinctly without burning real KYC credits.

Lives in agentscore.test_mode and is re-exported from the package root.

6 new tests, coverage holds at 97.35%.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

agentscore/__init__.py

@@ -2,6 +2,7 @@
 
 from agentscore.client import AgentScore
 from agentscore.errors import AgentScoreError
+from agentscore.test_mode import AGENTSCORE_TEST_ADDRESSES, is_agentscore_test_address
 from agentscore.types import (
     AccountVerification,
     AgentMemoryHint,
@@ -35,6 +36,7 @@
 __version__ = _pkg_version("agentscore-py")
 
 __all__ = [
+    "AGENTSCORE_TEST_ADDRESSES",
     "AccountVerification",
     "AgentMemoryHint",
     "AgentMemoryIdentityPaths",
@@ -65,5 +67,6 @@
     "WalletAuthRequiresSigningBody",
     "WalletSignerMismatchBody",
     "__version__",
+    "is_agentscore_test_address",
     "verify_webhook_signature",
 ]

agentscore/test_mode.py

@@ -0,0 +1,41 @@
+"""Recognizers for AgentScore reserved test addresses.
+
+AgentScore's ``/v1/assess`` endpoint recognizes seven EVM addresses
+(``0x0000…0001`` through ``0x0000…0007``) as test fixtures with deterministic
+policy outcomes — KYC verified, sanctions clear, age gates passing — so dev/test
+interactions don't burn real KYC credits and produce predictable results.
+
+Use this in test suites and dev/staging tooling to label test-mode interactions
+distinctly from production traffic.
+"""
+
+from __future__ import annotations
+
+_TEST_ADDRESSES: frozenset[str] = frozenset(
+    {
+        "0x0000000000000000000000000000000000000001",
+        "0x0000000000000000000000000000000000000002",
+        "0x0000000000000000000000000000000000000003",
+        "0x0000000000000000000000000000000000000004",
+        "0x0000000000000000000000000000000000000005",
+        "0x0000000000000000000000000000000000000006",
+        "0x0000000000000000000000000000000000000007",
+    },
+)
+
+AGENTSCORE_TEST_ADDRESSES: tuple[str, ...] = tuple(sorted(_TEST_ADDRESSES))
+"""The full list of reserved test addresses, exposed for documentation, completion,
+and downstream test fixtures."""
+
+
+def is_agentscore_test_address(address: str | None) -> bool:
+    """Recognize one of the seven reserved AgentScore EVM test fixtures.
+
+    Lowercases for comparison so accidentally mixed-case input still matches.
+    """
+    if not address:
+        return False
+    return address.lower() in _TEST_ADDRESSES
+
+
+__all__ = ["AGENTSCORE_TEST_ADDRESSES", "is_agentscore_test_address"]

tests/test_test_mode.py

@@ -0,0 +1,32 @@
+"""Tests for is_agentscore_test_address + AGENTSCORE_TEST_ADDRESSES."""
+
+from agentscore import AGENTSCORE_TEST_ADDRESSES, is_agentscore_test_address
+
+
+def test_returns_true_for_each_of_seven_reserved_addresses():
+    for i in range(1, 8):
+        addr = "0x" + "0" * 39 + str(i)
+        assert is_agentscore_test_address(addr) is True
+
+
+def test_matches_case_insensitively():
+    assert is_agentscore_test_address("0x0000000000000000000000000000000000000001".upper()) is True
+
+
+def test_returns_false_for_addresses_outside_reserved_range():
+    assert is_agentscore_test_address("0x0000000000000000000000000000000000000008") is False
+    assert is_agentscore_test_address("0xabcabcabcabcabcabcabcabcabcabcabcabcabca") is False
+
+
+def test_returns_false_for_none_and_empty():
+    assert is_agentscore_test_address(None) is False
+    assert is_agentscore_test_address("") is False
+
+
+def test_exports_exactly_seven_addresses():
+    assert len(AGENTSCORE_TEST_ADDRESSES) == 7
+
+
+def test_every_exported_address_passes_recognizer():
+    for addr in AGENTSCORE_TEST_ADDRESSES:
+        assert is_agentscore_test_address(addr) is True