# 🦅 San'e (صانع) — The Arabic-First Personal AI Assistant for the GCC

**San'e** (صانع, Arabic for "The Maker") is an open-source, self-hosted personal AI assistant designed from the ground up for the 400 million Arabic speakers in the Gulf and beyond. It is a localized fork of the powerful [OpenClaw](https://github.com/openclaw/openclaw) framework (MIT), reimagined with a deep understanding of GCC culture, language, and daily life.

Where OpenClaw provides a generic and excellent foundation, San'e provides a soul. It speaks your language, understands your culture, and anticipates your needs — from prayer times in Kuwait City to government services in Riyadh.

| Language | Status | License | Deployment |
|---|---|---|---|
| **TypeScript** | ✅ Active | **MIT** | **Docker / Node.js** |

---

## Core Philosophy

**Arabic-First, not Arabic-added.** San'e is not a translation of an English assistant; it is built with an Arabic-first mindset. All system prompts, configurations, and interactions default to a natural, professional Gulf Arabic register — the kind a Kuwaiti professional would use with a trusted colleague.

**GCC-Native.** Culturally-aware skills are at the core of San'e. It understands the rhythms of life in the Gulf, from Ramadan scheduling to Hijri calendar events and government portal navigation.

**Open & Self-Hosted.** Your data, your assistant. San'e runs on your own hardware (a local machine or any VPS), ensuring complete privacy and control.

---

## Features

### Arabic Language Layer
- Default model configured for strong Arabic capability (Claude Sonnet 4.6 via Anthropic API).
- Natural, warm, professional Gulf-Arabic persona — not formal MSA, not colloquial.
- Seamless RTL text handling across all interfaces.
- Arabic-first onboarding flow (`ما اسمك؟ كيف أساعدك؟`).

### GCC Cultural Skills (built-in)

| Skill | Description |
|---|---|
| 🕌 **Prayer Times** | Auto-fetches Salah times for Kuwait City, Riyadh, Dubai, Abu Dhabi, Doha, Manama, and Muscat. Sends proactive reminders 15 minutes before each prayer. |
| 🌙 **Ramadan Mode** | Automatically detects Ramadan via the Hijri calendar. Adjusts scheduling logic, provides Iftar/Suhoor times, and adopts a spiritually-aware tone. |
| 📅 **Hijri Calendar** | Displays both Gregorian and Hijri dates in all date references. Supports conversion between calendar systems. |
| 🇰🇼 **Kuwait Gov Portals** | Direct links and guidance for MOI, PACI, Civil ID, Ministry of Health, Municipality, and the Kuwait e-Government portal. |
| 🏢 **AgenThink Bridge** | A placeholder skill for future integration with the San'e Business and AgenThink Institutional ecosystem. |

### Channel Integration
- **Telegram** (via grammY): Full bot integration with Arabic welcome message, command handling, and session management.
- **WhatsApp** (via Baileys): QR-code pairing, Arabic welcome message, and persistent sessions.

### Deployment
- **One-command install** script for Ubuntu and macOS.
- **Docker Compose** file for production VPS deployment.
- **Health check endpoint** at `/health` for monitoring.
- **Web dashboard** at port `18789` for status overview.

---

## Tech Stack

- **Base Framework:** OpenClaw (Node.js, TypeScript)
- **AI Model:** Anthropic Claude Sonnet 4.6 (configurable via `SANE_MODEL`)
- **Channels:** WhatsApp (Baileys), Telegram (grammY)
- **Deployment:** Docker, Node.js 22+

---

## Getting Started

### Prerequisites

- **Node.js v22+**
- **Docker & Docker Compose** (for VPS deployment)
- **API Keys:** `ANTHROPIC_API_KEY` (required), `TELEGRAM_BOT_TOKEN` (optional)

### 1. One-Command Install (Ubuntu / macOS)

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/your-org/sane-assistant/main/scripts/install.sh)"
```

### 2. Manual Installation

```bash
# Clone the repository
git clone https://github.com/your-org/sane-assistant.git
cd sane-assistant

# Install dependencies
npm install -g pnpm
pnpm install

# Configure your assistant
cp .env.example .env
# Edit .env with your API keys and preferences

# Run the interactive onboarding wizard
pnpm sane onboard

# Start the assistant
pnpm start
```

### 3. Docker Deployment (VPS)

```bash
# Clone and configure
git clone https://github.com/your-org/sane-assistant.git
cd sane-assistant
cp .env.example .env
# Edit .env with your API keys

# Build and run
docker compose up -d --build

# Check status
docker compose logs -f
# Dashboard: http://<your-vps-ip>:18789
```

---

## Configuration

All configuration is managed via the `.env` file. Key settings:

| Variable | Default | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | — | **Required.** Your Anthropic API key. |
| `SANE_MODEL` | `claude-sonnet-4-5` | The AI model to use. |
| `SANE_LOCATION` | `kuwait_city` | Your city for prayer times. Options: `kuwait_city`, `riyadh`, `dubai`, `abu_dhabi`, `doha`, `manama`, `muscat`. |
| `SANE_LANGUAGE` | `ar` | Default language (`ar` or `en`). |
| `TELEGRAM_BOT_TOKEN` | — | Your Telegram bot token from @BotFather. |
| `TELEGRAM_ALLOWED_USERS` | — | Comma-separated Telegram user IDs allowed to use the bot. |
| `SANE_PRAYER_REMINDERS` | `true` | Enable/disable proactive prayer reminders. |
| `SANE_RAMADAN_MODE` | `auto` | `auto` (detect via Hijri calendar), `on`, or `off`. |

---

## CLI Commands

```bash
pnpm sane start       # Start the San'e gateway
pnpm sane onboard     # Run the interactive setup wizard
pnpm sane chat        # Chat directly in the terminal
pnpm sane status      # Check if San'e is running
pnpm sane skills      # List all loaded skills
```

---

## The San'e Ecosystem

San'e is the first step in a three-tier ecosystem designed to bring powerful, culturally-aware AI to the Arab world.

| Tier | Product | Status |
|---|---|---|
| 1 | **San'e Personal (صانع الشخصي)** — This project. Personal assistant for individuals. | ✅ Available |
| 2 | **San'e Business (صانع الأعمال)** — AI solutions for SMEs. | 🔜 Coming Soon |
| 3 | **AgenThink Institutional** — Enterprise-grade multi-agent platform. | 🔜 Coming Soon |

---

## Contributing

San'e is an open-source project, and contributions are welcome. Please fork the repository, create a feature branch, and submit a pull request.

## License

San'e is licensed under the **MIT License**. It is a derivative work of [OpenClaw](https://github.com/openclaw/openclaw), which is also licensed under MIT.