Deploy Mastra SQL agent

.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+.mastra
+dist
+.env
+.env.*
+*.db
+*.db-*
+.git
+.gitignore
+output.txt

.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY=

.gitignore

@@ -0,0 +1,8 @@
+output.txt
+node_modules
+dist
+.mastra
+.env.development
+.env
+*.db
+*.db-*

CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+
+This repository is auto-generated from the [Mastra monorepo](https://github.com/mastra-ai/mastra). Pull requests opened here will be ignored.
+
+To contribute:
+
+1. Fork the [Mastra monorepo](https://github.com/mastra-ai/mastra)
+2. Find this template in `templates/template-text-to-sql`
+3. Make your changes
+4. Open a pull request against the monorepo
+
+A bot syncs accepted changes to this repository.

Dockerfile

@@ -0,0 +1,22 @@
+FROM node:22-bookworm-slim
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+
+RUN npm ci
+
+COPY . .
+
+RUN npm run seed
+RUN npm run build -- --studio
+
+ENV PORT=7860
+ENV MASTRA_HOST=0.0.0.0
+ENV MASTRA_STUDIO_PATH=studio
+
+EXPOSE 7860
+
+WORKDIR /app/.mastra/output
+
+CMD ["node", "index.mjs"]

README.md

@@ -1,12 +1,15 @@
 ---
-title: My Sql Agent
-emoji: 👀
-colorFrom: yellow
+title: My SQL Agent
+emoji: 🗄️
+colorFrom: blue
 colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
-license: apache-2.0
-short_description: Mastra AI agent converting conversational English into SQL.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# My SQL Agent
+
+A Mastra Text-to-SQL agent deployed with Docker on Hugging Face Spaces.
+
+The agent converts natural-language questions into safe SQLite `SELECT` queries and returns results from the sample company database.

package.json

@@ -0,0 +1,33 @@
+{
+  "name": "template-text-to-sql",
+  "version": "1.0.0",
+  "description": "A Mastra template for natural language to SQL conversion using a local SQLite database.",
+  "main": "index.js",
+  "scripts": {
+    "seed": "tsx src/seed.ts",
+    "dev": "tsx src/seed.ts && mastra dev",
+    "build": "mastra build",
+    "start": "mastra start"
+  },
+  "license": "Apache-2.0",
+  "packageManager": "pnpm@11.3.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.17.0",
+    "@mastra/core": "latest",
+    "@mastra/libsql": "latest",
+    "@mastra/loggers": "latest",
+    "@mastra/memory": "latest",
+    "@mastra/observability": "latest",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.7",
+    "mastra": "latest",
+    "tsx": "^4.19.4",
+    "typescript": "^5.9.3"
+  }
+}

src/mastra/agents/sql-agent.ts

@@ -0,0 +1,44 @@
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+import { introspectDatabase } from '../tools/introspect-database';
+import { executeSql } from '../tools/execute-sql';
+
+export const sqlAgent = new Agent({
+  id: 'sql-agent',
+  name: 'SQL Agent',
+  model: 'opencode-go/deepseek-v4-flash',
+  instructions: `You are a SQL assistant that helps users query a local SQLite database using natural language.
+
+## Tools
+
+You have two tools:
+- **introspect-database**: Returns the database schema (tables, columns, types, foreign keys, row counts). Always call this first before writing any SQL so you know what's available.
+- **execute-sql**: Runs a SELECT query and returns the results. Only SELECT queries are allowed.
+
+## Workflow
+
+1. When the user asks a question, first call introspect-database to understand the schema.
+2. Convert the user's natural language question into a SQLite-compatible SELECT query.
+3. Call execute-sql with the generated query.
+4. Present the results in a clear, readable format (use tables when appropriate).
+
+## SQL Guidelines
+
+- Generate only SELECT queries. Never generate INSERT, UPDATE, DELETE, DROP, or any other mutating statements.
+- Use SQLite syntax: LIKE instead of ILIKE, no SERIAL, use INTEGER PRIMARY KEY.
+- Use proper JOINs when the question involves data across multiple tables.
+- Use aggregate functions (COUNT, SUM, AVG, MIN, MAX) when the user asks for summaries.
+- Use GROUP BY with aggregate functions.
+- Use ORDER BY and LIMIT for "top N" style questions.
+- Alias columns for readability (e.g., COUNT(*) AS total_employees).
+- When the user's question is ambiguous, explain your interpretation before executing.
+
+## Response Format
+
+- Show the SQL query you generated so the user can learn from it.
+- Present results clearly. For tabular data, format as a markdown table.
+- If the query returns no results, explain possible reasons.
+- If you're unsure about the schema, call introspect-database again.`,
+  tools: { introspectDatabase, executeSql },
+  memory: new Memory(),
+});

src/mastra/index.ts

@@ -0,0 +1,31 @@
+import { Mastra } from '@mastra/core/mastra';
+import { PinoLogger } from '@mastra/loggers';
+import { LibSQLStore } from '@mastra/libsql';
+import {
+  Observability,
+  MastraStorageExporter,
+  MastraPlatformExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability';
+import { sqlAgent } from './agents/sql-agent';
+
+export const mastra = new Mastra({
+  agents: { sqlAgent },
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+  logger: new PinoLogger({
+    name: 'Mastra Text-to-SQL',
+    level: 'info',
+  }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'text-to-sql',
+        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+      },
+    },
+  }),
+});

