CarGPT 🚗💨

An automotive Q&A API powered by Retrieval-Augmented Generation (RAG) and the Cohere platform. CarGPT answers questions about cars, trucks, motorcycles, maintenance, history, buying advice, and specs by retrieving relevant knowledge from a curated document base and generating grounded responses with citations.

Table of Contents

• Features
• Architecture
• Tech Stack
• Project Structure
• Prerequisites
• Installation
• Configuration
• Usage
  • Building Embeddings
  • Starting the Server
  • API Reference
• Knowledge Base
• How It Works

Features

• Domain-focused responses: Strictly scoped to automotive topics; gracefully declines off-topic questions.
• Retrieval-Augmented Generation: Queries are semantically matched against a local knowledge base so answers are grounded in curated documents, not just model knowledge.
• Citations: Responses include Cohere-provided citations linking claims back to source documents.
• Rate limiting: Built-in protection against abuse (50 requests per 15-minute window per client).
• Precomputed embeddings: Document vectors are generated offline and cached, keeping per-request latency low.
• Configurable: Model, chatbot name, and document paths are all driven by a single config.json.

Architecture

┌────────────┐       POST /generate         ┌──────────────────────┐
│   Client    │ ──────────────────────────► │   Express Server     │
└────────────┘                              │   (server.js)        │
                                            │                      │
                                            │  1. Embed query      │
                                            │     (Cohere Embed)   │
                                            │                      │
                                            │  2. Cosine similarity│
                                            │     → top 10 docs    │
                                            │                      │
                                            │  3. Chat completion  │
                                            │     (Cohere Chat)    │
                                            │     with docs as     │
                                            │     context          │
                                            └──────────┬───────────┘
                                                       │
                                            ┌──────────▼───────────┐
                                            │  embeddings.json     │
                                            │  (precomputed        │
                                            │   document vectors)  │
                                            └──────────────────────┘

Tech Stack

Component	Technology
Runtime	Node.js (ES modules)
HTTP framework	Express 5
AI platform	Cohere (cohere-ai SDK)
Embedding model	embed-english-v3.0
Chat model	command-r-plus (configurable)
Rate limiting	express-rate-limit
Environment	dotenv

Project Structure

CarGPT/
├── server.js                    # Express API server with RAG pipeline
├── embed.js                     # Offline script to build document embeddings
├── config.json                  # Application configuration
├── package.json                 # Dependencies and scripts
├── .env                         # API keys (not committed)
└── documents/
    ├── embeddings.json          # Precomputed vectors + snippets (generated)
    ├── car-training.jsonl       # Training data (reserved for future use)
    └── car-docs/                # Source knowledge base
        ├── car_basics.json
        ├── car_history.json
        ├── car_models.json
        ├── maintenance_guides.json
        ├── model_reviews_expanded.json
        └── technology_explained.json

Prerequisites

• Node.js: v18 or later (LTS recommended)
• Cohere API key: Sign up at cohere.com and generate an API key

Installation

# Clone the repository
git clone <repository-url>
cd CarGPT

# Install dependencies
npm install

Configuration

Environment Variables

Create a .env file in the project root:

COHERE_API_KEY=your_cohere_api_key_here
PORT=5000                # optional, defaults to 5000

Variable	Required	Default	Description
COHERE_API_KEY	Yes	—	Your Cohere API key for embeddings and chat
PORT	No	5000	Port the server listens on

Application Config

Edit config.json to customize the chatbot:

{
  "chatbotName": "CarGPT",
  "baseModel": "command-r-plus",
  "documentsFolder": "documents/car-docs"
}

Field	Description
chatbotName	Name used in the system preamble and server logs
baseModel	Cohere chat model to use for generation
documentsFolder	Path to the folder containing source knowledge JSON files

Usage

Building Embeddings

Before starting the server for the first time (or after updating documents), generate the embeddings file:

npm run embed

This reads every .json file in documents/car-docs/, sends them through Cohere's embedding API in batches of 96, and writes the result to documents/embeddings.json. A 10-second pause is inserted between batches to respect API rate limits.

Starting the Server

npm start

The server will load the precomputed embeddings and start listening:

✅ Loaded 152 document embeddings.
🚗 CarGPT server listening on http://localhost:5000

If embeddings.json is missing, the server will exit with instructions to run npm run embed first.

API Reference

POST /generate

Send a natural-language question about automobiles.

Request

{
  "prompt": "What are the differences between drum brakes and disc brakes?"
}

Field	Type	Constraints
prompt	string	Required, max 1000 characters

Response (200)

{
  "text": "Disc brakes use a caliper to squeeze brake pads against a rotor...",
  "citations": [
    {
      "start": 0,
      "end": 65,
      "text": "Disc brakes use a caliper to squeeze brake pads against a rotor",
      "document_ids": ["car_basics.json_Disc Brakes"]
    }
  ]
}

Field	Type	Description
text	string	The generated answer
citations	array	Source references linking parts of the answer to specific documents

Error Responses

Status	Body	Cause
400	{ "error": "Invalid prompt provided." }	Missing, non-string, or >1000 char prompt
429	{ "error": "Too many requests, please try again after 15 minutes." }	Rate limit exceeded (50 req / 15 min)
500	{ "error": "An internal error occurred." }	Cohere API failure or server error

Knowledge Base

The RAG pipeline draws from JSON documents stored in documents/car-docs/. Each file is an array of objects with the following shape:

[
  {
    "title": "Disc Brakes",
    "snippet": "Disc brakes use a caliper to squeeze pairs of pads against a disc..."
  }
]

Adding New Knowledge

1. Create or edit a .json file in documents/car-docs/ following the { title, snippet } format.
2. Re-run npm run embed to regenerate the embeddings.
3. Restart the server.

The knowledge base currently covers:

Document	Topics
car_basics.json	Fundamental automotive concepts
car_history.json	History of the automobile
car_models.json	Popular car models and brands
maintenance_guides.json	Maintenance tips and schedules
model_reviews_expanded.json	In-depth model reviews
technology_explained.json	Automotive technology explainers

How It Works

1. Offline embedding — embed.js reads all knowledge documents, concatenates each title and snippet, and sends them to Cohere's embed-english-v3.0 model with inputType: "search_document". The resulting vectors are saved to embeddings.json.

2. Query embedding — When a user sends a prompt, the server embeds it with the same model using inputType: "search_query".

3. Retrieval — Cosine similarity is computed between the query vector and every document vector. The top 10 most relevant documents are selected.

4. Generation — The selected documents are passed as context to Cohere's command-r-plus chat model alongside a system preamble that enforces the automotive domain scope. The model generates a grounded answer with inline citations.

5. Response — The answer text and citations array are returned to the client.