Revise AI, data modeling, actions, and hooks guides

Updated documentation for AI integration, data modeling, custom actions, and lifecycle hooks in ObjectQL. Improvements include clearer examples, streamlined explanations, and enhanced guidance on schema, relationships, validation, and business logic implementation.

Author: hotlong

docs/guide/ai.md

@@ -1,133 +1,84 @@
 # Building AI-Native Apps
 
-ObjectQL is designed from the ground up to be the ideal data layer for AI agents and LLM-powered applications. Unlike traditional ORMs that rely on string-based SQL generation (prone to hallucination and injection), ObjectQL uses a **strict JSON Protocol**.
+ObjectQL is engineered to be the ideal data layer for AI Agents and LLMs. By providing a **Structure-First** protocol (JSON AST) instead of raw strings (SQL), it drastically reduces hallucinations and injection risks.
 
-## Why ObjectQL for AI?
+## 1. Why ObjectQL for AI?
 
-| Feature | SQL / Traditional ORM | ObjectQL (JSON AST) |
+| Feature | SQL / Traditional ORM | ObjectQL |
 | :--- | :--- | :--- |
-| **Output Format** | Unstructured Strings | **Structured JSON** |
-| **Hallucinations** | High (Syntax errors, non-existent tables) | **Low** (constrained by schema) |
-| **Safety** | Injection vulnerable (requires sanitization) | **Injection Proof** (by design) |
-| **Context Window** | Heavy (DDL dumps) | **Lightweight** (JSON Schema) |
+| **Output** | Unstructured String | **Strict JSON** |
+| **Safety** | Injection Vulnerable | **Injection Safe** |
+| **Context** | Heavy DDL dumps | **Lightweight Scoped Schema** |
 
-### The "JSON Advantage"
+LLMs excel at generating JSON. ObjectQL lets the LLM speak its native language.
 
-LLMs are exceptionally good at generating JSON. By asking the LLM to output a JSON object instead of a SQL query, you drastically reduce error rates.
+## 2. Semantic Search (RAG)
 
-**User Prompt:** "Find high priority tasks for John."
+ObjectQL has first-class support for Vector Search. You don't need a separate vector database (like Pinecone) or generic ORM hacks.
 
-**LLM Output (ObjectQL Query):**
-```json
-{
-  "entity": "tasks",
-  "filters": [
-    ["priority", "=", "High"],
-    "and",
-    ["assignee", "=", "John"]
-  ]
-}
-```
-
-## Quick Start
+### Configuration
 
-### 1. Install Dependencies
+Enable search in your `*.object.yml`.
 
-You'll need the core package. We assume you are using OpenAI or a similar provider.
+```yaml
+# knowledge.object.yml
+name: knowledge
+fields:
+  title: { type: text }
+  content: { type: textarea }
 
-```bash
-npm install @objectql/core openai
+# Enable AI capabilities
+ai:
+  search:
+    enabled: true
+    fields: [title, content] # Fields to embed
+    model: text-embedding-3-small
 ```
 
-### 2. The Pattern: RAG for Schema
+### Usage
 
-To let the AI generate correct queries, you must first provide it with the relevant *Context* (your Schema), but only the parts it needs.
+When enabled, the driver manages the embeddings automatically. You can then search using natural language.
 
 ```typescript
-// 1. Get Schema Context (Simplified)
-const schemaContext = {
-    entities: {
-        todo: {
-            description: "Task items",
-            fields: ["title", "status", "priority"]
-        }
-    }
-};
-
-// 2. Prompt the AI
-const prompt = `
-You are a database assistant.
-Context: ${JSON.stringify(schemaContext)}
-
-User Request: "Show me all high priority tasks."
-
-Output: strictly valid ObjectQL JSON.
-`;
-
-// 3. Call LLM (Pseudo-code)
-const response = await openai.chat.completions.create({
-    messages: [{ role: "user", content: prompt }]
-});
-const query = JSON.parse(response.choices[0].message.content);
-```
-
-## AI Patterns
+// Search for "How to reset password"
+const results = await objectql.search('knowledge', 'How to reset password');
 
-### Pattern A: Natural Language Search (NL2Q)
-Directly converting user questions into database queries.
+// returns: [{ id: 1, title: 'Reset Config', _score: 0.89 }, ...]
+```
 