src/mastra/tools/execute-sql.ts

@@ -0,0 +1,44 @@
+import { createTool } from '@mastra/core/tools';
+import { createClient } from '@libsql/client';
+import { z } from 'zod';
+
+const db = createClient({ url: 'file:./data.db' });
+
+const BLOCKED_PATTERNS = [
+  /\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|REPLACE)\b/i,
+  /\b(ATTACH|DETACH)\b/i,
+  /\b(PRAGMA)\b/i,
+  /;.*\S/, // multiple statements
+];
+
+export const executeSql = createTool({
+  id: 'execute-sql',
+  description: 'Executes a read-only SQL SELECT query against the local SQLite database and returns the results.',
+  inputSchema: z.object({
+    query: z.string().describe('The SQL SELECT query to execute'),
+  }),
+  outputSchema: z.object({
+    rows: z.array(z.record(z.string(), z.unknown())).describe('Query result rows'),
+    rowCount: z.number().describe('Number of rows returned'),
+  }),
+  execute: async ({ query }) => {
+    const trimmed = query.trim().replace(/;$/, '');
+
+    for (const pattern of BLOCKED_PATTERNS) {
+      if (pattern.test(trimmed)) {
+        throw new Error('Only SELECT queries are allowed.');
+      }
+    }
+
+    if (!/^\s*SELECT\b/i.test(trimmed)) {
+      throw new Error('Query must start with SELECT.');
+    }
+
+    const result = await db.execute(trimmed);
+
+    return {
+      rows: result.rows as Record<string, unknown>[],
+      rowCount: result.rows.length,
+    };
+  },
+});

src/mastra/tools/introspect-database.ts

