Metadata-Version: 2.4
Name: result-parser-agent
Version: 1.1.0
Summary: A deep agent for extracting metrics from raw result files using LangGraph and intelligent parsing
Project-URL: Homepage, https://github.com/Infobellit-Solutions-Pvt-Ltd/result-parser-agent
Project-URL: Repository, https://github.com/Infobellit-Solutions-Pvt-Ltd/result-parser-agent
Project-URL: Documentation, https://github.com/Infobellit-Solutions-Pvt-Ltd/result-parser-agent#readme
Project-URL: Issues, https://github.com/Infobellit-Solutions-Pvt-Ltd/result-parser-agent/issues
Author-email: Akhilreddy <akhil@Infobellit.com>
License: MIT
License-File: LICENSE
Keywords: agent,ai,langgraph,metrics,parsing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.11
Requires-Dist: click>=8.0.0
Requires-Dist: deepagents>=0.0.3
Requires-Dist: langchain-anthropic>=0.1.23
Requires-Dist: langchain-google-genai>=0.1.0
Requires-Dist: langchain-groq>=0.1.0
Requires-Dist: langchain-ollama>=0.1.0
Requires-Dist: langchain-openai>=0.1.0
Requires-Dist: langchain>=0.2.14
Requires-Dist: langgraph>=0.2.6
Requires-Dist: loguru>=0.7.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pytest-asyncio>=1.1.0
Requires-Dist: pytest-cov>=6.2.1
Requires-Dist: pytest>=8.4.1
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: isort>=5.13.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🎯 Results Parser

A powerful, efficient parser for extracting metrics from benchmark result files using workload-specific extraction scripts. The parser automatically analyzes result files and extracts metrics into structured JSON output with high accuracy and reliability.

## 🚀 Features

- **🎯 Script-Based Parsing**: Uses workload-specific extraction scripts for reliable, deterministic metric extraction
- **📁 Flexible Input**: Process single files or entire directories of result files
- **🔧 Workload-Specific Tools**: Dedicated extraction scripts for different benchmark types (FIO, Redis, Nginx, MariaDB/MySQL TPC-H & TPC-C) that automatically extract all available metrics
- **⚙️ MongoDB Integration**: External API-backed workload registry for scalable management
- **📊 Structured Output**: Direct output in Pydantic schemas for easy integration
- **🛠️ Professional CLI**: Comprehensive Typer-based command-line interface with subcommands
- **🔧 Python API**: Easy integration into existing Python applications
- **🔄 Error Recovery**: Robust error handling and retry mechanisms
- **📦 Git-based Scripts**: Secure, efficient script distribution and caching system
- **🔒 Enterprise Security**: SSH authentication, environment variables, and secure defaults

## 📦 Installation

### Quick Install (Recommended)

```bash
pip install result-parser-agent
```

### Development Install

```bash
# Clone the repository
git clone https://github.com/Infobellit-Solutions-Pvt-Ltd/result-parser-agent.git
cd result-parser-agent

# Install with uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
uv pip install -e .

# Or install with pip
pip install -e .
```

## 📋 Configuration

### Environment Variables

Create a `.env` file in your project directory:

```bash
# MongoDB Registry API
REGISTRY_API_BASE_URL=http://your-mongodb-api.com/api/v1

# Script Management
SCRIPTS_BASE_URL=git@github.com:your-org/parser-scripts.git
SCRIPTS_CACHE_DIR=~/.cache/result-parser/scripts
SCRIPTS_CACHE_TTL=3600
```

## 🎯 Quick Start


### 2. Use the CLI

The CLI now supports multiple subcommands for different operations:

#### Parse Results
```bash
# Parse all files in a directory with workload-specific tools
result-parser parse ./benchmark_results --workload fio

# Parse Redis results (scripts automatically extract all available metrics)
result-parser parse ./benchmark_results --workload redis

# Parse a single file
result-parser parse ./results.txt --workload nginx

# Custom output file
result-parser parse ./results/ --workload mariadb_tpch --output my_results.json

# Verbose output
result-parser parse ./results/ --workload mysql_tpcc --verbose
```

#### Manage Registry
```bash
# Show registry information and script cache status
result-parser registry

# Add new workload
result-parser add-workload fio --metrics "random_read_iops,random_write_iops" --description "Storage performance benchmark"

# Update existing workload
result-parser update-workload redis --metrics "SET(requests/sec),GET(requests/sec),DEL(requests/sec)"

# Show workload details
result-parser show-workload nginx
```

#### Manage Script Cache
```bash
# Show cache information
result-parser cache info

# Clear specific workload cache
result-parser cache clear fio

# Clear all caches
result-parser cache clear-all
```

### 3. Use the Python API

```python
from result_parser_agent import ResultsParser

# Initialize parser
parser = ResultsParser()

# Parse results with workload-specific tools (scripts automatically extract all available metrics)
results = await parser.parse_results(
    input_path="./benchmark_results",
    workload="fio"
)

# Output structured data
print(results.json(indent=2))
```

## 📊 How Metrics Extraction Works

The agent now uses a **two-phase approach** for metrics extraction:

### **Phase 1: Automatic Extraction**
- **Scripts are self-sufficient**: Each workload-specific script automatically extracts all available metrics from the data
- **No user input required**: You don't need to specify which metrics to extract when parsing
- **Comprehensive coverage**: Scripts extract all metrics they can find in the data

### **Phase 2: Validation & Reporting**
- **Expected metrics**: Defined in the workload registry for validation purposes
- **Automatic validation**: The agent compares extracted metrics against expected metrics
- **Detailed reporting**: Shows missing metrics, unexpected metrics, and extraction success

