remotescout 1.0.0__tar.gz

remotescout-1.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+*.egg
+
+# Build
+build/
+build_log*.txt
+
+# Config & data (contains credentials/user data)
+config/
+data/cache/
+data/downloads/
+logs/
+
+# Keep uploads structure but ignore large files
+data/uploads/*/Remote/
+
+# OS
+desktop.ini
+.megaignore
+Thumbs.db
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+
+# Legacy reference file
+main-sinAPI.py
+
+# Claude Code
+.claude/

remotescout-1.0.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: remotescout
+Version: 1.0.0
+Summary: Python library for managing IoT agents via MQTT — screenshots, commands, file transfers, tunnels, cameras
+Project-URL: Homepage, https://github.com/Pedro77339/remotescout-mcp
+Project-URL: Repository, https://github.com/Pedro77339/remotescoutapp
+Author: Pedro Camacho
+License: MIT
+Keywords: agent,iot,mcp,mqtt,remote-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: paho-mqtt>=1.6
+Requires-Dist: pillow>=9.0
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# remotescout
+
+Python library for managing IoT agents via MQTT. Provides a unified API for remote device management: screenshots, shell commands, file transfers, TCP tunnels, camera feeds, and OTA deployments.
+
+Built for the [Remote Scout MCP Server](https://github.com/Pedro77339/remotescout-mcp) but can be used standalone.
+
+## Installation
+
+```bash
+pip install remotescout
+```
+
+## Configuration
+
+### Option 1: Environment variables
+
+```bash
+export RS_MQTT_GLOBAL_PASSWORD="your_global_password"
+export RS_MQTT_ROUTER_PASSWORD="your_router_password"
+```
+
+### Option 2: settings.json
+
+Create a `config/settings.json` in your base path:
+
+```json
+{
+    "mqtt_router_host": "mrouter.ci24.com",
+    "mqtt_router_port": 8001,
+    "mqtt_router_user": "ci24",
+    "mqtt_router_password": "YOUR_PASSWORD",
+    "mqtt_global_host": "mgovernor.ci24.com",
+    "mqtt_global_port": 1883,
+    "mqtt_global_user": "ci24",
+    "mqtt_global_password": "YOUR_PASSWORD"
+}
+```
+
+> Contact the project admin for MQTT broker credentials.
+
+## Quick start
+
+```python
+from remotescout import RemoteScoutAPI
+
+api = RemoteScoutAPI(base_path="./my_base")
+api.initialize()
+api.connect()
+
+# Login
+api.login("your_username")
+
+# List agents
+agents = api.get_agents_by_domain("BLX")
+for a in agents:
+    print(f"{a.mac} - {a.id} ({a.status.value})")
+
+# Execute command
+result = api.execute_command("d83addc8721e", "uptime")
+print(result.output)
+
+# Screenshot
+img_bytes = api.get_screenshot("d83addc8721e", ratio=3, timeout=10)
+```
+
+## Features
+
+| Feature | Method |
+|---------|--------|
+| Agent discovery | `get_agents_by_domain()`, `get_agent()` |
+| Shell commands | `execute_command()` |
+| Screenshots | `get_screenshot()` |
+| File browser | `list_directory()`, `get_file_bytes()` |
+| File transfer | `download_file()` |
+| TCP tunnels | `open_tunnel()`, `close_all_tunnels()` |
+| Camera feeds | `discover_cameras()`, `get_camera_frame()` |
+| OTA packages | `list_packages()`, `upload_package()` |
+| OTP tokens | `get_otp()` |
+
+## Requirements
+
+- Python 3.10+
+- Access to the MQTT broker (credentials from admin)
+- User permissions file or governor-validated credentials

remotescout-1.0.0/README.md

@@ -0,0 +1,84 @@
+# remotescout
+
+Python library for managing IoT agents via MQTT. Provides a unified API for remote device management: screenshots, shell commands, file transfers, TCP tunnels, camera feeds, and OTA deployments.
+
+Built for the [Remote Scout MCP Server](https://github.com/Pedro77339/remotescout-mcp) but can be used standalone.
+
+## Installation
+
+```bash
+pip install remotescout
+```
+
+## Configuration
+
+### Option 1: Environment variables
+
+```bash
+export RS_MQTT_GLOBAL_PASSWORD="your_global_password"
+export RS_MQTT_ROUTER_PASSWORD="your_router_password"
+```
+
+### Option 2: settings.json
+
+Create a `config/settings.json` in your base path:
+
+```json
+{
+    "mqtt_router_host": "mrouter.ci24.com",
+    "mqtt_router_port": 8001,
+    "mqtt_router_user": "ci24",
+    "mqtt_router_password": "YOUR_PASSWORD",
+    "mqtt_global_host": "mgovernor.ci24.com",
+    "mqtt_global_port": 1883,
+    "mqtt_global_user": "ci24",
+    "mqtt_global_password": "YOUR_PASSWORD"
+}
+```
+
+> Contact the project admin for MQTT broker credentials.
+
+## Quick start
+
+```python
+from remotescout import RemoteScoutAPI
+
+api = RemoteScoutAPI(base_path="./my_base")
+api.initialize()
+api.connect()
+
+# Login
+api.login("your_username")
+
+# List agents
+agents = api.get_agents_by_domain("BLX")
+for a in agents:
+    print(f"{a.mac} - {a.id} ({a.status.value})")
+
+# Execute command
+result = api.execute_command("d83addc8721e", "uptime")
+print(result.output)
+
+# Screenshot
+img_bytes = api.get_screenshot("d83addc8721e", ratio=3, timeout=10)
+```
+
+## Features
+
+| Feature | Method |
+|---------|--------|
+| Agent discovery | `get_agents_by_domain()`, `get_agent()` |
+| Shell commands | `execute_command()` |
+| Screenshots | `get_screenshot()` |
+| File browser | `list_directory()`, `get_file_bytes()` |
+| File transfer | `download_file()` |
+| TCP tunnels | `open_tunnel()`, `close_all_tunnels()` |
+| Camera feeds | `discover_cameras()`, `get_camera_frame()` |
+| OTA packages | `list_packages()`, `upload_package()` |
+| OTP tokens | `get_otp()` |
+
+## Requirements
+
+- Python 3.10+
+- Access to the MQTT broker (credentials from admin)
+- User permissions file or governor-validated credentials

remotescout-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "remotescout"
+version = "1.0.0"
+description = "Python library for managing IoT agents via MQTT — screenshots, commands, file transfers, tunnels, cameras"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Pedro Camacho"}]
+keywords = ["iot", "mqtt", "remote-management", "mcp", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "paho-mqtt>=1.6",
+    "pillow>=9.0",
+    "requests>=2.28",
+]
+
+[project.urls]
+Homepage = "https://github.com/Pedro77339/remotescout-mcp"
+Repository = "https://github.com/Pedro77339/remotescoutapp"
+
+[tool.hatch.build.targets.wheel]
+packages = ["remotescout"]

remotescout-1.0.0/remotescout/__init__.py

@@ -0,0 +1,35 @@
+"""RemoteScout — Agent management via MQTT."""
+
+from remotescout.api import RemoteScoutAPI
+from remotescout.models import (
+    AgentInfo,
+    AgentStatus,
+    UserPermissions,
+    Settings,
+    MqttConfig,
+    FileEntry,
+    CommandResult,
+    CameraInfo,
+    PortForwardInfo,
+    TransferProgress,
+)
+from remotescout.events import EventEmitter, EventType, Event
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "RemoteScoutAPI",
+    "AgentInfo",
+    "AgentStatus",
+    "UserPermissions",
+    "Settings",
+    "MqttConfig",
+    "FileEntry",
+    "CommandResult",
+    "CameraInfo",
+    "PortForwardInfo",
+    "TransferProgress",
+    "EventEmitter",
+    "EventType",
+    "Event",
+]

remotescout-1.0.0/remotescout/agents/__init__.py

@@ -0,0 +1,3 @@
+from remotescout.agents.manager import AgentManager, AgentData
+
+__all__ = ["AgentManager", "AgentData"]

remotescout-1.0.0/remotescout/agents/manager.py

@@ -0,0 +1,197 @@
+"""AgentManager: Centralized agent state management.
+
+Copied from remotev3/agents/agent_manager.py — no import changes needed.
+"""
+
+import threading
+import queue
+import json
+from datetime import datetime
+from dataclasses import dataclass, field
+from typing import Dict, Optional, List
+from os.path import exists
+
+
+@dataclass
+class AgentData:
+    """Datos de un agente"""
+    mac: str
+    id: str
+    domain: str
+    ip_public: str
+    ip_local: str
+    description: str
+    ver: str = "2.0"
+    cpu: str = ""
+    os: str = ""
+    rotate: int = 90
+    login: str = "root"
+    ts: float = field(default_factory=lambda: datetime.now().timestamp())
+    frozen: int = 0
+
+    @property
+    def status(self) -> str:
+        """Calcular estado basado en timestamp"""
+        elapsed = datetime.now().timestamp() - self.ts
+        if elapsed > 60:
+            return "frozen"
+        elif elapsed > 30:
+            return "offline"
+        else:
+            return "online"
+
+    @property
+    def status_color(self) -> str:
+        status_map = {
+            "online": "#4CAF50",
+            "offline": "#FF5722",
+            "frozen": "#9E9E9E"
+        }
+        return status_map.get(self.status, "#9E9E9E")
+
+    @property
+    def status_icon(self) -> str:
+        status_map = {
+            "online": "check_circle",
+            "offline": "error",
+            "frozen": "snowflake"
+        }
+        return status_map.get(self.status, "help")
+
+
+class AgentManager:
+    """Gestiona el estado de todos los agentes"""
+
+    def __init__(self, user: str = ""):
+        self.user = user
+        self.agents: Dict[str, AgentData] = {}
+        self.agents_lock = threading.Lock()
+        self.update_queue = queue.Queue()
+        self.agents_status: Dict[str, dict] = {}
+        self.screenshot_cache: Dict[str, bytes] = {}
+        self.screenshot_lock = threading.Lock()
+
+    def add_agent(self, mac: str, agent_data) -> bool:
+        is_new = False
+        with self.agents_lock:
+            if isinstance(agent_data, dict):
+                agent_obj = AgentData(**agent_data)
+            else:
+                agent_obj = agent_data
+            if mac not in self.agents:
+                is_new = True
+            self.agents[mac] = agent_obj
+            self.update_queue.put(('add', mac, agent_obj))
+        return is_new
+
+    def update_agent_status(self, mac: str, status_data: dict):
+        with self.agents_lock:
+            if mac in self.agents:
+                if mac not in self.agents_status:
+                    self.agents_status[mac] = {}
+                self.agents_status[mac].update(status_data)
+                self.update_queue.put(('status', mac, status_data))
+
+    def update_screenshot(self, mac: str, screenshot_data: bytes):
+        with self.screenshot_lock:
+            self.screenshot_cache[mac] = screenshot_data
+            self.update_queue.put(('screenshot', mac, screenshot_data))
+
+    def get_agent(self, mac: str) -> Optional[AgentData]:
+        with self.agents_lock:
+            return self.agents.get(mac)
+
+    def get_screenshot(self, mac: str) -> Optional[bytes]:
+        with self.screenshot_lock:
+            return self.screenshot_cache.get(mac)
+
+    def get_agents_by_domain(self, domain_path: str = "") -> List[tuple]:
+        with self.agents_lock:
+            agents = []
+            for mac, agent in self.agents.items():
+                if domain_path == "" or agent.domain == domain_path:
+                    agents.append((mac, agent))
+            agents.sort(key=lambda x: x[1].id.lower())
+            return agents
+
+    def get_domain_hierarchy(self) -> dict:
+        hierarchy = {}
+        with self.agents_lock:
+            for mac, agent in self.agents.items():
+                domain = agent.domain
+                domain_parts = domain.split('/') if domain else ['']
+                current_level = hierarchy
+                for i, part in enumerate(domain_parts):
+                    if part not in current_level:
+                        current_level[part] = {'agents': [], 'subdomains': {}}
+                    if i == len(domain_parts) - 1:
+                        current_level[part]['agents'].append((mac, agent))
+                    else:
+                        current_level = current_level[part]['subdomains']
+        return hierarchy
+
+    def get_main_domains(self) -> Dict[str, int]:
+        hierarchy = self.get_domain_hierarchy()
+        main_domains = {}
+
+        def count_agents_recursive(data: dict) -> int:
+            count = len(data.get('agents', []))
+            for subdomain_data in data.get('subdomains', {}).values():
+                count += count_agents_recursive(subdomain_data)
+            return count
+
+        for domain, data in hierarchy.items():
+            main_domains[domain] = count_agents_recursive(data)
+        return dict(sorted(main_domains.items()))
+
+    def get_subdomains(self, domain_path: str) -> Dict[str, int]:
+        hierarchy = self.get_domain_hierarchy()
+        path_parts = domain_path.split('/') if domain_path else []
+        current_level = hierarchy
+        for part in path_parts:
+            if part in current_level:
+                current_level = current_level[part].get('subdomains', {})
+            else:
+                return {}
+
+        def count_agents_recursive(data: dict) -> int:
+            count = len(data.get('agents', []))
+            for subdomain_data in data.get('subdomains', {}).values():
+                count += count_agents_recursive(subdomain_data)
+            return count
+
+        subdomains = {}
+        for subdomain, data in current_level.items():
+            subdomains[subdomain] = count_agents_recursive(data)
+        return dict(sorted(subdomains.items()))
+
+    def count_agents(self) -> int:
+        with self.agents_lock:
+            return len(self.agents)
+
+    def get_visible_agents(self, domain_path: str = "", limit: int = 50) -> List[tuple]:
+        agents = self.get_agents_by_domain(domain_path)
+        return agents[:limit]
+
+    def save_to_file(self, filepath: str):
+        with self.agents_lock:
+            agents_dict = {}
+            for mac, agent in self.agents.items():
+                agents_dict[mac] = {
+                    'mac': agent.mac, 'id': agent.id, 'domain': agent.domain,
+                    'ip_public': agent.ip_public, 'ip_local': agent.ip_local,
+                    'description': agent.description, 'ver': agent.ver,
+                    'cpu': agent.cpu, 'os': agent.os, 'rotate': agent.rotate,
+                    'login': agent.login, 'ts': agent.ts, 'frozen': agent.frozen,
+                }
+            with open(filepath, 'w') as f:
+                json.dump(agents_dict, f, indent=4)
+
+    def load_from_file(self, filepath: str):
+        if not exists(filepath):
+            return
+        with open(filepath, 'r') as f:
+            agents_dict = json.load(f)
+        with self.agents_lock:
+            for mac, agent_data in agents_dict.items():
+                self.agents[mac] = AgentData(**agent_data)

remotescout-1.0.0/remotescout/ai/__init__.py

@@ -0,0 +1,13 @@
+"""AI Chat module for Remote Scout."""
+
+from remotescout.ai.chat_engine import AIChatEngine
+from remotescout.ai.providers import LLMProvider, HttpApiProvider, HttpOllamaProvider, MqttOllamaProvider
+from remotescout.ai.models import ChatMessage, MessageRole, ToolCall, ToolResult
+from remotescout.ai.tools import TOOLS, ToolExecutor
+from remotescout.ai.scripts import ScriptIndex
+
+__all__ = [
+    "AIChatEngine", "LLMProvider", "HttpApiProvider", "HttpOllamaProvider", "MqttOllamaProvider",
+    "ChatMessage", "MessageRole", "ToolCall", "ToolResult",
+    "TOOLS", "ToolExecutor", "ScriptIndex",
+]