@@ -0,0 +1,54 @@
+import { createTool } from '@mastra/core/tools';
+import { createClient } from '@libsql/client';
+import { z } from 'zod';
+
+const db = createClient({ url: 'file:./data.db' });
+
+export const introspectDatabase = createTool({
+  id: 'introspect-database',
+  description:
+    'Introspects the local SQLite database and returns a description of all tables, columns, foreign keys, and row counts.',
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    schema: z.string().describe('Human-readable database schema description'),
+  }),
+  execute: async () => {
+    const tables = await db.execute(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_litestream_%' ORDER BY name",
+    );
+
+    const lines: string[] = ['# Database Schema', ''];
+
+    for (const table of tables.rows) {
+      const tableName = table.name as string;
+
+      const columns = await db.execute(`PRAGMA table_info('${tableName}')`);
+      const foreignKeys = await db.execute(`PRAGMA foreign_key_list('${tableName}')`);
+      const countResult = await db.execute(`SELECT COUNT(*) as count FROM "${tableName}"`);
+      const rowCount = countResult.rows[0].count;
+
+      lines.push(`## ${tableName} (${rowCount} rows)`);
+      lines.push('');
+      lines.push('| Column | Type | Nullable | PK |');
+      lines.push('|--------|------|----------|----|');
+
+      for (const col of columns.rows) {
+        const nullable = col.notnull ? 'NO' : 'YES';
+        const pk = col.pk ? 'YES' : '';
+        lines.push(`| ${col.name} | ${col.type || 'ANY'} | ${nullable} | ${pk} |`);
+      }
+
+      if (foreignKeys.rows.length > 0) {
+        lines.push('');
+        lines.push('**Foreign Keys:**');
+        for (const fk of foreignKeys.rows) {
+          lines.push(`- ${fk.from} → ${fk.table}.${fk.to}`);
+        }
+      }
+
+      lines.push('');
+    }
+
+    return { schema: lines.join('\n') };
+  },
+});

src/seed.ts

