259 lines
8.3 KiB
Markdown
Executable File
259 lines
8.3 KiB
Markdown
Executable File
# Quickstart Guide
|
||
|
||
Get AI Local Stack Control up and running in under 5 minutes.
|
||
|
||
## Prerequisites
|
||
|
||
| Requirement | Minimum | Recommended |
|
||
|-------------|---------|-------------|
|
||
| OS | Arch Linux | Arch Linux / EndeavourOS |
|
||
| Python | 3.11 | 3.12+ |
|
||
| RAM | 8 GB | 16 GB+ (for LLM inference) |
|
||
| Disk | 4 GB free | 20 GB+ (for model storage) |
|
||
| GPU | None | NVIDIA (CUDA) or AMD (ROCm) |
|
||
|
||
## Installation
|
||
|
||
### Option 1: Bootstrap Script (Recommended)
|
||
|
||
```bash
|
||
# Clone the repository
|
||
git clone https://github.com/your-username/ai-lsc.git
|
||
cd ai-lsc
|
||
|
||
# Run the bootstrap script (installs system + Python deps)
|
||
chmod +x bootstrap.sh
|
||
./bootstrap.sh
|
||
|
||
# Launch the application
|
||
python -m ai_lsc
|
||
```
|
||
|
||
### Option 2: Manual Install
|
||
|
||
#### Step 1: System Dependencies
|
||
|
||
```bash
|
||
# Core packages (Arch Linux)
|
||
sudo pacman -S python python-pip pyside6 \
|
||
git tmux ripgrep fd tree-sitter sqlite redis
|
||
|
||
# Optional: GPU support
|
||
sudo pacman -S cuda # NVIDIA
|
||
# sudo pacman -S rocm-hip-sdk # AMD
|
||
|
||
# Optional: Container runtimes
|
||
sudo pacman -S podman docker
|
||
# Optional: LXC support
|
||
sudo pacman -S lxc lxcfs
|
||
```
|
||
|
||
#### Step 2: Python Dependencies
|
||
|
||
```bash
|
||
cd ai-lsc
|
||
|
||
# Create a virtual environment (recommended)
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
|
||
# Install PySide6 and dependencies
|
||
pip install PySide6
|
||
pip install -e .
|
||
```
|
||
|
||
#### Step 3: Verify Installation
|
||
|
||
```bash
|
||
# Check that the registry loads correctly
|
||
python -c "
|
||
from ai_lsc import DEFAULT_REGISTRY, validate_registry
|
||
errors = validate_registry(DEFAULT_REGISTRY)
|
||
print(f'Registry loaded: {len(DEFAULT_REGISTRY)} tools')
|
||
print(f'Validation errors: {len(errors)}')
|
||
"
|
||
|
||
# Expected output (v3.1):
|
||
# Registry loaded: 125 tools
|
||
# Validation errors: 0
|
||
```
|
||
|
||
#### Step 4: Launch
|
||
|
||
```bash
|
||
python -m ai_lsc
|
||
```
|
||
|
||
## First Launch
|
||
|
||
When you launch AI-LSC for the first time, you will see the **Stack Template Wizard**. This is your entry point for configuring your AI stack.
|
||
|
||
### Choosing a Template
|
||
|
||
| Template | Best For | Tool Count |
|
||
|----------|----------|-----------|
|
||
| Claude Code Setup | Claude Code development workflow | 11 |
|
||
| Free Claude Code | Minimal Claude Code environment | 4 |
|
||
| Local LLM Lab | Self-hosted LLM experimentation | 10 |
|
||
| SaaS Integrations | Production deployment with SSL/CDN | 12 |
|
||
|
||
### Manual Configuration
|
||
|
||
If you prefer to build your stack from scratch:
|
||
|
||
1. Select **Create From Scratch** in the wizard
|
||
2. Navigate to the **Infrastructure** section in the sidebar
|
||
3. Expand each layer and toggle tools on/off
|
||
4. Use the **IPC Stack** tab to validate dependencies
|
||
5. Click **Compile** to save your stack configuration
|
||
|
||
### Watching the Pipeline Ticker
|
||
|
||
Once you have tools staged, the **Pipeline Ticker** at the top of every tab comes alive. It scrolls horizontally through the wiring topology of your active tools:
|
||
|
||
- `provider ──interface──▶ consumer` shows the data-flow direction
|
||
- Arrow color encodes the interface type (blue = openai_api, green = vector, orange = redis_pubsub, purple = postgresql, teal = http_api)
|
||
- Tools with no in-stack wiring are flagged red with an `❗` prefix — these are orphans worth investigating (either they're missing a `STACK_WIRINGS` entry in `stack/connections.py`, or the tools they wire to aren't yet staged)
|
||
- Hover over the ticker to pause the scroll
|
||
- Click any tool pill to jump to the Tools tab — the matching row is selected, scrolled to center, and flashed amber for 1.5 s
|
||
|
||
The ticker refreshes automatically on every service-status poll (every 2 s by default) so running-state color changes (stopped → running) propagate immediately.
|
||
|
||
### Using the Workspace Tab
|
||
|
||
The **Workspace** nav entry (between Chat and Git Sources) is your peek-style orchestration surface — think virt-manager for your AI stack. After you stage + start tools:
|
||
|
||
1. Click **Workspace** in the sidebar
|
||
2. You'll see one sub-tab per active tool, prefixed with an emoji:
|
||
- 🌐 — web-interface tool (OpenWebUI, Hermes, Odysseus, etc.)
|
||
- ⌨ — CLI tool (Aider, Claude Code, OpenHands, etc.)
|
||
- 📦 — passive / library tool (no interactive surface)
|
||
- ⏸ suffix — tool is staged but not yet running
|
||
3. For web tools: the sub-tab embeds the tool's web UI directly via `QWebEngineView` at `http://127.0.0.1:{port}` — no need to leave the app for a browser. A URL bar at the top shows the loaded URL; click ⟳ to reload or ↗ to open in an external browser
|
||
4. For CLI tools: the sub-tab embeds the tool's tmux session output, polled at 4 Hz via `tmux capture-pane`. The terminal is read-only — use a real terminal app for interactive input
|
||
5. For not-yet-running tools: the sub-tab shows a **Start tool** button that wires back to the existing service-start flow
|
||
6. Close a sub-tab with the × button — this stops the polling but does NOT stop the underlying tool (use the Stack Editor for that)
|
||
|
||
> **Servo note:** Web embedding uses `QWebEngineView` by default. To swap in Mozilla's servo engine later, replace `_make_web_view()` in `src/ai_lsc/ui/widgets/workspace_tab.py` — the rest of the WorkspaceTab code only depends on the `setUrl()` / `url()` / `load()` API.
|
||
|
||
## Post-Setup
|
||
|
||
### Installing a Base LLM
|
||
|
||
Most tools depend on Ollama as the local LLM runtime:
|
||
|
||
```bash
|
||
# Install Ollama (if not already installed)
|
||
curl -fsSL https://ollama.com/install.sh | sh
|
||
|
||
# Pull a model
|
||
ollama pull llama3
|
||
ollama pull codellama # Good for coding assistance
|
||
ollama pull mistral # Lightweight general-purpose
|
||
```
|
||
|
||
### Starting Services
|
||
|
||
After configuring your stack in the IPC Stack tab:
|
||
|
||
1. Click **Compile** to save the stack configuration
|
||
2. Switch to the **Monitor** tab
|
||
3. Click **Start All** or start individual services
|
||
4. Check service status indicators (green = running)
|
||
5. Watch the **Pipeline Ticker** at the top of the screen — pills turn blue as their tools come online
|
||
6. Switch to the **Workspace** tab to interact with each running tool in its own sub-tab
|
||
|
||
### Connecting the Chat Console
|
||
|
||
Once Ollama is running:
|
||
|
||
1. Navigate to the **Chat** section
|
||
2. Select a model from the dropdown (e.g., `llama3`, `codellama`)
|
||
3. Start chatting with your local AI assistant
|
||
|
||
## Common Tasks
|
||
|
||
### Adding a New Tool
|
||
|
||
1. Identify the target layer in `registry/layers/`
|
||
2. Add the tool entry following the canonical schema
|
||
3. Restart the application — the tool appears automatically
|
||
|
||
### Exporting to Containers
|
||
|
||
1. Open **Deployment Targets** from the sidebar
|
||
2. Select your backend: Podman, Docker, or LXC
|
||
3. Click **Export** to generate configuration files
|
||
4. Deploy with `podman compose up` or `lxc-launch.sh`
|
||
|
||
### Managing LXC Containers
|
||
|
||
```bash
|
||
# Create a container from exported config
|
||
sudo lxc-create -n ollama -f ollama.conf
|
||
|
||
# Start the container
|
||
sudo lxc-start -n ollama
|
||
|
||
# Attach to the container console
|
||
sudo lxc-attach -n ollama
|
||
|
||
# Freeze/unfreeze
|
||
sudo lxc-freeze -n ollama
|
||
sudo lxc-unfreeze -n ollama
|
||
|
||
# Destroy
|
||
sudo lxc-stop -n ollama
|
||
sudo lxc-destroy -n ollama
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### PySide6 Import Error
|
||
|
||
```
|
||
ModuleNotFoundError: No module named 'PySide6'
|
||
```
|
||
|
||
**Fix:** Install PySide6: `pip install PySide6`
|
||
|
||
### Registry Loading Errors
|
||
|
||
```
|
||
ERROR: Failed to load layer file: SyntaxError
|
||
```
|
||
|
||
**Fix:** Validate layer files:
|
||
```bash
|
||
python3 -c "
|
||
import ast, os
|
||
for f in os.listdir('ai_lsc/registry/layers'):
|
||
if f.endswith('.py') and f != '__init__.py':
|
||
ast.parse(open(f'ai_lsc/registry/layers/{f}').read())
|
||
print(f'{f}: OK')
|
||
"
|
||
```
|
||
|
||
### Service Won't Start
|
||
|
||
1. Check the **Monitor** tab for error messages
|
||
2. Verify the tool is installed: `which <tool_name>`
|
||
3. Check launcher command in the registry entry
|
||
4. For systemd services: `systemctl --user status <service>`
|
||
|
||
### Ollama Connection Refused
|
||
|
||
1. Ensure Ollama is running: `ollama serve` or `systemctl --user start ollama`
|
||
2. Check port: `curl http://localhost:11434/api/tags`
|
||
3. Verify the endpoint in Settings matches your Ollama port
|
||
|
||
## Next Steps
|
||
|
||
- Explore the **Infrastructure** section to understand the 13-layer architecture
|
||
- Try different **Stack Templates** to find the right combination for your workflow
|
||
- Set up the **Skills Console** to extend your tool capabilities
|
||
- Use **Code Analysis** to inspect and understand your project dependencies
|
||
- Read [CHANGES.md](CHANGES.md) for the full v3.1 changelog
|
||
- Read [whatremains.txt](whatremains.txt) for known deferred items (curl|sh installers, etc.)
|
||
- Read [docs/ADR-002-pipeline-ticker.md](docs/ADR-002-pipeline-ticker.md) and [docs/ADR-003-workspace-tab.md](docs/ADR-003-workspace-tab.md) for the design rationale behind the two new widgets
|