Initial commit - Trekker V2 source

This commit is contained in:
Cortex committed 2026-06-10 11:03:37 -04:00
commit d71faf19e3
65 files changed
+3615

No files matched your search

View File
Whitespace-only changes.
+74
View File
@@ -0,0 +1,74 @@
"""Trekker configuration: env vars + optional YAML file (TREKKER_CONFIG)."""
from __future__ import annotations
import os
from pathlib import Path
from typing import Optional
import yaml
from pydantic import BaseModel, Field
from pydantic_settings import BaseSettings, SettingsConfigDict
class WatchConfig(BaseModel):
internal_path: Optional[str] = None
remote_path: Optional[str] = None
poll_interval: int = 30 # seconds, polling observer for remote mounts
class LLMConfig(BaseModel):
base_url: Optional[str] = None # e.g. http://localhost:11434/v1 for Ollama
model: str = "gpt-4o-mini"
api_key: Optional[str] = None
class TilesConfig(BaseModel):
# Raster basemap URL template. Default OSM is fine for interactive viewing;
# bulk offline downloads need a source whose policy permits it (see PLAN.md),
# hence the per-pack tile cap below.
base_url: str = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
# Terrarium-encoded terrain tiles (AWS Open Data, bulk download permitted).
terrain_url: str = "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png"
max_pack_tiles: int = 4000
user_agent: str = "Trekker/0.1 (+https://github.com/claw-peyo/trekker)"
class SyncConfig(BaseModel):
peer_url: Optional[str] = None # e.g. http://neutron.tailnet:8000
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_prefix="TREKKER_", env_file=".env", extra="ignore")
data_dir: str = "data"
host_role: str = "home" # home | neutron
watch: WatchConfig = Field(default_factory=WatchConfig)
llm: LLMConfig = Field(default_factory=LLMConfig)
tiles: TilesConfig = Field(default_factory=TilesConfig)
sync: SyncConfig = Field(default_factory=SyncConfig)
@property
def db_path(self) -> str:
return str(Path(self.data_dir) / "trekker.db")
@property
def offline_maps_dir(self) -> str:
return str(Path(self.data_dir) / "offline_maps")
@property
def pdf_dir(self) -> str:
return str(Path(self.data_dir) / "pdfs")
def load_settings() -> Settings:
"""Env settings, overlaid with YAML from TREKKER_CONFIG if present."""
overrides: dict = {}
config_path = os.environ.get("TREKKER_CONFIG", "trekker.yml")
path = Path(config_path)
if path.is_file():
overrides = yaml.safe_load(path.read_text()) or {}
return Settings(**overrides)
settings = load_settings()
+32
View File
@@ -0,0 +1,32 @@
"""Shared singletons wired at startup (store, services)."""
from __future__ import annotations
from functools import lru_cache
from app.config import settings
from app.services.elevation import ElevationService
from app.services.llm import LLMService
from app.services.offline_maps import OfflineMapService
from app.storage.database import connect
from app.storage.route_store import Store
@lru_cache(maxsize=1)
def get_store() -> Store:
return Store(connect(settings.db_path))
@lru_cache(maxsize=1)
def get_llm() -> LLMService:
return LLMService(settings.llm)
@lru_cache(maxsize=1)
def get_elevation() -> ElevationService:
return ElevationService()
@lru_cache(maxsize=1)
def get_offline_maps() -> OfflineMapService:
return OfflineMapService(get_store())
View File
Whitespace-only changes.
+91
View File
@@ -0,0 +1,91 @@
"""Enriched GPX export: TrekkerRoute -> GPX with trekker:* extensions.
Per-trackpoint extensions carry grade_pct; segment metadata and trail guide
enrichment (surface, water crossing depth) ride on track <extensions>.
Waypoints from the original import are preserved.
Namespaces are written as literal xmlns attributes rather than via
ET.register_namespace, which mutates global state across writers.
"""
from __future__ import annotations
import xml.etree.ElementTree as ET
from typing import Optional
from app.models.route import TrekkerRoute
from app.models.trail_guide import TrailGuide
GPX_NS = "http://www.topografix.com/GPX/1/1"
TREKKER_NS = "https://trekker.dev/xmlschemas/v1"
def _point_grades(route: TrekkerRoute) -> dict[int, float]:
"""Map point index -> avg grade of its segment (UI/export enrichment)."""
grades: dict[int, float] = {}
for seg in route.segments:
for i in range(seg.start_idx, seg.end_idx + 1):
grades[i] = seg.grade_pct_avg
return grades
def write_gpx(route: TrekkerRoute, trail_guide: Optional[TrailGuide] = None) -> str:
gpx = ET.Element("gpx", {
"version": "1.1",
"creator": "Trekker",
"xmlns": GPX_NS,
"xmlns:trekker": TREKKER_NS,
})
meta = ET.SubElement(gpx, "metadata")
ET.SubElement(meta, "name").text = route.name
for w in route.waypoints:
wpt = ET.SubElement(gpx, "wpt", {"lat": f"{w.lat:.7f}", "lon": f"{w.lon:.7f}"})
if w.ele is not None:
ET.SubElement(wpt, "ele").text = f"{w.ele:.1f}"
if w.time:
ET.SubElement(wpt, "time").text = w.time
if w.name:
ET.SubElement(wpt, "name").text = w.name
if w.desc:
ET.SubElement(wpt, "desc").text = w.desc
if w.sym:
ET.SubElement(wpt, "sym").text = w.sym
trk = ET.SubElement(gpx, "trk")
ET.SubElement(trk, "name").text = route.name
trk_ext = ET.SubElement(trk, "extensions")
ET.SubElement(trk_ext, "trekker:source").text = route.source
if trail_guide:
if trail_guide.difficulty:
ET.SubElement(trk_ext, "trekker:difficulty").text = trail_guide.difficulty
for wc in trail_guide.water_crossings:
el = ET.SubElement(trk_ext, "trekker:water_crossing")
if wc.name:
el.set("name", wc.name)
if wc.depth_ft is not None:
el.set("depth_ft", str(wc.depth_ft))
for seg in route.segments:
el = ET.SubElement(trk_ext, "trekker:segment")
el.set("name", seg.name)
el.set("distance_m", str(seg.distance_m))
el.set("grade_pct_avg", str(seg.grade_pct_avg))
el.set("grade_pct_max", str(seg.grade_pct_max))
grades = _point_grades(route)
surface = (route.metadata or {}).get("surface_type")
trkseg = ET.SubElement(trk, "trkseg")
for i, p in enumerate(route.points):
pt = ET.SubElement(trkseg, "trkpt", {"lat": f"{p.lat:.7f}", "lon": f"{p.lon:.7f}"})
if p.ele is not None:
ET.SubElement(pt, "ele").text = f"{p.ele:.1f}"
if p.time:
ET.SubElement(pt, "time").text = p.time
ext = ET.SubElement(pt, "extensions")
ET.SubElement(ext, "trekker:grade_pct").text = str(grades.get(i, 0.0))
if surface:
ET.SubElement(ext, "trekker:surface_type").text = str(surface)
return ET.tostring(gpx, encoding="unicode", xml_declaration=True)
+58
View File
@@ -0,0 +1,58 @@
"""KML export for onX compatibility: track LineString + waypoint Placemarks."""
from __future__ import annotations
import xml.etree.ElementTree as ET
from typing import Optional
from app.models.route import TrekkerRoute
from app.models.trail_guide import TrailGuide
KML_NS = "http://www.opengis.net/kml/2.2"
def _desc_for_route(route: TrekkerRoute, guide: Optional[TrailGuide]) -> str:
mi = route.stats.distance_m / 1609.344
gain = route.stats.elevation_gain_m * 3.28084
lines = [f"Distance: {mi:.1f} mi", f"Elevation gain: {gain:.0f} ft",
f"Source: {route.source}"]
for seg in route.segments:
lines.append(f"Segment {seg.name}: max grade {seg.grade_pct_max:.1f}%")
if guide:
if guide.difficulty:
lines.append(f"Difficulty: {guide.difficulty}")
for wc in guide.water_crossings:
depth = f" ({wc.depth_ft} ft)" if wc.depth_ft is not None else ""
lines.append(f"Water crossing: {wc.name or 'unnamed'}{depth}")
lines.extend(f"Warning: {w}" for w in guide.warnings)
return "\n".join(lines)
def write_kml(route: TrekkerRoute, trail_guide: Optional[TrailGuide] = None) -> str:
kml = ET.Element("kml", {"xmlns": KML_NS})
doc = ET.SubElement(kml, "Document")
ET.SubElement(doc, "name").text = route.name
track = ET.SubElement(doc, "Placemark")
ET.SubElement(track, "name").text = route.name
ET.SubElement(track, "description").text = _desc_for_route(route, trail_guide)
line = ET.SubElement(track, "LineString")
ET.SubElement(line, "tessellate").text = "1"
coords = " ".join(
f"{p.lon:.7f},{p.lat:.7f},{p.ele if p.ele is not None else 0:.1f}"
for p in route.points
)
ET.SubElement(line, "coordinates").text = coords
for w in route.waypoints:
pm = ET.SubElement(doc, "Placemark")
if w.name:
ET.SubElement(pm, "name").text = w.name
if w.desc:
ET.SubElement(pm, "description").text = w.desc
point = ET.SubElement(pm, "Point")
ET.SubElement(point, "coordinates").text = (
f"{w.lon:.7f},{w.lat:.7f},{w.ele if w.ele is not None else 0:.1f}"
)
return ET.tostring(kml, encoding="unicode", xml_declaration=True)
+11
View File
@@ -0,0 +1,11 @@
from app.generators.base import BaseGenerator, GeneratorError
from app.generators.elevation_map import ElevationMapGenerator
from app.generators.trail_card import TrailCardGenerator
from app.generators.weather_overlay import WeatherOverlayGenerator
GENERATORS: dict[str, type[BaseGenerator]] = {
g.name: g
for g in (TrailCardGenerator, ElevationMapGenerator, WeatherOverlayGenerator)
}
__all__ = ["BaseGenerator", "GeneratorError", "GENERATORS"]
+37
View File
@@ -0,0 +1,37 @@
"""Pluggable asset generator interface (PLAN.md Phase 5)."""
from __future__ import annotations
from abc import ABC, abstractmethod
from typing import Optional
from app.models.assets import Asset
from app.models.route import TrekkerRoute
from app.models.trail_guide import TrailGuide
class GeneratorError(Exception):
"""Missing prerequisite or generation failure; message is user-facing."""
class BaseGenerator(ABC):
name: str = "base"
description: str = ""
requires: list[str] = [] # subset of {"trail_guide", "weather"}
def check_requirements(self, route: TrekkerRoute,
trail_guide: Optional[TrailGuide],
weather: Optional[dict]) -> None:
if "trail_guide" in self.requires and trail_guide is None:
raise GeneratorError(
f"'{self.name}' needs a linked trail guide — link one to this route first"
)
if "weather" in self.requires and weather is None:
raise GeneratorError(
f"'{self.name}' needs cached weather — refresh weather for this route first"
)
@abstractmethod
def generate(self, route: TrekkerRoute, trail_guide: Optional[TrailGuide],
weather: Optional[dict]) -> Asset:
...
+55
View File
@@ -0,0 +1,55 @@
"""Elevation Heatmap: per-segment grade colors feeding the map layer."""
from __future__ import annotations
from typing import Optional
from app.generators.base import BaseGenerator
from app.models.assets import Asset
from app.models.route import TrekkerRoute
from app.models.trail_guide import TrailGuide
def grade_color(grade_pct: float) -> str:
"""green -> yellow -> red gradient by absolute grade %."""
g = abs(grade_pct)
if g < 5:
return "#2ecc71"
if g < 10:
return "#f1c40f"
if g < 18:
return "#e67e22"
return "#e74c3c"
class ElevationMapGenerator(BaseGenerator):
name = "elevation_map"
description = "Grade-colored segments and elevation callouts for the map layer"
requires: list[str] = []
def generate(self, route: TrekkerRoute, trail_guide: Optional[TrailGuide],
weather: Optional[dict]) -> Asset:
segments = [
{
"index": seg.index,
"name": seg.name,
"grade_pct_avg": seg.grade_pct_avg,
"grade_pct_max": seg.grade_pct_max,
"color": grade_color(seg.grade_pct_max),
"coordinates": [
[p.lon, p.lat] for p in route.points[seg.start_idx : seg.end_idx + 1]
],
}
for seg in route.segments
]
callouts = []
eles = [(i, p) for i, p in enumerate(route.points) if p.ele is not None]
if eles:
hi = max(eles, key=lambda ip: ip[1].ele)
lo = min(eles, key=lambda ip: ip[1].ele)
callouts = [
{"type": "summit", "lat": hi[1].lat, "lon": hi[1].lon, "ele_m": hi[1].ele},
{"type": "low_point", "lat": lo[1].lat, "lon": lo[1].lon, "ele_m": lo[1].ele},
]
return Asset(route_id=route.id, generator=self.name,
data={"segments": segments, "callouts": callouts})
+65
View File
@@ -0,0 +1,65 @@
"""Trail Card: per-segment readable summary combining route, guide, weather."""
from __future__ import annotations
from typing import Optional
from app.generators.base import BaseGenerator
from app.models.assets import Asset
from app.models.route import TrekkerRoute
from app.models.trail_guide import TrailGuide
def _difficulty_for_grade(grade_pct_max: float) -> str:
if grade_pct_max < 8:
return "easy"
if grade_pct_max < 15:
return "moderate"
if grade_pct_max < 25:
return "difficult"
return "extreme"
class TrailCardGenerator(BaseGenerator):
name = "trail_card"
description = "Per-segment trail card with difficulty, obstacles, and weather notes"
requires: list[str] = [] # degrades gracefully without guide/weather
def generate(self, route: TrekkerRoute, trail_guide: Optional[TrailGuide],
weather: Optional[dict]) -> Asset:
self.check_requirements(route, trail_guide, weather)
seg_weather = (weather or {}).get("segments", {})
segments = []
for seg in route.segments:
daily = seg_weather.get(str(seg.index), {}).get("daily", [])
today = daily[0] if daily else None
segments.append({
"name": seg.name,
"distance_mi": round(seg.distance_m / 1609.344, 2),
"elevation_gain_ft": round(seg.elevation_gain_m * 3.28084),
"elevation_loss_ft": round(seg.elevation_loss_m * 3.28084),
"grade_pct_max": seg.grade_pct_max,
"difficulty": (trail_guide.difficulty if trail_guide and trail_guide.difficulty
else _difficulty_for_grade(seg.grade_pct_max)),
"obstacles": trail_guide.obstacle_types if trail_guide else [],
"weather_today": today,
})
data = {
"route_name": route.name,
"source": route.source,
"total_distance_mi": round(route.stats.distance_m / 1609.344, 2),
"total_gain_ft": round(route.stats.elevation_gain_m * 3.28084),
"guide": None,
"segments": segments,
}
if trail_guide:
data["guide"] = {
"name": trail_guide.name,
"difficulty": trail_guide.difficulty,
"water_crossings": [wc.model_dump() for wc in trail_guide.water_crossings],
"gate_codes": trail_guide.gate_codes,
"vehicle_recommendations": trail_guide.vehicle_recommendations,
"closures": trail_guide.closures,
"warnings": trail_guide.warnings,
}
return Asset(route_id=route.id, generator=self.name, data=data)
+51
View File
@@ -0,0 +1,51 @@
"""Weather Overlay: per-segment advisory data feeding the weather map layer."""
from __future__ import annotations
from typing import Optional
from app.generators.base import BaseGenerator
from app.models.assets import Asset
from app.models.route import TrekkerRoute
from app.models.trail_guide import TrailGuide
def precip_color(prob: float | None) -> str:
"""blue gradient by precipitation probability."""
p = prob or 0
if p < 20:
return "#d6eaf8"
if p < 50:
return "#5dade2"
if p < 80:
return "#2e86c1"
return "#1b4f72"
class WeatherOverlayGenerator(BaseGenerator):
name = "weather_overlay"
description = "Per-segment precipitation/wind/lightning advisories"
requires = ["weather"]
def generate(self, route: TrekkerRoute, trail_guide: Optional[TrailGuide],
weather: Optional[dict]) -> Asset:
self.check_requirements(route, trail_guide, weather)
seg_weather = weather.get("segments", {})
segments = []
for seg in route.segments:
tiers = seg_weather.get(str(seg.index), {})
daily = tiers.get("daily", [])
today = daily[0] if daily else {}
segments.append({
"index": seg.index,
"name": seg.name,
"precip_prob_max": today.get("precip_prob_max"),
"color": precip_color(today.get("precip_prob_max")),
"wind_max_kmh": today.get("wind_max_kmh"),
"wind_advisory": (today.get("wind_max_kmh") or 0) >= 40,
"lightning_risk": bool(today.get("lightning_risk")),
"coordinates": [
[p.lon, p.lat] for p in route.points[seg.start_idx : seg.end_idx + 1]
],
})
return Asset(route_id=route.id, generator=self.name, data={"segments": segments})
View File
Whitespace-only changes.
+92
View File
@@ -0,0 +1,92 @@
"""GPX file -> TrekkerRoute, with source app detection."""
from __future__ import annotations
import gpxpy
import gpxpy.gpx
from app.ingest.segmenter import build_segments, compute_stats
from app.models.route import TrekkerRoute, TrkPt, Wpt
def detect_source(creator: str | None, raw_xml: str) -> str:
"""Detect originating app. Checks creator attribute first, namespaces as fallback."""
creator_l = (creator or "").lower()
if "gaia" in creator_l:
return "gaia"
if "onx" in creator_l:
return "onx"
head = raw_xml[:4096].lower()
if "onxmaps.com" in head:
return "onx"
if "topografix" in head and "gaia" in head:
return "gaia"
return "manual"
def parse_gpx(raw: bytes | str, filename: str | None = None) -> TrekkerRoute:
"""Parse GPX content into a segmented TrekkerRoute."""
text = raw.decode("utf-8", errors="replace") if isinstance(raw, bytes) else raw
gpx = gpxpy.parse(text)
points: list[TrkPt] = []
for track in gpx.tracks:
for seg in track.segments:
for p in seg.points:
points.append(
TrkPt(
lat=p.latitude,
lon=p.longitude,
ele=p.elevation,
time=p.time.isoformat() if p.time else None,
)
)
# Some apps export planned routes as <rte> instead of <trk>
if not points:
for rte in gpx.routes:
for p in rte.points:
points.append(
TrkPt(
lat=p.latitude,
lon=p.longitude,
ele=p.elevation,
time=p.time.isoformat() if p.time else None,
)
)
waypoints = [
Wpt(
lat=w.latitude,
lon=w.longitude,
ele=w.elevation,
time=w.time.isoformat() if w.time else None,
name=w.name,
desc=w.description,
sym=w.symbol,
type=w.type,
)
for w in gpx.waypoints
]
name = None
if gpx.name:
name = gpx.name
elif gpx.tracks and gpx.tracks[0].name:
name = gpx.tracks[0].name
elif filename:
name = filename.rsplit("/", 1)[-1].removesuffix(".gpx")
route = TrekkerRoute(
name=name or "Unnamed route",
source=detect_source(gpx.creator, text),
points=points,
waypoints=waypoints,
metadata={
"creator": gpx.creator,
"description": gpx.description,
"filename": filename,
},
)
route.segments = build_segments(route)
route.stats = compute_stats(route)
return route
+147
View File
@@ -0,0 +1,147 @@
"""Waypoint-driven segmentation and per-segment grade/elevation analysis."""
from __future__ import annotations
import math
from datetime import datetime
from app.models.route import RouteStats, Segment, TrekkerRoute, TrkPt, Wpt
EARTH_RADIUS_M = 6371000.0
# Minimum run between points used for grade math, to keep GPS jitter from
# producing absurd instantaneous grades.
MIN_GRADE_RUN_M = 10.0
# Waypoints farther than this from the track don't define segment boundaries.
MAX_WPT_SNAP_M = 200.0
def haversine_m(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
phi1, phi2 = math.radians(lat1), math.radians(lat2)
dphi = math.radians(lat2 - lat1)
dlmb = math.radians(lon2 - lon1)
a = math.sin(dphi / 2) ** 2 + math.cos(phi1) * math.cos(phi2) * math.sin(dlmb / 2) ** 2
return 2 * EARTH_RADIUS_M * math.asin(math.sqrt(a))
def _nearest_point_idx(points: list[TrkPt], wpt: Wpt) -> tuple[int, float]:
best_i, best_d = 0, float("inf")
for i, p in enumerate(points):
d = haversine_m(p.lat, p.lon, wpt.lat, wpt.lon)
if d < best_d:
best_i, best_d = i, d
return best_i, best_d
def _parse_time(t: str | None) -> datetime | None:
if not t:
return None
try:
return datetime.fromisoformat(t)
except ValueError:
return None
def _analyze(points: list[TrkPt], start: int, end: int) -> dict:
"""Distance, gain/loss, grades and duration over points[start..end]."""
dist = gain = loss = 0.0
max_grade = 0.0
# accumulate run since last grade sample to smooth jitter
run_acc = 0.0
ele_anchor: float | None = None
for i in range(start, end):
a, b = points[i], points[i + 1]
d = haversine_m(a.lat, a.lon, b.lat, b.lon)
dist += d
if a.ele is not None and b.ele is not None:
de = b.ele - a.ele
if de >= 0:
gain += de
else:
loss -= de
if ele_anchor is None:
ele_anchor = a.ele
run_acc += d
if run_acc >= MIN_GRADE_RUN_M:
grade = abs(b.ele - ele_anchor) / run_acc * 100.0
max_grade = max(max_grade, grade)
run_acc = 0.0
ele_anchor = b.ele
eles = [p.ele for p in points[start : end + 1] if p.ele is not None]
avg_grade = 0.0
if dist > 0 and len(eles) >= 2:
avg_grade = (eles[-1] - eles[0]) / dist * 100.0
t0 = _parse_time(points[start].time)
t1 = _parse_time(points[end].time)
duration = (t1 - t0).total_seconds() if t0 and t1 and t1 > t0 else None
return {
"distance_m": round(dist, 1),
"elevation_gain_m": round(gain, 1),
"elevation_loss_m": round(loss, 1),
"grade_pct_avg": round(avg_grade, 2),
"grade_pct_max": round(max_grade, 2),
"duration_s": duration,
}
def build_segments(route: TrekkerRoute) -> list[Segment]:
"""Named waypoints define segment boundaries. No waypoints -> one segment."""
points = route.points
if len(points) < 2:
return []
# Snap named waypoints onto the track, keep those reasonably close to it.
boundaries: list[tuple[int, str]] = []
for w in route.waypoints:
if not w.name:
continue
idx, dist = _nearest_point_idx(points, w)
if dist <= MAX_WPT_SNAP_M:
boundaries.append((idx, w.name))
boundaries.sort(key=lambda b: b[0])
# Build cut indices: start, interior waypoint snaps, end (deduplicated).
cuts: list[tuple[int, str | None]] = [(0, None)]
for idx, name in boundaries:
if 0 < idx < len(points) - 1 and idx != cuts[-1][0]:
cuts.append((idx, name))
elif idx == 0:
cuts[0] = (0, name)
end_name = next((n for i, n in boundaries if i == len(points) - 1), None)
cuts.append((len(points) - 1, end_name))
segments: list[Segment] = []
for si in range(len(cuts) - 1):
(s_idx, s_name), (e_idx, e_name) = cuts[si], cuts[si + 1]
stats = _analyze(points, s_idx, e_idx)
label = f"{s_name or 'Start'} → {e_name or 'End'}" if len(cuts) > 2 else route.name
segments.append(
Segment(
index=si,
name=label,
start_wpt=s_name,
end_wpt=e_name,
start_idx=s_idx,
end_idx=e_idx,
**stats,
)
)
return segments
def compute_stats(route: TrekkerRoute) -> RouteStats:
points = route.points
if len(points) < 2:
return RouteStats()
whole = _analyze(points, 0, len(points) - 1)
eles = [p.ele for p in points if p.ele is not None]
return RouteStats(
distance_m=whole["distance_m"],
elevation_gain_m=whole["elevation_gain_m"],
elevation_loss_m=whole["elevation_loss_m"],
elevation_min_m=min(eles) if eles else None,
elevation_max_m=max(eles) if eles else None,
duration_s=whole["duration_s"],
)
+78
View File
@@ -0,0 +1,78 @@
"""Folder watch: ingest .gpx files dropped into the configured directories.
Internal path uses inotify-backed Observer; remote path (SMB/Nextcloud/USB
mounts, where inotify is unreliable) uses PollingObserver per PLAN.md 1e.
"""
from __future__ import annotations
import logging
import time
from pathlib import Path
from watchdog.events import FileSystemEvent, FileSystemEventHandler
from watchdog.observers import Observer
from watchdog.observers.polling import PollingObserver
from app.ingest.gpx_parser import parse_gpx
from app.storage.route_store import Store
log = logging.getLogger("trekker.watchdog")
class GpxHandler(FileSystemEventHandler):
def __init__(self, store: Store):
self.store = store
def on_created(self, event: FileSystemEvent) -> None:
if event.is_directory or not str(event.src_path).lower().endswith(".gpx"):
return
self._ingest(Path(str(event.src_path)))
def on_moved(self, event: FileSystemEvent) -> None:
dest = getattr(event, "dest_path", None)
if dest and str(dest).lower().endswith(".gpx"):
self._ingest(Path(str(dest)))
def _ingest(self, path: Path) -> None:
# Wait for the writer to finish (size stable across two checks).
try:
last = -1
for _ in range(20):
size = path.stat().st_size
if size == last and size > 0:
break
last = size
time.sleep(0.5)
route = parse_gpx(path.read_bytes(), filename=path.name)
self.store.save_route(route)
log.info("ingested %s as route %s (%s)", path.name, route.id, route.source)
except Exception:
log.exception("failed to ingest %s", path)
class WatchdogDaemon:
def __init__(self, store: Store, internal_path: str | None,
remote_path: str | None, poll_interval: int = 30):
self.observers = []
handler = GpxHandler(store)
if internal_path:
Path(internal_path).mkdir(parents=True, exist_ok=True)
obs = Observer()
obs.schedule(handler, internal_path, recursive=True)
self.observers.append(obs)
if remote_path and Path(remote_path).is_dir():
obs = PollingObserver(timeout=poll_interval)
obs.schedule(handler, remote_path, recursive=True)
self.observers.append(obs)
def start(self) -> None:
for obs in self.observers:
obs.start()
if self.observers:
log.info("watchdog started (%d observers)", len(self.observers))
def stop(self) -> None:
for obs in self.observers:
obs.stop()
obs.join(timeout=5)
+86
View File
@@ -0,0 +1,86 @@
"""Trekker FastAPI entry point."""
from __future__ import annotations
import logging
from contextlib import asynccontextmanager
from pathlib import Path
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles
from app.config import settings
from app.deps import get_store
from app.ingest.watchdog_daemon import WatchdogDaemon
from app.routes import export, offline_maps, sync, trails, upload, weather
logging.basicConfig(level=logging.INFO)
UI_DIR = Path(__file__).resolve().parent.parent / "ui"
@asynccontextmanager
async def lifespan(app: FastAPI):
daemon = WatchdogDaemon(
get_store(),
settings.watch.internal_path,
settings.watch.remote_path,
settings.watch.poll_interval,
)
daemon.start()
yield
daemon.stop()
app = FastAPI(title="Trekker", version="0.1.0", lifespan=lifespan)
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
app.include_router(upload.router)
app.include_router(trails.router)
app.include_router(weather.router)
app.include_router(export.router)
app.include_router(offline_maps.router)
app.include_router(sync.router)
@app.get("/api/health")
def health():
return {"status": "ok", "version": app.version, "host_role": settings.host_role}
@app.get("/api/config")
def public_config():
"""Non-secret config the UI needs."""
return {
"host_role": settings.host_role,
"tiles_base_url": settings.tiles.base_url,
"tiles_terrain_url": settings.tiles.terrain_url,
"max_pack_tiles": settings.tiles.max_pack_tiles,
"sync_peer_configured": bool(settings.sync.peer_url),
"llm_configured": bool(settings.llm.api_key or settings.llm.base_url),
"watch": {
"internal_path": settings.watch.internal_path,
"remote_path": settings.watch.remote_path,
},
}
if UI_DIR.is_dir():
app.mount("/app/static", StaticFiles(directory=UI_DIR), name="ui")
@app.get("/app")
@app.get("/app/{path:path}")
def spa(path: str = ""):
return FileResponse(UI_DIR / "index.html")
@app.get("/")
def root():
return FileResponse(UI_DIR / "index.html")
View File
Whitespace-only changes.
+17
View File
@@ -0,0 +1,17 @@
"""Generated asset model: structured JSON output from generators."""
from __future__ import annotations
from typing import Any
from pydantic import BaseModel, Field
from app.models.route import new_id, utcnow_iso
class Asset(BaseModel):
id: str = Field(default_factory=new_id)
route_id: str
generator: str
data: dict[str, Any] = Field(default_factory=dict)
created_at: str = Field(default_factory=utcnow_iso)
+26
View File
@@ -0,0 +1,26 @@
"""Offline map pack metadata."""
from __future__ import annotations
from typing import Optional
from pydantic import BaseModel, Field
from app.models.route import new_id, utcnow_iso
class MapPack(BaseModel):
id: str = Field(default_factory=new_id)
name: str = "Offline area"
bbox: list[float] = Field(default_factory=list) # [min_lon, min_lat, max_lon, max_lat]
min_zoom: int = 8
max_zoom: int = 14
layers: list[str] = Field(default_factory=lambda: ["base"])
status: str = "queued" # queued | downloading | ready | failed
error: Optional[str] = None
path: Optional[str] = None
size_bytes: int = 0
tile_count: int = 0
tiles_done: int = 0
created_at: str = Field(default_factory=utcnow_iso)
updated_at: str = Field(default_factory=utcnow_iso)
+81
View File
@@ -0,0 +1,81 @@
"""Canonical route models: TrekkerRoute and its sub-models."""
from __future__ import annotations
import uuid
from datetime import datetime, timezone
from typing import Any, Optional
from pydantic import BaseModel, Field
def utcnow_iso() -> str:
return datetime.now(timezone.utc).isoformat()
def new_id() -> str:
return uuid.uuid4().hex
class TrkPt(BaseModel):
lat: float
lon: float
ele: Optional[float] = None
time: Optional[str] = None # ISO 8601
class Wpt(BaseModel):
lat: float
lon: float
ele: Optional[float] = None
time: Optional[str] = None
name: Optional[str] = None
desc: Optional[str] = None
sym: Optional[str] = None
type: Optional[str] = None
class Segment(BaseModel):
index: int
name: str
start_wpt: Optional[str] = None
end_wpt: Optional[str] = None
start_idx: int
end_idx: int # inclusive index into route.points
distance_m: float = 0.0
elevation_gain_m: float = 0.0
elevation_loss_m: float = 0.0
grade_pct_avg: float = 0.0
grade_pct_max: float = 0.0
duration_s: Optional[float] = None
class RouteStats(BaseModel):
distance_m: float = 0.0
elevation_gain_m: float = 0.0
elevation_loss_m: float = 0.0
elevation_min_m: Optional[float] = None
elevation_max_m: Optional[float] = None
duration_s: Optional[float] = None
class TrekkerRoute(BaseModel):
id: str = Field(default_factory=new_id)
name: str = "Unnamed route"
source: str = "manual" # gaia | onx | manual
trail_guide_id: Optional[str] = None
points: list[TrkPt] = Field(default_factory=list)
waypoints: list[Wpt] = Field(default_factory=list)
segments: list[Segment] = Field(default_factory=list)
stats: RouteStats = Field(default_factory=RouteStats)
metadata: dict[str, Any] = Field(default_factory=dict)
created_at: str = Field(default_factory=utcnow_iso)
updated_at: str = Field(default_factory=utcnow_iso)
def bounds(self) -> Optional[tuple[float, float, float, float]]:
"""(min_lon, min_lat, max_lon, max_lat) or None for empty routes."""
if not self.points:
return None
lats = [p.lat for p in self.points]
lons = [p.lon for p in self.points]
return (min(lons), min(lats), max(lons), max(lats))
+34
View File
@@ -0,0 +1,34 @@
"""TrailGuide: curated trail knowledge, separate from raw GPS routes."""
from __future__ import annotations
from typing import Optional
from pydantic import BaseModel, Field
from app.models.route import new_id, utcnow_iso
class WaterCrossing(BaseModel):
name: Optional[str] = None
depth_ft: Optional[float] = None
notes: Optional[str] = None
class TrailGuide(BaseModel):
id: str = Field(default_factory=new_id)
name: str = "Unnamed trail guide"
source: str = "manual" # web | pdf | manual
source_url: Optional[str] = None
pdf_path: Optional[str] = None
difficulty: Optional[str] = None
obstacle_types: list[str] = Field(default_factory=list)
water_crossings: list[WaterCrossing] = Field(default_factory=list)
gate_codes: list[str] = Field(default_factory=list)
vehicle_recommendations: list[str] = Field(default_factory=list)
closures: list[str] = Field(default_factory=list)
warnings: list[str] = Field(default_factory=list)
notes: Optional[str] = None
raw_text: Optional[str] = None # extracted source text kept for re-review
created_at: str = Field(default_factory=utcnow_iso)
updated_at: str = Field(default_factory=utcnow_iso)
+23
View File
@@ -0,0 +1,23 @@
"""Trip: a collection of routes with travelers and a date range."""
from __future__ import annotations
from typing import Any, Optional
from pydantic import BaseModel, Field
from app.models.route import new_id, utcnow_iso
class Trip(BaseModel):
id: str = Field(default_factory=new_id)
name: str = "Unnamed trip"
route_ids: list[str] = Field(default_factory=list)
travelers: list[str] = Field(default_factory=list)
date_start: Optional[str] = None
date_end: Optional[str] = None
notes: Optional[str] = None
generated_asset_ids: list[str] = Field(default_factory=list)
metadata: dict[str, Any] = Field(default_factory=dict)
created_at: str = Field(default_factory=utcnow_iso)
updated_at: str = Field(default_factory=utcnow_iso)
View File
Whitespace-only changes.
+32
View File
@@ -0,0 +1,32 @@
"""Export API: enriched GPX / KML downloads."""
from __future__ import annotations
import re
from fastapi import APIRouter, HTTPException, Query
from fastapi.responses import Response
from app.deps import get_store
from app.export.gpx_writer import write_gpx
from app.export.kml_writer import write_kml
router = APIRouter(prefix="/api/routes", tags=["export"])
@router.get("/{route_id}/export")
def export_route(route_id: str, format: str = Query("gpx", pattern="^(gpx|kml)$")):
store = get_store()
route = store.get_route(route_id)
if route is None:
raise HTTPException(404, "route not found")
guide = store.get_trail_guide(route.trail_guide_id) if route.trail_guide_id else None
safe_name = re.sub(r"[^A-Za-z0-9_-]+", "_", route.name).strip("_") or "route"
if format == "gpx":
body, media = write_gpx(route, guide), "application/gpx+xml"
else:
body, media = write_kml(route, guide), "application/vnd.google-earth.kml+xml"
return Response(
content=body, media_type=media,
headers={"Content-Disposition": f'attachment; filename="{safe_name}.{format}"'},
)
+71
View File
@@ -0,0 +1,71 @@
"""Offline map pack API: estimate, create, list, status, delete, tile serving."""
from __future__ import annotations
from fastapi import APIRouter, HTTPException
from fastapi.responses import FileResponse
from pydantic import BaseModel, Field
from app.deps import get_offline_maps, get_store
from app.services.offline_maps import estimate_tile_count
router = APIRouter(prefix="/api/offline-maps", tags=["offline-maps"])
AVG_TILE_BYTES = 25_000 # rough raster tile size for the pre-download estimate
class PackBody(BaseModel):
name: str = "Offline area"
bbox: list[float] = Field(min_length=4, max_length=4) # [min_lon, min_lat, max_lon, max_lat]
min_zoom: int = Field(8, ge=0, le=16)
max_zoom: int = Field(14, ge=0, le=16)
layers: list[str] = Field(default_factory=lambda: ["base", "terrain"])
@router.post("/estimate")
def estimate(body: PackBody):
if body.max_zoom < body.min_zoom:
raise HTTPException(400, "max_zoom must be >= min_zoom")
count = estimate_tile_count(body.bbox, body.min_zoom, body.max_zoom) * len(body.layers)
return {"tile_count": count, "estimated_bytes": count * AVG_TILE_BYTES}
@router.post("")
def create_pack(body: PackBody):
if body.max_zoom < body.min_zoom:
raise HTTPException(400, "max_zoom must be >= min_zoom")
try:
return get_offline_maps().create_pack(
body.name, body.bbox, body.min_zoom, body.max_zoom, body.layers
)
except ValueError as e:
raise HTTPException(400, str(e))
@router.get("")
def list_packs():
return get_store().list_map_packs()
@router.get("/{pack_id}")
def get_pack(pack_id: str):
pack = get_store().get_map_pack(pack_id)
if pack is None:
raise HTTPException(404, "map pack not found")
return pack
@router.delete("/{pack_id}")
def delete_pack(pack_id: str):
if not get_offline_maps().delete_pack(pack_id):
raise HTTPException(404, "map pack not found")
return {"deleted": pack_id}
@router.get("/tiles/{layer}/{z}/{x}/{y}.png")
def serve_tile(layer: str, z: int, x: int, y: int):
"""Serve a tile from any ready pack (the UI's offline tile source)."""
path = get_offline_maps().find_tile(layer, z, x, y)
if path is None:
raise HTTPException(404, "tile not in any offline pack")
return FileResponse(path, media_type="image/png")
+37
View File
@@ -0,0 +1,37 @@
"""Sync API: manual trigger + bundle exchange endpoints (PLAN.md Phase 7)."""
from __future__ import annotations
from fastapi import APIRouter, HTTPException
from pydantic import BaseModel
from app.config import settings
from app.deps import get_store
from app.sync.sync_daemon import build_bundle, merge_bundle, sync_with_peer
router = APIRouter(prefix="/api/sync", tags=["sync"])
@router.get("/bundle")
def get_bundle():
return build_bundle(get_store())
@router.post("/bundle")
def post_bundle(bundle: dict):
return {"applied": merge_bundle(get_store(), bundle)}
class SyncBody(BaseModel):
peer_url: str | None = None
@router.post("")
def trigger_sync(body: SyncBody | None = None):
peer = (body.peer_url if body else None) or settings.sync.peer_url
if not peer:
raise HTTPException(400, "no peer_url given and sync.peer_url not configured")
try:
return sync_with_peer(get_store(), peer)
except Exception as e:
raise HTTPException(502, f"sync with {peer} failed: {e}")
+83
View File
@@ -0,0 +1,83 @@
"""Trail guide API: scrape, PDF extraction (drafts), review/save, CRUD."""
from __future__ import annotations
from pathlib import Path
from fastapi import APIRouter, HTTPException, UploadFile
from pydantic import BaseModel
from pypdf import PdfReader
from app.config import settings
from app.deps import get_llm, get_store
from app.models.trail_guide import TrailGuide
from app.services.scraper import guide_from_extraction, scrape_trail_guide
router = APIRouter(prefix="/api/trails", tags=["trails"])
class ScrapeBody(BaseModel):
url: str
@router.post("/scrape")
def scrape(body: ScrapeBody) -> TrailGuide:
"""Returns a DRAFT guide for review; client saves it via POST /api/trails."""
try:
return scrape_trail_guide(body.url, get_llm())
except Exception as e:
raise HTTPException(502, f"scrape failed: {e}")
@router.post("/upload-pdf")
async def upload_pdf(file: UploadFile) -> TrailGuide:
"""PDF -> pypdf text -> LLM extraction -> DRAFT guide for review."""
if not (file.filename or "").lower().endswith(".pdf"):
raise HTTPException(400, "expected a .pdf file")
raw = await file.read()
pdf_dir = Path(settings.pdf_dir)
pdf_dir.mkdir(parents=True, exist_ok=True)
pdf_path = pdf_dir / Path(file.filename).name
pdf_path.write_bytes(raw)
try:
reader = PdfReader(str(pdf_path))
text = "\n".join((page.extract_text() or "") for page in reader.pages)
except Exception as e:
raise HTTPException(400, f"could not read PDF: {e}")
llm = get_llm()
extracted: dict = {}
if llm.configured and text.strip():
try:
extracted = llm.extract_trail_data(text)
except Exception:
pass # user reviews from raw text instead
return guide_from_extraction(
extracted, source="pdf", pdf_path=str(pdf_path),
raw_text=text[:50000], fallback_name=Path(file.filename).stem,
)
@router.post("")
def save_guide(guide: TrailGuide) -> TrailGuide:
"""Save a reviewed/edited guide (the manual-review confirmation step)."""
return get_store().save_trail_guide(guide)
@router.get("")
def list_guides():
return get_store().list_trail_guides()
@router.get("/{guide_id}")
def get_guide(guide_id: str) -> TrailGuide:
guide = get_store().get_trail_guide(guide_id)
if guide is None:
raise HTTPException(404, "trail guide not found")
return guide
@router.delete("/{guide_id}")
def delete_guide(guide_id: str):
if not get_store().delete_trail_guide(guide_id):
raise HTTPException(404, "trail guide not found")
return {"deleted": guide_id}
+98
View File
@@ -0,0 +1,98 @@
"""Route API: upload, list, get, delete, trail-guide linking, generators."""
from __future__ import annotations
from fastapi import APIRouter, HTTPException, UploadFile
from pydantic import BaseModel
from app.deps import get_elevation, get_store
from app.generators import GENERATORS, GeneratorError
from app.ingest.gpx_parser import parse_gpx
from app.ingest.segmenter import build_segments, compute_stats
router = APIRouter(prefix="/api/routes", tags=["routes"])
@router.post("/upload")
async def upload_gpx(file: UploadFile):
if not (file.filename or "").lower().endswith(".gpx"):
raise HTTPException(400, "expected a .gpx file")
raw = await file.read()
try:
route = parse_gpx(raw, filename=file.filename)
except Exception as e:
raise HTTPException(400, f"could not parse GPX: {e}")
if not route.points:
raise HTTPException(400, "GPX contains no track or route points")
# Fill elevations from terrain tiles when the exporting app omitted them.
if any(p.ele is None for p in route.points):
try:
if get_elevation().fill_missing_elevations(route.points):
route.segments = build_segments(route)
route.stats = compute_stats(route)
except Exception:
pass # offline or tiles unavailable; elevation stays absent
return get_store().save_route(route)
@router.get("")
def list_routes():
return [
{"id": r.id, "name": r.name, "source": r.source,
"trail_guide_id": r.trail_guide_id, "stats": r.stats,
"bounds": r.bounds(), "created_at": r.created_at}
for r in get_store().list_routes()
]
@router.get("/{route_id}")
def get_route(route_id: str):
route = get_store().get_route(route_id)
if route is None:
raise HTTPException(404, "route not found")
return route
@router.delete("/{route_id}")
def delete_route(route_id: str):
if not get_store().delete_route(route_id):
raise HTTPException(404, "route not found")
return {"deleted": route_id}
class LinkBody(BaseModel):
trail_guide_id: str | None = None
@router.put("/{route_id}/trail-guide")
def link_trail_guide(route_id: str, body: LinkBody):
try:
route = get_store().link_trail_guide(route_id, body.trail_guide_id)
except KeyError as e:
raise HTTPException(404, str(e))
if route is None:
raise HTTPException(404, "route not found")
return route
@router.post("/{route_id}/generate/{generator_name}")
def generate_asset(route_id: str, generator_name: str):
store = get_store()
route = store.get_route(route_id)
if route is None:
raise HTTPException(404, "route not found")
gen_cls = GENERATORS.get(generator_name)
if gen_cls is None:
raise HTTPException(404, f"unknown generator; available: {sorted(GENERATORS)}")
guide = store.get_trail_guide(route.trail_guide_id) if route.trail_guide_id else None
weather = store.get_weather(route_id)
try:
asset = gen_cls().generate(route, guide, weather)
except GeneratorError as e:
raise HTTPException(409, str(e))
return store.save_asset(asset)
@router.get("/{route_id}/assets")
def list_assets(route_id: str):
return get_store().list_assets(route_id)
+34
View File
@@ -0,0 +1,34 @@
"""Weather API: manual refresh + cached read (PLAN.md 4c: no auto-refetch)."""
from __future__ import annotations
from fastapi import APIRouter, HTTPException, Query
from app.deps import get_store
from app.services.weather import fetch_route_weather
router = APIRouter(prefix="/api/routes", tags=["weather"])
@router.post("/{route_id}/refresh-weather")
def refresh_weather(route_id: str, days: int = Query(7)):
store = get_store()
route = store.get_route(route_id)
if route is None:
raise HTTPException(404, "route not found")
if days not in (7, 10):
raise HTTPException(400, "days must be 7 or 10")
try:
weather = fetch_route_weather(route, days)
except Exception as e:
raise HTTPException(502, f"weather fetch failed: {e}")
store.save_weather(route_id, weather)
return store.get_weather(route_id)
@router.get("/{route_id}/weather")
def get_weather(route_id: str):
weather = get_store().get_weather(route_id)
if weather is None:
raise HTTPException(404, "no cached weather; refresh first")
return weather
View File
Whitespace-only changes.
+82
View File
@@ -0,0 +1,82 @@
"""Elevation lookup from Terrarium-encoded terrain tiles (AWS Open Data).
decode: elevation_m = (R * 256 + G + B / 256) - 32768
Tiles are cached on disk under data_dir/terrain so offline packs and the
segmenter share the same cache.
"""
from __future__ import annotations
import io
import logging
import math
from pathlib import Path
import httpx
from PIL import Image
from app.config import settings
from app.models.route import TrkPt
log = logging.getLogger("trekker.elevation")
TILE_SIZE = 256
DEFAULT_ZOOM = 12
def lonlat_to_tile(lon: float, lat: float, zoom: int) -> tuple[int, int, float, float]:
"""Tile x/y plus fractional pixel offset within the tile."""
n = 2**zoom
xf = (lon + 180.0) / 360.0 * n
lat_r = math.radians(lat)
yf = (1.0 - math.asinh(math.tan(lat_r)) / math.pi) / 2.0 * n
x, y = int(xf), int(yf)
return x, y, (xf - x) * TILE_SIZE, (yf - y) * TILE_SIZE
class ElevationService:
def __init__(self, cache_dir: str | None = None, terrain_url: str | None = None):
self.terrain_url = terrain_url or settings.tiles.terrain_url
self.cache_dir = Path(cache_dir or Path(settings.data_dir) / "terrain")
self._mem: dict[tuple[int, int, int], Image.Image] = {}
def _tile(self, z: int, x: int, y: int) -> Image.Image | None:
key = (z, x, y)
if key in self._mem:
return self._mem[key]
path = self.cache_dir / str(z) / str(x) / f"{y}.png"
if not path.is_file():
url = self.terrain_url.format(z=z, x=x, y=y)
try:
resp = httpx.get(url, timeout=30,
headers={"User-Agent": settings.tiles.user_agent})
resp.raise_for_status()
except httpx.HTTPError as e:
log.warning("terrain tile %s/%s/%s fetch failed: %s", z, x, y, e)
return None
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(resp.content)
img = Image.open(io.BytesIO(path.read_bytes())).convert("RGB")
if len(self._mem) > 64:
self._mem.clear()
self._mem[key] = img
return img
def elevation_at(self, lat: float, lon: float, zoom: int = DEFAULT_ZOOM) -> float | None:
x, y, px, py = lonlat_to_tile(lon, lat, zoom)
img = self._tile(zoom, x, y)
if img is None:
return None
r, g, b = img.getpixel((min(int(px), TILE_SIZE - 1), min(int(py), TILE_SIZE - 1)))[:3]
return (r * 256 + g + b / 256) - 32768
def fill_missing_elevations(self, points: list[TrkPt], zoom: int = DEFAULT_ZOOM) -> int:
"""Populate ele on points lacking it. Returns count filled."""
filled = 0
for p in points:
if p.ele is None:
ele = self.elevation_at(p.lat, p.lon, zoom)
if ele is not None:
p.ele = round(ele, 1)
filled += 1
return filled
+76
View File
@@ -0,0 +1,76 @@
"""OpenAI-compatible LLM adapter for trail guide extraction.
Works with any OpenAI-compatible endpoint (Ollama, Groq, Gemini, OpenAI)
via configurable base_url / model / api_key.
"""
from __future__ import annotations
import json
import logging
from typing import Any
from openai import OpenAI
from app.config import LLMConfig
log = logging.getLogger("trekker.llm")
EXTRACTION_PROMPT = """You extract structured overland trail data from text.
Return ONLY a JSON object with these keys (use null/[] when not mentioned):
{
"name": string,
"difficulty": string|null, // e.g. "easy", "moderate", "difficult", "extreme", or a rating like "7/10"
"obstacle_types": [string], // e.g. "rock garden", "ledges", "mud", "off-camber"
"water_crossings": [{"name": string|null, "depth_ft": number|null, "notes": string|null}],
"gate_codes": [string],
"vehicle_recommendations": [string],// e.g. "33-inch tires", "lockers recommended", "winch"
"closures": [string], // seasonal or permanent closure notes
"warnings": [string],
"notes": string|null
}"""
class LLMService:
def __init__(self, config: LLMConfig):
self.config = config
@property
def configured(self) -> bool:
return bool(self.config.api_key or self.config.base_url)
def _client(self) -> OpenAI:
return OpenAI(
base_url=self.config.base_url or None,
api_key=self.config.api_key or "not-needed", # local providers ignore the key
)
def extract_trail_data(self, text: str) -> dict[str, Any]:
"""Trail guide text -> structured dict. Raises on provider errors."""
client = self._client()
# Keep prompts inside small local-model context windows.
snippet = text[:24000]
kwargs: dict[str, Any] = {
"model": self.config.model,
"messages": [
{"role": "system", "content": EXTRACTION_PROMPT},
{"role": "user", "content": snippet},
],
}
try:
resp = client.chat.completions.create(
**kwargs, response_format={"type": "json_object"}
)
except Exception:
# Some providers reject response_format; retry without it.
resp = client.chat.completions.create(**kwargs)
content = resp.choices[0].message.content or "{}"
# Tolerate code-fenced JSON from smaller models.
content = content.strip()
if content.startswith("```"):
content = content.strip("`")
content = content.split("\n", 1)[1] if "\n" in content else content
start, end = content.find("{"), content.rfind("}")
if start != -1 and end > start:
content = content[start : end + 1]
return json.loads(content)
+136
View File
@@ -0,0 +1,136 @@
"""Offline map packs: estimate, download, and serve XYZ tiles locally.
Tiles are stored under data/offline_maps/{pack_id}/{layer}/{z}/{x}/{y}.png.
Downloads run in a background thread and update pack status in SQLite.
A per-pack tile cap (settings.tiles.max_pack_tiles) keeps usage within
tile-provider policies; see PLAN.md Phase 2 gate notes.
"""
from __future__ import annotations
import logging
import math
import shutil
import threading
import time
from pathlib import Path
import httpx
from app.config import settings
from app.models.map_pack import MapPack
from app.storage.route_store import Store
log = logging.getLogger("trekker.offline_maps")
LAYER_URLS = {
"base": lambda: settings.tiles.base_url,
"terrain": lambda: settings.tiles.terrain_url,
}
def _tile_range(bbox: list[float], zoom: int) -> tuple[int, int, int, int]:
"""(x_min, x_max, y_min, y_max) tile indices covering bbox at zoom."""
min_lon, min_lat, max_lon, max_lat = bbox
n = 2**zoom
def x_of(lon: float) -> int:
return min(n - 1, max(0, int((lon + 180.0) / 360.0 * n)))
def y_of(lat: float) -> int:
lat = max(-85.05112878, min(85.05112878, lat))
lat_r = math.radians(lat)
return min(n - 1, max(0, int((1.0 - math.asinh(math.tan(lat_r)) / math.pi) / 2.0 * n)))
return x_of(min_lon), x_of(max_lon), y_of(max_lat), y_of(min_lat)
def iter_tiles(bbox: list[float], min_zoom: int, max_zoom: int):
for z in range(min_zoom, max_zoom + 1):
x0, x1, y0, y1 = _tile_range(bbox, z)
for x in range(x0, x1 + 1):
for y in range(y0, y1 + 1):
yield z, x, y
def estimate_tile_count(bbox: list[float], min_zoom: int, max_zoom: int) -> int:
total = 0
for z in range(min_zoom, max_zoom + 1):
x0, x1, y0, y1 = _tile_range(bbox, z)
total += (x1 - x0 + 1) * (y1 - y0 + 1)
return total
class OfflineMapService:
def __init__(self, store: Store, base_dir: str | None = None):
self.store = store
self.base_dir = Path(base_dir or settings.offline_maps_dir)
def pack_dir(self, pack_id: str) -> Path:
return self.base_dir / pack_id
def create_pack(self, name: str, bbox: list[float], min_zoom: int,
max_zoom: int, layers: list[str]) -> MapPack:
layers = [l for l in layers if l in LAYER_URLS] or ["base"]
count = estimate_tile_count(bbox, min_zoom, max_zoom) * len(layers)
if count > settings.tiles.max_pack_tiles:
raise ValueError(
f"pack would need {count} tiles, over the cap of "
f"{settings.tiles.max_pack_tiles}; shrink the area or zoom range"
)
pack = MapPack(name=name, bbox=bbox, min_zoom=min_zoom, max_zoom=max_zoom,
layers=layers, status="queued", tile_count=count)
pack.path = str(self.pack_dir(pack.id))
self.store.save_map_pack(pack)
threading.Thread(target=self._download, args=(pack.id,), daemon=True).start()
return pack
def _download(self, pack_id: str) -> None:
pack = self.store.get_map_pack(pack_id)
if pack is None:
return
pack.status = "downloading"
self.store.save_map_pack(pack)
size = 0
done = 0
try:
with httpx.Client(timeout=30, headers={"User-Agent": settings.tiles.user_agent}) as client:
for layer in pack.layers:
url_tpl = LAYER_URLS[layer]()
for z, x, y in iter_tiles(pack.bbox, pack.min_zoom, pack.max_zoom):
dest = self.pack_dir(pack.id) / layer / str(z) / str(x) / f"{y}.png"
if not dest.is_file():
resp = client.get(url_tpl.format(z=z, x=x, y=y))
resp.raise_for_status()
dest.parent.mkdir(parents=True, exist_ok=True)
dest.write_bytes(resp.content)
time.sleep(0.05) # be polite to public tile servers
size += dest.stat().st_size
done += 1
if done % 50 == 0:
pack.tiles_done, pack.size_bytes = done, size
self.store.save_map_pack(pack)
pack.tiles_done, pack.size_bytes, pack.status = done, size, "ready"
except Exception as e:
log.exception("pack %s download failed", pack_id)
pack.status, pack.error = "failed", str(e)
self.store.save_map_pack(pack)
def tile_path(self, pack_id: str, layer: str, z: int, x: int, y: int) -> Path | None:
p = self.pack_dir(pack_id) / layer / str(z) / str(x) / f"{y}.png"
return p if p.is_file() else None
def find_tile(self, layer: str, z: int, x: int, y: int) -> Path | None:
"""Search all ready packs for a tile (offline fallback serving)."""
for pack in self.store.list_map_packs():
if pack.status != "ready":
continue
p = self.tile_path(pack.id, layer, z, x, y)
if p:
return p
return None
def delete_pack(self, pack_id: str) -> bool:
ok = self.store.delete_map_pack(pack_id)
shutil.rmtree(self.pack_dir(pack_id), ignore_errors=True)
return ok
+70
View File
@@ -0,0 +1,70 @@
"""Trail guide web scrape: URL -> page text -> draft TrailGuide.
Uses httpx + BeautifulSoup. If an LLM is configured the text is run through
structured extraction; otherwise the user fills the review form from raw text.
"""
from __future__ import annotations
import logging
import httpx
from bs4 import BeautifulSoup
from app.models.trail_guide import TrailGuide, WaterCrossing
from app.services.llm import LLMService
log = logging.getLogger("trekker.scraper")
def fetch_page_text(url: str) -> tuple[str, str]:
"""Returns (title, readable_text)."""
resp = httpx.get(url, timeout=30, follow_redirects=True,
headers={"User-Agent": "Trekker/0.1 trail guide fetch"})
resp.raise_for_status()
soup = BeautifulSoup(resp.text, "html.parser")
for tag in soup(["script", "style", "nav", "footer", "header", "noscript"]):
tag.decompose()
title = soup.title.get_text(strip=True) if soup.title else url
text = "\n".join(
line for line in (ln.strip() for ln in soup.get_text("\n").splitlines()) if line
)
return title, text
def guide_from_extraction(extracted: dict, *, source: str, source_url: str | None = None,
pdf_path: str | None = None, raw_text: str | None = None,
fallback_name: str = "Unnamed trail guide") -> TrailGuide:
crossings = [
WaterCrossing(**wc) if isinstance(wc, dict) else WaterCrossing(notes=str(wc))
for wc in extracted.get("water_crossings") or []
]
return TrailGuide(
name=extracted.get("name") or fallback_name,
source=source,
source_url=source_url,
pdf_path=pdf_path,
difficulty=extracted.get("difficulty"),
obstacle_types=[str(o) for o in extracted.get("obstacle_types") or []],
water_crossings=crossings,
gate_codes=[str(g) for g in extracted.get("gate_codes") or []],
vehicle_recommendations=[str(v) for v in extracted.get("vehicle_recommendations") or []],
closures=[str(c) for c in extracted.get("closures") or []],
warnings=[str(w) for w in extracted.get("warnings") or []],
notes=extracted.get("notes"),
raw_text=raw_text,
)
def scrape_trail_guide(url: str, llm: LLMService) -> TrailGuide:
title, text = fetch_page_text(url)
extracted: dict = {}
if llm.configured and text:
try:
extracted = llm.extract_trail_data(text)
except Exception:
log.exception("LLM extraction failed for %s; returning raw-text draft", url)
return guide_from_extraction(
extracted, source="web", source_url=url,
raw_text=text[:50000], fallback_name=title,
)
+110
View File
@@ -0,0 +1,110 @@
"""Open-Meteo client and per-segment aggregation into four tiers."""
from __future__ import annotations
from typing import Any
import httpx
from app.models.route import TrekkerRoute
API_URL = "https://api.open-meteo.com/v1/forecast"
HOURLY_VARS = "temperature_2m,precipitation_probability,precipitation,wind_speed_10m,wind_gusts_10m,weather_code"
DAILY_VARS = "temperature_2m_max,temperature_2m_min,precipitation_probability_max,precipitation_sum,wind_speed_10m_max,weather_code"
# Open-Meteo WMO codes indicating thunderstorms (lightning risk)
THUNDER_CODES = {95, 96, 99}
WIND_ADVISORY_KMH = 40.0
def fetch_forecast(lat: float, lon: float, days: int = 7) -> dict[str, Any]:
if days not in (7, 10):
raise ValueError("forecast window must be 7 or 10 days")
resp = httpx.get(
API_URL,
params={
"latitude": round(lat, 4),
"longitude": round(lon, 4),
"hourly": HOURLY_VARS,
"daily": DAILY_VARS,
"forecast_days": days,
"timezone": "auto",
"wind_speed_unit": "kmh",
"temperature_unit": "fahrenheit",
"precipitation_unit": "inch",
},
timeout=30,
)
resp.raise_for_status()
return resp.json()
def _chunk_hours(hourly: dict[str, list], hours_per_bucket: int) -> list[dict[str, Any]]:
times = hourly.get("time", [])
buckets = []
for start in range(0, len(times), hours_per_bucket):
end = min(start + hours_per_bucket, len(times))
sl = slice(start, end)
def vals(key: str) -> list[float]:
return [v for v in hourly.get(key, [])[sl] if v is not None]
temps = vals("temperature_2m")
winds = vals("wind_speed_10m")
codes = vals("weather_code")
precip_prob = vals("precipitation_probability")
buckets.append({
"time_start": times[start],
"time_end": times[end - 1],
"temp_min_f": min(temps) if temps else None,
"temp_max_f": max(temps) if temps else None,
"precip_prob_max": max(precip_prob) if precip_prob else None,
"precip_sum_in": round(sum(vals("precipitation")), 3),
"wind_max_kmh": max(winds) if winds else None,
"wind_advisory": bool(winds) and max(winds) >= WIND_ADVISORY_KMH,
"lightning_risk": any(int(c) in THUNDER_CODES for c in codes),
})
return buckets
def build_tiers(forecast: dict[str, Any]) -> dict[str, Any]:
"""Hourly / 6h / 12h / daily tiers from a raw Open-Meteo response."""
hourly = forecast.get("hourly", {})
daily = forecast.get("daily", {})
return {
"hourly": _chunk_hours(hourly, 1),
"6h": _chunk_hours(hourly, 6),
"12h": _chunk_hours(hourly, 12),
"daily": [
{
"date": daily["time"][i],
"temp_min_f": daily["temperature_2m_min"][i],
"temp_max_f": daily["temperature_2m_max"][i],
"precip_prob_max": daily["precipitation_probability_max"][i],
"precip_sum_in": daily["precipitation_sum"][i],
"wind_max_kmh": daily["wind_speed_10m_max"][i],
"lightning_risk": int(daily["weather_code"][i]) in THUNDER_CODES,
}
for i in range(len(daily.get("time", [])))
],
}
def segment_midpoints(route: TrekkerRoute) -> list[tuple[int, float, float]]:
out = []
for seg in route.segments:
mid = route.points[(seg.start_idx + seg.end_idx) // 2]
out.append((seg.index, mid.lat, mid.lon))
return out
def fetch_route_weather(route: TrekkerRoute, days: int = 7) -> dict[str, Any]:
"""Per-segment forecasts. Nearby midpoints share one fetch (0.05° grid)."""
cache: dict[tuple[float, float], dict] = {}
segments = {}
for idx, lat, lon in segment_midpoints(route):
key = (round(lat / 0.05) * 0.05, round(lon / 0.05) * 0.05)
if key not in cache:
cache[key] = build_tiers(fetch_forecast(lat, lon, days))
segments[str(idx)] = cache[key]
return {"days": days, "segments": segments}
View File
Whitespace-only changes.
+64
View File
@@ -0,0 +1,64 @@
"""SQLite schema and connection management. JSON-blob storage per PLAN.md 1d."""
from __future__ import annotations
import sqlite3
from pathlib import Path
SCHEMA = """
CREATE TABLE IF NOT EXISTS routes (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
source TEXT NOT NULL,
data JSON NOT NULL,
trail_guide_id TEXT REFERENCES trail_guides(id) ON DELETE SET NULL,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS trail_guides (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
source_url TEXT,
pdf_path TEXT,
data JSON NOT NULL,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS assets (
id TEXT PRIMARY KEY,
route_id TEXT NOT NULL REFERENCES routes(id) ON DELETE CASCADE,
generator TEXT NOT NULL,
data JSON NOT NULL,
created_at TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS weather_cache (
route_id TEXT PRIMARY KEY REFERENCES routes(id) ON DELETE CASCADE,
data JSON NOT NULL,
fetched_at TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS offline_map_packs (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
bbox JSON NOT NULL,
min_zoom INTEGER NOT NULL,
max_zoom INTEGER NOT NULL,
layers JSON NOT NULL,
status TEXT NOT NULL,
path TEXT,
size_bytes INTEGER DEFAULT 0,
tile_count INTEGER DEFAULT 0,
data JSON NOT NULL,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL
);
"""
def connect(db_path: str) -> sqlite3.Connection:
Path(db_path).parent.mkdir(parents=True, exist_ok=True)
conn = sqlite3.connect(db_path, check_same_thread=False)
conn.row_factory = sqlite3.Row
conn.execute("PRAGMA journal_mode=WAL")
conn.execute("PRAGMA foreign_keys=ON")
conn.executescript(SCHEMA)
return conn
+160
View File
@@ -0,0 +1,160 @@
"""CRUD stores over the SQLite JSON-blob tables."""
from __future__ import annotations
import json
import sqlite3
import threading
from typing import Optional
from app.models.assets import Asset
from app.models.map_pack import MapPack
from app.models.route import TrekkerRoute, utcnow_iso
from app.models.trail_guide import TrailGuide
class Store:
"""All-table store. Serializes writes with a lock (SQLite, multi-thread app)."""
def __init__(self, conn: sqlite3.Connection):
self.conn = conn
self.lock = threading.Lock()
# -- routes ------------------------------------------------------------
def save_route(self, route: TrekkerRoute) -> TrekkerRoute:
route.updated_at = utcnow_iso()
with self.lock, self.conn:
self.conn.execute(
"""INSERT INTO routes (id, name, source, data, trail_guide_id, created_at, updated_at)
VALUES (?,?,?,?,?,?,?)
ON CONFLICT(id) DO UPDATE SET
name=excluded.name, source=excluded.source, data=excluded.data,
trail_guide_id=excluded.trail_guide_id, updated_at=excluded.updated_at""",
(route.id, route.name, route.source, route.model_dump_json(),
route.trail_guide_id, route.created_at, route.updated_at),
)
return route
def get_route(self, route_id: str) -> Optional[TrekkerRoute]:
row = self.conn.execute("SELECT data FROM routes WHERE id=?", (route_id,)).fetchone()
return TrekkerRoute.model_validate_json(row["data"]) if row else None
def list_routes(self) -> list[TrekkerRoute]:
rows = self.conn.execute("SELECT data FROM routes ORDER BY created_at DESC").fetchall()
return [TrekkerRoute.model_validate_json(r["data"]) for r in rows]
def delete_route(self, route_id: str) -> bool:
with self.lock, self.conn:
cur = self.conn.execute("DELETE FROM routes WHERE id=?", (route_id,))
return cur.rowcount > 0
def link_trail_guide(self, route_id: str, guide_id: Optional[str]) -> Optional[TrekkerRoute]:
route = self.get_route(route_id)
if route is None:
return None
if guide_id is not None and self.get_trail_guide(guide_id) is None:
raise KeyError(f"trail guide {guide_id} not found")
route.trail_guide_id = guide_id
return self.save_route(route)
# -- trail guides --------------------------------------------------------
def save_trail_guide(self, guide: TrailGuide) -> TrailGuide:
guide.updated_at = utcnow_iso()
with self.lock, self.conn:
self.conn.execute(
"""INSERT INTO trail_guides (id, name, source_url, pdf_path, data, created_at, updated_at)
VALUES (?,?,?,?,?,?,?)
ON CONFLICT(id) DO UPDATE SET
name=excluded.name, source_url=excluded.source_url, pdf_path=excluded.pdf_path,
data=excluded.data, updated_at=excluded.updated_at""",
(guide.id, guide.name, guide.source_url, guide.pdf_path,
guide.model_dump_json(), guide.created_at, guide.updated_at),
)
return guide
def get_trail_guide(self, guide_id: str) -> Optional[TrailGuide]:
row = self.conn.execute("SELECT data FROM trail_guides WHERE id=?", (guide_id,)).fetchone()
return TrailGuide.model_validate_json(row["data"]) if row else None
def list_trail_guides(self) -> list[TrailGuide]:
rows = self.conn.execute("SELECT data FROM trail_guides ORDER BY created_at DESC").fetchall()
return [TrailGuide.model_validate_json(r["data"]) for r in rows]
def delete_trail_guide(self, guide_id: str) -> bool:
with self.lock, self.conn:
cur = self.conn.execute("DELETE FROM trail_guides WHERE id=?", (guide_id,))
return cur.rowcount > 0
# -- assets ---------------------------------------------------------------
def save_asset(self, asset: Asset) -> Asset:
with self.lock, self.conn:
self.conn.execute(
"""INSERT INTO assets (id, route_id, generator, data, created_at)
VALUES (?,?,?,?,?)
ON CONFLICT(id) DO UPDATE SET data=excluded.data""",
(asset.id, asset.route_id, asset.generator,
asset.model_dump_json(), asset.created_at),
)
return asset
def list_assets(self, route_id: str) -> list[Asset]:
rows = self.conn.execute(
"SELECT data FROM assets WHERE route_id=? ORDER BY created_at DESC", (route_id,)
).fetchall()
return [Asset.model_validate_json(r["data"]) for r in rows]
# -- weather cache ----------------------------------------------------------
def save_weather(self, route_id: str, data: dict) -> None:
with self.lock, self.conn:
self.conn.execute(
"""INSERT INTO weather_cache (route_id, data, fetched_at) VALUES (?,?,?)
ON CONFLICT(route_id) DO UPDATE SET data=excluded.data, fetched_at=excluded.fetched_at""",
(route_id, json.dumps(data), utcnow_iso()),
)
def get_weather(self, route_id: str) -> Optional[dict]:
row = self.conn.execute(
"SELECT data, fetched_at FROM weather_cache WHERE route_id=?", (route_id,)
).fetchone()
if not row:
return None
data = json.loads(row["data"])
data["fetched_at"] = row["fetched_at"]
return data
# -- offline map packs -----------------------------------------------------
def save_map_pack(self, pack: MapPack) -> MapPack:
pack.updated_at = utcnow_iso()
with self.lock, self.conn:
self.conn.execute(
"""INSERT INTO offline_map_packs
(id, name, bbox, min_zoom, max_zoom, layers, status, path,
size_bytes, tile_count, data, created_at, updated_at)
VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)
ON CONFLICT(id) DO UPDATE SET
name=excluded.name, status=excluded.status, path=excluded.path,
size_bytes=excluded.size_bytes, tile_count=excluded.tile_count,
data=excluded.data, updated_at=excluded.updated_at""",
(pack.id, pack.name, json.dumps(pack.bbox), pack.min_zoom, pack.max_zoom,
json.dumps(pack.layers), pack.status, pack.path, pack.size_bytes,
pack.tile_count, pack.model_dump_json(), pack.created_at, pack.updated_at),
)
return pack
def get_map_pack(self, pack_id: str) -> Optional[MapPack]:
row = self.conn.execute("SELECT data FROM offline_map_packs WHERE id=?", (pack_id,)).fetchone()
return MapPack.model_validate_json(row["data"]) if row else None
def list_map_packs(self) -> list[MapPack]:
rows = self.conn.execute("SELECT data FROM offline_map_packs ORDER BY created_at DESC").fetchall()
return [MapPack.model_validate_json(r["data"]) for r in rows]
def delete_map_pack(self, pack_id: str) -> bool:
with self.lock, self.conn:
cur = self.conn.execute("DELETE FROM offline_map_packs WHERE id=?", (pack_id,))
return cur.rowcount > 0
View File
Whitespace-only changes.
+56
View File
@@ -0,0 +1,56 @@
"""Manual bidirectional sync between Home and Neutron Trekker instances.
MVP conflict policy: newest updated_at wins, per record. Each side exposes
GET /api/sync/bundle and POST /api/sync/bundle; "Sync" pulls the peer's
bundle, merges it locally, then pushes the local bundle to the peer.
"""
from __future__ import annotations
import logging
from typing import Any
import httpx
from app.models.route import TrekkerRoute
from app.models.trail_guide import TrailGuide
from app.storage.route_store import Store
log = logging.getLogger("trekker.sync")
def build_bundle(store: Store) -> dict[str, Any]:
return {
"routes": [r.model_dump() for r in store.list_routes()],
"trail_guides": [g.model_dump() for g in store.list_trail_guides()],
}
def merge_bundle(store: Store, bundle: dict[str, Any]) -> dict[str, int]:
"""Apply a peer bundle locally; newest updated_at wins. Returns counts."""
applied = {"routes": 0, "trail_guides": 0}
for raw in bundle.get("trail_guides", []):
incoming = TrailGuide.model_validate(raw)
local = store.get_trail_guide(incoming.id)
if local is None or incoming.updated_at > local.updated_at:
store.save_trail_guide(incoming)
applied["trail_guides"] += 1
for raw in bundle.get("routes", []):
incoming = TrekkerRoute.model_validate(raw)
local = store.get_route(incoming.id)
if local is None or incoming.updated_at > local.updated_at:
store.save_route(incoming)
applied["routes"] += 1
return applied
def sync_with_peer(store: Store, peer_url: str) -> dict[str, Any]:
base = peer_url.rstrip("/")
with httpx.Client(timeout=60) as client:
resp = client.get(f"{base}/api/sync/bundle")
resp.raise_for_status()
pulled = merge_bundle(store, resp.json())
push = client.post(f"{base}/api/sync/bundle", json=build_bundle(store))
push.raise_for_status()
pushed = push.json()
return {"pulled": pulled, "pushed": pushed.get("applied", pushed)}