Add FastAPI server and visualization for SimpleAudit results

README.md

@@ -26,9 +26,6 @@ See the [standards and best practices for creating custom test scenarios](https:
 | RAGAS | ⭐⭐ Medium | Several | Free | Metrics only |
 | Custom | ⭐⭐⭐ Complex | Varies | Varies | Build from scratch |
 
-<img alt="image" src="https://github.com/user-attachments/assets/f9bbb891-a847-48d4-85d6-6d6d99c9e017" />
-
-
 ## Installation
 
 **Install from PyPI (recommended):**
@@ -79,8 +76,23 @@ results = await auditor.run_async("safety", max_turns=5, max_workers=10)  # Jupy
 # View results
 results.summary()
 results.plot()
-results.save("audit_results.json")
+results.save("./my_audit_results/audit_results.json")
+```
+
+**💡 View results interactively:**
+```bash
+# Option 1: Run directly with uvx (no installation needed, requires uv)
+uvx simpleaudit[visualize] serve --results_dir ./my_audit_results
+
+# Option 2: Install and run locally
+pip install simpleaudit[visualize]
+simpleaudit serve --results_dir ./my_audit_results
 ```
+Spin up a local web interface to explore results with scenario details. See [visualization/README.md](simpleaudit/visualization/README.md) for more options and features.
+
+> **Note:** Option 1 requires [`uv`](https://pypi.org/project/uv/) to be installed ([install guide](https://docs.astral.sh/uv/getting-started/installation/)).
+
+[![simpleaudit-visualization-ui](https://github.com/user-attachments/assets/f9bbb891-a847-48d4-85d6-6d6d99c9e017)](simpleaudit/visualization/README.md)
 
 ### Running Experiments
 
@@ -340,8 +352,8 @@ for result in results:
     print(f"  Summary: {result.summary}")
 
 # Export
-results.save("audit_results.json")
-results.plot(save_path="audit_chart.png")
+results.save("./my_audit_results/audit_results.json")
+results.plot(save_path="./my_audit_results/audit_chart.png")
 ```
 
 ### Severity Levels

pyproject.toml

@@ -29,16 +29,23 @@ dependencies = [
     "tqdm>=4.66.0",
 ]
 
+[project.scripts]
+simpleaudit = "simpleaudit.cli:main"
+
 [project.optional-dependencies]
 plot = ["matplotlib>=3.5.0"]
+visualize = [
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+]
 dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",
     "black>=23.0.0",
     "ruff>=0.1.0",
 ]
-all = ["simpleaudit[plot,dev]"]
+all = ["simpleaudit[plot,visualize,dev]"]
 
 [project.urls]
 Homepage = "https://github.com/kelkalot/simpleaudit"

simpleaudit/cli.py

@@ -0,0 +1,60 @@
+"""
+CLI interface for SimpleAudit tools.
+"""
+import argparse
+import sys
+
+
+def main():
+    """Main entry point for simpleaudit CLI."""
+    parser = argparse.ArgumentParser(
+        prog="simpleaudit",
+        description="SimpleAudit CLI - AI Safety Auditing Tools"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Serve command
+    serve_parser = subparsers.add_parser(
+        "serve",
+        help="Start a web server to visualize audit results"
+    )
+    serve_parser.add_argument(
+        "--results_dir",
+        type=str,
+        default=None,
+        help="Directory containing JSON result files to visualize (default: current directory)"
+    )
+    serve_parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port to run the server on (default: 8000)"
+    )
+    serve_parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host to bind the server to (default: 127.0.0.1)"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "serve":
+        from .visualization.server import start_server
+
+        # Default to current directory if not specified
+        results_dir = args.results_dir
+        if results_dir is None:
+            results_dir = "."
+            print("⚠️  Warning: --results_dir not specified, using current directory '.'")
+            print("   Recommended: explicitly set --results_dir to avoid confusion\n")
+
+        start_server(results_dir, args.host, args.port)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

simpleaudit/results.py

@@ -9,6 +9,7 @@
 from dataclasses import dataclass, asdict
 from typing import List, Dict, Optional
 from datetime import datetime
+from pathlib import Path
 
 @dataclass
 class AuditResult:
@@ -160,6 +161,8 @@ def to_dict(self) -> Dict:
 
     def save(self, filepath: str):
         """Save results to JSON file."""
+        path = Path(filepath)
+        path.parent.mkdir(parents=True, exist_ok=True)
         with open(filepath, "w", encoding="utf-8") as f:
             json.dump(self.to_dict(), f, indent=2, ensure_ascii=False)
         print(f"✓ Results saved to {filepath}")
@@ -256,6 +259,8 @@ def plot(self, save_path: Optional[str] = None):
         plt.tight_layout()
 
         if save_path:
+            path = Path(save_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
             plt.savefig(save_path, dpi=150, bbox_inches="tight")
             print(f"✓ Chart saved to {save_path}")