Skip to content

sandy001-kki/ALOS

BranchesTags

Repository files navigation

ALOS

Advanced Local Operating System

ALOS v2 — Professional AI Desktop Assistant

Fully offline. Zero cloud. Zero API key. Zero subscription.

A production-quality personal AI assistant that runs 100% on your own machine — with a professional desktop GUI, local LLM inference, voice I/O, hardware control, and an extensible Skills ecosystem.

License: MIT Python 3.10+ PyQt6 Ollama Tests Platform Stars

Quick Start · Features · GUI · Skills · MCP · ESP32 · Roadmap

What is ALOS?

ALOS is an open-source personal AI platform that gives you the power of a large language model — with memory, tools, voice, and hardware control — without sending a single byte to the cloud.

You talk to ALOS in plain language. It understands your intent, routes to the right handler, calls tools or skills if needed, and responds. All computation runs on your own hardware, with SQLite persistence for every conversation, task, event, and health log you create.

Think of it as Claude Code + Claude Desktop — but fully local, fully open, and fully yours.

Why ALOS?

Problem with existing AI assistants How ALOS solves it
Data sent to cloud servers 100% local inference — nothing leaves your PC
Requires monthly API subscription Runs on free, open-weight Ollama models
Generic responses, no personal memory SQLite memory: conversations, tasks, events, health logs
No hardware integration ESP32 bridge: control relays, TFT display, touch UI
Closed extension ecosystem Open Skills system — write a tool in one Python file
No voice I/O faster-whisper STT + Windows SAPI / pyttsx3 TTS

Quick Start

Prerequisites

Requirement Version Install
Python 3.10+ python.org
Ollama latest ollama.ai
Git any git-scm.com

1 — Clone

git clone https://github.com/sandy001-kki/ALOS.git
cd ALOS

2 — Install dependencies

Windows:

setup.bat

Linux / macOS:

bash setup.sh

Or manually:

pip install -r requirements.txt

3 — Pull a model

# Start the Ollama server
ollama serve

# In another terminal, pull the default model
ollama pull llama3.2:1b

4 — Launch

# Full GUI — recommended
python gui_app.py

# Text-only terminal
python cli.py

# Voice — microphone + speaker
python voice_cli.py

Start here

If you are... Read this first Then do this
New to ALOS What is ALOS? Quick Start
A developer adding a skill Skills system Write your own skill
Connecting MCP servers MCP servers Add via config.json
Integrating ESP32 hardware ESP32 integration Hardware setup
A contributor Contributing Good first issues
Interested in ALOS-LM custom model FUTURE_PLAN.md Phase 3

Features

Core AI

  • Local LLM inference via Ollama — runs llama3.2, mistral, codellama, gemma, phi, and any compatible model
  • 8 specialized intent handlers — Chat, Schedule, Reminders, Health, Code, Smart Home, Day Planner, System
  • Conversation history with configurable depth (max_history in config)
  • Streaming response rendering in the GUI

Desktop GUI

  • Three-panel layout: navigation sidebar + chat panel + context panel
  • Dark professional theme — Claude Code-style design system
  • Intent badges on each message — shows which handler processed the request
  • Toolbar with model selector, screen monitor, hardware bridge, command palette
  • System tray icon — minimize to tray, morning briefing shortcut

Voice I/O

  • Speech-to-text using faster-whisper (runs locally, no API)
  • Text-to-speech using Windows SAPI (Windows) or pyttsx3 (Linux/macOS)
  • Voice tab in the input bar — push to talk

Memory and persistence

  • SQLite database with WAL mode — fast, reliable, crash-safe
  • 7 tables: sessions, conversations, tasks, schedule, health_log, memory, preferences
  • MemoryManager API — read/write from any handler or skill

Skills system

  • Modular Python plugins with a @tool decorator
  • SkillRegistry manages loading, enabling, and disabling at runtime
  • Built-in skills: Filesystem, PC Control, Web Search
  • Write a new skill in one file with no framework knowledge needed

MCP servers

  • Connects to any Model Context Protocol server
  • Supports both stdio (subprocess) and HTTP transports
  • GUI panel to add, connect, and disconnect servers at runtime
  • Tool results injected back into the LLM conversation automatically

