create-leo 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+- Initial public release.
+- Seven backend/RAG templates.
+- Interactive and flag-based generation.
+- Node 22+ native environment loading and watch mode.
+- Python 3.11+ with uv or venv + pip installation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# create-leo
+
+`create-leo` is a small, production-oriented backend generator for Node.js, FastAPI, databases, and RAG.
+
+## Requirements
+
+- Node.js 22+
+- Python 3.11+ for Python templates
+- `uv` is recommended for Python dependency installation, but Leo falls back to `venv` + `pip`
+
+## Use
+
+```bash
+npx create-leo my-api
+```
+
+Choose one of seven templates:
+
+| ID | Stack |
+|---|---|
+| `express-mongodb` | Express 5 + Mongoose + MongoDB |
+| `express-postgres` | Express 5 + pg + PostgreSQL |
+| `fastify-postgres` | Fastify + pg + PostgreSQL |
+| `fastapi-postgres` | FastAPI + SQLAlchemy + PostgreSQL |
+| `fastapi-mongodb` | FastAPI + native async PyMongo |
+| `semantic` | FastAPI + FastEmbed + local Qdrant + OpenAI-compatible LLM |
+| `hybrid` | Semantic + BM25 + RRF + optional cross-encoder |
+
+### Non-interactive
+
+```bash
+npx create-leo my-api --template express-mongodb
+npx create-leo my-rag --template hybrid --no-install
+npx create-leo --list
+```
+
+`--no-install` is useful for CI, smoke tests, or when you want to install dependencies yourself.
+
+## Design choices
+
+- Node 22 native `--watch` and `--env-file`; no nodemon or dotenv.
+- ESM everywhere in Node templates.
+- Express 5 async handlers; no custom async wrapper.
+- FastAPI configuration uses `pydantic-settings`.
+- MongoDB Python uses PyMongo's async client rather than Motor.
+- RAG uses FastEmbed/ONNX rather than sentence-transformers + torch.
+- Qdrant runs in local file mode; no Qdrant server is required for the starter.
+- LLM calls use the OpenAI client with configurable `LLM_BASE_URL`.
+- No LangChain dependency.
+- Hybrid RAG overlays the semantic pipeline instead of duplicating ingestion.
+- Every template has a DB-independent `/health` endpoint.
+
+## Free-tier development
+
+The generated projects do not require a paid service. For hosted free tiers, use a provider appropriate to the database you choose, or run the database locally. RAG's local Qdrant storage is file-based. An LLM key is only needed when you want generated answers rather than retrieved context.
+
+The first FastEmbed query downloads its embedding model. This is expected.
+
+## Publishing
+
+Before publishing, verify the package name is available:
+
+```bash
+npm view create-leo
+node scripts/check-name.mjs
+```
+
+If it is unavailable, use `create-leo-cli` or a scoped package.
+
+Then:
+
+```bash
+npm login
+npm publish
+```
+
+The `prepublishOnly` script resolves current Node dependency versions, builds `dist`, and runs tests.
+
+## Testing
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+CI generates all templates with `--no-install` and checks their basic filesystem output.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { parseArgs } from "util";
+import * as p3 from "@clack/prompts";
+import pc3 from "picocolors";
+
+// src/registry.ts
+var templates = [
+  { id: "express-mongodb", label: "Express + MongoDB", group: "Node.js", language: "node", description: "Express 5 API with Mongoose and MongoDB", postInstall: ["npm install"] },
+  { id: "express-postgres", label: "Express + PostgreSQL", group: "Node.js", language: "node", description: "Express 5 API with pg Pool and PostgreSQL", postInstall: ["npm install"] },
+  { id: "fastify-postgres", label: "Fastify + PostgreSQL", group: "Node.js", language: "node", description: "Fastify API with pg Pool and PostgreSQL", postInstall: ["npm install"] },
+  { id: "fastapi-postgres", label: "FastAPI + PostgreSQL", group: "Python", language: "python", description: "FastAPI with SQLAlchemy and PostgreSQL", postInstall: ["python -m pip install -r requirements.txt"] },
+  { id: "fastapi-mongodb", label: "FastAPI + MongoDB", group: "Python", language: "python", description: "FastAPI with native async PyMongo", postInstall: ["python -m pip install -r requirements.txt"] },
+  { id: "semantic", label: "Semantic RAG", group: "AI / RAG", language: "python", description: "FastAPI + FastEmbed + local Qdrant + configurable LLM", postInstall: ["python -m pip install -r requirements.txt"] },
+  { id: "hybrid", label: "Hybrid RAG", group: "AI / RAG", language: "python", description: "Semantic RAG plus BM25, RRF fusion and optional reranking", postInstall: ["python -m pip install -r requirements.txt"], overlay: "semantic" }
+];
+function getTemplate(id) {
+  return templates.find((t) => t.id === id);
+}
+
+// src/prompts.ts
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+async function interactive(templateArg, nameArg) {
+  p.intro(pc.bold("\u25C7 Leo \u2014 backend project generator"));
+  let templateId = templateArg;
+  if (!templateId) {
+    const selected = await p.select({
+      message: "Choose a backend template",
+      options: templates.map((t) => ({ value: t.id, label: t.label, hint: `${t.group} \xB7 ${t.description}` }))
+    });
+    if (p.isCancel(selected)) return null;
+    templateId = selected;
+  }
+  let name = nameArg;
+  if (!name) {
+    const value = await p.text({ message: "Project name", placeholder: "my-api", validate: (v) => /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(v) ? void 0 : "Use letters, numbers, dots, dashes or underscores." });
+    if (p.isCancel(value)) return null;
+    name = value;
+  }
+  return { templateId, name };
+}
+
+// src/generate.ts
+import path3 from "path";
+import { mkdir as mkdir2, cp as cp2, readFile as readFile2, writeFile as writeFile2, rm } from "fs/promises";
+import { fileURLToPath } from "url";
+import * as p2 from "@clack/prompts";
+import pc2 from "picocolors";
+
+// src/utils/fs.ts
+import { cp, mkdir, readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import path from "path";
+async function copyDir(src, dest) {
+  await mkdir(dest, { recursive: true });
+  await cp(src, dest, { recursive: true, force: true, errorOnExist: false });
+}
+async function replaceInTree(root, replacements) {
+  const entries = await walk(root);
+  for (const file of entries) {
+    if (!file.endsWith(".json") && !file.endsWith(".md") && !file.endsWith(".txt") && !file.endsWith(".env.example") && !file.endsWith(".py") && !file.endsWith(".js") && !file.endsWith(".ts")) continue;
+    const buf = await readFile(file);
+    if (buf.includes(0)) continue;
+    let text2 = buf.toString("utf8");
+    for (const [from, to] of Object.entries(replacements)) text2 = text2.split(from).join(to);
+    await writeFile(file, text2);
+  }
+}
+async function walk(dir) {
+  const { readdir, stat } = await import("fs/promises");
+  const out = [];
+  for (const entry of await readdir(dir)) {
+    const full = path.join(dir, entry);
+    const s = await stat(full);
+    if (s.isDirectory()) out.push(...await walk(full));
+    else out.push(full);
+  }
+  return out;
+}
+function pathExists(p4) {
+  return existsSync(p4);
+}
+
+// src/utils/process.ts
+import { spawn } from "child_process";
+function executable(command) {
+  if (process.platform !== "win32") return command;
+  if (command === "npm") return "npm.cmd";
+  if (command === "pnpm") return "pnpm.cmd";
+  if (command === "yarn") return "yarn.cmd";
+  if (command === "bun") return "bun.exe";
+  return command;
+}
+function run(command, args, cwd, env, shell = false) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable(command), args, {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: "inherit",
+      // Windows cannot launch .cmd shims (npm.cmd, uv.cmd, etc.) directly.
+      // Callers opt into the shell only for trusted, fixed package-manager args.
+      shell
+    });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with ${code ?? signal}`));
+    });
+  });
+}
+async function commandExists(command) {
+  const checker = process.platform === "win32" ? "where" : "which";
+  return new Promise((resolve) => {
+    const child = spawn(checker, [command], { stdio: "ignore", shell: false });
+    child.on("exit", (code) => resolve(code === 0));
+    child.on("error", () => resolve(false));
+  });
+}
+
+// src/install/node.ts
+function packageManager() {
+  const ua = process.env.npm_config_user_agent ?? "";
+  if (ua.startsWith("pnpm/")) return "pnpm";
+  if (ua.startsWith("yarn/")) return "yarn";
+  if (ua.startsWith("bun/")) return "bun";
+  return "npm";
+}
+async function installNode(projectDir) {
+  const manager = packageManager();
+  if (!await commandExists(manager)) throw new Error(`${manager} was not found. Install it or use npm.`);
+  const args = manager === "yarn" ? ["install"] : ["install"];
+  await run(manager, args, projectDir, void 0, process.platform === "win32");
+}
+
+// src/install/python.ts
+import path2 from "path";
+async function pythonCommand() {
+  if (process.platform === "win32" && await commandExists("py")) return "py";
+  if (await commandExists("python3")) return "python3";
+  if (await commandExists("python")) return "python";
+  throw new Error("Python 3.11+ was not found. Install Python or uv first.");
+}
+async function checkPython311(py) {
+  const { execFileSync } = await import("child_process");
+  try {
+    const args = process.platform === "win32" && py === "py" ? ["-3", "--version"] : ["--version"];
+    const output = execFileSync(py, args, { encoding: "utf8" }).trim();
+    const match = output.match(/Python (\d+)\.(\d+)/);
+    if (!match || Number(match[1]) < 3 || Number(match[1]) === 3 && Number(match[2]) < 11) {
+      throw new Error(`Python 3.11+ required; found ${output}`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Python 3.11+ required")) throw error;
+    throw new Error("Unable to verify Python 3.11+. Install a supported Python runtime.");
+  }
+}
+async function installPython(projectDir) {
+  const py = await pythonCommand();
+  await checkPython311(py);
+  if (await commandExists("uv")) {
+    await run("uv", ["venv", ".venv", "--python", "3.11"], projectDir);
+    const uvPython = path2.join(
+      projectDir,
+      ".venv",
+      process.platform === "win32" ? "Scripts" : "bin",
+      process.platform === "win32" ? "python.exe" : "python"
+    );
+    await run(uvPython, ["-m", "pip", "install", "-r", "requirements.txt"], projectDir);
+    return;
+  }
+  const pyArgs = process.platform === "win32" && py === "py" ? ["-3"] : [];
+  await run(py, [...pyArgs, "-m", "venv", ".venv"], projectDir);
+  const venvPython = path2.join(
+    projectDir,
+    process.platform === "win32" ? ".venv" : ".venv",
+    process.platform === "win32" ? "Scripts" : "bin",
+    process.platform === "win32" ? "python.exe" : "python"
+  );
+  await run(venvPython, ["-m", "pip", "install", "-r", "requirements.txt"], projectDir);
+}
+
+// src/generate.ts
+var here = path3.dirname(fileURLToPath(import.meta.url));
+var packageRoot = path3.resolve(here, "..");
+var templateRoot = path3.join(packageRoot, "templates");
+async function renameGitignore(root) {
+  const entries = await walk(root);
+  for (const file of entries) {
+    if (path3.basename(file) === "_gitignore") {
+      await cp2(file, path3.join(path3.dirname(file), ".gitignore"));
+      await rm(file);
+    }
+  }
+}
+async function patchPackageJson(root, name) {
+  const pkg = path3.join(root, "package.json");
+  if (!pathExists(pkg)) return;
+  const json = JSON.parse(await readFile2(pkg, "utf8"));
+  json.name = name;
+  await writeFile2(pkg, JSON.stringify(json, null, 2) + "\n");
+}
+async function generate(templateId, projectName, noInstall = false) {
+  const template = getTemplate(templateId);
+  if (!template) throw new Error(`Unknown template: ${templateId}`);
+  const target = path3.resolve(process.cwd(), projectName);
+  if (pathExists(target)) throw new Error(`Target folder already exists: ${target}`);
+  let committed = false;
+  const onInterrupt = async () => {
+    await rm(target, { recursive: true, force: true });
+    process.exit(130);
+  };
+  process.once("SIGINT", onInterrupt);
+  try {
+    await mkdir2(target, { recursive: true });
+    await copyDir(path3.join(templateRoot, "_shared"), target);
+    if (template.overlay) await copyDir(path3.join(templateRoot, template.overlay), target);
+    await copyDir(path3.join(templateRoot, template.id), target);
+    await replaceInTree(target, { "{{name}}": projectName });
+    await patchPackageJson(target, projectName);
+    const envExample = path3.join(target, ".env.example");
+    if (pathExists(envExample)) await cp2(envExample, path3.join(target, ".env"));
+    await renameGitignore(target);
+    committed = true;
+    if (!noInstall) {
+      const spin = p2.spinner();
+      spin.start(`Installing ${template.language} dependencies`);
+      try {
+        if (template.language === "node") await installNode(target);
+        else await installPython(target);
+        spin.stop("Dependencies installed");
+      } catch (error) {
+        spin.stop("Dependency installation failed");
+        throw error;
+      }
+    }
+    printNextSteps(target, projectName, template);
+    return target;
+  } catch (error) {
+    await rm(target, { recursive: true, force: true });
+    throw error;
+  } finally {
+    process.removeListener("SIGINT", onInterrupt);
+  }
+}
+function printNextSteps(target, name, template) {
+  const rel = path3.relative(process.cwd(), target) || name;
+  console.log(`
+${pc2.green("\u2714")} Created ${pc2.bold(name)} using ${template.label}`);
+  console.log(`
+${pc2.dim("Next steps")}`);
+  console.log(`  ${pc2.cyan(`cd ${rel}`)}`);
+  if (template.language === "node") {
+    console.log(`  ${pc2.cyan("cp .env.example .env")}`);
+    console.log(`  ${pc2.cyan("npm run dev")}`);
+  } else {
+    console.log(`  ${pc2.cyan("cp .env.example .env")}`);
+    console.log(`  ${pc2.cyan("source .venv/bin/activate")} ${pc2.dim("(macOS/Linux)")}`);
+    console.log(`  ${pc2.cyan("uvicorn app.main:app --reload")} ${pc2.dim("(or use the Windows venv equivalent)")}`);
+  }
+  console.log(`
+${pc2.dim("Health:")} ${pc2.cyan("GET /health")}`);
+}
+
+// src/index.ts
+var { values, positionals } = parseArgs({
+  options: {
+    template: { type: "string", short: "t" },
+    "no-install": { type: "boolean", default: false },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+    list: { type: "boolean" }
+  },
+  allowPositionals: true,
+  strict: true
+});
+if (values.version) {
+  console.log("0.1.0");
+  process.exit(0);
+}
+if (values.help) {
+  console.log(`${pc3.bold("create-leo")} \u2014 lightweight backend project generator
+
+Usage:
+  npx create-leo [project-name]
+  npx create-leo my-api --template express-mongodb
+  npx create-leo my-rag --template semantic --no-install
+
+Options:
+  -t, --template <id>  Generate directly from a template
+      --no-install     Skip dependency installation
+      --list           List templates
+  -h, --help            Show help
+  -v, --version         Show version
+
+Templates:
+${templates.map((t) => `  ${t.id.padEnd(20)} ${t.description}`).join("\n")}`);
+  process.exit(0);
+}
+if (values.list) {
+  for (const t of templates) console.log(`${t.id}	${t.description}`);
+  process.exit(0);
+}
+try {
+  if (values.template && !getTemplate(values.template)) throw new Error(`Unknown template '${values.template}'. Run --list to see valid IDs.`);
+  const chosen = await interactive(values.template, positionals[0]);
+  if (!chosen) process.exit(0);
+  await generate(chosen.templateId, chosen.name, values["no-install"]);
+} catch (error) {
+  if (error.code === "ERR_USE_AFTER_CLOSE") process.exit(130);
+  console.error(`
+${pc3.red("\u2716")} ${error instanceof Error ? error.message : String(error)}`);
+  p3.outro(pc3.dim("No partial project was left behind."));
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "create-leo",
+  "version": "0.1.0",
+  "description": "A lightweight project generator for production-oriented Node.js, FastAPI, database and RAG backends.",
+  "type": "module",
+  "bin": { "create-leo": "dist/index.js", "leo": "dist/index.js" },
+  "files": ["dist", "templates", "README.md", "LICENSE", "CHANGELOG.md", "versions.json"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --target node22 --clean",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "resolve-versions": "node scripts/resolve-versions.mjs",
+    "prepublishOnly": "npm run resolve-versions && npm run build && npm test"
+  },
+  "engines": { "node": ">=22.0.0" },
+  "packageManager": "npm@11",
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}

package/templates/_shared/README.md

@@ -0,0 +1,11 @@
+# {{name}}
+
+Generated by Leo.
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in the values for your environment.
+
+## Health
+
+`GET /health` is intentionally independent of the database so the service can boot before a database is available.

package/templates/_shared/_gitignore

@@ -0,0 +1,8 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+node_modules/
+dist/
+.qdrant/
+.pytest_cache/

package/templates/express-mongodb/.env.example

@@ -0,0 +1,2 @@
+PORT=3000
+MONGODB_URI=mongodb://127.0.0.1:27017/{{name}}

package/templates/express-mongodb/README.md

@@ -0,0 +1,13 @@
+# {{name}}
+
+Express 5 + MongoDB starter using Node 22 native `--watch` and `--env-file`.
+
+## Run
+
+```bash
+cp .env.example .env
+npm run dev
+```
+
+MongoDB is connected lazily after startup. `GET /health` works without MongoDB.
+For a free hosted database, use MongoDB Atlas and put its URI in `MONGODB_URI`.

package/templates/express-mongodb/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "dev": "node --watch --env-file=.env src/server.js",
+    "start": "node --env-file=.env src/server.js"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "mongoose": "^8.18.0"
+  }
+}

package/templates/express-mongodb/src/app.js

@@ -0,0 +1,11 @@
+import express from 'express';
+import cors from 'cors';
+import health from './routes/health.js';
+import examples from './routes/examples.js';
+import { errorHandler } from './middleware/error.js';
+export const app = express();
+app.use(cors());
+app.use(express.json());
+app.use(health);
+app.use('/api/examples', examples);
+app.use(errorHandler);

package/templates/express-mongodb/src/config/db.js

@@ -0,0 +1,9 @@
+import mongoose from 'mongoose';
+
+let connected = false;
+export async function connectDb() {
+  if (connected) return;
+  await mongoose.connect(process.env.MONGODB_URI);
+  connected = true;
+}
+export function dbState() { return mongoose.connection.readyState; }

package/templates/express-mongodb/src/middleware/error.js

@@ -0,0 +1,4 @@
+export function errorHandler(err, _req, res, _next) {
+  console.error(err);
+  res.status(err.statusCode ?? 500).json({ error: err.message ?? 'Internal server error' });
+}

package/templates/express-mongodb/src/models/example.js

@@ -0,0 +1,2 @@
+import mongoose from 'mongoose';
+export const Example = mongoose.model('Example', new mongoose.Schema({ name: { type: String, required: true } }, { timestamps: true }));

package/templates/express-mongodb/src/routes/examples.js

@@ -0,0 +1,6 @@
+import { Router } from 'express';
+import { Example } from '../models/example.js';
+const router = Router();
+router.get('/', async (_req, res) => res.json(await Example.find().lean()));
+router.post('/', async (req, res) => res.status(201).json(await Example.create(req.body)));
+export default router;

package/templates/express-mongodb/src/routes/health.js

@@ -0,0 +1,5 @@
+import { Router } from 'express';
+import { dbState } from '../config/db.js';
+const router = Router();
+router.get('/health', (_req, res) => res.json({ status: 'ok', database: dbState() === 1 ? 'connected' : 'not-connected' }));
+export default router;

package/templates/express-mongodb/src/server.js

@@ -0,0 +1,5 @@
+import { app } from './app.js';
+import { connectDb } from './config/db.js';
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => console.log(`API listening on http://localhost:${port}`));
+connectDb().catch((err) => console.warn('MongoDB unavailable; /health remains available:', err.message));

