User asks a question
       │
       ▼
┌──────────────────────────┐
│  6-Layer Context Assembly │  ← Schema + Annotations + Knowledge
│  ask_database()           │    + Docs + Learnings + Runtime
└──────────┬───────────────┘
           ▼
┌──────────────────────────┐
│  SQL Generation           │  Agent writes SQL grounded in context
└──────────┬───────────────┘
           ▼
┌──────────────────────────┐
│  Query Execution          │  ← Read-only enforcement, 30s timeout
│  run_query()              │
└──────────┬───────────────┘
      ┌────┴────┐
      ▼         ▼
  Success     Failure
      │         │
      ▼         ▼
  Store as   Auto-diagnose → Fix → Retry
  Knowledge    └─ Store as Learning

curl -X POST https://api.thinnest.ai/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Analyst",
    "instructions": "You are a data analyst that answers business questions by querying the database.",
    "tools": [
      {
        "type": "dash_postgres",
        "config": {
          "host": "your-db-host.com",
          "port": 5432,
          "db_name": "analytics",
          "user": "readonly_user",
          "password": "your_password",
          "schema": "public",
          "read_only": true,
          "enable_learning": true,
          "max_retries": 2,
          "annotations": {
            "description": "E-commerce analytics database",
            "notes": "Fiscal year starts April 1. All monetary amounts are in USD cents.",
            "metrics": {
              "revenue": "SUM(amount) FROM orders WHERE status = 'completed'",
              "churn_rate": "Users who cancelled in period / Total users at period start"
            },
            "tables": {
              "orders": {
                "description": "Customer orders. One row per order.",
                "columns": {
                  "status": "Values: pending, completed, cancelled, refunded",
                  "total_amount": "In USD cents. Includes tax and shipping.",
                  "net_amount": "In USD cents. Pre-tax, pre-shipping."
                }
              },
              "users": {
                "description": "Registered users. Soft-deleted via deleted_at.",
                "columns": {
                  "plan": "Values: free, starter, pro, enterprise",
                  "mrr": "Monthly recurring revenue in USD cents"
                }
              }
            }
          }
        }
      }
    ]
  }'

{
  "description": "Company analytics database — contains all customer, order, and product data",

  "notes": "Fiscal year starts April 1. All timestamps are UTC. Soft deletes use deleted_at column.",

  "metrics": {
    "revenue": "SUM(total_amount) / 100.0 FROM orders WHERE status = 'completed'",
    "active_users": "COUNT(DISTINCT user_id) FROM sessions WHERE created_at > NOW() - INTERVAL '30 days'",
    "churn_rate": "cancelled_users / total_users_at_period_start * 100"
  },

  "tables": {
    "orders": {
      "description": "One row per customer order. Created when checkout completes.",
      "columns": {
        "status": "Enum: pending → processing → completed → refunded. Cancelled is a separate flow.",
        "total_amount": "Integer, USD cents. Includes tax + shipping. Use net_amount for pre-tax.",
        "created_at": "When the order was placed. Use this for revenue date, not updated_at."
      }
    },
    "users": {
      "description": "One row per registered user. Soft-deleted via deleted_at (not hard deleted).",
      "columns": {
        "plan": "Current subscription: free, starter, pro, enterprise. Historical plans in plan_history table.",
        "email": "Always lowercase. Unique constraint. Some test accounts use @example.com."
      }
    }
  }
}

Query: "What were our top customers last quarter?"
SQL: SELECT u.name, SUM(o.total_amount)/100.0 as revenue
     FROM orders o JOIN users u ON o.user_id = u.id
     WHERE o.status = 'completed' AND o.created_at >= '2026-01-01'
     GROUP BY u.name ORDER BY revenue DESC LIMIT 10
Result: 10 rows ✓ → Stored as Knowledge

Failed:  SELECT * FROM users WHERE plan = 'premium'
Error:   No rows — 'premium' is not a valid plan value
Fixed:   SELECT * FROM users WHERE plan = 'pro'
Result:  247 rows ✓ → Stored as Learning

User: How many active users do we have?

Agent: [calls ask_database("How many active users do we have?")]
Agent: [calls run_query("SELECT COUNT(*) FROM users WHERE deleted_at IS NULL", "How many active users do we have?")]

Agent: You have 12,847 active users.

User: What's our monthly revenue trend?

Agent: [calls ask_database("What's our monthly revenue trend?")]
  → Context includes annotation: "All amounts are in USD cents"
  → Context includes Knowledge: Similar past query used /100.0 conversion

Agent: [calls run_query with proper cents-to-dollars conversion]

Agent: Here's your monthly revenue trend:
| Month    | Revenue     |
|----------|-------------|
| Jan 2026 | $1,234,567  |
| Feb 2026 | $1,345,678  |
| Mar 2026 | $1,456,789  |

Visualization: Line Chart — Plot Revenue over Month

User: Show me orders by product category

Agent: [calls run_query("SELECT category, COUNT(*) FROM orders GROUP BY category")]
  → Error: column "category" does not exist

Dash returns: QUERY FAILED (attempt 1/3)
  Diagnostic: Column name may be misspelled. Use discover_schema() to verify.

Agent: [calls discover_schema()]
  → Sees: orders has product_id, products table has category column

Agent: [calls run_query("SELECT p.category, COUNT(*) FROM orders o JOIN products p ON o.product_id = p.id GROUP BY p.category")]
  → Success! Stores the correction as a Learning.

Agent: [calls record_correction(...)]