🌙 Luna - AI Desktop Assistant

Luna is a professional AI desktop assistant that runs as a background service, awakens on command (hotword or hotkey), and executes tasks intelligently using Large Action Models (LAM).

---

✨ Features

• 🎙️ Voice & Hotkey Activation - Wake Luna with "Luna" or Ctrl+Shift+L
• 🤖 LAM Integration - Powered by Claude (Anthropic) or GPT (OpenAI)
• 🛡️ Security First - Permission system with risk levels and confirmations
• 🎨 Beautiful UI - Smooth animations, dark/light themes
• 🔌 Extensible Actions - Web search, file operations, emails, system commands
• 📊 Structured Logging - Full audit trail with structlog
• ⚡ Low Resource Usage - <5% CPU when idle
• 🧪 Well Tested - >85% test coverage

---

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/yourusername/Python-Project-Luna.git
cd Python-Project-Luna

# Install
pip install -e .

# Configure
cp .env.example .env
# Edit .env with your Anthropic API key

# Verify setup
luna doctor

# Run Luna
luna run

See QUICKSTART.md for detailed setup instructions.

---

🏗️ Architecture

graph TB
    User((User))
    Wake[Wake Detection<br/>Hotword/Hotkey]
    Daemon[Background<br/>Daemon]
    UI[Overlay UI<br/>Qt/PySide6]
    LAM[LAM Client<br/>Anthropic/OpenAI]
    Registry[Action<br/>Registry]
    Actions[Actions<br/>Web/File/Email/OS]
    
    User -->|"Luna" / Hotkey| Wake
    Wake --> Daemon
    Daemon --> UI
    UI -->|User Command| LAM
    LAM -->|Tool Calls| Registry
    Registry --> Actions
    Actions -->|Results| UI
    UI --> User
    
    style User fill:#4a9eff
    style Wake fill:#f9a825
    style LAM fill:#7e57c2
    style Actions fill:#66bb6a

Loading

Project Structure

src/luna/
├── app.py              # Application orchestration
├── cli.py              # Command-line interface
├── config.py           # Configuration management
├── logging.py          # Structured logging
├── actions/            # Pluggable actions (15 total)
│   ├── registry.py     # Action registration & execution
│   ├── web_actions.py  # Web search, YouTube, Wikipedia
│   ├── file_actions.py # File operations
│   ├── email_actions.py # Email sending
│   └── os_actions.py   # System operations
├── lam_client/         # LAM integration
│   ├── client.py       # Provider-agnostic LAM client
│   ├── schema.py       # Tool/action schemas
│   └── memory.py       # Conversation memory
├── service/            # Background service
│   ├── daemon.py       # Daemon process
│   └── permissions.py  # Security & permissions
├── ui/                 # User interface
│   ├── overlay.py      # Main overlay window
│   └── theme.py        # Theming system
└── wake/               # Wake detection
    ├── hotword.py      # Hotword detection
    └── hotkey.py       # Hotkey detection

---

🎯 Usage

Basic Commands

# Run interactively (foreground with UI)
luna run

# Run as background daemon
luna daemon

# Summon overlay (if daemon running)
luna summon

# Test individual actions
luna test-action web_search query="Python tutorial"
luna test-action get_current_time

# List all available actions
luna test-action

# Check system health
luna doctor

# Show configuration
luna config --show

Available Actions

Action	Description	Permission	Risk
web_search	Search Google	Network	Safe
search_youtube	Search YouTube	Network	Safe
play_youtube	Play video/music	Network	Safe
wikipedia_summary	Get Wikipedia info	Network	Safe
open_url	Open URL in browser	Browser	Low
get_current_time	Get date/time	None	Safe
text_to_speech	Speak text aloud	None	Safe
open_file_explorer	Open file browser	File Read	Safe
list_directory	List directory	File Read	Safe
read_file	Read text file	File Read	Safe
create_file	Create file	File Write	Medium
delete_file	Delete file	File Delete	High
send_email	Send email	Email	High
execute_command	Run system command	System	Critical
get_system_info	Get system details	None	Safe

---

⚙️ Configuration

Create .env file from template:

cp .env.example .env

Key settings:

# LAM Provider (required for intelligent features)
LUNA_LAM_PROVIDER=anthropic
LUNA_LAM_API_KEY=sk-ant-your-api-key-here

