Skip to content

Add gaia init command for one-stop setup#219

Merged
kovtcharov-amd merged 23 commits intomainfrom
kalin/gaia-init
Jan 23, 2026
Merged

Add gaia init command for one-stop setup#219
kovtcharov-amd merged 23 commits intomainfrom
kalin/gaia-init

Conversation

@kovtcharov
Copy link
Collaborator

@kovtcharov kovtcharov commented Jan 22, 2026

Summary

Adds gaia init command for one-stop GAIA setup: installs Lemonade Server and downloads required models.

Changes

  • New gaia init command with profile support (minimal, chat, code, rag, all)
  • Lemonade installer - Downloads from GitHub releases (Windows MSI, Linux DEB)
  • Version checking - Warns on version mismatch, suggests reinstall steps
  • Updated scripts - Changed lemonade-server-dev to lemonade-server in all startup scripts

Usage

gaia init                      # Default chat profile (~25GB)
gaia init --profile minimal    # Fast setup with 4B model (~4GB)
gaia init --yes                # Non-interactive mode
gaia init --skip-models        # Only install Lemonade

Files

New Modified
src/gaia/installer/ src/gaia/cli.py
tests/unit/test_init_command.py setup.py, docs/reference/cli.mdx
scripts/start-lemonade.*

Test Plan

  • Unit tests pass (30 tests)
  • Manual test: gaia init --profile minimal --yes
  • Manual test: gaia init --skip-models

@github-actions github-actions bot added documentation Documentation changes dependencies Dependency updates devops DevOps/infrastructure changes cli CLI changes tests Test changes labels Jan 22, 2026
- Add `gaia install --lemonade` to install Lemonade Server
- Add `gaia uninstall --lemonade` to uninstall (downloads matching MSI)
- Add `gaia kill --lemonade` to kill Lemonade server on port 8000
- Add minimal installer support for --profile minimal
- Update CLI reference docs with new commands
- Update quickstart/setup docs with gaia init step
- Add unit tests for minimal installer URL patterns
- Increase download timeout to 2 hours for large models
- Show filename, speed, and detailed progress info
- Add specific error handling for timeout/connection errors
- List models that need downloading before starting
@github-actions github-actions bot added llm LLM backend changes performance Performance-critical changes labels Jan 22, 2026
kovtcharov and others added 14 commits January 22, 2026 11:28
- Add model verification step with small inference requests
  - Tests LLMs with chat completions
  - Tests embedding models with embeddings API
  - Optional prompt with Ctrl+C skip support
- Refresh PATH from Windows registry after installation
  - Allows current session to find lemonade-server immediately
  - No terminal restart required
- Display lemonade-server installation path in step 1
- Improve gaia llm output with Rich formatting
- Fix None chunk handling in streaming responses
- Improve gaia uninstall console output
  - Rich formatting with colored output
  - Suppress duplicate log messages
- Change model loading log from info to debug level

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
Move speed calculation inside display update condition to prevent
updates every 0.5 seconds. Now only updates every 2% progress change.

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
- Add gaia uninstall --models to clear model cache
  - Deletes models directly from filesystem (no server required)
  - Shows cache location and total size
  - Lists all models with full names
  - Handles locked files gracefully
- Show Lemonade installation path when uninstalling
- Fix Path import shadowing issue

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
- Remove unused variables in progress callback
- Fix f-string without interpolation
- Add pylint disable for protected access to _estimate_model_size
- Add pylint disable for Console import (used in type hints)

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
When models fail verification tests, show commands to:
1. Delete corrupted models: gaia uninstall --models --yes
2. Re-download: gaia init --profile <profile> --yes

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
Prepend registry paths to current PATH instead of replacing it.
This preserves critical paths like System32 (where PowerShell lives)
that are needed by lemonade-server for ZIP extraction.

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
Critical fixes:
- Fix PowerShell not found during model loading
  - Redirect server output to ~/.gaia/lemonade-server.log instead of DEVNULL
  - Windows system() calls need inherited file handles to work
- Expand environment variables in registry PATH (%SystemRoot%, etc.)
- Kill orphaned llama-server.exe processes in gaia kill --lemonade

UI improvements:
- Hide verbose output (paths, status) unless --verbose flag used
- Show server log location in verbose mode
- Fix bitrate indicator flashing by always updating tracking state
- Add manual model deletion instructions with actual file paths
  - Shows platform-specific commands (rmdir vs rm -rf)
  - Searches for actual directory names in cache

Co-Authored-By: Claude Sonnet 4.5 (1M context) <[email protected]>
The unreachable code (129 lines) caused pylint errors and was no longer needed since we switched to prompting users to manually start Lemonade Server instead of automatic startup.

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Code cleanup:
- Remove commented debug print statements from security.py
- Add Windows platform check for taskkill commands in cli.py

