avins 0.1.0__tar.gz

avins-0.1.0/LICENSE

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

avins-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: avins
+Version: 0.1.0
+Summary: An advanced, proactive AI desktop assistant with terminal and GUI automation capabilities.
+Author: Avinash
+License: MIT
+Project-URL: Homepage, https://github.com/avin-1/avins
+Project-URL: Bug Tracker, https://github.com/avin-1/avins/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: groq
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic
+Requires-Dist: pyautogui
+Dynamic: license-file
+
+# Avins
+
+An advanced, proactive AI desktop assistant equipped with terminal and GUI automation capabilities.
+
+## Features
+- **Cross-Platform**: Supports Windows, macOS, and Linux (including Wayland and X11).
+- **GUI Automation**: Abstracted GUI controls for typing, clicking, scrolling, and hotkeys.
+- **Terminal Execution**: Safely execute shell commands directly on your system (with user confirmation).
+- **Dynamic Tool Creation**: The agent can write its own Python tools and add them dynamically.
+
+## Installation
+
+```bash
+pip install avins
+```
+
+## Usage
+
+Run the assistant via the command line:
+
+```bash
+avins
+```
+
+This will start an interactive ReAct (Reason + Act) loop where you can instruct the assistant to perform various operations on your desktop.

avins-0.1.0/README.md

@@ -0,0 +1,25 @@
+# Avins
+
+An advanced, proactive AI desktop assistant equipped with terminal and GUI automation capabilities.
+
+## Features
+- **Cross-Platform**: Supports Windows, macOS, and Linux (including Wayland and X11).
+- **GUI Automation**: Abstracted GUI controls for typing, clicking, scrolling, and hotkeys.
+- **Terminal Execution**: Safely execute shell commands directly on your system (with user confirmation).
+- **Dynamic Tool Creation**: The agent can write its own Python tools and add them dynamically.
+
+## Installation
+
+```bash
+pip install avins
+```
+
+## Usage
+
+Run the assistant via the command line:
+
+```bash
+avins
+```
+
+This will start an interactive ReAct (Reason + Act) loop where you can instruct the assistant to perform various operations on your desktop.

avins-0.1.0/agents/mail.py

@@ -0,0 +1,22 @@
+import os
+from groq import Groq
+from dotenv import load_dotenv
+load_dotenv()
+
+client=Groq()
+
+chat_completion=client.chat.completions.create(
+    messages=[
+        {
+            "role":"system",
+            "content": "You are a helpful assistant and at the end of each line append Avinash"
+        },
+        {
+            "role": "user",
+            "content": "what is the capital of india"
+        }
+    ],
+    model="openai/gpt-oss-120b"
+)
+
+print(chat_completion.choices[0].message.content)

avins-0.1.0/agents/tool_maker.py