-*   **Best for:** Reporting, Dashboards, Search bars.
-*   **Tip:** Use the `description` field in your ObjectQL definitions to give the AI hints about what an object represents.
+## 3. Explicit Vector Columns
 
-### Pattern B: Intelligent Form Generation
-Since ObjectQL schemas are just JSON, AI can easily generate new object definitions on the fly.
+For advanced use cases (e.g., Image Search or Multi-modal embeddings), you can define raw vector columns.
 
-```typescript
-// AI Output for "Create a Customer schema"
-const newSchema = {
-    name: "customer",
-    fields: {
-        name: { type: "text" },
-        email: { type: "email" },
-        status: { type: "select", options: ["active", "lead"] }
-    }
-};
-
-// Apply it immediately
-await app.metadata.registerObject(newSchema);
+```yaml
+fields:
+  image_url:
+    type: url
+  
+  clip_embedding:
+    type: vector
+    dimension: 512
+    index: true # Create IVFFlat/HNSW index
 ```
 
-## Safety Guidelines (Critical)
-
-Allowing an AI to generate database queries introduces risks. You must follow these principles:
+## 4. LLM to Query (Text-to-SQL alternative)
 
-### 1. Never Trust AI Output
-Always validate the structure and content of the generated JSON *before* execution.
-
-```typescript
-import { z } from 'zod';
+Instead of asking an LLM to write SQL, ask it to write ObjectQL JSON.
 
-// Define a safe schema for the query
-const QuerySchema = z.object({
-    entity: z.string(),
-    filters: z.array(z.any()).optional()
-});
+**Prompt Pattern:**
 
-const rawQuery = JSON.parse(aiOutput);
+```text
+You are a data assistant.
+Schema:
+- Object: Task (fields: title, status, priority)
 
-// 1. Structural Validation
-const safeQuery = QuerySchema.parse(rawQuery);
+User: "Find my high priority tasks"
 
-// 2. Permission Check (Kernel Level)
-// Even if the query is valid, ObjectQL's internal security layer 
-// will still enforce RLS (Row Level Security).
-const result = await db.find(safeQuery);
+Output JSON in ObjectQL format:
+{
+  "entity": "task",
+  "filters": [["priority", "=", "High"]]
+}
 ```
 
-### 2. Least Privilege
-The database user used by the AI agent should have **read-only** permissions where possible, or be scoped strictly to the objects it needs to modify.
-
-### 3. Complexity Limits
-AI models can sometimes generate deeply nested or inefficient queries. Implement a "Complexity Cost" check before executing:
-- Limit the number of joins (lookups).
-- Limit the result set size.
+This output can be safely executed by the ObjectQL engine without fear of `DROP TABLE` injections.

docs/guide/data-modeling.md

@@ -1,80 +1,99 @@
 # Data Modeling Guide
 
-Modeling your business data is the first step in building an ObjectQL application. This guide introduces the core concepts.
+Data modeling in ObjectQL is **Metadata-First**. You define your application's schema using `*.object.yml` files (or JSON), and ObjectQL handles validation, database mapping, and type generation.
 
-## 1. Objects
+## 1. The Object Definition
 
-An **Object** is like a database table. It represents a business entity, such as a Customer, Order, or Product.
+Each file represents one business entity. By convention, name the file `[object_name].object.yml`.
 
 ```yaml
-# customer.object.yml
-name: customer
-label: Customer
-icon: user
-description: Stores customer information.
+# objects/product.object.yml
+name: product
+label: Product
+description: "Catalog items for sale"
+icon: standard:product
+
 fields:
   name:
     type: text
-    label: Full Name
     required: true
+    label: Product Name
+  
+  price:
+    type: currency
+    scale: 2
+    label: Price
+    
+  category:
+    type: select
+    options:
+      - electronics
+      - furniture
+      - clothing
 ```
 
