Skip to content

AI module ​

The AI module lets you talk to several artificial intelligence providers in a decoupled way. The rest of the system does not need to know whether it is using Anthropic, OpenAI or Google — it only talks to AIService.

Governance ​

POST /ai/generate is a governed gateway:

  1. It resolves credentials (tenant BYOK → platform built-in with the provider_platform_ai entitlement → actionable error).
  2. Anti-abuse rate limit (plan ≤ global) applies to BYOK and platform before resolving or executing. Fixed 60s window per companyId, persisted in ai_rate_limit_counters to share the limit across replicas and keep it across restarts. Rejection: AI_RATE_LIMIT_EXCEEDED (HTTP 429). The numeric thresholds are not published.
  3. BYOK usage consumes neither plan quotas nor overage balance.
  4. Platform usage applies the model allowlist, the maxTokens ceiling and the included quotas (tokens + requests) of the current billing cycle — read live on every request (a plan change mid-cycle applies immediately).
  5. After a successful platform generate:
    • with included headroom → classified included, adding to the included counters;
    • with the included quota exhausted → classified overage, adding to the overage counters and charging the balance per platform_ai_overage_tariff (minor units / 1k tokens).
  6. If the included quota is exhausted and the overage switch is off → AI_OVERAGE_SWITCH_OFF. If the switch is on but the balance is ≤ 0 → AI_OVERAGE_SALDO_INSUFFICIENT.
  7. Failures charge nothing (neither quota nor balance). The cycle reset restarts the included/overage counters; it does not reset the switch or the balance.

Consumption, overage and balance (OWNER/ADMIN) ​

MethodRouteDescription
GET/ai/consumptionCycle consumption: included ceilings, included/overage used, remaining, switch, balance, cycle dates/id, resolution hint BYOK vs platform (no secrets and no rate-limit thresholds)
GET/ai/overageSwitch state + current prepaid balance
PATCH/ai/overage/switchBody { "enabled": true|false } — enables/disables overage (off by default)
POST/ai/overage/saldo/creditsDisabled for any human caller, including a Super Admin: it answers 403. Only the internal hook AiOverageService.applyConfirmedPaymentCredit credits balance after a confirmed payment; idempotent by paymentReference

OWNER/ADMIN can read the switch/balance and change the switch. MEMBER/VIEWER receive 403 on /ai/overage* and /ai/consumption. Anyone, including OWNER/ADMIN and a Super Admin, receives 403 when trying to credit balance through POST .../saldo/credits. Recharging is not exposed in the browser/node SDK; the SDK covers reading and the switch, not balance crediting. The full Stripe checkout stays outside this endpoint.

Assistants / public widget (entitlements) ​

Tenant assistants and the public widget are different plan capabilities from the governed gateway. Having provider_platform_ai (or other AI quota keys) does not enable assistants or the widget.

KeyTypeEffect
ai_assistantsflagCreate/use tenant assistants (authenticated channels)
ai_public_widgetflagPublish and serve the anonymous public widget
ai_max_assistantslimitOptional cap when creating assistants (no plan key → no product cap)
ai_max_skillslimitOptional cap when creating tenant skills

Enforcement through AssistantsEntitlementGate (exported by AIModule). Without the FLAG → AI_ASSISTANTS_NOT_ENTITLED / AI_PUBLIC_WIDGET_NOT_ENTITLED (422). With a LIMIT and no headroom → AI_ASSISTANTS_LIMIT_EXCEEDED / AI_SKILLS_LIMIT_EXCEEDED (422).

Skill catalogue and platform assistants ​

Module AssistantsModule. Global resources (super admin). Startup seed: the Config Nimobase assistant plus the platform skills (some shareable, some not).

For NimoApps connection administration, the catalogue includes the skills app-projects.connections.get and app-projects.connections.update. They run only from authenticated Nimo with the OWNER/ADMIN role; the update requires explicit confirmation. They return UUID references and diagnostics, never credentials. The handler marks them as ineligible for the public widget; the control plane is not published in the public SDK or external MCP.

The internal catalogue also includes app-projects.environments.promote. It requires explicit confirmation and revalidates on the server the OWNER/ADMIN session, the expected revisions and the deployed Preview release before atomically updating the active Production assignment. It does not start a new provider deployment and is not available to the public widget, the public SDK or external MCP.