package/templates/express-postgres/.env.example

@@ -0,0 +1,2 @@
+PORT=3000
+DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/{{name}}

package/templates/express-postgres/README.md

@@ -0,0 +1,6 @@
+# {{name}}
+
+Express 5 + PostgreSQL starter. The `pg` Pool is created once and shared by the app.
+
+`GET /health` does not require PostgreSQL to be running.
+For free hosted PostgreSQL, Neon is a simple option; place its connection string in `DATABASE_URL`.

package/templates/express-postgres/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "dev": "node --watch --env-file=.env src/server.js",
+    "start": "node --env-file=.env src/server.js"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "pg": "^8.16.3"
+  }
+}

package/templates/express-postgres/src/app.js

@@ -0,0 +1,7 @@
+import express from 'express';
+import cors from 'cors';
+import health from './routes/health.js';
+import examples from './routes/examples.js';
+import { errorHandler } from './middleware/error.js';
+export const app = express();
+app.use(cors()); app.use(express.json()); app.use(health); app.use('/api/examples', examples); app.use(errorHandler);

package/templates/express-postgres/src/config/db.js

@@ -0,0 +1,4 @@
+import pg from 'pg';
+const { Pool } = pg;
+export const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+export async function checkDb() { await pool.query('SELECT 1'); }

