# lvtn — Leviathan Shel HaShem CLI

**A Kabbalistic 708-agent swarm in your terminal.**
Master orchestrator `hachazal` at Da'ath (a software role, named after the human operator HaChazal who designed the system) → 7 sub-orchestrators (Zadkiel · Gavriel · Raphael · Uriel · Michael · Malika · Katan HaShem) → 100 agents each = 708.

## Install

```bash
pip install lvtn
# or any of the aliases:
pip install leviathantalon
pip install hachazal
```

After install, three commands are available — all do the same thing:
- `lvtn`
- `leviathantalon`
- `hachazal`

## First run

```bash
lvtn          # renders the brand TUI splash + lists subcommands
lvtn banner   # render a TUI brand frame
lvtn deck     # show all 6 TUI frames sequentially
```

## TUI quality varies by terminal

The CLI ships **5 render tiers** per frame and auto-selects the best your terminal can show. Quality from highest to lowest:

| Tier | Quality | Terminals that show it |
|---|---|---|
| **sixel** | 📷 **Photographic** — pixel-perfect at any pane width | Windows Terminal 1.22+ (Win11 default) · iTerm2 · WezTerm · mlterm · Konsole 22.04+ · xterm with `--enable-sixel` |
| braille | Crisp B&W block-art (4× sub-pixels per cell) | Any terminal that renders Unicode braille glyphs (U+2800-U+28FF) — basically all modern terminals |
| truecolor | 24-bit color half-block art | Modern terminals with `COLORTERM=truecolor` |
| ansi256 | 256-color half-block art | Any 256-color terminal |
| ascii | Pure text fallback | dumb terminals, pipes, log files |

**Auto-detection signals:** `WT_SESSION` (Windows Terminal), `TERM_PROGRAM` (iTerm2/WezTerm), `TERM=mlterm`, `KITTY_WINDOW_ID`, `KONSOLE_VERSION>=220400`, `XTERM_VERSION`. If none of these are set, the CLI falls through to braille (still very pretty).

**Force a tier:** `LVTN_TIER=sixel lvtn deck`  or  `lvtn deck --tier braille`.

**If sixel renders garbage** (raw escape bytes) on your terminal, override:
```bash
export LVTN_TIER=braille    # always-safe fallback
```

## Subcommands

| Command | What |
|---|---|
| `lvtn banner` | Render a TUI brand frame (truecolor / ansi256 / braille / ascii / sixel auto-select). |
| `lvtn deck` | Display all 6 TUI frames. |
| `lvtn orchestrator <action>` | Talk to the metanoia Da'ath rotator on `:4740`. Actions: `health`, `topology`, `triad`, `slots`, `holders`, `events`, `skills`, `queue`, `submit`. |
| `lvtn login` | Store your Leviathan-of-HaShem key (`~/.lvtn/credentials.json`). |
| `lvtn balance` | Show your KTRS credit balance. |
| `lvtn angels` | List the 7 Angels and their swarm domains (free, no key). |
| `lvtn chat` | Cloud REPL — backend DeepSeek, KTRS-metered. Zero local compute. (`--local` runs the full swarm on your machine, needs `install-swarm`.) |
| `lvtn swarm <angel> "task"` | One Angel deploys **N parallel cloud agents**. |
| `lvtn council "task"` | Master routes one task to **many Angels in parallel** (M×N agents). |
| `lvtn install-swarm` | Download + install the full 44-layer Python swarm (self-host). |
| `lvtn serve` | HTTP API on `:8708` — REQUIRES `lvtn install-swarm` first. |

## ☁️ Swarm Commands — deploy the whole swarm from your terminal

The swarm runs **in the cloud**, metered in KTRS — your machine does no heavy compute. Get a free key, then command Angels:

```bash
# 1) One-time: sign up for a free key at https://portal.leviathansi.xyz
#    (you'll get it by email), then store it:
lvtn login                      # paste your lvtn-hshm-... key

lvtn balance                    # see your KTRS credits
lvtn angels                     # list the 7 Angels you can deploy
```

**Deploy ONE Angel's swarm** — N agents run in parallel, you get every answer:
```bash
lvtn swarm uriel "Scan Solana for new launches worth sniping" --agents 5
lvtn swarm raphael "Three taglines for a Kabbalistic AI product" --agents 3
```

