ellma 0.1.9

Evolutionary Local LLM Agent - Self-improving AI assistant

🧬 ELLMa - Evolutionary Local LLM Agent

Evolutionary Local LLM Agent - Self-improving AI assistant that evolves with your needs

📋 Table of Contents

• 🚀 Features
• ⚡ Quick Start
  • Prerequisites
  • Installation
  • First Steps
• 🛠 Development
• 🔍 Usage Examples
• 🧩 Extending ELLMa
• ⚙️ Generated Utilities
• 🤝 Contributing
• 📄 License
• 📚 Documentation

🚀 Features

ELLMa is a revolutionary self-evolving AI agent that runs locally on your machine. Unlike traditional AI tools, ELLMa learns and improves itself with these key features:

🚀 What is ELLMa?

ELLMa is a revolutionary self-evolving AI agent that runs locally on your machine. Unlike traditional AI tools, ELLMa learns and improves itself by:

Core Capabilities

• 🧬 Self-Evolution: Automatically generates new capabilities based on usage patterns
• 🏠 Local-First: Runs entirely on your machine with complete privacy
• 🐚 Shell-Native: Integrates seamlessly with your system and workflows
• 🛠️ Command Execution: Executes commands in a structured format
• 📦 Modular: Extensible architecture that grows with your needs
• 🤖 Multi-Model: Supports various local LLM models
• 🔄 Auto-Improving: Continuously learns from interactions

Technical Highlights

• Built-in Commands: Wide range of system, web, and file operations
• Code Generation: Generate Python, Bash, and Docker configurations
• Web Interaction: Advanced web scraping and API interaction tools
• Plugin System: Easy to extend with custom modules
• Performance Monitoring: Built-in metrics and monitoring
• Cross-Platform: Works on Linux, macOS, and Windows (WSL2 recommended for Windows)

⚡ Quick Start

Prerequisites

• Python 3.8+
• pip (Python package manager)
• Git (for development)
• 8GB+ RAM recommended for local models
• For GPU acceleration: CUDA-compatible GPU (optional)

Installation

Option 1: Install from source (recommended for development)

# Clone the repository
git clone https://github.com/wronai/ellma.git
cd ellma

# Install in development mode with all dependencies
pip install -e ".[dev]"

Option 2: Install via pip

pip install ellma

First Steps

1. Initialize ELLMa (creates config in ~/.ellma)

   # Basic initialization
   ellma init
   
   # Force re-initialization
   # ellma init --force
   

2. Download a model (or let it auto-download when needed)

   # Download default model
   ellma download-model
   
   # Specify a different model
   # ellma download-model --model mistral-7b-instruct
   

3. Verify your setup

   # Check system requirements and configuration
   ellma verify
   

4. Start the interactive shell

   # Start interactive shell
   ellma shell
   
   # Start shell with verbose output
   # ellma -v shell
   

5. Or execute commands directly

   # System information
   ellma exec system.scan
   
   # Web interaction (extract text and links)
   ellma exec web.read https://example.com --extract-text --extract-links
   
   # File operations (search for Python files)
   ellma exec files.search /path/to/directory --pattern "*.py"
   
   # Get agent status
   ellma status
   

🛠 Development

🛠 Development

Setting Up Development Environment

1. Clone the repository

   git clone https://github.com/wronai/ellma.git
   cd ellma
   

2. Install with development dependencies

   pip install -e ".[dev]"
   

3. Set up pre-commit hooks (recommended)

   pre-commit install
   

Development Workflow

Running Tests

# Run all tests
make test

# Run specific test file
pytest tests/test_web_commands.py -v

# Run with coverage report
make test-coverage

Code Quality

# Run linters
make lint

# Auto-format code
make format

# Type checking
make typecheck

# Security checks
make security

Documentation

# Build documentation
make docs

# Serve docs locally
cd docs && python -m http.server 8000

Project Structure

ellma/
├── ellma/                  # Main package
│   ├── core/              # Core functionality
│   ├── commands/          # Built-in commands
│   ├── generators/        # Code generation
│   ├── models/           # Model management
│   └── utils/            # Utilities
├── tests/                 # Test suite
├── docs/                 # Documentation
└── scripts/              # Development scripts

Project Structure

ellma/
├── ellma/                  # Main package
│   ├── core/              # Core functionality
│   ├── commands/          # Built-in commands
│   ├── generators/        # Code generation
│   ├── models/           # Model management
│   └── utils/            # Utilities
├── tests/                 # Test suite
├── docs/                 # Documentation
└── scripts/              # Development scripts

🔄 Evolution & Self-Improvement

