Metadata-Version: 2.4
Name: merlya
Version: 0.3.0
Summary: AI-powered infrastructure orchestration CLI - Vibe Infra for DevOps
License: MIT-Commons-Clause
License-File: LICENSE
Keywords: cli,infrastructure,devops,ai,automation,ssh,autogen,llm,ops
Author: Merlya Contributors
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Provides-Extra: all
Provides-Extra: knowledge
Provides-Extra: smart-triage
Requires-Dist: ansible-runner (>=2.4,<3.0)
Requires-Dist: anthropic (>=0.70,<0.71)
Requires-Dist: beautifulsoup4 (>=4.12,<5.0)
Requires-Dist: click (>=8.1,<9.0)
Requires-Dist: cryptography (>=44.0,<45.0)
Requires-Dist: duckduckgo-search (>=8.0,<9.0) ; extra == "knowledge" or extra == "all"
Requires-Dist: fabric (>=3.2,<4.0)
Requires-Dist: falkordb (>=1.2,<2.0) ; extra == "knowledge" or extra == "smart-triage" or extra == "all"
Requires-Dist: jinja2 (>=3.1,<4.0)
Requires-Dist: keyring (>=25.5,<26.0)
Requires-Dist: litellm (>=1.80,<2.0)
Requires-Dist: loguru (>=0.7,<0.8)
Requires-Dist: netmiko (>=4.4,<5.0)
Requires-Dist: openai (>=2.0,<3.0)
Requires-Dist: openai-agents (>=0.6.0,<0.7.0)
Requires-Dist: paramiko (>=4.0,<5.0)
Requires-Dist: prompt_toolkit (>=3.0,<4.0)
Requires-Dist: psycopg2-binary (>=2.9,<3.0)
Requires-Dist: pyautogen (>=0.10.0,<0.11.0)
Requires-Dist: pydantic (>=2.12,<3.0)
Requires-Dist: pymongo (>=4.10,<5.0)
Requires-Dist: pymysql (>=1.1,<2.0)
Requires-Dist: python-dotenv (>=1.0,<2.0)
Requires-Dist: python-terraform (>=0.10,<0.11)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: redis (>=5.2,<6.0)
Requires-Dist: requests (>=2.32,<3.0)
Requires-Dist: rich (>=14.0,<15.0)
Requires-Dist: sentence-transformers (>=5.1,<6.0) ; extra == "smart-triage" or extra == "all"
Requires-Dist: sqlalchemy (>=2.0,<3.0)
Requires-Dist: tenacity (>=9.0,<10.0)
Project-URL: Documentation, https://github.com/m-kis/merlya#readme
Project-URL: Homepage, https://github.com/m-kis/merlya
Project-URL: Repository, https://github.com/m-kis/merlya
Description-Content-Type: text/markdown

# Merlya

**AI-powered infrastructure orchestration CLI** - A natural language interface for managing your infrastructure.

## Features

- Natural language queries for infrastructure management
- Multi-LLM support (OpenRouter, Anthropic, OpenAI, Ollama)
- SSH execution with your existing credentials (`~/.ssh/config`, `ssh-agent`)
- Interactive REPL with conversation memory
- Extensible slash commands and hooks system
- Host validation to prevent hallucinated commands
- Risk assessment for dangerous operations

## Installation

```bash
# Basic installation (core features only)
poetry install

# With knowledge graph support (DuckDuckGo search, FalkorDB)
poetry install -E knowledge

# With smart error triage (ML-based error classification)
poetry install -E smart-triage

# Full installation (all features)
poetry install -E all
```

### Installation Extras

| Extra | Dependencies | Features |
|-------|-------------|----------|
| `knowledge` | `duckduckgo-search`, `falkordb` | Web search, knowledge graph storage |
| `smart-triage` | `sentence-transformers`, `falkordb` | ML-based error classification, semantic tool selection |
| `all` | All of the above | Full feature set |

### With pip

```bash
pip install .                    # Basic
pip install ".[knowledge]"       # With knowledge graph
pip install ".[smart-triage]"    # With ML error triage
pip install ".[all]"             # Everything
```

## Quick Start

```bash
# Configure your LLM provider
export OPENROUTER_API_KEY="sk-or-..."
# or ANTHROPIC_API_KEY, OPENAI_API_KEY, OLLAMA_HOST

# Launch interactive REPL (default)
merlya

# Or run a single query
merlya ask "list all mongo hosts"
```

## Usage

### Interactive Mode (REPL)

```bash
$ merlya

Merlya REPL - Type /help for commands

> list mongo preprod IPs
MongoDB Preprod hosts:
  - mongo-preprod-1: 203.0.113.10
  - mongo-preprod-2: 198.51.100.20

> check if mongodb is running on mongo-preprod-1
Checking mongodb status...
[SSH] systemctl status mongod
mongod.service - MongoDB Database Server
   Active: active (running)

> /scan --full
Scanning all hosts...

> /help
```