Smart Home / ESP32

  • WebSocket server on port 8765 — ESP32 connects automatically
  • Control 4 relay channels from voice commands or the GUI
  • ILI9341 TFT display (320×240) running a 5-screen LVGL GUI
  • XPT2046 touchscreen for on-device navigation
  • Animated eyes — visual feedback when ALOS is listening or responding

Day Planner

  • Daily task management with priority levels
  • Morning briefing — summary of tasks, events, and health data
  • Proactive health check-ins — ALOS reminds you to drink water, take breaks

GUI overview

┌─────────────────────────────────────────────────────────────────┐
│  [Model: llama3.2:1b ▼] [◫ Screen] [⬡ Bridge] [⌘ Palette] [◀] │
├──────────┬──────────────────────────────────────┬───────────────┤
│ Sidebar  │           Chat Panel                 │ Context Panel │
│          │                                      │               │
│ ◈ Chat   │  ALOS  [schedule]  10:32            │  TASKS        │
│ ☑ Planner│  ┌──────────────────────────────┐   │  ⚑ Fix bug   │
│ ♥ Health │  │ Good morning Sandy! Today     │   │  · Review PR │
│ ⌂ Smart  │  │ you have 3 tasks and 1 event. │   │               │
│   Home   │  └──────────────────────────────┘   │  TODAY'S EVENTS│
│ ⚙ Skills │                                      │  10:00 Standup│
│ ⬡ MCP    │  You  ──────────────────────  09:01 │               │
│ ⊛ Settings│  ┌──────────────────────────────┐  │  HARDWARE     │
│          │  │ What should I focus on today? │  │  ● connected  │
│          │  └──────────────────────────────┘  │  Relay 1: ON  │
│  ● Ollama│                                      │  Relay 2: OFF │
│  online  ├──────────────────────────────────────┤               │
│          │ [Chat] [Voice] [Code]  Tools: Skills ▸│               │
│          │ Ask ALOS anything…     (Enter to send)│               │
└──────────┴──────────────────────────────────────┴───────────────┘

Keyboard shortcuts

Shortcut Action
Ctrl+P Open Command Palette
Ctrl+L Clear chat
Ctrl+, Open Settings
Enter Send message
Shift+Enter New line in input

Architecture overview

flowchart TD
    A["User Input\n(text / voice)"] --> B["IntentDetector\n8-class classifier"]
    B --> C["Router"]

    C --> D1["ChatHandler"]
    C --> D2["ScheduleHandler"]
    C --> D3["HealthHandler"]
    C --> D4["CodeHandler"]
    C --> D5["SmartHomeHandler"]
    C --> D6["PlannerHandler"]
    C --> D7["ReminderHandler"]
    C --> D8["SystemHandler"]

    D1 & D2 & D3 & D4 & D6 & D7 --> E["ALOSEngine\nOllama LLM"]

    E --> F["SkillRegistry\nFilesystem · PCControl · WebSearch"]
    E --> G["MCPRegistry\nstdio · HTTP servers"]

    F & G --> E

    D5 --> H["HardwareBridge\nWebSocket :8765"]
    H --> I["ESP32\nRelays · TFT · Touch"]

    E --> J["MemoryManager\nSQLite WAL"]
    E --> K["ChatPanel\nResponse rendering"]
Loading

Configuration

Edit config.json to change model, voice, skills, hardware, and MCP settings:

{
  "ai": {
    "model": "llama3.2:1b",
    "ollama_host": "http://localhost:11434",
    "max_history": 20
  },
  "voice": {
    "whisper_model": "base",
    "tts_rate": 175
  },
  "hardware": {
    "enabled": false,
    "websocket_port": 8765,
    "esp32_ip": "192.168.1.100"
  },
  "skills": {
    "filesystem": false,
    "pc_control": false,
    "web_search": false
  },
  "mcp_servers": [
    {
      "name": "filesystem",
      "type": "stdio",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "D:\\"]
    }
  ]
}

Available Ollama models

ollama pull llama3.2:1b      # fast, 1B — default
ollama pull llama3.2:3b      # better quality
ollama pull mistral           # great for code
ollama pull codellama         # specialized for code
ollama pull phi3              # Microsoft, very fast
ollama pull gemma2:2b         # Google, efficient

What ALOS understands

ALOS classifies every message into one of 8 intents automatically. No special syntax needed.

