docs: add cross-platform build scripts and install guide

INSTALL.md

@@ -0,0 +1,97 @@
+# Installing AgentEval
+
+## From Maven Central
+
+Add the dependencies to your project:
+
+### Maven
+
+```xml
+<dependency>
+    <groupId>org.byteveda.agenteval</groupId>
+    <artifactId>agenteval-junit5</artifactId>
+    <version>0.1.0-SNAPSHOT</version>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>org.byteveda.agenteval</groupId>
+    <artifactId>agenteval-metrics</artifactId>
+    <version>0.1.0-SNAPSHOT</version>
+    <scope>test</scope>
+</dependency>
+```
+
+### Gradle
+
+```kotlin
+testImplementation("org.byteveda.agenteval:agenteval-junit5:0.1.0-SNAPSHOT")
+testImplementation("org.byteveda.agenteval:agenteval-metrics:0.1.0-SNAPSHOT")
+```
+
+---
+
+## Building from Source
+
+If you prefer to build and install AgentEval locally instead of pulling from Maven Central:
+
+### Prerequisites
+
+- **Java 21+** — the only requirement. Maven is bundled via the wrapper.
+
+### Clone and Install
+
+```bash
+git clone https://github.com/ByteVeda/agenteval.git
+cd agenteval
+```
+
+**Linux / macOS:**
+
+```bash
+./scripts/install.sh                # Quick install (skips tests)
+./scripts/install.sh --with-tests   # Install with tests
+./scripts/install.sh --skip-javadoc # Skip javadoc for faster builds
+./scripts/install.sh --help         # Show all options
+```
+
+**Windows:**
+
+```cmd
+scripts\install.bat                 REM Quick install (skips tests)
+scripts\install.bat /with-tests     REM Install with tests
+scripts\install.bat /skip-javadoc   REM Skip javadoc for faster builds
+scripts\install.bat /help           REM Show all options
+```
+
+The scripts use the bundled Maven wrapper, so no separate Maven installation is needed. Artifacts are installed to your local Maven repository (`~/.m2/repository`).
+
+### Manual Build (without scripts)
+
+You can also build directly with the Maven wrapper:
+
+```bash
+./mvnw clean install -DskipTests                          # Linux / macOS
+mvnw.cmd clean install -DskipTests                        # Windows
+```
+
+---
+
+## Verifying the Installation
+
+After installing, verify the artifacts are in your local Maven repository:
+
+```bash
+ls ~/.m2/repository/org/byteveda/agenteval/
+```
+
+You should see directories for each module (`agenteval-core`, `agenteval-metrics`, etc.).
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| Java        | 21+     |
+| Maven       | 3.9+ (bundled via wrapper) |
+| Gradle      | 8.5+ (if using Gradle to consume the library) |

README.md

@@ -370,6 +370,12 @@ mvn test -pl agenteval-core    # Test specific module
 
 ---
 
+## Building from Source
+
+See [INSTALL.md](INSTALL.md) for full instructions on building from source, including cross-platform install scripts.
+
+---
+
 ## Requirements
 
 - Java 21+

scripts/install.bat

@@ -0,0 +1,131 @@
+@echo off
+REM ──────────────────────────────────────────────────────────────────────────
+REM AgentEval - Local Build & Install Script (Windows)
+REM
+REM Builds all modules and installs them to your local Maven repository.
+REM Requires: Java 21+
+REM
+REM Usage:
+REM   scripts\install.bat [OPTIONS]
+REM
+REM Options:
+REM   /with-tests     Run tests during the build (default: tests are skipped)
+REM   /skip-javadoc   Skip Javadoc generation for faster builds
+REM   /help           Show this help message
+REM ──────────────────────────────────────────────────────────────────────────
+
+setlocal enabledelayedexpansion
+
+REM ── Resolve project root (parent of scripts\) ────────────────────────────
+set "SCRIPT_DIR=%~dp0"
+pushd "%SCRIPT_DIR%.."
+set "PROJECT_ROOT=%cd%"
+popd
+
+REM ── Defaults ──────────────────────────────────────────────────────────────
+set "SKIP_TESTS=true"
+set "SKIP_JAVADOC=false"
+
+REM ── Parse arguments ───────────────────────────────────────────────────────
+:parse_args
+if "%~1"=="" goto :check_java
+if /I "%~1"=="/with-tests" (
+    set "SKIP_TESTS=false"
+    shift
+    goto :parse_args
+)
+if /I "%~1"=="/skip-javadoc" (
+    set "SKIP_JAVADOC=true"
+    shift
+    goto :parse_args
+)
+if /I "%~1"=="/help" goto :usage
+if /I "%~1"=="--help" goto :usage
+echo Unknown option: %~1
+echo Run 'scripts\install.bat /help' for usage.
+exit /b 1
+
+:usage
+echo.
+echo AgentEval - Local Build ^& Install
+echo.
+echo Builds all modules and installs them to your local Maven repository.
+echo Requires: Java 21+
+echo.
+echo Usage:
+echo   scripts\install.bat [OPTIONS]
+echo.
+echo Options:
+echo   /with-tests     Run tests during the build (default: tests are skipped)
+echo   /skip-javadoc   Skip Javadoc generation for faster builds
+echo   /help           Show this help message
+echo.
+echo Examples:
+echo   scripts\install.bat                    Quick install (skip tests)
+echo   scripts\install.bat /with-tests        Install with tests
+echo   scripts\install.bat /skip-javadoc      Skip javadoc generation
+exit /b 0
+
+REM ── Check Java ────────────────────────────────────────────────────────────
+:check_java
+where java >nul 2>&1
+if %errorlevel% neq 0 (
+    echo Error: Java is not installed or not on PATH.
+    echo AgentEval requires Java 21 or later.
+    exit /b 1
+)
+
+for /f "tokens=3" %%i in ('java -version 2^>^&1 ^| findstr /i "version"') do (
+    set "JAVA_VER_RAW=%%~i"
+)
+for /f "tokens=1 delims=." %%a in ("!JAVA_VER_RAW!") do set "JAVA_VERSION=%%a"
+
+if !JAVA_VERSION! lss 21 (
+    echo Error: Java 21+ is required (found Java !JAVA_VERSION!).
+    exit /b 1
+)
+
+REM ── Build Maven arguments ─────────────────────────────────────────────────
+set "MVN_ARGS=clean install"
+
+if "!SKIP_TESTS!"=="true" (
+    set "MVN_ARGS=!MVN_ARGS! -DskipTests"
+)
+
+if "!SKIP_JAVADOC!"=="true" (
+    set "MVN_ARGS=!MVN_ARGS! -Dmaven.javadoc.skip=true"
+)
+
+REM ── Run build ─────────────────────────────────────────────────────────────
+echo ========================================
+echo  AgentEval - Local Install
+echo ========================================
+echo  Java version : !JAVA_VERSION!
+echo  Skip tests   : !SKIP_TESTS!
+echo  Skip javadoc : !SKIP_JAVADOC!
+echo  Project root : %PROJECT_ROOT%
+echo ========================================
+echo.
+
+cd /d "%PROJECT_ROOT%"
+
+if not exist "mvnw.cmd" (
+    echo Error: Maven wrapper (mvnw.cmd) not found in project root.
+    exit /b 1
+)
+
+call mvnw.cmd !MVN_ARGS!
+
+if %errorlevel% neq 0 (
+    echo.
+    echo Build failed. See output above for details.
+    exit /b %errorlevel%
+)
+
+echo.
+echo ========================================
+echo  Install complete!
+echo  Artifacts are in: %%USERPROFILE%%\.m2\repository\org\byteveda\agenteval\
+echo ========================================
+
+endlocal