### Single Query Mode

```bash
# Simple query
merlya ask "what services are running on web-prod-1"

# Dry-run (see plan without executing)
merlya ask "restart nginx on lb-prod-1" --dry-run

# Auto-confirm critical actions
merlya ask "restart mongodb" --confirm
```

### Slash Commands

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/scan` | Scan infrastructure |
| `/scan --full` | Full SSH scan of all hosts |
| `/hosts` | List known hosts |
| `/variables set <key> <value>` | Set a variable |
| `/variables set-secret <key>` | Set a secret (hidden input) |
| `/model list` | List available models |
| `/model set <provider> <model>` | Switch LLM model |
| `/clear` | Clear conversation |
| `/exit` | Exit REPL |

### Custom Commands

Create markdown files in `~/.merlya/commands/` or `.merlya/commands/`:

```markdown
---
name: healthcheck
description: Run health check on a host
aliases: [hc, health]
---

Perform health check on {{$1}}:
- Check CPU, memory, disk
- List running services
- Check for errors in logs
```

Then use: `/healthcheck web-prod-1`

## Configuration

### LLM Providers

```bash
# OpenRouter (recommended - multiple models)
export OPENROUTER_API_KEY="sk-or-..."
export OPENROUTER_MODEL="anthropic/claude-sonnet-4"

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# Ollama (local/offline)
export OLLAMA_HOST="http://localhost:11434"
export OLLAMA_MODEL="llama3"
```

### SSH Configuration

Merlya uses your existing SSH setup:

```ssh
# ~/.ssh/config
Host mongo-*
    User mongodb-admin
    IdentityFile ~/.ssh/id_mongo

Host *.prod
    User ops
    IdentityFile ~/.ssh/id_prod
```

### Inventory Sources

Merlya discovers hosts from:
- `/etc/hosts`
- `~/.ssh/config`
- SSH scanning
- Custom inventory files (`~/.merlya/inventory.yaml`)

## Architecture

```
User Query
    |
    v
+-------------------+
|   REPL / CLI      |
+-------------------+
    |
    v
+-------------------+
|   Orchestrator    |  <- AutoGen/AG2 multi-agent
+-------------------+
    |
    v
+-------------------+
|   LLM Router      |  <- OpenRouter, Anthropic, OpenAI, Ollama
+-------------------+
    |
    v
+-------------------+
|  Context Manager  |  <- Host registry, SSH scan results
+-------------------+
    |
    v
+-------------------+
|  SSH Executor     |  <- Connection pooling, error correction
+-------------------+
```

## Security

### Risk Assessment

Commands are evaluated before execution:
- **Low**: read-only (ps, cat, df) - auto-execute
- **Moderate**: config changes (chmod) - prompt confirmation
- **Critical**: destructive (rm, reboot, stop) - requires `--confirm`

### Host Validation

All commands are validated against the host registry. Operations on unknown/hallucinated hostnames are blocked.

### Credential Management

When authentication errors occur (MongoDB, MySQL, PostgreSQL, SSH), Merlya:

1. **Detects the error** - Classifies it as a credential issue with confidence score
2. **Prompts the user** - Asks for username/password via secure input (getpass)
3. **Caches credentials** - Stores in-memory with 15-minute TTL
4. **Retries automatically** - Re-executes the command with new credentials

```bash
# Example flow
> check mongodb status on db-prod-01

🔐 Authentication required for:
   Service: MongoDB
   Target: db-prod-01
   Error: Authentication failed

Would you like to provide credentials? (yes/no)
> yes
   Username: admin
   Password: ****

✅ Credentials stored successfully! (TTL: 15 minutes)
```

Credentials are:

- Never persisted to disk
- Never logged (even in debug mode)
- Validated against injection attacks
- Available as `@mongodb-user` / `@mongodb-pass` variables

### Audit Trail

All actions logged to `~/.merlya/merlya.log`

## Optional Features

### Knowledge Graph (FalkorDB)

```bash
# Install with knowledge support
pip install ".[knowledge]"

# Start FalkorDB
docker run -p 6379:6379 falkordb/falkordb

# Enable in Merlya
export FALKORDB_HOST="localhost"
```

### Hooks

Create `~/.merlya/hooks.yaml` to intercept tool executions:

```yaml
hooks:
  tool_execute_start:
    - name: audit
      action: log
      config:
        file: /var/log/merlya-audit.log
```

## Development

```bash
# Install dev dependencies
poetry install

# Run tests
pytest

# Type checking
mypy merlya
```

## License

**MIT License with Commons Clause** - See [LICENSE](LICENSE)

This software is free to use for personal, educational, and community purposes.

**Commercial use, sale, for-profit redistribution, or integration into a paid product/service is strictly prohibited without written permission from the author, Cédric Merlin and M-KIS.**

For commercial licensing inquiries, please contact the author.