ELLMa's evolution engine allows it to analyze its performance and automatically improve its capabilities.

Running Evolution

# Run a single evolution cycle
ellma evolve

# Run multiple evolution cycles
ellma evolve --cycles 3

# Force evolution even if no improvements are detected
ellma evolve --force

# Run evolution with specific parameters
ellma evolve --learning-rate 0.2 --max-depth 5

Monitoring Evolution

# View evolution history
cat ~/.ellma/evolution/evolution_history.json | jq .

# Monitor evolution logs
tail -f ~/.ellma/logs/evolution.log

# Get evolution status
ellma status --evolution

Evolution Configuration

You can configure the evolution process in ~/.ellma/config.yaml:

evolution:
  enabled: true
  auto_improve: true
  learning_rate: 0.1
  max_depth: 3
  max_iterations: 100
  early_stopping: true

🧩 Extending ELLMa

Creating Custom Commands

1. Create a new Python module in ellma/commands/:

from ellma.commands.base import BaseCommand

class MyCustomCommand(BaseCommand):
    """My custom command"""

2. Register your command in ellma/commands/__init__.py
3. Restart ELLMa to load your new command

⚙️ Generated Utilities

ELLMa includes a powerful set of self-generated utilities for common programming tasks. These include:

• 🛡️ Enhanced Error Handling: Automatic retries with exponential backoff
• ⚡ Performance Caching: In-memory cache with TTL support
• 🚀 Parallel Processing: Easy parallel execution of tasks

See the Generated Utilities Documentation for detailed usage and examples.

def __init__(self, agent):
    super().__init__(agent)
    self.name = "custom"
    self.description = "My custom command"

def my_action(self, param1: str, param2: int = 42):
    """Example action"""
    return {"result": f"Got {param1} and {param2}"}

2. Register your command in `ellma/commands/__init__.py`

### Creating Custom Modules

1. Create a new module class:

```python
from ellma.core.module import BaseModule

class MyCustomModule(BaseModule):
    def __init__(self, agent):
        super().__init__(agent)
        self.name = "my_module"
        self.version = "1.0.0"
    
    def setup(self):
        # Initialization code
        pass
    
    def execute(self, command: str, *args, **kwargs):
        # Handle commands
        if command == "greet":
            return f"Hello, {kwargs.get('name', 'World')}!"
        raise ValueError(f"Unknown command: {command}")

2. Register your module in the agent's configuration

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Report Bugs: Open an issue with detailed steps to reproduce
2. Suggest Features: Share your ideas for new features
3. Submit Pull Requests: Follow these steps:
   • Fork the repository
   • Create a feature branch
   • Make your changes
   • Add tests
   • Update documentation
   • Submit a PR

Development Guidelines

• Follow PEP 8 style guide
• Write docstrings for all public functions and classes
• Add type hints for better code clarity
• Write tests for new features
• Update documentation when making changes

📄 License

MIT License - see LICENSE for details.

📚 Documentation

For complete documentation, visit ellma.readthedocs.io

🙏 Acknowledgments

• Thanks to all contributors who have helped improve ELLMa
• Built with ❤️ by the ELLMa team

🎯 Core Features

🧬 Self-Evolution Engine

ELLMa continuously improves by analyzing its performance and automatically generating new modules:

$ ellma evolve
🧬 Starting evolution process...
📊 Analyzing current capabilities...
🎯 Identified 3 improvement opportunities:
   ✅ Added: advanced_file_analyzer
   ✅ Added: network_monitoring
   ✅ Added: code_optimizer
🎉 Evolution complete! 3 new capabilities added.

📊 Performance Monitoring

Track your agent's performance:

# Show agent status
ellma status

# View system health metrics
ellma exec system.health

🔍 Advanced Command Usage

# Chain multiple commands
ellma exec "system.scan && web.read https://example.com"

# Save command output to file
ellma exec system.scan > scan_results.json

# Use different output formats
ellma exec system.scan --format json
ellma exec system.scan --format yaml

🐚 Powerful Shell Interface

Natural language commands that translate to system operations:

ellma> system scan network ports
ellma> generate bash script for backup
ellma> analyze this log file for errors
ellma> create docker setup for web app

🛠️ Multi-Language Code Generation

Generate production-ready code in multiple languages:

# Generate Bash scripts
ellma generate bash --task="Monitor system resources and alert on high usage"

# Generate Python code  
ellma generate python --task="Web scraper with rate limiting"

# Generate Docker configurations
ellma generate docker --task="Multi-service web application"

# Generate Groovy for Jenkins
ellma generate groovy --task="CI/CD pipeline with testing stages"

📊 Intelligent System Integration

ELLMa understands your system and can:

• Scan and analyze system configurations
• Monitor processes and resources
• Automate repetitive tasks
• Generate custom tools for your workflow

🏗️ Architecture

ellma/
├── core/                   # Core agent and evolution engine
│   ├── agent.py           # Main LLM Agent class
│   ├── evolution.py       # Self-improvement system
│   └── shell.py           # Interactive shell interface
├── commands/               # Modular command system
│   ├── system.py          # System operations
│   ├── web.py             # Web interactions
│   └── files.py           # File operations
├── generators/             # Code generation engines
│   ├── bash.py            # Bash script generator
│   ├── python.py          # Python code generator
│   └── docker.py          # Docker configuration generator
├── modules/                # Dynamic module system
│   ├── registry.py        # Module registry and loader
│   └── [auto-generated]/  # Self-created modules
└── cli/                   # Command-line interface
    ├── main.py            # Main CLI entry point
    └── shell.py           # Interactive shell

📚 Usage Examples

System Administration

# Run comprehensive system scan
ellma exec system.scan

# Monitor system resources (60 seconds with 5-second intervals)
ellma exec system.monitor --duration 60 --interval 5

# Check system health status
ellma exec system.health

# List top processes by CPU usage
ellma exec system.processes --sort-by cpu --limit 10

# Check open network ports
ellma exec system.ports

Development Workflow

# Generate a new Python project
ellma generate python --task "FastAPI project with SQLAlchemy and JWT auth"

# Create a Docker Compose setup
ellma generate docker --task "Python app with PostgreSQL and Redis"

# Generate test cases
ellma generate test --file app/main.py --framework pytest

# Document a Python function
ellma exec code.document_function utils.py --function process_data

Web & API Interaction

# Read and extract content from a webpage
ellma exec web.read https://example.com --extract-text --extract-links

# Make HTTP GET request to an API endpoint
ellma exec web.get https://api.example.com/data

# Make HTTP POST request with JSON data
ellma exec web.post https://api.example.com/data --data '{"key": "value"}'

# Generate API client code
ellma generate python --task "API client for REST service with error handling"

## 🔧 Configuration

ELLMa stores its configuration in `~/.ellma/`:

```yaml
# ~/.ellma/config.yaml
model:
  path: ~/.ellma/models/mistral-7b.gguf
  context_length: 4096
  temperature: 0.7