MethodRouteAuthDescription
GET/ai/catalog/skillsOWNER, ADMINShareable catalogue skills only
GET/ai/platform/skillsSuper adminFull catalogue
POST/PATCH/DELETE/ai/platform/skillsSuper adminCRUD + shareable flag
GET/POST/PATCH/DELETE/ai/platform/assistantsSuper adminPlatform assistants
PUT/ai/platform/assistants/:id/skillsSuper adminSkill allowlist
POST/ai/platform/assistants/:id/skills/:skillId/invokeSuper adminAllowlisted invocation; writes ask for confirmed; after confirmation it runs real mutations (settings/maintenance)

Tenant assistants and skills ​

Company CRUD (origin=tenant, companyId from the JWT). Requires the ai_assistants entitlement (and optionally the ai_max_assistants / ai_max_skills limits) on create. MEMBER/VIEWER → 403 on all these routes.

MethodRouteAuthDescription
GET/POST/PATCH/DELETE/ai/skillsOWNER, ADMINTenant skills; serviceKey Nimobase allowlist only; riskClass mandatory
GET/POST/PATCH/DELETE/ai/assistantsOWNER, ADMINTenant assistants; create/update accept presentationName / presentationAvatarUrl
PUT/ai/assistants/:id/skillsOWNER, ADMINAllowlist: shareable catalogue skills and/or own ones; rejects non-shareable ones or ones from another company

Tenant skills accept neither settings.get nor settings.put: the settings table is global and does not belong to a company. The catalogue read skill is platform-only too; authenticated access to GET /settings keeps its read contract.

The published /ai/skills contract (CreateTenantSkillDto.serviceKey.enum in packages/openapi/openapi.json and the public SDK) enumerates only the public tenant surface. The internal administration operations (app-projects.*, app-domains.*, app-dns-connections.*, app-repository-bindings.*, app-repository-export.*, app-migrations.*, git-integrations.webhooks.*) are declared with internalAdmin in the capability catalogue and are never published; the marker does not change what internal Nimo can execute.

The catalogue seed includes application-dsl.generate-draft as a shareable skill for tenant assistants. Draft generation requires OWNER/ADMIN inside the DSL handler and uses AIService with the existing provider resolution and governance. Even though the skill is classified as read, its result is an editable candidate pending review (valid=false, publishable=false). The server empties the policy/rules collections, the access roles for forms/views/triggers and the assignments; it removes actor_has_role conditions and marks the pending fields for the person in the editor. If the validator rejects the empty roles, it keeps the candidate document and attaches the errors so it can be completed manually.

Tenant capability catalogue (FE-AI-001) ​

GET /ai/capabilities returns the catalogue filtered for the JWT session and active company: it requires membership and the ai_assistants entitlement. It checks the current membership role; a role change requires renewing the session. It accepts no user or role IDs in the route, query or body, and it does not enumerate Object Storage objects.

The response omits planned and platform capabilities, filters OWNER/ADMIN operations by the current role, and includes requirements, limits and explicit confirmation per operation. Object Storage only appears with object_storage_enabled and the live permission/grant. App Data is available at company level with ai_assistants, but every operation resolves the published application, the assigned role and its contract when it runs. Commercial billing keeps its tenant reads and reserves writes for OWNER/ADMIN. Push only appears for OWNER/ADMIN and reports the current cap of 100 recipients.

The catalogue describes current access; it grants no permissions and guarantees no later operation's outcome. Every tool revalidates tenant, membership, entitlement, grants and confirmation before operating.

Commercial billing bridge (/ AI-BILLING-001) ​

The shareable catalogue for tenant assistants exposes reading clients, types, products and documents; it prepares a draft proposal and allows issuing an existing draft after a separate review. It does not use billing.invoices.list, which reads Nimobase's subscription invoices.

On every call the handler rechecks the authenticated context's company and user, the current membership and role, and ai_assistants. OWNER/ADMIN can create drafts and issue; every write requires the chat's confirmation. Price and taxes come from the current product and fiscal catalogue. Series and sequential numbers are resolved from the document type; the model cannot send its own amounts, rates or series. Issuance compares the proposal against the current document and catalogue again, and requires the document to still be a draft.

The bridge covers company→client invoices prepared from existing products. Assisted creation of credit notes/rectifications and platform→company invoicing are not offered; there is no operation to email invoices in the current module either.

