Terminal AI Assistant (CLI Edition) 🚀

A highly resilient, standalone Command-Line Interface (CLI) application for interacting with Large Language Models (LLMs) locally. Built with extreme focus on security, decoupled architecture, and fault tolerance.

🌟 Key Features

• Strict Decoupled Architecture: Pure Python backend without any web server dependencies (no FastAPI/Starlette overhead).
• Local JWT Authentication: Secure password hashing (bcrypt) and local stateless token caching (token.json) for rapid CLI restarts without re-authenticating.
• Intelligent Crisis Detection: Every message is routed through a parallel hidden LLM "meta-prompt" to classify risk (SAFE, LOW_RISK, MEDIUM_RISK, HIGH_RISK) before processing the conversation.
• Dual Persistence Layer:
  • Primary: SQLite via SQLModel & Repository Pattern.
  • Secondary: Append-only JSON flat-file mirror (crises_store/crises_detection.json) for severe security incidents.
• Fault Tolerance: Implements strict Exponential Backoff for API rate limits and 502/503 provider outages. Suppresses Python tracebacks in favor of clean CLI UX.
• Utilities: Built-in chat history, DB integrity checks, SQLite backups, and exports (.json, .md, .txt).

⚙️ Installation & Setup

1. Clone the repository:

   git clone https://github.com/hammad986/terminal-ai-assistant-cli.git
   cd terminal-ai-assistant-cli

2. Install dependencies: (We recommend using a virtual environment)

   pip install -r requirements.txt

3. Configure Environment Variables: Copy the example environment file:

   cp .env.example .env

   Open .env and insert your API credentials (e.g., OpenRouter API Key) and JWT Secret.

4. Run the CLI:

   python main.py

💬 Command Reference

Once authenticated, type any prompt to chat with the LLM, or use the following system commands:

Command	Description
help	Show available system commands
whoami	Display the currently authenticated username
clear	Wipe current session context window memory
list	View all historically saved sessions in SQLite
history	Read the exact chat logs of the current session
stats	View application metrics and database statistics
export	Export the conversation to JSON, TXT, or Markdown
backup	Instantly clone the SQLite database to the backups/ folder
check	Run a database integrity test
logout	Wipe local JWT and exit
exit	Terminate the application

🏗️ Core Architecture

• chat_service.py: The central Business Logic orchestrator.
• detector.py: Intervenes before AI responses to execute the safety classification.
• database/repository.py: The clean abstraction DAL over the SQLite assistant.db.
• llm_client.py: Outbound network layer containing backoff logic.