Add verification types, compliance policy fields, X-API-Key auth (TEC-177, TEC-179, TEC-182)

- Add VerificationLevel literal type and OperatorVerification TypedDict
- Add verification_level to ReputationResponse
- Add operator_verification, verify_url, resolved_operator to AssessResponse
- Add compliance policy fields to DecisionPolicy
- Switch auth header from Authorization: Bearer to X-API-Key
- Add python-dotenv + conftest.py for integration test env loading
- Update tests for new types and auth header

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

Author: vvillait88

agentscore/__init__.py

@@ -7,9 +7,11 @@
     DecisionPolicy,
     EntityType,
     Grade,
+    OperatorVerification,
     Reputation,
     ReputationResponse,
     ReputationStatus,
+    VerificationLevel,
 )
 
 __version__ = _pkg_version("agentscore-py")
@@ -21,8 +23,10 @@
     "DecisionPolicy",
     "EntityType",
     "Grade",
+    "OperatorVerification",
     "Reputation",
     "ReputationResponse",
     "ReputationStatus",
+    "VerificationLevel",
     "__version__",
 ]

agentscore/client.py

@@ -35,7 +35,7 @@ def __init__(
     def _headers(self) -> dict:
         return {
             "Accept": "application/json",
-            "Authorization": f"Bearer {self.api_key}",
+            "X-API-Key": self.api_key,
             "User-Agent": f"agentscore-py/{_pkg_version('agentscore-py')}",
         }
 

agentscore/types.py

@@ -5,6 +5,7 @@
 Grade = Literal["A", "B", "C", "D", "F"]
 EntityType = Literal["agent", "service", "hybrid", "wallet", "bot", "unknown"]
 ReputationStatus = Literal["scored", "stale", "known_unscored"]
+VerificationLevel = Literal["none", "wallet_claimed", "kyc_verified"]
 
 
 class Subject(TypedDict):
@@ -132,12 +133,28 @@ class ReputationResponse(_ReputationResponseRequired, total=False):
     reputation: Reputation
     operator_score: OperatorScore
     agents: list[AgentSummary]
+    verification_level: VerificationLevel
+
+
+class _OperatorVerificationRequired(TypedDict):
+    level: VerificationLevel
+
+
+class OperatorVerification(_OperatorVerificationRequired, total=False):
+    operator_type: str | None
+    claimed_at: str | None
+    verified_at: str | None
 
 
 class DecisionPolicy(TypedDict, total=False):
     min_grade: Grade
     min_score: int
     require_verified_payment_activity: bool
+    require_kyc: bool
+    require_sanctions_clear: bool
+    min_age: int
+    blocked_jurisdictions: list[str]
+    require_entity_type: str
 
 
 class _AssessResponseRequired(TypedDict):
@@ -156,3 +173,6 @@ class AssessResponse(_AssessResponseRequired, total=False):
     operator_score: OperatorScore | None
     reputation: Reputation | None
     agents: list[AgentSummary]
+    operator_verification: OperatorVerification
+    resolved_operator: str
+    verify_url: str

pyproject.toml

@@ -46,4 +46,5 @@ dev = [
     "pytest-cov>=6.0",
     "respx>=0.22.0",
     "pytest-asyncio>=1.2.0",
+    "python-dotenv>=1.2.1",
 ]

tests/conftest.py

@@ -0,0 +1,3 @@
+from dotenv import load_dotenv
+
+load_dotenv()

tests/test_client.py

@@ -220,7 +220,7 @@ def test_assess_raises_on_402():
 
 
 # ---------------------------------------------------------------------------
-# Authorization header
+# API key header
 # ---------------------------------------------------------------------------
 
 REPUTATION_PAYLOAD_SIMPLE = {
@@ -239,7 +239,7 @@ def test_auth_header_is_sent():
     )
     client = AgentScore(api_key="my-secret-key")
     client.get_reputation(ADDRESS)
-    assert route.calls.last.request.headers["authorization"] == "Bearer my-secret-key"
+    assert route.calls.last.request.headers["x-api-key"] == "my-secret-key"
 
 
 # ---------------------------------------------------------------------------
@@ -485,3 +485,182 @@ def test_error_response_no_error_key_fallback():
         client.get_reputation(ADDRESS)
     assert exc_info.value.status_code == 422
     assert exc_info.value.code == "unknown_error"
+
+
+# ---------------------------------------------------------------------------
+# Verification / Compliance fields
+# ---------------------------------------------------------------------------
+
+
+REPUTATION_WITH_VERIFICATION = {
+    **REPUTATION_PAYLOAD,
+    "verification_level": "kyc_verified",
+}
+
+ASSESS_WITH_COMPLIANCE = {
+    **ASSESS_PAYLOAD,
+    "decision": "deny",
+    "decision_reasons": ["kyc_required", "sanctions_check_pending"],
+    "operator_verification": {
+        "level": "none",
+        "operator_type": None,
+        "claimed_at": None,
+        "verified_at": None,
+    },
+    "verify_url": "https://agentscore.sh/verify/abc123",
+    "resolved_operator": "0xoperator456",
+}
+
+
+@respx.mock
+def test_get_reputation_returns_verification_level():
+    respx.get(f"{BASE_URL}/v1/reputation/{ADDRESS}").mock(
+        return_value=httpx.Response(200, json=REPUTATION_WITH_VERIFICATION)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = client.get_reputation(ADDRESS)
+    assert result["verification_level"] == "kyc_verified"
+
+
+@respx.mock
+def test_get_reputation_omits_verification_level_when_absent():
+    respx.get(f"{BASE_URL}/v1/reputation/{ADDRESS}").mock(
+        return_value=httpx.Response(200, json=REPUTATION_PAYLOAD)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = client.get_reputation(ADDRESS)
+    assert "verification_level" not in result
+
+
+@respx.mock
+def test_assess_returns_operator_verification():
+    respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(200, json=ASSESS_WITH_COMPLIANCE)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = client.assess(ADDRESS)
+    assert result["operator_verification"]["level"] == "none"
+    assert result["operator_verification"]["operator_type"] is None
+
+
+@respx.mock
+def test_assess_returns_verify_url():
+    respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(200, json=ASSESS_WITH_COMPLIANCE)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = client.assess(ADDRESS)
+    assert result["verify_url"] == "https://agentscore.sh/verify/abc123"
+
+
+@respx.mock
+def test_assess_returns_resolved_operator():
+    respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(200, json=ASSESS_WITH_COMPLIANCE)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = client.assess(ADDRESS)
+    assert result["resolved_operator"] == "0xoperator456"
+
+
+@respx.mock
+def test_assess_omits_verification_fields_when_absent():
+    respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(200, json=ASSESS_PAYLOAD)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = client.assess(ADDRESS)
+    assert "operator_verification" not in result
+    assert "verify_url" not in result
+    assert "resolved_operator" not in result
+
+
+@respx.mock
+def test_assess_sends_compliance_policy_fields():
+    route = respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(200, json=ASSESS_PAYLOAD)
+    )
+    client = AgentScore(api_key=API_KEY)
+    policy = {
+        "require_kyc": True,
+        "require_sanctions_clear": True,
+        "min_age": 90,
+        "blocked_jurisdictions": ["KP", "IR"],
+        "require_entity_type": "agent",
+    }
+    client.assess(ADDRESS, policy=policy)
+    body = json.loads(route.calls.last.request.content)
+    assert body["policy"]["require_kyc"] is True
+    assert body["policy"]["require_sanctions_clear"] is True
+    assert body["policy"]["min_age"] == 90
+    assert body["policy"]["blocked_jurisdictions"] == ["KP", "IR"]
+    assert body["policy"]["require_entity_type"] == "agent"
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_aget_reputation_returns_verification_level():
+    respx.get(f"{BASE_URL}/v1/reputation/{ADDRESS}").mock(
+        return_value=httpx.Response(200, json=REPUTATION_WITH_VERIFICATION)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = await client.aget_reputation(ADDRESS)
+    assert result["verification_level"] == "kyc_verified"
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_aassess_returns_compliance_fields():
+    respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(200, json=ASSESS_WITH_COMPLIANCE)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = await client.aassess(ADDRESS)
+    assert result["operator_verification"]["level"] == "none"
+    assert result["verify_url"] == "https://agentscore.sh/verify/abc123"
+    assert result["resolved_operator"] == "0xoperator456"
+    await client.aclose()
+
+
+# ---------------------------------------------------------------------------
+# Integration-style: compliance deny flow
+# ---------------------------------------------------------------------------
+
+
+@respx.mock
+def test_full_compliance_deny_flow():
+    """Full assess flow with compliance policy returning deny + verify_url."""
+    compliance_response = {
+        **REPUTATION_PAYLOAD,
+        "decision": "deny",
+        "decision_reasons": ["kyc_required", "sanctions_check_pending"],
+        "on_the_fly": False,
+        "operator_verification": {
+            "level": "none",
+            "operator_type": None,
+            "claimed_at": None,
+            "verified_at": None,
+        },
+        "verify_url": "https://agentscore.sh/verify/xyz789",
+    }
+    route = respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(200, json=compliance_response)
+    )
+    client = AgentScore(api_key=API_KEY)
+    result = client.assess(
+        ADDRESS,
+        policy={
+            "require_kyc": True,
+            "require_sanctions_clear": True,
+        },
+    )
+    assert result["decision"] == "deny"
+    assert "kyc_required" in result["decision_reasons"]
+    assert "sanctions_check_pending" in result["decision_reasons"]
+    assert result["verify_url"] == "https://agentscore.sh/verify/xyz789"
+    assert result["operator_verification"]["level"] == "none"
+
+    body = json.loads(route.calls.last.request.content)
+    assert body["policy"]["require_kyc"] is True
+    assert body["policy"]["require_sanctions_clear"] is True

tests/test_integration.py

@@ -104,16 +104,6 @@ def test_get_reputation_operator_score():
     assert isinstance(op["chains_active"], list)
 
 
-def test_get_reputation_reputation_field():
-    client = AgentScore(api_key=API_KEY, base_url=BASE_URL)
-    rep = client.get_reputation(TEST_ADDRESS)
-    r = rep.get("reputation")
-    if not r:
-        pytest.skip("no reputation on test address")
-    assert isinstance(r["feedback_count"], int)
-    assert isinstance(r["client_count"], int)
-
-
 def test_assess_then_get_reputation():
     client = AgentScore(api_key=API_KEY, base_url=BASE_URL)
     assessed = client.assess(TEST_ADDRESS)