arahin 1.1.1

AI Route Planning Agent — Spatial-RAG + TSP + Interactive CLI

ARAHIN — AI ReAct Agent for Hybrid Itinerary Navigation

Spatial-RAG + TSP + Interactive CLI

ARAHIN (AI ReAct Agent for Hybrid Itinerary Navigation) is an AI agent that plans multi-stop routes from natural language descriptions. It uses a ReAct loop — LLM calls tools (geocode, spatial search, POI lookup) to identify waypoints, then optimizes the route via OR-Tools TSP and renders an interactive Folium map.

Works for any city in the world with OpenStreetMap data. No ML dependencies, no FAISS, no pre-built index.

      █████╗ ██████╗  █████╗ ██╗  ██╗██╗███╗   ██╗
     ██╔══██╗██╔══██╗██╔══██╗██║  ██║██║████╗  ██║
     ███████║██████╔╝███████║███████║██║██╔██╗ ██║
     ██╔══██║██╔══██╗██╔══██║██╔══██║██║██║╚██╗██║
     ██║  ██║██║  ██║██║  ██║██║  ██║██║██║ ╚████║
     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝

Install

pipx install arahin

No PyTorch, no CUDA, no FAISS, no heavy ML stack. Dependencies (openai, requests, ortools, folium, rich) total ~30-50 MB installed.

Quick Start

export ARAHIN_API_KEY="sk-..."

# Interactive REPL
arahin

# One-shot with map
arahin "dari Monas ke Taman Mini, mampir sate dekat Cawang" --map

# With turn-by-turn directions
arahin "jalan-jalan di Kota Tua" --map --directions

Example Session

📍 Route Description > saya dari Universitas Muhammadiyah Yogyakarta,
                       saya mau ke Masjid Agung Kauman,
                       saya ingin lewat pasty dan berhenti untuk
                       makan bebek dulu

🧠 Extracting waypoints...
  🤔 geocode("Universitas Muhammadiyah Yogyakarta") → found (-7.8108, 110.3223)
  🤔 geocode("Masjid Agung Kauman") → found (-7.8038, 110.3624)
  🤔 geocode("Pasty Yogyakarta") → found (-7.8257, 110.3544)
  🤔 spatial_rag("bebek goreng", ...) → found 3 restaurants
  ✅ Waypoints: UMY → Pasty → Bebek Goreng H Slamet → Masjid Agung Kauman

📍 Route Description > /map     # opens route.html in browser
📍 Route Description > /dir     # prints turn-by-turn directions

REPL Commands

Command	Action
/api <key>	Set API key (session only, never written to disk)
/model <name>	Switch model (no arg: show current + available)
/map	Open route map in browser
/dir	Print turn-by-turn directions
/config	Show current settings
/help	Show help screen
/exit	Quit

CLI Flags

Flag	Description
query	Route description (omit for REPL mode)
--map, -m	Open route map in browser
--directions, -d	Print turn-by-turn directions
--version	Show version

How It Works

User prompt (any city, any language)
  → ReAct Loop (LLM calls geocode / spatial_rag / poi_search)
  → Ordered waypoints JSON
  → Route Optimizer (OSRM matrix → OR-Tools TSP)
  → Ordered route with road geometry
  → Folium interactive map (route.html)

Tools

Tool	API	Purpose
geocode	Nominatim	Named places: "Monas", "Universitas Gadjah Mada"
spatial_rag	Overpass	Natural language: "bebek goreng", "tempat wisata"
poi_search	Overpass	By category: "cari masjid", "cari restoran"
route	OSRM	Driving directions + distance matrix
optimizer	OR-Tools	TSP solver (open or closed path)
render_map	Folium	Interactive HTML map with distance labels

Requirements

• API key: OpenCode Go ($ARAHIN_API_KEY or $OPENCODE_API_KEY)
• LLM: DeepSeek V4 (or any model available on OpenCode Go)
• Internet: Required (all APIs are online)
• Disk: ~30-50 MB (ortools is the heaviest dep at ~15 MB)

Project Structure

arahin/
├── cli.py              # Entry point + REPL + 8 commands
├── banner.py           # ASCII splash screen
├── state.py            # Session state singleton
├── agent/
│   ├── controller.py   # ReAct loop with tool dispatch
│   └── prompts.py      # 3 tool schemas + system prompt
├── tools/
│   ├── geocode.py      # Nominatim forward geocode
│   ├── poi_search.py   # Overpass by amenity category
│   ├── spatial_rag.py  # Overpass multi-tag spatial search
│   ├── route.py        # OSRM driving + distance matrix
│   ├── optimizer.py    # TSP solver (brute-force n≤10, OR-Tools n>10)
│   └── render_map.py   # Folium interactive HTML map
├── tests/
│   ├── test_cli.py
│   ├── test_config.py
│   └── test_state.py
└── README.md

License

MIT