smah 0.1.13
OpenAI Driven system and user preference aware commandline GPT with pipe processing support and conversation history.
License: MIT
Requires Python: <4.0,>=3.10
Keywords: openai, command-line, system, automation, smart-pipe

README
======
SMAH the SMart As Hell SysteM Admin Helper.

Welcome to **SMAH** the **S**yste**M** **A**dmin **H**elper that just so happens to be
**SM**art **A**s **H**ell, an early prototype of a suite of tools designed 
to assist system administrators, data scientists, developers,
and power users with system operations. 

SMAH helps simplify tasks by providing command generation, 
pipe processing and other tasks tailored to your background and operating system. 

### Purpose

SMAH is designed to:
1. **Generate Commands**: Avoid endless searches through documentation. Simply describe what you want to do, and SMAH generates the necessary command while explaining potential impacts and asking for confirmation before execution. You just want to use ffmpeg(tm) to convert a mp4 into a gif. 
2. **Assisted Pipe Generation**: Take advantage of SMAH’s ability to assist in generating complex pipes and chaining commands in Unix environments.
3. **AI-Assisted Monitoring (pending)**: Set up system monitoring tasks quickly with AI guidance, allowing you to keep track of critical metrics and thresholds without manual configuration.

### Key Features

- **Interactive Command Generation**: SMAH can guide you through setting up environments, managing packages, configuring system services, and more, by generating commands and helping you understand their implications before execution. And ask questions as it (pending) process your query.
- **User Preferences and Personalization**: SMAH remembers your preferences for certain tools (e.g., package managers, environment management tools) and uses those to generate optimal commands, saving time and reducing repetitive configuration.
- **Command Confirmation and Safety**: For safety and control, SMAH will always ask for confirmation before running any system-altering command. You’ll also be given an overview of what the command will do and the expected impact on your system.
- **Model Planning/Prompt Planning**: A fast model is used to look at a sample of pipe data or your inquiry in order to decide
the best output format, runner model, additional instructions nad other details.


## Installation


### Pip Install
```
pip install smah
## call smah to begin setup. 
smah --setup
```

or 