Intent Example phrases
chat "Hello", "What's machine learning?", "Tell me a joke"
schedule "Schedule dentist on Friday at 3pm", "What do I have today?"
reminder "Remind me to call mom at 5pm", "Set a reminder in 30 minutes"
health "I drank 2 glasses of water", "I feel tired", "Log my mood as 7"
planner "Add task: finish report", "Show my tasks", "Morning briefing"
code "Write a Python function to sort a list", "Debug this error"
smart_home "Turn on the lights", "Turn off the fan", "Switch on AC"
system_command "/status", "/clear", "Switch model to mistral", "Clear history"

Skills system

The Skills system allows ALOS to call Python tool functions at runtime. Each skill is an independent Python module — no framework boilerplate required.

Built-in skills

Skill Tools available Default
Filesystem read_file, list_directory, find_files, write_file Off
PC Control set_volume, open_app, lock_screen, media_play, media_pause Off
Web Search search_web, open_url, get_page_content Off

Enable via GUI

  1. Click ⚙ Skills in the sidebar
  2. Toggle a skill ON or OFF
  3. Tools from that skill become available to the LLM immediately — no restart needed

Write your own skill

Create a single file in core/skills/:

# core/skills/weather_skill.py
from core.skills.base_skill import BaseSkill, tool

class WeatherSkill(BaseSkill):
    name        = "weather"
    description = "Get current weather and forecasts"
    version     = "1.0.0"

    @tool("Get current weather for a city")
    def get_weather(self, city: str) -> str:
        # Your implementation here
        return f"Fetching weather for {city}..."

    @tool("Get 7-day forecast for a city")
    def get_forecast(self, city: str, days: int = 7) -> str:
        return f"Fetching {days}-day forecast for {city}..."

Then register it:

# core/skills/builtin.py → register_all()
from core.skills.weather_skill import WeatherSkill
registry.register(WeatherSkill())

MCP servers

ALOS supports Model Context Protocol — the open standard from Anthropic for connecting AI models to external tools and data sources.

Any MCP-compatible server can be wired into ALOS, and its tools are exposed to the LLM alongside built-in Skills.

Add via GUI

  1. Click ⬡ MCP Servers in the sidebar
  2. Click + Add Server
  3. Enter server name, transport type (stdio or http), and command or URL
  4. Click Connect

Add via config.json

"mcp_servers": [
  {
    "name": "filesystem",
    "type": "stdio",
    "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home"]
  },
  {
    "name": "github",
    "type": "stdio",
    "command": ["npx", "-y", "@modelcontextprotocol/server-github"]
  },
  {
    "name": "remote-tools",
    "type": "http",
    "url": "http://localhost:3001"
  }
]

Popular MCP servers

# Filesystem access
npx -y @modelcontextprotocol/server-filesystem /your/path

# Git operations
uvx mcp-server-git

# GitHub integration
npx -y @modelcontextprotocol/server-github

# Web browser automation
npx -y @modelcontextprotocol/server-puppeteer

ESP32 hardware integration

ALOS controls physical hardware via an ESP32 microcontroller over a WebSocket connection. The firmware runs a fully interactive 5-screen LVGL GUI on a TFT touchscreen display.

Hardware components

Component Specification
Microcontroller ESP32 (any variant)
Display ILI9341 TFT — 320×240 pixels
Touch XPT2046 resistive touchscreen
Relay outputs 4 channels — lights, fan, AC, heater
Communication WebSocket over WiFi
Firmware framework Arduino + LVGL

LVGL display screens

  1. Home — relay status overview
  2. Controls — tap to toggle relays
  3. Status — ALOS connection status and IP
  4. Eyes — animated ALOS face (listening indicator)
  5. Sensors — temperature and humidity (with DHT22)

Hardware setup

  1. Open esp32/alos_firmware/config.h and set your WiFi credentials
  2. Flash esp32/alos_firmware/alos_firmware.ino via Arduino IDE
  3. In ALOS GUI, click ⬡ Bridge in the toolbar to start the WebSocket server
  4. ESP32 connects to ws://<PC_IP>:8765 automatically on boot

Voice commands for hardware control

"Turn on the lights"      → Relay 1 ON
"Turn off the lights"     → Relay 1 OFF
"Turn on the fan"         → Relay 2 ON
"Switch on AC"            → Relay 3 ON
"Turn off the heater"     → Relay 4 OFF
"What is the temperature" → Reads DHT22 sensor value

