Semantic FAQ CLI

Think of this as your go-to command-line buddy that fetches answers based on what you mean not just the exact words you type. Under the hood, it taps into TiDB Cloud’s vector columns and AWS Bedrock Titan-V2 embeddings, all wrapped up in pure Python.

---

🚀 Features

• Semantic search, minus the fluff
  Store question embeddings in TiDB and let vector lookups do the heavy lifting.

• Raw Bedrock power
  No LangChain wrappers, just straight JSON calls so you see exactly what Titan-V2 returns.

• Serverless-ready
  A free TiDB Serverless cluster and AWS keys are all you need to get started.

• Pure Python CLI
  Fire it up, ask a question, get an answer. No extra services required.

---

🛠️ Quick Start Prerequisites

• macOS with Python 3.8+
• AWS CLI v2 configured (aws configure)
• A TiDB Cloud Serverless cluster (free tier works)
• Root CA at /etc/ssl/cert.pem (macOS default)

Install Dependencies

pip install -r requirements.txt

Required Environment Variables

Create a .env file based on the .env.example template and fill in your own values:

cp .env.example .env
# edit .env with your secrets

• DATABASE_URL – TiDB connection string
• AWS_REGION – AWS region for Bedrock (defaults to us-east-1)
• FAQ_FILE – path to the FAQ JSON file (defaults to faqs.json)

🔍 Using the CLI

After configuring your environment variables and installing dependencies you can run the interactive command-line assistant:

python app.py

Type a question and you'll get back the closest stored FAQ entry. Enter exit to quit.

🌐 Web Interface

Prefer a web page over a terminal? Here’s how:

1. Install dependencies

   pip install -r requirements.txt

2. Check that server.py and index.html live in your project folder.

3. Start the dev server with a progress bar

   python run_with_bar.py

   (This script runs Uvicorn and waits for the /health endpoint to respond before handing over the logs.)

4. Run the server manually (alternative)

   uvicorn server:app --reload --host 0.0.0.0 --port 8000

5. Open your browser to http://localhost:8000 and start asking questions.

6. The included index.html uses React (loaded via CDN) so you get a modern UI with a growing history of your queries and results.

Running Tests

Install development dependencies and run pytest:

pip install -r requirements.txt
pytest