aether-robotics 3.4.2__tar.gz → 3.4.4__tar.gz

aether_robotics-3.4.4/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: aether-robotics
+Version: 3.4.4
+Summary: Autonomous multi-agent robotics system with DRL-First Hybrid FDIR
+Author: Chahel Paatur
+License: MIT
+Project-URL: Homepage, https://github.com/ChahelPaatur/AETHER
+Project-URL: Repository, https://github.com/ChahelPaatur/AETHER
+Project-URL: Issues, https://github.com/ChahelPaatur/AETHER/issues
+Keywords: robotics,autonomous,FDIR,fault-detection,raspberry-pi,drone,AI
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Hardware
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: requests>=2.32.0
+Provides-Extra: full
+Requires-Dist: anthropic>=0.50.0; extra == "full"
+Requires-Dist: flask>=3.0.0; extra == "full"
+Requires-Dist: opencv-python-headless>=4.8.0; extra == "full"
+Requires-Dist: matplotlib>=3.7.0; extra == "full"
+Provides-Extra: pi
+Requires-Dist: picamera2; extra == "pi"
+Requires-Dist: RPi.GPIO; extra == "pi"
+Requires-Dist: gpiozero; extra == "pi"
+Requires-Dist: smbus2; extra == "pi"
+Provides-Extra: drone
+Requires-Dist: pymavlink; extra == "drone"
+Requires-Dist: pyserial; extra == "drone"
+Provides-Extra: ml
+Requires-Dist: ultralytics; extra == "ml"
+Requires-Dist: scipy; extra == "ml"
+Requires-Dist: scikit-learn; extra == "ml"
+Dynamic: license-file
+
+```
+    ████████████████████████████████
+   ████████████████████████████████
+  █████╔═══════════════════╗█████
+  █████║  ▄████▄   ▄████▄  ║█████
+  █████║ ████████████████ ║█████
+  █████║ ██████████████ ║█████
+  █████║ █▀▀████████▀▀█ ║█████
+  █████║  ▀████▀   ▀████▀  ║█████
+  █████║▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄║█████
+  █████║  ━━━━━━━━━━━━━━━  ║█████
+  █████║  ▌ AETHER  v3 ▐  ║█████
+  █████║  ━━━━━━━━━━━━━━━  ║█████
+  █████╚═══════════════════╝█████
+   ████████████████████████████████
+    ████████████████████████████████
+```
+
+# AETHER — Autonomous Robotics Operating System
+
+> AETHER is the autonomous operating system for robots. Plug in and talk to your robot in plain English and ask it to do anything you want.
+
+AETHER connects to whatever hardware is present at startup, discovers every actuator through an interactive GPIO calibration walk, and writes a `physical_map` of every servo and motor by BCM pin. That map feeds into an LLM planner that translates plain-English objectives into the correct hardware action — pin pre-filled, servo type resolved, direction inferred. Motion commands dispatch to GPIO, while a PPO fault-detection network runs concurrently on the 15-dimensional sensor observation vector, detecting and recovering from failures in real time. Every layer — discovery, pin mapping, natural-language planning, execution, fault recovery — runs on a Raspberry Pi with no cloud dependency except the Anthropic API for the planner.
+
+[Demo and docs → aether-robotics.com](https://aether-robotics.com)
+
+---
+
+## Quick Start
+
+```bash
+pip install aether-robotics
+aether --calibrate
+aether --mode agent
+```
+
+Calibration walks every safe GPIO pin (BCM 4–27, excluding I2C/SPI/UART), pulses each with a positional servo sweep, and prompts you to label what moved. The result is a `physical_map` saved in your calibration profile and loaded automatically at next startup.
+
+Once calibrated:
+
+```
+objective> move the wheel forward for 5 seconds
+[PLAN]  [LLM]  servo_cont_wheel
+[EXEC]  servo_cont_wheel(speed=50, duration=5)
+[OK]    success=True  (5009ms)
+```
+
+AETHER discovered the wheel on BCM 17 during calibration, the planner mapped "wheel forward" to the calibrated action, the servo spun for 5 seconds and stopped.
+
+---
+
+## What AETHER Does That Others Don't
+
+- **Discovers the robot.** Calibration walks every GPIO pin, you label what moved, AETHER builds a `physical_map` with BCM pin, device type, and action label for each actuator (unlike ROS/Viam where you configure drivers manually before the system knows what hardware exists).
+- **Speaks natural language.** Type plain English; the LLM planner resolves intent against your robot's `physical_map` and dispatches the correct BCM pin pre-filled (unlike ROS action servers that require typed message structs and correct namespace knowledge).
+- **Detects faults in real time.** DRL-First Hybrid FDIR achieves SFRI 69.99, 100% detection rate, and 100% recovery rate over 6,023 real-hardware steps (unlike threshold-rule systems that require manual parameter tuning per platform and miss novel fault signatures).
+- **Improves through use.** Correction traces are logged per step; operational memory and sim-to-real action transfer are on the roadmap (unlike static planners that repeat the same failure mode without feedback).
+
+---
+
+## Commands
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| `--mode sim` | Simulation with fault injection against a virtual robot (default) |
+| `--mode agent` | Interactive LLM-planned objectives on live hardware; prompts for input |
+| `--mode realworld` | Continuous live-hardware FDIR loop — camera + system sensors, no planner |
+| `--mode server` | HTTP API on `--port`; accepts `POST /objective` and `GET /health` |
+| `--mode dashboard` | Flask web UI on port 5000 with live objective submission and OLED preview |
+
+### Useful Flags
+
+| Flag | When to use |
+|------|-------------|
+| `--calibrate` | First-time setup — walks every GPIO pin, you label what moves |
+| `--recalibrate` | Re-run the full pin walk (e.g. after wiring changes); skips known-empty pins |
+| `--auto-calibrate` | Headless calibration with no interactive prompts |
+| `--once "objective"` | Run a single objective non-interactively and exit; useful in scripts |
+| `--task "objective"` | Task description for `--mode sim` |
+| `--schedule "..."` | Scheduled runs: `"every 30s: scan environment"`, `"for 5min: obj"`, `"until 22:00: obj"` |
+| `--continuous` | Run `--mode realworld` indefinitely until Ctrl-C |
+| `--servo-pin N` | Override the servo GPIO BCM pin for this session (supersedes calibration profile) |
+| `--robot {rover_v1,drone_v1}` | Robot config for `--mode sim` (default: `rover_v1`) |
+| `--faults {disabled,enabled,heavy}` | Fault injection level for sim/realworld (default: `disabled`) |
+| `--scenario TEXT` | Sim scenario: `simple`, `obstacles`, `imu_fault`, `battery`, `compound`, `fault_heavy` |
+| `--max-steps N` | Max steps per episode (default: 300) |
+| `--seed N` | Random seed for reproducible sim runs (default: 42) |
+| `--render` | Print ASCII state render at each sim step |
+| `--plots` | Generate matplotlib SFRI/metrics plots after a sim run |
+| `--no-learning` | Freeze PPO weights — useful for controlled benchmarking |
+| `--port N` | Port for `--mode server` (default: 8080) |
+| `--auto-install` | Install missing Python packages without prompting |
+| `--auto-update` | Pull the latest version without prompting |
+| `--no-install` | Skip the package-install prompt entirely |
+| `--no-update` | Skip the update check |
+| `--verbose` | Enable debug logging |
+
+---
+
+## Supported Hardware
+
+**Tested and working**
+
+Raspberry Pi 4 Model B · USB camera or picamera2 · GPIO servos (positional or continuous-rotation) · SSD1306 OLED over SPI · Anthropic API (LLM planner and vision)
+
+**Should work, unverified**
+
+Pi Zero 2 W · Pi 5 (requires `rpi-lgpio` in place of `RPi.GPIO`) · PCA9685 I2C 16-channel servo driver · MAVLink flight controllers via USB serial
+
+**In development**
+
+Arduino/ESP32 serial bridge · ArduPilot drone support · multi-robot coordination
+
+---
+
+## Architecture
+
+```
+  User input (plain English)
+        │
+        ▼
+  ToolDiscovery ──────────────► physical_map  (saved calibration profile)
+        │                                  │
+        ▼                                  ▼
+  LLMPlanner ◄──── physical_map injected into planner context
+        │
+        ▼
+  NavigationEngine  (L1 camera / L2 GPIO / L3 MAVLink)
+        │                         │
+        ▼                         ▼
+  Hardware (servo/motor/FC)  FaultAgent (PPO, 15-dim obs → fault class)
+                                   │
+                             detect · recover · log
+```
+
+---
+
+## Benchmarks
+
+Real-hardware deployment: Raspberry Pi 4, GPIO servos, live camera, Anthropic API planner.
+
+| Metric | Value | Conditions |
+|--------|------:|------------|
+| SFRI | **69.99** | 6,023 steps, real hardware |
+| MTTR | **1.35 steps** | Mean time to recover from injected fault |
+| Detection rate | **100%** | 0 misses, 0 false positives |
+
+> SFRI (Stability Fault Recovery Index) = 35×DR + 25×(1 − MTTR/max\_steps) + 10×RR − 30×FPR. Range 0–70; higher is better.
+
+---
+
+## Roadmap
+
+- ✓ **Phase 1 — Reverse Engineering** (current)
+- **Phase 2 — Robot Genome** (portable robot identity card)
+- **Phase 3 — Vision-Language Grounding** ("follow the orange cone")
+- **Phase 4 — Operational Memory + Sim-to-Real Action Transfer**
+- **Phase 5 — Multi-robot coordination**
+
+---
+
+## Early Access
+
+AETHER is in early access. We're working with a small number of robotics teams and researchers to refine the platform. Email chahelpaatur@aether-robotics.com for access.
+
+---
+
+## Citation
+
+```bibtex
+@software{aether2026,
+  title   = {AETHER: Autonomous Operating System for Robots},
+  author  = {Paatur, Chahel},
+  year    = {2026},
+  version = {3.4.3},
+  url     = {https://aether-robotics.com},
+  note    = {DRL-First Hybrid FDIR with physical-map calibration and LLM planning},
+}
+```
+
+---
+
+AETHER is proprietary software in early access. All rights reserved. © 2026 Chahel Paatur.

aether_robotics-3.4.4/README.md

@@ -0,0 +1,185 @@
+```
+    ████████████████████████████████
+   ████████████████████████████████
+  █████╔═══════════════════╗█████
+  █████║  ▄████▄   ▄████▄  ║█████
+  █████║ ████████████████ ║█████
+  █████║ ██████████████ ║█████
+  █████║ █▀▀████████▀▀█ ║█████
+  █████║  ▀████▀   ▀████▀  ║█████
+  █████║▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄║█████
+  █████║  ━━━━━━━━━━━━━━━  ║█████
+  █████║  ▌ AETHER  v3 ▐  ║█████
+  █████║  ━━━━━━━━━━━━━━━  ║█████
+  █████╚═══════════════════╝█████
+   ████████████████████████████████
+    ████████████████████████████████
+```
+
+# AETHER — Autonomous Robotics Operating System
+
+> AETHER is the autonomous operating system for robots. Plug in and talk to your robot in plain English and ask it to do anything you want.
+
+AETHER connects to whatever hardware is present at startup, discovers every actuator through an interactive GPIO calibration walk, and writes a `physical_map` of every servo and motor by BCM pin. That map feeds into an LLM planner that translates plain-English objectives into the correct hardware action — pin pre-filled, servo type resolved, direction inferred. Motion commands dispatch to GPIO, while a PPO fault-detection network runs concurrently on the 15-dimensional sensor observation vector, detecting and recovering from failures in real time. Every layer — discovery, pin mapping, natural-language planning, execution, fault recovery — runs on a Raspberry Pi with no cloud dependency except the Anthropic API for the planner.
+
+[Demo and docs → aether-robotics.com](https://aether-robotics.com)
+
+---
+
+## Quick Start
+
+```bash
+pip install aether-robotics
+aether --calibrate
+aether --mode agent
+```
+
+Calibration walks every safe GPIO pin (BCM 4–27, excluding I2C/SPI/UART), pulses each with a positional servo sweep, and prompts you to label what moved. The result is a `physical_map` saved in your calibration profile and loaded automatically at next startup.
+
+Once calibrated:
+
+```
+objective> move the wheel forward for 5 seconds
+[PLAN]  [LLM]  servo_cont_wheel
+[EXEC]  servo_cont_wheel(speed=50, duration=5)
+[OK]    success=True  (5009ms)
+```
+
+AETHER discovered the wheel on BCM 17 during calibration, the planner mapped "wheel forward" to the calibrated action, the servo spun for 5 seconds and stopped.
+
+---
+
+## What AETHER Does That Others Don't
+
+- **Discovers the robot.** Calibration walks every GPIO pin, you label what moved, AETHER builds a `physical_map` with BCM pin, device type, and action label for each actuator (unlike ROS/Viam where you configure drivers manually before the system knows what hardware exists).
+- **Speaks natural language.** Type plain English; the LLM planner resolves intent against your robot's `physical_map` and dispatches the correct BCM pin pre-filled (unlike ROS action servers that require typed message structs and correct namespace knowledge).
+- **Detects faults in real time.** DRL-First Hybrid FDIR achieves SFRI 69.99, 100% detection rate, and 100% recovery rate over 6,023 real-hardware steps (unlike threshold-rule systems that require manual parameter tuning per platform and miss novel fault signatures).
+- **Improves through use.** Correction traces are logged per step; operational memory and sim-to-real action transfer are on the roadmap (unlike static planners that repeat the same failure mode without feedback).
+
+---
+
+## Commands
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| `--mode sim` | Simulation with fault injection against a virtual robot (default) |
+| `--mode agent` | Interactive LLM-planned objectives on live hardware; prompts for input |
+| `--mode realworld` | Continuous live-hardware FDIR loop — camera + system sensors, no planner |
+| `--mode server` | HTTP API on `--port`; accepts `POST /objective` and `GET /health` |
+| `--mode dashboard` | Flask web UI on port 5000 with live objective submission and OLED preview |
+
+### Useful Flags
+
+| Flag | When to use |
+|------|-------------|
+| `--calibrate` | First-time setup — walks every GPIO pin, you label what moves |
+| `--recalibrate` | Re-run the full pin walk (e.g. after wiring changes); skips known-empty pins |
+| `--auto-calibrate` | Headless calibration with no interactive prompts |
+| `--once "objective"` | Run a single objective non-interactively and exit; useful in scripts |
+| `--task "objective"` | Task description for `--mode sim` |
+| `--schedule "..."` | Scheduled runs: `"every 30s: scan environment"`, `"for 5min: obj"`, `"until 22:00: obj"` |
+| `--continuous` | Run `--mode realworld` indefinitely until Ctrl-C |
+| `--servo-pin N` | Override the servo GPIO BCM pin for this session (supersedes calibration profile) |
+| `--robot {rover_v1,drone_v1}` | Robot config for `--mode sim` (default: `rover_v1`) |
+| `--faults {disabled,enabled,heavy}` | Fault injection level for sim/realworld (default: `disabled`) |
+| `--scenario TEXT` | Sim scenario: `simple`, `obstacles`, `imu_fault`, `battery`, `compound`, `fault_heavy` |
+| `--max-steps N` | Max steps per episode (default: 300) |
+| `--seed N` | Random seed for reproducible sim runs (default: 42) |
+| `--render` | Print ASCII state render at each sim step |
+| `--plots` | Generate matplotlib SFRI/metrics plots after a sim run |
+| `--no-learning` | Freeze PPO weights — useful for controlled benchmarking |
+| `--port N` | Port for `--mode server` (default: 8080) |
+| `--auto-install` | Install missing Python packages without prompting |
+| `--auto-update` | Pull the latest version without prompting |
+| `--no-install` | Skip the package-install prompt entirely |
+| `--no-update` | Skip the update check |
+| `--verbose` | Enable debug logging |
+
+---
+
+## Supported Hardware
+
+**Tested and working**
+
+Raspberry Pi 4 Model B · USB camera or picamera2 · GPIO servos (positional or continuous-rotation) · SSD1306 OLED over SPI · Anthropic API (LLM planner and vision)
+
+**Should work, unverified**
+
+Pi Zero 2 W · Pi 5 (requires `rpi-lgpio` in place of `RPi.GPIO`) · PCA9685 I2C 16-channel servo driver · MAVLink flight controllers via USB serial
+
+**In development**
+
+Arduino/ESP32 serial bridge · ArduPilot drone support · multi-robot coordination
+
+---
+
+## Architecture
+
+```
+  User input (plain English)
+        │
+        ▼
+  ToolDiscovery ──────────────► physical_map  (saved calibration profile)
+        │                                  │
+        ▼                                  ▼
+  LLMPlanner ◄──── physical_map injected into planner context
+        │
+        ▼
+  NavigationEngine  (L1 camera / L2 GPIO / L3 MAVLink)
+        │                         │
+        ▼                         ▼
+  Hardware (servo/motor/FC)  FaultAgent (PPO, 15-dim obs → fault class)
+                                   │
+                             detect · recover · log
+```
+
+---
+
+## Benchmarks
+
+Real-hardware deployment: Raspberry Pi 4, GPIO servos, live camera, Anthropic API planner.
+
+| Metric | Value | Conditions |
+|--------|------:|------------|
+| SFRI | **69.99** | 6,023 steps, real hardware |
+| MTTR | **1.35 steps** | Mean time to recover from injected fault |
+| Detection rate | **100%** | 0 misses, 0 false positives |
+
+> SFRI (Stability Fault Recovery Index) = 35×DR + 25×(1 − MTTR/max\_steps) + 10×RR − 30×FPR. Range 0–70; higher is better.
+
+---
+
+## Roadmap
+
+- ✓ **Phase 1 — Reverse Engineering** (current)
+- **Phase 2 — Robot Genome** (portable robot identity card)
+- **Phase 3 — Vision-Language Grounding** ("follow the orange cone")
+- **Phase 4 — Operational Memory + Sim-to-Real Action Transfer**
+- **Phase 5 — Multi-robot coordination**
+
+---
+
+## Early Access
+
+AETHER is in early access. We're working with a small number of robotics teams and researchers to refine the platform. Email chahelpaatur@aether-robotics.com for access.
+
+---
+
+## Citation
+
+```bibtex
+@software{aether2026,
+  title   = {AETHER: Autonomous Operating System for Robots},
+  author  = {Paatur, Chahel},
+  year    = {2026},
+  version = {3.4.3},
+  url     = {https://aether-robotics.com},
+  note    = {DRL-First Hybrid FDIR with physical-map calibration and LLM planning},
+}
+```
+
+---
+
+AETHER is proprietary software in early access. All rights reserved. © 2026 Chahel Paatur.

aether_robotics-3.4.4/VERSION

@@ -0,0 +1 @@
+3.4.4

{aether_robotics-3.4.2 → aether_robotics-3.4.4}/aether/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "3.4.2"
+__version__ = "3.4.4"
 __author__ = "Chahel Paatur"

{aether_robotics-3.4.2 → aether_robotics-3.4.4}/aether/core/calibration.py

@@ -134,8 +134,12 @@ _CATEGORY_ACTION_PREFIX: Dict[int, str] = {
 # Stopwords stripped before slugifying descriptions (Bug 4)
 _SLUG_STOPWORDS = frozenset({
     "the", "then", "and", "a", "an", "that", "moved", "move", "moves",
-    "is", "was", "it", "of", "to", "in", "at", "by", "for", "from",
-    "with", "or", "but", "on", "its", "when", "while", "also", "did",
+    "is", "was", "it", "of", "to",
+    # "in" and "on" intentionally excluded: they appear in directional phrases
+    # like "in front", "on the left", "on top" and must survive slugification.
+    "at", "by", "for", "from",
+    "with", "or", "but",
+    "its", "when", "while", "also", "did",
     "went", "going", "started", "which",
 })
 

{aether_robotics-3.4.2 → aether_robotics-3.4.4}/aether/core/navigation_engine.py

@@ -858,10 +858,17 @@ class _MotorNav:
         return _ok({"action": "stop"})
 
     def servo_set(self, pin: int, angle: float,
-                  servo_type: str = "positional") -> Dict:
+                  servo_type: str = "positional",
+                  duty_cycle: Optional[float] = None) -> Dict:
         if self._gpio is None:
             return _err("GPIO not available")
 
+        # If an explicit duty_cycle is supplied, use it directly and skip the
+        # angle→duty formula.  This lets CorrectionAgent override the output
+        # without having to reverse-engineer the mapping.
+        if duty_cycle is not None:
+            return self.pwm_set(pin, 50, float(duty_cycle))
+
         if servo_type == "continuous":
             # Continuous-rotation servo: interpret angle as speed -100..+100
             # 0 → stop (90°), positive → forward, negative → reverse
@@ -1682,7 +1689,8 @@ class NavigationEngine:
                 "servo_set": lambda: self._motors.servo_set(
                     params.get("pin") or self._default_servo_pin(),
                     params.get("angle", 90),
-                    params.get("servo_type") or self._default_servo_type()),
+                    params.get("servo_type") or self._default_servo_type(),
+                    duty_cycle=params.get("duty_cycle")),
                 "navigate_to_color": lambda: self._motors.navigate_to_color(
                     params.get("color", params.get("class_name", "red")),
                     lp, rp, sp, params.get("timeout", 30)),

{aether_robotics-3.4.2 → aether_robotics-3.4.4}/aether/core/tool_registry.py

@@ -1023,18 +1023,52 @@ def register_built_tools(registry: "ToolRegistry",
                 def _make_physical_fn(pin, pwm_type):
                     def _fn(**kwargs):
                         if pwm_type == "servo_continuous":
-                            # Accept direction/speed/angle — any key the LLM uses
-                            hint = kwargs.get(
-                                "direction",
-                                kwargs.get("speed",
-                                kwargs.get("angle", "forward")))
+                            # Resolve direction from whichever kwarg the LLM uses.
+                            # Priority: direction/speed > angle > position > default.
+                            if "direction" in kwargs or "speed" in kwargs:
+                                hint = kwargs.get("direction") or kwargs.get("speed")
+                            elif "angle" in kwargs:
+                                hint = kwargs["angle"]
+                            elif "position" in kwargs:
+                                # "position" is a positional-servo idiom with no
+                                # meaning on a continuous servo.  position=90 is the
+                                # center/neutral default — treat it as forward intent
+                                # because stopping requires an explicit stop/halt/neutral.
+                                # TODO: thread objective text into the closure so that
+                                # "stop" + position=90 maps to neutral (0.0) while
+                                # "move" + position=90 maps to forward (100.0).
+                                pos = kwargs["position"]
+                                hint = "forward" if float(pos) == 90.0 else pos
+                            else:
+                                # No direction hint at all — default to forward.
+                                # Stopping requires explicit stop/halt/neutral intent.
+                                hint = "forward"
+
                             speed = _infer_continuous_speed(hint)
-                            return registry.execute(
+                            result = registry.execute(
                                 "servo_set",
                                 {"pin": pin, "angle": speed,
                                  "servo_type": "continuous"})
+
+                            # Optional timed run: spin for N seconds then neutral.
+                            duration = kwargs.get("duration")
+                            if duration is not None and result.success:
+                                try:
+                                    time.sleep(float(duration))
+                                except (ValueError, TypeError):
+                                    pass
+                                registry.execute(
+                                    "servo_set",
+                                    {"pin": pin, "angle": 0.0,
+                                     "servo_type": "continuous"})
+
+                            return result
+
                         elif pwm_type == "servo_positional":
-                            angle = float(kwargs.get("angle", 90))
+                            # Accept both "angle" and "position" — LLM uses either
+                            angle = float(
+                                kwargs.get("angle",
+                                kwargs.get("position", 90)))
                             return registry.execute(
                                 "servo_set",
                                 {"pin": pin, "angle": angle,