Metadata-Version: 2.4
Name: ai-linux-assistant
Version: 0.1.0
Summary: AI-powered natural-language Linux command-line assistant
License: MIT
Keywords: linux,bash,ai,cli,cybersecurity,assistant
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.34.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# ai-linux-assistant

An AI-powered natural-language Linux command-line assistant. Type what you
want to do in plain English; it figures out the Bash command, explains it,
checks whether it's safe to run automatically, executes it, and explains
the result.

```
ai "find the largest file in this folder"
ai "show my disk usage"
ai "create a folder called projects"
ai "why is my python command failing?"
```

Not a web app, no Firebase, no login system, no database — a Python
package you run from your own terminal.

## Install

```bash
pip install ai-linux-assistant
export ANTHROPIC_API_KEY=your-key-here
```

(Not yet published to PyPI — see `pyproject.toml` to build/install locally
with `pip install -e .`.)

## Usage

**Single-shot** (scriptable):

```bash
ai "find the largest file in this folder"
ai --explain "find . -type f -mtime +7 -delete"
ai --history 20
```

**Interactive** (remembers context across turns, supports `undo`):

```
$ ai
you> find the largest file
  $ find . -type f -exec du -h {} + | sort -rh | head -n 1
  ...
you> now sort them by size
you> undo
you> exit
```

## How it works

```
natural language
      │
      ▼
NLPEngine            understands intent, generates a command (or a
(AI + NLP)            multi-step plan), explains it, proposes an
                       advisory risk_hint
      │
      ▼
SafetyEngine          independent static analysis of the full command
(Safety/Permission)    string (pipes, redirects, sudo, chained operators,
                        etc). Only this module decides ALLOW / CONFIRM /
                        BLOCK — the AI's own risk_hint can escalate a
                        verdict but never soften one
      │
      ▼
CommandExecutor        runs the approved command, captures stdout/
(Linux Execution)       stderr/exit code, analyzes the result, and
                        suggests a next step on failure
      │
      ▼
back into NLPEngine's ConversationContext, so follow-up turns
("why did that fail?", "undo that") have something to reason about
```

Read-only commands (`ls`, `pwd`, `df`, `cat`, `grep`, ...) run
automatically. Commands that change something (`mkdir`, `rm`, `mv`,
`chmod`, `sudo`, package installs, ...) ask for confirmation first.
Catastrophic commands (`rm -rf /`, fork bombs, raw disk writes, piping a
remote script straight into `bash`, ...) are refused outright.

## Project layout

```
ai_linux_assistant/
    nlp/        AI + Natural Language — intent, command generation,
                explanations, context, master prompts
    safety/     Safety/Permission Engine — command risk analysis,
                confirmation system, dangerous-command detection
                (core/ is Member 2's real submitted engine; engine.py
                adapts it into the app's ALLOW/CONFIRM/BLOCK contract)
    executor/   Linux Execution + Smart Features — subprocess execution,
                output analysis, suggestions, multi-step runs, history
    cli.py      CLI + Packaging — terminal interface tying the above
                together
tests/          unit tests per module + end-to-end integration tests
```

See `INTEGRATION.md` for how each module's work was combined and what's
still outstanding.

## Development

```bash
pip install -e ".[dev]"
python3 -m pytest tests/ -v
```


## Development and testing

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python3 -m pytest -v
```

## CLI

```bash
ai --version
ai --help
ai "show my disk usage"
ai --explain "ls -la"
ai --history 20
```

Modifying commands require confirmation in an interactive terminal. `--yes`
is an explicit opt-in for automation; critical `BLOCK` decisions are never
bypassed.

## Build package

```bash
python3 -m pip install --upgrade build
python3 -m build
```

The generated wheel and source distribution in `dist/` can be tested locally
before any PyPI upload.
