Artha - Personal Intelligence OS

# Artha - Personal Intelligence OS

[![CI](https://github.com/vedprakash-m/artha/actions/workflows/ci.yml/badge.svg)](https://github.com/vedprakash-m/artha/actions/workflows/ci.yml)
[![PII Check](https://github.com/vedprakash-m/artha/actions/workflows/pii-check.yml/badge.svg)](https://github.com/vedprakash-m/artha/actions/workflows/pii-check.yml)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

**Your life, organized by AI.**

Artha gives your AI assistant (Claude, Gemini, or GitHub Copilot) deep, persistent context about your life — health, finance, family, goals, home, immigration — so every conversation starts where the last one left off.

> No server. No database. No Docker. Just your files + your AI assistant.
> 🔒 Your data stays on your machine. No telemetry. No cloud sync.

---

## Get Started

**You need: Python 3.11+ and Git.**

```bash
git clone https://github.com/vedprakash-m/artha.git
cd artha
bash setup.sh
```

Setup runs a demo briefing in under 10 seconds, then offers a 2-minute wizard to personalize Artha for your life. After the wizard, open your AI CLI and say: **catch me up**

<details>
<summary><b>Windows (PowerShell)</b></summary>

```powershell
git clone https://github.com/vedprakash-m/artha.git
cd artha
.\setup.ps1
```

`setup.ps1` mirrors `setup.sh` — creates a venv at `$HOME\.artha-venvs\.venv-win`, installs dependencies, runs the demo, then offers the setup wizard.

</details>

<details>
<summary><b>⚙ Advanced Setup — encryption, connectors, full prerequisites</b></summary>

### Prerequisites

| Prerequisite | Why | Install |
|---|---|---|
| **Python 3.11+** | Runs all Artha scripts | [python.org](https://www.python.org/downloads/) |
| **Git** | Clone the repo | [git-scm.com](https://git-scm.com/) |
| **`age`** | Encrypts sensitive state files | `brew install age` (macOS) · `sudo apt install age` (Ubuntu 22.04+) · `winget install FiloSottile.age` (Windows) |
| **Node.js 18+** | Only for Claude Code / Gemini CLI npm install | [nodejs.org](https://nodejs.org/) — skip if using GitHub Copilot |
| **System keyring** *(Linux only)* | Stores keys and tokens | Pre-installed on GNOME/KDE. Headless: `pip install keyrings.alt` |
| **An AI CLI** | Runtime — Artha runs *inside* your AI CLI | [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) · [Gemini CLI](https://github.com/google-gemini/gemini-cli) · [GitHub Copilot](https://github.com/features/copilot) |

> **Which AI CLI?** Gemini CLI has a free tier. Claude Code has rate-limited free access. GitHub Copilot has a free tier in VS Code. All three work. See [docs/supported-clis.md](docs/supported-clis.md).

### Set Up Encryption

```bash
age-keygen -o ~/age-key.txt
# Paste the age1... public key into config/user_profile.yaml → encryption.age_recipient
python scripts/vault.py store-key ~/age-key.txt   # store private key in OS keyring
python scripts/vault.py status                    # verify: credential store key ✓
rm ~/age-key.txt                                  # delete plaintext after verified
```

### Connect Data Sources

```bash
python scripts/setup_google_oauth.py    # Gmail + Google Calendar
python scripts/setup_msgraph_oauth.py   # Outlook + Calendar (optional)
python scripts/setup_todo_lists.py      # Microsoft To Do (optional)
python scripts/setup_ha_token.py        # Home Assistant IoT (optional, LAN only)
```

See [docs/google-oauth-setup.md](docs/google-oauth-setup.md) for a walkthrough.

### Preflight Check

```bash
python scripts/preflight.py --first-run   # advisory mode for new installs
python scripts/preflight.py --fix         # fix auto-correctable issues
```

### Migrating from Legacy Settings

```bash
python scripts/migrate.py --dry-run   # preview changes
python scripts/migrate.py             # write config/user_profile.yaml
```

</details>

---

## What You Get

- **Daily briefings** across 24 life domains (health, finance, goals, immigration, family, home, and more) — with action items, goal progress, and proactive nudges
- **Goal Intelligence Engine** — conversational goal management with metric progress bars, sprint planning, and cross-domain pattern alerts
- **Action Layer** — propose, approve, and execute real-world actions (email, calendar, reminders) through a human-gated queue with full audit trail; deterministic per-type schema validation, composite-key idempotency (TTL-windowed dedup), and OCC version-field conflict detection prevent silent data races
- **Work OS** — professional briefings, meeting prep, sprint health, career evidence capture, and knowledge graph for your work context
- **Career Search Intelligence** — 7-block A–G job evaluation framework, ATS-optimized PDF generation via Playwright, application tracker with story bank, 90-day audit trail, and 3 guardrails for JD injection, auto-submit prevention, and 

... (truncated)