package/templates/express-postgres/src/middleware/error.js

@@ -0,0 +1 @@
+export function errorHandler(err, _req, res, _next) { console.error(err); res.status(err.statusCode ?? 500).json({ error: err.message ?? 'Internal server error' }); }

package/templates/express-postgres/src/routes/examples.js

@@ -0,0 +1,5 @@
+import { Router } from 'express';
+import { pool } from '../config/db.js';
+const router = Router();
+router.get('/', async (_req, res) => res.json((await pool.query('SELECT NOW() AS now')).rows));
+export default router;

package/templates/express-postgres/src/routes/health.js

@@ -0,0 +1,4 @@
+import { Router } from 'express';
+const router = Router();
+router.get('/health', (_req, res) => res.json({ status: 'ok' }));
+export default router;

package/templates/express-postgres/src/server.js

@@ -0,0 +1,5 @@
+import { app } from './app.js';
+import { checkDb } from './config/db.js';
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => console.log(`API listening on http://localhost:${port}`));
+checkDb().catch((err) => console.warn('PostgreSQL unavailable; /health remains available:', err.message));

package/templates/fastapi-mongodb/.env.example

@@ -0,0 +1,4 @@
+APP_ENV=development
+PORT=8000
+MONGODB_URI=mongodb://127.0.0.1:27017
+MONGODB_DB={{name}}