@@ -0,0 +1,195 @@
+"""
+Tool-creation agent.
+
+Given a task, asks an LLM whether a new tool is needed. If so, it
+creates the tool (installing dependencies via use_terminal first),
+persists it into tools.py / tools_defination.py, and makes it callable
+immediately. If not, it just returns the model's answer.
+"""
+
+import asyncio
+import importlib
+import json
+from pathlib import Path
+from pprint import pformat
+import multiprocessing
+from config.asyncModel import async_client
+from tools.tools_defination import tool
+from tools.tools import use_terminal
+import tools.tools as tools_module
+from logger.logs import logging
+import threading
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+TOOLS_FILE = PROJECT_ROOT / "tools" / "tools.py"
+TOOLS_DEFINITION_FILE = PROJECT_ROOT / "tools" / "tools_defination.py"
+
+MAX_TURNS = 6  
+
+SYSTEM_PROMPT = """Your job is to make a tool for a master agent.
+
+The tool is a Python function, if needed, that uses lightweight and
+safe libraries. Any library you use must first be installed with the
+use_terminal tool, and the code you return must contain the imports
+for those libraries.
+
+No mistakes. This is a high stake task.
+
+Always respond with ONLY a JSON object, nothing else (no prose, no
+Markdown fences), in exactly this shape:
+
+{
+    "tool": null,
+    "defination": null,
+    "result": null
+}
+
+- If the task requires a NEW tool: set "tool" to the full Python
+  source of the function, and "defination" to its OpenAI-style tool
+  definition (with "type", "function.name", "function.description",
+  "function.parameters"). Leave "result" null.
+- If the task does NOT require a new tool: leave "tool" and
+  "defination" null, and put your final answer in "result".
+
+You may also make a tool call yourself (e.g. use_terminal to install
+a dependency) instead of returning JSON, when you need to act before
+you can answer.
+"""
+
+tool_call_history = []
+
+
+def build_history_note() -> str:
+    if not tool_call_history:
+        return "No tools have been called yet."
+    return (
+        "Here is the tool call history so far:\n"
+        f"{tool_call_history}\n\n"
+        "If the requested operation has already been executed "
+        "successfully, do not run it again."
+    )
+
+
+async def chat_completion(msg: str):
+    return await async_client.chat.completions.create(
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": msg},
+            {"role": "system", "content": build_history_note()},
+        ],
+        tools=tool,
+        model="openai/gpt-oss-120b",
+    )
+
+
+def save_tool_definition(tool_list):
+    """Persist tool definitions into tools_defination.py."""
+    content = f"tool = {pformat(tool_list, indent=4)}\n\n__all__ = [\"tool\"]\n"
+    TOOLS_DEFINITION_FILE.write_text(content)
+
+
+def execute_tool(name: str, arguments: str) -> str:
+    """Execute a tool by name with JSON arguments."""
+    try:
+        args = json.loads(arguments) if arguments else {}
+    except json.JSONDecodeError as e:
+        return f"Error: could not parse arguments for '{name}': {e}"
+
+    if name == "use_terminal":
+        command = args.get("text", "")
+        res = use_terminal(command)
+        if res.returncode == 0:
+            output = res.stdout or "(Command executed successfully with no output)"
+            return f"Stdout:\n{output}"
+        return f"Stderr:\n{res.stderr}"
+
+    importlib.reload(tools_module)
+    func = getattr(tools_module, name, None)
+    if func is None:
+        return f"Error: Tool '{name}' is not supported."
+
+    try:
+        return str(func(**args))
+    except Exception as e:
+        return f"Error while executing '{name}': {e}"
+
+
+def create_tool(task: str) -> str:
+    """
+    One turn with the model. Returns "Tool Called", "Success", or "Error".
+    """
+    try:
+        chat = asyncio.run(chat_completion(task))
+    except Exception as e:
+        print("API call failed:", e)
+        return "Error"
+
+    message = chat.choices[0].message
+    content = message.content
+
+    if message.tool_calls:
+        for call in message.tool_calls:
+            output = execute_tool(call.function.name, call.function.arguments)
+            tool_call_history.append({call.function.name: output})
+        return "Tool Called"
+
+    if content is None:
+        print("No response received from model.")
+        return "Error"
+
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        print("Result:", content)
+        return "Success"
+
+    tool_code = parsed.get("tool")
+    definition = parsed.get("defination")
+    result_text = parsed.get("result")
+
+    if tool_code and definition:
+        with open(TOOLS_FILE, "a") as f:
+            f.write("\n\n")
+            f.write(tool_code)
+
+        tool.append(definition)
+        save_tool_definition(tool)
+
+        print("Tool created successfully!")
+        return "Success"
+
+    if result_text:
+        print("Result:", result_text)
+        return "Success"
+
+    print("Model returned neither a tool nor a result.")
+    return "Error"
+
+
+def wrapper(task: str) -> None:
+    res = None
+    for _ in range(MAX_TURNS):
+        res = create_tool(task)
+        if res != "Tool Called":
+            print("Success")
+            break
+    else:
+        print(f"Stopped after {MAX_TURNS} turns without a final answer.")
+        return
+
+    if res == "Success":
+        print("Task completed successfully.")
+    else:
+        print("Task execution failed.")
+
+
+def create(user_task: str):
+    p = threading.Thread(target=wrapper, args=(user_task,))
+    p.start()
+    p.join(timeout=120) 
+    if p.is_alive():
+        p.terminate()
+
+if __name__ == "__main__":
+    user_task = input("Enter a task: ")
+    create(user_task)

avins-0.1.0/avins.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: avins
+Version: 0.1.0
+Summary: An advanced, proactive AI desktop assistant with terminal and GUI automation capabilities.
+Author: Avinash
+License: MIT
+Project-URL: Homepage, https://github.com/avin-1/avins
+Project-URL: Bug Tracker, https://github.com/avin-1/avins/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: groq
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic
+Requires-Dist: pyautogui
+Dynamic: license-file
+
+# Avins
+
+An advanced, proactive AI desktop assistant equipped with terminal and GUI automation capabilities.
+
+## Features
+- **Cross-Platform**: Supports Windows, macOS, and Linux (including Wayland and X11).
+- **GUI Automation**: Abstracted GUI controls for typing, clicking, scrolling, and hotkeys.
+- **Terminal Execution**: Safely execute shell commands directly on your system (with user confirmation).
+- **Dynamic Tool Creation**: The agent can write its own Python tools and add them dynamically.
+
+## Installation
+
+```bash
+pip install avins
+```
+
+## Usage
+
+Run the assistant via the command line:
+
+```bash
+avins
+```
+
+This will start an interactive ReAct (Reason + Act) loop where you can instruct the assistant to perform various operations on your desktop.