@@ -0,0 +1,174 @@
+import { createClient } from '@libsql/client';
+import { mkdirSync } from 'node:fs';
+
+const PUBLIC_DIR = 'src/mastra/public';
+const DB_PATH = `file:${PUBLIC_DIR}/data.db`;
+
+async function seed() {
+  mkdirSync(PUBLIC_DIR, { recursive: true });
+  const client = createClient({ url: DB_PATH });
+
+  // Check if already seeded
+  const existing = await client.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='companies'");
+  if (existing.rows.length > 0) {
+    console.log('Database already seeded, skipping.');
+    return;
+  }
+
+  console.log('Seeding database...');
+
+  await client.executeMultiple(`
+    CREATE TABLE companies (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      industry TEXT,
+      founded INTEGER,
+      employee_count INTEGER,
+      revenue INTEGER,
+      headquarters TEXT
+    );
+
+    CREATE TABLE departments (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      company_id INTEGER REFERENCES companies(id),
+      name TEXT NOT NULL,
+      budget INTEGER,
+      head_count INTEGER
+    );
+
+    CREATE TABLE employees (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      company_id INTEGER REFERENCES companies(id),
+      department_id INTEGER REFERENCES departments(id),
+      first_name TEXT NOT NULL,
+      last_name TEXT NOT NULL,
+      email TEXT UNIQUE,
+      hire_date TEXT,
+      salary INTEGER,
+      title TEXT,
+      status TEXT DEFAULT 'Active'
+    );
+
+    CREATE TABLE projects (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      company_id INTEGER REFERENCES companies(id),
+      department_id INTEGER REFERENCES departments(id),
+      name TEXT NOT NULL,
+      status TEXT,
+      budget INTEGER,
+      start_date TEXT,
+      end_date TEXT
+    );
+
+    CREATE TABLE project_assignments (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_id INTEGER REFERENCES projects(id),
+      employee_id INTEGER REFERENCES employees(id),
+      role TEXT,
+      UNIQUE(project_id, employee_id)
+    );
+
+    -- Companies
+    INSERT INTO companies (name, industry, founded, employee_count, revenue, headquarters) VALUES
+      ('Acme Corp', 'Technology', 2010, 150, 25000000, 'San Francisco, CA'),
+      ('Globex Inc', 'Finance', 2005, 300, 80000000, 'New York, NY'),
+      ('Initech', 'Healthcare', 2015, 80, 12000000, 'Austin, TX'),
+      ('Umbrella Ltd', 'Retail', 2008, 200, 45000000, 'Chicago, IL'),
+      ('Stark Industries', 'Manufacturing', 2000, 500, 120000000, 'Detroit, MI');
+
+    -- Departments
+    INSERT INTO departments (company_id, name, budget, head_count) VALUES
+      (1, 'Engineering', 5000000, 60),
+      (1, 'Marketing', 2000000, 25),
+      (1, 'Sales', 3000000, 35),
+      (1, 'Human Resources', 1000000, 15),
+      (2, 'Investment Banking', 10000000, 80),
+      (2, 'Risk Management', 4000000, 40),
+      (2, 'Compliance', 2000000, 30),
+      (2, 'Technology', 6000000, 50),
+      (3, 'Research', 4000000, 30),
+      (3, 'Clinical', 3000000, 25),
+      (3, 'Operations', 2000000, 15),
+      (4, 'Supply Chain', 5000000, 50),
+      (4, 'Marketing', 3000000, 40),
+      (4, 'Customer Service', 2000000, 35),
+      (5, 'Manufacturing', 8000000, 150),
+      (5, 'Engineering', 6000000, 100),
+      (5, 'Quality Assurance', 3000000, 50);
+
+    -- Employees
+    INSERT INTO employees (company_id, department_id, first_name, last_name, email, hire_date, salary, title, status) VALUES
+      (1, 1, 'Alice', 'Chen', 'alice.chen@acme.com', '2018-03-15', 145000, 'Senior Engineer', 'Active'),
+      (1, 1, 'Bob', 'Martinez', 'bob.martinez@acme.com', '2020-07-01', 125000, 'Software Engineer', 'Active'),
+      (1, 1, 'Carol', 'Johnson', 'carol.johnson@acme.com', '2019-01-10', 155000, 'Staff Engineer', 'Active'),
+      (1, 1, 'David', 'Kim', 'david.kim@acme.com', '2021-06-20', 110000, 'Junior Engineer', 'Active'),
+      (1, 2, 'Eve', 'Williams', 'eve.williams@acme.com', '2019-11-05', 95000, 'Marketing Manager', 'Active'),
+      (1, 2, 'Frank', 'Brown', 'frank.brown@acme.com', '2022-02-14', 75000, 'Marketing Specialist', 'Active'),
+      (1, 3, 'Grace', 'Davis', 'grace.davis@acme.com', '2020-09-01', 130000, 'Sales Director', 'Active'),
+      (1, 3, 'Henry', 'Wilson', 'henry.wilson@acme.com', '2021-03-22', 85000, 'Sales Representative', 'Active'),
+      (1, 4, 'Ivy', 'Taylor', 'ivy.taylor@acme.com', '2017-05-30', 90000, 'HR Manager', 'Active'),
+      (2, 5, 'Jack', 'Anderson', 'jack.anderson@globex.com', '2016-08-12', 180000, 'Senior Banker', 'Active'),
+      (2, 5, 'Karen', 'Thomas', 'karen.thomas@globex.com', '2018-04-03', 160000, 'Investment Analyst', 'Active'),
+      (2, 5, 'Leo', 'Garcia', 'leo.garcia@globex.com', '2020-01-15', 140000, 'Associate Banker', 'Active'),
+      (2, 6, 'Maria', 'Rodriguez', 'maria.rodriguez@globex.com', '2017-11-20', 150000, 'Risk Analyst', 'Active'),
+      (2, 6, 'Nick', 'Lee', 'nick.lee@globex.com', '2019-06-08', 135000, 'Risk Manager', 'Active'),
+      (2, 7, 'Olivia', 'White', 'olivia.white@globex.com', '2021-09-01', 120000, 'Compliance Officer', 'Active'),
+      (2, 8, 'Paul', 'Harris', 'paul.harris@globex.com', '2018-02-28', 155000, 'Tech Lead', 'Active'),
+      (3, 9, 'Quinn', 'Clark', 'quinn.clark@initech.com', '2019-07-15', 130000, 'Research Scientist', 'Active'),
+      (3, 9, 'Rachel', 'Lewis', 'rachel.lewis@initech.com', '2020-10-01', 120000, 'Lab Director', 'Active'),
+      (3, 10, 'Sam', 'Walker', 'sam.walker@initech.com', '2021-01-20', 110000, 'Clinical Researcher', 'Active'),
+      (3, 11, 'Tina', 'Hall', 'tina.hall@initech.com', '2022-04-10', 85000, 'Operations Manager', 'Active'),
+      (4, 12, 'Uma', 'Allen', 'uma.allen@umbrella.com', '2018-06-01', 115000, 'Supply Chain Manager', 'Active'),
+      (4, 12, 'Victor', 'Young', 'victor.young@umbrella.com', '2020-03-15', 90000, 'Logistics Coordinator', 'Active'),
+      (4, 13, 'Wendy', 'King', 'wendy.king@umbrella.com', '2019-08-20', 100000, 'Brand Manager', 'Active'),
+      (4, 14, 'Xavier', 'Scott', 'xavier.scott@umbrella.com', '2021-11-01', 65000, 'Support Specialist', 'Active'),
+      (5, 15, 'Yara', 'Green', 'yara.green@stark.com', '2015-04-10', 95000, 'Production Manager', 'Active'),
+      (5, 15, 'Zach', 'Adams', 'zach.adams@stark.com', '2017-09-22', 80000, 'Line Supervisor', 'Active'),
+      (5, 16, 'Amy', 'Nelson', 'amy.nelson@stark.com', '2016-12-05', 140000, 'Principal Engineer', 'Active'),
+      (5, 16, 'Brian', 'Carter', 'brian.carter@stark.com', '2019-02-18', 120000, 'Mechanical Engineer', 'Active'),
+      (5, 17, 'Cindy', 'Mitchell', 'cindy.mitchell@stark.com', '2020-07-30', 105000, 'QA Lead', 'Active'),
+      (5, 17, 'Derek', 'Roberts', 'derek.roberts@stark.com', '2022-01-10', 85000, 'QA Analyst', 'Active');
+
+    -- Projects
+    INSERT INTO projects (company_id, department_id, name, status, budget, start_date, end_date) VALUES
+      (1, 1, 'Cloud Migration', 'In Progress', 500000, '2024-01-15', '2024-12-31'),
+      (1, 1, 'Mobile App v2', 'Planning', 300000, '2024-06-01', '2025-03-31'),
+      (1, 2, 'Brand Refresh', 'Completed', 150000, '2023-09-01', '2024-02-28'),
+      (2, 5, 'Q4 Fund Launch', 'In Progress', 2000000, '2024-03-01', '2024-09-30'),
+      (2, 8, 'Trading Platform Upgrade', 'In Progress', 1500000, '2024-02-01', '2024-11-30'),
+      (3, 9, 'Drug Trial Phase 2', 'In Progress', 3000000, '2023-06-01', '2025-06-30'),
+      (4, 12, 'Warehouse Automation', 'Planning', 800000, '2024-07-01', '2025-04-30'),
+      (5, 16, 'EV Battery Design', 'In Progress', 5000000, '2024-01-01', '2025-12-31'),
+      (5, 15, 'Assembly Line Retrofit', 'Completed', 2000000, '2023-03-01', '2024-01-31');
+
+    -- Project Assignments
+    INSERT INTO project_assignments (project_id, employee_id, role) VALUES
+      (1, 1, 'Tech Lead'),
+      (1, 2, 'Developer'),
+      (1, 3, 'Architect'),
+      (2, 2, 'Developer'),
+      (2, 4, 'Developer'),
+      (3, 5, 'Project Manager'),
+      (3, 6, 'Designer'),
+      (4, 10, 'Lead Banker'),
+      (4, 11, 'Analyst'),
+      (5, 16, 'Tech Lead'),
+      (6, 17, 'Lead Researcher'),
+      (6, 18, 'Lab Director'),
+      (6, 19, 'Researcher'),
+      (7, 21, 'Project Manager'),
+      (7, 22, 'Coordinator'),
+      (8, 27, 'Lead Engineer'),
+      (8, 28, 'Engineer'),
+      (9, 25, 'Production Lead'),
+      (9, 26, 'Supervisor');
+  `);
+
+  console.log('Database seeded with sample company data.');
+  console.log('Tables: companies, departments, employees, projects, project_assignments');
+}
+
+seed().catch(err => {
+  console.error('Failed to seed database:', err);
+  process.exit(1);
+});

tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}