AI (swapps-ai)

swapps-ai is a Cloudflare Worker that powers the swapps.com/api/ai/* endpoints. It reads a prospective client's free-text request and turns it into structured, AI-assisted guidance for the Swapps Website:

  • It recommends one Swapps path (Build / Launch / Scale / Custom / Technical Review) and explains the choice with concrete signals from the user's input.
  • It refines a free-text project description into a categorized, itemized breakdown aligned with the /get-swapps/ wizard.

The Worker calls Workers AI for the language model, optionally layering in RAG context retrieved from a Cloudflare AI Search instance.

Role in the platform

Property Value
Worker swapps-ai
Routes swapps.com/api/ai/*, www.swapps.com/api/ai/*
Consumer The Website (swapps-client) — plan recommendation and "Improve with AI" affordances
Model @cf/meta/llama-3.2-3b-instruct (override via the AI_MODEL var)

Because the Worker is mounted on the same zone as the Website, the frontend calls the relative path /api/ai/... with fetch — no tokens are exposed in the browser.

Routes

Method Path Purpose
POST /api/ai/recommend-plan Recommend one Swapps path with rationale, plan info, and alternatives.
POST /api/ai/refine Refine free text into a categorized breakdown + /get-swapps/ field classification.
GET /api/ai/search-test?q=… Direct AI Search probe — returns the top indexed chunks.

See the API reference for full request/response schemas.

Tech stack

  • Cloudflare Workers (TypeScript, ES modules).
  • Workers AI via the AI binding (env.AI.run(...)).
  • AI Search (RAG) via the SWAPPS_AI_SEARCH binding, instance swapps-ai-search.
  • Vitest for tests; Wrangler for local dev and deploy.

Bindings

Binding Type Notes
AI Workers AI Runs the chat model selected by AI_MODEL.
SWAPPS_AI_SEARCH AI Search Instance swapps-ai-search; provides optional RAG context.

Architecture at a glance

flowchart LR Website["Website (swapps-client)"] -->|"POST /api/ai/*"| Worker["swapps-ai Worker"] Worker -->|"env.AI.run(model, …)"| WorkersAI["Workers AI
(llama-3.2-3b-instruct)"] Worker -->|"SWAPPS_AI_SEARCH.search(…)"| AISearch["AI Search
(swapps-ai-search)"] AISearch -. "retrieved chunks (RAG)" .-> Worker WorkersAI -. "JSON text" .-> Worker Worker -->|"JSON response"| Website

Next steps

  • Architecture — how the Worker is structured, how Workers AI and RAG are wired, the plan model, locale handling, and input validation.
  • API reference — endpoints, request/response schemas, limits, and error shapes.
  • Development — local dev, testing, configuration, deployment, and the WAF skip.