LiquidMetal AI AI Mode: what should I include in my plain-English spec so it generates the right endpoints, auth, and data resources?

Quick Answer: In AI Mode, treat your plain‑English spec like a lightweight product requirements doc: clearly describe your users, core use cases, required endpoints, data entities (and fields), auth rules, and any billing/limits. The more explicit you are about inputs/outputs, roles, and data relationships, the more accurately Raindrop can build, test, and deploy the right API for you.

Why This Matters

AI Mode is meant to compress weeks of backend work into minutes. But “describe what you need in plain English” doesn’t mean “be vague.” The quality of your spec directly determines whether Raindrop ships a production-ready backend that matches your intent, with the right endpoints, Smart primitives (SmartMemory, SmartBuckets, SmartSQL, SmartInference), authentication, and monetization wired in.

A good spec:

• Reduces back-and-forth iterations with AI Mode
• Lowers the chance of missing critical endpoints or data fields
• Ensures auth, billing, and observability are correct from day one

Key Benefits:

• Faster from idea to shipped API: A clear spec lets AI Mode build, test, and deploy the right API structure on the first pass.
• Production-ready by default: Explicit requirements give Raindrop enough signal to configure auth, billing, and smart primitives for real users—not just demos.
• Easier iteration and rollback: When your intent is precise, Raindrop’s complete versioning of code and data means you can evolve the spec, compare versions, and roll back safely.

Core Concepts & Key Points

Concept	Definition	Why it's important
AI Mode Spec	Your plain‑English description of what the API should do, who uses it, and how.	This is the blueprint AI Mode uses to build, test, and deploy your backend. Clarity here equals fewer surprises later.
Smart Primitives	Built-in Raindrop capabilities: SmartMemory, SmartBuckets, SmartSQL, SmartInference, plus Actors/Services.	These replace hand-rolled glue (vector DBs, RAG stacks, custom memory). If you describe your data and workflows well, AI Mode can choose and configure the right primitives.
Auth & Monetization Rules	How users authenticate (JWT, OAuth, API keys, RBAC) and how access is priced/limited.	This is what makes your API shippable as a product: secure by default, with plans, rate limits, and usage tracking wired in from day one.

How It Works (Step-by-Step)

At a high level, AI Mode takes your spec and turns it into a production-ready API with smart primitives, auth, and scaling built in.

1. You describe your API in plain English:
   You write a spec that explains the purpose of the API, core workflows, roles, data models, and any special requirements (RAG, analytics, persistent sessions, etc.).

2. Raindrop’s AI builds, tests, and deploys:
   AI Mode interprets your spec, chooses appropriate primitives (SmartBuckets vs SmartSQL vs SmartMemory, etc.), generates manifests and code, configures auth/monetization, runs tests, and deploys a globally scaled backend.

3. You iterate with versioning and observability:
   If something doesn’t match your needs, you refine the spec. Raindrop tracks versions of code, data, and smart primitive configs so you can compare behaviors, debug with full traces, and roll back or forward safely.

The rest of this guide focuses on step 1: what you should include in your spec so step 2 “just works.”

---

What to Include in Your Plain‑English Spec (Checklist)

You don’t need to write a 20-page PRD, but you should cover these sections clearly.

1. Product Summary: What the API is for

Give AI Mode a crisp, one-paragraph north star.

Include:

• Who the API is for (internal tool, SaaS customers, mobile app, other backend services)
• Primary purpose (e.g., “AI-powered customer support search,” “analytics API,” “document QA agent,” “personalized recommendations”)
• What “success” looks like (e.g., “users can upload documents and ask questions,” “dashboard can query 200k+ records in plain English”)

Example snippet:

I need an API for a SaaS app where users upload their support docs (PDF, HTML) and then query them with natural language. The API will power a chat-style UI that answers questions based on those docs, and we need per-tenant isolation so one customer’s data never leaks to another.

2. Users and Roles: Who calls the API

Auth and RBAC depend on this. Be explicit about actors and trust boundaries.

Include:

• Types of users (admin, standard user, anonymous, internal service, etc.)
• How they sign in (email/password, SSO/OAuth, API key, machine-to-machine)
• What each role is allowed to do

Example snippet:

There are two roles: tenant_admin and end_user.

• Tenant admins authenticate via OAuth (Google and Microsoft) and can manage docs and settings.
• End users authenticate via email+password and can only read/query docs.
• We also need API keys for server-to-server ingestion from our ETL jobs.

This gives AI Mode enough signal to configure built-in Authentication (JWT, OAuth, RBAC, API keys) correctly.

