feat(api): add navigation module with map provider and ai tools

- add lib/maps/ provider abstraction (MapProvider ABC, GoogleMapProvider, factory)
- add navigation/ domain module (model, schemas, repository, service, router)
- add 3 AI tools: start_navigation, cancel_navigation, get_navigation_step
- add location message handling, off-route detection, Gemini context feed in live.py
- add publish_location() to LiveKit bot for Concierge location relay
- add navigation system instructions to AI orchestrator
- add waypoint cleanup to admin service
- add Alembic migration for navigation_sessions and location_waypoints tables
- add MAP_PROVIDER, GOOGLE_MAPS_API_KEY config and MapsDep dependency

Author: gahyun-git

apps/api/alembic/env.py

@@ -12,6 +12,7 @@
 from src.lib.config import settings
 from src.lib.database import Base
 from src.medications.model import Medication  # noqa: F401
+from src.navigation.model import LocationWaypoint, NavigationSession  # noqa: F401
 from src.notification_logs.model import (  # noqa: F401
     NotificationLog,
     NotificationPreference,

apps/api/alembic/versions/0001_initial.py

@@ -449,8 +449,128 @@ def upgrade() -> None:
         unique=True,
     )
 
+    # --- navigation_sessions ---
+    op.create_table(
+        "navigation_sessions",
+        sa.Column(
+            "id",
+            sa.UUID(),
+            server_default=sa.text("gen_random_uuid()"),
+            nullable=False,
+        ),
+        sa.Column("host_id", sa.UUID(), nullable=False),
+        sa.Column(
+            "status",
+            sa.String(length=20),
+            server_default="active",
+            nullable=False,
+            comment="active | completed | cancelled",
+        ),
+        sa.Column("destination_name", sa.String(length=500), nullable=False),
+        sa.Column("destination_lat", sa.Float(), nullable=False),
+        sa.Column("destination_lng", sa.Float(), nullable=False),
+        sa.Column("origin_lat", sa.Float(), nullable=False),
+        sa.Column("origin_lng", sa.Float(), nullable=False),
+        sa.Column(
+            "route_data",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'{}'::jsonb"),
+            nullable=False,
+        ),
+        sa.Column(
+            "current_step_index",
+            sa.Integer(),
+            server_default=sa.text("0"),
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column("completed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.ForeignKeyConstraint(
+            ["host_id"],
+            ["users.id"],
+            name=op.f("fk_navigation_sessions_host_id_users"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_navigation_sessions")),
+    )
+    op.create_index(
+        "ix_navigation_sessions_host_id",
+        "navigation_sessions",
+        ["host_id"],
+        unique=False,
+    )
+    op.create_index(
+        "ix_navigation_sessions_status",
+        "navigation_sessions",
+        ["status"],
+        unique=False,
+    )
+
+    # --- location_waypoints ---
+    op.create_table(
+        "location_waypoints",
+        sa.Column(
+            "id",
+            sa.UUID(),
+            server_default=sa.text("gen_random_uuid()"),
+            nullable=False,
+        ),
+        sa.Column("host_id", sa.UUID(), nullable=False),
+        sa.Column("session_id", sa.UUID(), nullable=True),
+        sa.Column("lat", sa.Float(), nullable=False),
+        sa.Column("lng", sa.Float(), nullable=False),
+        sa.Column("altitude", sa.Float(), nullable=True),
+        sa.Column("accuracy", sa.Float(), nullable=True),
+        sa.Column("speed", sa.Float(), nullable=True),
+        sa.Column("heading", sa.Float(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["host_id"],
+            ["users.id"],
+            name=op.f("fk_location_waypoints_host_id_users"),
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["session_id"],
+            ["navigation_sessions.id"],
+            name=op.f("fk_location_waypoints_session_id_navigation_sessions"),
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_location_waypoints")),
+    )
+    op.create_index(
+        "ix_location_waypoints_host_id_created_at",
+        "location_waypoints",
+        ["host_id", "created_at"],
+        unique=False,
+    )
+    op.create_index(
+        "ix_location_waypoints_session_id",
+        "location_waypoints",
+        ["session_id"],
+        unique=False,
+    )
+
 
 def downgrade() -> None:
+    op.drop_index("ix_location_waypoints_session_id", table_name="location_waypoints")
+    op.drop_index(
+        "ix_location_waypoints_host_id_created_at", table_name="location_waypoints"
+    )
+    op.drop_table("location_waypoints")
+    op.drop_index("ix_navigation_sessions_status", table_name="navigation_sessions")
+    op.drop_index("ix_navigation_sessions_host_id", table_name="navigation_sessions")
+    op.drop_table("navigation_sessions")
     op.drop_index(op.f("ix_device_tokens_token"), table_name="device_tokens")
     op.drop_index("ix_device_tokens_user_id", table_name="device_tokens")
     op.drop_table("device_tokens")

apps/api/src/admin/schemas.py

@@ -14,6 +14,7 @@ class CleanupRequest(BaseModel):
 class CleanupResponse(BaseModel):
     deleted_wellness_logs: int
     deactivated_tokens: int
+    deleted_waypoints: int = 0
 
 
 class InactiveRelationResponse(BaseModel):

apps/api/src/admin/service.py

@@ -14,6 +14,7 @@
     WellnessAggregateResponse,
 )
 from src.medications import repository as medication_repo
+from src.navigation import repository as navigation_repo
 from src.notifications import repository as notification_repo
 from src.relations import repository as relation_repo
 from src.users import repository as user_repo
@@ -46,13 +47,20 @@ async def cleanup_data(
 
     deleted_logs = 0
     deactivated = 0
+    deleted_waypoints = 0
 
     if resource_type in ("all", "wellness_logs"):
         deleted_logs = await repository.delete_old_wellness_logs(db, before)
 
     if resource_type in ("all", "device_tokens"):
         deactivated = await repository.deactivate_old_tokens(db, before)
 
+    if resource_type in ("all", "waypoints"):
+        waypoint_cutoff = datetime.now(UTC) - timedelta(days=7)
+        deleted_waypoints = await navigation_repo.delete_waypoints_before(
+            db, waypoint_cutoff
+        )
+
     await _log_audit(
         db,
         action="cleanup",
@@ -61,12 +69,14 @@ async def cleanup_data(
             "retention_days": retention_days,
             "deleted_wellness_logs": deleted_logs,
             "deactivated_tokens": deactivated,
+            "deleted_waypoints": deleted_waypoints,
         },
     )
     await db.commit()
     return CleanupResponse(
         deleted_wellness_logs=deleted_logs,
         deactivated_tokens=deactivated,
+        deleted_waypoints=deleted_waypoints,
     )
 
 

apps/api/src/common/enums.py

@@ -16,3 +16,11 @@ class WellnessStatus(str, enum.Enum):
     NORMAL = "normal"
     WARNING = "warning"
     EMERGENCY = "emergency"
+
+
+class NavigationStatus(str, enum.Enum):
+    """Navigation session lifecycle states."""
+
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"

apps/api/src/common/errors.py

@@ -22,6 +22,8 @@
 RES_003: ErrorTuple = ("RES_003", "Medication not found")
 RES_004: ErrorTuple = ("RES_004", "User not found")
 RES_005: ErrorTuple = ("RES_005", "Device token not found")
+RES_006: ErrorTuple = ("RES_006", "Navigation session not found")
+RES_007: ErrorTuple = ("RES_007", "No active navigation session")
 
 # ── Validation ─────────────────────────────────────────────────────
 VAL_001: ErrorTuple = ("VAL_001", "Invalid caregiver role")
@@ -33,6 +35,8 @@
 SVC_003: ErrorTuple = ("SVC_003", "OAuth provider did not return an email address")
 SVC_004: ErrorTuple = ("SVC_004", "Storage provider is not configured")
 SVC_005: ErrorTuple = ("SVC_005", "File upload failed")
+SVC_006: ErrorTuple = ("SVC_006", "Maps provider is not configured")
+SVC_007: ErrorTuple = ("SVC_007", "Geocoding returned no results")
 
 
 def raise_api_error(

apps/api/src/lib/ai/orchestrator.py

@@ -44,7 +44,17 @@ def _resolve_model() -> str:
     "9. When the Host shows a medication schedule, prescription, pharmacy label, "
     "or pill organizer to the camera, use `scan_medication_schedule` to extract "
     "ALL visible medication names and times in a single call. Confirm the "
-    "extracted data with the Host before finalizing."
+    "extracted data with the Host before finalizing.\n"
+    "10. NAVIGATION — When the Host mentions a destination, call `start_navigation`. "
+    "Combine camera imagery with GPS data for natural guidance. "
+    "Give advance notice 20m before intersections. "
+    "Prefer visible landmarks over street names.\n"
+    "11. OFF-ROUTE — When off-route is detected, calmly guide back. "
+    "Never blame the Host for going the wrong way.\n"
+    "12. ARRIVAL — When within 30m of destination, announce arrival "
+    "and call `cancel_navigation`.\n"
+    "13. LOCATION AWARENESS — Use GPS context to mention nearby "
+    "crosswalks, traffic lights, and other environmental cues."
 )
 
 ToolHandler = Callable[[str, dict[str, Any]], Coroutine[Any, Any, Any]]

apps/api/src/lib/ai/tools/cancel_navigation.py

@@ -0,0 +1,55 @@
+"""Gemini function calling tool: cancel current navigation."""
+
+from typing import Any
+
+import structlog
+
+from src.lib.ai.tools.base import BaseTool, ToolContext, register_tool
+from src.navigation import repository, service
+
+logger = structlog.get_logger(__name__)
+
+
+class CancelNavigationTool(BaseTool):
+    """AI tool to cancel the current walking navigation session."""
+
+    @property
+    def name(self) -> str:
+        return "cancel_navigation"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Cancel the current navigation. "
+            "Use when the Host says to stop directions or has arrived."
+        )
+
+    async def execute(
+        self, *, context: ToolContext | None = None, **kwargs: Any
+    ) -> Any:
+        if not context or "db" not in context or "host_id" not in context:
+            return {"error": "Missing required context (db, host_id)"}
+
+        db = context["db"]
+        host_id = context["host_id"]
+
+        nav = await repository.find_active_session(db, host_id)
+        if nav is None:
+            return {"error": "No active navigation session"}
+
+        await service.cancel_navigation(db, nav.id)
+
+        logger.info(
+            "navigation_cancelled",
+            host_id=str(host_id),
+            session_id=str(nav.id),
+        )
+
+        return {
+            "success": True,
+            "session_id": str(nav.id),
+            "message": "Navigation cancelled",
+        }
+
+
+register_tool(CancelNavigationTool())

apps/api/src/lib/ai/tools/get_navigation_step.py

@@ -0,0 +1,76 @@
+"""Gemini function calling tool: get current navigation step."""
+
+from typing import Any
+
+import structlog
+
+from src.lib.ai.tools.base import BaseTool, ToolContext, register_tool
+from src.navigation import repository
+
+logger = structlog.get_logger(__name__)
+
+
+class GetNavigationStepTool(BaseTool):
+    """AI tool to retrieve the current or next navigation step."""
+
+    @property
+    def name(self) -> str:
+        return "get_navigation_step"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Get the current or next navigation instruction. "
+            "Use when the Host asks about the next turn or direction."
+        )
+
+    async def execute(
+        self, *, context: ToolContext | None = None, **kwargs: Any
+    ) -> Any:
+        if not context or "db" not in context or "host_id" not in context:
+            return {"error": "Missing required context (db, host_id)"}
+
+        db = context["db"]
+        host_id = context["host_id"]
+
+        nav = await repository.find_active_session(db, host_id)
+        if nav is None:
+            return {"error": "No active navigation session"}
+
+        route_data = nav.route_data
+        steps = route_data.get("steps", [])
+        idx = nav.current_step_index
+
+        if not steps:
+            return {"error": "No route steps available"}
+
+        if idx >= len(steps):
+            return {
+                "message": "You have completed all steps. "
+                "You should be at your destination.",
+                "destination": nav.destination_name,
+            }
+
+        current_step = steps[idx]
+        remaining_steps = len(steps) - idx
+
+        result: dict[str, Any] = {
+            "current_step": idx + 1,
+            "total_steps": len(steps),
+            "remaining_steps": remaining_steps,
+            "instruction": current_step.get("instruction", ""),
+            "distance_meters": current_step.get("distance_meters", 0),
+            "maneuver": current_step.get("maneuver"),
+            "destination": nav.destination_name,
+        }
+
+        # Include next step preview if available
+        if idx + 1 < len(steps):
+            next_step = steps[idx + 1]
+            result["next_instruction"] = next_step.get("instruction", "")
+            result["next_maneuver"] = next_step.get("maneuver")
+
+        return result
+
+
+register_tool(GetNavigationStepTool())