result-parser-agent 1.2.0

A deep agent for extracting metrics from raw result files using LangGraph and intelligent parsing

🎯 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)

pip install result-parser-agent

Development Install

# 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:

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

# Script Management
SCRIPTS_BASE_URL=[e-mail]: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

# 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

# Show cached workloads (cache-first, no API calls)
result-parser registry

# Show all workloads including registry (with API calls)
result-parser registry --include-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

# 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

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))

🚀 Cache-First Architecture

The CLI tool now uses a cache-first approach for better performance and offline capability:

Local Cache Priority

• No API calls by default: The CLI first checks local cache for available workload scripts
• Fast startup: No network delays when using cached workloads
• Offline capability: Works without internet connection for cached workloads
• Explicit registry access: Use --include-registry flag to check registry API

Smart Workload Discovery

• Cache-first validation: When parsing, checks local cache first
• Auto-download: If workload not in cache, automatically downloads from registry
• Registry info: Use registry --include-registry to see all available workloads

📊 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

📊 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

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

result-parser registry

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

cache - Manage Script Cache

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

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

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

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:

# 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

# 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 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 file for details.

🆘 Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🏆 Acknowledgments

• Powered by Typer for CLI development
• Enhanced with Pydantic for data validation
• Script management powered by Git and SSH
• Built with Python async/await for efficient processing