argo-shell-assistant 0.1.0__tar.gz

argo_shell_assistant-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+hidden/*
+
+# PyPI token (never commit)
+.pypirc
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Local config (se dentro il progetto)
+config.json
+knowledge.json
+history.json
+perf.json
+risk-rules.json

argo_shell_assistant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Argo contributors
+
+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.

argo_shell_assistant-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: argo-shell-assistant
+Version: 0.1.0
+Summary: Natural language assistant for the Linux shell
+Project-URL: Homepage, https://gitlab.com/gianfrasoft/argo
+Project-URL: Documentation, https://gitlab.com/gianfrasoft/argo/-/blob/main/README.md
+Project-URL: Repository, https://gitlab.com/gianfrasoft/argo
+Project-URL: Issues, https://gitlab.com/gianfrasoft/argo/-/issues
+Author: Argo contributors
+License: MIT
+License-File: LICENSE
+Keywords: cli,llm,natural-language,ollama,openai,shell
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.10
+Requires-Dist: ollama>=0.3.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Description-Content-Type: text/markdown
+
+# Argo
+
+Terminal assistant that translates natural language requests into Linux commands.
+
+## What it is
+
+Argo is a CLI tool that:
+
+- interprets natural language requests (Italian, English, etc.)
+- generates appropriate shell commands via LLM (Ollama)
+- classifies commands by risk level (🟢 read-only, 🟡 write, 🔴 destructive)
+- allows preview, edit, explain and execution time estimation before running
+- learns from your choices and improves suggestions over time
+
+## Installation
+
+```bash
+# Quick install script
+./install.sh
+# or without sudo (installs to ~/.local)
+./install.sh --user
+
+# Manual
+pip install -e .
+# or run from source without installing
+./run.sh --version
+```
+
+## Requirements
+
+- Python 3.10+
+- [Ollama](https://ollama.com) running
+  - `ollama serve` — start the server
+  - `ollama pull llama3.2` — download a model
+
+## Basic usage
+
+```bash
+# Interactive mode (REPL)
+argo
+
+# Single query
+argo find files larger than 1gb
+argo find files modified today
+argo search for "error" in logs
+```
+
+After generation you'll see a list of commands: use arrow keys to select, **Enter** to run. Keys: **p** preview, **e** edit, **t** estimate, **x** explain, **q** exit.
+
+## Examples
+
+### Single commands
+
+```bash
+# Preview (what the command would do)
+argo preview "rm *.log"
+
+# Step-by-step explanation
+argo explain "grep -r error logs/"
+
+# Execution time estimate
+argo estimate ls -la
+argo estimate find . -name "*.log"
+```
+
+### Learning and memory
+
+```bash
+# Save a preferred command
+argo learn grep -r error logs/
+
+# List learned commands
+argo memory
+
+# Remove one
+argo forget 1
+
+# Optimize knowledge (deduplicate, learn from history)
+argo optimize
+argo optimize --dry-run
+```
+
+### Configuration
+
+```bash
+argo config set llm.model llama3.2
+argo config set language.output it
+argo config get language.output
+argo config list
+
+# Verify environment
+argo check
+argo check --fix   # create missing config files
+```
+
+### Custom risk rules
+
+```bash
+argo risk add command mytool danger
+argo risk add pattern "curl.*\|.*sh" critical
+argo risk protect /etc
+argo risk list
+argo risk remove command mytool
+```
+
+### Auto-execute
+
+```bash
+argo -y find .log files          # auto if read-only
+argo -y2 copy files to backup/   # auto if read-only or write
+argo -y3 any command            # use with caution!
+```
+
+### Session options
+
+```bash
+argo --lang it      # session in Italian
+argo --auto         # same as -y for REPL
+argo --no-color     # disable colors
+```
+
+## Remote LLM (OpenAI, OpenRouter, etc.)
+
+Argo can use remote APIs instead of local Ollama. API keys are read from environment variables (never stored in config).
+
+**OpenAI / compatible APIs:**
+
+```bash
+# Set your API key (never commit this!)
+export OPENAI_API_KEY="sk-..."
+
+# Enable remote in config
+argo config set llm.remote.enabled true
+argo config set llm.remote.model gpt-4
+```
+
+**OpenRouter** (access to many models with one key):
+
+```bash
+export OPENAI_API_KEY="sk-or-..."
+argo config set llm.remote.enabled true
+argo config set llm.remote.base_url "https://openrouter.ai/api/v1"
+argo config set llm.remote.model "anthropic/claude-3-haiku"
+```
+
+**Custom env var name:**
+
+```bash
+export MY_API_KEY="sk-..."
+argo config set llm.remote.api_key_env MY_API_KEY
+```
+
+If remote fails or the `openai` package is missing, Argo falls back to local Ollama.
+
+## Configuration
+
+Files in `~/.config/argo/`:
+
+- `config.json` — LLM, language, colors
+- `knowledge.json` — learned commands
+- `history.json` — choice history
+- `risk-rules.json` — custom risk rules
+- `perf.json` — performance estimate cache
+
+## License
+
+MIT — see [LICENSE](LICENSE)

argo_shell_assistant-0.1.0/README.md

@@ -0,0 +1,167 @@
+# Argo
+
+Terminal assistant that translates natural language requests into Linux commands.
+
+## What it is
+
+Argo is a CLI tool that:
+
+- interprets natural language requests (Italian, English, etc.)
+- generates appropriate shell commands via LLM (Ollama)
+- classifies commands by risk level (🟢 read-only, 🟡 write, 🔴 destructive)
+- allows preview, edit, explain and execution time estimation before running
+- learns from your choices and improves suggestions over time
+
+## Installation
+
+```bash
+# Quick install script
+./install.sh
+# or without sudo (installs to ~/.local)
+./install.sh --user
+
+# Manual
+pip install -e .
+# or run from source without installing
+./run.sh --version
+```
+
+## Requirements
+
+- Python 3.10+
+- [Ollama](https://ollama.com) running
+  - `ollama serve` — start the server
+  - `ollama pull llama3.2` — download a model
+
+## Basic usage
+
+```bash
+# Interactive mode (REPL)
+argo
+
+# Single query
+argo find files larger than 1gb
+argo find files modified today
+argo search for "error" in logs
+```
+
+After generation you'll see a list of commands: use arrow keys to select, **Enter** to run. Keys: **p** preview, **e** edit, **t** estimate, **x** explain, **q** exit.
+
+## Examples
+
+### Single commands
+
+```bash
+# Preview (what the command would do)
+argo preview "rm *.log"
+
+# Step-by-step explanation
+argo explain "grep -r error logs/"
+
+# Execution time estimate
+argo estimate ls -la
+argo estimate find . -name "*.log"
+```
+
+### Learning and memory
+
+```bash
+# Save a preferred command
+argo learn grep -r error logs/
+
+# List learned commands
+argo memory
+
+# Remove one
+argo forget 1
+
+# Optimize knowledge (deduplicate, learn from history)
+argo optimize
+argo optimize --dry-run
+```
+
+### Configuration
+
+```bash
+argo config set llm.model llama3.2
+argo config set language.output it
+argo config get language.output
+argo config list
+
+# Verify environment
+argo check
+argo check --fix   # create missing config files
+```
+
+### Custom risk rules
+
+```bash
+argo risk add command mytool danger
+argo risk add pattern "curl.*\|.*sh" critical
+argo risk protect /etc
+argo risk list
+argo risk remove command mytool
+```
+
+### Auto-execute
+
+```bash
+argo -y find .log files          # auto if read-only
+argo -y2 copy files to backup/   # auto if read-only or write
+argo -y3 any command            # use with caution!
+```
+
+### Session options
+
+```bash
+argo --lang it      # session in Italian
+argo --auto         # same as -y for REPL
+argo --no-color     # disable colors
+```
+
+## Remote LLM (OpenAI, OpenRouter, etc.)
+
+Argo can use remote APIs instead of local Ollama. API keys are read from environment variables (never stored in config).
+
+**OpenAI / compatible APIs:**
+
+```bash
+# Set your API key (never commit this!)
+export OPENAI_API_KEY="sk-..."
+
+# Enable remote in config
+argo config set llm.remote.enabled true
+argo config set llm.remote.model gpt-4
+```
+
+**OpenRouter** (access to many models with one key):
+
+```bash
+export OPENAI_API_KEY="sk-or-..."
+argo config set llm.remote.enabled true
+argo config set llm.remote.base_url "https://openrouter.ai/api/v1"
+argo config set llm.remote.model "anthropic/claude-3-haiku"
+```
+
+**Custom env var name:**
+
+```bash
+export MY_API_KEY="sk-..."
+argo config set llm.remote.api_key_env MY_API_KEY
+```
+
+If remote fails or the `openai` package is missing, Argo falls back to local Ollama.
+
+## Configuration
+
+Files in `~/.config/argo/`:
+
+- `config.json` — LLM, language, colors
+- `knowledge.json` — learned commands
+- `history.json` — choice history
+- `risk-rules.json` — custom risk rules
+- `perf.json` — performance estimate cache
+
+## License
+
+MIT — see [LICENSE](LICENSE)

argo_shell_assistant-0.1.0/install.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Argo — installazione rapida
+# Uso: ./install.sh [--user]
+#   --user  installa in ~/.local (non richiede sudo)
+
+set -e
+cd "$(dirname "$0")"
+
+OPTS=""
+if [ "$1" = "--user" ]; then
+  OPTS="--user"
+fi
+
+echo "Installing Argo..."
+python3 -m pip install $OPTS -e . 2>/dev/null || pip install $OPTS -e .
+
+if command -v argo &>/dev/null; then
+  echo ""
+  echo "Argo installato. Prova:"
+  echo "  argo --version"
+  echo "  argo help"
+  echo "  argo trova file più grandi di 1gb"
+  echo ""
+  echo "Assicurati che Ollama sia in esecuzione: ollama serve"
+  echo "E che un modello sia disponibile: ollama pull llama3.2"
+else
+  echo ""
+  echo "Installazione completata. Se 'argo' non è nel PATH:"
+  echo "  python3 -m argo.cli --version"
+  echo "  oppure aggiungi ~/.local/bin al PATH"
+fi

argo_shell_assistant-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "argo-shell-assistant"
+version = "0.1.0"
+description = "Natural language assistant for the Linux shell"
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    { name = "Argo contributors" }
+]
+keywords = ["cli", "shell", "llm", "natural-language", "ollama", "openai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Shells",
+]
+
+dependencies = [
+    "ollama>=0.3.0",
+    "openai>=1.0.0",
+    "prompt_toolkit>=3.0.0",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/gianfrasoft/argo"
+Documentation = "https://gitlab.com/gianfrasoft/argo/-/blob/main/README.md"
+Repository = "https://gitlab.com/gianfrasoft/argo"
+Issues = "https://gitlab.com/gianfrasoft/argo/-/issues"
+
+[project.scripts]
+argo = "argo.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argo"]

argo_shell_assistant-0.1.0/requirements.txt

@@ -0,0 +1,10 @@
+# Argo CLI — dipendenze
+# Python 3.10+
+
+# Fase 1 (LLM)
+ollama>=0.3.0
+
+# Fase 3 (UI interattiva)
+prompt_toolkit>=3.0.0
+
+# Nessuna dipendenza esterna per Fase 0

argo_shell_assistant-0.1.0/run.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Esegue Argo in sviluppo senza installazione
+cd "$(dirname "$0")"
+PYTHONPATH=src python3 -m argo.cli "$@"

argo_shell_assistant-0.1.0/src/argo/__init__.py

@@ -0,0 +1,3 @@
+"""Argo — natural language assistant for the Linux shell."""
+
+__version__ = "0.1.0"