Merge branch 'next' of github.com:devforth/adminforth

Author: NoOne7135

adminforth/documentation/docs/tutorial/05-Adapters/05-ai-completion-adapters.md

@@ -129,7 +129,7 @@ new CompletionAdapterOpenAIResponses({
 
 You can specify any GPT model you need. The default is `gpt-5-nano` as it is cheapest though may behave weakly.
 
-By default, this adapter uses the OpenAI `responses` API (`v1/responses`) unless `useComplitionApi` is set to `true`. If `useComplitionApi` is `true`, it uses the older Chat Completions API (`v1/chat/completions`). 
+By default, this adapter uses the OpenAI `responses` API (`v1/responses`) unless `useCompletionApi` is set to `true`. If `useCompletionApi` is `true`, it uses the older Chat Completions API (`v1/chat/completions`). 
 
 
 ### Using with OpenAI-compatible API providers (for example based on self-hosted vLLM docker images)
@@ -141,25 +141,25 @@ new CompletionAdapterOpenAIResponses({
   openAiApiKey: process.env.OVH_AI_ENDPOINTS_ACCESS_TOKEN as string,
   baseUrl: 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
   model: 'gpt-oss-20b',
-  useComplitionApi: true,
+  useCompletionApi: true,
   extraRequestBodyParameters: {
     store: false,
   },
 }),
 ```
 
-If `useComplitionApi` is omitted, the adapter keeps the current default behavior:
+If `useCompletionApi` is omitted, the adapter keeps the current default behavior:
 
 - official OpenAI uses the `responses` API
 - custom `baseUrl` providers use the Chat Completions API. 
 
-This is because many OpenAI-compatible providers do not yet support the `responses` API or support it unstably (for example OVH AI Endpoints still - Apr 2026 does not fully support the `responses`, so `useComplitionApi: false` may work unstably there, though you can re-test it by manually enabling it by setting `useComplitionApi: true` and checking if it works).
+This is because many OpenAI-compatible providers do not yet support the `responses` API or support it unstably (for example OVH AI Endpoints still - Apr 2026 does not fully support the `responses`, so `useCompletionApi: false` may work unstably there, though you can re-test it by manually enabling it by setting `useCompletionApi: true` and checking if it works).
 Any 3rd-party API providers might have next reasones of pure `responses` API compatibility:
 
 1) If they use vLLM open-source software under the hood they might have outdated version
 2) Custom non-vLLM implmentation might have reliable chat API implementation while give less priority to responses API as it is more complex and new.
 
-We recommend you to try responses API first by setting `false` in `useComplitionApi` because it gives rich features set, including summarization and better structured outputs, and if it does not work for your provider, then set it to `true` to have less features but working implementation.
+We recommend you to try responses API first by setting `false` in `useCompletionApi` because it gives rich features set, including summarization and better structured outputs, and if it does not work for your provider, then set it to `true` to have less features but working implementation.
 
 
 

adminforth/documentation/docs/tutorial/08-Plugins/01-agent.md

@@ -579,18 +579,18 @@ completionAdapter: new CompletionAdapterOpenAIResponses({
 
 However some of 3rd party providers might serve outdated vLLM and still don't fully support the Responses API needed for langchain internal implmentation, for example [OVH AI Endpoints](https://www.ovhcloud.com/en/public-cloud/ai-endpoints/) in Responses mode still don't play well with langchain proxy (25 Apr 2026)
 
-In that case you can try to use the OpenAI Complition API mode of the plugin, which is less efficient but more compatible with older APIs, you can force Chat Completions API mode with `useComplitionApi: true`:
+In that case you can try to use the OpenAI Chat Completions API mode of the plugin, which is less efficient but more compatible with older APIs, you can force Chat Completions API mode with `useCompletionApi: true`:
 
 ```ts
 completionAdapter: new CompletionAdapterOpenAIResponses({
   openAiApiKey: process.env.OVH_AI_ENDPOINTS_ACCESS_TOKEN as string,
   baseUrl: 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1',
   model: 'gpt-oss-120b',
-  useComplitionApi: true,
+  useCompletionApi: true,
 })
 ```
 
-OVH AI Endpoints still does not fully support the OpenAI `responses` API, so `useComplitionApi: false` may work unstably there.
+OVH AI Endpoints still does not fully support the OpenAI `responses` API, so `useCompletionApi: false` may work unstably there.
 
 
 ## Turn on audio chat support
@@ -655,6 +655,29 @@ To define a custom tool, register an API endpoint with `admin.express.endpoint`.
 
 By default, `admin.express.endpoint` applies AdminForth authorization. The endpoint handler receives `adminUser` from the user who is controlling the agent. In other words, all permissions and access rights of the agent are defined by that admin user. At the same time, actions done by the agent are automatically attributed in the audit log to the admin user who is controlling the agent.
 
+If a tool is risky, you can attach AdminForth agent metadata directly to the endpoint with the `agent` field.
+
+```ts
+type AgentRiskLevel = 'safe' | 'danger';
+
+type AgentToolMeta = {
+  riskLevel?: AgentRiskLevel;
+  confirmation?: {
+    title?: string;
+    message?: string;
+    confirmLabel?: string;
+  };
+};
+```
+
+Use it in `.endpoint(...)` like this:
+
+- `riskLevel: 'safe'` marks the tool as low-risk.
+- `riskLevel: 'danger'` marks the tool as dangerous.
+- `confirmation` customizes the confirmation dialog shown before the tool is executed.
+
+This metadata is rendered into the generated OpenAPI document, so the agent can understand that a tool is dangerous and requires an explicit confirmation UI before execution.
+
 This example uses the same email adapter pattern shown in the Email Invite and Email Password Reset plugins. The transport below uses Mailgun only to keep the snippet short; you can replace it with SES or any other adapter from [List of adapters](/docs/tutorial/ListOfAdapters/).
 
 ```ts title="./api.ts"
@@ -691,6 +714,14 @@ export function initApi(app: Express, admin: IAdminForth) {
     method: 'POST',
     path: '/send_email_to_user',
     description: 'Send an email to one AdminForth user by id. Use this after the user row is resolved.',
+    agent: {
+      riskLevel: 'danger',
+      confirmation: {
+        title: 'Send email to user',
+        message: 'This action will send a real email to the selected user.',
+        confirmLabel: 'Send email',
+      },
+    },
     request_schema: {
       type: 'object',
       additionalProperties: false,

adminforth/documentation/docs/tutorial/08-Plugins/17-bulk-ai-flow.md

@@ -283,6 +283,31 @@ new BulkAiFlowPlugin({
 }),
 ```
 
+## Image generation quality
+
+`ImageGenerationAdapterOpenAI` accepts an `extraParams` object that is passed directly to the OpenAI API. The most useful option here is `quality`, which controls the fidelity and cost of each generated image:
+
+| Value | Description |
+|-------|-------------|
+| `'low'` | Fastest generation, lowest cost. Good for drafts or high-volume batch jobs where speed matters more than visual fidelity. |
+| `'medium'` | Balanced quality and speed. A sensible default for most use cases. |
+| `'high'` | Best image quality, slowest and most expensive. Use for final promotional assets or when visual detail is critical. |
+
+```ts
+new ImageGenerationAdapterOpenAI({
+  openAiApiKey: process.env.OPENAI_API_KEY as string,
+  model: 'gpt-image-1',
+  //diff-add
+  extraParams: {
+  //diff-add
+    quality: 'low', // 'low' | 'medium' | 'high'
+  //diff-add
+  },
+}),
+```
+
+> ☝️ `'low'` quality is a great starting point when processing large datasets — you can always re-run generation with `'high'` for selected records once you're happy with the prompts.
+
 ## Rate Limiting and Best Practices
 
 - Use `rateLimit` for individual image generation operations and for the bulk image generation
@@ -429,6 +454,21 @@ If you are processing large sets of data, you might want to limit the number of
 
 And there won't be more than 5 parallel requests being handled.
 
+## Controlling page size in the generation dialog
+
+When users trigger bulk generation, records are displayed as cards in a paginated dialog. By default, 6 cards are shown per page. Use `pageSize` to tune this — lower values help when cards contain large images or long text, keeping the dialog fast and reviewable:
+
+```ts
+new BulkAiFlowPlugin({
+  actionName: 'Generate description and Price',
+
+  //diff-add
+  pageSize: 10, // default is 6
+
+  // ...
+}),
+```
+
 ## Confirming long-running generations
 
 For very large datasets, you can pause generation at specific checkpoints so users can review results before continuing.

adminforth/documentation/docs/tutorial/08-Plugins/27-dashboard.md

@@ -1,6 +1,6 @@
 ---
-title: Dashboard
-description: "Guide to the Dashboard plugin."
+title: Dashboard plugin
+description: "Documentation for the Dashboard plugin."
 slug: /tutorial/Plugins/dashboard
 ---
 
@@ -24,7 +24,7 @@ Supported widgets:
 pnpm install @adminforth/dashboard --save
 ```
 
-## Create Dashboard Configs Table
+### Create Dashboard Configs Table
 
 The plugin needs one resource to store dashboard definitions. For Prisma-based projects, add the table to your schema:
 
@@ -64,7 +64,7 @@ CREATE INDEX "dashboard_configs_slug_idx" ON "dashboard_configs"("slug");
 
 Use the JSON column type supported by your database connector. For example, PostgreSQL migrations might use `JSONB`, while SQLite migrations can use `JSON`.
 
-## Create Resource
+### Create Resource
 
 Create a resource that points to the `dashboard_configs` table:
 
@@ -136,7 +136,7 @@ export const admin = new AdminForth({
 });
 ```
 
-## Configure Plugin
+### Configure Plugin
 
 Attach the plugin to one of your resources, usually the users resource:
 
@@ -332,7 +332,7 @@ query:
 
 ### Chart With Multiple Sources
 
-Use `query.steps` when funnel steps come from different resources. Each step returns one row with `name` and the metric alias.
+Use `query.source: steps` when chart data comes from different resources. Each step returns one row with `name`, `resource`, and the selected aggregate aliases.
 
 ```yaml
 label: Sales Funnel
@@ -343,27 +343,68 @@ chart:
   type: funnel
   title: Sales funnel
 query:
+  source: steps
   steps:
     - name: Leads
       resource: leads
-      metric:
-        agg: count
-        as: value
+      select:
+        - agg: count
+          as: value
     - name: Qualified
       resource: leads
-      metric:
-        agg: count
-        as: value
+      select:
+        - agg: count
+          as: value
       filters:
         and:
           - field: status
             eq: qualified
     - name: Customers
       resource: orders
-      metric:
-        agg: count_distinct
-        field: customer_id
-        as: value
+      select:
+        - agg: count_distinct
+          field: customer_id
+          as: value
+```
+
+For the same numeric buckets across multiple resources, add `query.bucket` and render the result as a stacked bar chart. The dashboard runs every step once per bucket and returns rows with `label`, `name`, `resource`, and the aggregate aliases:
+
+```yaml
+label: Cars by Price Range and Database
+target: chart
+size: wide
+height: 360
+chart:
+  type: stacked_bar
+  x:
+    field: label
+  y:
+    field: count
+  series:
+    field: name
+query:
+  source: steps
+  bucket:
+    field: price
+    buckets:
+      - label: Budget
+        max: 3500
+      - label: Mid-range
+        min: 3500
+        max: 7000
+      - label: Premium
+        min: 7000
+  steps:
+    - name: SQLite
+      resource: cars_sl
+      select:
+        - agg: count
+          as: count
+    - name: MySQL
+      resource: cars_mysql
+      select:
+        - agg: count
+          as: count
 ```
 
 ### KPI Card

adminforth/documentation/src/pages/index.tsx

@@ -140,6 +140,18 @@ const images = [
     link: '/docs/tutorial/Plugins/background-jobs/',
     description: 'Use background jobs to handle long-running tasks efficiently. Schedule, monitor, and manage your background processes with ease even after server restarts'
   },
+  {
+    original: require('@site/static/img/previews/agent.png').default,
+    title: 'Agent Plugin - give AI any task and let it handle it',
+    link: '/docs/tutorial/Plugins/agent/',
+    description: 'Provides an internal agent that can perform various tasks based on natural language instructions. Connect it to your data and let it help you with content generation, data management, or any custom use case you can think of'
+  },
+  {
+    original: require('@site/static/img/previews/dashboards-plugin.png').default,
+    title: 'Dashboard Plugin - creare custom dashboards from web interface',
+    link: '/docs/tutorial/Plugins/dashboard/',
+    description: 'Provides a customizable dashboard plugin that allows you to create and manage dashboards for your data. Connect it to your resources and visualize your data in a meaningful way'
+  },
 ];
 
 

adminforth/documentation/static/img/previews/agent.png

@@ -1927,6 +1927,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         method: 'POST',
         path: '/create_record',
       description: 'Creates a new record in the specified resource. The endpoint validates create permissions, required fields, hidden or backend-only field rules, polymorphic foreign keys, and resource hooks before persisting and returning the created primary key.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: createRecordRequestSchema,
       response_schema: createRecordResponseSchema,
         handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
@@ -2075,9 +2078,12 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         }
     });
     server.endpoint({
-        method: 'POST',
-        path: '/update_record',
+      method: 'POST',
+      path: '/update_record',
       description: 'Updates an existing record by primary key. The endpoint validates edit permissions, current record existence, hidden, backend-only, and read-only field rules, polymorphic foreign keys, and resource hooks before saving changes.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: updateRecordRequestSchema,
       response_schema: updateRecordResponseSchema,
         handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
@@ -2216,9 +2222,12 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         }
     });
     server.endpoint({
-        method: 'POST',
-        path: '/delete_record',
+      method: 'POST',
+      path: '/delete_record',
       description: 'Deletes an existing record by primary key. The endpoint validates delete permissions, loads the current record, executes configured cascade child deletion, and then removes the record.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: deleteRecordRequestSchema,
       response_schema: deleteRecordResponseSchema,
         handler: async ({ body, adminUser, query, headers, cookies, requestUrl, response }) => {
@@ -2305,6 +2314,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/start_custom_action',
       description: 'Executes a custom resource action for a single record. The endpoint validates the resource, action existence, and action permissions, then either returns a redirect URL or executes the action handler and returns its result together with action context.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: startCustomActionRequestSchema,
       response_schema: startCustomActionResponseSchema,
       handler: async ({ body, adminUser, tr, cookies, response, headers }) => {
@@ -2361,6 +2373,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/start_custom_bulk_action',
       description: 'Executes a custom resource action in bulk mode for multiple records. The endpoint validates the resource, action existence, bulk handler availability, and permissions, then runs the bulk handler and returns its result together with action context.',
+      agent: {
+        isDangerous: true,
+      },
       request_schema: startCustomBulkActionRequestSchema,
       response_schema: startCustomBulkActionResponseSchema,
       handler: async ({ body, adminUser, tr, response, cookies, headers }) => {

adminforth/documentation/static/img/previews/dashboards-plugin.png

@@ -479,6 +479,7 @@ class ExpressServer implements IExpressHttpServer {
           method: method.toUpperCase(),
           path: routePath,
           description: schema.description,
+          agent: schema.agent,
           request_schema: schema.request,
           response_schema: schema.response,
           meta: schema.meta,
@@ -568,6 +569,7 @@ class ExpressServer implements IExpressHttpServer {
       request_schema,
       response_schema,
       responce_schema,
+      agent,
       target='json'
     } = options;
     if (!path.startsWith('/')) {
@@ -583,6 +585,7 @@ class ExpressServer implements IExpressHttpServer {
         description,
         request_schema,
         response_schema: normalizedResponseSchema,
+        agent,
         handler,
       })
       : null;

adminforth/modules/restApi.ts

@@ -56,6 +56,7 @@ class OpenApiRegistry implements IOpenApiRegistry {
       method: options.method.toLowerCase(),
       path: options.path,
       description: options.description,
+      agent: options.agent,
       request_schema: options.request_schema,
       response_schema: responseSchema,
       meta: options.meta,