### **Example Output**
```bash
📊 Expected metrics for fio: ['random_read_iops', 'random_write_iops']
📈 Extracted metrics: random_read_iops, random_write_iops, sequential_read_mbps
ℹ️  Additional metrics found: sequential_read_mbps
✅ All expected metrics successfully extracted!
```

This approach ensures **maximum flexibility** while maintaining **quality control** through validation.

## 🔧 Supported Workloads

The agent supports various benchmark workloads with dedicated extraction scripts:

| Workload | Description | Example Metrics |
|----------|-------------|-----------------|
| **FIO** | Storage performance benchmark | `random_read_iops`, `random_write_iops`, `sequential_read_mbps` |
| **Redis** | In-memory database benchmark | `SET(requests/sec)`, `GET(requests/sec)` |
| **Nginx** | Web server performance | `Requests/sec`, `Transfer/sec` |
| **MariaDB TPC-H** | Database TPC-H benchmark | `Power@Size`, `Throughput@Size`, `QphH@Size` |
| **MySQL TPC-H** | Database TPC-H benchmark | `Power@Size`, `Throughput@Size`, `QphH@Size` |
| **MariaDB TPC-C** | Database TPC-C benchmark | `tpmC`, `tpmTOTAL` |
| **MySQL TPC-C** | Database TPC-C benchmark | `tpmC`, `tpmTOTAL` |

## 🏗️ Architecture

The parser uses a streamlined architecture focused on workload-specific script execution:

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   CLI Layer     │    │  Results Parser  │    │  Tool Registry  │
│  (Typer CLI)    │◄──►│  (Core Logic)    │◄──►│  (Workloads)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Configuration  │    │  Script Download │    │  Script Cache   │
│  (Pydantic)     │    │   (Git SSH)      │    │   (Local)       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ MongoDB Registry│    │  Result Output   │    │  Extraction     │
│     API         │    │   (JSON)         │    │   Scripts       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

**Key Benefits:**
- **Simplified**: Direct script execution without LLM overhead
- **Faster**: No AI processing delays
- **Reliable**: Deterministic script-based extraction
- **Maintainable**: Clear separation of concerns

## 🛠️ CLI Commands Reference

### `parse` - Parse Benchmark Results
```bash
result-parser parse <input_path> [OPTIONS]

Arguments:
  input_path              Path to results file or directory

Options:
  --workload TEXT         Workload type (fio, redis, nginx, mariadb_tpch, etc.)
  --output TEXT           Output file path [default: results.json]
  --verbose               Enable verbose logging
  --help                  Show this message and exit
```

### `registry` - Show Registry Information
```bash
result-parser registry

Shows:
- Registry source (API + Git Scripts)
- Available workloads
- Script cache status
- Cache directory information
```

### `cache` - Manage Script Cache
```bash
result-parser cache <action> [workload]

Actions:
  info                    Show cache information
  clear [workload]        Clear specific or all caches
  clear-all               Clear all caches
```

### `add-workload` - Add New Workload
```bash
result-parser add-workload <name> [OPTIONS]

Arguments:
  name                    Workload name

Options:
  --metrics TEXT          Comma-separated list of expected metrics [required]
  --script TEXT           Script filename [default: extractor.sh]
  --description TEXT      Workload description
  --status TEXT           Workload status (active/inactive) [default: active]
```

**Note**: The `--metrics` parameter defines the expected metrics for validation purposes. The actual extraction scripts will automatically extract all available metrics from the data.

### `update-workload` - Update Existing Workload
```bash
result-parser update-workload <name> [OPTIONS]

Arguments:
  name                    Workload name

Options:
  --metrics TEXT          Comma-separated list of expected metrics
  --script TEXT           Script filename
  --description TEXT      Workload description
  --status TEXT           Workload status (active/inactive)
```

**Note**: The `--metrics` parameter updates the expected metrics for validation purposes. The actual extraction scripts will automatically extract all available metrics from the data.

### `show-workload` - Show Workload Details
```bash
result-parser show-workload <name>

Arguments:
  name                    Workload name to display
```

## 🔒 Security Features

- **SSH Authentication**: Secure access to private Git repositories
- **Environment Variables**: No hardcoded secrets or API keys
- **Input Validation**: Comprehensive validation of all user inputs
- **Secure Defaults**: Principle of least privilege in configuration
- **Script Isolation**: Scripts run in controlled environment

## 🚀 Performance Features

- **Script Caching**: Local cache with TTL-based invalidation
- **Sparse Git Operations**: Efficient individual script retrieval
- **Lazy Loading**: Scripts downloaded only when needed
- **Optimized API Calls**: Efficient MongoDB API interactions

## 🧪 Testing

Run the test suite to ensure everything works correctly:

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/result_parser_agent

# Run specific test file
uv run pytest tests/test_cli.py
```

## 📚 Development

### Code Quality
```bash
# Format code
uv run black .

# Sort imports
uv run isort .

# Lint code
uv run ruff check .

# Type checking
uv run mypy src/
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## 📄 License

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

## 🆘 Support

- **Documentation**: [GitHub Wiki](https://github.com/Infobellit-Solutions-Pvt-Ltd/result-parser-agent/wiki)
- **Issues**: [GitHub Issues](https://github.com/Infobellit-Solutions-Pvt-Ltd/result-parser-agent/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Infobellit-Solutions-Pvt-Ltd/result-parser-agent/discussions)

## 🏆 Acknowledgments

- Powered by [Typer](https://typer.tiangolo.com/) for CLI development
- Enhanced with [Pydantic](https://pydantic.dev/) for data validation
- Script management powered by Git and SSH
- Built with Python async/await for efficient processing
