lai-setup · diff
git:20260412.c7d541e to git:20260417.89d056b
243 added, 19 removed. Audit A to A.
---
name: lai-setup
- description: Install LattifAI and get a free trial API key. Trigger on first mention of LattifAI / `lai`, authentication errors, trial requests, or "how do I get started with alignment" / "我想做字幕对齐" before `lai --version` is verified. Do NOT trigger when already authenticated — route to `/lai-align`, `/lai-transcribe`, etc.
+ description: Use when the user needs to install LattifAI, authenticate, get a trial key, run diagnostics, or configure the CLI. Use this skill whenever the user mentions LattifAI for the first time, asks about API keys, wants to set up audio-text alignment tools, mentions "lai" CLI, asks about trial access, or encounters authentication errors. Also triggers on "install lattifai", "setup lai", "get API key", "lai auth", "lai doctor", "配置 LattifAI", "安装", "认证", "试用", even if they just say "how do I get started with alignment" or "I need to align some captions" without having LattifAI installed yet.
allowed-tools: Read, Bash(lai:*), Bash(pip:*)
---
# LattifAI Setup
- LattifAI aligns captions to audio at word-level precision. Two steps to get started.
+ Get from zero to a working LattifAI environment in under 2 minutes.
- ## 1. Install
+ ## When to Use
+ - User mentions LattifAI for the first time in a project
+ - Need to install or update the `lai` CLI
+ - Authentication issues (expired key, missing key, trial expired)
+ - Environment diagnostics (`lai doctor`)
+ - Configuration management (`lai config`)
+
+ ## When NOT to Use
+
+ - Already set up and authenticated -- jump to `/lai-align`, `/lai-transcribe`, etc.
+ - Issues with a specific feature (alignment, transcription) -- use the feature-specific skill
+
+ ## Installation
+
+ ### Quick Install (pip)
+
```bash
+ pip install lattifai
+ ```
+
+ ### Full Install (all optional dependencies)
+
+ ```bash
+ pip install "lattifai[all]"
+ ```
+
+ ### From Private Index (if not on public PyPI yet)
+
+ ```bash
pip install lattifai --extra-index-url https://lattifai.github.io/pypi/simple/
```
- Requires Python 3.10+.
+ ### Verify Installation
- ## 2. Get a Free Trial Key
+ ```bash
+ lai --version
+ ```
- No sign-up. 2 hours of alignment credits, valid 7 days.
+ ## Authentication
+ LattifAI alignment requires an API key. Three paths to get one:
+
+ ### Path 1: Free Trial (Recommended for First-Time Users)
+
+ No sign-up required. Grants 2 hours of alignment credits, valid for 7 days.
+
```bash
lai auth trial
```
- The output shows your credits and expiry. You're ready.
+ Output shows credits remaining and expiry date. When trial expires:
+ - `lai auth logout` to clear, then `lai auth trial` for a new trial
+ - Or `lai auth login` to upgrade to a full account
- To double-check the environment any time: `lai doctor` (FAIL rows include a fix suggestion).
+ ### Path 2: Browser Login (Full Account)
- ## Common Issues
+ Opens browser for OAuth login. Creates a device-bound session.
- | Problem | Fix |
- |---------|-----|
- | `pip` can't find lattifai | Re-run with `--extra-index-url https://lattifai.github.io/pypi/simple/` |
- | `lai auth trial` returns 429 | Trial already used on this device — run `lai auth login` for a full account |
- | API key invalid / expired | `lai auth logout`, then `lai auth trial` or `lai auth login` |
- | Outdated package | `lai update` |
+ ```bash
+ lai auth login
+ ```
+ For headless / SSH environments where browser is unavailable:
+ 1. Run `lai auth login` on the remote machine
+ 2. Copy the printed URL to a machine with a browser
+ 3. Complete login in the browser
+ 4. Copy the verification code back to the terminal
+
+ ### Path 3: Manual API Key
+
+ For CI/CD or when you already have a key from https://lattifai.com/dashboard/api-keys:
+
+ ```bash
+ lai auth login --api-key
+ # Prompts for key input (hidden)
+ ```
+
+ Or set the environment variable directly:
+
+ ```bash
+ export LATTIFAI_API_KEY="your-key-here"
+ ```
+
+ ### Check Current Session
+
+ ```bash
+ lai auth whoami
+ ```
+
+ ### Logout
+
+ ```bash
+ lai auth logout
+ ```
+
+ ## Diagnostics
+
+ Run a full environment check:
+
+ ```bash
+ lai doctor
+ ```
+
+ Checks:
+ - OS and Python version (3.10--3.14 required)
+ - Package version (current vs latest)
+ - Editable install sync status
+ - GPU acceleration (CUDA, CoreML, MPS, MLX)
+ - Lattice-1 model cache
+ - API key presence and source
+ - Critical dependencies (k2py, onnxruntime, lattifai-core)
+ - Self-test (bundled data, caption roundtrip, audio loading)
+
+ **Interpreting results:**
+ - `OK` -- all good
+ - `WARN` -- non-blocking, works but suboptimal
+ - `FAIL` -- blocking, must fix before alignment works
+
+ Common fixes:
+ | Issue | Fix |
+ |-------|-----|
+ | Package outdated | `lai update` |
+ | Stale editable install | `lai update` or `pip install --no-deps -e .` |
+ | Missing dependencies | `pip install "lattifai[all]"` |
+ | No GPU acceleration | Install `onnxruntime-gpu` (CUDA) or use CPU (slower but works) |
+ | Model not cached | Runs auto-download on first `lai alignment align` |
+
+ ## Configuration
+
+ Persistent settings stored in `~/.lattifai/config.toml`.
+
+ ### Set a value
+
+ ```bash
+ lai config set GEMINI_API_KEY sk-xxx
+ lai config set transcription.model_name gemini-2.5-flash
+ lai config set diarization.infer_speakers true
+ ```
+
+ ### Get a value
+
+ ```bash
+ lai config get GEMINI_API_KEY
+ lai config get transcription.model_name
+ ```
+
+ ### List all settings
+
+ ```bash
+ lai config list
+ ```
+
+ ### Key Configuration Keys
+
+ | Key | Description |
+ |-----|-------------|
+ | `LATTIFAI_API_KEY` | LattifAI API key (set via `lai auth`) |
+ | `GEMINI_API_KEY` | Google Gemini API key (for transcription) |
+ | `OPENAI_API_KEY` | OpenAI-compatible API key (for translation/summarization) |
+ | `OPENAI_API_BASE_URL` | Custom OpenAI-compatible endpoint |
+ | `transcription.model_name` | Default transcription model |
+ | `diarization.infer_speakers` | Auto-infer speaker names via LLM |
+ | `summarization.llm.model_name` | LLM model for summarization |
+ | `translation.llm.model_name` | LLM model for translation |
+
+ ### Priority Order
+
+ For any setting: **CLI argument > config.toml > environment variable > default**
+
+ ## Workflow
+
+ ### Step 1 -- Check if LattifAI is installed
+
+ ```bash
+ lai --version
+ ```
+
+ If not installed, install with `pip install lattifai`.
+
+ ### Step 2 -- Run diagnostics
+
+ ```bash
+ lai doctor
+ ```
+
+ Fix any FAIL issues before proceeding.
+
+ ### Step 3 -- Authenticate
+
+ For new users:
+ ```bash
+ lai auth trial
+ ```
+
+ For returning users:
+ ```bash
+ lai auth whoami
+ ```
+
+ If expired or invalid:
+ ```bash
+ lai auth logout
+ lai auth login
+ ```
+
+ ### Step 4 -- Configure API keys (if needed)
+
+ For transcription (Gemini):
+ ```bash
+ lai config set GEMINI_API_KEY your-gemini-key
+ ```
+
+ For translation/summarization (OpenAI-compatible):
+ ```bash
+ lai config set OPENAI_API_KEY your-key
+ lai config set OPENAI_API_BASE_URL http://localhost:8000/v1 # optional
+ ```
+
+ ### Step 5 -- Verify with a quick test
+
+ ```bash
+ lai alignment align --help
+ ```
+
+ ## Error Handling
+
+ | Condition | Action |
+ |-----------|--------|
+ | `pip install` fails | Check Python version (3.10+), try `--extra-index-url` |
+ | `lai auth trial` returns 429 | Trial limit reached for this device. Use `lai auth login` |
+ | `lai auth login` timeout | Copy URL manually to browser, paste verification code |
+ | `lai doctor` shows FAIL | Follow the specific fix suggestion in the output |
+ | API key invalid/expired | `lai auth logout` then `lai auth login` or `lai auth trial` |
+
+ ## Update
+
+ ```bash
+ lai update
+ ```
+
+ Or force reinstall:
+
+ ```bash
+ lai update --force
+ ```
+
## Related Skills
- Once authenticated, jump straight to the feature you need:
+ | Skill | Use After Setup |
+ |-------|----------------|
+ | `/lai-align` | Run your first forced alignment |
+ | `/lai-transcribe` | Transcribe audio/video |
+ | `/lai-youtube` | Process YouTube videos |
- - `/lai-align` — align audio + existing captions
- - `/lai-transcribe` — transcribe audio/video from scratch (also covers Gemini API key setup)
- - `/lai-youtube` — process a YouTube video end-to-end
+ ## Non-Goals
+
+ - Does NOT install Python itself -- user must have Python 3.10+ pre-installed
+ - Does NOT manage virtual environments -- user chooses their own env manager
+ - Does NOT configure IDE integrations -- this is CLI-only setup