embodi-os 0.2.0
AI-powered operating system with natural language interface
License: MIT
Requires Python: >=3.8

# EMBODIOS - Embodied Intelligence Operating System

## Overview

So, I've been working on this interesting project - EMBODIOS. It's basically an operating system, but with a twist. Instead of typing cryptic commands or dealing with complex system calls, you just... talk to it. Well, type to it, actually. The whole thing runs on language models that handle the kernel operations. Pretty neat way to control hardware when you think about it.

Quick heads up: When I say "conversational", I mean text-based conversations. The system reads what you type, not what you say out loud. Though if you're curious about voice stuff, there's a demo in the docs that shows how you could add that.

```bash
> Turn on GPIO pin 17
AI: Executing hardware control...
[HARDWARE] GPIO Pin 17 -> HIGH

> Show system status
AI: System Status Report
[SYSTEM] Memory: 1.2GB allocated
[SYSTEM] Uptime: 2m 34s
[SYSTEM] Hardware: GPIO, UART, Timers active
```

## Quick Start

### Install EMBODIOS CLI

```bash
# Install from source
git clone https://github.com/dddimcha/embodiOS.git
cd embodiOS
pip install -e .
```

### Try It Out

```bash
# Create a Modelfile
cat > Modelfile << EOF
FROM scratch
MODEL huggingface:TinyLlama/TinyLlama-1.1B-Chat-v1.0
QUANTIZE 4bit
MEMORY 2G
HARDWARE gpio:enabled
EOF

# Build EMBODIOS image
embodi build -f Modelfile -t my-ai-os:latest

# Run it!
embodi run my-ai-os:latest

# Or run a model directly (no container)
embodi run test-model.aios --bare-metal

# Create bootable bundle for real hardware
embodi bundle create --model my-ai-os:latest --output embodios.iso --target bare-metal
```

## Key Features

- **Natural Language Control**: Type commands in plain English - "turn on pin 17" instead of `gpio.write(17, HIGH)`
- **AI-Powered Kernel**: Language models handle system operations, memory management, and hardware control
- **Bare Metal Performance**: Direct hardware access with <2ms response times
- **Minimal Footprint**: Entire OS in ~16MB RAM (vs 100MB+ for traditional deployments)
- **Hardware Abstraction**: Unified interface for GPIO, I2C, SPI, UART through natural language
- **Docker-like Workflow**: Build, run, and deploy AI-OS images with familiar commands
- **Real-time Processing**: 465+ commands/second throughput on commodity hardware

## Documentation

- [Getting Started](docs/getting-started.md)
- [Modelfile Reference](docs/modelfile-reference.md)
- [Hardware Compatibility](docs/hardware.md)
- [API Documentation](docs/api.md)
- [Performance Benchmarks](docs/performance-benchmarks.md)
- [Bare Metal Deployment](docs/bare-metal-deployment.md)
- [Contributing Guide](CONTRIBUTING.md)

## Use Cases

### Embedded Systems
```dockerfile
FROM scratch
MODEL huggingface:microsoft/phi-2
QUANTIZE 4bit
MEMORY 1G
HARDWARE gpio:enabled uart:enabled
```

### Robotics
```yaml
name: robot-embodi
model:
  source: huggingface
  name: microsoft/Phi-3-mini-4k-instruct
capabilities:
  - motion_control
  - sensor_fusion
  - path_planning
```

### Smart Home
```dockerfile
FROM scratch
MODEL huggingface:TinyLlama/TinyLlama-1.1B-Chat-v1.0
CAPABILITY home_automation voice_control
HARDWARE wifi:enabled zigbee:enabled
```

## How It Works

The basic flow is simple: you type something, the language model figures out what you want, and then it talks directly to the hardware. No complicated APIs or system calls in between. The model processes your text and converts it into hardware instructions through memory-mapped I/O.

```
User Input (Natural Language)
        ↓
┌─────────────────┐
│  NL Processor   │  ← Pattern matching &
│                 │     intent extraction
└────────┬────────┘
         ↓
┌─────────────────┐
│  AI Inference   │  ← Transformer Model
│     Engine      │     with hardware tokens
└────────┬────────┘
         ↓
┌─────────────────┐
│ Hardware Layer  │  ← Direct hardware
│      (HAL)      │     control via MMIO
└─────────────────┘
```

### Core Components

- **Natural Language Processor**: Translates commands like "turn on the LED" into hardware operations
- **Inference Engine**: Runs transformer models with special hardware control tokens
- **Hardware Abstraction Layer**: Provides unified interface to GPIO, I2C, SPI, UART
- **Runtime Kernel**: Manages system state, interrupts, and background services

## Why EMBODIOS?

Here's the thing - traditional operating systems have layers upon layers of abstractions. System calls, drivers, APIs, frameworks... it all adds up. EMBODIOS cuts through all that overhead.

**The benefits are pretty straightforward:**

- **Speed**: Direct hardware access means no kernel/userspace context switches. We're talking microseconds, not milliseconds.
- **Resource Efficiency**: No background services, no daemons, no unnecessary processes. Just your model and the hardware. Perfect when every MB counts.
- **Bare Metal Access**: Your commands go straight to the metal. No translation layers, no permission checks, no virtualization overhead.
- **IoT Ready**: Built specifically for embedded devices where traditional OSes are too heavy. Runs great on a Raspberry Pi or even smaller boards.
- **Cloud Cost Savings**: Why pay for cloud compute when your edge device can handle everything locally? No API calls, no bandwidth costs, no latency.

Think about it - a typical Linux distro needs hundreds of MB just for the base system. EMBODIOS? The whole OS *is* the model. That's it. Your 1GB model handles everything from memory management to GPIO control.

For IoT developers tired of stripping down Linux distributions, or anyone who wants their devices to actually understand what they're being asked to do - this might be worth a look.

## Contributing

If you want to help out or have ideas, that's awesome. Check the contributing guide for the details.

```bash
# Clone the repository
git clone https://github.com/dddimcha/embodiOS.git
cd core

# Install dependencies
make deps

# Run tests
make test

# Build EMBODIOS
make build
```

## Performance

Latest benchmark results show significant improvements over traditional deployments:

- **Boot Time**: <1 second to fully operational state
- **Memory Usage**: 16.3MB (vs 108.5MB for traditional model servers)
- **Response Time**: 1.3ms average (40.7x faster than traditional)
- **Throughput**: 465 commands/second (vs 16/sec traditional)
- **Token Processing**: 154 tokens/second with TinyLlama

See [full benchmark results](docs/performance-benchmarks.md) for detailed comparisons.

## Community

- [Discord Server](https://discord.gg/xRsYfcdP)

## License

EMBODIOS is open source software licensed under the [MIT License](LICENSE).

## Acknowledgments

This project pulls ideas from various places - Linux kernels, Docker's approach to containers, modern language models, and embedded systems. Just another unconventional approach to OS design that might interest someone out there.

---

**EMBODIOS** - An experimental OS where you can control hardware through everyday language