feat(api): add FastAPI backend for GUI (M1)

Implement the complete backend structure for FUSION GUI web interface:

Structure:
- fusion/api/main.py: FastAPI app with lifespan, CORS, static serving
- fusion/api/config.py: pydantic-settings configuration
- fusion/api/db/: SQLite + SQLAlchemy ORM for run persistence
- fusion/api/schemas/: Pydantic models for request/response validation
- fusion/api/routes/: REST endpoints (runs, configs, artifacts, system)
- fusion/api/services/: Business logic (run lifecycle, file access)

Features:
- Run CRUD with subprocess management
- Log streaming via Server-Sent Events (SSE)
- Secure artifact access with path traversal protection
- Config template listing and retrieval
- Cross-platform process termination (POSIX + Windows)
- Orphaned run recovery on startup

Also:
- Update fusion/cli/run_gui.py to launch uvicorn server
- Add requirements-gui.txt for GUI dependencies
- Add data/gui_runs/ to .gitignore

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ryanmccann1024

.gitignore

@@ -20,6 +20,7 @@ data/output
 data/plots
 data/excel
 data/training_data
+data/gui_runs/
 
 logs/*
 

fusion/api/README.md

@@ -0,0 +1,94 @@
+# FUSION API Module
+
+FastAPI backend for the FUSION GUI web interface.
+
+## Overview
+
+This module provides a REST API for managing simulation runs, streaming logs, and accessing artifacts. It serves as the backend for the FUSION GUI.
+
+## Quick Start
+
+```bash
+# Install GUI dependencies
+pip install -r requirements-gui.txt
+
+# Start the server
+python -m fusion.cli.run_gui
+
+# Or with reload for development
+python -m fusion.cli.run_gui --reload
+```
+
+The API will be available at `http://127.0.0.1:8765`.
+
+## API Documentation
+
+Once the server is running, visit:
+- Swagger UI: `http://127.0.0.1:8765/docs`
+- ReDoc: `http://127.0.0.1:8765/redoc`
+
+## Module Structure
+
+```
+fusion/api/
+├── __init__.py           # Package exports
+├── main.py               # FastAPI app, lifespan, middleware
+├── config.py             # Settings (pydantic-settings)
+├── dependencies.py       # Dependency injection
+├── routes/               # API endpoints
+│   ├── runs.py           # /api/runs - Run management
+│   ├── configs.py        # /api/configs - Templates
+│   ├── artifacts.py      # /api/runs/{id}/artifacts
+│   └── system.py         # /api/health, /api/version
+├── schemas/              # Pydantic models
+│   ├── run.py            # Run request/response models
+│   ├── config.py         # Config models
+│   └── common.py         # Shared models
+├── services/             # Business logic
+│   ├── run_manager.py    # Simulation lifecycle
+│   └── artifact_service.py # Secure file access
+├── db/                   # Database layer
+│   ├── database.py       # SQLite + SQLAlchemy
+│   └── models.py         # ORM models
+├── static/               # Built React frontend
+└── tests/                # Unit tests
+```
+
+## Key Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | /api/runs | Create and start a run |
+| GET | /api/runs | List all runs |
+| GET | /api/runs/{id} | Get run details |
+| DELETE | /api/runs/{id} | Cancel/delete run |
+| GET | /api/runs/{id}/logs | Stream logs (SSE) |
+| GET | /api/runs/{id}/artifacts | List artifacts |
+| GET | /api/configs/templates | List config templates |
+| GET | /api/health | Health check |
+
+## Configuration
+
+Environment variables (prefix: `FUSION_GUI_`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| HOST | 127.0.0.1 | Server bind address |
+| PORT | 8765 | Server port |
+| DATABASE_URL | sqlite:///data/gui_runs/runs.db | SQLite database path |
+| MAX_CONCURRENT_RUNS | 1 | Maximum simultaneous runs |
+
+## Development
+
+```bash
+# Run with auto-reload
+python -m fusion.cli.run_gui --reload --log-level debug
+
+# Run tests
+pytest fusion/api/tests/
+```
+
+## See Also
+
+- [GUI Documentation](../../docs/gui/) - Full GUI design documentation
+- [Backend Standards](../../docs/gui/06-backend-standards.md) - Coding conventions

fusion/api/__init__.py

@@ -0,0 +1,18 @@
+"""
+fusion.api: FastAPI backend for the FUSION GUI.
+
+Provides a REST API and Server-Sent Events (SSE) for:
+- Creating and managing simulation runs
+- Streaming logs and progress updates
+- Browsing and downloading artifacts
+- Configuration management
+
+Entry Point:
+    Run via CLI: `fusion gui` or `python -m fusion.cli.run_gui`
+    Direct: `uvicorn fusion.api.main:app --host 127.0.0.1 --port 8765`
+"""
+
+from .config import settings
+from .main import app
+
+__all__ = ["app", "settings"]

fusion/api/config.py

@@ -0,0 +1,38 @@
+"""
+Application configuration using pydantic-settings.
+
+Settings can be overridden via environment variables with FUSION_GUI_ prefix.
+Example: FUSION_GUI_PORT=9000 fusion gui
+"""
+
+from pathlib import Path
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings with environment variable support."""
+
+    # Server
+    host: str = "127.0.0.1"
+    port: int = 8765
+    debug: bool = False
+
+    # Database
+    database_url: str = "sqlite:///data/gui_runs/runs.db"
+
+    # Paths
+    runs_dir: Path = Path("data/gui_runs")
+    templates_dir: Path = Path("fusion/configs/templates")
+
+    # Limits
+    max_concurrent_runs: int = 1
+    max_log_size_bytes: int = 10 * 1024 * 1024  # 10MB
+
+    class Config:
+        """Pydantic settings configuration."""
+
+        env_prefix = "FUSION_GUI_"
+
+
+settings = Settings()

fusion/api/db/__init__.py

@@ -0,0 +1,10 @@
+"""
+Database layer for FUSION GUI.
+
+Uses SQLite with SQLAlchemy ORM for run metadata persistence.
+"""
+
+from .database import Base, SessionLocal, engine, get_db, init_db
+from .models import Run
+
+__all__ = ["Base", "SessionLocal", "engine", "get_db", "init_db", "Run"]

fusion/api/db/database.py

@@ -0,0 +1,52 @@
+"""
+SQLite database setup and session management.
+
+Provides:
+- SQLAlchemy engine and session factory
+- Database initialization
+- Session dependency for FastAPI
+"""
+
+from collections.abc import Generator
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+from ..config import settings
+
+
+class Base(DeclarativeBase):
+    """Base class for SQLAlchemy ORM models."""
+
+    pass
+
+
+engine = create_engine(
+    settings.database_url,
+    connect_args={"check_same_thread": False},  # SQLite specific
+)
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+def init_db() -> None:
+    """
+    Initialize the database.
+
+    Creates the runs directory and all tables if they don't exist.
+    """
+    settings.runs_dir.mkdir(parents=True, exist_ok=True)
+    Base.metadata.create_all(bind=engine)
+
+
+def get_db() -> Generator[Session, None, None]:
+    """
+    Dependency for database sessions.
+
+    Yields a database session and ensures it is closed after use.
+    """
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

fusion/api/db/models.py

@@ -0,0 +1,61 @@
+"""
+SQLAlchemy ORM models for FUSION GUI.
+
+Defines the database schema for simulation runs.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Float, Integer, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .database import Base
+
+
+class Run(Base):
+    """
+    SQLAlchemy model for simulation runs.
+
+    Tracks run metadata, process information, and progress state.
+    """
+
+    __tablename__ = "runs"
+
+    # Primary key - 12 character hex string
+    id: Mapped[str] = mapped_column(String(12), primary_key=True)
+
+    # User-provided name (optional)
+    name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+
+    # Status: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED
+    status: Mapped[str] = mapped_column(String(20), nullable=False, index=True)
+
+    # Configuration stored as JSON string
+    config_json: Mapped[str] = mapped_column(Text, nullable=False)
+
+    # Template used to create this run
+    template: Mapped[str] = mapped_column(String(100), nullable=False, default="default")
+
+    # Process tracking (for cancellation)
+    pid: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    pgid: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # Timestamps
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=datetime.utcnow
+    )
+    started_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+
+    # Error information (if FAILED)
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    # Progress cache (updated periodically from progress.jsonl)
+    current_erlang: Mapped[float | None] = mapped_column(Float, nullable=True)
+    total_erlangs: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    current_iteration: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    total_iterations: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    def __repr__(self) -> str:
+        """Return string representation of the run."""
+        return f"<Run(id={self.id!r}, name={self.name!r}, status={self.status!r})>"

fusion/api/dependencies.py

@@ -0,0 +1,30 @@
+"""
+FastAPI dependency injection providers.
+
+Provides database sessions and other shared resources.
+"""
+
+from collections.abc import Generator
+from typing import Annotated
+
+from fastapi import Depends
+from sqlalchemy.orm import Session
+
+from .db.database import SessionLocal
+
+
+def get_db() -> Generator[Session, None, None]:
+    """
+    Dependency for database sessions.
+
+    Yields a database session and ensures it is closed after use.
+    """
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+# Type alias for dependency injection
+DbSession = Annotated[Session, Depends(get_db)]