3. Core Workflows: What people actually do

Think in terms of flows, not endpoints. AI Mode will derive endpoints from the flows.

For each workflow, describe:

• Trigger: who initiates it and how (UI button, cron, webhook)
• Input: what data is provided
• Behavior: what should happen
• Output: what the caller should receive

Common workflow categories:

• CRUD on resources (users, projects, documents, subscriptions)
• Search/RAG (upload → embed → query)
• Analytics (natural-language queries over SQL data)
• Agent conversations (chat sessions with persistent memory)
• Billing and usage (plan changes, metering, rate limits)

Example snippet (RAG workflow):

Workflow: Upload and index docs

• Only tenant_admin can upload.
• They POST files (PDF, DOCX, HTML) plus a project_id.
• System stores the raw files, automatically embeds content for semantic search, and links documents to that tenant and project.
• Return file IDs and an “indexing” status that can be polled or subscribed to.

This points AI Mode toward using SmartBuckets (S3-compatible storage + automatic vector embeddings + semantic search) plus tenant-aware metadata.

4. Data Model: Entities, fields, and relationships

Describe your core objects like you would on a whiteboard. You don’t need SQL syntax; you do need structure.

For each entity, specify:

• Name (User, Tenant, Document, Subscription, ChatSession, etc.)
• Key fields and types (string, number, datetime, enum, boolean)
• Relationships (one-to-many, many-to-many, ownership, tenancy)

Example snippet:

Entities:

• Tenant: id, name, billing_plan, created_at
• User: id, tenant_id, email, role (tenant_admin or end_user), created_at
• Document: id, tenant_id, project_id, title, source_url, status (uploaded, indexing, ready), created_at
• ChatSession: id, tenant_id, user_id, started_at, last_activity_at, status
  A tenant can have many users, projects, and documents. Documents and sessions must never be visible across tenants.

From here, AI Mode can decide:

• When to use SmartSQL (structured analytics & PII awareness)
• When to use SmartBuckets (unstructured files + automatic embeddings)
• How to model tenant isolation and RBAC rules

5. Smart Primitives & Intelligence Needs

Call out where you need intelligence primitives explicitly. This helps AI Mode avoid generic storage.

Examples:

• SmartBuckets: “When users upload files, I want automatic vector embeddings and semantic search across their content, plus keyword search.”
• SmartSQL: “We need analytics over ~200k+ transaction records with natural-language queries and automatic PII handling.”
• SmartMemory / Actors: “We need long-lived chat sessions where the agent remembers prior steps across requests and can resume workflows after delays.”
• SmartInference: “We need access to multiple LLMs with one interface and automatic scaling.”

Example snippet:

Use intelligent storage wherever appropriate:

• Documents should live in storage with automatic vector embeddings and both semantic and keyword search.
• I also want graph-style relationships between documents in the same project (e.g., related pages), so related docs can be surfaced.
• Chat sessions should use persistent memory so the assistant recalls prior answers and user preferences across sessions.

This aligns your spec with SmartBuckets + SmartMemory and, if needed, graph-based search.

6. Auth, Security, and Isolation

You want “production-ready from day one,” which means being explicit about trust boundaries.

Include:

• Auth methods: JWT, OAuth providers, API keys, sessions
• Role-based permissions (who can call which endpoint)
• Tenancy/isolation model
• PII considerations

Example snippet:

Security & auth:

• Authentication via JWT for all API calls. OAuth login for admins, email/password for end users.
• RBAC: tenant_admin can manage users, docs, and billing. end_user can only query and view answers.
• All data must be tenant-scoped; no cross-tenant queries.
• Treat user emails and full names as PII; avoid returning them in logs or analytics unless explicitly requested by an admin.

This informs Raindrop’s built-in auth plus SmartSQL’s PII detection behavior.

7. Plans, Monetization, and Limits

If you plan to ship this API as a product, specify how you want to charge and control usage.

Include:

• Plans/tiers (Free, Pro, Enterprise)
• Limits (requests per minute, docs per tenant, storage per plan, etc.)
• Overages and behavior under load

Example snippet:

Monetization:

• Free plan: up to 100 docs, 1GB storage, 1,000 queries/month.
• Pro plan: up to 5,000 docs, 50GB storage, 50,000 queries/month.
• Enterprise: custom limits.
• Enforce rate limits on query endpoints per tenant; return a clear error when exceeded.
• Track usage per tenant for billing and display usage stats to tenant admins.

AI Mode can then wire up Raindrop’s Monetization primitives: tiered plans, usage tracking, rate limiting, and payments.

