Metadata-Version: 2.4
Name: arahin
Version: 1.1.1
Summary: AI Route Planning Agent — Spatial-RAG + TSP + Interactive CLI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: ortools>=9.0.0
Requires-Dist: folium>=0.17.0
Requires-Dist: rich>=13.0.0

# 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

```bash
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

```bash
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