package/templates/fastapi-mongodb/README.md

@@ -0,0 +1,12 @@
+# {{name}}
+
+Generated by Leo.
+
+## Run
+
+```bash
+cp .env.example .env
+uvicorn app.main:app --reload --port 8000
+```
+
+If Leo created `.venv`, activate it first. The `/health` endpoint is independent of external services.

package/templates/fastapi-mongodb/_gitignore

@@ -0,0 +1,6 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.qdrant/
+.pytest_cache/

package/templates/fastapi-mongodb/app/api/routes/examples.py

@@ -0,0 +1,5 @@
+from fastapi import APIRouter
+from app.database.mongo import db
+router = APIRouter(prefix='/api/examples', tags=['examples'])
+@router.get('/')
+async def examples(): return await db.example.find().to_list(100)

package/templates/fastapi-mongodb/app/api/routes/health.py

@@ -0,0 +1,4 @@
+from fastapi import APIRouter
+router = APIRouter()
+@router.get('/health')
+async def health(): return {'status': 'ok'}

package/templates/fastapi-mongodb/app/core/config.py

@@ -0,0 +1,6 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+class Settings(BaseSettings):
+    app_env: str = 'development'; port: int = 8000
+    mongodb_uri: str = 'mongodb://127.0.0.1:27017'; mongodb_db: str = '{{name}}'
+    model_config = SettingsConfigDict(env_file='.env', extra='ignore')
+settings = Settings()

