AI Integration

How ObjectQL's metadata-first design enables AI code generation, schema discovery, and intelligent querying

ObjectQL's declarative YAML schemas and JSON AST queries are inherently AI-friendly. This page covers the integration points between ObjectQL and AI systems.

Why ObjectQL + AI?

Traditional ORMs use imperative code (classes, decorators, method chains) that AI models struggle to generate reliably. ObjectQL's approach is different:

Aspect	Traditional ORM	ObjectQL
Schema format	TypeScript classes	YAML/JSON — structured, parseable
Query format	Method chains (`db.where().join()`)	JSON AST — deterministic, validatable
Validation	Scattered across code	Declarative rules in schema
API surface	Large, framework-specific	Small, protocol-driven

This means LLMs can:

Generate schemas from natural language descriptions
Build queries as JSON objects (no syntax errors possible)
Discover metadata via the Metadata API at runtime
Validate outputs against the schema before execution

AI-Readable Metadata

Every ObjectQL object definition includes an optional ai_context field that provides natural language hints to AI agents:

name: customer
label: Customer
ai_context: >
  Represents business customers. Each customer has a unique email.
  Status transitions: prospect → active → churned.
  Revenue is calculated from related invoices.
fields:
  name:
    type: text
    required: true
    ai_context: "Full company name, e.g. 'Acme Corp'"
  email:
    type: text
    required: true
    ai_context: "Primary contact email, must be unique"
  status:
    type: select
    options: [prospect, active, churned]
    defaultValue: prospect
    ai_context: "Customer lifecycle stage"
  revenue:
    type: formula
    formula: "SUM(invoices.amount)"
    return_type: currency
    ai_context: "Auto-calculated from related invoice amounts"

AI agents can retrieve this context via the Metadata API to understand the data model before generating queries.

Generating Queries with AI

Since ObjectQL queries are JSON objects (not SQL strings), AI models can generate them reliably:

// AI generates this structured query — no SQL injection risk
const query = {
  object: 'customer',
  filters: [
    ['status', '=', 'active'],
    ['revenue', '>', 10000]
  ],
  fields: ['name', 'email', 'revenue'],
  sort: [{ field: 'revenue', order: 'desc' }],
  limit: 20
};

// Execute safely through the validated pipeline
const results = await ctx.object('customer').find(query);

The engine validates the query against the schema before execution — invalid field names, wrong types, and unauthorized filters are caught automatically.

Schema Discovery for Agents

AI agents can discover the full schema at runtime using the Metadata API:

# Get all objects
GET /api/metadata/objects

# Get specific object schema
GET /api/metadata/objects/customer

# Get field definitions
GET /api/metadata/objects/customer/fields

This enables agentic workflows where the AI:

Discovers available objects and their fields
Reads ai_context for semantic understanding
Generates valid JSON queries
Executes and interprets results

Runtime Registries

ObjectQL exposes lightweight registries for AI model and prompt management:

Model Registry

app.ai.models.register({
  name: 'gpt-4',
  provider: 'openai',
  capabilities: ['text-generation', 'function-calling'],
  config: {
    apiKey: process.env.OPENAI_API_KEY,
    maxTokens: 4096
  }
});

Prompt Template Registry

Store and version prompt templates:

app.ai.prompts.register({
  name: 'generate-query',
  version: '1.0',
  template: `Given the following ObjectQL schema:
{{schema}}

Generate a JSON query to: {{user_request}}

Return ONLY the JSON query object.`,
  variables: ['schema', 'user_request']
});

// Use at runtime
const prompt = app.ai.prompts.render('generate-query', {
  schema: JSON.stringify(metadata),
  user_request: 'Find all active customers with revenue over 10k'
});

RAG Integration Points

Connect embeddings and vector stores for retrieval-augmented generation:

app.ai.embeddings = new OpenAIEmbeddingProvider({
  model: 'text-embedding-3-small'
});

app.ai.vectorStore = new PineconeVectorStore({
  index: 'objectql-docs'
});

AI registries are intentionally minimal and adapter-friendly. They define the interface — you bring your own provider SDK.

Best Practices

Always set ai_context on objects and fields — it dramatically improves AI query generation accuracy
Use the Metadata API for schema discovery instead of hardcoding schema in prompts
Validate AI-generated queries through ObjectQL's pipeline (it happens automatically)
Use JSON queries, not SQL — structured data is more reliable for AI generation
Version prompt templates to track and improve AI interactions over time

AI Integration

On this page