Server Guide¶

This guide covers running the FastAPI backend and React UI for FairSense-AgentiX, including the programmatic server launcher and manual startup.

Quick Start (Programmatic Launcher)¶

Start both the FastAPI backend and React frontend with a single call:

from fairsense_agentix import server

server.start()

This will:

Start FastAPI backend on http://localhost:8000
Start React UI on http://localhost:5173
Auto-open your browser
Wait for both services to be ready (health checks)
Gracefully shutdown on Ctrl+C

Manual Startup¶

Backend only¶

uv run uvicorn fairsense_agentix.service_api.server:app --reload

API docs: http://localhost:8000/docs

React UI (after backend is running)¶

cd ui
npm install
npm run dev

Set VITE_API_BASE to your backend URL (default: http://localhost:8000).

Launcher Usage¶

Custom Ports¶

server.start(port=9000, ui_port=3000)

Development Mode (Auto-Reload)¶

server.start(reload=True)

Backend auto-reloads when you edit prompts in fairsense_agentix/prompts/templates/, modify .env, or change tool parameters.

Headless (No Browser)¶

server.start(open_browser=False)

Configuration Options¶

def start(
    port: int = 8000,          # FastAPI backend port
    ui_port: int = 5173,       # React UI port (Vite default)
    open_browser: bool = True, # Auto-open browser
    verbose: bool = True,      # Stream logs to stdout
    reload: bool = False       # Enable auto-reload
) -> None:

Requirements¶

Python 3.12+ with fairsense-agentix installed (uv sync or pip install -e .)
Node.js 18+ and npm for the React UI

Troubleshooting¶

Backend failed to start on port 8000¶

Port may be in use. Check and free it:

# macOS/Linux
lsof -i :8000

# Windows
netstat -ano | findstr :8000

Or use another port: server.start(port=9000).

Frontend failed to start on port 5173¶

Install UI dependencies:

cd ui
npm install

Or use another port: server.start(ui_port=3000).

Backend startup is slow (30–45s)¶

Normal on first run. The backend loads LLM clients, embedding models (~90MB), FAISS indexes, and optionally OCR/caption models. Later starts are much faster (~5–10s).

Testing¶

Run server launcher tests:

uv run pytest tests/test_server_launcher.py -v

Manual check:

uv run python examples/launch_server.py

Then verify the browser opens, the UI loads, and a text analysis works; press Ctrl+C to stop both servers.