package/templates/fastapi-mongodb/app/database/mongo.py

@@ -0,0 +1,4 @@
+from pymongo import AsyncMongoClient
+from app.core.config import settings
+client = AsyncMongoClient(settings.mongodb_uri)
+db = client[settings.mongodb_db]

package/templates/fastapi-mongodb/app/main.py

@@ -0,0 +1,6 @@
+from fastapi import FastAPI
+from app.api.routes.health import router as health_router
+from app.api.routes.examples import router as examples_router
+app = FastAPI(title='{{name}}')
+app.include_router(health_router)
+app.include_router(examples_router)

package/templates/fastapi-mongodb/requirements.txt

@@ -0,0 +1,4 @@
+fastapi==0.142.2
+uvicorn==0.54.0
+pydantic-settings==2.15.0
+pymongo==4.18.2

package/templates/fastapi-postgres/.env.example

@@ -0,0 +1,3 @@
+APP_ENV=development
+PORT=8000
+DATABASE_URL=postgresql+psycopg://postgres:postgres@127.0.0.1:5432/{{name}}

package/templates/fastapi-postgres/README.md

@@ -0,0 +1,12 @@
+# {{name}}
+
+Generated by Leo.
+
+## Run
+
+```bash
+cp .env.example .env
+uvicorn app.main:app --reload --port 8000
+```
+
+If Leo created `.venv`, activate it first. The `/health` endpoint is independent of external services.