Files and Object Storage bridge (/ AI-FILES-001) ​

The tenant assistant can list metadata and organize paths in the active company's space: create folders, move, delete and create or revoke temporary links. Human confirmation is mandatory for these mutations; folder deletion is recursive. The handler pins space=tenant, requires the authenticated context and revalidates ai_assistants; ObjectStorageService revalidates object_storage_enabled, grants/permissions and access to the object on every call.

Binary upload, binary download, the platform space and grant management are not exposed. To share a download it creates a public link scoped to one object, 48 hours by default, with explicit confirmation. backups/ paths and paths outside the active space stay blocked; resource errors include neither names nor metadata from other tenants.

Push notification bridge (/ AI-PUSH-001) ​

The shareable catalogue exposes notifications.push.recipients.list and notifications.push.send. Both operations recheck on every call the active company, the authenticated human session, the current OWNER/ADMIN membership and role, and the ai_assistants entitlement. The recipient query returns only id and name, paginated up to 100 per page.

Sending accepts a closed list of 1 to 100 current members, a title, a body, an optional internal route and explicit web_push/native_push channels. It accepts no broadcast, email, webhook, in-app, tenant selected by the model, credentials or device tokens. The write call goes through the chat's confirmation flow; the server compares every id and name against the current membership before delegating to NotificationsService.sendComposed, which records tenant, actor and operation in the outbox.

Acceptance is best-effort, not a delivery receipt: preferences, a missing subscription/device, no linked native app or a NoOp provider may skip delivery. The push skill is not available in the anonymous widget and does not allow registering devices or changing credentials.

In authenticated execution and in the widget, the catalogue rechecks current visibility: an already-assigned platform skill stops being available to tenant assistants when shareable becomes false. Tenant-own skills do not depend on that flag.

Presentation identity: every assistant response includes resolved presentationName and presentationAvatarUrl:

OriginpresentationNamepresentationAvatarUrl
platformalways NimoNimobase logo (FRONTEND_URL + /brand/icon.svg, or a relative path when there is no FRONTEND_URL)
tenantthe value configured by OWNER/ADMIN, or name when absentthe configured URL, or null → the client must show the default robot avatar

There is no file upload in this delivery: the tenant avatar is an HTTP(S) URL. A PATCH with presentationAvatarUrl: null clears the avatar. Input limits (400 when exceeded): presentationName ≤ 255 characters; presentationAvatarUrl ≤ 2048 (aligned with the persisted columns).

Authenticated chat (+) ​

