@@ -237,6 +237,9 @@ class PostcodeDetails(FromLibrary):
237237 building_use_status : str | None = Field (description = "Level 3 and up, e.g. residential." )
238238 other_building_info : Any = Field (default = None , description = "Level 4 and up, unstructured." )
239239 point_geometry : Any = Field (default = None , description = "Level 5, unstructured." )
240+ note : str | None = Field (
241+ default = None , description = "Why the answer may be incomplete, such as a test key."
242+ )
240243
241244
242245class Completion (FromLibrary ):
@@ -273,6 +276,9 @@ class Location(FromLibrary):
273276 message : str | None
274277 radius_m : float | None = Field (description = "The radius the API actually applied." )
275278 depth : str | None = Field (default = None , description = "How deep the match goes, e.g. unit." )
279+ note : str | None = Field (
280+ default = None , description = "Why the answer may be incomplete, such as a test key."
281+ )
276282
277283
278284@dataclass (frozen = True , slots = True )
@@ -369,8 +375,9 @@ async def lookup_postcode(
369375
370376 For the address and building details, use lookup_postcode_details.
371377 """
372- result = await api (ctx ).send (lookup (checked (postcode ), level ))
373- return PostcodeDetails .model_validate (unwrap (result ))
378+ client = api (ctx )
379+ result = await client .send (lookup (checked (postcode ), level ))
380+ return noted (PostcodeDetails .model_validate (unwrap (result )), client )
374381
375382 async def lookup_postcode_details (
376383 postcode : Annotated [
@@ -413,7 +420,7 @@ async def lookup_postcode_details(
413420 result = await client .send (lookup (code , level ))
414421 if mine and not reached_billing (result ):
415422 state .paid [0 ] -= 1
416- return PostcodeDetails .model_validate (unwrap (result ))
423+ return noted ( PostcodeDetails .model_validate (unwrap (result )), client )
417424
418425 # Not offered at all under the default cap, so a model cannot spend by accident.
419426 if settings .max_level >= 2 :
@@ -476,10 +483,10 @@ async def find_postcode_at_location(
476483
477484 Names and the house address are withheld unless NG_POSTCODE_MAX_LEVEL is 2 or more.
478485 """
479- result = await api (ctx ). send (
480- reverse (Coordinate (lat = latitude , lng = longitude ), max_distance_m )
481- )
482- return capped ( Location . model_validate ( unwrap ( result )), settings . max_level )
486+ client = api (ctx )
487+ result = await client . send ( reverse (Coordinate (lat = latitude , lng = longitude ), max_distance_m ) )
488+ found = capped ( Location . model_validate ( unwrap ( result )), settings . max_level )
489+ return noted ( found , client )
483490
484491 @server .tool (
485492 title = "Resolve a Nigerian address to a postcode" ,
@@ -595,6 +602,17 @@ def geocoder_for(settings: Settings, http: httpx.AsyncClient | None) -> Nominati
595602 )
596603
597604
605+ Answer = TypeVar ("Answer" , PostcodeDetails , Location )
606+
607+ TEST_KEY = "Asked with a test key, which may not see assigned codes."
608+
609+
610+ def noted (answer : Answer , client : AsyncClient ) -> Answer :
611+ """The answer, with a note when a test key found nothing: NIPOST may hold the building."""
612+ missing = not (answer .valid if isinstance (answer , PostcodeDetails ) else answer .found )
613+ return answer .model_copy (update = {"note" : TEST_KEY }) if missing and client .test_key else answer
614+
615+
598616def capped (location : Location , max_level : int ) -> Location :
599617 """The location with only the unit's level 1 fields, unless the cap allows more. Any
600618 field the unit gains later is withheld until it is listed as level 1."""
0 commit comments