feat: add embedded MicroPython VM with run_python tool

.gitignore

@@ -8,9 +8,16 @@ releases/
 sdkconfig
 sdkconfig.old
 dependencies.lock
-components/
 managed_components/
 
+# Custom components — track structure, ignore generated files
+components/*
+!components/micropython_embed/
+components/micropython_embed/generated/
+
+# MicroPython submodule build artifacts
+lib/micropython/
+
 # Generated headers
 main/assets/lang_config.h
 main/mmap_generate_emoji.h

README.md

@@ -24,6 +24,7 @@ MimiClaw turns a tiny ESP32-S3 board into a personal AI assistant. Plug it into
 - **Tiny** — No Linux, no Node.js, no bloat — just pure C
 - **Handy** — Message it from Telegram, it handles the rest
 - **Loyal** — Learns from memory, remembers across reboots
+- **Smart** — Embedded MicroPython VM lets the AI write and run code on the chip
 - **Energetic** — USB power, 0.5 W, runs 24/7
 - **Lovable** — One ESP32-S3 board, $5, nothing else
 
@@ -256,12 +257,29 @@ MimiClaw supports tool calling for both Anthropic and OpenAI — the LLM can cal
 |------|-------------|
 | `web_search` | Search the web via Tavily (preferred) or Brave for current information |
 | `get_current_time` | Fetch current date/time via HTTP and set the system clock |
+| `run_python` | Execute Python code in an embedded MicroPython VM (math, json, regex, collections, and more) |
 | `cron_add` | Schedule a recurring or one-shot task (the LLM creates cron jobs on its own) |
 | `cron_list` | List all scheduled cron jobs |
 | `cron_remove` | Remove a cron job by ID |
 
 To enable web search, set a [Tavily API key](https://app.tavily.com/home) via `MIMI_SECRET_TAVILY_KEY` (preferred), or a [Brave Search API key](https://brave.com/search/api/) via `MIMI_SECRET_SEARCH_KEY` in `mimi_secrets.h`.
 
+### MicroPython VM
+
+MimiClaw embeds a sandboxed [MicroPython](https://micropython.org/) interpreter that the AI can use via the `run_python` tool. This lets the agent write and execute Python code on the fly — for calculations, data transformations, text processing, and anything else that's unreliable via pure LLM reasoning.
+
+- **Available modules:** math, json, re, collections, struct, binascii, random, heapq
+- **Sandboxed:** no network, no filesystem, no hardware access — safe to run untrusted code
+- **Resource-light:** 512 KB PSRAM allocated per execution, freed immediately after
+- **Timeout-protected:** default 10 s, max 30 s — infinite loops are killed automatically
+
+The MicroPython VM requires a one-time setup step before building:
+
+```bash
+./scripts/build_micropython_embed.sh   # generates the MicroPython embed files
+idf.py build                           # then build as usual
+```
+
 ## Cron Tasks
 
 MimiClaw has a built-in cron scheduler that lets the AI schedule its own tasks. The LLM can create recurring jobs ("every N seconds") or one-shot jobs ("at unix timestamp") via the `cron_add` tool. When a job fires, its message is injected into the agent loop — so the AI wakes up, processes the task, and responds.
@@ -284,6 +302,8 @@ This turns MimiClaw into a proactive assistant — write tasks to `HEARTBEAT.md`
 - **Cron scheduler** — the AI can schedule its own recurring and one-shot tasks, persisted across reboots
 - **Heartbeat** — periodically checks a task file and prompts the AI to act autonomously
 - **Tool use** — ReAct agent loop with tool calling for both providers
+- **MicroPython VM** — embedded Python interpreter for on-device code execution by the AI
+- **Skill creator** — the AI can create new skills as Markdown files, including Python-powered ones
 
 ## For Developers
 

components/micropython_embed/CMakeLists.txt

@@ -0,0 +1,26 @@
+# MicroPython Embed Component for ESP-IDF
+#
+# Before building, generate the MicroPython embed files:
+#   ./scripts/build_micropython_embed.sh
+#
+# See: https://docs.micropython.org/en/latest/develop/embed.html
+
+set(MP_GENERATED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/generated")
+
+if(EXISTS "${MP_GENERATED_DIR}/port/micropython_embed.h")
+    file(GLOB_RECURSE MP_SRCS "${MP_GENERATED_DIR}/*.c")
+    idf_component_register(
+        SRCS ${MP_SRCS}
+        INCLUDE_DIRS "${MP_GENERATED_DIR}" "${MP_GENERATED_DIR}/port" "port"
+    )
+    # Suppress warnings in generated MicroPython code
+    target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-all -Wno-extra)
+else()
+    # Register component with headers only so CMake config succeeds.
+    # Linking will fail until the embed files are generated.
+    idf_component_register(INCLUDE_DIRS "port")
+    message(WARNING
+        "MicroPython embed files not found in ${MP_GENERATED_DIR}.\n"
+        "Run: ./scripts/build_micropython_embed.sh\n"
+        "Then rebuild with: idf.py build")
+endif()

components/micropython_embed/port/mpconfigport.h

@@ -0,0 +1,85 @@
+/*
+ * MicroPython port configuration for MimiClaw (ESP32-S3 embed).
+ *
+ * This file is used BOTH when building the embed port (to generate
+ * micropython_embed.c/h) AND when compiling the generated source
+ * as part of the ESP-IDF project.
+ *
+ * Safety: network, filesystem, hardware, and threading modules are
+ * disabled to sandbox executed code.
+ */
+#pragma once
+
+#include <stdint.h>
+
+/* Feature level — includes basic standard library modules */
+#define MICROPY_CONFIG_ROM_LEVEL        (MICROPY_CONFIG_ROM_LEVEL_BASIC_FEATURES)
+
+/* Type definitions for ESP32-S3 (32-bit Xtensa) */
+typedef intptr_t  mp_int_t;
+typedef uintptr_t mp_uint_t;
+typedef long      mp_off_t;
+
+/* Compiler & GC (required for mp_embed_exec_str) */
+#define MICROPY_ENABLE_COMPILER         (1)
+#define MICROPY_ENABLE_GC               (1)
+
+/* Scheduler — needed for KeyboardInterrupt on timeout */
+#define MICROPY_ENABLE_SCHEDULER        (1)
+#define MICROPY_KBD_EXCEPTION           (1)
+
+/* Stack overflow checking */
+#define MICROPY_STACKCHECK              (1)
+
+/* GC register scanning: use setjmp fallback on Xtensa (not natively supported) */
+#define MICROPY_GCREGS_SETJMP           (1)
+
+/* Use setjmp-based NLR instead of Xtensa asm (avoids linker relocation issues) */
+#define MICROPY_NLR_SETJMP              (1)
+
+/* ---- Enabled modules ---- */
+#define MICROPY_PY_MATH                 (1)
+#define MICROPY_PY_CMATH                (0)
+#define MICROPY_PY_JSON                 (1)
+#define MICROPY_PY_RE                   (1)
+#define MICROPY_PY_COLLECTIONS          (1)
+#define MICROPY_PY_COLLECTIONS_DEQUE    (1)
+#define MICROPY_PY_COLLECTIONS_ORDEREDDICT (1)
+#define MICROPY_PY_IO                   (1)
+#define MICROPY_PY_STRUCT               (1)
+#define MICROPY_PY_BINASCII             (1)
+#define MICROPY_PY_RANDOM               (1)
+#define MICROPY_PY_HEAPQ                (1)
+#define MICROPY_PY_HASHLIB              (0)
+
+/* Useful builtins */
+#define MICROPY_PY_BUILTINS_HELP        (0)
+#define MICROPY_PY_BUILTINS_INPUT       (0)
+
+/* ---- Disabled modules (sandbox) ---- */
+#define MICROPY_PY_SYS                  (0)
+#define MICROPY_PY_OS                   (0)
+#define MICROPY_PY_NETWORK              (0)
+#define MICROPY_PY_SOCKET               (0)
+#define MICROPY_PY_MACHINE              (0)
+#define MICROPY_PY_SELECT               (0)
+#define MICROPY_PY_THREAD               (0)
+
+/* No filesystem access */
+#define MICROPY_VFS                     (0)
+#define MICROPY_READER_VFS              (0)
+#define MICROPY_PY_BUILTINS_OPEN        (0)
+
+/* ---- VM hook for timeout enforcement ---- */
+extern volatile int micropython_vm_timeout_flag;
+
+#define MICROPY_VM_HOOK_LOOP \
+    do { \
+        if (micropython_vm_timeout_flag) { \
+            micropython_vm_timeout_flag = 0; \
+            mp_sched_keyboard_interrupt(); \
+        } \
+    } while (0);
+
+/* Root pointers (none needed for embed) */
+#define MICROPY_PORT_ROOT_POINTERS

