Thoughtful 🌿

A personal relationship memory bank. Save little observations about the people in your life, then let a local AI turn those notes into thoughtful, budget-aware gift ideas. The notes are the source of truth — no tags, no categories. The AI does the interpreting.

• Frontend: React (Vite) + React Router
• Backend: Flask + SQLAlchemy + JWT auth
• Database: PostgreSQL
• AI: Ollama running locally, model is configurable

---

Project layout

thoughtful/
├── backend/            Flask API (app factory in app/, run.py entry point)
│   ├── app/            config, models, ai (Ollama), auth, people, gifts
│   ├── venv/           Python virtualenv (created during setup)
│   ├── setup_db.sql    one-time PostgreSQL role + database creation
│   └── .env            backend configuration (DB URL, secrets, Ollama model)
├── frontend/           React app (src/pages, src/components, src/context)
│   └── .env            frontend config (VITE_API_URL)
└── start.sh            launches backend + frontend together

---

One-time setup

Dependencies are already installed (Python venv + npm packages). Two external services still need a one-time setup: PostgreSQL and Ollama.

1. PostgreSQL

The app expects a thoughtful role and database (matching the default DATABASE_URL in backend/.env). Create them once with a superuser:

sudo -u postgres psql -f backend/setup_db.sql

Prefer different credentials? Edit DATABASE_URL in backend/.env and point it at any database you can reach. SQLAlchemy creates the tables automatically on first run.

2. Ollama (the AI)

Install Ollama, start it, and pull a model. The default model is llama3.2 (configurable in backend/.env via OLLAMA_MODEL).

# Install (Linux/macOS)
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model — any of these work well. Pick one and set OLLAMA_MODEL to match.
ollama pull llama3.2      # default
# ollama pull qwen2.5
# ollama pull gemma2

# Make sure the server is running (it usually starts on install):
ollama serve              # serves http://localhost:11434

The app talks to Ollama over HTTP, so the model is fully swappable — change OLLAMA_MODEL and restart the backend. You can browse and create notes/people without Ollama; only gift generation and summaries need it.

---

Running the app

./start.sh

Then open http://localhost:5173. The backend runs on http://localhost:5001.

Or run each side separately:

# Terminal 1 — backend
cd backend && ./venv/bin/python run.py

# Terminal 2 — frontend
cd frontend && npm run dev

Check the AI connection anytime:

curl http://localhost:5001/api/health

---

How it works

1. Sign up / log in. Auth is JWT-based; each user only ever sees their own people, notes, and gift ideas.
2. Add people with a name, optional birthday, and a gift budget.
3. Jot notes — one fast textarea, no structure. "Sarah wants to learn pottery."
4. Generate gift ideas. The backend gathers all of a person's notes + their budget, builds a prompt, and asks Ollama for structured gift concepts (title, reasoning, price estimate, Amazon/Etsy search phrases).
5. Shop. Each idea card has Amazon / Etsy / eBay buttons that open a marketplace search built from the AI's search phrases. No marketplace APIs are used — just search URLs.
6. Summaries. Each profile can generate a short AI portrait of the person based on their notes.

Configuration reference (backend/.env)

Variable	Purpose	Default
DATABASE_URL	PostgreSQL connection string	postgresql://thoughtful:thoughtful@localhost:5432/thoughtful
OLLAMA_HOST	Ollama server URL	http://localhost:11434
OLLAMA_MODEL	Model used for ideas + summaries	llama3.2
OLLAMA_TIMEOUT	Seconds to wait for the model	120
SECRET_KEY / JWT_SECRET_KEY	Flask + JWT secrets	dev values
FLASK_PORT	Backend port	5001
CORS_ORIGINS	Allowed frontend origins	http://localhost:5173