### Local Build
@see [Contributing - Local Build Setup](CONTRIBUTING.md#local-development-setup)

-  git checkout code
- install poetry and python env. 
- setup python env (conda, venv, etc.)
- navigate to smah folder and run `poetry install`
- set SMAH_OPENAI_API_KEY env variable or set key in your smah config file `~/.smah/config.yaml`
- run smah --setup

## Examples

###  Pipe Input Processing

#### Log Audit to Pipe Output Format
Analyze Access Log Entries

```sh
tail -n 500 /var/log/auth.log | smah -q "Analyze these access log entries and output a markdown summary with tables of suspicious ips and events."  
```
![image](https://github.com/user-attachments/assets/445c0004-84db-46a9-b654-bb3c3692e73b)


#### System Control Summary
```
systemctl status | smah -i ~/SCAN-SYSTEMCTL.md
```
![image](https://github.com/user-attachments/assets/0304e06c-bb6f-4a2c-894d-f672225b1b83)



#### System Task
```sh
smah -q "How do I setup a web proxy on this server that I can connect to via my remote desktop to access the web?"
 ```
![image](https://github.com/user-attachments/assets/b712fbd7-7e2b-4e1f-9320-71c48fe90e58)

#### Resume last chat 

```sh
smah --continue
```

#### Resume recent or (pending) search old conversations to pick up from.

```sh
smah --history
```
![image](https://github.com/user-attachments/assets/6da1841e-5014-468b-b933-6b215853c80e)



#### Resume by id.

```sh
smah --session ID
```

#### Interative Mode

```sh
smah --interactive
```

#### Saved Prompt
```
systemctl status | smah -i ~/.scan-status.md 
```

#### Help
```
> smah -h
usage: smah [-h] [-q QUERY] [-i INSTRUCTIONS] [--interactive | --no-interactive] [-c CONFIG] [--database DATABASE] [--configure | --no-configure] [--continue | --no-continue] [--session SESSION] [--history | --no-history]
            [-v] [--model MODEL] [--model-picker MODEL_PICKER] [--model-query MODEL_QUERY] [--model-pipe MODEL_PIPE] [--model-interactive MODEL_INTERACTIVE] [--model-review MODEL_REVIEW] [--model-edit MODEL_EDIT]
            [--openai-api-tier OPENAI_API_TIER] [--openai-api-key OPENAI_API_KEY] [--openai-api-org OPENAI_API_ORG] [--gui | --no-gui] [--rich | --no-rich]

SMAH Command Line Tool

options:
  -h, --help            show this help message and exit
  -q QUERY, --query QUERY
                        The Query to process
  -i INSTRUCTIONS, --instructions INSTRUCTIONS
                        The Instruction File to process
  --interactive, --no-interactive
                        Run in interactive mode (default: False)
  -c CONFIG, --config CONFIG
                        Path to alternative config file
  --database DATABASE   Path to sqlite smah database
  --configure, --no-configure
                        Enter Config Setup (default: False)
  --continue, --no-continue
                        Continue Last Conversation (default: False)
  --session SESSION     Resume Session
  --history, --no-history
                        Resume Recent Session (default: False)
  -v, --verbose         Set Verbosity Level, such as -vv
  --model MODEL         Default Model
  --model-picker MODEL_PICKER
                        Picker Model
  --model-query MODEL_QUERY
                        Query Model
  --model-pipe MODEL_PIPE
                        Pipe Processing Model
  --model-interactive MODEL_INTERACTIVE
                        Interactive Processing Model
  --model-review MODEL_REVIEW
                        Output Reviewer Model
  --model-edit MODEL_EDIT
                        Output Editor Model
  --openai-api-tier OPENAI_API_TIER
                        OpenAI Tier
  --openai-api-key OPENAI_API_KEY
                        OpenAI Api Key
  --openai-api-org OPENAI_API_ORG
                        OpenAI Api Org
  --gui, --no-gui       Run in GUI mode (default: False)
  --rich, --no-rich     Rich Format Output (default: True)
```



## Setup

```
pip install smah
```

### Getting Started
When you run `smah` for the first time, it will guide you through a setup process to configure the necessary settings. Here is a step-by-step walkthrough of what the first run setup flow looks like:

#### 1. First Run
```sh
smah
```


## First Run Setup Flow

On the first run you will be asked about your background, experience,
and system details will be extracted or manually provided to reference 
future requests. 

system details will be extracted or manually provided, 
and the chance to set a optional instruction statement to include 
in every request. 

After completing these steps, your `smah` tool will be configured and ready to use.

#### 3. Fine Tuning
You can tweak model setting rules/weighthing currently by 
manually editing the generated `~/.smah/config.yaml` file. 
You can try differnt config options out with the `--config` arg


```yaml 
vsn: 0.0.1
user:
  vsn: 0.0.1
  name: Your Name
  system_admin_experience: Intermediate
  role: Administrator
  about: |
    I prefer detailed responses. I am well versed in biology, mathematics, and software testing and engineering, as well as relational database design and tuning. I am an INTP personality type.
system:
  vsn: 0.0.1
  operating_system:
    type: Linux
    name: posix
    version: '#1 SMP Thu Oct 5 21:02:42 UTC 2023'
    release: 5.15.133.1-microsoft-standard-WSL2
    info:
      vsn: 0.0.1
      kind: Linux
      source: os-release
      details:
        bug-report-url: https://bugs.launchpad.net/ubuntu/
        home-url: https://www.ubuntu.com/
        id: ubuntu
        id-like: debian
        name: Ubuntu
        pretty-name: Ubuntu 22.04.4 LTS
        privacy-policy-url: https://www.ubuntu.com/legal/terms-and-policies/privacy-policy
        support-url: https://help.ubuntu.com/
        ubuntu-codename: jammy
        version: 22.04.4 LTS (Jammy Jellyfish)
        version-codename: jammy
        version-id: '22.04'
    vsn: 0.0.1
inference:
  vsn: 0.0.1
  instructions: null # Optional additional instructions to include in each request.
  model_picker:
    default:
    - openai.gpt-4o-mini
    - openai.gpt-4o
  providers:
    openai:
      name: OpenAI
      description: OpenAI Models
      enabled: true
      vsn: 0.0.1
      settings: {}
      models:
      - name: gpt-4-turbo
        model: gpt-4-turbo
        description: GPT-4 Turbo
        enabled: false
        training_cutoff: 2023-12-01 00:00:00
        license: OpenAI License
        model_type: LLM
        context:
          window: 128000
          out: 4096
        strengths:
        - Highly accurate
        - Fast
        weaknesses:
        - Expensive
        - Multimodal capabilities limited
        modalities:
          text:
            in: true
            out: true
          image:
            in: true
            out: false
        settings: {}
        attributes:
          speed: 5
          reasoning: 5
          planning: 5
          creativity: 5
          conciseness: 5
          coding: 5
        cost:
          million_tokens_in: 10.0
          million_tokens_out: 30.0
        use_cases:
        - name: Code Generation
          score: 0.5
        - name: Text Generation
          score: 0.6
        - name: Translation
          score: 0.5
        - name: Planning
          score: 0.5
        - name: Reasoning
          score: 0.5
        - name: Creativity
          score: 0.5
        - name: Data Analysis
          score: 0.5
        vsn: 0.0.1
## ...        
      - name: o1-mini
        model: o1-mini
        description: o1 (mini)
        enabled: false
        training_cutoff: 2023-12-01 00:00:00
        license: OpenAI License
        model_type: LLM
        context:
          window: 128000
          out: 32768
        strengths:
        - Highly accurate
        - Advanced Reasoning
        weaknesses:
        - Expensive
        - Multimodal capabilities limited
        modalities:
          text:
            in: true
            out: true
        settings:
          max_completion_tokens: true
        attributes:
          speed: 5
          reasoning: 7
          planning: 7
          creativity: 4
          conciseness: 7
          coding: 7
        cost:
          million_tokens_in: 3.0
          million_tokens_out: 12.0
        use_cases:
        - name: Code Generation
          score: 0.7
        - name: Text Generation
          score: 0.7
        - name: Translation
          score: 0.7
        - name: Planning
          score: 0.7
        - name: Reasoning
          score: 0.7
        - name: Creativity
          score: 0.4
        - name: Data Analysis
          score: 0.7
        vsn: 0.0.1

```

## Security
Do not pass sensitive data/details to Smah if your LLM will persist/track it, use a (pending) local model instead.
Double check exec commands they may have errors and require edits prior to execution. 

### Future Enhancements

SMAH is in its early alpha stage, and we are actively working on the following enhancements:

1. **Expanded Command Generation Use Cases**: Increase the range of commands that SMAH can generate, including more complex system operations and integrations with additional tools.
2. **Enhanced AI-Assisted Monitoring**: Improve the AI's ability to set up and manage system monitoring tasks, including more advanced metrics and alerting capabilities.
3. **Interactive Rich Terminal Interface**: Develop a terminal-based user interface for managing and interacting with the system, providing a richer user experience.
4. **Multi-User Support**: Implement support for multiple user accounts with shared global configuration options, allowing for seamless management across different users.
5. **Advanced Security Features**: Strengthen security measures, especially when running commands with elevated privileges, and enhance guardrail enforcement.
6. **Integration with External Tools**: Enable integration with other popular tools and services to streamline workflows and improve productivity.
7. **Data Visualization**: Add capabilities for visualizing data trends and analysis results, making it easier to interpret and present findings.
8. **Automated Reporting**: Develop features for generating automated reports based on data analyses, saving time on repetitive tasks.
9. **Enhanced Logging and Monitoring**: Improve the logging and monitoring system to provide more detailed insights and better auditability.
10. **Secrets Management**: Implement secure storage and management of sensitive information, such as API keys and passwords.

### 1-Year Roadmap

#### Q1
- **Release Beta Version**: Transition from alpha to beta, incorporating initial user feedback and stabilizing core features.
- **Expand Command Generation**: Add support for more complex commands and integrations with additional tools.
- **Improve AI-Assisted Monitoring**: Enhance the AI's capabilities for setting up and managing system monitoring tasks.

#### Q2
- **Develop Interactive Terminal Interface**: Create a rich terminal-based user interface for better user interaction.
- **Implement Multi-User Support**: Enable support for multiple user accounts with shared global configuration options.
- **Strengthen Security Features**: Enhance security measures, especially for commands requiring elevated privileges.

#### Q3
- **Integrate with External Tools**: Enable seamless integration with other popular tools and services.
- **Add Data Visualization**: Develop features for visualizing data trends and analysis results.
- **Automate Reporting**: Implement automated reporting capabilities to save time on repetitive tasks.

#### Q4
- **Enhance Logging and Monitoring**: Improve the logging and monitoring system for better insights and auditability.
- **Implement Secrets Management**: Develop secure storage and management of sensitive information.
- **Prepare for General Availability**: Finalize features and prepare for a general availability release, ensuring stability and robustness.

## Contributing

We welcome contributions to help improve SMAH. Here are some guidelines to get you started:

### How to Contribute

#### Feature Requests, Feedback and Bug Reports

- Use the GitHub issues tracker to report bugs or suggest features.
- Provide as much detail as possible, including steps to reproduce the issue.
_ When use user-story style at the openning of feature/change requests.

#### Bug Fixes and Code Changes
 
1. Fork the Repository: Create a personal fork of the repository on GitHub.
2. Create a Feature: Create a new branch for your feature or bugfix.
3. Make Changes: Make your changes in the new branch.
4. Commit Changes: Use descriptive commit changes orgnanize work, 
   rebase/group related items together for complex multi part changes
   and split into sub branches/pull requests. 
5. Make A Pull Request - give details on what you've changed/fixed.

#### Code Style

- When Possible Follow the existing code style and conventions unless overhauling format/layout only (I suggest asking first.) 
- Write clear, concise, and descriptive commit messages.
- Use Type Hints and Doc Tags. 
- Ensure your code is well-documented. Consider md and mermaid diagrams for complax/major changes.

#### Testing

- Write pytests for any new features or bug fixes.
- Ensure all tests pass before submitting a pull request.


### Code of Conduct

Be Kind.

## License
[MIT](./LICENSE)