OWNER/ADMIN/MEMBER/VIEWER chat by assistant UUID. If origin=tenant, the ai_assistants entitlement is still required and the assistant must belong to the active company. If origin=platform (Config Nimobase / the dashboard's Nimo), the assistants add-on is not required: it is product surface. The thread stays isolated by company+user and the consumption is billed to the actor's tenant.

Shareable read skills assigned to Nimo can run when the actor is authorized. The global Settings skills (settings.get and settings.put) are platform-only and require a super admin; other non-shareable catalogue mutations (maintenance.set) are also executed only by a platform super admin (same spirit as POST /ai/platform/assistants/:id/skills/:skillId/invoke): a normal OWNER/ADMIN/MEMBER sees them rejected; the SA confirms and executes.

GET /ai/assistants does not list platform assistants; the administration GET (GET /ai/assistants/:id, OWNER/ADMIN) on a platform UUID still answers 404. The authenticated launcher does not use that GET or the seed: it calls GET /ai/assistants/:assistantId/presentation, which does resolve platform Nimo.

Generation goes through the governed runtime (AIService.generate). Only skills in the assistant's allowlist. read skills run without extra confirmation; tenant write/destructive ones return status: awaiting_confirmation with a pendingId until confirm or reject. History in ai_conversations. Confirmation is claimed atomically before running the skill: if two confirmations arrive at once, only one can apply the write. Retries after a completed run are idempotent. To reconnect a turn after losing the response, the client resends the same requestId UUID with the same content: the API recovers the stored response without generating another message or re-running skills. Reusing the ID with different content, provider or model answers 409. The reservation is limited to the company, assistant and authenticated user; a turn in progress does not run in parallel. GET /ai/conversations?limit=&offset= returns only the current user's authenticated conversations, in pages of up to 100 rows. It is an internal Nimo route and is not exported to the public SDK/OpenAPI. Long-running job operationIds point at the existing durable record: GET /app-operations/:id reads progress inside the active company. Every thread belongs to one specific assistant: reusing a conversationId from another assistant in POST …/:assistantId/chat answers an opaque 404 (same criterion as an id foreign to the tenant/user) and does not mix history with the route assistant's prompt or skills.

Authenticated Nimo responses include schemaVersion: 1, messageId and blocks, plus the compatibility field assistantMessage. History persists the blocks so they survive a reload; old messages or messages with unknown blocks are presented as text. The registry accepts only text, choice, review, progress, dsl_preview and the form, table, chart, diff and confirm review and decision widgets. The model can only propose text, choice or dsl_preview; the rest is emitted by the server and its payload is validated before being persisted. Blocks execute no code.

Review widgets have closed limits: forms of up to 8 fields and tables of up to 6 columns with pagination. A chart must include its equivalent table, plus source, period, units and filters; without it the block is rejected. confirm requires an interactionId issued by the server and authorizes nothing by itself: the only route that runs a write skill remains the confirmation of pendings. Dismissing a widget (with Escape, say) is local to the client and does not cancel the work. A public renderer may limit which types it accepts; anything outside its scope is shown as text.

A choice option carries IDs and labels generated from a closed list. The API accepts only a choiceId from that list through the interaction endpoint; it records the use atomically and expires it after 15 minutes. The validated label is sent as an ordinary chat message and authorizes no skill. review confirmations keep using exclusively the existing pending-skill flow, also with a 15-minute expiry. These blocks and the choice route belong to the authenticated chat, not the public widget.

One protocol for every Nimo surface: the public widget and the launcher respond with the same envelope (schemaVersion, messageId, blocks) plus assistantMessage, read from the same persisted message. An embeddable host's scope is closed — text, progress, dsl_preview, table, chart and diff — so review, form, confirm and choice never reach an integrator: if the stored message keeps a block with authority, the turn degrades to a text block with the assistant's message. Platform administration (projects, environments, releases, hosting, domains, DNS and Git) stays outside these blocks, the public SDK and external MCP. The chat request carries only explicit fields (message, conversationId, visitorId and the existing routing hints): the server resolves the tenant and screenshots, form values or secrets are never accepted.

Skill result: a confirmed fact, not prose ​

Every skillResults element reports outcome (completed, partial or failed) and effects, the list of steps the server can prove with state: applied | not_applied | unknown and an optional reason. ok remains only as a compatibility alias of outcome !== "failed".

This avoids two common deceptions:

  • An accepted push send whose channels the provider skipped is not a binary success: it is reported as partial with the channel that went out and the one that did not, with its reason (no_recipient_devices, no_app_client_linked).
  • A file operation answering status: not_found, conflict or invalid inside the payload is not shown as executed: it is reported as failed, because nothing was applied.

The assistant's text is only text: the chat never infers that something ran from the model's prose. The execution label, the summary, the effect list and the state of long-running jobs are built solely from skillResults and the durable operations record. If the server predates this contract, the client falls back to the inherited ok.

The contract does not widen permissions. No skill parameter can pin the company or choose credentials: the company comes from the session, the result always returns the server's company and every handler validates a closed list of keys. Nimo's internal channel receives the same outcome/effects with its own scope, without additional privileges.

MethodRouteAuthDescription
GET/ai/assistants/:assistantId/presentationOWNER, ADMIN, MEMBER, VIEWERMinimal presentation (id, origin, presentationName, presentationAvatarUrl). No systemPrompt or skills. Tenant: active company + ai_assistants. Platform: 200 without that add-on. Opaque 404 when not accessible (same criterion as the chat POST)
POST/ai/assistants/:assistantId/chatOWNER, ADMIN, MEMBER, VIEWERChat message (message, optional conversationId from the same assistant and a UUID requestId). Repeating the same ID + content returns the persisted response without repeating the turn; an ID reused with other content returns 409. provider does not change the resolved vendor; model may be an override subject to the plan allowlist for vendors other than OpenRouter. The response includes neither provider nor model; pending confirmations and skill results include serviceKey to identify the operation. 404 when the thread belongs to another assistant
GET/ai/conversations?limit=&offset=OWNER, ADMIN, MEMBER, VIEWERInternal paginated listing of the authenticated user's conversations (1–100 rows, offset up to 1,000,000). It does not appear in the public SDK/OpenAPI
GET/ai/conversations/:conversationIdOWNER, ADMIN, MEMBER, VIEWERHistory + open pendings
POST/ai/conversations/:conversationId/messages/:messageId/interactions/:interactionIdsameSends the choiceId of a persisted option; single use and 15 minutes. Continues the chat without authorizing skills; 400 when the option does not belong to the block, 409 when it expired or was already used
POST/ai/conversations/:conversationId/pending-skills/:pendingId/confirmsameConfirms and runs the write skill
POST/ai/conversations/:conversationId/pending-skills/:pendingId/rejectsameRejects without running

For tests with the noop provider, a message [[skill:<toolName>]]{…json} makes the NoOp emit tool_calls (toolName = skill.code or skill.id).

Public widget ​

OWNER/ADMIN publish an assistant as a widget without a Nimobase login. It requires the ai_public_widget entitlement to publish and to serve anonymous requests. When assigning skills, publicSafeSkillIds marks which ones are suitable for the widget; in v1 only riskClass=read.

Anonymous chat bills usage to the owning tenant and applies shared anti-abuse limits of 20 turns/minute per IP+assistant, 60 per assistant+tenant and 120 per tenant, on top of Nest's @Throttle. Unpublishing rejects anonymous requests. The anonymous launcher reads GET /ai/public/widget/:assistantId to decide whether to show the bubble: 200 only when published and, for origin=tenant, the plan still has ai_public_widget. A 404 does not distinguish existence. OWNER/ADMIN list and read the history (channel=public).

A published origin=platform assistant can be served on this endpoint without ai_public_widget when there is a request tenant; if the assistant's companyId is null and there is no tenant in the request → 422 AI_PUBLIC_WIDGET_TENANT_REQUIRED. Config Nimobase is not published in the seed: the landing's anonymous launcher remains a follow-up (the public widget does not accept pk_ in the current matrix and the tenant interceptor does not invent a company).

MethodRouteAuthDescription
PUT/ai/assistants/:assistantId/public-widgetOWNER, ADMIN{ published: true|false }
GET/ai/assistants/:assistantId/public-widget/conversationsOWNER, ADMINListing of the widget's threads
GET/ai/assistants/:assistantId/public-widget/conversations/:conversationIdOWNER, ADMINDetail + messages
GET/ai/public/widget/:assistantIdPublicPublished presence (id, origin, presentationName, presentationAvatarUrl, publicWidgetEnabled). Opaque 404 when missing, unpublished or the tenant lacks ai_public_widget. No systemPrompt or skills. A published platform assistant requires no tenant
POST/ai/public/widget/:assistantId/chatPublicAnonymous chat (message, optional conversationId / visitorId). The inherited provider/model fields are ignored: the server governs selection and reuses the conversation's resolved model; optional X-Widget-Visitor-Id header. Shared limits: 20/min per IP+assistant, 60/min per assistant+tenant and 120/min per tenant; visitorId only identifies the conversation. The response includes neither provider nor model

Available providers ​

ProviderEnvironment variable / vaultStatus
Anthropic (Claude)ANTHROPIC_API_KEY or vault secret apiKeyAvailable when a key exists
OpenAI (GPT)OPENAI_API_KEY or vault secret apiKeyAvailable when a key exists
Google (Gemini)GOOGLE_API_KEY or vault secret apiKeyAvailable when a key exists
NoOp— (vendor noop in the provider catalogue)Deterministic stub for tests

Governed generation uses the vault-resolved credentials, not only the environment variables.

How to use it from code ​

Other modules can import AIModule and inject AIService:

typescript
import { AIModule } from '../ai/ai.module';

@Module({ imports: [AIModule] })
export class MyModule {}

@Injectable()
export class MyService {
  constructor(private readonly aiService: AIService) {}

  async summarize(text: string): Promise<string> {
    const response = await this.aiService.generate({
      provider: AIProvider.ANTHROPIC,
      model: 'claude-sonnet-4-6',
      messages: [{ role: 'user', content: `Summarize: ${text}` }],
      maxTokens: 500,
    });
    return response.content;
  }
}

Available models ​

Anthropic ​

ModelContextCapabilities
claude-opus-5200k tokensText, vision, tools, structured output, streaming
claude-sonnet-5200k tokensText, vision, tools, structured output, streaming
claude-sonnet-4-6200k tokensText, vision, tools, structured output, streaming
claude-haiku-4-5-20251001200k tokensText, vision, tools, structured output, streaming

OpenAI ​

ModelContextCapabilities
gpt-4o128k tokensText, vision, tools, structured output, streaming
gpt-4o-mini128k tokensText, vision, tools, structured output, streaming
o3200k tokensText, tools, streaming
o4-mini128k tokensText, vision, tools, streaming

Google ​

ModelContextCapabilities
gemini-2.5-pro1M tokensText, vision, tools, structured output, streaming
gemini-2.5-flash1M tokensText, vision, tools, structured output, streaming
gemini-2.0-flash1M tokensText, vision, tools, structured output, streaming

HTTP API ​

Every endpoint requires authentication (Authorization: Bearer <token>).

GET /ai/providers ​

Returns the available providers (with configured credentials).

json
{
  "available": ["anthropic", "openai"]
}

GET /ai/models ​

Returns every registered model. Filter by provider with ?provider=anthropic. ?provider=openrouter returns only the Auto Router (openrouter/auto); there is no live OpenRouter model catalogue.

json
{
  "models": [
    {
      "id": "claude-sonnet-4-6",
      "displayName": "Claude Sonnet 4.6",
      "provider": "anthropic",
      "capabilities": [
        "text_generation",
        "vision",
        "tool_calling",
        "structured_output",
        "streaming"
      ],
      "contextWindow": 200000,
      "maxOutputTokens": 8096
    }
  ]
}

POST /ai/generate ​

Synchronous text generation. provider accepts anthropic | openai | google | openrouter | noop. With openrouter the model field is still mandatory in the body, but the backend ignores it and uses the Auto Router (openrouter/auto).

Body:

json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "messages": [{ "role": "user", "content": "What is the capital of France?" }],
  "systemPrompt": "You are a helpful assistant that answers in English.",
  "temperature": 0.7,
  "maxTokens": 500
}