scripts/install.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+#
+# AgentEval - Local Build & Install Script (Linux / macOS)
+#
+# Builds all modules and installs them to your local Maven repository (~/.m2/repository).
+# Requires: Java 21+
+#
+# Usage:
+#   ./scripts/install.sh [OPTIONS]
+#
+# Options:
+#   --with-tests     Run tests during the build (default: tests are skipped)
+#   --skip-javadoc   Skip Javadoc generation for faster builds
+#   --help           Show this help message
+#
+
+set -euo pipefail
+
+# ── Resolve project root (parent of scripts/) ──────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# ── Defaults ────────────────────────────────────────────────────────────────
+SKIP_TESTS=true
+SKIP_JAVADOC=false
+
+# ── Parse arguments ─────────────────────────────────────────────────────────
+usage() {
+    cat <<EOF
+AgentEval - Local Build & Install
+
+Builds all modules and installs them to your local Maven repository (~/.m2/repository).
+Requires: Java 21+
+
+Usage:
+  ./scripts/install.sh [OPTIONS]
+
+Options:
+  --with-tests     Run tests during the build (default: tests are skipped)
+  --skip-javadoc   Skip Javadoc generation for faster builds
+  --help           Show this help message
+
+Examples:
+  ./scripts/install.sh                     # Quick install (skip tests & javadoc)
+  ./scripts/install.sh --with-tests        # Install with tests
+  ./scripts/install.sh --skip-javadoc      # Skip javadoc generation
+EOF
+    exit 0
+}
+
+for arg in "$@"; do
+    case "$arg" in
+        --with-tests)   SKIP_TESTS=false ;;
+        --skip-javadoc) SKIP_JAVADOC=true ;;
+        --help)         usage ;;
+        *)
+            echo "Unknown option: $arg"
+            echo "Run './scripts/install.sh --help' for usage."
+            exit 1
+            ;;
+    esac
+done
+
+# ── Check Java ──────────────────────────────────────────────────────────────
+if ! command -v java &>/dev/null; then
+    echo "Error: Java is not installed or not on PATH."
+    echo "AgentEval requires Java 21 or later."
+    exit 1
+fi
+
+JAVA_VERSION=$(java -version 2>&1 | head -n1 | sed -E 's/.*"([0-9]+).*/\1/')
+if [ "$JAVA_VERSION" -lt 21 ] 2>/dev/null; then
+    echo "Error: Java 21+ is required (found Java $JAVA_VERSION)."
+    exit 1
+fi
+
+# ── Build Maven arguments ──────────────────────────────────────────────────
+MVN_ARGS="clean install"
+
+if [ "$SKIP_TESTS" = true ]; then
+    MVN_ARGS="$MVN_ARGS -DskipTests"
+fi
+
+if [ "$SKIP_JAVADOC" = true ]; then
+    MVN_ARGS="$MVN_ARGS -Dmaven.javadoc.skip=true"
+fi
+
+# ── Run build ───────────────────────────────────────────────────────────────
+echo "========================================"
+echo " AgentEval - Local Install"
+echo "========================================"
+echo " Java version : $JAVA_VERSION"
+echo " Skip tests   : $SKIP_TESTS"
+echo " Skip javadoc : $SKIP_JAVADOC"
+echo " Project root : $PROJECT_ROOT"
+echo "========================================"
+echo ""
+
+cd "$PROJECT_ROOT"
+
+# Use the Maven wrapper (no Maven installation required)
+if [ ! -f "./mvnw" ]; then
+    echo "Error: Maven wrapper (mvnw) not found in project root."
+    exit 1
+fi
+
+chmod +x ./mvnw
+./mvnw $MVN_ARGS
+
+echo ""
+echo "========================================"
+echo " Install complete!"
+echo " Artifacts are in: ~/.m2/repository/org/byteveda/agenteval/"
+echo "========================================"