calm-cli 0.3.0__tar.gz

calm_cli-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Bhattacharya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

calm_cli-0.3.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: calm-cli
+Version: 0.3.0
+Summary: [C]alm [A]nswers via (local) [L]anguage [M]odels
+Keywords: cli,llm,mlx,macos,terminal
+Author: Abhishek Bhattacharya
+Author-email: Abhishek Bhattacharya <babhishek21@yahoo.co.in>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Utilities
+Requires-Dist: mlx-lm>=0.31.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/quirkdom/calm
+Project-URL: Repository, https://github.com/quirkdom/calm.git
+Project-URL: Issues, https://github.com/quirkdom/calm/issues
+Description-Content-Type: text/markdown
+
+# calm
+
+**C**alm **A**nswers via (local) **L**anguage **M**odels
+
+`calm` is a CLI tool that answers simple questions using a local language model. `calm` runs and communicates with the `calmd` LM server daemon.
+
+Currently, only running **MLX** models on **Apple Silicon Macs** is supported. Please open an issue on GitHub to request other model backends and platforms.
+
+## Quick Start
+
+### Installation
+
+```bash
+brew install quirkdom/tap/calm  # Recommended. Easy and straightforward.
+
+# Package managers
+pipx install calm-cli
+uv tool install calm-cli
+python -m pip install calm-cli
+```
+
+The PyPI package name is `calm-cli`, but the installed commands are still `calm` and `calmd`.
+
+### First run
+
+```bash
+calm "what's running on port 3567?"
+```
+
+On first run `calm` will start `calmd` in the background, which will configure itself, load models and respond to your query. This may take a while depending on your system and network speed.
+
+### Examples
+
+```bash
+calm -y "top 5 memory processes"                # YOLO. Autoruns suggested command
+calm -f "kill what's running on port 3567"      # bypass dangerous command execution protection
+ps aux | calm "largest memory users"
+git diff | calm "summarize what changed"
+```
+
+### Steering and Guardrails
+
+You can force a specific output type using the `-c` (`--command`) or `-a` (`--analysis`) flags:
+
+- **Force Command**: `calm -c "what's on port 3000"` ensures the model suggests a runnable command.
+- **Force Analysis**: `calm -a "install git"` ensures the model provides an explanation instead of a command.
+
+These flags also act as strict guardrails; if the model provides a mismatched type, the CLI will error out and refuse the output.
+
+## What's under the hood?
+
+Please read [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Appendix
+
+### Configuration
+
+`calm` and `calmd` read `~/.config/calm/config.toml`.
+
+`calmd` creates this file with defaults on first start if it does not exist.
+Per-key precedence is: CLI flag > environment variable > config file > hardcoded default.
+
+```toml
+[common]
+socket_path = "~/.cache/calmd/socket"
+
+[cli]
+wait_timeout_secs = 300
+shutdown_timeout_secs = 2
+
+[daemon]
+model_path = "mlx-community/Qwen3.5-9B-OptiQ-4bit"
+use_fast_model = false  # Default fast model is mlx-community/Qwen3.5-4B-OptiQ-4bit
+verbose = false
+skip_warmup = false
+idle_offload_secs = 450
+
+[backend]
+disable_prefix_cache = false
+max_kv_size = 4096
+```
+
+For the full list of environment variable overrides, local development commands, and benchmark instructions, see [DEVELOPMENT.md](DEVELOPMENT.md).
+
+### `calmd` Auto-Start and Offload
+
+#### Auto-start
+
+`calm` auto-starts `calmd` if needed, preferring to start a managed service (Homebrew service or custom LaunchAgent) first. If neither managed option exists, `calm` may start an unmanaged `calmd` just to serve the request.
+
+This unmanaged fallback can't be administered by `calm -d`. You can always ask `calm` to help terminate the unmanaged daemon later:
+
+```bash
+> uv run calm 'terminate the calmd python daemon'
+pkill -f "calmd"
+
+Run this command? [y/N]
+```
+
+#### Offload
+
+`calmd` automatically offloads models after periods of inactivity to save memory. This can be configured with the `idle_offload_secs` config option.
+
+You can also manually trigger an offload using the `offload` command:
+
+```bash
+calm -d offload
+```
+
+### Running `calmd` as a login service
+
+#### Homebrew-managed service
+
+If installed via Homebrew, use Homebrew service management:
+
+```bash
+brew services start calm
+brew services stop calm
+```
+
+When a Homebrew service is installed, plain `calm` queries will prefer that service. Use `brew services` to administer it.
+
+#### Custom LaunchAgent managed by `calm -d`
+
+If you installed via PyPI, `pipx`, `uv tool`, or another non-Homebrew path, you can install a per-user LaunchAgent:
+
+```bash
+calm -d install
+calm -d start
+```
+
+Other useful commands:
+
+```bash
+calm -d offload
+calm -d stop
+calm -d uninstall
+```
+
+`calm -d install`, `start`, `stop`, and `uninstall` manage only the custom LaunchAgent created by `calm -d install`.
+If a Homebrew service is installed, use `brew services` instead.
+
+LaunchAgent logs are written to `~/Library/Logs/calmd/`.
+
+For daemon startup diagnostics, set `CALM_DEBUG_DAEMON=1` before running `calm`. This prints `launchctl` timing and daemon start-path debug logs to stderr.

calm_cli-0.3.0/README.md

@@ -0,0 +1,145 @@
+# calm
+
+**C**alm **A**nswers via (local) **L**anguage **M**odels
+
+`calm` is a CLI tool that answers simple questions using a local language model. `calm` runs and communicates with the `calmd` LM server daemon.
+
+Currently, only running **MLX** models on **Apple Silicon Macs** is supported. Please open an issue on GitHub to request other model backends and platforms.
+
+## Quick Start
+
+### Installation
+
+```bash
+brew install quirkdom/tap/calm  # Recommended. Easy and straightforward.
+
+# Package managers
+pipx install calm-cli
+uv tool install calm-cli
+python -m pip install calm-cli
+```
+
+The PyPI package name is `calm-cli`, but the installed commands are still `calm` and `calmd`.
+
+### First run
+
+```bash
+calm "what's running on port 3567?"
+```
+
+On first run `calm` will start `calmd` in the background, which will configure itself, load models and respond to your query. This may take a while depending on your system and network speed.
+
+### Examples
+
+```bash
+calm -y "top 5 memory processes"                # YOLO. Autoruns suggested command
+calm -f "kill what's running on port 3567"      # bypass dangerous command execution protection
+ps aux | calm "largest memory users"
+git diff | calm "summarize what changed"
+```
+
+### Steering and Guardrails
+
+You can force a specific output type using the `-c` (`--command`) or `-a` (`--analysis`) flags:
+
+- **Force Command**: `calm -c "what's on port 3000"` ensures the model suggests a runnable command.
+- **Force Analysis**: `calm -a "install git"` ensures the model provides an explanation instead of a command.
+
+These flags also act as strict guardrails; if the model provides a mismatched type, the CLI will error out and refuse the output.
+
+## What's under the hood?
+
+Please read [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Appendix
+
+### Configuration
+
+`calm` and `calmd` read `~/.config/calm/config.toml`.
+
+`calmd` creates this file with defaults on first start if it does not exist.
+Per-key precedence is: CLI flag > environment variable > config file > hardcoded default.
+
+```toml
+[common]
+socket_path = "~/.cache/calmd/socket"
+
+[cli]
+wait_timeout_secs = 300
+shutdown_timeout_secs = 2
+
+[daemon]
+model_path = "mlx-community/Qwen3.5-9B-OptiQ-4bit"
+use_fast_model = false  # Default fast model is mlx-community/Qwen3.5-4B-OptiQ-4bit
+verbose = false
+skip_warmup = false
+idle_offload_secs = 450
+
+[backend]
+disable_prefix_cache = false
+max_kv_size = 4096
+```
+
+For the full list of environment variable overrides, local development commands, and benchmark instructions, see [DEVELOPMENT.md](DEVELOPMENT.md).
+
+### `calmd` Auto-Start and Offload
+
+#### Auto-start
+
+`calm` auto-starts `calmd` if needed, preferring to start a managed service (Homebrew service or custom LaunchAgent) first. If neither managed option exists, `calm` may start an unmanaged `calmd` just to serve the request.
+
+This unmanaged fallback can't be administered by `calm -d`. You can always ask `calm` to help terminate the unmanaged daemon later:
+
+```bash
+> uv run calm 'terminate the calmd python daemon'
+pkill -f "calmd"
+
+Run this command? [y/N]
+```
+
+#### Offload
+
+`calmd` automatically offloads models after periods of inactivity to save memory. This can be configured with the `idle_offload_secs` config option.
+
+You can also manually trigger an offload using the `offload` command:
+
+```bash
+calm -d offload
+```
+
+### Running `calmd` as a login service
+
+#### Homebrew-managed service
+
+If installed via Homebrew, use Homebrew service management:
+
+```bash
+brew services start calm
+brew services stop calm
+```
+
+When a Homebrew service is installed, plain `calm` queries will prefer that service. Use `brew services` to administer it.
+
+#### Custom LaunchAgent managed by `calm -d`
+
+If you installed via PyPI, `pipx`, `uv tool`, or another non-Homebrew path, you can install a per-user LaunchAgent:
+
+```bash
+calm -d install
+calm -d start
+```
+
+Other useful commands:
+
+```bash
+calm -d offload
+calm -d stop
+calm -d uninstall
+```
+
+`calm -d install`, `start`, `stop`, and `uninstall` manage only the custom LaunchAgent created by `calm -d install`.
+If a Homebrew service is installed, use `brew services` instead.
+
+LaunchAgent logs are written to `~/Library/Logs/calmd/`.
+
+For daemon startup diagnostics, set `CALM_DEBUG_DAEMON=1` before running `calm`. This prints `launchctl` timing and daemon start-path debug logs to stderr.

calm_cli-0.3.0/calm/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())