Response:

json
{
  "content": "The capital of France is Paris.",
  "model": "claude-sonnet-4-6",
  "provider": "anthropic",
  "finishReason": "stop",
  "usage": {
    "inputTokens": 28,
    "outputTokens": 12,
    "totalTokens": 40
  }
}

Possible errors ​

ErrorCause
404Provider not registered or without credentials
400Invalid request or rejected by content policy
429 + AI_PROVIDER_RATE_LIMITEDProvider/OpenRouter rate limit (different from governance)
429 + AI_RATE_LIMIT_EXCEEDEDGovernance anti-abuse rate limit
500Internal provider error or authentication failure

Asynchronous calls (Jobs) ​

If you do not want to block the HTTP response, use RunAIRequestJob:

typescript
await this.jobDispatcher.dispatch(
  new RunAIRequestJob({
    provider: AIProvider.ANTHROPIC,
    model: 'claude-sonnet-4-6',
    messages: [{ role: 'user', content: '...' }],
  }),
);

The job runs in the background. Errors are handled by the retry system.

System events ​

The module publishes events automatically:

EventWhen it is emittedPayload
ai.request-completedSuccessful generationprovider, model, inputTokens, outputTokens, durationMs
ai.governed-usage-recordedAfter a successful governed generateusage metadata (classification, saldoImpact, …) — no prompts
ai.overage-saldo-creditedAfter a balance top-upamountMinorUnits, saldoMinorUnitsAfter, paymentReference
ai.request-failedGeneration errorprovider, model, errorType, durationMs

