Installation Guide — AuldLangSynth

Tip: These docs are now MkDocs-ready (see mkdocs.yml). Run mkdocs serve for a polished docs site.

Prerequisites

  • Node.js 18.17+ (Vite 5 requires 18.0+, but 18.17 or 20.x LTS is recommended; Node 16 is too old and will fail).
  • npm 9+ (comes with Node 18+/20+; npm 8.x from Node 16 is too old).
  • git (for cloning).
  • Optional tools:
  • npx puppeteer browsers install chrome if you need the YouTube fetch fallback.
  • yt-dlp on your PATH for restricted YouTube audio.
  • Qdrant instance (remote or local) if you want vector DB sync.

1) Clone the repo

git clone https://github.com/your-org/auldlangsynth.git
cd auldlangsynth

2) Install dependencies

npm install
  • Create .env.local in the project root and add the keys you plan to use:
  • GEMINI_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, etc.
  • Qdrant: QDRANT_HOST, QDRANT_API_KEY if applicable.
  • You can also set these via the in-app Environment view.

4) Run in development mode

npm run dev
  • Vite dev server defaults to http://localhost:5173.
  • Backend routes are mounted through Vite middleware; no separate server needed for dev.
  • Recommended: pair with Qdrant as the vector DB to enable higher-quality synthetic generations via retrieval and embedding feedback loops.

5) Build for production

npm run build
  • Runs TypeScript type-checking then builds the Vite app to dist/.

6) Preview the production build

npm run preview
  • Serves the built assets locally (defaults to http://localhost:4173).

7) Reverse-engineering backend (optional)

If you want to run the standalone reverse-engineering backend instead of the dev middleware:

npm run reverse-backend
  • Uses tsx server/start.ts. Ensure Node 18+ and required binary analysis deps are available.

Troubleshooting

  • Node too old: Upgrade to Node 18.17+ or 20.x if you see Vite/ESM errors.
  • Puppeteer missing Chrome: Run npx puppeteer browsers install chrome.
  • YouTube 403/restricted: Install yt-dlp and/or provide cookies in the Transcribe view.
  • Vector DB dimension mismatch: Confirm Qdrant collection vector size matches your embedding model; update via the app if needed.
  • Browser compatibility: Prefer Chromium-based browsers (Chrome/Edge/Brave) for heavy flows like mass uploads, chunking, and in-browser Whisper.js; they handle worker threads and streaming uploads more reliably than Safari/older Firefox. Keep the tab focused during long client-side tasks to avoid background throttling.