Project structure

ALOS/
├── gui_app.py                  # GUI entry point
├── cli.py                      # CLI entry point
├── voice_cli.py                # Voice CLI entry point
├── config.json                 # All user configuration
├── requirements.txt            # Python dependencies
│
├── core/
│   ├── engine.py               # ALOSEngine — Ollama LLM wrapper
│   ├── intent_detector.py      # 8-category intent classifier
│   ├── router.py               # Message routing to handlers
│   ├── planner.py              # Day planner + health check-ins
│   ├── handlers/
│   │   ├── chat_handler.py
│   │   ├── schedule_handler.py
│   │   ├── reminder_handler.py
│   │   ├── health_handler.py
│   │   ├── code_handler.py
│   │   ├── planner_handler.py
│   │   ├── smart_home_handler.py
│   │   └── system_handler.py
│   ├── skills/
│   │   ├── base_skill.py       # BaseSkill + @tool decorator
│   │   ├── skill_registry.py   # SkillRegistry
│   │   ├── builtin.py          # Built-in skill registration
│   │   ├── filesystem_skill.py
│   │   ├── pc_control_skill.py
│   │   └── web_search_skill.py
│   └── mcp/
│       ├── client.py           # MCP client (stdio + HTTP)
│       └── registry.py         # MCPRegistry
│
├── gui/
│   ├── main_window.py          # 3-panel main window
│   ├── sidebar.py              # Navigation sidebar
│   ├── chat_panel.py           # Message bubbles + intent badges
│   ├── input_bar.py            # Chat/Voice/Code tabs + skill chips
│   ├── context_panel.py        # Tasks, events, hardware status
│   ├── command_palette.py      # Ctrl+P command overlay
│   ├── skills_panel.py         # Skills browser dialog
│   ├── mcp_panel.py            # MCP servers manager dialog
│   ├── toast_manager.py        # Floating notification toasts
│   ├── settings_dialog.py      # Settings dialog
│   ├── tray_icon.py            # System tray icon
│   └── styles.py               # Design system — colors, QSS stylesheet
│
├── database/
│   ├── schema.py               # SQLite schema — 7 tables
│   └── manager.py              # MemoryManager API
│
├── hardware_bridge/
│   ├── server.py               # WebSocket server — port 8765
│   └── protocol.py             # JSON message protocol
│
├── esp32/
│   └── alos_firmware/
│       ├── alos_firmware.ino   # Main Arduino sketch
│       ├── lvgl_ui.h           # 5-screen LVGL GUI
│       ├── animated_eyes.h     # Animated eye renderer
│       └── config.h            # WiFi credentials + pin config
│
└── tests/
    ├── test_week1.py           # Engine + Ollama integration (requires Ollama)
    ├── test_week2.py           # STT/TTS integration (requires Ollama)
    ├── test_week4.py           # Router + intent detection
    ├── test_week5.py           # Handlers
    ├── test_week8.py           # Skills + MCP
    └── test_week9.py           # ESP32 firmware + hardware bridge (28 tests)

Running tests

# Full test suite
python -m pytest tests/ -v

# Quick check — no Ollama or hardware required
python -m pytest tests/test_week4.py tests/test_week5.py tests/test_week8.py tests/test_week9.py -q

# ESP32 and hardware tests only
python -m pytest tests/test_week9.py -v

# With coverage
python -m pytest tests/ --cov=core --cov-report=term-missing

Note: test_week1.py and test_week2.py require Ollama running (ollama serve). All 161 other tests run without any external services.

Release packages

Download a release — easiest path

  1. Go to the Releases page
  2. Download the latest ALOS-vX.X.X-windows.zip
  3. Extract and run ALOS.exe

Releases bundle Ollama — no separate install needed.

Build from source — Windows

pip install pyinstaller

pyinstaller \
  --noconfirm \
  --onedir \
  --windowed \
  --name ALOS \
  --add-data "config.json;." \
  --add-data "core;core" \
  --add-data "gui;gui" \
  --add-data "database;database" \
  gui_app.py

# Output in dist/ALOS/

Build from source — Linux / macOS

pip install pyinstaller

pyinstaller \
  --noconfirm \
  --onedir \
  --windowed \
  --name ALOS \
  --add-data "config.json:." \
  gui_app.py

Troubleshooting

Ollama is not running