avins-0.1.0/avins.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+agents/mail.py
+agents/tool_maker.py
+avins.egg-info/PKG-INFO
+avins.egg-info/SOURCES.txt
+avins.egg-info/dependency_links.txt
+avins.egg-info/entry_points.txt
+avins.egg-info/requires.txt
+avins.egg-info/top_level.txt
+config/api_setup.py
+config/asyncModel.py
+config/model.py
+core/main.py
+model/tool.py
+model/user.py
+tools/ast_builder.py
+tools/tools.py
+tools/tools_defination.py

avins-0.1.0/avins.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

avins-0.1.0/avins.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+avins = core.main:cli

avins-0.1.0/avins.egg-info/requires.txt

@@ -0,0 +1,4 @@
+groq
+python-dotenv
+pydantic
+pyautogui

avins-0.1.0/avins.egg-info/top_level.txt

@@ -0,0 +1,5 @@
+agents
+config
+core
+model
+tools

avins-0.1.0/config/api_setup.py

@@ -0,0 +1,62 @@
+"""
+API Key Setup — Hardcoded safety net for GROQ_API_KEY.
+
+This module is imported at the very top of every client module
+(config/asyncModel.py, config/model.py).  It guarantees that by the
+time a Groq client is instantiated, GROQ_API_KEY is present both in
+os.environ and persisted in the project's .env file.
+"""
+
+import os
+from pathlib import Path
+from dotenv import load_dotenv, set_key
+
+# Always resolve .env relative to this file's project root
+ENV_FILE = Path(__file__).resolve().parent.parent / ".env"
+
+
+def ensure_api_key() -> str:
+    """
+    Ensure GROQ_API_KEY exists and is non-empty.
+
+    Priority order:
+      1. Already set in os.environ (e.g. system environment)
+      2. Found in .env file
+      3. Prompted from the user → saved to .env for future runs
+
+    Returns the validated API key string.
+    """
+    # Load .env into os.environ (safe even if file doesn't exist)
+    load_dotenv(ENV_FILE, override=False)
+
+    key = os.environ.get("GROQ_API_KEY", "").strip()
+
+    if key:
+        return key  # Already available — nothing to do
+
+    # ── Key is missing: inform and prompt ─────────────────────────────
+    print()
+    print("=" * 58)
+    print("  ⚠  GROQ API Key not found.")
+    print("  Get yours free at: https://console.groq.com/keys")
+    print("=" * 58)
+
+    while not key:
+        key = input("  Enter your GROQ_API_KEY: ").strip()
+        if not key:
+            print("  Key cannot be empty. Please try again.")
+
+    # ── Persist to .env ────────────────────────────────────────────────
+    ENV_FILE.touch(exist_ok=True)          # create .env if it doesn't exist
+    set_key(str(ENV_FILE), "GROQ_API_KEY", key)
+    os.environ["GROQ_API_KEY"] = key       # make available in current process
+
+    print()
+    print("  ✔  API key saved to .env — you won't be asked again.")
+    print("=" * 58)
+    print()
+
+    return key
+
+
+__all__ = ["ensure_api_key"]

avins-0.1.0/config/asyncModel.py

@@ -0,0 +1,13 @@
+from groq import AsyncGroq
+from dotenv import load_dotenv
+from config.api_setup import ensure_api_key
+
+# Guarantee key exists (prompts user and saves to .env if missing)
+ensure_api_key()
+
+load_dotenv()
+
+async_client = AsyncGroq()
+
+
+__all__ = ["async_client"]

avins-0.1.0/config/model.py

@@ -0,0 +1,12 @@
+from groq import Groq
+from dotenv import load_dotenv
+from config.api_setup import ensure_api_key
+
+# Guarantee key exists (prompts user and saves to .env if missing)
+ensure_api_key()
+
+load_dotenv()
+
+client = Groq()
+
+__all__ = ["client"]

avins-0.1.0/core/main.py

