Add startup scripts for server and client on macOS/Linux and Windows

README.md

@@ -42,6 +42,23 @@ Neuro SAN also offers:
     * an Assessor app which classifies the modes of failure for your agents, given a data-driven test case
 * MCP protocol API
 
+## Quick Start
+
+**🚀 For the easiest way to get started, use our automated startup scripts!**
+
+See the [startup/README.md](startup/README.md) for simple one-command scripts that handle all setup automatically:
+- **macOS/Linux:** `./startup/start-server.sh`
+- **Windows:** `startup\start-server.bat`
+
+These scripts automatically:
+- Create and activate virtual environment
+- Install all dependencies
+- Set up environment variables
+- Enable CORS for web applications
+- Launch the server
+
+For manual setup, continue with the instructions below.
+
 ## Running client and server
 
 ### Prep

startup/README.md

@@ -0,0 +1,136 @@
+# Neuro-SAN Startup Scripts
+
+This folder contains easy-to-use startup scripts for launching the Neuro-SAN server and client on different operating systems.
+
+## Quick Start
+
+### macOS / Linux
+
+**Start the server:**
+```bash
+chmod +x startup/start-server.sh
+./startup/start-server.sh
+```
+
+**Start the client (in another terminal):**
+```bash
+chmod +x startup/start-client.sh
+./startup/start-client.sh
+```
+
+### Windows
+
+**Start the server:**
+```cmd
+startup\start-server.bat
+```
+
+**Start the client (in another terminal):**
+```cmd
+startup\start-client.bat
+```
+
+## What These Scripts Do
+
+### Server Scripts (`start-server.sh` / `start-server.bat`)
+
+1. ✅ Check for virtual environment (create if missing)
+2. ✅ Activate virtual environment
+3. ✅ Set PYTHONPATH
+4. ✅ Install dependencies (if not already installed)
+5. ✅ Enable CORS headers (for web applications)
+6. ✅ Check for API keys (warns if missing)
+7. ✅ Start the Neuro-SAN server on port 8080
+
+### Client Scripts (`start-client.sh` / `start-client.bat`)
+
+1. ✅ Activate virtual environment
+2. ✅ Set PYTHONPATH
+3. ✅ Start the CLI client with specified agent
+
+## Client Usage
+
+### Direct Mode (No Server Required)
+```bash
+# macOS/Linux
+./startup/start-client.sh hello_world
+
+# Windows
+startup\start-client.bat hello_world
+```
+
+### Server Mode (Connects to Running Server)
+```bash
+# macOS/Linux
+./startup/start-client.sh hello_world --http
+
+# Windows
+startup\start-client.bat hello_world --http
+```
+
+## Available Agents
+
+Based on the server logs, you can use any of these agents:
+- `hello_world` - Simple greeting agent (default)
+- `copy_cat` - Echo agent
+- `math_guy` - Math operations
+- `date_time` - Current date and time
+- `music_nerd` - Music-related queries
+- `gist` - Terse announcements
+- And many more...
+
+## Environment Variables
+
+### Required
+- `OPENAI_API_KEY` - Your OpenAI API key
+
+### Optional
+- `AGENT_HTTP_PORT` - Server port (default: 8080)
+- `AGENT_SERVER_NAME` - Server name for health reporting
+- Other provider API keys (AWS, Azure, Anthropic, etc.)
+
+### Setting Environment Variables
+
+**macOS/Linux:**
+```bash
+export OPENAI_API_KEY="your-key-here"
+```
+
+**Windows:**
+```cmd
+set OPENAI_API_KEY=your-key-here
+```
+
+## Troubleshooting
+
+### Port Already in Use
+If you see "Address already in use" error:
+```bash
+# macOS/Linux
+lsof -i :8080
+kill <PID>
+
+# Windows
+netstat -ano | findstr :8080
+taskkill /PID <PID> /F
+```
+
+### Virtual Environment Issues
+Delete the `.venv` or `venv` folder and run the script again to recreate it.
+
+### Missing Dependencies
+The scripts automatically install dependencies, but you can manually run:
+```bash
+pip install -r requirements.txt
+```
+
+## Server Endpoints
+
+Once the server is running:
+- **Server URL:** http://localhost:8080
+- **Health Check:** http://localhost:8080/health
+- **API endpoints:** See the OpenAPI spec for details
+
+## Stopping the Server
+
+Press `Ctrl+C` in the terminal where the server is running.

startup/start-client.bat

