smart-linux-assistant 0.5.0__py3-none-any.whl

linux_assistant/__init__.py

@@ -0,0 +1,11 @@
+"""
+Expose shared utility functions for the application.
+"""
+
+from linux_assistant.utils.logger import get_logger
+from linux_assistant.utils.shell import command_exists
+
+__all__ = [
+    "get_logger",
+    "command_exists",
+]

linux_assistant/cli/main.py

@@ -0,0 +1,277 @@
+"""
+Command-line interface for the Smart Linux Assistant.
+"""
+
+from __future__ import annotations
+import sys
+import typer
+from linux_assistant.exceptions import CommandExecutionError, CommandFailedError, CommandTimeoutError, ValidationError, MissingAPIKeyError, ServiceError, RateLimitError
+from linux_assistant.services.explainer import Explainer
+from linux_assistant.services.command_executor import CommandExecutor
+from linux_assistant.utils.logger import get_logger
+from linux_assistant.utils.shell import command_exists
+from linux_assistant.services.search import Searcher
+
+logger = get_logger(__name__)
+
+app = typer.Typer(
+    name="smart-linux",
+    help="An AI-powered Linux productivity assistant.",
+    add_completion=False,
+)
+
+@app.callback()
+def callback() -> None:
+    """
+    Smart Linux Assistant — an AI-powered Linux productivity CLI.
+    """
+
+@app.command()
+def run(
+    command: str = typer.Argument(..., help="The shell command to execute."),
+    timeout: int = typer.Option(30, help="Timeout in seconds."),
+    check: bool = typer.Option(
+        False, "--check", help="Exit non-zero if the command itself fails."
+    ),
+    suggest_fix: bool = typer.Option(
+        False, "--suggest-fix", help="If the command fails, suggest an AI-generated fix."
+    ),
+) -> None:
+    """
+    Execute a shell command and display structured results.
+    """
+    
+    if suggest_fix and not check:
+        typer.secho(
+            "Invalid usage: --suggest-fix requires --check (fix suggestions only apply to command failures detected via --check).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    executor = CommandExecutor()
+    
+    try:
+        if check:
+            result = executor.execute_checked(command, timeout=timeout)
+        else:
+            result = executor.execute(command, timeout=timeout)
+
+    except ValidationError as exc:
+        typer.secho(f"Invalid input: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    except CommandTimeoutError as exc:
+        typer.secho(f"Timed out: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=124)
+
+    except CommandFailedError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        if exc.result.stderr:
+            typer.secho(exc.result.stderr, fg=typer.colors.YELLOW, err=True)
+
+        if suggest_fix:
+            typer.echo()
+            try:
+                explainer = Explainer()
+                suggestion = explainer.suggest_fix(command, exc.result.stderr)
+
+            except MissingAPIKeyError as fix_exc:
+                typer.secho(str(fix_exc), fg=typer.colors.RED, err=True)
+
+            except RateLimitError as fix_exc:
+                typer.secho(str(fix_exc), fg=typer.colors.YELLOW, err=True)
+
+            except ServiceError as fix_exc:
+                typer.secho(f"Could not get a fix suggestion: {fix_exc}", fg=typer.colors.RED, err=True)
+
+            else:
+                if suggestion is None:
+                    typer.secho("No confident fix available.", fg=typer.colors.YELLOW)
+                else:
+                    typer.secho("Suggested fix:", fg=typer.colors.CYAN)
+                    typer.echo(f"  {suggestion}")
+
+        raise typer.Exit(code=exc.result.exit_code)
+
+    except CommandExecutionError as exc:
+        typer.secho(f"Execution error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    if result.stdout:
+        typer.echo(result.stdout)
+    if result.stderr:
+        typer.secho(result.stderr, fg=typer.colors.YELLOW, err=True)
+
+    raise typer.Exit(code=result.exit_code)
+
+DOCTOR_CHECKS: tuple[str, ...] = (
+    "bash",
+    "git",
+    "python3",
+    "docker",
+    "curl",
+    "systemctl",
+)
+
+
+@app.command()
+def doctor() -> None:
+    """
+    Check for the presence of common tools on this system.
+    """
+    typer.echo("Running environment checks...\n")
+
+    missing: list[str] = []
+
+    for tool in DOCTOR_CHECKS:
+        exists = command_exists(tool)
+        symbol = "✔" if exists else "✘"
+        color = typer.colors.GREEN if exists else typer.colors.RED
+        typer.secho(f"  {symbol}  {tool}", fg=color)
+
+        if not exists:
+            missing.append(tool)
+
+    typer.echo()
+
+    if missing:
+        typer.secho(
+            f"{len(missing)} tool(s) missing: {', '.join(missing)}",
+            fg=typer.colors.YELLOW,
+        )
+        raise typer.Exit(code=1)
+
+    typer.secho("All checked tools are available.", fg=typer.colors.GREEN)
+    
+@app.command()
+def explain(
+    text: str = typer.Argument(
+        ..., help="The command, error message, or output to explain."
+    ),
+) -> None:
+    """
+    Get a plain-language explanation of a command or error message.
+    """
+    if not text.strip():
+        typer.secho("Invalid input: Text to explain cannot be empty.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    
+    try:
+        explainer = Explainer()
+        result = explainer.explain(text)
+
+    except MissingAPIKeyError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+   
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=1)
+
+    except ServiceError as exc:
+        typer.secho(f"Explanation failed: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo(result)
+    
+@app.command()
+def fix(
+    command: str = typer.Argument(..., help="The failing command to fix."),
+    timeout: int = typer.Option(30, help="Timeout in seconds."),
+) -> None:
+    """
+    Run a command, and if it fails, suggest a corrected version.
+    """
+    executor = CommandExecutor()
+
+    try:
+        result = executor.execute(command, timeout=timeout)
+
+    except ValidationError as exc:
+        typer.secho(f"Invalid input: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+    
+    except CommandTimeoutError as exc:
+        typer.secho(f"Timed out: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=124)
+
+    except CommandExecutionError as exc:
+        typer.secho(f"Execution error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    if result.succeeded:
+        typer.secho(f"Command succeeded, nothing to fix.", fg=typer.colors.GREEN)
+        if result.stdout:
+            typer.echo(result.stdout)
+        raise typer.Exit(code=0)
+
+    typer.secho(f"Command failed: {result.stderr or '(no error output)'}", fg=typer.colors.RED)
+    typer.echo()
+   
+    try:
+        explainer = Explainer()
+        suggestion = explainer.suggest_fix(command, result.stderr)
+
+    except MissingAPIKeyError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=1)
+
+    except ServiceError as exc:
+        typer.secho(f"Could not get a fix suggestion: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    if suggestion is None:
+        typer.secho("No confident fix available.", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=1)
+
+    typer.secho("Suggested fix:", fg=typer.colors.CYAN)
+    typer.echo(f"  {suggestion}")
+    typer.echo()
+    typer.echo(f'Run it manually, or try: smart-linux run "{suggestion}"')
+
+    raise typer.Exit(code=1)
+
+@app.command()
+def search(
+    query: str = typer.Argument(
+        ..., help="A natural-language question about a Linux task."
+    ),
+) -> None:
+    """
+    Search for how to accomplish a Linux task in plain language.
+    """
+    if not query.strip():
+        typer.secho("Invalid input: Search query cannot be empty.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    try:
+        searcher = Searcher()
+        result = searcher.search(query)
+
+    except MissingAPIKeyError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    except RateLimitError as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=1)
+
+    except ServiceError as exc:
+        typer.secho(f"Search failed: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo(result)
+
+
+def main() -> None:
+    """Entry point wrapper, used by the packaged console script."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

linux_assistant/config/settings.py

@@ -0,0 +1,65 @@
+"""
+centralised configuration to make the project easier to maintain, test, and extend as new features are added.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+def _find_project_root(marker: str = "pyproject.toml") -> Path:
+    """
+    Dynamically locate the project root by searching upwards for a marker file.
+    This prevents breakage if the settings module is moved to a different depth.
+    """
+    current_dir = Path(__file__).resolve().parent
+    for parent in [current_dir, *current_dir.parents]:
+        if (parent / marker).exists():
+            return parent
+    return None 
+
+def _get_user_data_home() -> Path:
+    """
+    Resolve the user's data directory following the XDG Base Directory
+    specification, with a Windows/macOS fallback. This is where the
+    application should write logs and runtime data regardless of where
+    the code itself is installed.
+    """
+    xdg_data_home = os.environ.get("XDG_DATA_HOME")
+    if xdg_data_home:
+        return Path(xdg_data_home) / "smart-linux-assistant"
+    return Path.home() / ".local" / "share" / "smart-linux-assistant"
+
+
+PROJECT_ROOT = _find_project_root()
+USER_DATA_HOME = _get_user_data_home()
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """
+    Store shared project configuration.
+    """
+    project_root: Path  | None
+    logs_directory: Path
+    data_directory: Path
+    documentation_directory: Path | None
+
+
+settings = Settings(
+    project_root=PROJECT_ROOT,
+    logs_directory=USER_DATA_HOME / "logs",
+    data_directory=USER_DATA_HOME / "data",
+    documentation_directory=(PROJECT_ROOT / "docs") if PROJECT_ROOT else None,
+)
+
+
+def initialize_app_filesystem() -> None:
+    """
+    Ensure required runtime directories exist with appropriate permissions.
+    
+    must be called explicitly during application startup to prevent 
+    unintended side-effects during standard imports or automated testing.
+    """
+    for directory in (settings.logs_directory, settings.data_directory):
+        directory.mkdir(parents=True, exist_ok=True)
+        directory.chmod(0o755)

linux_assistant/exceptions/__init__.py

@@ -0,0 +1,31 @@
+"""
+Expose the public exception hierarchy for the application.
+Importing exceptions from this package keeps call sites concise and
+avoids exposing the internal module structure.
+"""
+
+from .base import (
+    CommandExecutionError,
+    CommandFailedError,
+    CommandTimeoutError,
+    ConfigurationError,
+    MissingAPIKeyError,
+    RateLimitError,
+    RepositoryError,
+    ServiceError,
+    SmartLinuxAssistantError,
+    ValidationError,
+)
+
+__all__ = [
+    "SmartLinuxAssistantError",
+    "ConfigurationError",
+    "RepositoryError",
+    "ServiceError",
+    "ValidationError",
+    "CommandExecutionError",
+    "CommandTimeoutError",
+    "CommandFailedError",
+    "MissingAPIKeyError",
+    "RateLimitError",
+]

linux_assistant/exceptions/base.py

@@ -0,0 +1,98 @@
+"""
+exception hierarchy for the Smart Linux Assistant.
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from linux_assistant.models import CommandResult
+
+class SmartLinuxAssistantError(Exception):
+    """
+    Base exception for the entire application.
+    """
+
+
+class ConfigurationError(SmartLinuxAssistantError):
+    """
+    Raised when the application configuration is missing, invalid,
+    or cannot be initialized correctly.
+    """
+
+
+class RepositoryError(SmartLinuxAssistantError):
+    """
+    Raised when a repository cannot read from or write to its
+    underlying data source.
+    """
+
+
+class ServiceError(SmartLinuxAssistantError):
+    """
+    Raised when a business service cannot complete the requested
+    operation due to an application-level failure.
+    """
+
+
+class ValidationError(SmartLinuxAssistantError):
+    """
+    Raised when user-provided or internally generated data fails
+    validation before processing.
+    """
+    
+class CommandExecutionError(ServiceError):
+    """
+    Raised when a shell command cannot be executed at all, for
+    example because the shell could not be spawned or the system
+    refused to run it. This does NOT cover commands that ran but
+    returned a non-zero exit code; a non-zero exit code is a normal,
+    successfully-reported outcome captured in CommandResult.
+    """
+
+
+class CommandTimeoutError(CommandExecutionError):
+    """
+    Raised when a shell command exceeds its allotted timeout and is
+    forcibly terminated before completion.
+    """
+    
+class CommandFailedError(ServiceError):
+    """
+    Raised by execute_checked() when a command runs to completion but
+    exits with a non-zero status code. This is distinct from
+    CommandExecutionError: the command DID execute successfully at
+    the OS level, it simply reported failure via its exit code.
+    """
+
+    def __init__(self, result: "CommandResult") -> None:
+        self.result = result
+        message = (
+            f"Command '{result.command}' failed with exit code "
+            f"{result.exit_code}."
+        )
+        super().__init__(message)
+        
+        
+class MissingAPIKeyError(ConfigurationError):
+    """
+    Raised when an AI-powered feature is used but the required API
+    key environment variable is not set.
+    """
+
+    def __init__(self, env_var_name: str) -> None:
+        self.env_var_name = env_var_name
+        message = (
+            f"The '{env_var_name}' environment variable is not set. "
+            f"Get a free API key at https://console.groq.com and set it with:\n"
+            f"  export {env_var_name}=\"your-key-here\""
+        )
+        super().__init__(message)
+        
+        
+class RateLimitError(ServiceError):
+    """
+    Raised when an AI-powered feature hits the API provider's rate
+    limit. This is a transient condition — retrying after a short
+    delay will typically succeed.
+    """

linux_assistant/models/__init__.py

@@ -0,0 +1,11 @@
+"""
+Expose the application's public domain models.
+Importing models from this package keeps the rest of the project
+independent of the underlying file layout.
+"""
+
+from .command_result import CommandResult
+
+__all__ = [
+    "CommandResult",
+]

linux_assistant/models/command_result.py

@@ -0,0 +1,51 @@
+"""
+Domain model representing the result of a Linux command.
+
+This model acts as the common language between different parts of
+the application. Whether a command is executed by the CLI, collected
+by a background daemon, or later exposed through a FastAPI endpoint,
+its outcome should be represented using this object.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(slots=True, frozen=True)
+class CommandResult:
+    """
+    Store the outcome of a single command execution.
+        command:
+            The exact command that was executed.
+
+        exit_code:
+            Exit status returned by the operating system.
+
+        stdout:
+            Standard output produced by the command.
+
+        stderr:
+            Standard error produced by the command.
+
+        executed_at:
+            Timestamp indicating when the command finished executing.
+        duration_seconds:
+            Time taken to execute the command, in seconds.
+    """
+
+    command: str
+    exit_code: int
+    stdout: str
+    stderr: str
+    executed_at: datetime
+    duration_seconds: float
+
+    @property
+    def succeeded(self) -> bool:
+        return self.exit_code == 0
+
+    @property
+    def failed(self) -> bool:
+        return not self.succeeded

linux_assistant/services/__init__.py

@@ -0,0 +1,2 @@
+def __init__(self) -> None:
+        self._client = build_groq_client()

linux_assistant/services/command_executor.py

@@ -0,0 +1,109 @@
+"""
+Execute Linux commands and return structured results.
+"""
+
+from __future__ import annotations
+import subprocess
+import time
+from datetime import datetime, timezone
+from linux_assistant.exceptions import ValidationError, CommandExecutionError, CommandTimeoutError, CommandFailedError
+from linux_assistant.models import CommandResult
+from linux_assistant.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class CommandExecutor:
+    """
+    Execute Linux shell commands.
+    """
+
+    def execute(
+        self,
+        command: str,
+        timeout: int = 30,
+    ) -> CommandResult:
+        """
+        Execute a Linux command.
+        """
+        command = command.strip()
+        
+        if not command:
+            raise ValidationError("Command cannot be empty.")
+        
+        if timeout <= 0:
+            raise ValidationError("Timeout must be greater than zero.")
+        logger.info("Executing command: %s", command)
+
+        start_time = time.perf_counter()
+        try:
+            completed_process = subprocess.run(
+                command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            duration = time.perf_counter() - start_time
+            logger.error(
+                "Command timed out after %.3f seconds: %s",
+                duration,
+                command,
+            )
+            raise CommandTimeoutError(
+                f"Command '{command}' timed out after {timeout} seconds."
+            ) from exc
+        except OSError as exc:
+            duration = time.perf_counter() - start_time
+            logger.error(
+                "Command could not be executed: %s (%s)",
+                command,
+                exc,
+            )
+            raise CommandExecutionError(
+                f"Command '{command}' could not be executed: {exc}"
+            ) from exc
+            
+        duration = time.perf_counter() - start_time
+
+        logger.info(
+            "Command finished with exit code %d in %.3f seconds.",
+            completed_process.returncode,
+            duration,
+        )
+
+        return CommandResult(
+            command=command,
+            exit_code=completed_process.returncode,
+            stdout=completed_process.stdout.strip(),
+            stderr=completed_process.stderr.strip(),
+            executed_at=datetime.now(timezone.utc),
+            duration_seconds=duration,
+        )
+    
+    def execute_checked(
+        self,
+        command: str,
+        timeout: int = 30,
+    ) -> CommandResult:
+        """
+        Execute a Linux command and raise if it fails.
+        Behaves exactly like execute(), except that a non-zero exit
+        code raises CommandFailedError instead of being returned
+        silently inside a CommandResult. Use this when a failed
+        command should be treated as an exceptional condition rather
+        than a normal outcome the caller must check manually.
+        """
+        result = self.execute(command, timeout=timeout)
+
+        if result.failed:
+            logger.error(
+                "Command '%s' failed with exit code %d.",
+                result.command,
+                result.exit_code,
+            )
+            raise CommandFailedError(result)
+
+        return result

linux_assistant/services/explainer.py

@@ -0,0 +1,141 @@
+"""
+AI-powered explanations for Linux commands and error messages.
+"""
+
+from __future__ import annotations
+import groq
+from linux_assistant.utils.groq_client import GROQ_MODEL, build_groq_client
+from linux_assistant.exceptions import MissingAPIKeyError, ServiceError, ValidationError, RateLimitError
+from linux_assistant.utils.logger import get_logger
+from linux_assistant.utils.groq_client import GROQ_MODEL, build_groq_client, truncate_for_api
+
+logger = get_logger(__name__)
+
+SYSTEM_PROMPT = """You are an elite Linux System Administrator and DevOps expert. Your primary role is to analyze, explain, and troubleshoot Linux shell commands, shell scripts, error messages, and terminal output. 
+
+Your tone should be professional, direct, and accessible, translating complex technical concepts into plain language without losing accuracy. 
+
+When responding, strictly adhere to the following guidelines:
+
+1. STRUCTURED BREAKDOWNS: When explaining a command, break it down logically. Briefly explain what the entire command does, then use standard dashes (-) to list and explain each specific flag, option, and argument.
+2. TROUBLESHOOTING PROTOCOL: If the user provides an error message or broken script, always include:
+   - Root Cause: A brief explanation of why it failed.
+   - The Fix: The exact, corrected command or action required.
+   - Verification: How the user can verify the fix worked.
+3. SAFETY FIRST: If a command is destructive (e.g., involves rm -rf, dd, chmod 777, or partition changes), clearly prepend a [WARNING] to your response explaining the risk and how to execute it safely.
+4. BEST PRACTICES: Where applicable, suggest modern or more efficient alternatives (e.g., using ip instead of ifconfig).
+5. TERMINAL-SAFE FORMATTING: Do NOT use any Markdown formatting. Your output is being displayed in a raw text terminal. Do not use asterisks for bolding, hashes for headers, or backticks for code. Instead, use ALL CAPS for section headers. To highlight commands or file paths, simply indent them with spaces on a new line or wrap them in single quotes (' ').
+
+Keep responses concise and scannable. Limit your response to the essential information needed to solve the user's problem or answer their question, avoiding unnecessary fluff.
+"""
+
+FIX_SYSTEM_PROMPT = """You are an automated Linux command correction tool operating in a raw terminal. You receive a failed shell command and its corresponding error message. Your single purpose is to output the exact, executable corrected command.
+
+CRITICAL CONSTRAINTS:
+1. Output ONLY the corrected command on a single line.
+2. Provide zero conversational filler (do not start with "Here is the command" or "Try this").
+3. Use zero Markdown formatting (no backticks or formatting blocks).
+4. Do not include quotes or a leading '$' prompt.
+5. Retain the user's original filenames, paths, and valid arguments exactly as provided; do not substitute them with generic placeholders.
+6. If you cannot determine a highly confident fix, output exactly: NO_FIX_AVAILABLE
+"""
+
+
+class Explainer:
+    """
+    Generate plain-language explanations of Linux commands or errors
+    using an LLM.
+    """
+
+    def __init__(self) -> None:
+        self._client = build_groq_client()
+
+    def explain(self, text: str) -> str:
+        """
+        Explain a command or error message in plain language.
+        ValidationError: If text is empty or whitespace-only.
+        ServiceError: If the underlying API call fails.
+        """
+        text = text.strip()
+
+        if not text:
+            from linux_assistant.exceptions import ValidationError
+
+            raise ValidationError("Text to explain cannot be empty.")
+
+        text = truncate_for_api(text)
+
+        logger.info("Requesting explanation for: %s", text)
+
+        try:
+            response = self._client.chat.completions.create(
+                model=GROQ_MODEL,
+                messages=[
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {"role": "user", "content": text},
+                ],
+            )
+        except groq.RateLimitError as exc:
+            logger.error("Rate limit hit: %s", exc)
+            raise RateLimitError(
+                "Groq API rate limit reached. Please wait a moment and try again."
+            ) from exc
+        except Exception as exc:
+            logger.error("Explanation request failed: %s", exc)
+            raise ServiceError(f"Failed to get explanation: {exc}") from exc
+        
+        explanation = response.choices[0].message.content
+        if explanation is None:
+            raise ServiceError("Received an empty explanation from the API.")
+        logger.info("Explanation received (%d characters).", len(explanation))
+
+        return explanation.strip()
+    
+    def suggest_fix(self, command: str, error: str) -> str | None:
+        """
+        Suggest a corrected version of a failed shell command.
+        """
+        command = command.strip()
+
+        if not command:
+            from linux_assistant.exceptions import ValidationError
+
+            raise ValidationError("Command to fix cannot be empty.")
+
+        error = truncate_for_api(error, keep_end=True)
+
+        user_content = f"Command: {command}\nError: {error.strip()}"
+
+        logger.info("Requesting fix suggestion for: %s", command)
+
+        try:
+            response = self._client.chat.completions.create(
+                model=GROQ_MODEL,
+                messages=[
+                    {"role": "system", "content": FIX_SYSTEM_PROMPT},
+                    {"role": "user", "content": user_content},
+                ],
+            )
+        except groq.RateLimitError as exc:
+            logger.error("Rate limit hit: %s", exc)
+            raise RateLimitError(
+                "Groq API rate limit reached. Please wait a moment and try again."
+            ) from exc
+        except Exception as exc:
+            logger.error("Explanation request failed: %s", exc)
+            raise ServiceError(f"Failed to get explanation: {exc}") from exc
+
+        suggestion = response.choices[0].message.content
+
+        if suggestion is None:
+            raise ServiceError("Received an empty fix suggestion from the API.")
+
+        suggestion = suggestion.strip()
+
+        if suggestion == "NO_FIX_AVAILABLE":
+            logger.info("No confident fix available for: %s", command)
+            return None
+
+        logger.info("Fix suggestion received: %s", suggestion)
+
+        return suggestion

linux_assistant/services/search.py

@@ -0,0 +1,77 @@
+"""
+AI-powered natural-language search for Linux commands and tasks.
+"""
+
+from __future__ import annotations
+import groq
+from linux_assistant.exceptions import ServiceError, ValidationError, RateLimitError
+from linux_assistant.utils.groq_client import GROQ_MODEL, build_groq_client
+from linux_assistant.utils.logger import get_logger
+from linux_assistant.utils.groq_client import GROQ_MODEL, build_groq_client, truncate_for_api
+
+logger = get_logger(__name__)
+
+SEARCH_SYSTEM_PROMPT = """You are a Linux command lookup tool operating in a raw terminal. The user will describe a desired action in plain language. Your objective is to provide a concrete, ready-to-run command and a brief explanation.
+
+CRITICAL CONSTRAINTS:
+1. COMMAND FORMAT: Place the suggested command on its own line, prefixed with exactly "$ ". 
+2. EXPLANATION: Provide a 1-2 sentence practical explanation on the line immediately below the command.
+3. ZERO MARKDOWN: Do NOT use backticks (`), asterisks (*), or hashes (#). Output pure raw text.
+4. ZERO FILLER: Do not use conversational openings like "Sure" or "Here is the command". Start immediately with the "$ " command line.
+5. READY-TO-RUN (NO PLACEHOLDERS): Always use realistic, runnable values in the command itself. Use standard defaults (like '.' for the current directory) or plausible example filenames (like 'example.txt'). NEVER use angle-bracket placeholders like <directory_path> or <filename>. The user should be able to copy and run the command directly.
+6. BREVITY: Keep the entire response strictly under 120 words.
+"""
+
+
+class Searcher:
+    """
+    Answer natural-language questions about Linux commands and tasks.
+    """
+
+    def __init__(self) -> None:
+        self._client = build_groq_client()
+
+    def search(self, query: str) -> str:
+        """
+        Answer a natural-language question about a Linux task.
+
+        Args:
+            query: The user's question, e.g. "how do I find large files".
+
+        Returns:
+            A short, practical answer.
+        """
+        query = query.strip()
+
+        if not query:
+            raise ValidationError("Search query cannot be empty.")
+
+        query = truncate_for_api(query)
+
+        logger.info("Searching for: %s", query)
+
+        try:
+            response = self._client.chat.completions.create(
+                model=GROQ_MODEL,
+                messages=[
+                    {"role": "system", "content": SEARCH_SYSTEM_PROMPT},
+                    {"role": "user", "content": query},
+                ],
+            )
+        except groq.RateLimitError as exc:
+            logger.error("Rate limit hit: %s", exc)
+            raise RateLimitError(
+                "Groq API rate limit reached. Please wait a moment and try again."
+            ) from exc
+        except Exception as exc:
+            logger.error("Explanation request failed: %s", exc)
+            raise ServiceError(f"Failed to get explanation: {exc}") from exc
+
+        answer = response.choices[0].message.content
+
+        if answer is None:
+            raise ServiceError("Received an empty answer from the API.")
+
+        logger.info("Search answer received (%d characters).", len(answer))
+
+        return answer.strip()

linux_assistant/utils/groq_client.py

@@ -0,0 +1,65 @@
+"""
+Shared Groq client construction for AI-powered services.
+"""
+
+from __future__ import annotations
+import os
+from groq import Groq
+from linux_assistant.exceptions import MissingAPIKeyError
+
+GROQ_API_KEY = "GROQ_API_KEY"
+GROQ_MODEL = "llama-3.3-70b-versatile"
+
+MAX_INPUT_CHARACTERS = 4000
+REQUEST_TIMEOUT_SECONDS = 30.0
+MAX_RETRIES = 2
+
+
+def build_groq_client() -> Groq:
+    """
+    Construct an authenticated Groq client using the GROQ_API_KEY
+    environment variable.
+
+    The client is configured with a request timeout and automatic
+    retries for transient failures (connection errors, timeouts, and
+    5xx server errors), handled internally by the Groq SDK.
+
+    Raises:
+        MissingAPIKeyError: If the environment variable is not set.
+    """
+    api_key = os.environ.get(GROQ_API_KEY)
+
+    if not api_key:
+        raise MissingAPIKeyError(GROQ_API_KEY)
+
+    return Groq(
+        api_key=api_key,
+        timeout=REQUEST_TIMEOUT_SECONDS,
+        max_retries=MAX_RETRIES,
+    )
+    
+def truncate_for_api(text: str, *, keep_end: bool = False) -> str:
+    """
+    Truncate text to a safe length before sending it to the API,
+    avoiding excessive token usage or provider-side length limits.
+
+    Args:
+        text: The text to truncate.
+        keep_end: If True, keep the end of the text and truncate from
+            the start (useful for error output, where the final lines
+            are usually most relevant). If False, keep the beginning
+            and truncate from the end.
+
+    Returns:
+        The original text if already within the limit, otherwise a
+        truncated version with a marker indicating truncation occurred.
+    """
+    if len(text) <= MAX_INPUT_CHARACTERS:
+        return text
+
+    marker = "...[truncated]..."
+    available = MAX_INPUT_CHARACTERS - len(marker)
+
+    if keep_end:
+        return marker + text[-available:]
+    return text[:available] + marker

linux_assistant/utils/logger.py

@@ -0,0 +1,54 @@
+"""
+Centralized logging configuration for the Smart Linux Assistant.
+"""
+
+from __future__ import annotations
+
+import logging
+from logging.handlers import RotatingFileHandler
+from linux_assistant.config.settings import settings
+
+
+LOG_FILE = settings.logs_directory / "smart_linux_assistant.log"
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Return a configured logger for the given module.
+    """
+
+    logger = logging.getLogger(name)
+
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(logging.INFO)
+
+    formatter = logging.Formatter(
+        fmt=(
+            "%(asctime)s | "
+            "%(levelname)-8s | "
+            "%(name)s | "
+            "%(message)s"
+        ),
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+    
+    LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    file_handler = RotatingFileHandler(
+        filename=LOG_FILE,
+        maxBytes=5 * 1024 * 1024,
+        backupCount=5,
+        encoding="utf-8",
+    )
+    file_handler.setFormatter(formatter)
+
+    logger.addHandler(console_handler)
+    logger.addHandler(file_handler)
+
+    logger.propagate = False
+
+    return logger

linux_assistant/utils/shell.py

@@ -0,0 +1,31 @@
+"""
+Shell-level utilities for checking the system environment.
+"""
+
+from __future__ import annotations
+
+import shutil
+
+from linux_assistant.exceptions import ValidationError
+from linux_assistant.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def command_exists(name: str) -> bool:
+    """
+    Check whether a command is available on the system's PATH.
+    """
+    name = name.strip()
+
+    if not name:
+        raise ValidationError("Command name cannot be empty.")
+
+    found_path = shutil.which(name)
+
+    if found_path is None:
+        logger.info("Command '%s' was not found on PATH.", name)
+        return False
+
+    logger.info("Command '%s' found at '%s'.", name, found_path)
+    return True

smart_linux_assistant-0.5.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: smart-linux-assistant
+Version: 0.5.0
+Summary: An AI-powered Linux productivity assistant for command analysis, troubleshooting, and knowledge management.
+Author: Shubham Kumar Jha
+License: MIT
+Project-URL: Homepage, https://github.com/shubham-k-jha-dev/smart-linux-assistant
+Project-URL: Repository, https://github.com/shubham-k-jha-dev/smart-linux-assistant
+Project-URL: Issues, https://github.com/shubham-k-jha-dev/smart-linux-assistant/issues
+Keywords: linux,cli,automation,terminal,devops,shell,productivity
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: groq>=0.9.0
+Dynamic: license-file
+
+# Smart Linux Assistant
+
+Smart Linux Assistant is an AI-powered Linux operations assistant that understands natural language, safely executes shell commands, retrieves Linux knowledge, explains errors, and assists users with troubleshooting. The current version implements the core command execution engine and foundational architecture for future AI capabilities.
+
+![Python](https://img.shields.io/badge/python-3.11%2B-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-lightgrey)
+[![CI](https://github.com/shubham-k-jha-dev/smart-linux-assistant/actions/workflows/ci.yml/badge.svg)](https://github.com/shubham-k-jha-dev/smart-linux-assistant/actions/workflows/ci.yml)
+
+## Project Overview
+
+Smart Linux Assistant is a command-line utility that executes shell commands and returns structured outcomes. The tool captures the command, exit code, stdout, stderr, execution timestamp, and duration to make downstream automation and logging straightforward.
+
+## System Architecture
+
+- CLI (`linux_assistant.cli.main`) accepts user commands and options and delegates execution to `CommandExecutor`.
+- `CommandExecutor` runs shell commands using `subprocess.run` and returns a `CommandResult` dataclass describing the outcome.
+- Centralized logging is provided by `linux_assistant.utils.logger`, writing to `logs/smart_linux_assistant.log` with rotation.
+- Runtime paths and directories are managed by `linux_assistant.config.settings` and can be initialized with `initialize_app_filesystem()`.
+
+## Tech Stack
+
+- Python 3.11+
+- Typer (CLI)
+- Standard library: `subprocess`, `logging`, `shutil`, `dataclasses`, `pathlib`, `datetime`
+
+## Prerequisites
+
+1. Python 3.11 or newer.
+2. Optional: a virtual environment tool (`venv`).
+3. No Dockerfile or docker-compose are included in this repository.
+
+## Local Setup & Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/shubham-k-jha-dev/smart-linux-assistant
+cd smart-linux-assistant
+```
+
+2. Create and activate a virtual environment:
+
+```bash
+# Linux/macOS
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Windows (PowerShell)
+python -m venv .venv
+.venv\\Scripts\\Activate.ps1
+```
+
+3. Install development dependencies:
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+4. (Optional) Install the package in editable mode to enable the `smart-linux` CLI entrypoint:
+
+```bash
+pip install -e .
+```
+
+5. (Optional) Ensure runtime directories exist from Python:
+
+```python
+from linux_assistant.config.settings import initialize_app_filesystem
+initialize_app_filesystem()
+```
+
+## Environment Variables
+
+This project does not require any environment variables for its core CLI functionality. The repository includes an empty `.env.example` placeholder.
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| (none) | No required environment variables for CLI execution | - |
+
+## Usage / API Reference
+
+The project exposes the console scripts `smart-linux` and `sla` (configured in `pyproject.toml`).
+
+- Run a shell command:
+
+```bash
+smart-linux run "echo hello"
+```
+
+- Options:
+  - `--timeout <seconds>` — maximum seconds to allow command to run (default: 30)
+  - `--check` — treat non-zero exit codes as errors and exit with that code
+  - `--suggest-fix` — if the command fails, use AI to suggest a corrected version (requires `--check`; requires `GROQ_API_KEY`, same as `explain`/`fix`/`search`)
+
+- Doctor command (checks common tools):
+
+```bash
+smart-linux doctor
+```
+- Get an AI-powered explanation of a command or error message:
+
+```bash
+smart-linux explain "permission denied when running ./script.sh"
+```
+
+  Requires a free Groq API key set as an environment variable:
+
+```bash
+export GROQ_API_KEY="your-key-here"
+```
+
+  Get a free key at [console.groq.com](https://console.groq.com).
+
+- Fix a failing command:
+
+```bash
+smart-linux fix "ls /nonexistent"
+```
+
+- Options:
+  - `--timeout <seconds>` — maximum seconds to allow the command to run (default: 30)
+
+- This runs the command and, if it fails, uses the AI to suggest a corrected version. Requires the same `GROQ_API_KEY` environment variable as the `explain` command.
+
+- Search for a Linux task in plain language:
+
+```bash
+smart-linux search "find the 10 largest files in the current directory"
+```
+
+- This returns a concrete command and brief explanation for the requested task. Requires the same `GROQ_API_KEY` environment variable as the `explain` command.
+
+### Example output
+
+Successful command:
+
+```bash
+$ smart-linux run "echo hello"
+hello
+```
+
+Failed command (example):
+
+```bash
+$ smart-linux run "ls nonexistent" --check
+ls: cannot access 'nonexistent': No such file or directory
+```
+
+These outputs reflect the CLI behaviour: standard output is printed for successful commands; standard error is printed for failures and, when `--check` is used, the CLI exits with the command's exit code.
+
+Failed command with an AI-suggested fix:
+
+```bash
+$ smart-linux run "gti status" --check --suggest-fix
+gti: command not found
+
+Suggested fix:
+  git status
+```
+
+`--suggest-fix` requires `--check` (fix suggestions only apply to command failures detected via `--check`); calling it without `--check` exits immediately with an error.
+
+## Roadmap / Current Status
+
+- Core CLI: implemented — `run` and `doctor` commands are provided in `linux_assistant.cli.main`.
+- Command execution: implemented using `linux_assistant.services.command_executor.CommandExecutor` which returns `CommandResult` instances.
+- Logging & configuration: implemented via `linux_assistant.utils.logger` and `linux_assistant.config.settings`.
+- Packaging: console script entry points are declared in `pyproject.toml`.
+- AI-powered explanations: implemented — `smart-linux explain` uses the Groq API (`llama-3.3-70b-versatile`) to generate plain-language explanations of commands and error messages, via `linux_assistant.services.explainer.Explainer`. Requires a user-supplied `GROQ_API_KEY` environment variable.
+- AI-powered fix suggestions: implemented — `smart-linux fix` runs a failing command and suggests a corrected version; `smart-linux run --check --suggest-fix` offers the same suggestion inline as part of normal command execution. Both use `linux_assistant.services.explainer.Explainer.suggest_fix()`.
+- AI-powered search: implemented — `smart-linux search` answers natural-language questions about Linux tasks via `linux_assistant.services.search.Searcher`.
+- Production hardening: implemented — API timeouts, retry logic, rate-limit-specific handling, input truncation, and documented OS/privacy limitations across all AI-backed commands.
+- Additional AI features (command history awareness, documentation lookup) are planned but not yet implemented.
+
+## Known Limitations
+
+- Tested and verified on Linux (native and WSL). Not yet tested on macOS or native Windows Python — behavior on those platforms is currently unverified, though the codebase avoids Linux-only APIs where possible.
+
+## Privacy Note
+
+The `explain`, `fix`, and `search` commands send the command text, error output, or your query to Groq's API for processing. Avoid running these commands on text that contains secrets, passwords, or sensitive data, since that content leaves your machine.
+
+## Install from PyPI
+
+If this package is published to PyPI, it can be installed with:
+
+```bash
+pip install smart-linux-assistant
+```
+
+## Testing
+
+Run the test suite with `pytest`:
+
+```bash
+pytest
+```
+
+## License
+
+MIT License — see `LICENSE`.
+
+## Contributing
+
+- Run tests with `pytest` before opening a pull request.
+- Follow standard Python packaging best practices.

smart_linux_assistant-0.5.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+linux_assistant/__init__.py,sha256=ZtxUCkFFzbqtXCAYGt_FhBSiAsWhJkcecOv9e6tbnUs,233
+linux_assistant/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linux_assistant/cli/main.py,sha256=9Pupxu5ppg6j3AAdsUjQEUZmi4rvSAXT-GIuu8Qr5wQ,8783
+linux_assistant/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linux_assistant/config/settings.py,sha256=Ll1QLfgxwON6tst2-uRMHPTx2ACL5CypkjBm0CXsd_w,2187
+linux_assistant/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linux_assistant/exceptions/__init__.py,sha256=Nw2jvBHkML5Wg02zr-gR7G0XCwxmJId9a1eE8jy77eM,737
+linux_assistant/exceptions/base.py,sha256=85oWenBiosghSjzuz95Tzh7APE6O34wkH587Obz2-FU,3015
+linux_assistant/models/__init__.py,sha256=GXMAMk8W_s2XzQ7KoBWS2G8l_tOa8DvOpwopADbBLN0,251
+linux_assistant/models/command_result.py,sha256=E7Ik3idYMI7-5eEjliriUu8QCxd3ndhcb_aH0Va8fHs,1346
+linux_assistant/repositories/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linux_assistant/services/__init__.py,sha256=XZOAN1X6KMgVQQ0gcvsgJ2-VSLlDvBrrGFFKCW2g5Uc,71
+linux_assistant/services/command_executor.py,sha256=NKVka5u6N64vJ3REDIcK0WaGIVIu8kYgLker1VClwuI,3489
+linux_assistant/services/explainer.py,sha256=3oO0wu_cgMn1WI1BE-jgLRjbVZ7kwl9yTOKRmTUghOg,6592
+linux_assistant/services/search.py,sha256=kHVERaIycVTFz9y-Z27SRLks94EXOScj6tkRm8KVCAY,3269
+linux_assistant/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linux_assistant/utils/groq_client.py,sha256=lLiV6nJpSQxuZ1SKDfZriVgVKvNUb4-aYNZYS8DGvcI,1966
+linux_assistant/utils/logger.py,sha256=wBMPv6VcqkKPapXDyAA6rhMTtoSCzTJ8C1VAIJAPYFA,1273
+linux_assistant/utils/shell.py,sha256=in4zz7uQiM4w7nqEdFz6Vem_zMqc0dCDu8fNRMieVS0,744
+smart_linux_assistant-0.5.0.dist-info/licenses/LICENSE,sha256=jo3I7AiH6gbrwm977FhHWRGmpkgpo4K3sPFhLg2R9kg,1074
+smart_linux_assistant-0.5.0.dist-info/METADATA,sha256=2v9kYvocOq8Op9eN69ekD2_AvMbHJEN6hMFOxWPIP9M,8748
+smart_linux_assistant-0.5.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+smart_linux_assistant-0.5.0.dist-info/entry_points.txt,sha256=bIeHREzxAeh5t4rP4ESLqwUBStKYdlHVhUdYlr0SEok,96
+smart_linux_assistant-0.5.0.dist-info/top_level.txt,sha256=ClGTbRQlqUYxbbL_9Y_cM4nAAObdue-YdB8TbACfZeo,16
+smart_linux_assistant-0.5.0.dist-info/RECORD,,

smart_linux_assistant-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

smart_linux_assistant-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sla = linux_assistant.cli.main:app
+smart-linux = linux_assistant.cli.main:app

smart_linux_assistant-0.5.0.dist-info/licenses/LICENSE

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

smart_linux_assistant-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+linux_assistant