@@ -0,0 +1,218 @@
+import asyncio
+import json
+import platform
+from typing import Any, Dict, List, Optional
+
+from config.asyncModel import async_client
+from model.tool import Tool
+from model.user import User
+from tools.tools_defination import tool as tools_definition
+from tools.tools import use_terminal, gui_control
+
+user = User()
+tool_log_history: dict[str, list[str]] = {}
+
+_PLATFORM = platform.system()   
+
+_OS_GUIDELINES: dict[str, str] = {
+    "Windows": """\
+### WINDOWS DESKTOP AUTOMATION GUIDELINES:
+- Use PowerShell or cmd.exe commands for terminal actions.
+  e.g., `Start-Process chrome "https://www.google.com/search?q=<query>"`
+       or `start chrome "https://..."` (cmd style)
+- For file paths always use Windows-style separators: C:\\Users\\...
+- To get screen dimensions: `powershell "[System.Windows.Forms.Screen]::PrimaryScreen.Bounds"`
+  or simply call gui_control with action='move' to a known position.
+- For GUI control: pyautogui is used automatically — no extra tools needed.
+""",
+    "Darwin": """\
+### macOS DESKTOP AUTOMATION GUIDELINES:
+- Use bash/zsh commands for terminal actions.
+  e.g., `open -a "Google Chrome" "https://www.google.com/search?q=<query>"`
+- To get screen dimensions: `system_profiler SPDisplaysDataType | grep Resolution`
+- For GUI control: pyautogui is used automatically.
+""",
+    "Linux": """\
+### LINUX DESKTOP AUTOMATION GUIDELINES:
+- Use bash commands for terminal actions.
+  e.g., `google-chrome "https://www.google.com/search?q=<query>"`
+  or `firefox "https://..."`
+- To get screen geometry: `xdpyinfo | grep dimensions` or `xdotool getdisplaygeometry`
+  Once you have dimensions (e.g. 1920x1080), compute center (960, 540) and
+  call `gui_control(action='move', x=960, y=540)` immediately.
+- On Wayland: ydotool is used automatically; on X11 pyautogui is used.
+""",
+}
+
+_OS_SECTION = _OS_GUIDELINES.get(_PLATFORM, _OS_GUIDELINES["Linux"])
+
+SYSTEM_PROMPT = f"""\
+You are an advanced, proactive AI desktop assistant equipped with terminal and GUI automation capabilities.
+You are running on: {_PLATFORM}
+
+### OPERATIONAL FRAMEWORK: CHAIN OF THOUGHT & REACT
+For every user instruction, you MUST reason step-by-step before acting:
+1. **THINK (Reasoning & Plan)**: Analyze the user's intent. Break down the task into concrete, atomic steps.
+2. **ACT (Tool Execution)**: Call the appropriate tool(s) for the next immediate step.
+3. **OBSERVE & REFLECT**: Review the tool execution output. Did the step succeed? What information was obtained?
+4. **REPEAT or FINISH**: Continue executing the remaining steps until the user's request is 100% fulfilled. Only provide your final message once all actions are physically completed.
+
+{_OS_SECTION}
+### GENERAL GUIDELINES:
+- **Mouse & Screen Interaction**:
+  - Once screen dimensions are obtained, immediately compute center coordinates and move there.
+- **Do NOT hallucinate completion**:
+  - Never state an action has been completed unless the corresponding tool call has been executed and confirmed.
+- **Output Format**:
+  - Keep final responses direct, concise, and informative in plain text (no unnecessary markdown).
+"""
+
+
+def execute_tool(name: str, arguments: str) -> str:
+    """Safely executes a tool by name with JSON arguments and returns string result."""
+    try:
+        args: Dict[str, Any] = json.loads(arguments) if arguments else {}
+    except json.JSONDecodeError as e:
+        return f"Error: Failed to parse tool arguments for '{name}': {e}"
+
+    if name == "use_terminal":
+        command = args.get("text", "")
+        if not command:
+            return "Error: No command provided to use_terminal."
+
+        res = use_terminal(command)
+        terminal_tool = Tool(name="use_terminal")
+
+        if res.returncode == 0:
+            output = res.stdout.strip() if res.stdout else "(Command completed with no stdout output)"
+            terminal_tool.message.append(f"Command '{command}' succeeded: {output}")
+            result_str = f"Stdout:\n{output}"
+        else:
+            err = (res.stderr or res.stdout or "Command failed with non-zero exit code").strip()
+            terminal_tool.message.append(f"Command '{command}' failed: {err} (Exit code {res.returncode})")
+            result_str = f"Exit Code {res.returncode}\nStderr/Output:\n{err}"
+
+        tool_log_history.setdefault(name, []).extend(terminal_tool.message)
+        return result_str
+
+    if name == "gui_control":
+        gui_tool = Tool(name="gui_control")
+        try:
+            result_str = gui_control(
+                action=args.get("action"),
+                x=args.get("x"),
+                y=args.get("y"),
+                duration=args.get("duration", 0.0),
+                clicks=args.get("clicks", 1),
+                interval=args.get("interval", 0.0),
+                button=args.get("button", "left"),
+                text=args.get("text"),
+                keys=args.get("keys"),
+                scroll=args.get("scroll"),
+            )
+        except Exception as e:
+            result_str = f"Error executing gui_control: {e}"
+
+        gui_tool.message.append(f"gui_control({args}) -> {result_str}")
+        tool_log_history.setdefault(name, []).extend(gui_tool.message)
+        return result_str
+
+    return f"Error: Tool '{name}' is not supported."
+
+
+async def loop(message: str, max_iterations: int = 10):
+    """Executes the agentic Chain-of-Thought loop with persistent multi-turn memory."""
+    # Build context: system prompt + past conversation turns + current user message
+    messages: List[Dict[str, Any]] = [{"role": "system", "content": SYSTEM_PROMPT}]
+    messages.extend(user.last_messages)
+    messages.append({"role": "user", "content": message})
+
+    for iteration in range(1, max_iterations + 1):
+        try:
+            chat_completion = await async_client.chat.completions.create(
+                messages=messages,
+                tools=tools_definition,
+                model="openai/gpt-oss-120b",
+            )
+        except Exception as e:
+            print(f"\n[Model Error]: {e}")
+            break
+
+        msg = chat_completion.choices[0].message
+        content = msg.content or ""
+
+        if content.strip():
+            print(f"\n[Thought / Plan]:\n{content.strip()}\n")
+
+        # Handle tool execution
+        if msg.tool_calls:
+            assistant_msg: Dict[str, Any] = {
+                "role": "assistant",
+                "content": msg.content,
+                "tool_calls": [
+                    {
+                        "id": t.id,
+                        "type": "function",
+                        "function": {"name": t.function.name, "arguments": t.function.arguments},
+                    }
+                    for t in msg.tool_calls
+                ],
+            }
+            messages.append(assistant_msg)
+
+            for t in msg.tool_calls:
+                function_name = t.function.name
+                args_str = t.function.arguments
+                print(f"[Action]: Calling tool '{function_name}' with args: {args_str}")
+
+                tool_output = execute_tool(function_name, args_str)
+                print(f"[Observation]:\n{tool_output}\n")
+
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": t.id,
+                    "name": function_name,
+                    "content": tool_output,
+                })
+        else:
+            # final completion reached without further tool calls
+            print(f"[Assistant]:\n{content.strip()}\n")
+            
+            user.last_messages = messages[1:]
+            user.last_messages.append({"role": "assistant", "content": content})
+            return
+
+    # if max iterations reached, persist current state
+    user.last_messages = messages[1:]
+    print("\n[Notice]: Maximum task iterations reached.")
+
+
+async def main():
+    print("=" * 60)
+    print(f" Desktop Agent initialized  [{_PLATFORM}]")
+    print("  Chain-of-Thought + ReAct loop enabled")
+    print("  Type 'exit' or 'quit' to close.")
+    print("=" * 60 + "\n")
+
+    while True:
+        try:
+            msg = input("Enter Your Message: ").strip()
+            if not msg:
+                continue
+            if msg.lower() in ("exit", "quit"):
+                print("Goodbye!")
+                break
+            user.message = msg
+            await loop(user.message)
+        except (KeyboardInterrupt, EOFError):
+            print("\nExiting...")
+            break
+
+
+def cli():
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    cli()
+

