caelum-sys


Namecaelum-sys JSON
Version 0.4.0 PyPI version JSON
download
home_pageNone
SummaryAI-enhanced system automation toolkit with HIGH-PERFORMANCE vision - 135+ commands, MSS/OpenCV/Tesseract integration, OpenAI/Anthropic/Ollama support
upload_time2025-08-03 13:04:10
maintainerNone
docs_urlNone
authorJoshua Wells
requires_python>=3.9
licenseNone
keywords automation system scripting ai natural-language openai anthropic ollama local-models assistant agent chatbot
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # CaelumSys 🚀 AI-Enhanced System Automation with **135+ specialized plugins** and a powerful AI integration framework supporting **OpenAI, Anthropic, and local models like Ollama**.

> 🚀 **NEW in v0.4.0**: **BUILT-IN HIGH-PERFORMANCE VISION!** MSS, OpenCV, and Tesseract are now integrated directly - no separate installation needed!

> ⚡ **BREAKTHROUGH**: **3-4x faster screen capture**, **enhanced template matching**, and **OCR text extraction** built into every installation!

> đŸ‘ī¸ **GAMING-READY**: AI agents can now monitor screens at **160+ FPS** and detect changes in **real-time** for competitive gaming applications!

![PyPI](https://img.shields.io/pypi/v/caelum-sys)
![Python Version](https://img.shields.io/pypi/pyversions/caelum-sys)
![Wheel](https://img.shields.io/pypi/wheel/caelum-sys)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![Downloads](https://img.shields.io/pypi/dm/caelum-sys)

**CaelumSys** is the ultimate AI-enhanced system automation toolkit that transforms natural language commands into system actions. Build intelligent assistants, chatbots, and automation agents with **135+ specialized plugins** and a powerful AI integration framework supporting **OpenAI, Anthropic, and local models like Ollama**.

## 📈 Roadmap

**v0.4.0 (Current - JUST RELEASED!) ✅**
- 🚀 **BUILT-IN HIGH-PERFORMANCE VISION**: MSS, OpenCV, Tesseract integrated directly
- ⚡ **3-4x faster screen capture** with MSS (no separate installation)
- đŸŽ¯ **Enhanced template matching** with OpenCV for superior accuracy
- 📖 **Built-in OCR text extraction** with Tesseract
- 🎮 **Gaming-level performance**: 160+ FPS pixel monitoring
- 📊 **Performance benchmarking tools** built-in
- 🤖 Full AI agent integration (OpenAI, Anthropic, Ollama)
- 🏠 Local model support (Ollama) - No API keys needed!
- đŸ›Ąī¸ Advanced safety and permission systems
- 🔧 Enhanced function schema generation
- 📚 Comprehensive AI integration documentation

**v0.3.x (Previous) ✅**
- Basic system automation commands
- Plugin architecture foundation
- Command-line interface
- File management operations

**v0.5.0 (Planned)**
- 📡 REST API server mode
- 🔧 Plugin management CLI
- 🌐 Web dashboard interface
- 🛒 Plugin marketplace

**v1.0.0 (Future)**
- đŸŽ¯ Stable API guarantee
- 🔒 Advanced security features
- đŸĸ Enterprise integrations
- 📊 Analytics and monitoring

---

**CaelumSys** is the ultimate AI-enhanced system automation toolkit that transforms natural language commands into system actions. Build intelligent assistants, chatbots, and automation agents with **135+ specialized plugins** and a powerful AI integration framework supporting **OpenAI, Anthropic, and local models like Ollama**.

> 🚀 **NEW in v0.4.0**: **BUILT-IN HIGH-PERFORMANCE VISION!** MSS, OpenCV, and Tesseract are now integrated directly - no separate installation needed!

> ⚡ **BREAKTHROUGH**: **3-4x faster screen capture**, **enhanced template matching**, and **OCR text extraction** built into every installation!

> đŸ‘ī¸ **GAMING-READY**: AI agents can now monitor screens at **160+ FPS** and detect changes in **real-time** for competitive gaming applications!

---

## 🤖 AI Agent Quick Start

Create a powerful AI assistant with system automation in just one line:

```python
import os
from caelum_sys import create_openai_agent

# Create an AI assistant with full system capabilities
agent = create_openai_agent(os.getenv("OPENAI_API_KEY"))

# Start chatting!
**That's it!** Your AI assistant can now:
- 📁 Manage files and directories
- 🌐 Make network requests and web searches  
- 📊 Monitor system performance
- đŸŽĩ Control media playback
- 📸 **Capture screenshots at HIGH-SPEED (MSS - 3x faster)**
- đŸ‘ī¸ **Watch your screen in real-time at 160+ FPS**
- đŸ–ąī¸ **Control mouse clicks and movements**
- âŒ¨ī¸ **Type text and press keyboard shortcuts**
- đŸŽ¯ **Find and click on images/UI elements (OpenCV enhanced)**
- 📖 **Read any text from screen using OCR (Tesseract)**
- 🧮 Perform calculations
- ⏰ Handle date/time operations
- 🔧 Execute Git operations
- And 135+ more system tasks!

---

## 🌟 Key Features

- **🤖 AI-First Design**: Built for OpenAI, Anthropic, and local models (Ollama)
- **đŸ‘ī¸ Vision Capabilities**: AI agents can see and analyze screen content
- **đŸ–ąī¸ Input Control**: Complete mouse and keyboard automation
- **đŸŽ¯ Smart Interactions**: Find and click on UI elements automatically  
- **đŸ—Ŗī¸ Natural Language Interface**: `do("get current time")` instead of complex APIs
- **🔌 Plugin Architecture**: 135+ specialized plugins covering daily automation needs  
- **đŸ›Ąī¸ Safety Classifications**: Commands marked safe/unsafe for AI agent integration
- **💰 Cost-Effective**: Use free local models or premium cloud APIs
- **🚀 One-Line Setup**: Create AI assistants instantly with minimal code
- **⚡ Zero Configuration**: Works immediately after `pip install caelum-sys`
- **đŸŽ¯ 135+ Commands**: Comprehensive coverage from file operations to UI automation
- **🔧 Extensible**: Create custom plugins in just 10-15 lines of code
- **🌐 Cross-Platform**: Windows-focused with macOS/Linux compatibility
- **🔄 Async Support**: Built for real-time AI applications

---

## đŸ“Ļ Installation

### Basic Installation
```bash
pip install caelum-sys
```
*✨ **High-Performance Vision included!** MSS, OpenCV, and Tesseract are automatically installed - no extra setup needed!*

### With AI Capabilities
```bash
# For OpenAI integration (GPT-4, etc.)
pip install caelum-sys[openai]

# For Anthropic integration (Claude)  
pip install caelum-sys[anthropic]

# For all AI features
pip install caelum-sys[ai]

# For local Ollama (no extra dependencies needed!)
pip install caelum-sys
# Then: ollama serve && ollama pull llama3.1
```

> **Note**: The base installation includes all system automation and high-performance vision features. AI provider packages are only needed for cloud-based AI integration.

---

## ⚡ High-Performance Vision (NEW in v0.4.0!)

CaelumSys now includes **built-in high-performance vision backends** - no separate installation needed:

### 🚀 **3-4x Faster Screen Capture with MSS**
```python
do("take screenshot")  # Now uses MSS automatically - 3x faster!
do("take screenshot of region 100 100 500 300")  # 4x faster for regions!
```

### đŸŽ¯ **Enhanced Image Recognition with OpenCV**
```python
do("find image on screen button.png")  # OpenCV provides superior accuracy
```

### 📖 **Built-in OCR Text Extraction**
```python
do("read text from screen region 500 50 800 100")  # Extract any screen text
# Returns: "Health: 100/100  Mana: 50/75"
```

### 🎮 **Gaming-Level Performance**
```python
do("high speed pixel monitor 500 300 for 10 seconds")  # 160+ FPS monitoring
do("performance benchmark screen capture")  # See the speed difference
```

**Performance Improvements:**
- **Full Screen Capture:** MSS is 1.3x faster than PyAutoGUI
- **Region Capture:** MSS is 4.4x faster than PyAutoGUI  
- **Gaming Monitoring:** Sustained 160+ FPS pixel monitoring
- **Template Matching:** OpenCV provides enhanced accuracy and reliability

---

## 🚀 Quick Examples

### Local AI with Ollama (No API Keys!)
```python
from caelum_sys import create_ollama_agent

# Create a local AI assistant - completely free!
agent = create_ollama_agent("llama3.1")  # or "codellama", "mistral", etc.

# Start chatting with your local AI
response = await agent.chat("What's the current time and show me system info?")
print(response)  # Your local AI executes commands and responds naturally
```

### AI with Vision & Control (NEW!)
```python
from caelum_sys import create_ollama_agent

# Create an AI that can see and control your desktop!
agent = create_ollama_agent(
    model="llama3.1",
    system_prompt="You can see the user's screen and control their mouse/keyboard. Help them with desktop tasks!"
)

# Your AI can now see and interact!
response = await agent.chat("Take a screenshot and tell me what's on my screen, then click the start button")
print(response)  # AI analyzes your screen and performs actions!
```

### Traditional Usage
```python
from caelum_sys import do

# System Information
do("get current time")           # ⏰ Current time: 2025-08-02 15:30:45
do("get system info")            # đŸ–Ĩī¸ System Info: Windows 11, Intel i7...

# File Operations
do("create file at test.txt")    # 📄 File created: test.txt
do("list files in .")           # 📁 Files: [file1.txt, file2.py, ...]

# Network & Web
do("ping google.com")           # 🌐 Ping: google.com is reachable
do("get weather for Tokyo")     # â˜€ī¸ Tokyo: 25°C, Sunny
```

### AI Agent Examples

#### OpenAI Assistant (GPT-4)
```python
import asyncio
from caelum_sys import create_openai_agent

async def main():
    agent = create_openai_agent(
        api_key="your-openai-key",
        name="System Admin Assistant"
    )
    
    # Natural conversation with system capabilities
    response = await agent.chat("Can you check the current time, create a backup folder, and show me disk usage?")
    print(response)

asyncio.run(main())
```

#### Discord Bot with CaelumSys
```python
import discord
from caelum_sys import create_openai_agent

class SystemBot(discord.Client):
    async def on_ready(self):
        self.agent = create_openai_agent("your-openai-key")
    
    async def on_message(self, message):
        if message.content.startswith('!system'):
            query = message.content[8:]
            response = await self.agent.chat(query)
            await message.channel.send(response)
```

#### Ollama Local AI (Free!)
```python
import asyncio
from caelum_sys import create_ollama_agent

async def main():
    # Use local models - no API costs!
    agent = create_ollama_agent(
        model="llama3.1",  # or "codellama", "mistral", "phi3", etc.
        name="Local System Admin"
    )
    
    # Natural conversation with your local AI
    response = await agent.chat("Can you check disk usage, create a backup folder called 'daily_backup', and show me running processes?")
    print(response)

asyncio.run(main())
```

#### Discord Bot with Local AI
```python
import discord
from caelum_sys import create_ollama_agent

class LocalSystemBot(discord.Client):
    async def on_ready(self):
        # No API key needed - use local Ollama
        self.agent = create_ollama_agent("llama3.1")
    
    async def on_message(self, message):
        if message.content.startswith('!local'):
            query = message.content[7:]
            response = await self.agent.chat(query)
            await message.channel.send(response)
```

#### Custom Agent Configuration
```python
from caelum_sys import CaelumAgent, AgentConfig
from caelum_sys.ai_agent import OpenAIProvider, OllamaProvider

# OpenAI Configuration
config = AgentConfig(
    name="DevOps Assistant",
    system_prompt="You are a DevOps expert with system automation capabilities...",
    safety_mode=True,
    max_tokens=2000,
    temperature=0.3
)

provider = OpenAIProvider("your-key", model="gpt-4")
agent = CaelumAgent(config, provider)

# Or use local Ollama (no API key needed)
local_provider = OllamaProvider("codellama")  # Great for development tasks
local_agent = CaelumAgent(config, local_provider)
```
do("get cpu usage")              # đŸ’ģ CPU usage: 12.5%

# File Operations  
do("create file at report.txt")  # ✅ Created file at: report.txt
do("check if file exists data.json")  # ✅ File exists: data.json
do("get file size setup.py")     # 📏 File size: 1401 bytes (1.4 KB)

# Web & Network
do("check website status github.com")  # ✅ https://github.com is accessible (Status: 200)
do("get my public ip")           # 🌐 Public IP address: 203.0.113.42
do("get weather for London")     # đŸŒ¤ī¸ Weather for London: ⛅ 18°C

# Text & Data Processing
do("encode base64 Hello World")  # 🔐 Encoded: SGVsbG8gV29ybGQ=
do("hash text with md5 secret")  # 🔒 MD5 hash: 5ebe2294ecd0e0f08eab7690d2a6ee69
do("generate uuid")              # 🆔 Generated UUID: 550e8400-e29b-41d4-a716...

# Productivity
do("add note Meeting at 3pm")    # 📝 Note saved with ID: 1
do("copy text to clipboard")     # 📋 Text copied to clipboard
do("calculate 15% of 240")       # 🧮 15% of 240 = 36.0

# Git Integration (for developers)
do("git status")                 # 📊 Git status: 3 modified files
do("git add all files")          # ✅ Added all files to staging
```

### Command Line Interface
```bash
# Get help and discover commands
caelum-sys "help"
caelum-sys "list safe commands"
caelum-sys "search commands for file"

# Execute commands
caelum-sys "get system info"
caelum-sys "take screenshot"
caelum-sys "check website status example.com"
```

---

## 📂 Plugin Categories

### đŸ‘ī¸ **Screen Watching** (9 commands) - NEW!
AI agents can see and analyze screen content in real-time.
```python
do("take screenshot")                          # Capture full screen
do("take screenshot of region 0 0 500 300")   # Capture specific area
do("analyze screen content")                   # AI visual analysis
do("find image on screen button.png")         # Locate UI elements
do("monitor screen changes for 10 seconds")   # Watch for changes
```

### đŸ–ąī¸ **Input Control** (15 commands) - NEW!
Complete mouse and keyboard automation for AI agents.
```python
do("click at 250 150")                    # Click at coordinates
do("type text Hello World")              # Type text naturally
do("press keys ctrl+c")                  # Keyboard shortcuts
do("drag from 100 100 to 200 200")      # Drag operations
do("click on image button.png")         # Smart UI clicking
```

### đŸ—‚ī¸ **File Management** (8 commands)
Complete file system operations with safety checks.
```python
do("create folder Projects/my-app")      # Create directories
do("copy file data.txt to backup.txt")  # Copy operations  
do("move file temp.log to archive/")    # Move operations
do("delete file old-data.csv")          # Safe deletion
```

### 🌐 **Web & APIs** (7 commands)  
Internet connectivity and web service integration.
```python
do("check website status api.example.com")  # HTTP status checking
do("download file from https://...")        # File downloads
do("shorten url https://very-long-url...")  # URL shortening
do("get page title from news.ycombinator.com")  # Web scraping
```

### 📋 **Text & Clipboard** (8 commands)
Text manipulation and clipboard integration.
```python
do("copy text to clipboard")        # Clipboard operations
do("get clipboard content")         # Retrieve clipboard
do("uppercase text hello world")    # Text transformations
do("count words in text")          # Text analysis
```

### đŸ”ĸ **Math & Calculations** (7 commands)
Safe mathematical operations and unit conversions.
```python
do("calculate 15% of 240")                    # Percentage calculations
do("convert 100 fahrenheit to celsius")       # Temperature conversion
do("calculate tip 45.50 at 18 percent")      # Financial calculations
do("generate random number between 1 and 100")  # Random generation
```

### 📅 **Date & Time** (8 commands)
Temporal operations with timezone support.
```python
do("get current timestamp")              # Unix timestamps
do("add 5 days to today")               # Date arithmetic
do("what time is it in Tokyo")          # Timezone conversion
do("how many days until 2025-12-25")    # Date calculations
```

### 📝 **Quick Notes** (8 commands)
Persistent note management with JSON storage.
```python
do("save note Meeting with client tomorrow")  # Create notes
do("list all notes")                         # List notes
do("search notes for meeting")               # Search functionality
do("get note 1")                            # Retrieve specific notes
```

### 📊 **Git Integration** (12 commands)
Version control operations for developers.
```python
do("git status")                    # Repository status
do("git add all files")             # Stage changes
do("git commit with message Fix bug") # Commit changes
do("list git branches")             # Branch management
```

### â„šī¸ **File Information** (7 commands)
Detailed file inspection and metadata.
```python
do("get file info document.pdf")              # Complete file details
do("get file hash important.zip")             # File integrity
do("find files with extension .py in src/")   # File discovery
do("count lines in file script.py")           # File analysis
```

### đŸ–Ĩī¸ **System Utilities** (15+ commands)
System monitoring and control operations.
```python
do("get memory usage")           # Resource monitoring
do("list running processes")     # Process management  
do("take screenshot")           # Screen capture
do("open task manager")         # System tools
```

### 🔍 **Help & Discovery** (4 commands)
Built-in documentation and command discovery.
```python
do("help")                           # Complete command list
do("search commands for network")    # Find relevant commands
do("list safe commands")             # LLM-safe operations
do("list unsafe commands")           # Commands requiring permission
```

### 🤖 **AI Assistant Generator** (3 commands) - NEW!
Create personalized AI development assistants with custom capabilities.
```python
do("setup dev assistant")                    # Interactive setup wizard
do("setup dev assistant quick MyBot ollama") # Quick setup with defaults
do("list dev assistant templates")           # Show available templates
do("setup dev assistant template fullstack openai") # Use pre-configured template
```

---

## 🤖 AI Agent Integration

CaelumSys provides the most advanced AI agent capabilities with **vision and control** integration:

### đŸ‘ī¸ Vision-Enabled Commands (9 total) ✅
AI agents can **see and analyze** your screen:
```python
do("take screenshot")           # ✅ Safe - capture screen
do("analyze screen content")    # ✅ Safe - visual analysis  
do("find image on screen")      # ✅ Safe - locate UI elements
do("get pixel color at 100 100") # ✅ Safe - color detection
```

### đŸ–ąī¸ Input Control Commands (15 total) âš ī¸
AI agents can **control mouse and keyboard** (requires permission):
```python
do("click at 250 150")          # âš ī¸ Controlled - mouse clicking
do("type text Hello")           # âš ī¸ Controlled - keyboard input
do("press keys ctrl+c")         # âš ī¸ Controlled - shortcuts
do("drag from 100 100 to 200 200") # âš ī¸ Controlled - drag operations
```

### Safe Commands (111 total) ✅
Commands that **read information** without modifying system state:
```python
do("get current time")        # ✅ Safe - information retrieval
do("check website status")    # ✅ Safe - network checking  
do("get file size setup.py")  # ✅ Safe - file inspection
do("list running processes")  # ✅ Safe - system monitoring
```

### Unsafe Commands (24 total) âš ī¸
Commands that **modify system state** and require explicit permission:
```python
do("delete file config.txt")  # âš ī¸ Unsafe - file deletion
do("kill process chrome")     # âš ī¸ Unsafe - process termination
do("empty recycle bin")       # âš ī¸ Unsafe - system cleanup
do("git commit with message") # âš ī¸ Unsafe - repository changes
```

**Query commands by safety:** 
- `do("list safe commands")` - Shows read-only operations
- `do("list unsafe commands")` - Shows system-modifying operations

### đŸŽ¯ Revolutionary Use Cases

**🎮 Gaming Automation:**
```python
# AI can watch game screens and react
agent.chat("Watch for the enemy and click to attack when you see red")
```

**đŸ’ŧ Productivity Automation:**
```python  
# AI can read and interact with any application
agent.chat("Read my emails and draft replies to the important ones")
```

**🔧 Smart Testing:**
```python
# AI can perform visual UI testing
agent.chat("Click through the app workflow and report any visual bugs")
```

---

## đŸ› ī¸ Creating Custom Plugins

Extend CaelumSys with custom functionality:

```python
# caelum_sys/plugins/my_plugin.py
from caelum_sys.registry import register_command

@register_command("greet {name}", safe=True)
def greet_person(name: str):
    """Greet someone by name."""
    return f"👋 Hello, {name}! Welcome to CaelumSys!"

@register_command("backup database", safe=False)  
def backup_database():
    """Backup the application database."""
    # Implementation here
    return "💾 Database backup completed successfully"
```

**Plugin features:**
- ✅ **Auto-discovery**: Just add `.py` files to `caelum_sys/plugins/`
- ✅ **Parameter extraction**: `{name}` automatically becomes function parameter
- ✅ **Safety classification**: Mark commands as safe/unsafe for AI agents
- ✅ **Error handling**: Built-in exception handling and user-friendly messages

---

## đŸ› ī¸ Development

```bash
# Install development dependencies
pip install -e ".[dev]"

# Format code
black caelum_sys/
isort caelum_sys/

# Type checking (optional)
mypy caelum_sys/

# Build package
python -m build
```

**Project Structure:**
```
caelum_sys/
├── plugins/           # Plugin modules (25+ plugins with 135+ commands)
├── core_actions.py    # Main execution engine
├── registry.py        # Command registration system
├── cli.py            # Command-line interface
└── __init__.py       # Package interface
```

---

## 📋 Requirements

- **Python**: 3.9+ (tested on 3.9, 3.10, 3.11, 3.12, 3.13)
- **Operating System**: Windows (primary), macOS, Linux
- **Dependencies**: Automatically installed with package
  
### Core Dependencies
  - `psutil` - System monitoring and process management
  - `requests` - Web operations and HTTP requests
  - `pyperclip` - Clipboard integration
  - `pytz` - Timezone support and conversions
  - `python-dateutil` - Advanced date parsing and manipulation
  - `pyautogui` - Basic screen capture and input control
  - `pillow` - Image processing and manipulation

### High-Performance Vision (NEW in v0.4.0!)
  - `mss>=9.0.1` - Ultra-fast screen capture (3-4x faster than PyAutoGUI)
  - `opencv-python>=4.8.0` - Advanced computer vision and template matching
  - `pytesseract>=0.3.10` - OCR text extraction from screen regions
  - `numpy>=1.24.0` - Numerical operations for image processing

### Optional AI Dependencies
  - `openai` - For GPT-4, GPT-3.5-turbo integration (install with `pip install caelum-sys[openai]`)
  - `anthropic` - For Claude 3.5 Sonnet, Claude 3 integration (install with `pip install caelum-sys[anthropic]`)
  - **Ollama** - Local AI models (no extra Python dependencies - just install Ollama separately)

---

## 🤝 Contributing

We welcome contributions! Here's how to get started:

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-plugin`
3. **Add your plugin** to `caelum_sys/plugins/`
4. **Test your functionality** with the CLI or programmatic interface
5. **Submit a pull request**

**Contribution Ideas:**
- 🔌 New plugins (email, database, cloud services)
- 📚 Documentation improvements
- 🔧 Performance optimizations
- 🐛 Bug fixes and optimizations
- 🌍 Cross-platform compatibility

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## 🔗 Links

- **PyPI Package**: https://pypi.org/project/caelum-sys/
- **GitHub Repository**: https://github.com/BlackBeardJW/caelum-sys
- **Issue Tracker**: https://github.com/BlackBeardJW/caelum-sys/issues
- **Documentation**: Coming soon!

---

## 📈 Roadmap

## 📈 Roadmap

**v0.4.0 (Current - COMPLETE!) ✅**
- 🚀 **BUILT-IN HIGH-PERFORMANCE VISION**: MSS, OpenCV, Tesseract integrated directly
- ⚡ **3-4x faster screen capture** with MSS (no separate installation)
- đŸŽ¯ **Enhanced template matching** with OpenCV for superior accuracy
- 📖 **Built-in OCR text extraction** with Tesseract
- 🎮 **Gaming-level performance**: 160+ FPS pixel monitoring
- 📊 **Performance benchmarking tools** built-in
- 🤖 Full AI agent integration (OpenAI, Anthropic, Ollama)
- 🏠 Local model support (Ollama) - No API keys needed!
- đŸ›Ąī¸ Advanced safety and permission systems
- 🔧 Enhanced function schema generation
- 📚 Comprehensive AI integration documentation

**v0.5.0 (Planned)**
- 📡 REST API server mode
- 🔧 Plugin management CLI
- 🌐 Web dashboard interface
- 🛒 Plugin marketplace

**v1.0.0 (Future)**
- đŸŽ¯ Stable API guarantee
- 🔒 Advanced security features
- đŸĸ Enterprise integrations
- 📊 Analytics and monitoring

---

<div align="center">

**Made with â¤ī¸ by Joshua Wells**

⭐ **Star this repo** if you find CaelumSys useful!

</div>

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "caelum-sys",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "automation, system, scripting, ai, natural-language, openai, anthropic, ollama, local-models, assistant, agent, chatbot",
    "author": "Joshua Wells",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/c4/24/19f3bbb3a62047b87cc4b03f8300bb1111ec3dead517e5562a12e4aadc79/caelum_sys-0.4.0.tar.gz",
    "platform": null,
    "description": "# CaelumSys \ud83d\ude80 AI-Enhanced System Automation with **135+ specialized plugins** and a powerful AI integration framework supporting **OpenAI, Anthropic, and local models like Ollama**.\n\n> \ud83d\ude80 **NEW in v0.4.0**: **BUILT-IN HIGH-PERFORMANCE VISION!** MSS, OpenCV, and Tesseract are now integrated directly - no separate installation needed!\n\n> \u26a1 **BREAKTHROUGH**: **3-4x faster screen capture**, **enhanced template matching**, and **OCR text extraction** built into every installation!\n\n> \ud83d\udc41\ufe0f **GAMING-READY**: AI agents can now monitor screens at **160+ FPS** and detect changes in **real-time** for competitive gaming applications!\n\n![PyPI](https://img.shields.io/pypi/v/caelum-sys)\n![Python Version](https://img.shields.io/pypi/pyversions/caelum-sys)\n![Wheel](https://img.shields.io/pypi/wheel/caelum-sys)\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![Downloads](https://img.shields.io/pypi/dm/caelum-sys)\n\n**CaelumSys** is the ultimate AI-enhanced system automation toolkit that transforms natural language commands into system actions. Build intelligent assistants, chatbots, and automation agents with **135+ specialized plugins** and a powerful AI integration framework supporting **OpenAI, Anthropic, and local models like Ollama**.\n\n## \ud83d\udcc8 Roadmap\n\n**v0.4.0 (Current - JUST RELEASED!) \u2705**\n- \ud83d\ude80 **BUILT-IN HIGH-PERFORMANCE VISION**: MSS, OpenCV, Tesseract integrated directly\n- \u26a1 **3-4x faster screen capture** with MSS (no separate installation)\n- \ud83c\udfaf **Enhanced template matching** with OpenCV for superior accuracy\n- \ud83d\udcd6 **Built-in OCR text extraction** with Tesseract\n- \ud83c\udfae **Gaming-level performance**: 160+ FPS pixel monitoring\n- \ud83d\udcca **Performance benchmarking tools** built-in\n- \ud83e\udd16 Full AI agent integration (OpenAI, Anthropic, Ollama)\n- \ud83c\udfe0 Local model support (Ollama) - No API keys needed!\n- \ud83d\udee1\ufe0f Advanced safety and permission systems\n- \ud83d\udd27 Enhanced function schema generation\n- \ud83d\udcda Comprehensive AI integration documentation\n\n**v0.3.x (Previous) \u2705**\n- Basic system automation commands\n- Plugin architecture foundation\n- Command-line interface\n- File management operations\n\n**v0.5.0 (Planned)**\n- \ud83d\udce1 REST API server mode\n- \ud83d\udd27 Plugin management CLI\n- \ud83c\udf10 Web dashboard interface\n- \ud83d\uded2 Plugin marketplace\n\n**v1.0.0 (Future)**\n- \ud83c\udfaf Stable API guarantee\n- \ud83d\udd12 Advanced security features\n- \ud83c\udfe2 Enterprise integrations\n- \ud83d\udcca Analytics and monitoring\n\n---\n\n**CaelumSys** is the ultimate AI-enhanced system automation toolkit that transforms natural language commands into system actions. Build intelligent assistants, chatbots, and automation agents with **135+ specialized plugins** and a powerful AI integration framework supporting **OpenAI, Anthropic, and local models like Ollama**.\n\n> \ud83d\ude80 **NEW in v0.4.0**: **BUILT-IN HIGH-PERFORMANCE VISION!** MSS, OpenCV, and Tesseract are now integrated directly - no separate installation needed!\n\n> \u26a1 **BREAKTHROUGH**: **3-4x faster screen capture**, **enhanced template matching**, and **OCR text extraction** built into every installation!\n\n> \ud83d\udc41\ufe0f **GAMING-READY**: AI agents can now monitor screens at **160+ FPS** and detect changes in **real-time** for competitive gaming applications!\n\n---\n\n## \ud83e\udd16 AI Agent Quick Start\n\nCreate a powerful AI assistant with system automation in just one line:\n\n```python\nimport os\nfrom caelum_sys import create_openai_agent\n\n# Create an AI assistant with full system capabilities\nagent = create_openai_agent(os.getenv(\"OPENAI_API_KEY\"))\n\n# Start chatting!\n**That's it!** Your AI assistant can now:\n- \ud83d\udcc1 Manage files and directories\n- \ud83c\udf10 Make network requests and web searches  \n- \ud83d\udcca Monitor system performance\n- \ud83c\udfb5 Control media playback\n- \ud83d\udcf8 **Capture screenshots at HIGH-SPEED (MSS - 3x faster)**\n- \ud83d\udc41\ufe0f **Watch your screen in real-time at 160+ FPS**\n- \ud83d\uddb1\ufe0f **Control mouse clicks and movements**\n- \u2328\ufe0f **Type text and press keyboard shortcuts**\n- \ud83c\udfaf **Find and click on images/UI elements (OpenCV enhanced)**\n- \ud83d\udcd6 **Read any text from screen using OCR (Tesseract)**\n- \ud83e\uddee Perform calculations\n- \u23f0 Handle date/time operations\n- \ud83d\udd27 Execute Git operations\n- And 135+ more system tasks!\n\n---\n\n## \ud83c\udf1f Key Features\n\n- **\ud83e\udd16 AI-First Design**: Built for OpenAI, Anthropic, and local models (Ollama)\n- **\ud83d\udc41\ufe0f Vision Capabilities**: AI agents can see and analyze screen content\n- **\ud83d\uddb1\ufe0f Input Control**: Complete mouse and keyboard automation\n- **\ud83c\udfaf Smart Interactions**: Find and click on UI elements automatically  \n- **\ud83d\udde3\ufe0f Natural Language Interface**: `do(\"get current time\")` instead of complex APIs\n- **\ud83d\udd0c Plugin Architecture**: 135+ specialized plugins covering daily automation needs  \n- **\ud83d\udee1\ufe0f Safety Classifications**: Commands marked safe/unsafe for AI agent integration\n- **\ud83d\udcb0 Cost-Effective**: Use free local models or premium cloud APIs\n- **\ud83d\ude80 One-Line Setup**: Create AI assistants instantly with minimal code\n- **\u26a1 Zero Configuration**: Works immediately after `pip install caelum-sys`\n- **\ud83c\udfaf 135+ Commands**: Comprehensive coverage from file operations to UI automation\n- **\ud83d\udd27 Extensible**: Create custom plugins in just 10-15 lines of code\n- **\ud83c\udf10 Cross-Platform**: Windows-focused with macOS/Linux compatibility\n- **\ud83d\udd04 Async Support**: Built for real-time AI applications\n\n---\n\n## \ud83d\udce6 Installation\n\n### Basic Installation\n```bash\npip install caelum-sys\n```\n*\u2728 **High-Performance Vision included!** MSS, OpenCV, and Tesseract are automatically installed - no extra setup needed!*\n\n### With AI Capabilities\n```bash\n# For OpenAI integration (GPT-4, etc.)\npip install caelum-sys[openai]\n\n# For Anthropic integration (Claude)  \npip install caelum-sys[anthropic]\n\n# For all AI features\npip install caelum-sys[ai]\n\n# For local Ollama (no extra dependencies needed!)\npip install caelum-sys\n# Then: ollama serve && ollama pull llama3.1\n```\n\n> **Note**: The base installation includes all system automation and high-performance vision features. AI provider packages are only needed for cloud-based AI integration.\n\n---\n\n## \u26a1 High-Performance Vision (NEW in v0.4.0!)\n\nCaelumSys now includes **built-in high-performance vision backends** - no separate installation needed:\n\n### \ud83d\ude80 **3-4x Faster Screen Capture with MSS**\n```python\ndo(\"take screenshot\")  # Now uses MSS automatically - 3x faster!\ndo(\"take screenshot of region 100 100 500 300\")  # 4x faster for regions!\n```\n\n### \ud83c\udfaf **Enhanced Image Recognition with OpenCV**\n```python\ndo(\"find image on screen button.png\")  # OpenCV provides superior accuracy\n```\n\n### \ud83d\udcd6 **Built-in OCR Text Extraction**\n```python\ndo(\"read text from screen region 500 50 800 100\")  # Extract any screen text\n# Returns: \"Health: 100/100  Mana: 50/75\"\n```\n\n### \ud83c\udfae **Gaming-Level Performance**\n```python\ndo(\"high speed pixel monitor 500 300 for 10 seconds\")  # 160+ FPS monitoring\ndo(\"performance benchmark screen capture\")  # See the speed difference\n```\n\n**Performance Improvements:**\n- **Full Screen Capture:** MSS is 1.3x faster than PyAutoGUI\n- **Region Capture:** MSS is 4.4x faster than PyAutoGUI  \n- **Gaming Monitoring:** Sustained 160+ FPS pixel monitoring\n- **Template Matching:** OpenCV provides enhanced accuracy and reliability\n\n---\n\n## \ud83d\ude80 Quick Examples\n\n### Local AI with Ollama (No API Keys!)\n```python\nfrom caelum_sys import create_ollama_agent\n\n# Create a local AI assistant - completely free!\nagent = create_ollama_agent(\"llama3.1\")  # or \"codellama\", \"mistral\", etc.\n\n# Start chatting with your local AI\nresponse = await agent.chat(\"What's the current time and show me system info?\")\nprint(response)  # Your local AI executes commands and responds naturally\n```\n\n### AI with Vision & Control (NEW!)\n```python\nfrom caelum_sys import create_ollama_agent\n\n# Create an AI that can see and control your desktop!\nagent = create_ollama_agent(\n    model=\"llama3.1\",\n    system_prompt=\"You can see the user's screen and control their mouse/keyboard. Help them with desktop tasks!\"\n)\n\n# Your AI can now see and interact!\nresponse = await agent.chat(\"Take a screenshot and tell me what's on my screen, then click the start button\")\nprint(response)  # AI analyzes your screen and performs actions!\n```\n\n### Traditional Usage\n```python\nfrom caelum_sys import do\n\n# System Information\ndo(\"get current time\")           # \u23f0 Current time: 2025-08-02 15:30:45\ndo(\"get system info\")            # \ud83d\udda5\ufe0f System Info: Windows 11, Intel i7...\n\n# File Operations\ndo(\"create file at test.txt\")    # \ud83d\udcc4 File created: test.txt\ndo(\"list files in .\")           # \ud83d\udcc1 Files: [file1.txt, file2.py, ...]\n\n# Network & Web\ndo(\"ping google.com\")           # \ud83c\udf10 Ping: google.com is reachable\ndo(\"get weather for Tokyo\")     # \u2600\ufe0f Tokyo: 25\u00b0C, Sunny\n```\n\n### AI Agent Examples\n\n#### OpenAI Assistant (GPT-4)\n```python\nimport asyncio\nfrom caelum_sys import create_openai_agent\n\nasync def main():\n    agent = create_openai_agent(\n        api_key=\"your-openai-key\",\n        name=\"System Admin Assistant\"\n    )\n    \n    # Natural conversation with system capabilities\n    response = await agent.chat(\"Can you check the current time, create a backup folder, and show me disk usage?\")\n    print(response)\n\nasyncio.run(main())\n```\n\n#### Discord Bot with CaelumSys\n```python\nimport discord\nfrom caelum_sys import create_openai_agent\n\nclass SystemBot(discord.Client):\n    async def on_ready(self):\n        self.agent = create_openai_agent(\"your-openai-key\")\n    \n    async def on_message(self, message):\n        if message.content.startswith('!system'):\n            query = message.content[8:]\n            response = await self.agent.chat(query)\n            await message.channel.send(response)\n```\n\n#### Ollama Local AI (Free!)\n```python\nimport asyncio\nfrom caelum_sys import create_ollama_agent\n\nasync def main():\n    # Use local models - no API costs!\n    agent = create_ollama_agent(\n        model=\"llama3.1\",  # or \"codellama\", \"mistral\", \"phi3\", etc.\n        name=\"Local System Admin\"\n    )\n    \n    # Natural conversation with your local AI\n    response = await agent.chat(\"Can you check disk usage, create a backup folder called 'daily_backup', and show me running processes?\")\n    print(response)\n\nasyncio.run(main())\n```\n\n#### Discord Bot with Local AI\n```python\nimport discord\nfrom caelum_sys import create_ollama_agent\n\nclass LocalSystemBot(discord.Client):\n    async def on_ready(self):\n        # No API key needed - use local Ollama\n        self.agent = create_ollama_agent(\"llama3.1\")\n    \n    async def on_message(self, message):\n        if message.content.startswith('!local'):\n            query = message.content[7:]\n            response = await self.agent.chat(query)\n            await message.channel.send(response)\n```\n\n#### Custom Agent Configuration\n```python\nfrom caelum_sys import CaelumAgent, AgentConfig\nfrom caelum_sys.ai_agent import OpenAIProvider, OllamaProvider\n\n# OpenAI Configuration\nconfig = AgentConfig(\n    name=\"DevOps Assistant\",\n    system_prompt=\"You are a DevOps expert with system automation capabilities...\",\n    safety_mode=True,\n    max_tokens=2000,\n    temperature=0.3\n)\n\nprovider = OpenAIProvider(\"your-key\", model=\"gpt-4\")\nagent = CaelumAgent(config, provider)\n\n# Or use local Ollama (no API key needed)\nlocal_provider = OllamaProvider(\"codellama\")  # Great for development tasks\nlocal_agent = CaelumAgent(config, local_provider)\n```\ndo(\"get cpu usage\")              # \ud83d\udcbb CPU usage: 12.5%\n\n# File Operations  \ndo(\"create file at report.txt\")  # \u2705 Created file at: report.txt\ndo(\"check if file exists data.json\")  # \u2705 File exists: data.json\ndo(\"get file size setup.py\")     # \ud83d\udccf File size: 1401 bytes (1.4 KB)\n\n# Web & Network\ndo(\"check website status github.com\")  # \u2705 https://github.com is accessible (Status: 200)\ndo(\"get my public ip\")           # \ud83c\udf10 Public IP address: 203.0.113.42\ndo(\"get weather for London\")     # \ud83c\udf24\ufe0f Weather for London: \u26c5 18\u00b0C\n\n# Text & Data Processing\ndo(\"encode base64 Hello World\")  # \ud83d\udd10 Encoded: SGVsbG8gV29ybGQ=\ndo(\"hash text with md5 secret\")  # \ud83d\udd12 MD5 hash: 5ebe2294ecd0e0f08eab7690d2a6ee69\ndo(\"generate uuid\")              # \ud83c\udd94 Generated UUID: 550e8400-e29b-41d4-a716...\n\n# Productivity\ndo(\"add note Meeting at 3pm\")    # \ud83d\udcdd Note saved with ID: 1\ndo(\"copy text to clipboard\")     # \ud83d\udccb Text copied to clipboard\ndo(\"calculate 15% of 240\")       # \ud83e\uddee 15% of 240 = 36.0\n\n# Git Integration (for developers)\ndo(\"git status\")                 # \ud83d\udcca Git status: 3 modified files\ndo(\"git add all files\")          # \u2705 Added all files to staging\n```\n\n### Command Line Interface\n```bash\n# Get help and discover commands\ncaelum-sys \"help\"\ncaelum-sys \"list safe commands\"\ncaelum-sys \"search commands for file\"\n\n# Execute commands\ncaelum-sys \"get system info\"\ncaelum-sys \"take screenshot\"\ncaelum-sys \"check website status example.com\"\n```\n\n---\n\n## \ud83d\udcc2 Plugin Categories\n\n### \ud83d\udc41\ufe0f **Screen Watching** (9 commands) - NEW!\nAI agents can see and analyze screen content in real-time.\n```python\ndo(\"take screenshot\")                          # Capture full screen\ndo(\"take screenshot of region 0 0 500 300\")   # Capture specific area\ndo(\"analyze screen content\")                   # AI visual analysis\ndo(\"find image on screen button.png\")         # Locate UI elements\ndo(\"monitor screen changes for 10 seconds\")   # Watch for changes\n```\n\n### \ud83d\uddb1\ufe0f **Input Control** (15 commands) - NEW!\nComplete mouse and keyboard automation for AI agents.\n```python\ndo(\"click at 250 150\")                    # Click at coordinates\ndo(\"type text Hello World\")              # Type text naturally\ndo(\"press keys ctrl+c\")                  # Keyboard shortcuts\ndo(\"drag from 100 100 to 200 200\")      # Drag operations\ndo(\"click on image button.png\")         # Smart UI clicking\n```\n\n### \ud83d\uddc2\ufe0f **File Management** (8 commands)\nComplete file system operations with safety checks.\n```python\ndo(\"create folder Projects/my-app\")      # Create directories\ndo(\"copy file data.txt to backup.txt\")  # Copy operations  \ndo(\"move file temp.log to archive/\")    # Move operations\ndo(\"delete file old-data.csv\")          # Safe deletion\n```\n\n### \ud83c\udf10 **Web & APIs** (7 commands)  \nInternet connectivity and web service integration.\n```python\ndo(\"check website status api.example.com\")  # HTTP status checking\ndo(\"download file from https://...\")        # File downloads\ndo(\"shorten url https://very-long-url...\")  # URL shortening\ndo(\"get page title from news.ycombinator.com\")  # Web scraping\n```\n\n### \ud83d\udccb **Text & Clipboard** (8 commands)\nText manipulation and clipboard integration.\n```python\ndo(\"copy text to clipboard\")        # Clipboard operations\ndo(\"get clipboard content\")         # Retrieve clipboard\ndo(\"uppercase text hello world\")    # Text transformations\ndo(\"count words in text\")          # Text analysis\n```\n\n### \ud83d\udd22 **Math & Calculations** (7 commands)\nSafe mathematical operations and unit conversions.\n```python\ndo(\"calculate 15% of 240\")                    # Percentage calculations\ndo(\"convert 100 fahrenheit to celsius\")       # Temperature conversion\ndo(\"calculate tip 45.50 at 18 percent\")      # Financial calculations\ndo(\"generate random number between 1 and 100\")  # Random generation\n```\n\n### \ud83d\udcc5 **Date & Time** (8 commands)\nTemporal operations with timezone support.\n```python\ndo(\"get current timestamp\")              # Unix timestamps\ndo(\"add 5 days to today\")               # Date arithmetic\ndo(\"what time is it in Tokyo\")          # Timezone conversion\ndo(\"how many days until 2025-12-25\")    # Date calculations\n```\n\n### \ud83d\udcdd **Quick Notes** (8 commands)\nPersistent note management with JSON storage.\n```python\ndo(\"save note Meeting with client tomorrow\")  # Create notes\ndo(\"list all notes\")                         # List notes\ndo(\"search notes for meeting\")               # Search functionality\ndo(\"get note 1\")                            # Retrieve specific notes\n```\n\n### \ud83d\udcca **Git Integration** (12 commands)\nVersion control operations for developers.\n```python\ndo(\"git status\")                    # Repository status\ndo(\"git add all files\")             # Stage changes\ndo(\"git commit with message Fix bug\") # Commit changes\ndo(\"list git branches\")             # Branch management\n```\n\n### \u2139\ufe0f **File Information** (7 commands)\nDetailed file inspection and metadata.\n```python\ndo(\"get file info document.pdf\")              # Complete file details\ndo(\"get file hash important.zip\")             # File integrity\ndo(\"find files with extension .py in src/\")   # File discovery\ndo(\"count lines in file script.py\")           # File analysis\n```\n\n### \ud83d\udda5\ufe0f **System Utilities** (15+ commands)\nSystem monitoring and control operations.\n```python\ndo(\"get memory usage\")           # Resource monitoring\ndo(\"list running processes\")     # Process management  \ndo(\"take screenshot\")           # Screen capture\ndo(\"open task manager\")         # System tools\n```\n\n### \ud83d\udd0d **Help & Discovery** (4 commands)\nBuilt-in documentation and command discovery.\n```python\ndo(\"help\")                           # Complete command list\ndo(\"search commands for network\")    # Find relevant commands\ndo(\"list safe commands\")             # LLM-safe operations\ndo(\"list unsafe commands\")           # Commands requiring permission\n```\n\n### \ud83e\udd16 **AI Assistant Generator** (3 commands) - NEW!\nCreate personalized AI development assistants with custom capabilities.\n```python\ndo(\"setup dev assistant\")                    # Interactive setup wizard\ndo(\"setup dev assistant quick MyBot ollama\") # Quick setup with defaults\ndo(\"list dev assistant templates\")           # Show available templates\ndo(\"setup dev assistant template fullstack openai\") # Use pre-configured template\n```\n\n---\n\n## \ud83e\udd16 AI Agent Integration\n\nCaelumSys provides the most advanced AI agent capabilities with **vision and control** integration:\n\n### \ud83d\udc41\ufe0f Vision-Enabled Commands (9 total) \u2705\nAI agents can **see and analyze** your screen:\n```python\ndo(\"take screenshot\")           # \u2705 Safe - capture screen\ndo(\"analyze screen content\")    # \u2705 Safe - visual analysis  \ndo(\"find image on screen\")      # \u2705 Safe - locate UI elements\ndo(\"get pixel color at 100 100\") # \u2705 Safe - color detection\n```\n\n### \ud83d\uddb1\ufe0f Input Control Commands (15 total) \u26a0\ufe0f\nAI agents can **control mouse and keyboard** (requires permission):\n```python\ndo(\"click at 250 150\")          # \u26a0\ufe0f Controlled - mouse clicking\ndo(\"type text Hello\")           # \u26a0\ufe0f Controlled - keyboard input\ndo(\"press keys ctrl+c\")         # \u26a0\ufe0f Controlled - shortcuts\ndo(\"drag from 100 100 to 200 200\") # \u26a0\ufe0f Controlled - drag operations\n```\n\n### Safe Commands (111 total) \u2705\nCommands that **read information** without modifying system state:\n```python\ndo(\"get current time\")        # \u2705 Safe - information retrieval\ndo(\"check website status\")    # \u2705 Safe - network checking  \ndo(\"get file size setup.py\")  # \u2705 Safe - file inspection\ndo(\"list running processes\")  # \u2705 Safe - system monitoring\n```\n\n### Unsafe Commands (24 total) \u26a0\ufe0f\nCommands that **modify system state** and require explicit permission:\n```python\ndo(\"delete file config.txt\")  # \u26a0\ufe0f Unsafe - file deletion\ndo(\"kill process chrome\")     # \u26a0\ufe0f Unsafe - process termination\ndo(\"empty recycle bin\")       # \u26a0\ufe0f Unsafe - system cleanup\ndo(\"git commit with message\") # \u26a0\ufe0f Unsafe - repository changes\n```\n\n**Query commands by safety:** \n- `do(\"list safe commands\")` - Shows read-only operations\n- `do(\"list unsafe commands\")` - Shows system-modifying operations\n\n### \ud83c\udfaf Revolutionary Use Cases\n\n**\ud83c\udfae Gaming Automation:**\n```python\n# AI can watch game screens and react\nagent.chat(\"Watch for the enemy and click to attack when you see red\")\n```\n\n**\ud83d\udcbc Productivity Automation:**\n```python  \n# AI can read and interact with any application\nagent.chat(\"Read my emails and draft replies to the important ones\")\n```\n\n**\ud83d\udd27 Smart Testing:**\n```python\n# AI can perform visual UI testing\nagent.chat(\"Click through the app workflow and report any visual bugs\")\n```\n\n---\n\n## \ud83d\udee0\ufe0f Creating Custom Plugins\n\nExtend CaelumSys with custom functionality:\n\n```python\n# caelum_sys/plugins/my_plugin.py\nfrom caelum_sys.registry import register_command\n\n@register_command(\"greet {name}\", safe=True)\ndef greet_person(name: str):\n    \"\"\"Greet someone by name.\"\"\"\n    return f\"\ud83d\udc4b Hello, {name}! Welcome to CaelumSys!\"\n\n@register_command(\"backup database\", safe=False)  \ndef backup_database():\n    \"\"\"Backup the application database.\"\"\"\n    # Implementation here\n    return \"\ud83d\udcbe Database backup completed successfully\"\n```\n\n**Plugin features:**\n- \u2705 **Auto-discovery**: Just add `.py` files to `caelum_sys/plugins/`\n- \u2705 **Parameter extraction**: `{name}` automatically becomes function parameter\n- \u2705 **Safety classification**: Mark commands as safe/unsafe for AI agents\n- \u2705 **Error handling**: Built-in exception handling and user-friendly messages\n\n---\n\n## \ud83d\udee0\ufe0f Development\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Format code\nblack caelum_sys/\nisort caelum_sys/\n\n# Type checking (optional)\nmypy caelum_sys/\n\n# Build package\npython -m build\n```\n\n**Project Structure:**\n```\ncaelum_sys/\n\u251c\u2500\u2500 plugins/           # Plugin modules (25+ plugins with 135+ commands)\n\u251c\u2500\u2500 core_actions.py    # Main execution engine\n\u251c\u2500\u2500 registry.py        # Command registration system\n\u251c\u2500\u2500 cli.py            # Command-line interface\n\u2514\u2500\u2500 __init__.py       # Package interface\n```\n\n---\n\n## \ud83d\udccb Requirements\n\n- **Python**: 3.9+ (tested on 3.9, 3.10, 3.11, 3.12, 3.13)\n- **Operating System**: Windows (primary), macOS, Linux\n- **Dependencies**: Automatically installed with package\n  \n### Core Dependencies\n  - `psutil` - System monitoring and process management\n  - `requests` - Web operations and HTTP requests\n  - `pyperclip` - Clipboard integration\n  - `pytz` - Timezone support and conversions\n  - `python-dateutil` - Advanced date parsing and manipulation\n  - `pyautogui` - Basic screen capture and input control\n  - `pillow` - Image processing and manipulation\n\n### High-Performance Vision (NEW in v0.4.0!)\n  - `mss>=9.0.1` - Ultra-fast screen capture (3-4x faster than PyAutoGUI)\n  - `opencv-python>=4.8.0` - Advanced computer vision and template matching\n  - `pytesseract>=0.3.10` - OCR text extraction from screen regions\n  - `numpy>=1.24.0` - Numerical operations for image processing\n\n### Optional AI Dependencies\n  - `openai` - For GPT-4, GPT-3.5-turbo integration (install with `pip install caelum-sys[openai]`)\n  - `anthropic` - For Claude 3.5 Sonnet, Claude 3 integration (install with `pip install caelum-sys[anthropic]`)\n  - **Ollama** - Local AI models (no extra Python dependencies - just install Ollama separately)\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-plugin`\n3. **Add your plugin** to `caelum_sys/plugins/`\n4. **Test your functionality** with the CLI or programmatic interface\n5. **Submit a pull request**\n\n**Contribution Ideas:**\n- \ud83d\udd0c New plugins (email, database, cloud services)\n- \ud83d\udcda Documentation improvements\n- \ud83d\udd27 Performance optimizations\n- \ud83d\udc1b Bug fixes and optimizations\n- \ud83c\udf0d Cross-platform compatibility\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## \ud83d\udd17 Links\n\n- **PyPI Package**: https://pypi.org/project/caelum-sys/\n- **GitHub Repository**: https://github.com/BlackBeardJW/caelum-sys\n- **Issue Tracker**: https://github.com/BlackBeardJW/caelum-sys/issues\n- **Documentation**: Coming soon!\n\n---\n\n## \ud83d\udcc8 Roadmap\n\n## \ud83d\udcc8 Roadmap\n\n**v0.4.0 (Current - COMPLETE!) \u2705**\n- \ud83d\ude80 **BUILT-IN HIGH-PERFORMANCE VISION**: MSS, OpenCV, Tesseract integrated directly\n- \u26a1 **3-4x faster screen capture** with MSS (no separate installation)\n- \ud83c\udfaf **Enhanced template matching** with OpenCV for superior accuracy\n- \ud83d\udcd6 **Built-in OCR text extraction** with Tesseract\n- \ud83c\udfae **Gaming-level performance**: 160+ FPS pixel monitoring\n- \ud83d\udcca **Performance benchmarking tools** built-in\n- \ud83e\udd16 Full AI agent integration (OpenAI, Anthropic, Ollama)\n- \ud83c\udfe0 Local model support (Ollama) - No API keys needed!\n- \ud83d\udee1\ufe0f Advanced safety and permission systems\n- \ud83d\udd27 Enhanced function schema generation\n- \ud83d\udcda Comprehensive AI integration documentation\n\n**v0.5.0 (Planned)**\n- \ud83d\udce1 REST API server mode\n- \ud83d\udd27 Plugin management CLI\n- \ud83c\udf10 Web dashboard interface\n- \ud83d\uded2 Plugin marketplace\n\n**v1.0.0 (Future)**\n- \ud83c\udfaf Stable API guarantee\n- \ud83d\udd12 Advanced security features\n- \ud83c\udfe2 Enterprise integrations\n- \ud83d\udcca Analytics and monitoring\n\n---\n\n<div align=\"center\">\n\n**Made with \u2764\ufe0f by Joshua Wells**\n\n\u2b50 **Star this repo** if you find CaelumSys useful!\n\n</div>\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "AI-enhanced system automation toolkit with HIGH-PERFORMANCE vision - 135+ commands, MSS/OpenCV/Tesseract integration, OpenAI/Anthropic/Ollama support",
    "version": "0.4.0",
    "project_urls": {
        "Documentation": "https://github.com/BlackBeardJW/caelum-sys/blob/main/AI_QUICKSTART.md",
        "Homepage": "https://github.com/BlackBeardJW/caelum-sys",
        "Issues": "https://github.com/BlackBeardJW/caelum-sys/issues",
        "Repository": "https://github.com/BlackBeardJW/caelum-sys"
    },
    "split_keywords": [
        "automation",
        " system",
        " scripting",
        " ai",
        " natural-language",
        " openai",
        " anthropic",
        " ollama",
        " local-models",
        " assistant",
        " agent",
        " chatbot"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "30ed123c0be4d40ab64b30e43a4bf2c11e6d7f6fb20d0df3173f00f713b36261",
                "md5": "9df36a3c38c91ffbd39fa0ace187b923",
                "sha256": "e5050c039f31240a8417c7527071488d55b87ddc36ae0a6b1603c4d61712c3c1"
            },
            "downloads": -1,
            "filename": "caelum_sys-0.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9df36a3c38c91ffbd39fa0ace187b923",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 63247,
            "upload_time": "2025-08-03T13:04:08",
            "upload_time_iso_8601": "2025-08-03T13:04:08.778614Z",
            "url": "https://files.pythonhosted.org/packages/30/ed/123c0be4d40ab64b30e43a4bf2c11e6d7f6fb20d0df3173f00f713b36261/caelum_sys-0.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c42419f3bbb3a62047b87cc4b03f8300bb1111ec3dead517e5562a12e4aadc79",
                "md5": "bd9750711a122d3ada21de00b927e95f",
                "sha256": "d1dbe30d4968eb5ea4454f82f24da1cc640fc62a9b646aecafd288d3b057524a"
            },
            "downloads": -1,
            "filename": "caelum_sys-0.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "bd9750711a122d3ada21de00b927e95f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 65814,
            "upload_time": "2025-08-03T13:04:10",
            "upload_time_iso_8601": "2025-08-03T13:04:10.225367Z",
            "url": "https://files.pythonhosted.org/packages/c4/24/19f3bbb3a62047b87cc4b03f8300bb1111ec3dead517e5562a12e4aadc79/caelum_sys-0.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-03 13:04:10",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "BlackBeardJW",
    "github_project": "caelum-sys",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "caelum-sys"
}
        
Elapsed time: 0.84518s