-## 2. Fields
+## 2. Fields & Relationships
 
-Fields store the data attributes for an object. ObjectQL provides a rich set of field types.
+ObjectQL supports rich field types that automate UI rendering and validation.
 
-### 2.1 Basic Types
-*   **Text & Area**: `text`, `textarea`, `markdown`, `html`
+### Core Types
+*   **Text**: `text`, `textarea`, `markdown`, `html`
 *   **Numbers**: `number`, `currency`, `percent`
-*   **Switch**: `boolean` (checkbox)
-*   **Date**: `date`, `datetime`, `time`
-*   **System**: `password`, `auto_number`
-
-### 2.2 Format Types
-These types provide automatic validation and formatted display.
-*   **Email** (`email`): Validates email addresses.
-*   **Phone** (`phone`): Stores phone numbers.
-*   **URL** (`url`): Validates web links.
+*   **Flags**: `boolean`
+*   **Media**: `image`, `file`, `avatar`
 
-### 2.3 Media & Files
-*   **File** (`file`): Upload generic documents.
-*   **Image** (`image`): Upload pictures with preview support.
-*   **Avatar** (`avatar`): User profile pictures.
+### Relationships
+*   **Lookup**: A loose foreign key. Can be optional.
+    ```yaml
+    created_by: { type: lookup, reference_to: user }
+    ```
+*   **Master-Detail**: A strong parent-child bond. Deleting the parent cascades to the child.
+    ```yaml
+    order_id: { type: master_detail, reference_to: order }
+    ```
 
-*Note: You can allow multiple files/images by setting `multiple: true`.*
+### Specialized Types
+*   **Vector**: Stores embeddings (arrays of floats) for AI search.
+    ```yaml
+    embedding: { type: vector, dimension: 1536, index: true }
+    ```
 
-### 2.4 Location
-*   **Location** (`location`): Stores Latitude and Longitude. Useful for maps.
+## 3. Indexes & Constraints
 
-### 2.5 Calculations
-*   **Formula**: Calculate values automatically based on other fields.
-    *   Example: `Total` = `Price` * `Quantity`
-*   **Summary**: Aggregate data from child records (e.g., Total Order Amount for a Customer).
+Optimize query performance and ensure data integrity.
 
-## 3. Relationships
+### Field-Level Shortcuts
+Use these for simple, single-column definitions.
 
-Linking objects together is powerful.
+```yaml
+fields:
+  sku:
+    type: text
+    unique: true  # Enforce uniqueness
+  
+  status:
+    type: select
+    index: true   # Speed up filters
+```
 
-*   **Lookup**: A simple link to another object. (e.g., An Order looks up a Customer).
-*   **Master-Detail**: A strong parent-child relationship. If the parent is deleted, children are deleted.
+### Composite Indexes
+Define these at the root of your object file for multi-column optimizations (e.g., sorting by Date within a Category).
 
 ```yaml
-# order.object.yml
-fields:
-  customer:
-    type: lookup
-    reference_to: customer
-    label: Customer
+indexes:
+  category_date_idx:
+    fields: [category, created_at]
+  
+  unique_product_variant:
+    fields: [product_id, color, size]
+    unique: true
 ```
 
-## 4. Attributes
+## 4. Internationalization (i18n)
 
-You can enforce rules on your data using attributes:
+ObjectQL adopts a "clean schema, external translation" philosophy.
 
-*   `required`: Cannot be empty.
-*   `unique`: Must be unique in the whole table.
-*   `min`, `max`: Range validation for numbers.
-*   `defaultValue`: Automatic initial value.
-*   `hidden`: Hide from standard UI.
-*   `readonly`: Prevent editing in UI.
+*   **Schema**: Keep `*.object.yml` clean and technical (usually English keys/labels).
+*   **Metadata Translations**: Store UI labels in `i18n/[lang]/[object].json`.
+*   **Data Translations**: If you need to translate record content (like a Product Name), we recommend modeling it explicitly (e.g., a `ProductTranslation` table) rather than complicating the core column types.