package/templates/fastapi-postgres/_gitignore

@@ -0,0 +1,6 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.qdrant/
+.pytest_cache/

package/templates/fastapi-postgres/app/api/routes/examples.py

@@ -0,0 +1,7 @@
+from fastapi import APIRouter
+from sqlalchemy import text
+from app.database.session import engine
+router = APIRouter(prefix='/api/examples', tags=['examples'])
+@router.get('/')
+def examples():
+    with engine.connect() as conn: return [dict(row) for row in conn.execute(text('SELECT NOW() AS now')).mappings()]

package/templates/fastapi-postgres/app/api/routes/health.py

@@ -0,0 +1,4 @@
+from fastapi import APIRouter
+router = APIRouter()
+@router.get('/health')
+def health(): return {'status': 'ok'}

package/templates/fastapi-postgres/app/core/config.py

@@ -0,0 +1,7 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+class Settings(BaseSettings):
+    app_env: str = 'development'
+    port: int = 8000
+    database_url: str = 'postgresql+psycopg://postgres:postgres@127.0.0.1:5432/{{name}}'
+    model_config = SettingsConfigDict(env_file='.env', extra='ignore')
+settings = Settings()

package/templates/fastapi-postgres/app/database/session.py

@@ -0,0 +1,3 @@
+from sqlalchemy import create_engine
+from app.core.config import settings
+engine = create_engine(settings.database_url, pool_pre_ping=True)

package/templates/fastapi-postgres/app/main.py

@@ -0,0 +1,6 @@
+from fastapi import FastAPI
+from app.api.routes.health import router as health_router
+from app.api.routes.examples import router as examples_router
+app = FastAPI(title='{{name}}')
+app.include_router(health_router)
+app.include_router(examples_router)

package/templates/fastapi-postgres/requirements.txt

@@ -0,0 +1,5 @@
+fastapi==0.142.2
+uvicorn==0.54.0
+pydantic-settings==2.15.0
+sqlalchemy==2.1.2
+psycopg==3.3.6

package/templates/fastify-postgres/.env.example

@@ -0,0 +1,2 @@
+PORT=3000
+DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/{{name}}

package/templates/fastify-postgres/README.md

@@ -0,0 +1,5 @@
+# {{name}}
+
+Fastify + PostgreSQL starter. The DB plugin is registered once and exposes a shared `pg` Pool.
+
+`GET /health` works before PostgreSQL is available.

package/templates/fastify-postgres/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "dev": "node --watch --env-file=.env src/server.js",
+    "start": "node --env-file=.env src/server.js"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.1.0",
+    "fastify": "^5.6.0",
+    "pg": "^8.16.3"
+  }
+}

package/templates/fastify-postgres/src/app.js