avins-0.1.0/model/tool.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, Field
+
+
+class Tool(BaseModel):
+    name: str = ""
+    message: list[str] = Field(default_factory=list)
+
+
+__all__ = ["Tool"]

avins-0.1.0/model/user.py

@@ -0,0 +1,11 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class User(BaseModel):
+    message: Optional[str] = None
+    last_messages: list[dict] = Field(default_factory=list)
+
+
+__all__ = ["User"]
+

avins-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "avins"
+version = "0.1.0"
+description = "An advanced, proactive AI desktop assistant with terminal and GUI automation capabilities."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+  {name = "Avinash"},
+]
+dependencies = [
+    "groq",
+    "python-dotenv",
+    "pydantic",
+    "pyautogui"
+]
+
+[project.scripts]
+avins = "core.main:cli"
+
+[project.urls]
+"Homepage" = "https://github.com/avin-1/avins"
+"Bug Tracker" = "https://github.com/avin-1/avins/issues"
+
+[tool.setuptools]
+packages = ["core", "model", "agents", "config", "tools"]

avins-0.1.0/setup.cfg

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

avins-0.1.0/tools/tools.py

@@ -0,0 +1,293 @@
+"""
+tools.py — OS-independent tool implementations.
+
+Supports:
+  - Windows  → pyautogui for all GUI actions
+  - Linux X11 → pyautogui
+  - Linux Wayland → ydotool (with GNOME xdotool fallback) → pyautogui
+  - macOS → pyautogui
+"""
+
+import os
+import platform
+import shutil
+import subprocess
+import time
+
+import pyautogui
+
+pyautogui.FAILSAFE = False
+
+# ── Detect current OS once at import time ─────────────────────────────────────
+PLATFORM = platform.system()   # 'Windows' | 'Linux' | 'Darwin'
+
+# On Linux, grant the current user access to the X display (no-op on Wayland/Windows)
+if PLATFORM == "Linux":
+    import getpass
+    _username = getpass.getuser()
+    subprocess.run(
+        ["xhost", f"+SI:localuser:{_username}"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Terminal tool
+# ══════════════════════════════════════════════════════════════════════════════
+
+def use_terminal(text: str) -> subprocess.CompletedProcess:
+    """Executes a terminal command after asking for user confirmation.
+
+    Works on Windows (cmd/PowerShell), Linux, and macOS.
+    """
+    des = input(
+        f"Do you want to execute this command?\n"
+        f"{text}\n"
+        f"Enter 1 for Yes, 0 for No: "
+    )
+
+    try:
+        des = int(des)
+    except ValueError:
+        print("Invalid input. Please enter 1 or 0.")
+        return subprocess.CompletedProcess(
+            args=text, returncode=1, stdout="", stderr="Invalid user input"
+        )
+
+    if des == 1:
+        print("Running Process....")
+        res = subprocess.run(
+            text,
+            shell=True,
+            capture_output=True,
+            text=True,
+        )
+        print("Command Executed Output is: ", res.stdout, "Exiting...")
+        return res
+    else:
+        print("Command Execution cancelled")
+        return subprocess.CompletedProcess(
+            args=text, returncode=1, stdout="", stderr="Command execution cancelled by user"
+        )
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# Linux Wayland helpers  (all guarded — never called on Windows/macOS)
+# ══════════════════════════════════════════════════════════════════════════════
+
+def _is_wayland() -> bool:
+    """True only on Linux Wayland sessions."""
+    if PLATFORM != "Linux":
+        return False
+    return (
+        os.environ.get("XDG_SESSION_TYPE", "").lower() == "wayland"
+        or bool(os.environ.get("WAYLAND_DISPLAY"))
+    )
+
+
+def _is_gnome() -> bool:
+    """True only on GNOME desktops (Linux)."""
+    if PLATFORM != "Linux":
+        return False
+    return "gnome" in os.environ.get("XDG_CURRENT_DESKTOP", "").lower()
+
+
+def _run_ydotool(cmd_args: list[str]) -> subprocess.CompletedProcess:
+    """Run an ydotool command, injecting the socket path if needed."""
+    env = os.environ.copy()
+    if (
+        "/tmp/.ydotool_socket" not in env.get("YDOTOOL_SOCKET", "")
+        and os.path.exists("/tmp/.ydotool_socket")
+    ):
+        env["YDOTOOL_SOCKET"] = "/tmp/.ydotool_socket"
+    return subprocess.run(["ydotool"] + cmd_args, capture_output=True, text=True, env=env)
+
+
+def _ydotool_working() -> bool:
+    """True if the ydotool daemon is running and uinput is accessible."""
+    res = _run_ydotool(["key", "--delay", "0", "a:1", "a:0"])
+    return res.returncode == 0
+
+
+def _run_gnome_hotkey(keys: list[str]) -> bool:
+    """Send a hotkey via xdotool to the XWayland display.
+
+    Works on GNOME Wayland — the compositor intercepts system shortcuts
+    sent to the XWayland display.  Returns True on success.
+    """
+    if shutil.which("xdotool") is None:
+        return False
+
+    _xdotool_key_map = {
+        "ctrl": "ctrl", "alt": "alt", "shift": "shift",
+        "super": "super", "win": "super",
+        "tab": "Tab", "return": "Return", "enter": "Return",
+        "escape": "Escape", "esc": "Escape", "space": "space",
+        "left": "Left", "right": "Right", "up": "Up", "down": "Down",
+    }
+    combo = "+".join(_xdotool_key_map.get(k.lower(), k) for k in keys)
+
+    env = os.environ.copy()
+    if not env.get("DISPLAY"):
+        env["DISPLAY"] = ":0"
+
+    res = subprocess.run(
+        ["xdotool", "key", "--clearmodifiers", combo],
+        capture_output=True, text=True, env=env, timeout=5,
+    )
+    return res.returncode == 0
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# GUI control — unified cross-platform entry point
+# ══════════════════════════════════════════════════════════════════════════════
+
+def gui_control(
+    action: str,
+    x: int = None,
+    y: int = None,
+    duration: float = 0.0,
+    clicks: int = 1,
+    interval: float = 0.0,
+    button: str = "left",
+    text: str = None,
+    keys: list = None,
+    scroll: int = None,
+) -> str:
+    """Perform GUI actions using the best available backend for the current OS.
+
+    Backend selection:
+      • Windows / macOS    → pyautogui (always)
+      • Linux X11          → pyautogui
+      • Linux Wayland      → ydotool → GNOME xdotool → pyautogui (fallback chain)
+
+    Parameters
+    ----------
+    action : str
+        One of 'move', 'click', 'double_click', 'right_click',
+        'typewrite', 'press', 'hotkey', 'scroll'.
+    x, y : int, optional
+        Screen coordinates for mouse actions.
+    duration : float
+        Seconds taken to move the mouse (pyautogui).
+    clicks : int
+        Number of clicks (default 1).
+    interval : float
+        Seconds between clicks.
+    button : str
+        Mouse button — 'left', 'right', or 'middle'.
+    text : str, optional
+        Text to type ('typewrite') or key to press ('press').
+    keys : list[str], optional
+        Key combination for 'hotkey' (e.g. ['ctrl', 'c']).
+    scroll : int, optional
+        Scroll amount — positive = up, negative = down.
+
+    Returns
+    -------
+    str
+        'Success' or an error description.
+    """
+    # Wayland + ydotool are only relevant on Linux
+    is_wayland = _is_wayland()
+    has_ydotool = (PLATFORM == "Linux") and (shutil.which("ydotool") is not None)
+
+    try:
+        # ── move ──────────────────────────────────────────────────────
+        if action == "move":
+            if x is None or y is None:
+                return "Error: x and y must be provided for move action"
+            if is_wayland and has_ydotool:
+                res = _run_ydotool(["mousemove", "-a", str(x), str(y)])
+                if res.returncode != 0:
+                    pyautogui.moveTo(x, y, duration=duration)
+            else:
+                pyautogui.moveTo(x, y, duration=duration)
+
+        # ── click ─────────────────────────────────────────────────────
+        elif action == "click":
+            if is_wayland and has_ydotool:
+                if x is not None and y is not None:
+                    _run_ydotool(["mousemove", "-a", str(x), str(y)])
+                btn_code = "0xC0" if button == "left" else "0xC1" if button == "right" else "0xC2"
+                _run_ydotool(["click", btn_code])
+            else:
+                if x is not None and y is not None:
+                    pyautogui.click(x, y, clicks=clicks, interval=interval, button=button)
+                else:
+                    pyautogui.click(clicks=clicks, interval=interval, button=button)
+
+        # ── double_click ──────────────────────────────────────────────
+        elif action == "double_click":
+            if is_wayland and has_ydotool:
+                if x is not None and y is not None:
+                    _run_ydotool(["mousemove", "-a", str(x), str(y)])
+                _run_ydotool(["click", "0xC0"])
+                time.sleep(0.1)
+                _run_ydotool(["click", "0xC0"])
+            else:
+                if x is not None and y is not None:
+                    pyautogui.doubleClick(x, y, interval=interval, button=button)
+                else:
+                    pyautogui.doubleClick(interval=interval, button=button)
+
+        # ── right_click ───────────────────────────────────────────────
+        elif action == "right_click":
+            if is_wayland and has_ydotool:
+                if x is not None and y is not None:
+                    _run_ydotool(["mousemove", "-a", str(x), str(y)])
+                _run_ydotool(["click", "0xC1"])
+            else:
+                if x is not None and y is not None:
+                    pyautogui.rightClick(x, y, clicks=clicks, interval=interval)
+                else:
+                    pyautogui.rightClick(clicks=clicks, interval=interval)
+
+        # ── typewrite ─────────────────────────────────────────────────
+        elif action == "typewrite":
+            if text is None:
+                return "Error: text must be provided for typewrite action"
+            if is_wayland and has_ydotool:
+                _run_ydotool(["type", "--", text])
+            else:
+                pyautogui.typewrite(text, interval=interval)
+
+        # ── press ─────────────────────────────────────────────────────
+        elif action == "press":
+            if text is None:
+                return "Error: key must be provided in text parameter for press action"
+            if is_wayland and has_ydotool:
+                _run_ydotool(["key", f"{text}:1", f"{text}:0"])
+            else:
+                pyautogui.press(text)
+
+        # ── hotkey ────────────────────────────────────────────────────
+        elif action == "hotkey":
+            if not keys:
+                return "Error: keys list must be provided for hotkey action"
+            if is_wayland:
+                # Fallback chain: GNOME xdotool → ydotool daemon → pyautogui
+                if _is_gnome() and _run_gnome_hotkey(keys):
+                    pass  # handled
+                elif has_ydotool and _ydotool_working():
+                    key_args = [f"{k}:1" for k in keys] + [f"{k}:0" for k in reversed(keys)]
+                    _run_ydotool(["key"] + key_args)
+                else:
+                    pyautogui.hotkey(*keys)
+            else:
+                pyautogui.hotkey(*keys)
+
+        # ── scroll ────────────────────────────────────────────────────
+        elif action == "scroll":
+            if scroll is None:
+                return "Error: scroll amount must be provided for scroll action"
+            pyautogui.scroll(scroll, x=x, y=y)
+
+        else:
+            return f"Error: Unknown action '{action}'"
+
+        return "Success"
+
+    except Exception as e:
+        return f"Error: {e}"

avins-0.1.0/tools/tools_defination.py

@@ -0,0 +1,116 @@
+tool = [   {   'function': {   'description': 'Executes a terminal command in the '
+                                       'current working directory.',
+                        'name': 'use_terminal',
+                        'parameters': {   'properties': {   'text': {   'type': 'string'}},
+                                          'required': ['text'],
+                                          'type': 'object'}},
+        'type': 'function'},
+    {   'function': {   'description': 'Perform GUI actions such as moving the '
+                                       'mouse, clicking, typing, pressing '
+                                       'keys, hotkeys, and scrolling using '
+                                       'pyautogui.',
+                        'name': 'gui_control',
+                        'parameters': {   'properties': {   'action': {   'description': 'The '
+                                                                                         'GUI '
+                                                                                         'action '
+                                                                                         'to '
+                                                                                         'perform '
+                                                                                         '(move, '
+                                                                                         'click, '
+                                                                                         'double_click, '
+                                                                                         'right_click, '
+                                                                                         'typewrite, '
+                                                                                         'press, '
+                                                                                         'hotkey, '
+                                                                                         'scroll).',
+                                                                          'enum': [   'move',
+                                                                                      'click',
+                                                                                      'double_click',
+                                                                                      'right_click',
+                                                                                      'typewrite',
+                                                                                      'press',
+                                                                                      'hotkey',
+                                                                                      'scroll'],
+                                                                          'type': 'string'},
+                                                            'button': {   'default': 'left',
+                                                                          'description': 'Mouse '
+                                                                                         'button '
+                                                                                         'to '
+                                                                                         'use '
+                                                                                         '(left, '
+                                                                                         'right, '
+                                                                                         'middle).',
+                                                                          'enum': [   'left',
+                                                                                      'right',
+                                                                                      'middle'],
+                                                                          'type': 'string'},
+                                                            'clicks': {   'default': 1,
+                                                                          'description': 'Number '
+                                                                                         'of '
+                                                                                         'clicks '
+                                                                                         '(default '
+                                                                                         '1).',
+                                                                          'type': 'integer'},
+                                                            'duration': {   'default': 0.0,
+                                                                            'description': 'Duration '
+                                                                                           'for '
+                                                                                           'mouse '
+                                                                                           'movement '
+                                                                                           '(seconds).',
+                                                                            'type': 'number'},
+                                                            'interval': {   'default': 0.0,
+                                                                            'description': 'Interval '
+                                                                                           'between '
+                                                                                           'clicks '
+                                                                                           '(seconds).',
+                                                                            'type': 'number'},
+                                                            'keys': {   'description': 'List '
+                                                                                       'of '
+                                                                                       'keys '
+                                                                                       'for '
+                                                                                       'hotkey '
+                                                                                       'action.',
+                                                                        'items': {   'type': 'string'},
+                                                                        'type': 'array'},
+                                                            'scroll': {   'description': 'Amount '
+                                                                                         'to '
+                                                                                         'scroll '
+                                                                                         '(positive '
+                                                                                         'for '
+                                                                                         'up, '
+                                                                                         'negative '
+                                                                                         'for '
+                                                                                         'down).',
+                                                                          'type': 'integer'},
+                                                            'text': {   'description': 'Text '
+                                                                                       'to '
+                                                                                       'type '
+                                                                                       'or '
+                                                                                       'key '
+                                                                                       'to '
+                                                                                       'press '
+                                                                                       'for '
+                                                                                       'certain '
+                                                                                       'actions.',
+                                                                        'type': 'string'},
+                                                            'x': {   'description': 'X '
+                                                                                    'coordinate '
+                                                                                    'for '
+                                                                                    'mouse '
+                                                                                    'actions '
+                                                                                    '(optional).',
+                                                                     'type': 'integer'},
+                                                            'y': {   'description': 'Y '
+                                                                                    'coordinate '
+                                                                                    'for '
+                                                                                    'mouse '
+                                                                                    'actions '
+                                                                                    '(optional).',
+                                                                     'type': 'integer'}},
+                                          'required': ['action'],
+                                          'type': 'object'}},
+        'type': 'function'}]
+
+__all__ = ["tool"]
+
+