@@ -0,0 +1,64 @@
+@echo off
+REM Neuro-SAN Client Startup Script for Windows
+REM This script starts the neuro-san CLI client
+
+setlocal enabledelayedexpansion
+
+echo ===============================================
+echo   Neuro-SAN Client Startup
+echo ===============================================
+echo.
+
+REM Get the directory where this script is located
+set SCRIPT_DIR=%~dp0
+set PROJECT_DIR=%SCRIPT_DIR%..
+cd /d "%PROJECT_DIR%"
+
+REM Activate virtual environment
+if exist ".venv" (
+    set VENV_DIR=.venv
+) else if exist "venv" (
+    set VENV_DIR=venv
+) else (
+    echo Virtual environment not found!
+    echo Please run start-server.bat first to set up the environment.
+    pause
+    exit /b 1
+)
+
+echo Activating virtual environment...
+call "%VENV_DIR%\Scripts\activate.bat"
+if errorlevel 1 (
+    echo Failed to activate virtual environment
+    pause
+    exit /b 1
+)
+echo Virtual environment activated
+echo.
+
+REM Set PYTHONPATH
+set PYTHONPATH=%PROJECT_DIR%
+
+REM Get agent name from command line argument or use default
+set AGENT_NAME=%1
+if "%AGENT_NAME%"=="" set AGENT_NAME=hello_world
+
+REM Check if connecting to server or running direct
+if "%2"=="--server" goto server_mode
+if "%2"=="--http" goto server_mode
+goto direct_mode
+
+:server_mode
+echo Connecting to server mode...
+echo Make sure the server is running (start-server.bat)
+echo.
+python -m neuro_san.client.agent_cli --http --agent %AGENT_NAME%
+goto end
+
+:direct_mode
+echo Running in direct mode (no server)...
+echo.
+python -m neuro_san.client.agent_cli --agent %AGENT_NAME%
+
+:end
+pause

startup/start-client.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Neuro-SAN Client Startup Script for macOS/Linux
+# This script starts the neuro-san CLI client
+
+set -e
+
+echo "==============================================="
+echo "  Neuro-SAN Client Startup"
+echo "==============================================="
+echo ""
+
+# Get the directory where this script is located
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$PROJECT_DIR"
+
+# Activate virtual environment
+if [ -d ".venv" ]; then
+    VENV_DIR=".venv"
+elif [ -d "venv" ]; then
+    VENV_DIR="venv"
+else
+    echo "❌ Virtual environment not found!"
+    echo "Please run start-server.sh first to set up the environment."
+    exit 1
+fi
+
+echo "Activating virtual environment..."
+source "$VENV_DIR/bin/activate"
+echo "✅ Virtual environment activated"
+echo ""
+
+# Set PYTHONPATH
+export PYTHONPATH="$PROJECT_DIR"
+
+# Get agent name from command line argument or use default
+AGENT_NAME="${1:-hello_world}"
+
+# Check if connecting to server or running direct
+if [ "$2" = "--server" ] || [ "$2" = "--http" ]; then
+    echo "Connecting to server mode..."
+    echo "Make sure the server is running (start-server.sh)"
+    echo ""
+    python -m neuro_san.client.agent_cli --http --agent "$AGENT_NAME"
+else
+    echo "Running in direct mode (no server)..."
+    echo ""
+    python -m neuro_san.client.agent_cli --agent "$AGENT_NAME"
+fi

startup/start-server.bat

@@ -0,0 +1,95 @@
+@echo off
+REM Neuro-SAN Server Startup Script for Windows
+REM This script handles all necessary steps to launch the neuro-san server
+
+setlocal enabledelayedexpansion
+
+echo ===============================================
+echo   Neuro-SAN Server Startup
+echo ===============================================
+echo.
+
+REM Get the directory where this script is located
+set SCRIPT_DIR=%~dp0
+set PROJECT_DIR=%SCRIPT_DIR%..
+cd /d "%PROJECT_DIR%"
+
+echo Project directory: %PROJECT_DIR%
+echo.
+
+REM Check if virtual environment exists
+if not exist "venv" if not exist ".venv" (
+    echo Virtual environment not found!
+    echo Creating virtual environment...
+    python -m venv .venv
+    if errorlevel 1 (
+        echo Failed to create virtual environment
+        pause
+        exit /b 1
+    )
+    echo Virtual environment created
+    echo.
+)
+
+REM Activate virtual environment
+if exist ".venv" (
+    set VENV_DIR=.venv
+) else (
+    set VENV_DIR=venv
+)
+
+echo Activating virtual environment...
+call "%VENV_DIR%\Scripts\activate.bat"
+if errorlevel 1 (
+    echo Failed to activate virtual environment
+    pause
+    exit /b 1
+)
+echo Virtual environment activated
+echo.
+
+REM Set PYTHONPATH
+set PYTHONPATH=%PROJECT_DIR%
+echo PYTHONPATH set to: %PYTHONPATH%
+echo.
+
+REM Check if dependencies are installed
+echo Checking dependencies...
+python -c "import neuro_san" 2>nul
+if errorlevel 1 (
+    echo Installing dependencies...
+    pip install -r requirements.txt
+    if errorlevel 1 (
+        echo Failed to install dependencies
+        pause
+        exit /b 1
+    )
+    echo Dependencies installed
+) else (
+    echo Dependencies already installed
+)
+echo.
+
+REM Check for API keys
+if not defined OPENAI_API_KEY (
+    echo WARNING: OPENAI_API_KEY environment variable is not set!
+    echo Some features may not work without API keys.
+    echo Set it with: set OPENAI_API_KEY=your-key-here
+    echo.
+)
+
+REM Enable CORS headers for web applications
+set AGENT_ALLOW_CORS_HEADERS=1
+echo CORS headers enabled
+echo.
+
+REM Start the server
+echo ===============================================
+echo   Starting Neuro-SAN Server on port 8080
+echo ===============================================
+echo.
+echo Server will be available at: http://localhost:8080
+echo Press Ctrl+C to stop the server
+echo.
+
+python -m neuro_san.service.main_loop.server_main_loop