Chat Server API Reference and Internals

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/techjarves/USB-Uncensored-LLM/llms.txt

Use this file to discover all available pages before exploring further.

​

Configuration Constants

​

API Endpoints

​

GET / and GET /index.html

• Response: 200 text/html — contents of Shared/FastChatUI.html
• Error: 404 if FastChatUI.html is missing from the Shared/ directory

​

GET /api/chats

• Response: 200 application/json — a JSON array of all chat objects stored in Shared/chat_data/chats.json
• Fallback: If the file is missing or contains malformed JSON, returns 200 with an empty array [] rather than an error, so the UI always loads cleanly

​

POST /api/chats

• Body: JSON array of chat objects (the full chat history from the UI)
• Response: 200 application/json
  { "ok": true }
  
• Error: 500 application/json
  { "error": "..." }
  
• Atomicity: Writes to chats.json.tmp first, then renames to chats.json via os.replace(). This prevents corruption if the process is killed mid-write.

​

GET /api/settings

• Response: 200 application/json
  {
    "globalSystemPrompt": "",
    "temperature": 0.7,
    "logMode": "errors_only"
  }
  
• If the file is missing, these defaults are returned automatically.

​

POST /api/settings

• Body: A partial JSON object — only keys you want to change are required
  { "temperature": 0.9, "logMode": "all" }
  
• The incoming object is merged on top of the existing settings (missing keys are preserved).
• logMode is normalized: any value other than "all" is coerced to "errors_only".
• The in-memory log mode is updated immediately without restart.
• Response: 200 application/json
  { "ok": true, "logMode": "errors_only" }
  
• Error: 500 application/json
  { "error": "..." }
  

​

GET /api/stats

• Response: 200 application/json
  {
    "cpu_percent": 14.2,
    "ram_percent": 67.8,
    "has_psutil": false
  }
  
• has_psutil — indicates whether the optional psutil library was found. The server works without it using platform-native fallbacks:

  Platform	RAM source	CPU source
  Windows	GlobalMemoryStatusEx (kernel32)	GetSystemTimes (kernel32)
  Linux	/proc/meminfo	/proc/stat delta
  macOS	—	—

  On macOS, CPU and RAM are returned as 0.0 in the stdlib fallback path to avoid potential permission issues. Install psutil (pip install psutil) for accurate macOS stats.
• Error: 500 application/json on unexpected failure

​

GET | POST | DELETE /ollama/*

• Path rewriting: The /ollama prefix is stripped before forwarding. For example, GET /ollama/api/tags is forwarded to GET http://127.0.0.1:11434/api/tags.
• Streaming: For /api/chat and /api/generate, the response is streamed back in 4096-byte chunks as they arrive from Ollama, enabling token-by-token rendering in the UI.
• Validation: POST /ollama/api/chat validates the request body before forwarding:
  • model must be a non-empty string — returns 400 if missing or blank
  • messages must be a non-empty array — returns 400 if missing or empty
• LLAMA_CPP_MODE bridging: When started with --llama-cpp, the proxy translates /api/chat payloads from Ollama JSONL format to OpenAI /v1/chat/completions format for llama.cpp’s llama-server. SSE (data: {...}) responses from llama-server are bridged back to Ollama-style JSONL ({"message": ..., "done": false}\n) for the UI.
• Responses:
  • Upstream status code on success
  • 400 — validation failure (missing model or messages)
  • 502 — Ollama engine is unreachable (not running or not yet ready)
  • 500 — unexpected proxy error

​

Concurrency Model

class ThreadedHTTPServer(http.server.HTTPServer):
    def process_request(self, request, client_address):
        thread = threading.Thread(target=self._handle, args=(request, client_address))
        thread.daemon = True
        thread.start()

• A long-running streaming response (a model generating thousands of tokens) does not block the UI from loading or saving chats.
• Hardware stats polls from the UI run concurrently with active generation.
• Thread safety for shared file access is enforced with threading.RLock() — DATA_FILE_LOCK guards chats.json and settings.json, and LOG_MODE_LOCK guards the in-memory log mode state.

​

CORS

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

​

Logging

• Timestamp with timezone
• Request ID (UUID, unique per request)
• HTTP method and path
• Client IP address
• User-Agent header
• Model name, temperature, and stream flag
• Python module, function, and line number
• Thread name
• Full hardware snapshot (platform, CPU count, total RAM, Python version)
• Exception traceback (if applicable)

​

Atomic File Writes

temp_file = CHATS_FILE + ".tmp"
with open(temp_file, "w", encoding="utf-8") as f:
    json.dump(chats, f, ensure_ascii=False, indent=2)
    f.flush()
os.replace(temp_file, CHATS_FILE)

​

Starting the Server Manually

# Standard mode (proxies Ollama at :11434)
python3 Shared/chat_server.py

# llama.cpp mode (proxies llama-server at :8080, translates API format)
python3 Shared/chat_server.py --llama-cpp

# Suppress automatic browser open on launch
python3 Shared/chat_server.py --no-browser

# Combine flags
python3 Shared/chat_server.py --llama-cpp --no-browser