Minerva - Ansible Error Diagnosis Tool

minerva is a Python-based CLI tool that uses LangGraph to create a simple workflow for processing JSON errors from Red Hat Ansible Automation Controllers by passing them to an LLM with a systems prompt for diagnosis.

Features

• ✨ LLM-Powered Diagnosis: Uses OpenAI's GPT models to analyze and diagnose Ansible automation errors
• 🔄 LangGraph Workflow: Simple, clear workflow processing with LangGraph
• 📊 Structured Output: Pydantic-based models ensure consistent, validated diagnostic outputs
• 🖥️ CLI Interface: Easy-to-use command-line interface powered by Typer
• 📝 JSON Processing: Processes error events from Red Hat Ansible Automation Controllers

Quick Start

Prerequisites

• Python 3.13+
• uv package manager (recommended) or standard Python venv

Installation

1. Clone the repository

   git clone https://github.com/example/jaii-langgraph-minerva.git
   cd jaii-langgraph-minerva

2. Create and activate virtual environment

   Using uv (recommended):

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

   Or using standard Python:

   python3.13 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

   uv pip install -e .

4. Install development dependencies (optional)

   uv pip install -e ".[dev]"

Configuration

Set your OpenAI API key:

export OPENAI_API_KEY="your-api-key-here"

Usage

Process a single error event:

uv run minerva diagnose events/1364477456.json

Process multiple error events with verbose output:

uv run minerva diagnose events/ --verbose

Show version:

uv run minerva version

Get help:

uv run minerva --help

Development

Project Structure

jaii-langgraph-minerva/
├── src/minerva/           # Main package source
│   ├── __init__.py        # Package initialization
│   ├── cli.py             # CLI interface
│   ├── basemodels.py      # Pydantic models (to be created)
│   ├── workflow.py        # LangGraph workflow (to be created)
│   └── utils.py           # Utility functions (to be created)
├── tests/                 # Test suite
├── events/                # Sample error events (gitignored)
├── data/                  # Data files (gitignored)
├── spec/                  # Requirements and specifications
├── pyproject.toml         # Project configuration
├── README.md              # This file
└── .gitignore             # Git ignore rules

Development Workflow

1. Install development dependencies

   uv pip install -e ".[dev]"

2. Run tests

   uv run pytest

3. Code formatting and linting

   uv run ruff check .
   uv run ruff format .

Architecture

The tool follows a simple architecture:

1. Input: JSON error events from Ansible Automation Controllers
2. Processing: LangGraph workflow that:
   • Loads and validates error events using Pydantic models
   • Sends structured prompts to OpenAI's GPT models
   • Processes LLM responses into structured diagnostic outputs
3. Output: Structured diagnosis with confidence levels

Key Components

• ErrorTask: Pydantic model for original error events (to be implemented)
• ErrorDiagnosis: Pydantic model for LLM diagnostic outputs (to be implemented)
• LangGraph Workflow: Simple processing pipeline (to be implemented)
• CLI Interface: User-friendly command-line tool ✅

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the coding standards
4. Run tests and ensure they pass
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Coding Standards

• Follow Python 3.13+ standards
• Use type hints throughout
• Follow the project's Ruff configuration
• Write comprehensive tests with pytest
• Document functions and classes with docstrings
• Keep code modular and well-structured

License

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

Acknowledgments

• Built with LangGraph for workflow management
• Uses OpenAI for LLM capabilities
• Pydantic for data validation
• Typer for CLI interface