Security note: full prompts and responses are NOT included in events. Only usage metadata is recorded.

Configuration ​

Add the environment variables for the providers you want to use:

env
# One or more of these:
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...

Without configured credentials the system runs with the noop provider (placeholder responses) — useful in development.

Adding a new provider ​

  1. Add the identifier to the AIProvider enum in src/api/ai/constants/ai-provider.enum.ts
  2. Create src/api/ai/providers/<name>/<name>.provider.ts implementing IAIProvider
  3. Document the API key environment variable
  4. Register the provider in src/api/ai/ai.module.ts inside the AIProviderRegistry factory
  5. Add model definitions in src/api/ai/models/<name>.models.ts
  6. Add tests in src/api/ai/providers/<name>/<name>.provider.spec.ts

No consumer code needs changes.

What it does NOT do (yet) ​

  • Real-time token streaming
  • Embeddings, image generation, audio
  • Autonomous agents / RAG
  • Automatic fallback between providers
  • Embedded Stripe checkout for top-ups (the internal credit is the post-payment hook)

NimoApps forms and capabilities inventory ​

The current administrative form lives in frontend/src/app/features/app-projects/app-projects.page.ts and app-projects.page.html. The SPA uses ApplicationEnvironmentsInternalService as its internal transport. Tenant Nimo uses ApplicationProjectsAssistantSkillHandler, registered in AssistantSkillServiceRegistry; the handler invokes backend services with the authenticated context, not the public SDK. On every run the server again requires a user session, an active company and a live OWNER/ADMIN membership. Tenant Nimo's entitlement is ai_assistants (assistant-feature). The public widget is independent and this handler returns isWidgetEligible: false. The test owners abbreviated as "handler" and "catalogue" in the table are backend-api/src/api/assistants/application-projects-assistant-skill.handler.spec.ts and backend-api/src/api/assistants/chat/assistant-capability.registry.spec.ts.