Documentation updates:
- Add --models flag and gaia kill command to CLI reference
- Add gaia init mentions to features.mdx
- Add Model Issues section to troubleshooting.mdx
- Add Lemonade Server troubleshooting tips
Ensures gaia llm works after init by always including
DEFAULT_MODEL_NAME in the model list for any profile.
@github-actions github-actions bot added the security Security-sensitive changes label Jan 23, 2026
@kovtcharov kovtcharov self-assigned this Jan 23, 2026
@kovtcharov kovtcharov added this to the v0.15.2 milestone Jan 23, 2026
@kovtcharov
Copy link
Collaborator Author

@claude review this PR in detail.

@github-actions
Copy link

github-actions bot commented Jan 23, 2026

Claude finished @kovtcharov's task —— View job


PR Review: gaia init Command

  • Read PR diff and changed files
  • Review core implementation (init_command.py, lemonade_installer.py)
  • Review CLI integration (cli.py)
  • Review test coverage
  • Review documentation updates
  • Provide detailed review feedback

Summary

This PR adds a comprehensive gaia init command for one-stop GAIA setup. The implementation is well-structured with good separation of concerns between the InitCommand orchestrator and LemonadeInstaller utility class.

Overall Assessment: 🟢 Approve with Minor Suggestions

The code is well-written, follows existing patterns, and includes thorough documentation and tests. Ready to merge after addressing a few minor items.


🟢 Strengths

  1. Clean Architecture - Good separation between InitCommand (orchestration) and LemonadeInstaller (platform-specific installation logic)

  2. Comprehensive Error Handling - Timeout handling, connection errors, and user-friendly error messages throughout

  3. Cross-Platform Support - Windows (MSI) and Linux (DEB) properly handled with clear unsupported platform messaging

  4. Good Test Coverage - 30 unit tests covering version parsing, platform detection, download URLs, installation logic, and profile validation

  5. Documentation - CLI docs are thorough with examples for all profiles and options


🟡 Minor Suggestions

1. Potential NoneType Error in _install_lemonade

src/gaia/installer/init_command.py:554-559

self.console.print("   [bold]Installing...[/bold]")
self.console.print()

If Rich is not available, self.console will be None and this will raise AttributeError. Should use self._print() or add a guard:

if self.console:
    self.console.print("   [bold]Installing...[/bold]")
    self.console.print()

This pattern appears in several other places where self.console.print() is called directly without checking RICH_AVAILABLE.

Affected lines: 554-559, 567, 572, 697-709, 714-715, 719, 723, 741-744, 1167-1174, 1181-1183, 1193-1201, 1210-1217, 1228-1285

2. Consider Adding Retry Logic for Downloads

src/gaia/installer/lemonade_installer.py:275-346

Network downloads can be flaky. Consider adding a simple retry mechanism (1-2 retries) for the installer download.

3. Hardcoded Paths Could Be Constants

src/gaia/installer/init_command.py:625-640

The Windows installation paths are hardcoded. Consider extracting to module-level constants for easier maintenance:

WINDOWS_INSTALL_PATHS = [
    r"%LOCALAPPDATA%\Programs\Lemonade Server\lemonade-server.exe",
    # ...
]

4. Missing --minimal Flag in Help Text

The --minimal flag is documented in cli.mdx as a shortcut for --profile minimal, but I don't see it listed in the argparser configuration. Verify this is properly wired up.


🟢 Security Considerations

  • ✅ Downloads from fixed GitHub release URLs (no user-controlled URLs)
  • ✅ Uses subprocess.run with explicit arguments (no shell injection)
  • ✅ Proper timeout handling prevents hanging
  • ✅ No secrets or credentials in code

🟢 Testing Notes

  • Unit tests properly mock network calls and subprocess
  • Tests cover edge cases (invalid profiles, version parsing)
  • Integration tests would benefit from CI validation on actual Windows/Linux

Files Reviewed

File Lines Notes
src/gaia/installer/init_command.py 1388 Main orchestration, well-structured
src/gaia/installer/lemonade_installer.py 619 Platform-specific install logic
src/gaia/installer/__init__.py 23 Clean exports
tests/unit/test_init_command.py 293 Good coverage
docs/reference/cli.mdx +208 Comprehensive docs
docs/quickstart.mdx +53 Updated for gaia init
scripts/start-lemonade.* New CI/CD helper scripts

Recommendation: Merge after addressing the console.print() null-safety issue.

@kovtcharov-amd kovtcharov-amd added this pull request to the merge queue Jan 23, 2026
Merged via the queue into main with commit 8c65743 Jan 23, 2026
65 checks passed
@kovtcharov-amd kovtcharov-amd deleted the kalin/gaia-init branch January 23, 2026 17:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cli CLI changes dependencies Dependency updates devops DevOps/infrastructure changes documentation Documentation changes llm LLM backend changes performance Performance-critical changes security Security-sensitive changes tests Test changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants