Metadata-Version: 2.4
Name: slm-cli-agent
Version: 0.1.0
Summary: A lightweight local CPU-optimized CLI executor agent via ONNX Runtime with safety filters
Author-email: Suryaprakash CV <suryaprakash.c.v@gmail.com>
Keywords: llm,slm,cli,shell,bash,local-ai,cpu-inference
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: onnxruntime-genai>=0.2.0
Requires-Dist: huggingface_hub>=0.10.0
Requires-Dist: pyyaml

# SLM CLI Agent

A lightweight, local CPU-optimized command line interface companion agent powered by a local Small Language Model (SLM) running via ONNX Runtime GenAI. It translates natural language instructions into precise system shell commands, explains what they do, and executes them safely through an isolation layer with built-in command security constraints.

---

## Features

- **Local CPU Execution**: Optimized to run with less than 2.0 GB RAM using INT4-quantized Qwen2.5-1.5B-Instruct-ONNX.
- **Natural Language to CLI**: Converts developer instructions (e.g. "kill process on port 8000") into correct syntax-compliant shell commands.
- **Command Security Sandbox**: Detects and automatically blocks dangerous destructive actions (e.g., `rm -rf /`, formatting drives, reboots) before running them.
- **Explainable CLI**: Explains the proposed command and its options prior to execution.
- **Streaming & Thought Process**: Supports streaming responses, outputting the model's step-by-step reasoning inside `<thought>` tags before the final output.

---

## Installation

In your local project environment:
```bash
pip install -e ./slm_cli_agent
```

Ensure `onnxruntime-genai` is installed. It uses the shared monorepo model path cached locally at `models/qwen2.5-1.5b-onnx`.

---

## API Reference

### `SLMCLIAgent`

```python
from slm_cli_agent.cli_agent import SLMCLIAgent

agent = SLMCLIAgent(
    model_path=None,   # Path to the ONNX model directory (defaults to models/qwen2.5-1.5b-onnx)
    cache_dir=None,    # Alternative HF cache dir
    n_ctx=2048,        # Context length (defaults to 2048)
    n_threads=4        # Number of CPU threads to use for execution
)
```

#### Methods

#### `generate_command(query: str, stream: bool = False)`
Translates natural language to command line input.
- **Arguments**:
  - `query` (str): Natural language instruction.
  - `stream` (bool): If `True`, returns a generator that yields decoded output tokens in real-time. If `False`, runs to completion.
- **Returns**:
  - `tuple[str, str]`: `(extracted_command, full_response)` if `stream=False`.
  - `Generator`: A generator of tokens if `stream=True`.

#### `execute_command(cmd: str) -> tuple[int, str, str]`
Executes the proposed command.
- **Arguments**:
  - `cmd` (str): The raw command line script to execute.
- **Returns**:
  - `tuple[int, str, str]`: `(return_code, stdout, stderr)`. Returns `-1` with a security warning in `stderr` if the command contains dangerous destructive patterns.

#### `run(query: str) -> dict`
Translates, explains, and runs the instruction in one method call.
- **Arguments**:
  - `query` (str): Natural language instruction.
- **Returns**:
  - `dict`:
    ```python
    {
        "success": True/False,
        "command": str,       # Extracted executable bash command
        "explanation": str,   # Model explanation and thought process
        "stdout": str,        # Execution standard output logs
        "stderr": str,        # Execution error logs
        "returncode": int     # Subprocess exit status code
    }
    ```

---

## Usage Examples

### 1. Unified Natural Language Execution (`run`)
```python
from slm_cli_agent.cli_agent import SLMCLIAgent

agent = SLMCLIAgent()

# Translate and execute in a single call
result = agent.run("list directory contents in clean format")

print(f"Success: {result['success']}")
print(f"Command Executed: {result['command']}")
print(f"Stdout:\n{result['stdout']}")
```

### 2. Manual Generation and Execution
```python
from slm_cli_agent.cli_agent import SLMCLIAgent

agent = SLMCLIAgent()

# Translate instruction to command
cmd, explanation = agent.generate_command("find all files ending with .py in current folder")
print(f"Generated Command: {cmd}")
# Output: find . -name "*.py"

# Safely execute it
code, stdout, stderr = agent.execute_command(cmd)
print(f"Exit code: {code}")
print(f"Output:\n{stdout}")
```

### 2. Command Safety Check in Action
```python
# The agent detects and blocks malicious or destructive sequences automatically
code, stdout, stderr = agent.execute_command("rm -rf /usr/bin")
print(code)    # Output: -1
print(stderr)  # Output: Execution Blocked: Destructive or dangerous command pattern detected.
```

### 3. Complex Command Pipeline Generation and Run
The agent can translate and execute complex pipelines combining search, filtering, counting, and head limitations securely:

```python
from slm_cli_agent.cli_agent import SLMCLIAgent

agent = SLMCLIAgent()

# A dense multi-stage pipeline command request
query = (
    "Find all files in /var/log ending with .log modified in the last 7 days, "
    "search them for the term 'ERROR' case-insensitively, count the matching "
    "lines for each file, sort the count descending, and output the top 5 records "
    "while ignoring permission denied errors."
)

result = agent.run(query)

print("Exit code:", result["returncode"])
print("Generated Pipeline Command:")
print(result["command"])
print("\nExplanation:")
print(result["explanation"])
```

#### Generated Command:
```bash
find /var/log -type f -name "*.log" -mtime -7 2>/dev/null | xargs grep -io "ERROR" 2>/dev/null | cut -d: -f1 | sort | uniq -c | sort -rn | head -n 5
```

---

## Configuration (`config.yaml`)

Specify custom paths or model settings inside the project directory:
```yaml
models:
  cli_agent:
    path: "../../models/qwen2.5-1.5b-onnx"
    repo_id: "tonythethompson/Qwen2.5-1.5B-Instruct-ONNX"
```
