{"id":28814973,"url":"https://github.com/wronai/ellma","last_synced_at":"2026-03-17T23:09:12.554Z","repository":{"id":297793280,"uuid":"997878366","full_name":"wronai/ellma","owner":"wronai","description":"Evolutionary Local LLM Agent - Self-improving AI assistant","archived":false,"fork":false,"pushed_at":"2025-06-08T18:21:44.000Z","size":447,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T03:26:12.087Z","etag":null,"topics":["agent","bio","client-server","cursor","ellma","evolutionary","llm","mistral","ollama","windsurf"],"latest_commit_sha":null,"homepage":"https://wronai.github.io/ellma/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wronai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-07T11:41:23.000Z","updated_at":"2025-06-08T18:21:49.000Z","dependencies_parsed_at":"2025-06-27T02:43:43.904Z","dependency_job_id":null,"html_url":"https://github.com/wronai/ellma","commit_stats":null,"previous_names":["wronai/ellma"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wronai/ellma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wronai%2Fellma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wronai%2Fellma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wronai%2Fellma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wronai%2Fellma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wronai","download_url":"https://codeload.github.com/wronai/ellma/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wronai%2Fellma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30635156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T22:38:22.569Z","status":"ssl_error","status_checked_at":"2026-03-17T22:38:11.804Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","bio","client-server","cursor","ellma","evolutionary","llm","mistral","ollama","windsurf"],"created_at":"2025-06-18T16:03:21.345Z","updated_at":"2026-03-17T23:09:12.508Z","avatar_url":"https://github.com/wronai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧬 ELLMa - Evolutionary Local LLM Agent\n\n\u003e **E**volutionary **L**ocal **LLM** **A**gent - Self-improving AI assistant that evolves with your needs\n\n[![PyPI version](https://badge.fury.io/py/ellma.svg)](https://badge.fury.io/py/ellma)\n[![Python Support](https://img.shields.io/pypi/pyversions/ellma.svg)](https://pypi.org/project/ellma/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Documentation Status](https://readthedocs.org/projects/ellma/badge/?version=latest)](https://ellma.readthedocs.io/)\n\n## 📋 Table of Contents\n\n- [🚀 Features](#-features)\n- [⚡ Quick Start](#-quick-start)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [First Steps](#first-steps)\n- [🛠 Development](#-development)\n- [🔍 Usage Examples](#-usage-examples)\n- [🧩 Extending ELLMa](#-extending-ellma)\n- [⚙️ Generated Utilities](#️-generated-utilities)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n- [📚 Documentation](#-documentation)\n\n## 🚀 Features\n\nELLMa 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:\n\n### 🔄 Self-Improvement \u0026 Evolution\n\n- **Automatic Code Generation**: Generates new modules and capabilities on-the-fly\n- **Continuous Learning**: Improves from interactions and feedback\n- **Evolution Engine**: Self-modifying architecture that evolves over time\n- **Performance Optimization**: Identifies and implements performance improvements\n- **Error Recovery**: Automatically detects and recovers from errors\n\n### 🔒 Security \u0026 Dependency Management\n\n- **Automatic Environment Setup**: Ensures all dependencies are installed and configured correctly\n- **Dependency Auto-Repair**: Automatically detects and fixes missing or broken dependencies\n- **Virtual Environment Management**: Handles Python virtual environments automatically\n- **Security Checks**: Performs security validations before executing commands\n- **Graceful Degradation**: Works even when optional dependencies are missing\n\n### 🎙️ Audio Features (Optional)\n\nELLMa includes optional audio capabilities that can be enabled by installing the audio extras. These features require additional system dependencies.\n\n#### Audio Features\n\n- **Speech Recognition**: Convert speech to text\n- **Text-to-Speech**: Convert text to speech (coming soon)\n\n#### Installation\n\nTo install with audio support:\n\n```bash\npip install ellma[audio]\n```\n\n#### System Dependencies\n\n**On Ubuntu/Debian:**\n```bash\nsudo apt-get update\nsudo apt-get install -y python3-dev portaudio19-dev\n```\n\n**On Fedora/RHEL:**\n```bash\nsudo dnf install -y python3-devel alsa-lib-devel portaudio-devel\n```\n\n**On macOS (using Homebrew):**\n```bash\nbrew install portaudio\n```\n\n**Note:** Audio features are optional. If you don't need them, you can use ELLMa without installing these dependencies.\n- **Audio Processing**: Work with audio files and streams\n\nTo install with audio support:\n```bash\npoetry install --extras \"audio\"\n# or with pip\npip install ellma[audio]\n```\n\nNote: Audio features require system dependencies. On Fedora/RHEL:\n```bash\nsudo dnf install python3-devel alsa-lib-devel portaudio-devel\n```\n\nOn Ubuntu/Debian:\n```bash\nsudo apt-get install python3-dev portaudio19-dev\n```\n\n## 📦 Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- Poetry (recommended) or pip\n- System dependencies (for audio features, see above)\n\n### 🛠 Commands\n\n```bash\n# Check environment status\nellma security check\n\n# Install dependencies\nellma security install [--group GROUP]\n\n# Repair environment issues\nellma security repair\n```\n\n[![PyPI version](https://badge.fury.io/py/ellma.svg)](https://badge.fury.io/py/ellma)\n[![Python Support](https://img.shields.io/pypi/pyversions/ellma.svg)](https://pypi.org/project/ellma/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n## 🚀 What is ELLMa?\n\nELLMa is a revolutionary **self-evolving AI agent** that runs locally on your machine. Unlike traditional AI tools, ELLMa **learns and improves itself** by:\n\n### Core Capabilities\n\n- **Performance Monitoring**: Built-in metrics and monitoring\n- **Cross-Platform**: Works on Linux, macOS, and Windows (WSL2 recommended for Windows)\n- **System Introspection**: Built-in commands for system exploration and debugging\n\n### System Introspection\n\nELLMa includes powerful introspection capabilities to help you understand and debug the system:\n\n```python\n# View configuration\nsys config                # Show all configuration\nsys config model         # Show model configuration\n\n# Explore source code\nsys source ellma.core.agent.ELLMa  # View class source\nsys code ellma.commands.system     # View module source\n\n# System information\nsys info                 # Show detailed system info\nsys status               # Show system status\nsys health              # Run system health check\n\n# Module exploration\nsys modules             # List all available modules\nsys module ellma.core   # Show info about a module\n\n# Command help\nsys commands           # List all available commands\nsys help               # Show help for system commands\n```\n\nThese commands support natural language queries, so you can type things like:\n- \"show me the config\" → `sys config`\n- \"what modules are available\" → `sys modules`\n- \"display system information\" → `sys info`\n\n## 🛡️ Security and Dependency Management\n\nELLMa includes a comprehensive security and dependency management system that ensures safe and reliable execution:\n\n### 🔒 Security Features\n\n- **Secure Code Execution**: All code runs in a sandboxed environment with restricted permissions\n- **Dependency Validation**: Automatic verification of required packages and versions\n- **Environment Isolation**: Each component runs in its own isolated environment\n- **Audit Logging**: Detailed logging of all security-relevant actions\n- **Automatic Repair**: Self-healing capabilities for common issues\n- **Secure Defaults**: Secure by default with sensible restrictions\n\n### 📦 Dependency Management\n\n- **Automatic Dependency Resolution**: Automatically installs missing dependencies\n- **Version Conflict Resolution**: Handles version conflicts gracefully\n- **Dependency Isolation**: Each module can specify its own dependencies\n- **Security Scanning**: Regular security scans for known vulnerabilities\n\n### 🛠️ Using the Secure Executor\n\nRun any Python script or module securely:\n\n```bash\n# Run a script with dependency checking\nellma-secure path/to/script.py\n\n# Interactive secure Python shell\nellma-secure\n\n# Install dependencies from requirements.txt\nellma-secure --requirements requirements.txt\n```\n\n### 🛡️ Security Context Manager\n\nUse the security context manager in your code:\n\n```python\nfrom ellma.core.security import SecurityContext, Dependency\n\n# Define dependencies\ndependencies = [\n    Dependency(name=\"numpy\", min_version=\"1.20.0\"),\n    Dependency(name=\"pandas\", min_version=\"1.3.0\")\n]\n\n# Run code in a secure context\nwith SecurityContext(dependencies):\n    import numpy as np\n    import pandas as pd\n    # Your secure code here\n```\n\n### 🔄 Automatic Dependency Checking\n\nAdd dependency checking to any function:\n\n```python\nfrom ellma.core.decorators import secure\nfrom ellma.core.security import Dependency\n\n@secure(dependencies=[\n    Dependency(name=\"requests\", min_version=\"2.25.0\"),\n    Dependency(name=\"numpy\", min_version=\"1.20.0\")\n])\ndef process_data(url: str) -\u003e dict:\n    import requests\n    import numpy as np\n    # Your function code here\n```\n\n### 🚀 Setup and Configuration\n\n1. **Install development dependencies**:\n   ```bash\n   poetry install --with dev\n   ```\n\n2. **Run security checks**:\n   ```bash\n   # Run bandit security scanner\n   bandit -r ellma/\n   \n   # Check for vulnerable dependencies\n   safety check\n   ```\n\n3. **Update dependencies**:\n   ```bash\n   # Update all dependencies\n   poetry update\n   \n   # Update a specific package\n   poetry update package-name\n   ```\n\n## ⚡ Quick Start\n\n### Prerequisites\n\n- Python 3.8+\n- pip (Python package manager)\n- Git (for development)\n- 8GB+ RAM recommended for local models\n- For GPU acceleration: CUDA-compatible GPU (optional)\n\n### Installation\n\n#### Option 1: Install from source (recommended for development)\n```bash\n# Clone the repository\ngit clone https://github.com/wronai/ellma.git\ncd ellma\n\n# Install in development mode with all dependencies\npip install -e \".[dev]\"\n```\n\n#### Option 2: Install via pip\n```bash\npip install ellma\n```\n\n### First Steps\n\n1. **Initialize ELLMa** (creates config in ~/.ellma)\n   ```bash\n   # Basic initialization\n   ellma init\n   \n   # Force re-initialization\n   # ellma init --force\n   ```\n\n2. **Download a model** (or let it auto-download when needed)\n   ```bash\n   # Download default model\n   ellma download-model\n   \n   # Specify a different model\n   # ellma download-model --model mistral-7b-instruct\n   ```\n\n3. **Start the interactive shell**\n   ```bash\n   # Start interactive shell\n   ellma shell\n   \n   # Start shell with verbose output\n   # ellma -v shell\n   ```\n\n5. **Or execute commands directly**\n   ```bash\n   # System information\n   ellma exec system scan\n   \n   # Web interaction (extract text and links)\n   ellma exec web read https://example.com --extract-text --extract-links\n   \n   # File operations (search for Python files)\n   ellma exec files search /path/to/directory --pattern \"*.py\"\n   \n   # Get agent status\n   ellma status\n   ```\n\n## 🛠 Development\n\n### Setting Up Development Environment\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/wronai/ellma.git\n   cd ellma\n   ```\n\n2. **Create and activate a virtual environment**\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install development dependencies**\n   ```bash\n   pip install -e \".[dev]\"\n   pip install pytest pytest-cov pytest-mock\n   ```\n\n4. **Install runtime dependencies**\n   ```bash\n   pip install SpeechRecognition pyttsx3\n   ```\n\n### Running Tests\n\nRun all tests:\n```bash\npytest -v\n```\n\nRun tests with coverage report:\n```bash\npytest --cov=ellma --cov-report=term-missing\n```\n\n### Evolution Engine\n\nThe evolution engine is a core component that enables self-improvement. It works by:\n1. Analyzing system performance and capabilities\n2. Identifying improvement opportunities\n3. Generating and testing new code\n4. Integrating successful changes\n\nTo manually trigger an evolution cycle:\n```python\nfrom ellma.core.agent import ELLMa\n\nagent = ELLMa()\nagent.evolve()\n```\n\n### Code Style\n\nWe use `black` for code formatting and `flake8` for linting. Before submitting a PR, please run:\n\n```bash\nblack .\nflake8\n```\n\n3. **Set up pre-commit hooks** (recommended)\n   ```bash\n   pre-commit install\n   ```\n\n### Development Workflow\n\n#### Running Tests\n```bash\n# Run all tests\nmake test\n\n# Run specific test file\npytest tests/test_web_commands.py -v\n\n# Run with coverage report\nmake test-coverage\n```\n\n#### Code Quality\n```bash\n# Run linters\nmake lint\n\n# Auto-format code\nmake format\n\n# Type checking\nmake typecheck\n\n# Security checks\nmake security\n```\n\n#### Documentation\n```bash\n# Build documentation\nmake docs\n\n# Serve docs locally\ncd docs \u0026\u0026 python -m http.server 8000\n```\n\n### Project Structure\n\n```\nellma/\n├── ellma/                  # Main package\n│   ├── core/              # Core functionality\n│   ├── commands/          # Built-in commands\n│   ├── generators/        # Code generation\n│   ├── models/           # Model management\n│   └── utils/            # Utilities\n├── tests/                 # Test suite\n├── docs/                 # Documentation\n└── scripts/              # Development scripts\n```\n\n### Project Structure\n\n```\nellma/\n├── ellma/                  # Main package\n│   ├── core/              # Core functionality\n│   ├── commands/          # Built-in commands\n│   ├── generators/        # Code generation\n│   ├── models/           # Model management\n│   └── utils/            # Utilities\n├── tests/                 # Test suite\n├── docs/                 # Documentation\n└── scripts/              # Development scripts\n```\n\n## 🔄 Evolution \u0026 Self-Improvement\n\nELLMa's evolution engine allows it to analyze its performance and automatically improve its capabilities.\n\n### Running Evolution\n\n```bash\n# Run a single evolution cycle\nellma evolve\n\n# Run multiple evolution cycles (up to 3 recommended)\nellma evolve --cycles 3\n\n# Force evolution even if not enough commands have been executed\nellma evolve --force\n```\n\n### Evolution Requirements\n- At least 10 commands should be executed before evolution is recommended\n- Use `--force` to bypass this requirement\n- Evolution status is shown in the main status output\n\n### Monitoring Evolution\n\n```bash\n# View evolution history (if available)\ncat ~/.ellma/evolution/evolution_history.json | jq .\n\n# Monitor evolution logs\ntail -f ~/.ellma/logs/evolution.log\n\n# Check evolution status in the main status output\nellma status\n```\n\n### 🧬 Evolution Configuration\n\nCustomize the self-improvement process in `~/.ellma/config.yaml`:\n\n```yaml\nevolution:\n  enabled: true               # Enable/disable evolution\n  auto_improve: true         # Allow automatic improvements\n  learning_rate: 0.1         # Learning rate for evolution (0.0-1.0)\n```\n\n### Status Information\n\nThe main status command shows key evolution metrics:\n```bash\nellma status\n```\n\nExample output:\n```\n🤖 ELLMa Status                        \n┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n┃ Property               ┃ Value                                   ┃\n┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩\n│ Version                │ 0.1.6                                   │\n│ Model Loaded           │ ✅ Yes                                  │\n│ Model Path             │ /path/to/model.gguf                     │\n│ Modules                │ 0                                       │\n│ Commands               │ 3                                       │\n│ Commands Executed      │ 15                                      │\n│ Success Rate           │ 100.0%                                  │\n│ Evolution Cycles       │ 0                                       │\n│ Modules Created        │ 0                                       │\n└────────────────────────┴─────────────────────────────────────────┘\n```\n```\n\n### Monitoring Evolution\n\nTrack evolution progress and results:\n\n```bash\n# View evolution history with detailed metrics\nellma evolution history --limit 10\n\n# Monitor evolution in real-time\nellma evolution monitor\n\n# Get evolution statistics\nellma evolution stats\n\n# Compare evolution cycles\nellma evolution compare cycle1 cycle2\n```\n\n### Evolution Best Practices\n\n1. **Start Conservative**: Begin with lower learning rates and enable auto-improve\n2. **Monitor Progress**: Regularly check evolution logs and metrics\n3. **Set Resource Limits**: Prevent excessive resource usage\n4. **Use Benchmarks**: Enable benchmarking to measure improvements\n5. **Review Changes**: Periodically review and test evolved modules\n\n### Troubleshooting Evolution\n\nCommon issues and solutions:\n\n```bash\n# If evolution gets stuck\nellma evolution cancel\n\n# Reset to last known good state\nellma evolution rollback\n\n# Clear evolution cache\nellma evolution clean\n\n# Force reset evolution state (use with caution)\nellma evolution reset --confirm\n```\n\n## 🧩 Extending ELLMa\n\n### Creating Custom Commands\n\n1. Create a new Python module in `ellma/commands/`:\n\n```python\nfrom ellma.commands.base import BaseCommand\n\nclass MyCustomCommand(BaseCommand):\n    \"\"\"My custom command\"\"\"\n```\n\n2. Register your command in `ellma/commands/__init__.py`\n3. Restart ELLMa to load your new command\n\n## ⚙️ Generated Utilities\n\nELLMa includes a powerful set of self-generated utilities for common programming tasks. These include:\n\n- 🛡️ **Enhanced Error Handling**: Automatic retries with exponential backoff\n- ⚡ **Performance Caching**: In-memory cache with TTL support\n- 🚀 **Parallel Processing**: Easy parallel execution of tasks\n\nSee the [Generated Utilities Documentation](docs/generated_utilities.md) for detailed usage and examples.\n    \n    def __init__(self, agent):\n        super().__init__(agent)\n        self.name = \"custom\"\n        self.description = \"My custom command\"\n    \n    def my_action(self, param1: str, param2: int = 42):\n        \"\"\"Example action\"\"\"\n        return {\"result\": f\"Got {param1} and {param2}\"}\n```\n\n2. Register your command in `ellma/commands/__init__.py`\n\n### Creating Custom Modules\n\n1. Create a new module class:\n\n```python\nfrom ellma.core.module import BaseModule\n\nclass MyCustomModule(BaseModule):\n    def __init__(self, agent):\n        super().__init__(agent)\n        self.name = \"my_module\"\n        self.version = \"1.0.0\"\n    \n    def setup(self):\n        # Initialization code\n        pass\n    \n    def execute(self, command: str, *args, **kwargs):\n        # Handle commands\n        if command == \"greet\":\n            return f\"Hello, {kwargs.get('name', 'World')}!\"\n        raise ValueError(f\"Unknown command: {command}\")\n```\n\n2. Register your module in the agent's configuration\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how you can help:\n\n1. **Report Bugs**: Open an issue with detailed steps to reproduce\n2. **Suggest Features**: Share your ideas for new features\n3. **Submit Pull Requests**: Follow these steps:\n   - Fork the repository\n   - Create a feature branch\n   - Make your changes\n   - Add tests\n   - Update documentation\n   - Submit a PR\n\n### Development Guidelines\n\n- Follow [PEP 8](https://peps.python.org/pep-0008/) style guide\n- Write docstrings for all public functions and classes\n- Add type hints for better code clarity\n- Write tests for new features\n- Update documentation when making changes\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 📚 Documentation\n\nFor complete documentation, visit [ellma.readthedocs.io](https://ellma.readthedocs.io/)\n\n## 🙏 Acknowledgments\n\n- Thanks to all contributors who have helped improve ELLMa\n- Built with ❤️ by the ELLMa team\n\n## 🎯 Core Features\n\n### 🧬 Self-Evolution Engine\n\nELLMa continuously improves by analyzing its performance and automatically generating new modules:\n\n```bash\n$ ellma evolve\n🧬 Starting evolution process...\n📊 Analyzing current capabilities...\n🎯 Identified 3 improvement opportunities:\n   ✅ Added: advanced_file_analyzer\n   ✅ Added: network_monitoring\n   ✅ Added: code_optimizer\n🎉 Evolution complete! 3 new capabilities added.\n```\n\n### 📊 Performance Monitoring\n\nTrack your agent's performance:\n```bash\n# Show agent status\nellma status\n\n# View system health metrics\nellma exec system.health\n```\n\n### 🔍 Advanced Command Usage\n\n```bash\n# Run system scan\nellma exec system.scan\n\n# Read web page content\nellma exec web.read https://example.com\n\n# Read web page with link extraction\nellma exec web.read https://example.com extract_links true extract_text true\n\n# Quick system health check\nellma exec system.health\n\n# Save command output to file\nellma exec system.scan \u003e scan_results.json\n```\n\n### 🐚 Interactive Shell Interface\n\nStart the interactive shell and use system commands:\n\n```bash\n# Start the interactive shell\nellma shell\n\n# In the shell, you can run commands like:\nellma\u003e system.health\nellma\u003e system.scan\nellma\u003e web.read https://example.com\nellma\u003e web.read https://example.com extract_links true extract_text true\n```\n\nExample shell session:\n```\n🤖 ELLMa Interactive Shell (v0.1.6)\nType 'help' for available commands, 'exit' to quit\n\n# Available commands:\n# - system.health: Check system health\n# - system.scan: Perform system scan\n# - web.read [url]: Read web page content\n# - web.read [url] extract_links true extract_text true: Read web page with link extraction\n# - help: Show available commands\n\nellma\u003e system.health\n{'status': 'HEALTHY', 'cpu_usage': 12.5, 'memory_usage': 45.2, ...}\n\nellma\u003e web.read example.com\n{'status': 200, 'title': 'Example Domain', 'content_length': 1256, ...}\n\n# For commands with parameters, use space-separated values\nellma\u003e web.read example.com extract_links true extract_text true\n```\n\n### 🛠️ Multi-Language Code Generation\nGenerate production-ready code in multiple languages:\n\n```bash\n# Generate Bash scripts\nellma generate bash --task=\"Monitor system resources and alert on high usage\"\n\n# Generate Python code  \nellma generate python --task=\"Web scraper with rate limiting\"\n\n# Generate Docker configurations\nellma generate docker --task=\"Multi-service web application\"\n\n# Generate Groovy for Jenkins\nellma generate groovy --task=\"CI/CD pipeline with testing stages\"\n```\n\n### 📊 Intelligent System Integration\nELLMa understands your system and can:\n\n- Scan and analyze system configurations\n- Monitor processes and resources\n- Automate repetitive tasks\n- Generate custom tools for your workflow\n\n## 🏗️ Architecture\n\n```\nellma/\n├── core/                   # Core agent and evolution engine\n│   ├── agent.py           # Main LLM Agent class\n│   ├── evolution.py       # Self-improvement system\n│   └── shell.py           # Interactive shell interface\n├── commands/               # Modular command system\n│   ├── system.py          # System operations\n│   ├── web.py             # Web interactions\n│   └── files.py           # File operations\n├── generators/             # Code generation engines\n│   ├── bash.py            # Bash script generator\n│   ├── python.py          # Python code generator\n│   └── docker.py          # Docker configuration generator\n├── modules/                # Dynamic module system\n│   ├── registry.py        # Module registry and loader\n│   └── [auto-generated]/  # Self-created modules\n└── cli/                   # Command-line interface\n    ├── main.py            # Main CLI entry point\n    └── shell.py           # Interactive shell\n```\n\n## 📚 Usage Examples\n\n### System Administration\n```bash\n# Run comprehensive system scan\nellma exec system.scan\n\n# Monitor system resources (60 seconds with 5-second intervals)\nellma exec system.monitor --duration 60 --interval 5\n\n# Check system health status\nellma exec system.health\n\n# List top processes by CPU usage\nellma exec system.processes --sort-by cpu --limit 10\n\n# Check open network ports\nellma exec system.ports\n```\n\n### Development Workflow\n\n```bash\n# Generate a new Python project\nellma generate python --task \"FastAPI project with SQLAlchemy and JWT auth\"\n\n# Create a Docker Compose setup\nellma generate docker --task \"Python app with PostgreSQL and Redis\"\n\n# Generate test cases\n```bash\nellma generate test --file app/main.py --framework pytest\n\n# Document a Python function\nellma exec code document_function utils.py --function process_data\n```\n\n### Generated Utilities Examples\n\nExplore practical examples of using the generated utilities in the `examples/generated_utils/` directory:\n\n1. [Error Handling](examples/generated_utils/error_handling_example.py) - Automatic retries with exponential backoff\n2. [Performance Caching](examples/generated_utils/cache_example.py) - Efficient data caching with TTL\n3. [Parallel Processing](examples/generated_utils/parallel_processing_example.py) - Concurrent task execution\n4. [Combined Example](examples/generated_utils/combined_example.py) - Using all utilities together\n\nRun any example with:\n```bash\n# From the project root\npython -m examples.generated_utils.example_name\n\n# Or directly\ncd examples/generated_utils/\npython example_name.py\n```\n\nFor more details, see the [generated utilities documentation](docs/generated_utilities.md).\n\n\n### Web \u0026 API Interaction\n\n```bash\n# Read and extract content from a webpage\nellma exec web.read https://example.com --extract-text --extract-links\n\n# Make HTTP GET request to an API endpoint\nellma exec web.get https://api.example.com/data\n\n# Make HTTP POST request with JSON data\nellma exec web.post https://api.example.com/data --data '{\"key\": \"value\"}'\n\n# Generate API client code\nellma generate python --task \"API client for REST service with error handling\"\n```\n\n\n```\n\n## 🔧 Configuration\n\nELLMa stores its configuration in `~/.ellma/`:\n\n```yaml\n# ~/.ellma/config.yaml\nmodel:\n  path: ~/.ellma/models/mistral-7b.gguf\n  context_length: 4096\n  temperature: 0.7\n\nevolution:\n  enabled: true\n  auto_improve: true\n  learning_rate: 0.1\n\nmodules:\n  auto_load: true\n  custom_path: ~/.ellma/modules\n```\n\n## 🧬 How Evolution Works\n\n1. **Performance Analysis**: ELLMa monitors execution times, success rates, and user feedback\n2. **Gap Identification**: Identifies missing functionality or optimization opportunities  \n3. **Code Generation**: Uses its LLM to generate new modules and improvements\n4. **Testing \u0026 Integration**: Automatically tests and integrates new capabilities\n5. **Continuous Learning**: Learns from each interaction to become more useful\n\n## 🚀 Advanced Features\n\n### Custom Module Development\n```python\n# Create custom modules that ELLMa can use and improve\nfrom ellma.core.module import BaseModule\n\nclass MyCustomModule(BaseModule):\n    def execute(self, *args, **kwargs):\n        # Your custom functionality\n        return result\n```\n\n### API Integration\n```python\nfrom ellma import ELLMa\n\n# Use ELLMa programmatically\nagent = ELLMa()\nresult = agent.execute(\"system.scan\")\ncode = agent.generate(\"python\", task=\"Data analysis script\")\n```\n\n### Web Interface (Optional)\n```bash\n# Install web dependencies\npip install ellma[web]\n\n# Start web interface\nellma web --port 8000\n```\n\n## 🛣️ Roadmap\n\n### Version 0.1.6 - MVP ✅\n- [x] Core agent with Mistral 7B\n- [x] Basic command system\n- [x] Shell interface\n- [x] Evolution foundation\n\n### Version 0.2.0 - Enhanced Shell\n- [ ] Advanced command completion\n- [ ] Command history and favorites\n- [ ] Real-time performance monitoring\n- [ ] Module hot-reloading\n\n### Version 0.3.0 - Code Generation\n- [ ] Multi-language code generators\n- [ ] Template system\n- [ ] Code quality analysis\n- [ ] Integration testing\n\n### Version 0.4.0 - Advanced Evolution\n- [ ] Performance-based learning\n- [ ] User feedback integration\n- [ ] Predictive capability development\n- [ ] Module marketplace\n\n### Version 1.0.0 - Autonomous Agent\n- [ ] Full self-management\n- [ ] Advanced reasoning capabilities\n- [ ] Multi-agent coordination\n- [ ] Enterprise features\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n```bash\n# Clone repository\ngit clone https://github.com/wronai/ellma.git\ncd ellma\n\n# Install in development mode\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Run linting\nblack ellma/\nflake8 ellma/\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built on top of [llama-cpp-python](https://github.com/abetlen/llama-cpp-python)\n- Inspired by the vision of autonomous AI agents\n- Powered by the amazing Mistral 7B model\n\n## 📞 Support\n\n- 📖 [Documentation](https://ellma.readthedocs.io/)\n- 🐛 [Issue Tracker](https://github.com/wronai/ellma/issues)\n- 💬 [Discussions](https://github.com/wronai/ellma/discussions)\n- 📧 [Email Support](mailto:support@ellma.dev)\n\n---\n\n**ELLMa: The AI agent that grows with you** 🌱→🌳","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwronai%2Fellma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwronai%2Fellma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwronai%2Fellma/lists"}