linux-assistant 0.1.0__tar.gz

linux_assistant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ali Fathi Jahromi
+
+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.

linux_assistant-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: linux-assistant
+Version: 0.1.0
+Summary: An AI-powered natural-language Linux assistant
+Author-email: Ali Fathi Jahromi <alifathijahromi@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Ali Fathi Jahromi
+        
+        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.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain
+Requires-Dist: click
+Dynamic: license-file
+
+# linux‑Assistant
+
+An AI-powered assistant that lets you interact with your Linux system using natural language. Ask it to list files, install packages, inspect processes, or perform any shell task—behind the scenes it translates your request into safe bash commands and runs them for you.
+
+---
+
+## Features
+
+- **Natural‑language interface**: Describe what you want to do—no need to remember exact commands.  
+- **Interactive shell execution**: The assistant decides when to run commands, executes them in a temporary script, and returns the output.  
+- **Continuous conversation**: You can follow up on results, ask for clarifications, or chain multiple operations in one session.  
+- **Customizable**: Swap in any Ollama‑compatible model and adjust prompts to suit your workflow.
+
+---
+
+## Prerequisites
+
+- **Linux** with Bash installed  
+- **Python 3.12+**  
+- [Ollama CLI & daemon](https://ollama.com/) with at least one local model (e.g. `qwen3:8b`)  
+- (Optional but recommended) A dedicated Python virtual environment
+
+---
+
+## Installation
+
+1. **Clone the repository**  
+   ```bash
+   git clone https://github.com/alifthi/linux-Assistant.git
+   cd linux-Assistant
+   ```
+
+2. **Set up a virtual environment**  
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+3. **Install ollama and pull model**
+   ```bash 
+   curl -fsSL https://ollama.com/install.sh | sh
+   ollama pull qwen3:8B  # Or any other models you want to use
+   ```
+4. **Install dependencies**  
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+---
+
+## Configuration
+
+Open **`models/config.py`** and adjust:
+
+- `MODEL_NAME` – the Ollama model you wish to use (e.g. `"qwen3:8b"`).  
+- `SYSTEM_PROMPT` – how the assistant should frame its replies and decide when to run shell commands.
+
+---
+
+## Usage
+
+Run the assistant and start chatting:
+
+```bash
+cd src
+python -m linux_assistant
+```
+
+- Ask anything you would normally do in the terminal.
+
+- Continue the conversation naturally or type `exit` to quit.
+---
+Run the assistant using Docker
+
+```bash
+docker run --name <Container's name> \
+   -v linux_assistant_volume:/app/data \
+   -v "$(pwd)":/app/workspace alifthi/linux-assistant 
+
+```
+
+---
+
+## Contributing
+
+Contributions and feedback are welcome! Feel free to:
+
+- Open issues for bugs or feature requests  
+- Submit pull requests to improve prompts, handling, or documentation  
+- Suggest new use cases or integrations
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for details.  

linux_assistant-0.1.0/README.md

@@ -0,0 +1,95 @@
+# linux‑Assistant
+
+An AI-powered assistant that lets you interact with your Linux system using natural language. Ask it to list files, install packages, inspect processes, or perform any shell task—behind the scenes it translates your request into safe bash commands and runs them for you.
+
+---
+
+## Features
+
+- **Natural‑language interface**: Describe what you want to do—no need to remember exact commands.  
+- **Interactive shell execution**: The assistant decides when to run commands, executes them in a temporary script, and returns the output.  
+- **Continuous conversation**: You can follow up on results, ask for clarifications, or chain multiple operations in one session.  
+- **Customizable**: Swap in any Ollama‑compatible model and adjust prompts to suit your workflow.
+
+---
+
+## Prerequisites
+
+- **Linux** with Bash installed  
+- **Python 3.12+**  
+- [Ollama CLI & daemon](https://ollama.com/) with at least one local model (e.g. `qwen3:8b`)  
+- (Optional but recommended) A dedicated Python virtual environment
+
+---
+
+## Installation
+
+1. **Clone the repository**  
+   ```bash
+   git clone https://github.com/alifthi/linux-Assistant.git
+   cd linux-Assistant
+   ```
+
+2. **Set up a virtual environment**  
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+3. **Install ollama and pull model**
+   ```bash 
+   curl -fsSL https://ollama.com/install.sh | sh
+   ollama pull qwen3:8B  # Or any other models you want to use
+   ```
+4. **Install dependencies**  
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+---
+
+## Configuration
+
+Open **`models/config.py`** and adjust:
+
+- `MODEL_NAME` – the Ollama model you wish to use (e.g. `"qwen3:8b"`).  
+- `SYSTEM_PROMPT` – how the assistant should frame its replies and decide when to run shell commands.
+
+---
+
+## Usage
+
+Run the assistant and start chatting:
+
+```bash
+cd src
+python -m linux_assistant
+```
+
+- Ask anything you would normally do in the terminal.
+
+- Continue the conversation naturally or type `exit` to quit.
+---
+Run the assistant using Docker
+
+```bash
+docker run --name <Container's name> \
+   -v linux_assistant_volume:/app/data \
+   -v "$(pwd)":/app/workspace alifthi/linux-assistant 
+
+```
+
+---
+
+## Contributing
+
+Contributions and feedback are welcome! Feel free to:
+
+- Open issues for bugs or feature requests  
+- Submit pull requests to improve prompts, handling, or documentation  
+- Suggest new use cases or integrations
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for details.  

linux_assistant-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "linux-assistant"
+version = "0.1.0"
+description = "An AI-powered natural-language Linux assistant"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Ali Fathi Jahromi", email = "alifathijahromi@gmail.com" }]
+requires-python = ">=3.9"
+dependencies = ["langchain", "click"]
+
+[project.scripts]
+linux-assistant = "linux_assistant.__main__:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

linux_assistant-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

linux_assistant-0.1.0/src/linux_assistant/__init__.py

@@ -0,0 +1,4 @@
+# linux_assistant/__init__.py
+
+__version__ = "0.1.0"
+

linux_assistant-0.1.0/src/linux_assistant/__main__.py

@@ -0,0 +1,33 @@
+
+import click
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def cli(ctx):
+    """Linux Assistant CLI"""
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(run)
+
+
+@cli.command()
+def run():
+    from linux_assistant.runtime.checks import require_llama
+    require_llama()
+    
+    from linux_assistant.app import run_app
+    run_app()
+
+
+@cli.command()
+def setup():
+    from linux_assistant.setup import setup_cmd
+    setup_cmd()
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

linux_assistant-0.1.0/src/linux_assistant/app.py

@@ -0,0 +1,25 @@
+from linux_assistant.graph.graph import build_graph
+from linux_assistant.utils.dicts import AgentState
+from linux_assistant.utils.console_utils import console_utils
+
+
+def run_app():
+    app = build_graph()
+    console = console_utils()
+
+    state: AgentState = {"messages": [], "logger": console}
+
+    console.release_banner()
+
+    while True:
+        input_text = console.get_user_input()
+
+        if input_text == "exit":
+            break
+
+        state["messages"].append({
+            "role": "user",
+            "content": input_text
+        })
+
+        state = app.invoke(state)

linux_assistant-0.1.0/src/linux_assistant/graph/config.py

@@ -0,0 +1,3 @@
+MAX_SEARCH_RESULTS = 5
+WIKIPEDIA_RESULTS = 1
+SHOW_CODE_OUTPUT = False

linux_assistant-0.1.0/src/linux_assistant/graph/graph.py

@@ -0,0 +1,30 @@
+from linux_assistant.graph.nodes import shell_node, prepare_shell_code,\
+                        tool_select, prepare_tool_prompt, prepare_search_query, search_tools
+from linux_assistant.utils.dicts import AgentState
+from linux_assistant.models.model_nodes import model_nodes
+from langgraph.graph import StateGraph, START,END
+
+def build_graph() -> StateGraph:
+    ''' This function builds graph '''
+    call_model = model_nodes()
+    search = search_tools()
+    graph = StateGraph(AgentState)
+    graph.set_entry_point('call_model')
+    graph.add_node('call_model', call_model.call_model)
+    graph.add_node('prepare_tool_prompt', prepare_tool_prompt)
+    graph.add_node('prepare_shell_code',prepare_shell_code)
+    graph.add_node('shell_node', shell_node)
+    graph.add_conditional_edges(
+        "call_model",
+        tool_select,
+        {'shell_node': 'prepare_shell_code', "search_node": "prepare_search_query" ,"nothing": END}
+    )
+    graph.add_node('prepare_search_query', prepare_search_query)
+    graph.add_node('search_node', search.search_node)
+    graph.add_edge('prepare_search_query', 'search_node')
+    graph.add_edge('search_node', 'call_model')
+    graph.add_edge('prepare_shell_code', 'shell_node')
+    graph.add_edge('shell_node', 'prepare_tool_prompt')
+    graph.add_edge('prepare_tool_prompt','call_model')
+    app = graph.compile()
+    return app

linux_assistant-0.1.0/src/linux_assistant/graph/nodes.py

@@ -0,0 +1,110 @@
+from linux_assistant.graph.config import MAX_SEARCH_RESULTS, WIKIPEDIA_RESULTS, SHOW_CODE_OUTPUT
+from linux_assistant.utils.dicts import AgentState
+from linux_assistant.utils.subprocess import processor
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from langchain_community.tools.wikipedia.tool import WikipediaQueryRun
+from langchain_community.utilities.wikipedia import WikipediaAPIWrapper
+from ddgs import DDGS
+import time
+import gc
+
+
+
+def shell_node( state: AgentState)->  AgentState:
+    '''To run a shell code that generated with AI'''
+    state['logger'].print_text("🔧 Running shell command ...", color='blue', end='\n')
+    print("\n")
+    t = time.perf_counter()
+
+    proc = processor(show_output=SHOW_CODE_OUTPUT)
+    proc.subprocess(state['code'])
+    
+    interval = time.perf_counter() - t
+    
+    state['stdout'], state['stderr'], state['exit_code'] = proc.output['stdout'], proc.output['stderr'], proc.output['returncode']
+    if state['exit_code'] == 0:
+        state['logger'].print_text(f"✔️ Completed in {interval:.3f}s", color='green')
+    else:
+        state['logger'].print_text("❌ Exited with error...", color='red')
+    print('\n')
+    return state
+
+def tool_select(state: AgentState) -> AgentState:
+    ''' To decide witch tool is needed '''
+    last = state["messages"][-1]['content'].split('</think>')[-1]
+    if "shell_node" in last:
+        return "shell_node"
+    elif "search_node" in last:
+        return "search_node"
+    else:
+        return "nothing"
+
+def prepare_shell_code(state:AgentState) -> AgentState:
+    ''' To extract generated code '''
+    last = state["messages"][-1]['content']
+    last = last.split('shell_node')[-1]
+    last = last.split('```bash')[-1].split('```')[0]
+    state['code'] = last
+    return state
+
+def prepare_tool_prompt( state: AgentState) -> AgentState:
+    '''Prepare the output of executed command for LM'''
+    content = (
+        "Here is the output of command you generated:\n"
+        f"stdout:\n{state['stdout']}\n"
+        f"stderr:\n{state['stderr']}\n"
+        f"exit_code: {state['exit_code']}"
+    )
+    state['messages'].append({'role':'user', 'content': content})
+
+    return state
+def prepare_search_query(state: AgentState) -> AgentState:
+    '''Prepare the query for giving to search_node'''
+    last = state["messages"][-1]['content']
+    last = last.split('search_node')[-1]
+    last = last.split('```query')[-1].split('```')[0]
+    state['search_query'] = last
+    return state
+class search_tools:
+    def __init__(self):
+        wiki_api = WikipediaAPIWrapper(
+                        top_k_results=WIKIPEDIA_RESULTS,   
+                        lang="en",         
+                        doc_content_chars_max=2000
+                    )
+        self.wiki_tool = WikipediaQueryRun(
+                api_wrapper=wiki_api,
+                description="Search Wikipedia for general knowledge",
+                verbose=False
+            )
+    def search_in_wiki(self, query):
+        answer = self.wiki_tool.run(query)
+        return answer
+    @staticmethod
+    def search_duckduckgo(query):
+        with DDGS() as ddgs:
+            results = ddgs.text(query, max_results = MAX_SEARCH_RESULTS)
+        return results
+    def search_node(self, state: AgentState)-> AgentState:
+        '''A node for search'''
+        state['logger'].print_text("🔍 Searching ...", color='blue', end='\n')
+        print("\n")
+        with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                transient=True,) as prog:
+            task = prog.add_task("Searching...", total=None)
+            t = time.perf_counter()
+            wiki_search_res = self.search_in_wiki(state['search_query'])
+            ddg_res = self.search_duckduckgo(state['search_query'])
+            interval = time.perf_counter() - t
+        state['messages'].append({'role':'user', 'content': wiki_search_res})
+        for i, res in enumerate(ddg_res):
+            state['messages'].append({'role':'user', 'content': res['body']})
+        if len(ddg_res) == 0:
+            state['logger'].print_text("❌ No result found ", color='red')
+        else:
+            state['logger'].print_text(f"🔍 Search is completed in {interval}s, {len(ddg_res)} results found", color='green')
+        print('\n')
+        gc.collect()
+        return state

linux_assistant-0.1.0/src/linux_assistant/models/config.py

@@ -0,0 +1,23 @@
+SYSTEM_PROMPT = ("You are an AI assistant to help user to do the tasks that user asks with there linux os",
+                "If users asks for something that can handle with there linux at first you must generate `shell_node` token at the begining of generation", 
+                "then you must generate a Code like follow",
+                "```bash \n<your code> \n```",
+                "Do not generate any fallback response when you generate a shell code.",
+                "Do not generate more than one code block in each round of response."
+                "After executing the provided code you will recive the result of execution, then if it was successfull you should generate a fallback response else you must run another code if it's possible",
+                "Every time user asked for doing something you must generate `shell_node` token before code.",
+                "You are able to run multiple code on users linux and see the results then run another code.",
+                "each time you want to generate code only one batch of code are allowed, so do not generate multiple codes in each round of generation",
+                "If it's not possible to run another code you mut tell user that it's not possible and why.",
+                "You are able to search in web for that you must only generate `search_node` token",
+                "After that you generate the search_node you must provide the search query like follow:",
+                "```query \n<your search query>\n'''",
+                "If you need to search about your code or search about what user asked use this tool."
+                "If user didn't ask for doing anything with there linux OS only chat normally.",
+                "Do not miss special tokens before code or query")
+
+
+GENERATION_MODEL='Qwen3.5-4B-Q6_K.gguf'
+REPO_ID = "unsloth/Qwen3.5-4B-GGUF"
+
+SHOW_THINKS = False

linux_assistant-0.1.0/src/linux_assistant/models/model_nodes.py

@@ -0,0 +1,69 @@
+from llama_cpp import Llama, LlamaRAMCache
+from huggingface_hub import hf_hub_download
+from linux_assistant.models.config import SYSTEM_PROMPT, SHOW_THINKS,\
+                                        REPO_ID, GENERATION_MODEL
+from linux_assistant.utils.dicts import AgentState
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+class model_nodes:
+    def __init__(self):
+        self.model = self.build_model()
+        self.cache = LlamaRAMCache(capacity_bytes=512 << 20)
+        self.model.set_cache(self.cache)
+    def call_model(self, state: AgentState) -> AgentState:
+        ''' A node to call model '''
+        if len(state['messages']) == 1:
+            system_message = {'role':'system', 'content': SYSTEM_PROMPT} 
+            state['messages'] = [system_message] + state['messages']
+        
+        stream = self.model.create_chat_completion(
+                messages=state['messages'],
+                temperature=0.7,
+                top_p=0.95,
+                min_p=0.05,        
+                top_k=40,    
+                stream=True,
+            )
+        is_think_generated = False
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            transient=not SHOW_THINKS,) as prog:
+            task = prog.add_task("Thinking...", total=None)
+            response_content = ""
+            for chunk in stream:
+                chunk = chunk["choices"][0]["delta"].get("content", "")
+                response_content += chunk
+                if SHOW_THINKS:
+                    prog.update(task, description=response_content, end = '', flush = True)
+                if chunk == '</think>':
+                    is_think_generated = True
+                    break
+        tmp = True
+        dont_show = False
+        for chunk in stream:     
+            chunk = chunk["choices"][0]["delta"].get("content", "")
+            response_content += chunk
+            if (is_think_generated and (chunk == 'shell' or chunk == 'search')) or dont_show:
+                dont_show = True
+                continue
+            if tmp:
+                if chunk == '\n\n': 
+                    continue
+                tmp = False
+                state['logger'].print_text(' ➜ ', color = 'yellow')
+            state['logger'].print_text(chunk, color='white') 
+        print('\n')
+        state['messages'].append({'role':'assistant', 'content': response_content})
+        return state
+    @staticmethod
+    def build_model():
+        ''' A function to define the LM '''
+        model_path = hf_hub_download(repo_id=REPO_ID, filename=GENERATION_MODEL, local_dir="./model")
+        return Llama(
+            model_path=model_path,
+            n_ctx=4096,                    
+            n_gpu_layers=10,               
+            chat_format='qwen',
+            verbose=False,
+        )