components/micropython_embed/port/mphalport.h

@@ -0,0 +1,9 @@
+/*
+ * Minimal HAL port header for MicroPython embed on ESP32-S3.
+ * Actual HAL implementations are in main/micropython/micropython_vm.c.
+ */
+#pragma once
+
+static inline void mp_hal_set_interrupt_char(int c) {
+    (void)c;
+}

main/CMakeLists.txt

@@ -20,11 +20,13 @@ idf_component_register(
         "tools/tool_web_search.c"
         "tools/tool_get_time.c"
         "tools/tool_files.c"
+        "tools/tool_run_python.c"
+        "micropython/micropython_vm.c"
         "skills/skill_loader.c"
     INCLUDE_DIRS
         "."
     REQUIRES
         nvs_flash esp_wifi esp_netif esp_http_client esp_http_server
         esp_https_ota esp_event json spiffs console vfs app_update esp-tls
-        esp_timer esp_websocket_client
+        esp_timer esp_websocket_client micropython_embed
 )

main/agent/context_builder.c

@@ -46,7 +46,9 @@ esp_err_t context_build_system_prompt(char *buf, size_t size)
         "- list_dir: List files, optionally filter by prefix.\n"
         "- cron_add: Schedule a recurring or one-shot task. The message will trigger an agent turn when the job fires.\n"
         "- cron_list: List all scheduled cron jobs.\n"