8. Observability and Governance Requirements

Raindrop already provides “full observability” and logs every AI decision. Your spec should indicate what you care about most.

Possible requirements:

• Which events to log (auth, uploads, queries, billing, agent actions)
• What you need per-tenant dashboards for
• Audit demands (e.g., for compliance or internal review)

Example snippet:

Observability:

• Log every query, response, and model used, including latency and token counts.
• I need per-tenant usage stats: number of docs, queries, and active users.
• For admin users, expose an endpoint to inspect past sessions (questions + answers + sources) for quality review.
• Make it easy to roll back to previous backend versions if a new spec change degrades responses.

This lets Raindrop surface the right traces and tie them into its complete versioning and rollback model.

---

Common Mistakes to Avoid

• Being vague about roles and access:
  “Users can log in and use the app” is not enough. Spell out roles, permissions, and how they authenticate so AI Mode can set up JWT/OAuth, RBAC, and API keys correctly.

• Describing UI instead of API behavior:
  “There is a search box on the page” doesn’t help. Describe what the API should accept and return: inputs, outputs, filters, and error cases.

• Ignoring data relationships and tenancy:
  If you don’t describe which entities belong to which tenant, AI Mode can’t enforce isolation. Always explain multi-tenant needs and which data boundaries must never be crossed.

• Forgetting non-functional requirements:
  If you care about rate limits, latency, or max dataset size, write it down. It influences how Raindrop configures scaling and resource usage.

---

Real-World Example

Let’s put this together for a realistic build: a “customer knowledge search” API you want to expose to your customers as a paid feature.

Plain-English spec (condensed):

I need a multi-tenant API that lets B2B SaaS customers upload their knowledge base content and expose it as an AI-powered search for their end users.

Users & auth:

• Two user types for each tenant: owner and agent.
• Owners authenticate using OAuth (Google, Microsoft) and manage docs, plans, and settings.
• Agents use email+password and can only query and view answers.
• We also need API keys for the tenant’s own frontend to call the query endpoint directly.

Workflows:

1. Owners create a tenant account, pick a plan (Free, Pro, Enterprise), and invite agents.
2. Owners upload docs (PDF, HTML, Markdown) or connect a public URL to be crawled.
3. System stores all content, automatically chunks and embeds it, and makes it searchable by semantic and keyword search for that tenant only.
4. Agents and the tenant’s frontend send questions, and the system returns: an answer, the top 3 source snippets, and links to original docs.

Data model:

• Tenant, User, Plan, Document, Collection, QueryLog.
• Each Document belongs to a Tenant and optional Collection.
• QueryLog stores question, answer reference, latency, and which docs were used.

Intelligence & primitives:

• Use intelligent storage (vector embeddings + semantic, keyword, and related-docs search) for documents.
• Support natural language queries over QueryLog for admins (e.g., “show me the top unanswered questions this week”).

Security & governance:

• Strict tenant isolation; never mix documents or queries across tenants.
• Treat emails and IP addresses as PII.
• Log every query and source docs used, with a way for owners to audit.

Plans & limits:

• Free: 100 docs, 1GB, 1,000 queries/month.
• Pro: 5,000 docs, 50GB, 50,000 queries/month.
• Enterprise: custom.
• Enforce rate limits per tenant on query endpoints and return meaningful errors.

From this single spec, AI Mode can:

• Create Services (REST endpoints) aligned with each workflow
• Use SmartBuckets for doc storage + automatic embeddings + search
• Use SmartSQL for analytics over QueryLog with PII detection
• Configure JWT/OAuth + API keys + RBAC for owners/agents
• Wire in Monetization primitives for plans, usage tracking, and rate limits
• Deploy a production API with complete versioning and observability so you can inspect every AI decision and roll back if needed.

Pro Tip: Before pasting your spec into AI Mode, walk through one example request/response per workflow in your head (or on paper). If you can’t clearly describe the inputs and outputs for a flow, AI Mode will struggle to infer it. Tighten the spec until a teammate could implement the backend from it manually—then let Raindrop do it instead.

Summary

To get high-quality APIs out of LiquidMetal AI’s AI Mode, you don’t need to learn a new DSL—you need a precise plain‑English spec. Describe your users and roles, core workflows, data entities and relationships, intelligence needs (SmartBuckets, SmartSQL, SmartMemory, SmartInference), auth and isolation rules, and any plans/limits you care about. AI Mode uses that to build, test, and deploy a backend that’s production-ready from day one, with complete versioning, full observability, and automatic scaling baked in.

Next Step

Get Started