linux_assistant-0.1.0/src/linux_assistant/runtime/checks.py

@@ -0,0 +1,8 @@
+def require_llama():
+    try:
+        import llama_cpp
+    except ImportError:
+        raise RuntimeError(
+            "llama-cpp-python not installed.\n"
+            "Run: linux-assistant setup"
+        )

linux_assistant-0.1.0/src/linux_assistant/setup.py

@@ -0,0 +1,67 @@
+import platform
+import subprocess
+import sys
+
+
+def detect_cuda():
+    try:
+        result = subprocess.run(
+            ["nvidia-smi"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True
+        )
+        return result.returncode == 0
+    except FileNotFoundError:
+        return False
+
+
+def install_llama_cpp(cuda=False):
+    if cuda:
+        print("Installing CUDA version of llama-cpp-python...")
+        subprocess.check_call([
+            sys.executable,
+            "-m",
+            "pip",
+            "install",
+            "llama-cpp-python",
+            "--extra-index-url",
+            "https://abetlen.github.io/llama-cpp-python/whl/cu124"
+        ])
+    else:
+        print("Installing CPU version of llama-cpp-python...")
+        subprocess.check_call([
+            sys.executable,
+            "-m",
+            "pip",
+            "install",
+            "llama-cpp-python"
+        ])
+
+
+def setup_cmd():
+    print("Linux Assistant Setup\n")
+
+    system = platform.system()
+    print(f"Detected OS: {system}")
+
+    cuda = detect_cuda()
+    print(f"NVIDIA GPU detected: {cuda}")
+
+    choice = None
+
+    if cuda:
+        print("\nSelect backend:")
+        print("1) CUDA (recommended)")
+        print("2) CPU only")
+
+        choice = input("> ").strip()
+
+        use_cuda = (choice == "1")
+    else:
+        print("No GPU detected → using CPU")
+        use_cuda = False
+
+    install_llama_cpp(cuda=use_cuda)
+
+    print("\nSetup complete ✔")

linux_assistant-0.1.0/src/linux_assistant/utils/console_utils.py

@@ -0,0 +1,27 @@
+from pyfiglet import Figlet
+from rich.console import Console
+from rich.markdown import Markdown
+from prompt_toolkit.styles import Style
+import questionary
+
+class console_utils:
+    def __init__(self):
+        self.console = Console()
+        self.banner = Figlet(font="slant").renderText("Linux Assistant")
+        self.intro_md = Markdown("Welcome! Enjoy your linux more.")
+        self.custom_style = Style.from_dict({
+            'question': 'magenta',
+            'answer': 'gray',
+            'pointer': 'yellow'})
+    def release_banner(self):
+        self.console.print(self.banner, style="cyan")
+        self.console.print(self.intro_md)
+    
+    def get_user_input(self):
+        cmd = questionary.text("➜",style=self.custom_style,qmark="").ask()
+        if cmd == None:
+            raise SystemExit
+        return cmd  
+    
+    def print_text(self, text, color, end = ''):
+        self.console.print(f"[{color}]{text}", end=end)

linux_assistant-0.1.0/src/linux_assistant/utils/dicts.py

@@ -0,0 +1,13 @@
+from typing import TypedDict,  Sequence
+from linux_assistant.utils.console_utils import console_utils
+from langchain_core.messages import BaseMessage    
+
+class AgentState(TypedDict):
+    messages: Sequence[dict]
+    logger: console_utils
+    search_query: str
+    code: str 
+    search_query: str
+    stdout: str
+    stderr: str
+    exit_code: int

linux_assistant-0.1.0/src/linux_assistant/utils/subprocess.py

@@ -0,0 +1,81 @@
+import subprocess
+import tempfile
+import io, os
+import threading
+
+class processor:
+    def __init__(self, show_output=False):
+        self.output = {'stderr':None, "stdout":None, "returncode":None}
+        self.show_output = show_output
+
+    def subprocess(self, code):
+        '''Runing subprocess'''
+        path = self.create_tmp_file(code)
+        returncode, stdout, stderr = self.run_interactive_subprocess(['bash', path])
+        os.remove(path)
+        self.output = {'stderr':stderr, "stdout":stdout, "returncode":returncode}
+        
+    def run_interactive_subprocess(self, command):
+        '''To run shell intractivly'''
+        stdout_buffer = io.StringIO()
+        stderr_buffer = io.StringIO()
+        
+        try:
+            process = subprocess.Popen(
+                command,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1
+            )
+            
+            stdout_thread = threading.Thread(
+                target=self.read_output, 
+                args=(process.stdout, "Subprocess output", stdout_buffer, self.show_output)
+            )
+            stderr_thread = threading.Thread(
+                target=self.read_output, 
+                args=(process.stderr, "Subprocess error", stderr_buffer, self.show_output)
+            )
+            
+            stdout_thread.daemon = True
+            stderr_thread.daemon = True
+            
+            stdout_thread.start()
+            stderr_thread.start()
+            
+            process.stdin.close()  
+            
+            returncode = process.wait()
+            
+            stdout_thread.join(timeout=1)
+            stderr_thread.join(timeout=1)
+            
+            stdout_content = stdout_buffer.getvalue()
+            stderr_content = stderr_buffer.getvalue()
+
+            return returncode, stdout_content, stderr_content
+            
+        except Exception as e:
+            print(f"Error: {e}")
+            return -1, "", str(e)
+        
+    @staticmethod
+    def create_tmp_file(code):
+        '''Creating a temp file'''
+        with tempfile.NamedTemporaryFile("w", suffix=".sh", delete=False) as tf:
+            tf.write(code)
+            path = tf.name
+        return path
+        
+    @staticmethod
+    def read_output(stream, prefix, buffer, show_output=True):
+        '''To gather outputs'''
+        while True:
+            line = stream.readline()
+            if not line:
+                break
+            if show_output:
+                print(f"{prefix}: {line.strip()}")
+            buffer.write(line)

linux_assistant-0.1.0/src/linux_assistant.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: linux-assistant
+Version: 0.1.0
+Summary: An AI-powered natural-language Linux assistant
+Author-email: Ali Fathi Jahromi <alifathijahromi@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Ali Fathi Jahromi
+        
+        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.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain
+Requires-Dist: click
+Dynamic: license-file
+
+# linux‑Assistant
+
+An AI-powered assistant that lets you interact with your Linux system using natural language. Ask it to list files, install packages, inspect processes, or perform any shell task—behind the scenes it translates your request into safe bash commands and runs them for you.
+
+---
+
+## Features
+
+- **Natural‑language interface**: Describe what you want to do—no need to remember exact commands.  
+- **Interactive shell execution**: The assistant decides when to run commands, executes them in a temporary script, and returns the output.  
+- **Continuous conversation**: You can follow up on results, ask for clarifications, or chain multiple operations in one session.  
+- **Customizable**: Swap in any Ollama‑compatible model and adjust prompts to suit your workflow.
+
+---
+
+## Prerequisites
+
+- **Linux** with Bash installed  
+- **Python 3.12+**  
+- [Ollama CLI & daemon](https://ollama.com/) with at least one local model (e.g. `qwen3:8b`)  
+- (Optional but recommended) A dedicated Python virtual environment
+
+---
+
+## Installation
+
+1. **Clone the repository**  
+   ```bash
+   git clone https://github.com/alifthi/linux-Assistant.git
+   cd linux-Assistant
+   ```
+
+2. **Set up a virtual environment**  
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+3. **Install ollama and pull model**
+   ```bash 
+   curl -fsSL https://ollama.com/install.sh | sh
+   ollama pull qwen3:8B  # Or any other models you want to use
+   ```
+4. **Install dependencies**  
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+---
+
+## Configuration
+
+Open **`models/config.py`** and adjust:
+
+- `MODEL_NAME` – the Ollama model you wish to use (e.g. `"qwen3:8b"`).  
+- `SYSTEM_PROMPT` – how the assistant should frame its replies and decide when to run shell commands.
+
+---
+
+## Usage
+
+Run the assistant and start chatting:
+
+```bash
+cd src
+python -m linux_assistant
+```
+
+- Ask anything you would normally do in the terminal.
+
+- Continue the conversation naturally or type `exit` to quit.
+---
+Run the assistant using Docker
+
+```bash
+docker run --name <Container's name> \
+   -v linux_assistant_volume:/app/data \
+   -v "$(pwd)":/app/workspace alifthi/linux-assistant 
+
+```
+
+---
+
+## Contributing
+
+Contributions and feedback are welcome! Feel free to:
+
+- Open issues for bugs or feature requests  
+- Submit pull requests to improve prompts, handling, or documentation  
+- Suggest new use cases or integrations
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for details.  

linux_assistant-0.1.0/src/linux_assistant.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+src/linux_assistant/__init__.py
+src/linux_assistant/__main__.py
+src/linux_assistant/app.py
+src/linux_assistant/setup.py
+src/linux_assistant.egg-info/PKG-INFO
+src/linux_assistant.egg-info/SOURCES.txt
+src/linux_assistant.egg-info/dependency_links.txt
+src/linux_assistant.egg-info/entry_points.txt
+src/linux_assistant.egg-info/requires.txt
+src/linux_assistant.egg-info/top_level.txt
+src/linux_assistant/graph/config.py
+src/linux_assistant/graph/graph.py
+src/linux_assistant/graph/nodes.py
+src/linux_assistant/models/config.py
+src/linux_assistant/models/model_nodes.py
+src/linux_assistant/runtime/checks.py
+src/linux_assistant/utils/console_utils.py
+src/linux_assistant/utils/dicts.py
+src/linux_assistant/utils/subprocess.py

linux_assistant-0.1.0/src/linux_assistant.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

linux_assistant-0.1.0/src/linux_assistant.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+linux-assistant = linux_assistant.__main__:main

linux_assistant-0.1.0/src/linux_assistant.egg-info/requires.txt

@@ -0,0 +1,2 @@
+langchain
+click

linux_assistant-0.1.0/src/linux_assistant.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+linux_assistant
+model