ghostty-ambient 0.6.0__tar.gz

ghostty_ambient-0.6.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: ghostty-ambient
+Version: 0.6.0
+Summary: Ambient light-aware Ghostty theme selector with Bayesian preference learning
+Keywords: ghostty,terminal,theme,ambient,bayesian
+Author: Gezim Basha
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
+Requires-Dist: simple-term-menu>=1.6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: readchar>=4.0.0
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0 ; extra == 'dev'
+Requires-Dist: freezegun>=1.2.0 ; extra == 'dev'
+Requires-Dist: winsdk>=1.0.0b10 ; extra == 'windows'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/gezibash/ghostty-ambient
+Project-URL: Repository, https://github.com/gezibash/ghostty-ambient
+Project-URL: Issues, https://github.com/gezibash/ghostty-ambient/issues
+Provides-Extra: dev
+Provides-Extra: windows
+Description-Content-Type: text/markdown
+
+# Ghostty Ambient
+
+Ambient light-aware theme selector for [Ghostty](https://ghostty.org/) with Bayesian preference learning.
+
+<img src="https://github.com/gezibash/ghostty-ambient/releases/download/v0.1.0/demo.gif" alt="ghostty-ambient demo" />
+
+## Quick Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gezibash/ghostty-ambient/main/install.sh | bash
+```
+
+This installs the package and sets up the learning daemon to run automatically.
+
+## Features
+
+- **Ambient Light Sensing**: Reads your Mac's ambient light sensor to suggest themes appropriate for current lighting
+- **Bayesian Learning**: Learns your color preferences over time—which themes you prefer in different contexts
+- **Context-Aware**: Considers time of day, weather, system dark/light mode, and power source
+- **Theme Generation**: Generates custom themes from your learned preferences (background, contrast, saturation)
+- **Portable Profiles**: Export/import your learned preferences across devices
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add ghostty-ambient
+
+# Using pip
+pip install ghostty-ambient
+```
+
+## Quick Start
+
+### Interactive Theme Picker
+
+```bash
+ghostty-ambient
+```
+
+Shows a picker with theme recommendations based on current conditions. Select a theme to apply it.
+
+### Run the Learning Daemon
+
+```bash
+ghostty-ambient --daemon
+```
+
+Runs in the background, learning your preferences by observing which themes you use in different contexts. Only records when Ghostty is the frontmost application.
+
+### Generate Your Ideal Theme
+
+```bash
+ghostty-ambient --ideal
+```
+
+Generates and applies a custom theme optimized for your current context, based on learned preferences:
+- Background color (light vs dark)
+- Contrast (how much difference between background and foreground)
+- Chroma (color saturation)
+
+## CLI Reference
+
+```
+ghostty-ambient              # Interactive theme picker
+ghostty-ambient --ideal      # Generate and apply optimal theme
+ghostty-ambient --set NAME   # Set theme by name
+ghostty-ambient --stats      # Show learned preferences
+ghostty-ambient --export-profile FILE  # Export preferences
+ghostty-ambient --import-profile FILE  # Import preferences
+ghostty-ambient --favorite   # Mark current theme as favorite
+ghostty-ambient --dislike    # Mark current theme as disliked
+ghostty-ambient --sensors    # Show available light sensors
+ghostty-ambient --setup      # Configure location (for weather)
+```
+
+### Daemon Management
+
+```bash
+ghostty-ambient --status              # Check daemon status
+ghostty-ambient --start               # Start daemon (5m interval)
+ghostty-ambient --start --freq 1m     # Start with custom interval
+ghostty-ambient --stop                # Stop daemon
+ghostty-ambient --restart             # Restart daemon
+ghostty-ambient --logs                # Tail daemon logs
+```
+
+### Run Daemon Inline
+
+```bash
+ghostty-ambient --daemon              # Run daemon in foreground
+ghostty-ambient --daemon --interval 30s  # Custom interval
+```
+
+## How It Works
+
+### Bayesian Preference Learning
+
+The system learns three key properties of your theme preferences:
+
+| Property | What It Learns |
+|----------|----------------|
+| **Background L** | Light vs dark theme preference (LAB lightness) |
+| **Contrast** | Preferred difference between background and foreground |
+| **Chroma** | Preferred color saturation in the palette |
+
+These are learned per-context:
+- Time of day (morning, afternoon, evening, night)
+- Ambient light (dim, office, bright, daylight)
+- System appearance (light mode, dark mode)
+- Power source (AC, battery)
+
+### View Your Learned Preferences
+
+```bash
+ghostty-ambient --stats
+```
+
+```
+By Time of Day
+╭───────────┬───────┬────┬──────────┬────────┬─────╮
+│           │ Theme │  L │ Contrast │ Chroma │   n │
+├───────────┼───────┼────┼──────────┼────────┼─────┤
+│ Morning   │ light │ 97 │       84 │     49 │ 124 │
+│ Afternoon │ light │ 97 │       86 │     50 │ 121 │
+╰───────────┴───────┴────┴──────────┴────────┴─────╯
+```
+
+### Portable Profiles
+
+Export your learned preferences:
+
+```bash
+ghostty-ambient --export-profile ~/my-prefs.json
+```
+
+Import on another device:
+
+```bash
+ghostty-ambient --import-profile ~/my-prefs.json
+```
+
+## Platform Support
+
+| Platform | Ambient Light Sensor | Theme Detection |
+|----------|---------------------|-----------------|
+| macOS    | Native (via `als` helper) | Full support |
+| Linux    | Via `iio-sensor-proxy` | Full support |
+| Windows  | Via Windows SDK | Partial support |
+
+### macOS Ambient Light Sensor
+
+The bundled `als` binary reads the ambient light sensor. To compile from source:
+
+```bash
+clang -framework IOKit -framework CoreFoundation als.m -o als
+```
+
+## Daemon Management
+
+The install script sets up a background daemon that learns your preferences. Use these commands to manage it:
+
+```bash
+ghostty-ambient --status              # Check if daemon is running
+ghostty-ambient --start               # Start the daemon (default 5m interval)
+ghostty-ambient --start --freq 30s    # Start with custom interval
+ghostty-ambient --stop                # Stop the daemon
+ghostty-ambient --restart             # Restart the daemon
+ghostty-ambient --logs                # Tail daemon logs (Ctrl+C to exit)
+```
+
+## Uninstall
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gezibash/ghostty-ambient/main/uninstall.sh | bash
+```
+
+Your learned preferences are preserved in `~/.config/ghostty-ambient/`.
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/gezibash/ghostty-ambient
+cd ghostty-ambient
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Run with verbose output
+uv run ghostty-ambient --daemon --interval 30s
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

ghostty_ambient-0.6.0/README.md

@@ -0,0 +1,197 @@
+# Ghostty Ambient
+
+Ambient light-aware theme selector for [Ghostty](https://ghostty.org/) with Bayesian preference learning.
+
+<img src="https://github.com/gezibash/ghostty-ambient/releases/download/v0.1.0/demo.gif" alt="ghostty-ambient demo" />
+
+## Quick Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gezibash/ghostty-ambient/main/install.sh | bash
+```
+
+This installs the package and sets up the learning daemon to run automatically.
+
+## Features
+
+- **Ambient Light Sensing**: Reads your Mac's ambient light sensor to suggest themes appropriate for current lighting
+- **Bayesian Learning**: Learns your color preferences over time—which themes you prefer in different contexts
+- **Context-Aware**: Considers time of day, weather, system dark/light mode, and power source
+- **Theme Generation**: Generates custom themes from your learned preferences (background, contrast, saturation)
+- **Portable Profiles**: Export/import your learned preferences across devices
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add ghostty-ambient
+
+# Using pip
+pip install ghostty-ambient
+```
+
+## Quick Start
+
+### Interactive Theme Picker
+
+```bash
+ghostty-ambient
+```
+
+Shows a picker with theme recommendations based on current conditions. Select a theme to apply it.
+
+### Run the Learning Daemon
+
+```bash
+ghostty-ambient --daemon
+```
+
+Runs in the background, learning your preferences by observing which themes you use in different contexts. Only records when Ghostty is the frontmost application.
+
+### Generate Your Ideal Theme
+
+```bash
+ghostty-ambient --ideal
+```
+
+Generates and applies a custom theme optimized for your current context, based on learned preferences:
+- Background color (light vs dark)
+- Contrast (how much difference between background and foreground)
+- Chroma (color saturation)
+
+## CLI Reference
+
+```
+ghostty-ambient              # Interactive theme picker
+ghostty-ambient --ideal      # Generate and apply optimal theme
+ghostty-ambient --set NAME   # Set theme by name
+ghostty-ambient --stats      # Show learned preferences
+ghostty-ambient --export-profile FILE  # Export preferences
+ghostty-ambient --import-profile FILE  # Import preferences
+ghostty-ambient --favorite   # Mark current theme as favorite
+ghostty-ambient --dislike    # Mark current theme as disliked
+ghostty-ambient --sensors    # Show available light sensors
+ghostty-ambient --setup      # Configure location (for weather)
+```
+
+### Daemon Management
+
+```bash
+ghostty-ambient --status              # Check daemon status
+ghostty-ambient --start               # Start daemon (5m interval)
+ghostty-ambient --start --freq 1m     # Start with custom interval
+ghostty-ambient --stop                # Stop daemon
+ghostty-ambient --restart             # Restart daemon
+ghostty-ambient --logs                # Tail daemon logs
+```
+
+### Run Daemon Inline
+
+```bash
+ghostty-ambient --daemon              # Run daemon in foreground
+ghostty-ambient --daemon --interval 30s  # Custom interval
+```
+
+## How It Works
+
+### Bayesian Preference Learning
+
+The system learns three key properties of your theme preferences:
+
+| Property | What It Learns |
+|----------|----------------|
+| **Background L** | Light vs dark theme preference (LAB lightness) |
+| **Contrast** | Preferred difference between background and foreground |
+| **Chroma** | Preferred color saturation in the palette |
+
+These are learned per-context:
+- Time of day (morning, afternoon, evening, night)
+- Ambient light (dim, office, bright, daylight)
+- System appearance (light mode, dark mode)
+- Power source (AC, battery)
+
+### View Your Learned Preferences
+
+```bash
+ghostty-ambient --stats
+```
+
+```
+By Time of Day
+╭───────────┬───────┬────┬──────────┬────────┬─────╮
+│           │ Theme │  L │ Contrast │ Chroma │   n │
+├───────────┼───────┼────┼──────────┼────────┼─────┤
+│ Morning   │ light │ 97 │       84 │     49 │ 124 │
+│ Afternoon │ light │ 97 │       86 │     50 │ 121 │
+╰───────────┴───────┴────┴──────────┴────────┴─────╯
+```
+
+### Portable Profiles
+
+Export your learned preferences:
+
+```bash
+ghostty-ambient --export-profile ~/my-prefs.json
+```
+
+Import on another device:
+
+```bash
+ghostty-ambient --import-profile ~/my-prefs.json
+```
+
+## Platform Support
+
+| Platform | Ambient Light Sensor | Theme Detection |
+|----------|---------------------|-----------------|
+| macOS    | Native (via `als` helper) | Full support |
+| Linux    | Via `iio-sensor-proxy` | Full support |
+| Windows  | Via Windows SDK | Partial support |
+
+### macOS Ambient Light Sensor
+
+The bundled `als` binary reads the ambient light sensor. To compile from source:
+
+```bash
+clang -framework IOKit -framework CoreFoundation als.m -o als
+```
+
+## Daemon Management
+
+The install script sets up a background daemon that learns your preferences. Use these commands to manage it:
+
+```bash
+ghostty-ambient --status              # Check if daemon is running
+ghostty-ambient --start               # Start the daemon (default 5m interval)
+ghostty-ambient --start --freq 30s    # Start with custom interval
+ghostty-ambient --stop                # Stop the daemon
+ghostty-ambient --restart             # Restart the daemon
+ghostty-ambient --logs                # Tail daemon logs (Ctrl+C to exit)
+```
+
+## Uninstall
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gezibash/ghostty-ambient/main/uninstall.sh | bash
+```
+
+Your learned preferences are preserved in `~/.config/ghostty-ambient/`.
+
+## Development
+
+```bash
+# Clone and install dev dependencies
+git clone https://github.com/gezibash/ghostty-ambient
+cd ghostty-ambient
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Run with verbose output
+uv run ghostty-ambient --daemon --interval 30s
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

ghostty_ambient-0.6.0/pyproject.toml

@@ -0,0 +1,123 @@
+[project]
+name = "ghostty-ambient"
+version = "0.6.0"
+description = "Ambient light-aware Ghostty theme selector with Bayesian preference learning"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Gezim Basha" }]
+license = "MIT"
+keywords = ["ghostty", "terminal", "theme", "ambient", "bayesian"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Terminals :: Terminal Emulators/X Terminals",
+]
+dependencies = [
+    "simple-term-menu>=1.6.0",
+    "rich>=13.0.0",
+    "numpy>=1.26.0",
+    "readchar>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/gezibash/ghostty-ambient"
+Repository = "https://github.com/gezibash/ghostty-ambient"
+Issues = "https://github.com/gezibash/ghostty-ambient/issues"
+
+[project.optional-dependencies]
+windows = ["winsdk>=1.0.0b10"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "freezegun>=1.2.0",
+]
+
+[project.scripts]
+ghostty-ambient = "ghostty_ambient.cli:main"
+
+# Plugin entry point for third-party sensor backends
+# Example: A custom sensor plugin can register via:
+#   [project.entry-points."ghostty_ambient.sensors"]
+#   my_sensor = "my_package.sensors:MySensorBackend"
+[project.entry-points."ghostty_ambient.sensors"]
+
+[build-system]
+requires = ["uv_build>=0.9.2,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["src/ghostty_ambient"]
+omit = ["src/ghostty_ambient/cli.py", "src/ghostty_ambient/daemon.py", "src/ghostty_ambient/picker.py", "src/ghostty_ambient/browser.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.8.0",
+    "pre-commit>=4.0.0",
+    "gitlint>=0.19.0",
+]
+release = [
+    "python-semantic-release>=9.0.0",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "SIM108", # ternary operators often less readable
+    "SIM105", # contextlib.suppress often less clear
+    "SIM102", # nested if often clearer than combined
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+tag_format = "v{version}"
+branch = "main"
+commit_message = "chore(release): v{version}"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]

ghostty_ambient-0.6.0/src/ghostty_ambient/__init__.py

@@ -0,0 +1,18 @@
+"""ghostty-ambient library modules."""
+
+from .adaptive_scorer import score_themes_adaptive as score_themes
+from .history import History
+from .sensor import get_lux, get_sun_phase, get_sun_times, lux_to_condition
+from .themes import calculate_brightness, load_all_themes, parse_theme
+
+__all__ = [
+    "get_lux",
+    "get_sun_times",
+    "lux_to_condition",
+    "get_sun_phase",
+    "load_all_themes",
+    "parse_theme",
+    "calculate_brightness",
+    "History",
+    "score_themes",
+]