Form/actionInternal API → SPA clientInternal Nimo: serviceKey → handlerRisk, scope, effective permission, entitlement and confirmationOwning tests
List and select a projectGET /app-projects → listProjectsapp-projects.list → ApplicationEnvironmentsService.listProjectsRead, tenant; OWNER/ADMIN; ai_assistants; no confirmationNimo: application-projects-assistant-skill.handler.spec.ts; catalogue: assistant-capability.registry.spec.ts; API and SPA: service and page tests
Create a project and its initial environmentsPOST /app-projects → createProjectapp-projects.create → ApplicationEnvironmentsService.createProjectWrite, tenant; OWNER/ADMIN; ai_assistants; explicit confirmationNimo: application-projects-assistant-skill.handler.spec.ts; catalogue: assistant-capability.registry.spec.ts; API/SPA: service and page tests
Read environmentsGET /app-projects/:id/environments → listEnvironmentsapp-projects.environments.list → ApplicationEnvironmentsService.listEnvironmentsRead, tenant; effective OWNER/ADMIN; ai_assistants; no confirmationHandler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts
Create an immutable releasePOST /app-projects/:id/releases → createReleaseapp-projects.releases.create → ApplicationEnvironmentsService.createReleaseWrite, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation. Creating a release neither builds nor deploysHandler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts
Build a release artifact (no separate form)POST /app-projects/:projectId/releases/:releaseId/artifact → buildReleaseArtifactapp-projects.artifacts.build → internal projects handlerWrite, tenant; OWNER/ADMIN; ai_assistants; explicit confirmationapplication-projects-assistant-skill.handler.spec.ts; deployments service
Read a release artifact (no separate form)GET /app-projects/:projectId/releases/:releaseId/artifact → getReleaseArtifactapp-projects.artifacts.get → internal projects handlerRead, tenant; effective OWNER/ADMIN; ai_assistants; no confirmationHandler and catalogue; deployments service tests
Read per-environment connectionsGET /app-projects/:projectId/environments/:environmentId/connections → getConnectionsapp-projects.connections.get → ApplicationEnvironmentsService.getConnectionsRead, tenant; effective OWNER/ADMIN; ai_assistants; no confirmation. Returns references/diagnostics only, never credentialsHandler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts
Save environment connectionsPUT /app-projects/:projectId/environments/:environmentId/connections → updateConnectionsapp-projects.connections.update → ApplicationEnvironmentsService.updateConnectionsWrite, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation. Preview accepts no productive referencesHandler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts
Start a durable deploymentPOST /app-operations → createOperationapp-projects.operations.create → AppOperationsService.createWrite, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation. Acceptance does not equal deployment successHandler, catalogue and tenant-assistant-chat.service.spec.ts; app-operations.service.spec.ts; app-projects.page.spec.ts
Read operation stateGET /app-operations/:id → getOperationapp-projects.operations.get → AppOperationsService.getRead, tenant; effective OWNER/ADMIN; ai_assistants; no confirmationHandler and catalogue; app-operations.service.spec.ts; app-projects.page.spec.ts
Cancel a pending deploymentPOST /app-operations/:id/cancel → cancelOperationapp-projects.operations.cancel → AppOperationsService.cancelDestructive, tenant; OWNER/ADMIN; ai_assistants; explicit confirmationHandler, catalogue and tenant-assistant-chat.service.spec.ts; app-operations.service.spec.ts; app-projects.page.spec.ts
List runtime originsGET /app-projects/:projectId/environments/:environmentId/runtime-origins → listRuntimeOriginsapp-projects.runtime-origins.list → internal projects handlerRead, tenant; effective OWNER/ADMIN; ai_assistants; no confirmationHandler and catalogue; runtime-origin.spec.ts; SPA page
Register a runtime originPOST /app-projects/:projectId/environments/:environmentId/runtime-origins → createRuntimeOriginapp-projects.runtime-origins.register → internal projects handlerWrite, tenant; OWNER/ADMIN; ai_assistants; explicit confirmationHandler and catalogue; runtime-origin.spec.ts; app-projects.page.spec.ts
Retire a runtime originDELETE /app-projects/:projectId/environments/:environmentId/runtime-origins/:originId → retireRuntimeOriginapp-projects.runtime-origins.retire → internal projects handlerDestructive, tenant; OWNER/ADMIN; ai_assistants; explicit confirmationHandler and catalogue; runtime-origin.spec.ts; app-projects.page.spec.ts
Issue a scoped runtime sessionPOST /app-projects/:projectId/environments/:environmentId/runtime-sessions → createRuntimeSessionapp-projects.runtime-sessions.issue → internal projects handlerWrite, tenant; OWNER/ADMIN; ai_assistants; explicit confirmationHandler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts
Revoke your own runtime sessionDELETE /app-projects/runtime-sessions/:id → revokeRuntimeSessionapp-projects.runtime-sessions.revoke → internal projects handlerDestructive, tenant; OWNER/ADMIN; ai_assistants; explicit confirmationHandler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts

The permissions shown reflect the server's effective revalidation. Every app-projects read now declares OWNER or ADMIN, which is what ApplicationEnvironmentsService.requireAdmin enforces on each call; before, the generic metadata said "authenticated tenant session" and described less than the server validated. The catalogue grants no authority: adding app-projects.list aligned the declarative permission of the existing reads without widening any guard.

Public surfaces and global operations ​

  • Public SDK: packages/sdk-typescript/src/index.ts re-exports paths from generated/openapi.ts. The contract contains 12 internal /app-projects and /app-operations routes; additionally, the /ai/skills and /ai/assistants schemas include app-projects.* literals in serviceKey. There are no high-level helpers to administer NimoApps, but routes and types already expose those details to integrators. This is a contract exposure; it does not bypass the backend guards. Contract tests cover routes, schemas and the internal/public boundary.
  • Other paths: the exported contract contains no /app-deployments, domain or Git routes. /application-dsl keeps definition authoring, publishing, roles and the pre-existing runtime APIs; it is a separate earlier capability and is preserved outside the new projects/hosting control plane. The follow-up will audit the full external contract before closing the boundary.
  • External MCP: packages/mcp-server/src/tool-registry.ts keeps a manual NIMOBASE_TOOL_REGISTRY. There are no administrative tools for projects, environments, releases, connections, deployments, domains or Git. The existing runtime and data tools keep their current scope.
  • Embeddable chat: the widget registry is independent and the projects handler's operations are not eligible. The control plane is not added to the widget.
  • Public runtime: the artifact execution, data and scoped runtime API endpoints remain separate from these administrative routes; they are neither removed nor widened here.

Global operations are not tenant NimoApps forms. settings.get is read/platform, with no entitlement and no confirmation; settings.put and maintenance.set are write/platform, require a Super Admin and confirmation. The executor only allows them from the platform assistant and revalidates Super Admin; the tenant assistant is denied even when it receives a shareable skill. Test: backend-api/src/api/assistants/chat/assistant-skill-executor.spec.ts. No global rules are changed.

The architectural boundary is already documented: internal Nimo and platform internal transport; no new administration through the public SDK, external MCP or embeddable chat; the scoped public runtime is preserved. The generated-OpenAPI gap remains a follow-up and does not change the authority defined by the catalogue.