Spaces:
Running
Running
| # NLProxy CLI Module Reference | |
| This document covers the command-line interface implemented under `cli/`. | |
| ## Purpose | |
| The CLI package provides operational tooling for NLProxy: | |
| - Starting the server | |
| - Downloading and validating local models | |
| - Running compression tasks from the command line | |
| - Running project tests | |
| ## Files | |
| ### `cli/runserver.py` | |
| #### Responsibilities | |
| - Parses CLI arguments for server host, port, worker count, provider selection, and logging. | |
| - Loads `.env` values from the current working directory. | |
| - Configures provider API keys and exports them to environment variables. | |
| - Starts `uvicorn` with production-ready settings. | |
| #### Notable CLI Behavior | |
| - `--reload` forces `workers=1` to avoid conflicts with auto-reload. | |
| - Default provider is resolved from CLI flag, environment variables, or built-in fallback. | |
| - Logs an error and exits if provider credentials are missing. | |
| - Uses `uvicorn.run(..., http="httptools", ws="websockets")` for performance. | |
| #### Configuration Options | |
| - `--host`, `--port` | |
| - `--workers` | |
| - `--llm-client` | |
| - `--model` | |
| - `--api-key-client` | |
| - `--reload` | |
| - `--log-level` | |
| - `--access-log` | |
| - `--list-models` | |
| #### Environment Variables | |
| - `NLPROXY_HOST` | |
| - `NLPROXY_PORT` | |
| - `NLPROXY_LOG_LEVEL` | |
| - `NLPROXY_DEFAULT_LLM_PROVIDER` | |
| - `NLPROXY_DEFAULT_LLM_MODEL` | |
| - `NLPROXY_MODELS_URL` | |
| ### `cli/download_models.py` | |
| #### Responsibilities | |
| - Downloads the repository model archive from a configurable URL. | |
| - Extracts model files safely and validates required directory structure. | |
| - Supports checksum verification for `nlproxy_models.zip`. | |
| - Reports progress via `tqdm` when available. | |
| #### Primary Functions | |
| - `ensure_models_dir(models_dir: Path) -> None` | |
| - `download_with_retries(url: str, dest_path: Path) -> bool` | |
| - `extract_and_validate(zip_path: Path, models_dir: Path, expected_dirs: List[str]) -> bool` | |
| - `cleanup_temp(zip_path: Path, keep_zip: bool) -> None` | |
| #### Validation Rules | |
| - Rejects archives containing absolute paths or `..` entries. | |
| - Ensures expected directories exist after extraction: | |
| - `all-MiniLM-L6-v2` | |
| - `nli-distilroberta-base` | |
| - `distilgpt2` | |
| - Fails if any extracted model directory lacks valid model artifact files. | |
| ### `cli/compress.py` | |
| #### Responsibilities | |
| - Provides a terminal wrapper for one-off compression operations. | |
| - Accepts prompt text, compression mode, aggressiveness, and output formatting. | |
| - Integrates with the service layer for the same pipeline used by the server. | |
| #### General Behavior | |
| - Supports `--quiet` to reduce console output. | |
| - Outputs JSON by default. | |
| - Reuses the same compressor logic as the FastAPI route. | |
| ### `cli/help.py` | |
| #### Responsibilities | |
| - Prints CLI usage help text. | |
| - Acts as a lightweight documentation helper for users who invoke the CLI with `--help`. | |
| ### `cli/tests.py` | |
| #### Responsibilities | |
| - Wraps `pytest` invocation for repository tests. | |
| - Builds pytest command line based on CLI flags. | |
| - Supports coverage and custom test selection. | |
| ## Usage Notes | |
| - The CLI is intentionally thin and delegates heavy work to `server`, `service`, and `core` modules. | |
| - The downloader is the only CLI entrypoint that performs local filesystem writes and network I/O. | |
| - `runserver` is the recommended path for production deployments. | |