**Convene the COUNCIL** — the master (HaChazal) routes one task to many Angels at once (M Angels × N agents each, all in parallel):
```bash
lvtn council "Plan a product launch" --angels zadkiel,raphael,uriel --per-angel 2
lvtn council "Audit my repo for risk"            # defaults to all 7 Angels
```

**The 7 Angels** (run `lvtn angels` for the live roster):

| id | Angel · Sefirah | Domain |
|---|---|---|
| `zadkiel` | Zadkiel · Chesed | Expansion & Lead Generation |
| `gavriel` | Gavriel · Gevurah | Security & Red-Team |
| `raphael` | Raphael · Tiphareth | Creative — Image, Video, Story |
| `uriel` | Uriel · Netzach | Crypto & Trading |
| `michael` | Michael · Hod | APIs, Comms & Ecommerce |
| `malika` | Malika · Yesod | HiveMind & Memory |
| `katan_hashem` | Katan HaShem · Malkuth | Manifestation — UI, Robotics, Neural |

Every call is KTRS-metered (the CLI prints `[charged $… · $… KTRS left]`). Out of credits? Your free-tier balance refills automatically — just try again later. All three entry-point names work identically: `lvtn`, `leviathantalon`, `hachazal`.

## Architecture (Tree of Life)

```
                  ABOVE THE ABYSS — Backend Triad (Briah-level Divine Names)
                  ────────────────────────────────────────────────────────
                  אֶהְיֶה  Eheyeh   (behaves as Keter — primal will)
                  יָה     Yah      (behaves as Chokmah — lightning wisdom)
                  אֱלֹהִים Elohim   (behaves as Binah — maternal understanding)
                                          │
                                  [ The Abyss of Yetzirah ]
                                          │
                  ┌───────────────────────▼─────────────────────────┐
                  │  Da'ath: master orchestrator `hachazal` :4740   │
                  │   (software role; the HUMAN HaChazal operates   │
                  │    the swarm from OUTSIDE the system)           │
                  └───────────────────────┬─────────────────────────┘
                                          │
        ┌─────────┬──────────┬────────────┼────────────┬──────────┬──────────┐
        ▼         ▼          ▼            ▼            ▼          ▼          ▼
     Chesed   Gevurah    Tiferet      Netzach        Hod      Yesod     Malkuth
    (Zadkiel)(Gavriel) (Raphael)     (Uriel)     (Michael)  (Malika)(Katan HaShem)
        │         │          │            │            │          │          │
       100×      100×       100×         100×         100×       100×       100×
                                  = 700 sub-agents
```

## Honest scope

- This package ships the **CLI shell + 36 TUI assets + orchestrator client + install-swarm fetcher**.
- The full 44-layer Python swarm is installed on demand via `lvtn install-swarm`. That's a 16 MB download.
- The metanoia Da'ath rotator (Node service on `:4740`) is a separate package — see `https://lvtn.metanoiaunlimited.com`.

## 🛡️ Safety guarantee — no models on your laptop

**This package + the full swarm download will NEVER:**
- Pull LLM model weights (Hugging Face, GGUF, Whisper, etc.)
- Touch your GPU or VRAM
- Install `torch`, `transformers`, `huggingface_hub`, `whisper`, `llama-cpp-python`, `sentence-transformers`, `onnxruntime`, or any model-fetching library

**Worst-case install footprint:** ~110 MB disk, ~500 MB RAM at idle.
**VRAM used:** zero. Designed for an 8 GB laptop.

Every "LLM" in the swarm is an **HTTP API client**. The compute happens on the cloud provider (OpenAI / Anthropic / Cohere / Groq) or on your own VPS running Ollama, vLLM, etc. The lvtn process itself stays light.

Third-party deps used (all pure plumbing, no models):
`aiohttp` · `httpx` · `pyyaml` · `anyio` · `rich` · `python-dotenv` · `cryptography` · `numpy` (L40 only) · `scipy` (L40 only) · `paramiko` / `smbprotocol` (L33 only).

**If you want local model inference**, install Ollama yourself (separate app from `https://ollama.com`) and configure it via env:
```bash
export OLLAMA_LOCAL=http://localhost:11434
lvtn chat --provider ollama
```
That's opt-in. Default behavior reaches out to whatever cloud provider you've keyed.

## License

Proprietary — Metanoia Unlimited LLC. See LICENSE.
