Files · Pre-purchase fit advisor for WooCommerce merchants

# Pre-purchase fit advisor for WooCommerce merchants
 
> Answer product-fit questions 24/7 using AI trained on your catalog and return data.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Architecture
 
The fit advisor is built around 6 REAA packages wired into a Next.js 16+ App Router + Hono stack with the Vercel AI SDK:
 
| Package | Role |
|---|---|
| `@reaatech/agent-memory` | Long-term memory facade — stores and retrieves customer sizing preferences and fit interactions via `AgentMemory` |
| `@reaatech/agent-memory-retrieval` | Semantic context injection — `ContextInjector` formats retrieved memories for LLM prompts with token budgeting |
| `@reaatech/agent-memory-storage` | Storage abstraction — `InMemoryMemoryStorage` provides the backing store for agent memories |
| `@reaatech/llm-cache` | Response caching — `CacheEngine` with exact-match (SHA-256) and semantic (cosine similarity) cache lookups |
| `@reaatech/rag-eval-core` | Evaluation types — `EvaluationSampleSchema` validates RAG evaluation data shapes |
| `@reaatech/agent-handoff` | Escalation utilities — `TypedEventEmitter`, `withRetry`, and `createHandoffConfig` for routing low-confidence questions |
 
### Data flow
 
```
Shopper question → Hono router → FitAdvisor.answerQuestion()
  → CacheService.get() — return cached answer on hit
  → ProductCatalog.search() — find relevant products
  → MemoryService.retrieveRelevantContext() — customer fit preferences
  → generateResponse() — Vercel AI SDK LLM call with context
  → CacheService.set() — cache for future
  → MemoryService.storeInteraction() — learn from this interaction
  → return FitAnswer
```
 
## Getting started
 
### Prerequisites
 
- Node.js >= 22, pnpm 10.x
- An OpenAI-compatible API key (or any LLM provider supported by the Vercel AI SDK)
 
### Setup
 
```bash
pnpm install
cp .env.example .env
# Edit .env with your API keys
pnpm dev              # start Next.js dev server at http://localhost:3000
pnpm test             # run vitest suite with coverage
pnpm typecheck        # TypeScript type checking
pnpm lint             # ESLint
```
 
### Environment variables
 
| Variable | Required | Default | Description |
|---|---|---|---|
| `OPENAI_API_KEY` | Yes | — | LLM provider API key |
| `LLM_MODEL` | No | `gpt-5.2-mini` | Model identifier for `@ai-sdk/openai` |
| `LANGFUSE_SECRET_KEY` | No | — | Langfuse secret (observability) |
| `LANGFUSE_PUBLIC_KEY` | No | — | Langfuse public key |
| `LANGFUSE_BASE_URL` | No | `https://cloud.langfuse.com` | Langfuse endpoint |
| `POSTGRES_URL` | No | — | PostgreSQL connection string (for production pgvector) |
 
## API Reference
 
### `POST /api/chat`
 
Answer a product-fit question.
 
**Request body:**
 
```json
{
  "messages": [
    { "speaker": "user", "content": "Will these jeans fit a 32-inch waist?", "timestamp": "2025-01-01T00:00:00Z" }
  ],
  "productId": "jeans-01",
  "customerId": "cust-42"
}
```
 
**Response `200`:**
 
```json
{
  "answer": "The Slim Fit Stretch Jeans in size 32 should fit a 32-inch waist comfortably...",
  "confidence": 85,
  "sources": ["jeans-01: Slim Fit Stretch Jeans"],
  "productFitAdvice": "Slim fit — size up if between sizes",
  "cached": false
}
```
 
**Response `400`** (validation error):
 
```json
{ "error": "invalid request", "details": [...] }
```
 
### `GET /api/health`
 
Returns `200` with `{ "status": "ok", "timestamp": "..." }`.
 
### `GET /api/products?q=<query>`
 
Search the product catalog. Returns a JSON array of matching products.
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/                  services, lib, adapters
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).