Simple Chatbot API

Status

---

About

A FastAPI-powered conversational AI service using OpenAI, with full conversation management, streaming responses, token-based context trimming, rolling summarization, and a composable prompt system. Part of a larger portfolio project — built incrementally, PR by PR.

Phases:

• Phase 1 — Core chat API with conversation memory (PostgreSQL) ✅
• Phase 2 — Full CRUD, context window, auto-title, streaming & composable prompt system ✅
• Phase 3 — RAG over retail inventory data

---

Project Structure

simple-chatbot-api/
├── main.py                  # App launcher
├── Dockerfile               # Container image definition
├── docker-compose.yml       # Multi-service orchestration (API + PostgreSQL)
├── app/
│   ├── core/                # Infrastructure (config, database, logging, errors)
│   ├── routers/             # HTTP layer — thin, no business logic
│   ├── controllers/         # Business logic & orchestration
│   ├── services/            # OpenAI client, summarizer, prompt loader
│   ├── utils/               # Shared utilities (token counting, etc.)
│   └── models/              # Pydantic & SQLModel schemas
├── prompts/                 # Composable prompt library
│   ├── prompts.yaml         # Control layer — defines prompt compositions
│   ├── base/                # Base prompt templates
│   ├── core/                # Identity and persona
│   ├── styles/              # Tone styles (casual, formal, sarcastic)
│   ├── rules/               # Behavioral rules (communication, factuality, etc.)
│   └── intensity/           # Intensity calibration (low, medium, high)
└── tests/                   # Test suite

---

Installation

Option A — Docker (recommended)

1. Clone the repo:

git clone https://github.com/chris-kechagias/simple-chatbot-api.git
cd simple-chatbot-api

2. Copy the example env file and fill in your values:

cp .env.example .env

3. Build and start:

task build       # build image and start containers (detached)
task start       # start without rebuilding
task stop        # stop containers
task restart     # stop and restart
task logs        # follow container logs

Or using Docker directly:

docker compose up --build -d

The API will be available at http://localhost:8000.

---

Option B — Local

Prerequisites: Python 3.11+, PostgreSQL, an OpenAI API key

1. Clone the repo and install dependencies:

git clone https://github.com/chris-kechagias/simple-chatbot-api.git
cd simple-chatbot-api
uv sync

2. Copy the example env file and fill in your values:

cp .env.example .env

3. Run the API locally:

task dev

---

First Request

This API has no authentication yet. Every request requires a user_id UUID that you generate yourself — think of it as your user identifier until auth is added.

Generate one:

python -c "import uuid; print(uuid.uuid4())"

Use that UUID as user_id in all your requests. For new conversations, set conversation_id to null or omit it entirely.

---

Author

Chris Kechagias

Transitioning from retail operations to AI engineering.

⭐ If you find this project helpful, consider giving it a star!