ollama serve
ollama pull llama3.2:1b

"No module named PyQt6"

pip install PyQt6

Voice input not working

pip install faster-whisper sounddevice soundfile

TTS silent on Windows ALOS uses PowerShell System.Speech for reliable Windows TTS — no extra install needed. If silent, check that your Windows audio output is not muted.

ESP32 not connecting

  • Verify hardware.esp32_ip in config.json matches your ESP32's IP address
  • Ensure your PC firewall allows inbound connections on port 8765
  • Check config.h in the firmware has the correct WiFi SSID and password
  • Use the LVGL Status screen on the TFT to see the IP the ESP32 received

GUI layout broken on high-DPI display

# Set this environment variable before launching
QT_AUTO_SCREEN_SCALE_FACTOR=1 python gui_app.py

Contributing

ALOS is fully open to contributions from developers, researchers, hardware enthusiasts, and AI practitioners.

Whether you are adding a new skill, building a connector (Gmail, Calendar, Notion), improving a handler, fixing a bug, or writing documentation — all pull requests are welcome and reviewed promptly.

How to contribute

  1. Fork the repository on GitHub

  2. Create a feature branch

    git checkout -b feature/my-feature

  3. Make your changes and run the tests

    python -m pytest tests/ -q

  4. Push and open a pull request with a clear title and description

Good first issues

  • Add a new built-in skill — Calendar sync, Notes, Clipboard manager, Timer
  • Improve intent detection accuracy with better keyword patterns or a small classifier
  • Build a connector skill — Gmail, Google Calendar, Slack, Notion
  • Write additional tests for edge cases in handlers
  • Improve ESP32 firmware — DHT22 integration, BLE proximity, IR blaster
  • Add Linux and macOS compatibility fixes
  • Improve accessibility — keyboard navigation, screen reader support

Contribution areas

Area What to build
Skills Gmail, Google Calendar, Slack, Notion, Spotify, WhatsApp integrations
Handlers Finance tracker, News reader, Weather, Travel planner
GUI Dark/light theme toggle, chat history browser, plugin marketplace
Multi-modal Image input, PDF reading, clipboard watcher, screenshot analysis
ESP32 DHT22 sensor, IR blaster, BLE proximity, multi-node room control
Model Help build ALOS-LM — the custom LLM to replace Ollama (see FUTURE_PLAN.md)

Roadmap

ALOS is actively developed. See FUTURE_PLAN.md for the complete vision.

Phase 2 — Platform Expansion Adding connectors (Gmail, Google Calendar, Slack, Notion, GitHub), advanced GUI features (dark/light theme, plugin marketplace), multi-modal input (images, PDFs, screenshots), and additional ESP32 hardware support.

Phase 3 — ALOS-LM Custom Language Model Building a purpose-trained Transformer decoder model (1B → 3B → 7B parameters) to replace Ollama entirely. The model will be trained specifically for ALOS tasks — scheduling, health, code, smart home, and conversation — with DPO alignment, native tool-call output, and GGUF quantization for CPU inference. Open weights will be published on Hugging Face.

Phase 4 — ALOS as a Platform ALOS Cloud, ALOS Hub (community skills marketplace), ALOS Mobile (Flutter, on-device 1B inference), ALOS API (REST), multi-agent coordination, and a vector memory graph.

License

MIT License — see LICENSE.

Developer

Sandeep Kumar Bollavaram

B.Tech Computer Science & Engineering · SCSVMV University, Kanchipuram · Batch 2028

Building at the intersection of AI, robotics, and the web.

Portfolio GitHub LinkedIn

Open to internships, research collaborations, and project partnerships.

ALOS — Fully offline. Fully open. Fully yours.

In one sentence: ALOS lets you describe what you need in plain language and have a local AI assistant continuously understand, act, and remember — without sending a single byte to the cloud.

About

Fully offline personal AI assistant — local LLM, voice I/O, PyQt6 GUI, ESP32 hardware, Skills system, MCP servers. No API key. No cloud.

sandeepkumarbollavaram.in

Topics

python open-source ai mcp esp32 personal-assistant voice-assistant pyqt6 llm local-ai ollama offline-ai

Resources

Readme

License

MIT license
Activity

Stars

4 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

ALOS v2.0.0 — Advanced Local Operating System Latest
Apr 16, 2026

Packages

 
 
 

Contributors

Languages