evolution:
  enabled: true
  auto_improve: true
  learning_rate: 0.1

modules:
  auto_load: true
  custom_path: ~/.ellma/modules

🧬 How Evolution Works

1. Performance Analysis: ELLMa monitors execution times, success rates, and user feedback
2. Gap Identification: Identifies missing functionality or optimization opportunities
3. Code Generation: Uses its LLM to generate new modules and improvements
4. Testing & Integration: Automatically tests and integrates new capabilities
5. Continuous Learning: Learns from each interaction to become more useful

🚀 Advanced Features

Custom Module Development

# Create custom modules that ELLMa can use and improve
from ellma.core.module import BaseModule

class MyCustomModule(BaseModule):
    def execute(self, *args, **kwargs):
        # Your custom functionality
        return result

API Integration

from ellma import ELLMa

# Use ELLMa programmatically
agent = ELLMa()
result = agent.execute("system.scan")
code = agent.generate("python", task="Data analysis script")

Web Interface (Optional)

# Install web dependencies
pip install ellma[web]

# Start web interface
ellma web --port 8000

🛣️ Roadmap

Version 0.1.6 - MVP ✅

• Core agent with Mistral 7B
• Basic command system
• Shell interface
• Evolution foundation

Version 0.2.0 - Enhanced Shell

• Advanced command completion
• Command history and favorites
• Real-time performance monitoring
• Module hot-reloading

Version 0.3.0 - Code Generation

• Multi-language code generators
• Template system
• Code quality analysis
• Integration testing

Version 0.4.0 - Advanced Evolution

• Performance-based learning
• User feedback integration
• Predictive capability development
• Module marketplace

Version 1.0.0 - Autonomous Agent

• Full self-management
• Advanced reasoning capabilities
• Multi-agent coordination
• Enterprise features

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/ellma-ai/ellma.git
cd ellma

# Install in development mode
pip install -e .[dev]

# Run tests
pytest

# Run linting
black ellma/
flake8 ellma/

📄 License

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

🙏 Acknowledgments

• Built on top of llama-cpp-python
• Inspired by the vision of autonomous AI agents
• Powered by the amazing Mistral 7B model

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

---

ELLMa: The AI agent that grows with you 🌱→🌳