@@ -0,0 +1,14 @@
+import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import { createDb } from './plugins/db.js';
+import health from './routes/health.js';
+export function buildApp() {
+  const app = Fastify({ logger: true });
+  app.register(cors);
+  const db = createDb();
+  app.decorate('db', db);
+  app.addHook('onClose', async () => db.end());
+  app.register(health);
+  app.get('/api/examples', async () => (await app.db.query('SELECT NOW() AS now')).rows);
+  return app;
+}

package/templates/fastify-postgres/src/plugins/db.js

@@ -0,0 +1,3 @@
+import pg from 'pg';
+const { Pool } = pg;
+export function createDb() { return new Pool({ connectionString: process.env.DATABASE_URL }); }

package/templates/fastify-postgres/src/routes/health.js

@@ -0,0 +1 @@
+export default async function health(fastify) { fastify.get('/health', async () => ({ status: 'ok' })); }

package/templates/fastify-postgres/src/server.js

@@ -0,0 +1,4 @@
+import { buildApp } from './app.js';
+const app = buildApp();
+const port = Number(process.env.PORT ?? 3000);
+try { await app.listen({ port, host: '0.0.0.0' }); } catch (err) { app.log.error(err); process.exit(1); }

package/templates/hybrid/.env.example

@@ -0,0 +1,8 @@
+APP_ENV=development
+PORT=8000
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_API_KEY=
+LLM_MODEL=gpt-4o-mini
+EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+QDRANT_PATH=.qdrant
+RERANK=false

package/templates/hybrid/README.md

@@ -0,0 +1,27 @@
+# {{name}}
+
+Hybrid RAG project skeleton.
+
+Leo installs the dependencies and creates the folder structure; the retrieval/ingestion implementation is intentionally left for you to build.
+
+Hybrid is designed as a thin retrieval overlay on top of the semantic architecture: semantic search + BM25 + RRF + optional cross-encoder reranking. Keep one ingestion pipeline.
+
+## Dependencies
+
+Includes all Semantic RAG dependencies plus:
+
+- `bm25s` — lexical/BM25 retrieval
+
+The reranker uses the cross-encoder support provided by FastEmbed.
+
+## Structure
+
+- `app/main.py` — application entry point
+- `app/api/routes/ingest.py` — shared ingestion route
+- `app/api/routes/query.py` — hybrid query route
+- `app/core/config.py` — settings
+- `app/retrieval/bm25.py` — lexical retrieval
+- `app/retrieval/fusion.py` — RRF fusion
+- `app/retrieval/reranker.py` — optional cross-encoder reranking
+
+Each Python file contains only a short note describing its responsibility.

package/templates/hybrid/_gitignore

@@ -0,0 +1,6 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.qdrant/
+.pytest_cache/

package/templates/hybrid/app/api/routes/ingest.py

@@ -0,0 +1,4 @@
+"""Document ingestion route placeholder.
+
+Significance: keep one ingestion pipeline shared with semantic retrieval; hybrid search should not duplicate ingestion.
+"""

package/templates/hybrid/app/api/routes/query.py

@@ -0,0 +1,4 @@
+"""Hybrid RAG query route placeholder.
+
+Significance: combine semantic retrieval with lexical BM25 retrieval, fuse results with RRF, optionally rerank, then generate an answer.
+"""

package/templates/hybrid/app/core/config.py

@@ -0,0 +1,4 @@
+"""Hybrid RAG configuration placeholder.
+
+Significance: define LLM, embedding, Qdrant, and reranker settings from environment variables here.
+"""

package/templates/hybrid/app/main.py

@@ -0,0 +1,4 @@
+"""Entry point for the Hybrid RAG application.
+
+Significance: create the FastAPI application and connect the hybrid retrieval routes here.
+"""

package/templates/hybrid/app/retrieval/bm25.py

@@ -0,0 +1,4 @@
+"""BM25 retrieval placeholder.
+
+Significance: provide lexical/keyword retrieval to complement semantic vector search.
+"""

package/templates/hybrid/app/retrieval/fusion.py

@@ -0,0 +1,4 @@
+"""Rank-fusion placeholder.
+
+Significance: combine semantic and BM25 result rankings with Reciprocal Rank Fusion (RRF).
+"""

package/templates/hybrid/app/retrieval/reranker.py

@@ -0,0 +1,4 @@
+"""Reranker placeholder.
+
+Significance: optionally apply a FastEmbed cross-encoder to reorder the fused candidates by relevance.
+"""

package/templates/hybrid/requirements.txt

@@ -0,0 +1,9 @@
+fastapi==0.142.2
+uvicorn==0.54.0
+pydantic-settings==2.15.0
+python-multipart==0.0.32
+pypdf==6.19.0
+fastembed==0.8.1
+qdrant-client==1.19.1
+openai==3.24.0
+bm25s==0.3.11