-        "- cron_remove: Remove a scheduled cron job by ID.\n\n"
+        "- cron_remove: Remove a scheduled cron job by ID.\n"
+        "- run_python: Execute Python code via embedded MicroPython VM. Use print() for output. "
+        "Available modules: math, json, re, collections, struct, binascii, random. No network/file/hardware access.\n\n"
         "When using cron_add for Telegram delivery, always set channel='telegram' and a valid numeric chat_id.\n\n"
         "Use tools when needed. Provide your final answer as text after using tools.\n\n"
         "## Memory\n"

main/micropython/micropython_vm.c

@@ -0,0 +1,175 @@
+#include "micropython_vm.h"
+#include "mimi_config.h"
+
+#include <string.h>
+#include <errno.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+#include "esp_timer.h"
+#include "esp_log.h"
+#include "esp_heap_caps.h"
+
+#include "py/runtime.h"
+#include "py/builtin.h"
+#include "py/lexer.h"
+#include "py/mphal.h"
+#include "micropython_embed.h"
+
+static const char *TAG = "upy_vm";
+
+static SemaphoreHandle_t s_mutex = NULL;
+static esp_timer_handle_t s_timeout_timer = NULL;
+
+/* Shared stdout capture state (protected by mutex — only one exec at a time) */
+static char  *s_stdout_buf  = NULL;
+static size_t s_stdout_pos  = 0;
+static size_t s_stdout_size = 0;
+
+/* Timeout flag — set by timer callback, checked by VM hook in mpconfigport.h */
+volatile int micropython_vm_timeout_flag = 0;
+
+/* ---------- MicroPython HAL implementations ---------- */
+
+/* Called by MicroPython for all print() / stdout output */
+mp_uint_t mp_hal_stdout_tx_strn(const char *str, size_t len)
+{
+    if (!s_stdout_buf) return 0;
+    size_t avail = (s_stdout_size > s_stdout_pos + 1)
+                   ? s_stdout_size - s_stdout_pos - 1
+                   : 0;
+    size_t copy = (len < avail) ? len : avail;
+    if (copy > 0) {
+        memcpy(s_stdout_buf + s_stdout_pos, str, copy);
+        s_stdout_pos += copy;
+        s_stdout_buf[s_stdout_pos] = '\0';
+    }
+    return len;
+}
+
+/* Called by MicroPython for time.sleep_ms() / delays */
+void mp_hal_delay_ms(mp_uint_t ms)
+{
+    vTaskDelay(pdMS_TO_TICKS(ms));
+}
+
+/* ---------- Stubs for disabled filesystem/import features ---------- */
+
+/* Import stat — always report "not found" since we have no filesystem imports */
+mp_import_stat_t mp_import_stat(const char *path)
+{
+    return MP_IMPORT_STAT_NO_EXIST;
+}
+
+/* Lexer from file — not supported, raise error */
+mp_lexer_t *mp_lexer_new_from_file(qstr filename)
+{
+    mp_raise_OSError(ENOENT);
+}
+
+/* Built-in open() — disabled */
+mp_obj_t mp_builtin_open(size_t n_args, const mp_obj_t *args, mp_map_t *kwargs)
+{
+    mp_raise_OSError(EPERM);
+}
+MP_DEFINE_CONST_FUN_OBJ_KW(mp_builtin_open_obj, 1, mp_builtin_open);
+
+/* ---------- Timeout timer ---------- */
+
+static void timeout_callback(void *arg)
+{
+    micropython_vm_timeout_flag = 1;
+}
+
+/* ---------- Public API ---------- */
+
+esp_err_t micropython_vm_init(void)
+{
+    s_mutex = xSemaphoreCreateMutex();
+    if (!s_mutex) return ESP_ERR_NO_MEM;
+
+    esp_timer_create_args_t timer_args = {
+        .callback = timeout_callback,
+        .name = "upy_timeout",
+    };
+    esp_err_t err = esp_timer_create(&timer_args, &s_timeout_timer);
+    if (err != ESP_OK) {
+        vSemaphoreDelete(s_mutex);
+        s_mutex = NULL;
+        return err;
+    }
+
+    ESP_LOGI(TAG, "MicroPython VM ready (heap=%dKB, timeout=%dms)",
+             MIMI_MICROPYTHON_HEAP_SIZE / 1024, MIMI_MICROPYTHON_TIMEOUT_MS);
+    return ESP_OK;
+}
+
+esp_err_t micropython_vm_exec(const char *code, char *output, size_t output_size,
+                               int timeout_ms)
+{
+    if (!s_mutex || !code || !output || output_size == 0) {
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    /* Only one script at a time */
+    if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(1000)) != pdTRUE) {
+        snprintf(output, output_size, "Error: MicroPython VM is busy");
+        return ESP_ERR_TIMEOUT;
+    }
+
+    esp_err_t ret = ESP_OK;
+
+    /* Allocate GC heap from PSRAM */
+    void *gc_heap = heap_caps_calloc(1, MIMI_MICROPYTHON_HEAP_SIZE, MALLOC_CAP_SPIRAM);
+    if (!gc_heap) {
+        snprintf(output, output_size, "Error: failed to allocate MicroPython heap (%dKB)",
+                 MIMI_MICROPYTHON_HEAP_SIZE / 1024);
+        ret = ESP_ERR_NO_MEM;
+        goto unlock;
+    }
+
+    /* Setup stdout capture */
+    s_stdout_buf  = output;
+    s_stdout_pos  = 0;
+    s_stdout_size = output_size;
+    output[0]     = '\0';
+
+    /* Reset timeout flag */
+    micropython_vm_timeout_flag = 0;
+
+    /* Init interpreter — stack_top is the current stack pointer */
+    volatile int stack_var;
+    mp_embed_init(gc_heap, MIMI_MICROPYTHON_HEAP_SIZE, (void *)&stack_var);
+
+    /* Start timeout timer */
+    if (timeout_ms > 0) {
+        esp_timer_start_once(s_timeout_timer, (uint64_t)timeout_ms * 1000);
+    }
+
+    /* Execute — exceptions are printed to stdout via mp_hal_stdout_tx_strn */
+    mp_embed_exec_str(code);
+
+    /* Cancel timeout */
+    esp_timer_stop(s_timeout_timer);
+    micropython_vm_timeout_flag = 0;
+
+    /* Teardown interpreter */
+    mp_embed_deinit();
+
+    /* Free heap */
+    heap_caps_free(gc_heap);
+
+    /* Detach stdout capture */
+    s_stdout_buf  = NULL;
+    s_stdout_size = 0;
+
+    /* If no output was produced, say so */
+    if (s_stdout_pos == 0) {
+        snprintf(output, output_size, "(no output — use print() to see results)");
+    }
+
+    ESP_LOGI(TAG, "Python exec done (%d bytes output)", (int)s_stdout_pos);
+
+unlock:
+    xSemaphoreGive(s_mutex);
+    return ret;
+}