Rust Core Engine
The execution engine is implemented entirely in Rust using the bollard Docker client library and tokio async runtime. Each execution creates a fresh Docker container with a specified base image for the target programming language. The container is configured with a HostConfig that enforces memory limits through cgroups, CPU quotas through nano_cpus, and network isolation by setting network mode to none. The filesystem is mounted as read-only except for a size-limited tmpfs at /tmp. All Linux capabilities are dropped for the container process. The Rust code spawns the container, attaches to its output streams, waits for completion with a configurable timeout, captures all stdout and stderr output, retrieves the exit code, and finally removes the container. All of this happens asynchronously using tokio, allowing for proper timeout handling and cancellation. The Rust core exposes a simple synchronous interface to Python through PyO3, hiding all the async complexity behind a blocking facade.
Python Orchestration
The Python layer implements the high-level self-healing loop. The main YuuBox class accepts code and language parameters, then enters an iteration loop that can run up to five times. In each iteration, it calls the Rust executor through PyO3, receives back the execution result with exit code and output streams, and checks for success. On failure, it invokes the ErrorAnalyzer to parse the stderr output and extract structured error information. The analyzer has language-specific parsers for Python tracebacks, JavaScript error stacks, and Rust compiler messages. The structured error is then passed to the YuukiHealer, which constructs a context-aware prompt that includes the current code, the error details, and a summary of previous attempts. The healer calls the Yuuki API, parses the response to extract corrected code, and returns it to the main loop. The loop updates the current code and begins the next iteration. This continues until either the code succeeds, five iterations complete, or the healer fails to generate a fix.
Language Support
YuuBox supports five major programming languages with dedicated Docker images and execution strategies. Python code executes using the python:3.11-slim image with the command python -c followed by the code string. JavaScript runs on node:20-slim using node -e. Rust compilation and execution happens in rust:1.75-slim using a shell script that writes the code to a temporary file, invokes rustc to compile it, then runs the resulting binary. Go uses golang:1.21-alpine with a similar pattern of writing to a temp file and running with go run. Java support uses openjdk:17-slim with javac compilation followed by java execution. Each language has a corresponding error parser in the analyzer that understands that language's error message format and can extract meaningful structured information from stack traces and compiler output.
Resource Limits
Every container execution is subject to strict resource limits configured through Docker's HostConfig. Memory limits are specified in bytes and enforced by Linux cgroups, with a default of 256MB. CPU quotas are specified as a fraction of one core converted to nano_cpus for Docker, with a default allowing full use of one core. Execution timeouts are enforced using tokio's timeout future wrapper, with a default of 60 seconds. On timeout, the Rust code sends a kill signal to the container and proceeds with cleanup. Disk space is limited by mounting the root filesystem as read-only and providing only a size-limited tmpfs at /tmp with a default of 100MB. Network access is controlled by the network mode setting, defaulting to disabled which prevents all network communication. These limits can be customized per execution through the ResourceLimits dataclass passed from Python.
|
Error Analysis
The ErrorAnalyzer class provides sophisticated parsing of execution errors across multiple programming languages. For Python, it searches stderr for the Traceback marker, extracts all lines from there to the end, parses the final line to separate error type from message using a regex pattern, and searches the traceback for line number references. For JavaScript, it looks for patterns like SyntaxError: or TypeError: and extracts the error class and message. For Rust, it detects compiler error patterns like error[E0308]: and extracts the compiler's message. All analyzers produce a standardized error dictionary containing type, message, optional line number, and the full stack trace. This structured representation allows the healer to construct precise prompts that guide Yuuki toward relevant fixes.
Yuuki Integration
Integration with the Yuuki AI platform happens through the YuukiHealer class, which manages HTTP communication with the HuggingFace Spaces API endpoint. The healer constructs prompts by combining the failing code wrapped in markdown code fences, the error type and message, optional line number information, and a summary of how many previous attempts have been made. The prompt explicitly instructs Yuuki to provide only the corrected code without explanations, which simplifies parsing. The healer makes a POST request to the generate endpoint with parameters including the prompt, a max token count of 1000, a low temperature of 0.3 for more deterministic debugging output, and the yuuki-best model identifier. Response parsing handles multiple formats that the API might return, extracting text from string responses or dictionary fields like generated_text or response. The healer strips markdown code fences and cleans conversational artifacts like "User:" or "System:" markers that sometimes appear in responses.
CLI Interface
The command-line interface is built with Click for command parsing and Rich for beautiful terminal output. The main command yuubox run accepts a file path and automatically detects the programming language from the file extension. Optional flags control the maximum iteration count, disable healing for single-shot execution, set timeout and memory limits, and explicitly specify the language. When execution begins, Rich displays a spinner with status text. Progress updates show which iteration is running. On success, a green checkmark appears with the iteration count and any stdout output. On failure after all iterations, a red X shows with the final error message truncated to 500 characters. The entire experience is designed to feel responsive and informative without overwhelming the user with technical details about Docker or Rust internals.
HTTP API
The FastAPI server provides HTTP access to YuuBox functionality for integration with web applications and automated systems. The main endpoint accepts POST requests at /execute with a JSON body containing code, language, and optional parameters for max iterations, timeout, memory limit, and healing control. The server creates a YuuBox instance, calls its execute method with the provided parameters, and returns a JSON response with success status, stdout and stderr output, the number of iterations used, and total execution time. A health check endpoint at /health returns a simple status message for monitoring and load balancer health checks. The API is fully documented with automatic OpenAPI schema generation from FastAPI, accessible at the /docs endpoint when the server is running.
Security Model
Security is enforced through multiple layers of isolation. Docker containers provide process-level isolation with separate PID namespaces preventing container processes from seeing or interacting with host processes. The network is disabled by default, eliminating data exfiltration and external command-and-control risks. The filesystem is read-only except for a size-limited temporary directory, preventing persistence of malicious code or data. Containers run as a non-root user with UID 1000, removing privilege escalation vectors. All Linux capabilities are explicitly dropped, disabling operations like loading kernel modules or modifying system time. Resource limits prevent resource exhaustion attacks like fork bombs or memory allocation attacks. Execution timeouts prevent infinite loops or deliberate hanging. After each execution, the container is unconditionally removed, ensuring no state persists between runs. The Rust implementation provides additional safety through compile-time memory safety checks and absence of data races.
|
