- botBrowser `play`: searches YouTube for the words as said, opens the first video (not an ad, without the playlist) and starts it, in one call (an address given opens that page); `type` also takes `query`. Live 0.1.19: the model stopped on YouTube's home page or the results, a retry was refused as a third call, and the answer still said the video played. - `brain.location` (기본 위치, default 대한민국) goes to the brain as `location_name`: the time line says it without GeoIP (no database on the game PC), and getWeather without a place uses it. - Planner and webSearch keep search words in the user's language (never translated into English), so recommendations fit where the user is. Evals (qwen3:8b, 3 runs): play ending on a playing video found with the words as said 0/6 -> 5/6; Korean searches for Korean requests 6/9 -> 8/9. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.2 KiB
7.2 KiB
Location Detection Spec
This specification documents the location detection module (src/jarvis/utils/location.py) which resolves the user's geographic location from an IP address using a local GeoLite2 database. The module is designed with privacy as the primary concern — all geolocation is performed locally and external network queries are minimised and opt-in.
Dependencies
- geoip2 — Local MaxMind GeoLite2 database reader. Required for any geolocation.
- miniupnpc — UPnP client for querying the local router's external IP. Optional.
- Both libraries degrade gracefully when unavailable (import errors are caught).
Configuration Keys
| Key | Type | Default | Description |
|---|---|---|---|
location_enabled |
bool | true |
Master toggle. When false, location context returns "Location: Disabled" and no detection is attempted. |
location_auto_detect |
bool | true |
Allow automatic IP detection via UPnP, socket, and (if enabled) OpenDNS. When false, only location_ip_address or direct parameters are used. |
location_ip_address |
str | null | null |
Manually configured public IP. Takes precedence over auto-detection when set. |
location_cgnat_resolve_public_ip |
bool | true |
When a CGNAT address (100.64.0.0/10) is detected, attempt a single DNS query to OpenDNS to resolve the true public IP. Disable to prevent any external DNS query. |
location_cache_minutes |
int | 60 |
TTL for cached location lookups persisted to disk. |
location_name |
str | null | null |
A place the user set (v2: the app's brain.location, default 대한민국). When set (and location_enabled), the reply engine's time line says Location: <name> (where the user is) without any detection, and getWeather without a place asked for uses it (a place the person names still wins). The local time is then the computer's. Live 2026-11-16: the game PC has no GeoLite2 database, so detection always failed ("Location: Unknown", weather asked for the city) and searches fitted no country. |
IP Resolution Chain
When get_location_info is called without an explicit ip_address:
- Manual IP (
config_ip) — used as-is if provided. - Auto-detection (only when
auto_detect=True):- UPnP — queries the local router via
miniupnpc. Most privacy-friendly; no traffic leaves the LAN. Returns the router's external IP if UPnP is enabled and the IP is public. - Socket heuristic — opens a UDP socket to well-known DNS servers (Google
8.8.8.8, Cloudflare1.1.1.1, OpenDNS208.67.222.222) without sending data, to determine which local interface would be used. Returns the first non-private IP found. - OpenDNS DNS query — sends a single
myip.opendns.comA-record query to208.67.222.222:53. This is the only step that transmits data externally. The DNS response is validated for RTYPE=1 (A record) and RCLASS=1 (IN) before interpreting the RDATA as an IPv4 address. Returns the resolved public IP if valid.
- UPnP — queries the local router via
- Local IP fallback — if all auto-detection fails (or
auto_detect=False), falls back to the local network interface IP via a non-routable socket connect. This IP is typically private and will not produce a geolocation result.
CGNAT Resolution
If the resolved IP falls within the CGNAT range (100.64.0.0/10) and resolve_cgnat_public_ip=True:
- A single DNS query to OpenDNS (
myip.opendns.com) resolves the true public IP. - Results are cached in memory and on disk with a 1-hour TTL to minimise repeated queries.
- If the resolved IP is still CGNAT or private, the original IP is kept (and geolocation will likely fail gracefully).
Caching
Two independent caches exist, each with in-memory and on-disk tiers:
| Cache | Key | Value | Disk path | TTL |
|---|---|---|---|---|
| Location | Final resolved IP | Location info dict | ~/.local/share/jarvis/location_cache.json |
location_cache_minutes (default 60 min) |
| CGNAT resolution | Original CGNAT IP | (timestamp, resolved_ip | None) |
~/.local/share/jarvis/cgnat_cache.json |
1 hour (hardcoded) |
- Disk caches are loaded on module import and persisted after each successful lookup or CGNAT resolution.
- Expired entries are discarded on load.
- All cache reads and writes are protected by a module-level
threading.RLock(_cache_lock) for thread safety.
GeoLite2 Database
- Expected path:
~/.local/share/jarvis/geoip/GeoLite2-City.mmdb - Database freshness check: files older than 30 days trigger a setup instruction prompt.
- Setup instructions are printed once per session (guarded by
_location_warning_shown). - The module does not auto-download the database; users must register at MaxMind and place the file manually.
Public API
| Function | Returns | Description |
|---|---|---|
get_location_info(ip_address, *, config_ip, auto_detect, resolve_cgnat_public_ip, location_cache_minutes) |
dict |
Core lookup. Returns location fields or {"error": ...}. |
get_location_context(*, config_ip, auto_detect, resolve_cgnat_public_ip, location_cache_minutes) |
str |
Formatted string like "Location: London, England, United Kingdom (Europe/London)" or "Location: Unknown". |
get_detailed_location_info(ip_address, *, config_ip, auto_detect, resolve_cgnat_public_ip, location_cache_minutes) |
dict |
Extends get_location_info with computed coordinates and formatted_address fields. |
is_location_available() |
bool |
True if geoip2 is importable and the database file exists. |
setup_location_database() |
bool |
Checks database availability and prints setup instructions if missing. |
Privacy Guarantees
- No HTTP calls — the module never contacts HTTP-based IP lookup services.
- Single DNS query — the only external network activity is a raw UDP DNS query to OpenDNS, and only when:
auto_detect=Trueand both UPnP and socket detection failed, OR- A CGNAT IP is detected and
resolve_cgnat_public_ip=True.
- Fully disableable — setting
location_enabled=falseprevents all detection. Settinglocation_auto_detect=falseandlocation_cgnat_resolve_public_ip=falseprevents any external query while still allowing manual IP geolocation.
Error Handling
AddressNotFoundErrorfrom geoip2 returns a structured error withreason("cgnat_not_found"or"not_found") and user-facingadvice.- All other exceptions are caught and returned as
{"error": "<message>", "ip": "<ip>"}. - Negative results are cached to avoid repeated failed lookups for the same IP.
Integration Points
- Daemon (
src/jarvis/daemon.py): Callsget_location_contextat startup using config values. - Reply Engine (
src/jarvis/reply/engine.py): Refreshes location context each agentic turn viaget_location_context. - Setup Wizard (
src/desktop_app/setup_wizard.py): Usesget_location_contextandget_location_infofor status display and IP validation. Skips the location page entirely whenlocation_enabled=false. Uses the OpenDNS resolver (not an external website) for the "Detect My IP" button. IP validation reuses the core_is_private_ipand_is_cgnat_iphelpers. - Settings UI (
src/desktop_app/settings_window.py): Exposes all five config keys as toggleable fields.