Phase 17 — pip Packaging + `local2` CLI ✅ COMPLETE

Make LoCAL2 installable as a standard Python package. The install story goes from "clone repo, manage paths manually" to pip install local2.

Motivation

Phase 16 delivered the web UI. The remaining friction to sharing LoCAL2 was the install story: users had to clone the repo, set PYTHONPATH, and figure out SearXNG setup themselves. Phase 17 resolves this with a proper pyproject.toml, a local2 CLI entry point that handles first-run setup, and a data directory (~/.local2/) that stores user config outside the repo.

Install story after Phase 17: pip install local2 → local2 setup → local2 → open browser

Milestones

17.1 — pyproject.toml + hatchling build

Replace setup.py / requirements.txt with a pyproject.toml using hatchling as the build backend. All runtime dependencies declared. The React frontend/dist/ bundle is included as a build artifact so it ships with the wheel.

Build backend: hatchling
Package name: local2
Entry point: local2 = "local.cli:main"
Artifacts: src/local/api/static/** (React build output)
Python ≥ 3.11 required

Dependencies declared

ollama, fastapi, uvicorn, websockets, pydantic, pyzmq, PySide6,
PyYAML, httpx, python-multipart, beautifulsoup4, chromadb, pypdf

Files

pyproject.toml — build config, deps, entry point
requirements.txt — superseded by pyproject.toml deps

17.2 — Data directory (`~/.local2/`)

User config, SearXNG docker-compose, and generated secrets live in ~/.local2/ — not inside the repo or install path. This lets the package be updated without clobbering user settings.

~/.local2/config/*.yaml — user YAML configs (copied from package defaults on first local2 setup)
~/.local2/docker-compose.yml — SearXNG compose file
~/.local2/searxng/ — SearXNG settings directory
~/.local2/.env — auto-generated MY_SEARX_SECRET
LOCAL2_DATA_DIR env var overrides the default path

Files

src/local/data_dir.py — get_data_dir(), get_defaults_dir()
src/local/config/config_loader.py — reads YAML from data dir first, falls back to package defaults

17.3 — `local2` CLI entry point

A single local2 command handles all startup modes and first-run setup. Delegates to src/local/run.py for the main runtime.

local2                       # web UI, opens browser
local2 --headless            # web server only (no browser pop)
local2 --panels              # web UI + Qt observer panels
local2 --desktop             # legacy PySide6 UI
local2 setup                 # init config + pull Ollama models
local2 setup --models-only   # re-pull models only
local2 setup --config-only   # re-init config only
local2 searxng up            # start SearXNG in Docker
local2 searxng down          # stop SearXNG
local2 searxng status        # show container status

Files

src/local/cli.py — entry point registered in pyproject.toml
src/local/run.py — main runtime (moved from run_local.py)

17.4 — File attachments in web UI

Paperclip button in the web chat interface. Files are uploaded via POST /api/attachments, stored server-side for the duration of the query, and passed through the WebSocket → session → bus pipeline to the GeneratorAgent.

Paperclip button opens file picker; attached filenames shown as chips
Images: base64-encoded → Ollama images field (same path as Qt Phase 7)
PDFs / text: extracted server-side, prepended to user message content
Dependency added: python-multipart

Files

src/local/api/gateway.py — POST /api/attachments endpoint
frontend/src/components/MessageInput.tsx — paperclip button + chip display

17.5 — Remote-bus mode (`--web-only` / `--ipaddress`)

Enables a split deployment where the web server runs on one machine and the agent bus runs on another (LAN use case). The web server connects to a remote ZMQ proxy rather than starting its own.

--web-only — start FastAPI + WebSocket bridge only; no local agents
--ipaddress IP — connect to ZMQ proxy at IP (sets LOCAL2_PROXY_HOST)
Use case: run agents on a GPU machine, open browser on a laptop on the same LAN

Files

src/local/run.py — --web-only, --ipaddress args; LOCAL2_PROXY_HOST env

File Map

File	Status	Notes
`pyproject.toml`	new	hatchling build, all deps, local2 entry point, frontend/dist artifact
`src/local/cli.py`	new	local2 CLI: setup, searxng subcommands; delegates to run.py
`src/local/run.py`	new	main runtime moved from run_local.py; --web-only/--ipaddress flags
`src/local/data_dir.py`	new	get_data_dir() → ~/.local2/; LOCAL2_DATA_DIR override
`src/local/api/gateway.py`	modified	POST /api/attachments endpoint; python-multipart dep
`frontend/src/components/MessageInput.tsx`	modified	paperclip button, attachment chip display
`run_local.py`	kept	thin shim delegating to src/local/run.py for dev-mode runs

Run Modes After Phase 17

# Standard (pip install)
pip install local2
local2 setup        # first run: write config, pull models
local2              # open browser → localhost:8080

# Dev (repo checkout)
python run_local.py              # same as local2
python run_local.py --headless   # no browser
python run_local.py --panels     # Qt observer panels alongside web UI
python run_local.py --desktop    # legacy PySide6 UI

# Remote / LAN split
local2 --ipaddress 192.168.1.42 --web-only   # web layer only, bus on remote machine

# SearXNG
local2 searxng up      # start Docker container
local2 searxng status  # check it's running
local2 searxng down    # stop it

Acceptance Criteria

pip install -e . succeeds; local2 --help runs without error
local2 setup writes YAML configs to ~/.local2/config/ and pulls Ollama models
local2 searxng up/down/status manages the Docker container using ~/.local2/docker-compose.yml
File attachment in web UI: image sent to Gemma vision; PDF/text content prepended to message
--web-only --ipaddress X connects to remote ZMQ proxy; queries complete end-to-end
All existing Python tests continue to pass
Version: 0.1.9

What's Next

PyPI publish (hatch publish) — not yet done; package is installable from source
Developer mode (16.6) — bus stream panel, per-participant observability in web UI
PySide6 removal — kept as fallback; can remove once web UI reaches full feature parity
Docker image / one-command install for non-Python users

Phase 17 — pip Packaging + local2 CLI ✅ COMPLETE

Motivation

Milestones

17.1 — pyproject.toml + hatchling build

Dependencies declared

Files

17.2 — Data directory (~/.local2/)

Files

17.3 — local2 CLI entry point

Files

17.4 — File attachments in web UI

Files

17.5 — Remote-bus mode (--web-only / --ipaddress)

Files

File Map

Run Modes After Phase 17

Acceptance Criteria

What's Next

Phase 17 — pip Packaging + `local2` CLI ✅ COMPLETE

17.2 — Data directory (`~/.local2/`)

17.3 — `local2` CLI entry point

17.5 — Remote-bus mode (`--web-only` / `--ipaddress`)