package/templates/semantic/.env.example

@@ -0,0 +1,7 @@
+APP_ENV=development
+PORT=8000
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_API_KEY=
+LLM_MODEL=gpt-4o-mini
+EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+QDRANT_PATH=.qdrant

package/templates/semantic/README.md

@@ -0,0 +1,31 @@
+# {{name}}
+
+Semantic RAG project skeleton.
+
+Leo installs the dependencies and creates the folder structure; the RAG implementation is intentionally left for you to build.
+
+## Dependencies
+
+- `fastapi` / `uvicorn[standard]` — API server
+- `pydantic-settings` — typed environment configuration
+- `python-multipart` — file uploads
+- `pypdf` — PDF text extraction
+- `fastembed` — lightweight ONNX embeddings
+- `qdrant-client` — local vector storage/client
+- `openai` — OpenAI-compatible LLM client
+
+## Structure
+
+- `app/main.py` — application entry point
+- `app/api/routes/ingest.py` — document ingestion route
+- `app/api/routes/query.py` — retrieval/query route
+- `app/api/routes/health.py` — health endpoint
+- `app/core/config.py` — settings
+- `app/services/chunker.py` — chunking logic
+- `app/services/llm.py` — LLM integration
+- `app/vectorstore/qdrant.py` — vector-store integration
+
+The API starts with `uvicorn app.main:app --reload` and exposes `GET /health`.
+The ingestion and retrieval pipeline is a skeleton for you to implement.
+
+The first real embedding operation will download the selected FastEmbed model.

package/templates/semantic/_gitignore

@@ -0,0 +1,6 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.qdrant/
+.pytest_cache/

package/templates/semantic/app/api/routes/health.py

@@ -0,0 +1,10 @@
+"""Lightweight health endpoint for the semantic RAG API."""
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}

package/templates/semantic/app/api/routes/ingest.py

@@ -0,0 +1,4 @@
+"""Document ingestion route placeholder.
+
+Significance: receive documents, extract text, chunk it, create embeddings, and store vectors here.
+"""

package/templates/semantic/app/api/routes/query.py

@@ -0,0 +1,4 @@
+"""RAG query route placeholder.
+
+Significance: accept a user question, retrieve relevant chunks, and pass context to an LLM here.
+"""

package/templates/semantic/app/core/config.py

@@ -0,0 +1,4 @@
+"""Application configuration placeholder.
+
+Significance: define typed settings and environment-variable loading here.
+"""

package/templates/semantic/app/main.py

@@ -0,0 +1,8 @@
+"""FastAPI application entry point for the semantic RAG project."""
+
+from fastapi import FastAPI
+
+from app.api.routes.health import router as health_router
+
+app = FastAPI(title="Semantic RAG API")
+app.include_router(health_router)

package/templates/semantic/app/services/chunker.py

@@ -0,0 +1,4 @@
+"""Text chunking placeholder.
+
+Significance: split extracted documents into retrieval-friendly chunks while preserving useful context.
+"""

package/templates/semantic/app/services/llm.py

@@ -0,0 +1,4 @@
+"""LLM client placeholder.
+
+Significance: configure the OpenAI-compatible client and generate an answer from retrieved context here.
+"""

package/templates/semantic/app/vectorstore/qdrant.py

@@ -0,0 +1,4 @@
+"""Qdrant/vector-store placeholder.
+
+Significance: initialize local Qdrant, create the collection, store embeddings, and perform vector search here.
+"""

package/templates/semantic/requirements.txt

@@ -0,0 +1,8 @@
+fastapi==0.142.2
+uvicorn==0.54.0
+pydantic-settings==2.15.0
+python-multipart==0.0.32
+pypdf==6.19.0
+fastembed==0.8.1
+qdrant-client==1.19.1
+openai==3.24.0

package/versions.json

@@ -0,0 +1,24 @@
+{
+  "node": {
+    "express": "^5.1.0",
+    "mongoose": "^8.18.0",
+    "cors": "^2.8.5",
+    "pg": "^8.16.3",
+    "fastify": "^5.6.0",
+    "@fastify/cors": "^11.1.0"
+  },
+  "python": {
+    "fastapi": "fastapi==0.142.2",
+    "uvicorn": "uvicorn==0.54.0",
+    "pydantic-settings": "pydantic-settings==2.15.0",
+    "sqlalchemy": "sqlalchemy==2.1.2",
+    "psycopg": "psycopg==3.3.6",
+    "pymongo": "pymongo==4.18.2",
+    "python-multipart": "python-multipart==0.0.32",
+    "pypdf": "pypdf==6.19.0",
+    "fastembed": "fastembed==0.8.1",
+    "qdrant-client": "qdrant-client==1.19.1",
+    "openai": "openai==3.24.0",
+    "bm25s": "bm25s==0.3.11"
+  }
+}