# Wake Detection
LUNA_HOTKEY_COMBINATION=ctrl+shift+l
LUNA_HOTWORD_PHRASE=luna
LUNA_HOTWORD_ENABLED=true

# UI Settings
LUNA_UI_THEME=dark
LUNA_UI_ANIMATION_DURATION=300

# Permissions (adjust security level)
LUNA_ALLOW_FILE_WRITE=false
LUNA_ALLOW_FILE_DELETE=false
LUNA_ALLOW_SYSTEM_COMMANDS=false
LUNA_REQUIRE_CONFIRMATION_HIGH_RISK=true

# Email (optional)
LUNA_EMAIL_USERNAME=your-email@gmail.com
LUNA_EMAIL_PASSWORD=your-app-password

---

🔐 Security

Luna implements a comprehensive security model:

Risk Levels

• Safe - No confirmation (e.g., web search)
• Low - Logged (e.g., open URL)
• Medium - May require confirmation (e.g., create file)
• High - Always confirm (e.g., delete file)
• Critical - Confirm + audit (e.g., system commands)

Permissions

All actions require explicit permissions configurable in .env:

• FILE_READ, FILE_WRITE, FILE_DELETE
• NETWORK_REQUEST, SYSTEM_COMMAND
• EMAIL_SEND, BROWSER_CONTROL

Audit Trail

All high-risk actions logged to ~/.luna/logs/audit.log

---

🧪 Development

Setup Development Environment

# Clone and install with dev dependencies
git clone https://github.com/yourusername/Python-Project-Luna.git
cd Python-Project-Luna
pip install -e ".[dev]"

# Set up pre-commit hooks
pre-commit install

# Run tests
pytest --cov=luna

# Run quality checks
black src/ tests/
ruff check src/ tests/
mypy src/luna --strict

Adding New Actions

# src/luna/actions/my_actions.py
from luna.actions.registry import register_action
from luna.lam_client.schema import ToolParameter, ToolParameterType
from luna.service.permissions import Permission, RiskLevel

@register_action(
    name="my_action",
    description="Does something useful",
    parameters=[
        ToolParameter(
            name="input",
            type=ToolParameterType.STRING,
            description="Input parameter",
            required=True,
        )
    ],
    permission=Permission.NETWORK_REQUEST,
    risk_level=RiskLevel.SAFE,
)
def my_action(input: str) -> str:
    """Execute my custom action."""
    return f"Result: {input}"

Then test it:

luna test-action my_action input="test"

See CONTRIBUTING.md for full development guide.

---

📊 Performance

Metric	Target	Actual
Idle CPU	<5%	~2-3%
Idle Memory	<100MB	~80MB
Startup Time	<1s	~800ms
Wake Response	<500ms	~200ms
Overlay Render	<200ms	~150ms

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick checklist:

• Follow PEP 8 style guide
• Add type hints to all functions
• Write tests (maintain >85% coverage)
• Update documentation
• Run pre-commit checks

---

📝 Documentation

• QUICKSTART.md - 5-minute setup guide
• CONTRIBUTING.md - Development guide
• MIGRATION.md - Migration from v1.x details
• CHANGELOG.md - Version history

---

🐛 Troubleshooting

Common Issues

"Module not found" error:

pip install -e .

"API key not configured":

# Set in .env file
LUNA_LAM_API_KEY=sk-ant-your-key-here

Hotkey not working:

# May need elevated privileges on some systems
# Or use hotword instead by setting in .env:
LUNA_HOTKEY_ENABLED=false
LUNA_HOTWORD_ENABLED=true

Check logs:

cat ~/.luna/logs/luna.log

Run diagnostics:

luna doctor

---

🗺️ Roadmap

v2.1 (Next Release)

• System tray integration
• Voice responses (TTS for LAM)
• Custom action templates
• Plugin system
• Local LLM support (Ollama)

v2.2

• Multi-language support
• Calendar integration
• Note-taking features
• Spotlight-style launcher

---

📜 License

This project is licensed under the MIT License - see LICENSE for details.

---

🙏 Acknowledgments

• Anthropic for Claude API
• OpenAI for GPT API
• Qt/PySide6 for cross-platform UI
• Python community for amazing libraries

---

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with ❤️ by the Luna Team

⭐ Star us on GitHub if you find Luna useful!