create-atlas-agent 0.2.5

package/template/docs/deploy.md

@@ -0,0 +1,341 @@
+# Deploy Guides
+
+Atlas ships a multi-stage `Dockerfile` that produces a standalone Next.js build. It runs on any Docker-capable platform. This guide covers Docker, Railway, Fly.io, Render, and Vercel.
+
+---
+
+## Quick Deploy: Vercel
+
+Go from zero to production in 5 minutes.
+
+1. **Scaffold your project:**
+
+```bash
+bun create atlas-agent my-app
+cd my-app
+```
+
+2. **Push to GitHub:**
+
+```bash
+git init && git add -A && git commit -m "Initial commit"
+gh repo create my-app --public --source=. --push
+```
+
+3. **Import in Vercel:** Open the [Vercel Dashboard](https://vercel.com/), click **Add New > Project**, and import your repo. Vercel auto-detects Next.js via `vercel.json`.
+
+4. **Set environment variables** in the Vercel project settings:
+
+```
+ATLAS_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+DATABASE_URL=postgresql://user:pass@host:5432/dbname
+```
+
+5. **Deploy.** Vercel builds and deploys automatically.
+
+6. **Verify:** `https://<your-app>.vercel.app/api/health` -- should return `{"status":"ok"}`
+
+**What happens automatically on Vercel:**
+
+- The explore tool uses `@vercel/sandbox` instead of `just-bash` when the `VERCEL` env var is present (no config needed)
+- `output: "standalone"` is auto-skipped on Vercel (see `next.config.ts` -- the `VERCEL` env var check)
+- `maxDuration` is already set to 60s in the chat API route
+- `pg` and `just-bash` are in `serverExternalPackages` for serverless compatibility
+
+For more details, see the [full Vercel section](#vercel) below.
+
+---
+
+## Quick Deploy: Railway
+
+Go from zero to production with managed Postgres included.
+
+1. **Scaffold your project:**
+
+```bash
+bun create atlas-agent my-app
+cd my-app
+```
+
+2. **Push to GitHub:**
+
+```bash
+git init && git add -A && git commit -m "Initial commit"
+gh repo create my-app --public --source=. --push
+```
+
+3. **Create a Railway project:** Go to the [Railway Dashboard](https://railway.app/) and click **New Project**.
+
+4. **Add a Postgres plugin:** Click **+ New** inside the project and add **Database > PostgreSQL**. Link it to your web service -- Railway injects `DATABASE_URL` automatically.
+
+5. **Connect your repo:** Click **+ New > GitHub Repo** and select your repo. Railway detects `railway.json` and builds from the Dockerfile.
+
+6. **Set environment variables** in the Railway service settings (only 2 -- `DATABASE_URL` is already set):
+
+```
+ATLAS_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+7. **Seed your data.** Either seed the demo dataset or generate a semantic layer from your own tables:
+
+```bash
+# Option A: Demo data
+psql "$RAILWAY_DATABASE_URL" < data/demo.sql
+
+# Option B: Your own data
+DATABASE_URL="$RAILWAY_DATABASE_URL" bun run atlas -- init
+```
+
+8. **Deploy.** Railway builds and starts the container automatically.
+
+9. **Verify:** `https://<your-app>.up.railway.app/api/health` -- should return `{"status":"ok"}`
+
+**What happens automatically on Railway:**
+
+- `DATABASE_URL` is injected by the Postgres plugin -- no manual config needed
+- `railway.json` configures Dockerfile builds, health checks, and restart policy
+- The Docker `HEALTHCHECK` polls `/api/health` every 30 seconds
+
+For more details, see the [full Railway section](#railway) below.
+
+---
+
+## Required environment variables
+
+Every deployment needs these three:
+
+| Variable | Example |
+|----------|---------|
+| `ATLAS_PROVIDER` | `anthropic` |
+| Provider API key | `ANTHROPIC_API_KEY=sk-ant-...` |
+| `DATABASE_URL` | `postgresql://user:pass@host:5432/dbname` |
+
+Optional variables (safe defaults for most deployments):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ATLAS_MODEL` | Provider default | Override the LLM model |
+| `ATLAS_ROW_LIMIT` | `1000` | Max rows returned per query |
+| `ATLAS_QUERY_TIMEOUT` | `30000` | Query timeout in ms |
+| `PORT` | `3000` | Set automatically by most platforms |
+
+## Health check
+
+All deployments should verify with the health endpoint:
+
+```
+GET /api/health
+```
+
+Returns JSON with status `"ok"`, `"degraded"`, or `"error"` and sub-checks for database connectivity, provider configuration, and semantic layer presence. Returns HTTP 200 when status is `"ok"` or `"degraded"`, and HTTP 503 when status is `"error"` (database unreachable).
+
+---
+
+## Docker
+
+The `Dockerfile` uses a three-stage build: install deps, build Next.js standalone output, then run with a minimal image.
+
+### Build and run
+
+```bash
+docker build -t atlas .
+docker run -p 3000:3000 \
+  -e ATLAS_PROVIDER=anthropic \
+  -e ANTHROPIC_API_KEY=sk-ant-... \
+  -e DATABASE_URL=postgresql://user:pass@host:5432/dbname \
+  atlas
+```
+
+### Verify
+
+```bash
+curl http://localhost:3000/api/health
+```
+
+The Dockerfile includes a built-in `HEALTHCHECK` that polls `/api/health` every 30 seconds.
+
+### Notes
+
+- The image is based on `oven/bun:1.3`
+- Standalone output copies only what's needed: `.next/standalone`, `.next/static`, `public/`, and `semantic/`
+- The semantic layer (`semantic/`) is baked into the image at build time. If you update YAMLs, rebuild the image
+
+---
+
+## Railway
+
+Railway auto-detects the `Dockerfile` via `railway.json` at the repo root.
+
+### Steps
+
+1. Create a new Railway project
+2. Add a **Postgres** plugin (or use an external database)
+3. Connect your GitHub repo -- Railway detects `railway.json` and builds from the Dockerfile
+4. Set environment variables in the Railway dashboard:
+
+```
+ATLAS_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+DATABASE_URL=<Railway-provided Postgres URL>
+```
+
+5. If using the demo dataset, seed the database:
+
+```bash
+# Connect to the Railway Postgres and run the seed file
+psql "$RAILWAY_DATABASE_URL" < data/demo.sql
+```
+
+Or generate a semantic layer from your own data:
+
+```bash
+DATABASE_URL="$RAILWAY_DATABASE_URL" bun run atlas -- init
+```
+
+6. Deploy -- Railway builds and starts the container automatically
+
+### Configuration
+
+The `railway.json` config sets:
+
+- Dockerfile-based builds
+- Health check at `/api/health` with a 60-second timeout
+- Restart on failure (max 10 retries)
+
+### Verify
+
+Railway exposes a public URL. Check health at `https://<your-app>.up.railway.app/api/health`.
+
+---
+
+## Fly.io
+
+Atlas includes a `fly.toml` at the repo root.
+
+### Steps
+
+1. Install the [Fly CLI](https://fly.io/docs/flyctl/install/)
+
+2. Launch the app (without deploying yet):
+
+```bash
+fly launch --no-deploy
+```
+
+3. Set secrets:
+
+```bash
+fly secrets set \
+  DATABASE_URL="postgresql://user:pass@host:5432/dbname" \
+  ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+4. Deploy:
+
+```bash
+fly deploy
+```
+
+### Using Fly Postgres
+
+To use Fly's managed Postgres instead of an external database:
+
+```bash
+fly postgres create --name atlas-db
+fly postgres attach atlas-db
+```
+
+Fly automatically sets `DATABASE_URL` when you attach. Seed the demo data:
+
+```bash
+fly postgres connect --app atlas-db
+# Then in the psql shell, paste contents of data/demo.sql
+```
+
+### Configuration
+
+The `fly.toml` configures:
+
+- Region: `iad` (US East) -- change `primary_region` for your location
+- Health check: `GET /api/health` every 30 seconds
+- Auto-stop/start machines (scales to zero when idle)
+- VM: `shared-cpu-1x` with 512 MB memory
+
+### Verify
+
+```bash
+fly status
+curl https://<your-app>.fly.dev/api/health
+```
+
+---
+
+## Render
+
+Atlas includes a `render.yaml` Blueprint at the repo root.
+
+### Steps
+
+1. Go to the [Render Dashboard](https://dashboard.render.com/) and click **New > Blueprint**
+2. Connect your GitHub repo -- Render reads `render.yaml`
+3. Set the prompted environment variables:
+   - `DATABASE_URL` -- your Postgres connection string
+   - `ANTHROPIC_API_KEY` -- your API key
+4. Deploy
+
+### Using Render Postgres
+
+1. Create a Render Postgres instance from the dashboard
+2. Copy the **Internal Connection String**
+3. Set it as `DATABASE_URL` in the Atlas service environment
+
+### Configuration
+
+The `render.yaml` configures:
+
+- Docker-based deployment using the repo's `Dockerfile`
+- Health check at `/api/health`
+- Starter plan
+- `ATLAS_PROVIDER` defaults to `anthropic`
+- `autoDeploy` is disabled -- trigger deploys manually from the Render dashboard, or set `autoDeploy: true` in `render.yaml` to deploy on every push
+
+### Verify
+
+```bash
+curl https://<your-app>.onrender.com/api/health
+```
+
+---
+
+## Vercel
+
+Atlas supports Vercel-native deployment. On Vercel, the explore tool uses `@vercel/sandbox` instead of `just-bash` for shell operations.
+
+### Steps
+
+1. Import your repo in the [Vercel Dashboard](https://vercel.com/)
+2. Vercel auto-detects Next.js via `vercel.json` (framework: `nextjs`)
+3. Set environment variables:
+
+```
+ATLAS_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+DATABASE_URL=postgresql://user:pass@host:5432/dbname
+```
+
+4. Deploy
+
+### Notes
+
+- Vercel is auto-detected via the `VERCEL` environment variable -- no manual `ATLAS_RUNTIME` setting needed
+- The `output: "standalone"` build option is skipped on Vercel (Vercel uses its own build pipeline)
+- `@vercel/sandbox` is an optional dependency and only loaded when running on Vercel
+- `pg` and `just-bash` are listed in `serverExternalPackages` in `next.config.ts` for compatibility with serverless functions
+
+### Verify
+
+```bash
+curl https://<your-app>.vercel.app/api/health
+```

package/template/eslint.config.mjs

@@ -0,0 +1,18 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import nextPlugin from "@next/eslint-plugin-next";
+
+export default tseslint.config(
+  js.configs.recommended,
+  tseslint.configs.recommended,
+  {
+    plugins: { "@next/next": nextPlugin },
+    rules: {
+      ...nextPlugin.configs.recommended.rules,
+      ...nextPlugin.configs["core-web-vitals"].rules,
+    },
+  },
+  {
+    ignores: [".next/", "node_modules/"],
+  }
+);

package/template/fly.toml

@@ -0,0 +1,46 @@
+# Deploy Atlas on Fly.io
+#
+# Quick start:
+#   fly launch --no-deploy
+#   fly secrets set DATABASE_URL="postgresql://..." ANTHROPIC_API_KEY="sk-ant-..."
+#   fly deploy
+#
+# Attach Fly Postgres instead of an external DB (name is a suggestion):
+#   fly postgres create --name %PROJECT_NAME%-db
+#   fly postgres attach %PROJECT_NAME%-db
+
+app = "%PROJECT_NAME%"
+primary_region = "iad"
+
+[build]
+  dockerfile = "Dockerfile"
+
+[env]
+  HOSTNAME = "0.0.0.0"
+  ATLAS_PROVIDER = "anthropic"
+  # Secrets (set via `fly secrets set`):
+  #   DATABASE_URL
+  #   ANTHROPIC_API_KEY (or OPENAI_API_KEY, etc.)
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+  auto_stop_machines = "stop"
+  auto_start_machines = true
+  min_machines_running = 0
+
+[http_service.concurrency]
+  type = "requests"
+  hard_limit = 250
+  soft_limit = 200
+
+[[http_service.checks]]
+  grace_period = "30s"
+  interval = "30s"
+  method = "GET"
+  timeout = "5s"
+  path = "/api/health"
+
+[[vm]]
+  size = "shared-cpu-1x"
+  memory = "512mb"

package/template/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.next/
+.env
+.env.local
+*.tsbuildinfo

package/template/next.config.ts

@@ -0,0 +1,8 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  ...(process.env.VERCEL ? {} : { output: "standalone" }),
+  serverExternalPackages: ["pg", "just-bash"],
+};
+
+export default nextConfig;

package/template/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "%PROJECT_NAME%",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Atlas text-to-SQL data analyst agent",
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint src/",
+    "type": "tsgo --noEmit",
+    "atlas": "bun bin/atlas.ts",
+    "db:up": "docker compose up -d postgres",
+    "db:down": "docker compose down",
+    "db:reset": "docker compose down -v && docker compose up -d postgres",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ai-sdk/amazon-bedrock": "^4.0.63",
+    "@ai-sdk/anthropic": "^3.0.46",
+    "@ai-sdk/openai": "^3.0.31",
+    "@ai-sdk/react": "^3.0.99",
+    "ai": "^6.0.97",
+    "js-yaml": "^4.1.1",
+    "just-bash": "^2.10.2",
+    "next": "^16.1.6",
+    "node-sql-parser": "^5.4.0",
+    "pg": "^8.18.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "react-syntax-highlighter": "^16.1.0",
+    "recharts": "^3.7.0",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "@vercel/sandbox": "^1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@next/eslint-plugin-next": "^16.1.6",
+    "@tailwindcss/postcss": "^4.2.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.3.0",
+    "@types/pg": "^8.16.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "@typescript/native-preview": "^7.0.0-dev.20260223.1",
+    "eslint": "^10.0.2",
+    "tailwindcss": "^4.2.1",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.56.1"
+  }
+}

package/template/postcss.config.mjs

@@ -0,0 +1,8 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/template/railway.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "Dockerfile"
+  },
+  "deploy": {
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10,
+    "healthcheckPath": "/api/health",
+    "healthcheckTimeout": 60
+  }
+}

package/template/render.yaml

@@ -0,0 +1,19 @@
+# Render Blueprint — deploy Atlas with "New > Blueprint" pointing at this repo.
+# https://render.com/docs/infrastructure-as-code
+
+services:
+  - type: web
+    name: %PROJECT_NAME%
+    runtime: docker
+    dockerfilePath: ./Dockerfile
+    plan: starter
+    autoDeploy: false
+    healthCheckPath: /api/health
+    healthCheckTimeout: 15
+    envVars:
+      - key: DATABASE_URL
+        sync: false
+      - key: ATLAS_PROVIDER
+        value: anthropic
+      - key: ANTHROPIC_API_KEY
+        sync: false

package/template/semantic/catalog.yml

@@ -0,0 +1,5 @@
+# Atlas Semantic Layer — Catalog
+# Run `bun run atlas -- init` to auto-generate from your database.
+version: "1.0"
+entities: []
+glossary: glossary.yml

package/template/semantic/glossary.yml

@@ -0,0 +1,6 @@
+# Atlas Glossary — Business term definitions
+# Run `bun run atlas -- init` to auto-generate terms from your database.
+terms:
+  example_term:
+    status: defined
+    definition: Replace this with your own business terms

package/template/src/app/api/chat/route.ts

@@ -0,0 +1,107 @@
+import { type UIMessage } from "ai";
+import { runAgent } from "@/lib/agent";
+import { validateEnvironment } from "@/lib/startup";
+import { GatewayModelNotFoundError } from "@ai-sdk/gateway";
+
+export const maxDuration = 60;
+
+export async function POST(req: Request) {
+  // Startup diagnostics — fast-fail with actionable errors
+  const diagnostics = await validateEnvironment();
+  if (diagnostics.length > 0) {
+    return Response.json(
+      {
+        error: "configuration_error",
+        message: diagnostics.map((d) => d.message).join("\n\n"),
+        diagnostics,
+      },
+      { status: 400 }
+    );
+  }
+
+  // Parse request body separately so malformed JSON gets a 400, not 500
+  let messages: UIMessage[];
+  try {
+    ({ messages } = await req.json());
+  } catch {
+    return Response.json(
+      {
+        error: "invalid_request",
+        message: "Invalid request body. Expected JSON with a 'messages' array.",
+      },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const result = await runAgent({ messages });
+    return result.toUIMessageStreamResponse();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "";
+
+    // Gateway-specific errors (structured types, checked before regex fallbacks)
+    if (GatewayModelNotFoundError.isInstance(err)) {
+      console.error("[atlas] Gateway model not found in /api/chat:", message);
+      return Response.json(
+        {
+          error: "provider_model_not_found",
+          message:
+            "Model not found on the AI Gateway. Check that your ATLAS_MODEL uses the correct provider/model format (e.g., anthropic/claude-sonnet-4.6).",
+        },
+        { status: 400 }
+      );
+    }
+
+    // LLM provider auth errors (invalid or expired API key)
+    if (
+      /401|403|unauthorized|authentication|invalid.*key/i.test(message)
+    ) {
+      console.error("[atlas] Provider auth error in /api/chat:", message);
+      return Response.json(
+        {
+          error: "provider_auth_error",
+          message:
+            "LLM provider authentication failed. Check that your API key is valid and has not expired.",
+        },
+        { status: 503 }
+      );
+    }
+
+    // LLM provider rate limit errors
+    if (/429|rate.?limit|too many requests|overloaded/i.test(message)) {
+      console.error("[atlas] Provider rate limit in /api/chat:", message);
+      return Response.json(
+        {
+          error: "provider_rate_limit",
+          message:
+            "LLM provider rate limit reached. Wait a moment and try again.",
+        },
+        { status: 503 }
+      );
+    }
+
+    // Provider network errors (e.g., network failure to LLM API)
+    if (/fetch failed|ECONNREFUSED|ENOTFOUND/i.test(message)) {
+      console.error("[atlas] Provider unreachable in /api/chat:", message);
+      return Response.json(
+        {
+          error: "provider_unreachable",
+          message:
+            "Could not reach the LLM provider. Check your network connection and provider status.",
+        },
+        { status: 503 }
+      );
+    }
+
+    // Fallback — safe 500 with correlation ID for debugging
+    const errorId = crypto.randomUUID().slice(0, 8);
+    console.error(`[atlas] Unexpected error in /api/chat [${errorId}]:`, err);
+    return Response.json(
+      {
+        error: "internal_error",
+        message: `An unexpected error occurred (ref: ${errorId}). If this persists, check the server logs.`,
+      },
+      { status: 500 }
+    );
+  }
+}