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:
- It resolves credentials (tenant BYOK → platform built-in with the
provider_platform_aientitlement → actionable error). - Anti-abuse rate limit (plan ≤ global) applies to BYOK and platform before resolving or executing. Fixed 60s window per
companyId, persisted inai_rate_limit_countersto share the limit across replicas and keep it across restarts. Rejection:AI_RATE_LIMIT_EXCEEDED(HTTP 429). The numeric thresholds are not published. - BYOK usage consumes neither plan quotas nor overage balance.
- Platform usage applies the model allowlist, the
maxTokensceiling and the included quotas (tokens + requests) of the current billing cycle — read live on every request (a plan change mid-cycle applies immediately). - 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).
- 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. - 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)
| Method | Route | Description |
|---|---|---|
GET | /ai/consumption | Cycle 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/overage | Switch state + current prepaid balance |
PATCH | /ai/overage/switch | Body { "enabled": true|false } — enables/disables overage (off by default) |
POST | /ai/overage/saldo/credits | Disabled 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.
| Key | Type | Effect |
|---|---|---|
ai_assistants | flag | Create/use tenant assistants (authenticated channels) |
ai_public_widget | flag | Publish and serve the anonymous public widget |
ai_max_assistants | limit | Optional cap when creating assistants (no plan key → no product cap) |
ai_max_skills | limit | Optional 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.
| Method | Route | Auth | Description |
|---|---|---|---|
GET | /ai/catalog/skills | OWNER, ADMIN | Shareable catalogue skills only |
GET | /ai/platform/skills | Super admin | Full catalogue |
POST/PATCH/DELETE | /ai/platform/skills | Super admin | CRUD + shareable flag |
GET/POST/PATCH/DELETE | /ai/platform/assistants | Super admin | Platform assistants |
PUT | /ai/platform/assistants/:id/skills | Super admin | Skill allowlist |
POST | /ai/platform/assistants/:id/skills/:skillId/invoke | Super admin | Allowlisted 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.
| Method | Route | Auth | Description |
|---|---|---|---|
GET/POST/PATCH/DELETE | /ai/skills | OWNER, ADMIN | Tenant skills; serviceKey Nimobase allowlist only; riskClass mandatory |
GET/POST/PATCH/DELETE | /ai/assistants | OWNER, ADMIN | Tenant assistants; create/update accept presentationName / presentationAvatarUrl |
PUT | /ai/assistants/:id/skills | OWNER, ADMIN | Allowlist: 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:
| Origin | presentationName | presentationAvatarUrl |
|---|---|---|
platform | always Nimo | Nimobase logo (FRONTEND_URL + /brand/icon.svg, or a relative path when there is no FRONTEND_URL) |
tenant | the value configured by OWNER/ADMIN, or name when absent | the 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
partialwith 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,conflictorinvalidinside the payload is not shown as executed: it is reported asfailed, 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.
| Method | Route | Auth | Description |
|---|---|---|---|
GET | /ai/assistants/:assistantId/presentation | OWNER, ADMIN, MEMBER, VIEWER | Minimal 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/chat | OWNER, ADMIN, MEMBER, VIEWER | Chat 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, VIEWER | Internal 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/:conversationId | OWNER, ADMIN, MEMBER, VIEWER | History + open pendings |
POST | /ai/conversations/:conversationId/messages/:messageId/interactions/:interactionId | same | Sends 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/confirm | same | Confirms and runs the write skill |
POST | /ai/conversations/:conversationId/pending-skills/:pendingId/reject | same | Rejects 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).
| Method | Route | Auth | Description |
|---|---|---|---|
PUT | /ai/assistants/:assistantId/public-widget | OWNER, ADMIN | { published: true|false } |
GET | /ai/assistants/:assistantId/public-widget/conversations | OWNER, ADMIN | Listing of the widget's threads |
GET | /ai/assistants/:assistantId/public-widget/conversations/:conversationId | OWNER, ADMIN | Detail + messages |
GET | /ai/public/widget/:assistantId | Public | Published 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/chat | Public | Anonymous 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
| Provider | Environment variable / vault | Status |
|---|---|---|
| Anthropic (Claude) | ANTHROPIC_API_KEY or vault secret apiKey | Available when a key exists |
| OpenAI (GPT) | OPENAI_API_KEY or vault secret apiKey | Available when a key exists |
| Google (Gemini) | GOOGLE_API_KEY or vault secret apiKey | Available 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:
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
| Model | Context | Capabilities |
|---|---|---|
claude-opus-5 | 200k tokens | Text, vision, tools, structured output, streaming |
claude-sonnet-5 | 200k tokens | Text, vision, tools, structured output, streaming |
claude-sonnet-4-6 | 200k tokens | Text, vision, tools, structured output, streaming |
claude-haiku-4-5-20251001 | 200k tokens | Text, vision, tools, structured output, streaming |
OpenAI
| Model | Context | Capabilities |
|---|---|---|
gpt-4o | 128k tokens | Text, vision, tools, structured output, streaming |
gpt-4o-mini | 128k tokens | Text, vision, tools, structured output, streaming |
o3 | 200k tokens | Text, tools, streaming |
o4-mini | 128k tokens | Text, vision, tools, streaming |
Google
| Model | Context | Capabilities |
|---|---|---|
gemini-2.5-pro | 1M tokens | Text, vision, tools, structured output, streaming |
gemini-2.5-flash | 1M tokens | Text, vision, tools, structured output, streaming |
gemini-2.0-flash | 1M tokens | Text, vision, tools, structured output, streaming |
HTTP API
Every endpoint requires authentication (Authorization: Bearer <token>).
GET /ai/providers
Returns the available providers (with configured credentials).
{
"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.
{
"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:
{
"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:
{
"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
| Error | Cause |
|---|---|
404 | Provider not registered or without credentials |
400 | Invalid request or rejected by content policy |
429 + AI_PROVIDER_RATE_LIMITED | Provider/OpenRouter rate limit (different from governance) |
429 + AI_RATE_LIMIT_EXCEEDED | Governance anti-abuse rate limit |
500 | Internal provider error or authentication failure |
Asynchronous calls (Jobs)
If you do not want to block the HTTP response, use RunAIRequestJob:
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:
| Event | When it is emitted | Payload |
|---|---|---|
ai.request-completed | Successful generation | provider, model, inputTokens, outputTokens, durationMs |
ai.governed-usage-recorded | After a successful governed generate | usage metadata (classification, saldoImpact, …) — no prompts |
ai.overage-saldo-credited | After a balance top-up | amountMinorUnits, saldoMinorUnitsAfter, paymentReference |
ai.request-failed | Generation error | provider, 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:
# 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
- Add the identifier to the
AIProviderenum insrc/api/ai/constants/ai-provider.enum.ts - Create
src/api/ai/providers/<name>/<name>.provider.tsimplementingIAIProvider - Document the API key environment variable
- Register the provider in
src/api/ai/ai.module.tsinside theAIProviderRegistryfactory - Add model definitions in
src/api/ai/models/<name>.models.ts - 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/action | Internal API → SPA client | Internal Nimo: serviceKey → handler | Risk, scope, effective permission, entitlement and confirmation | Owning tests |
|---|---|---|---|---|
| List and select a project | GET /app-projects → listProjects | app-projects.list → ApplicationEnvironmentsService.listProjects | Read, tenant; OWNER/ADMIN; ai_assistants; no confirmation | Nimo: 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 environments | POST /app-projects → createProject | app-projects.create → ApplicationEnvironmentsService.createProject | Write, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation | Nimo: application-projects-assistant-skill.handler.spec.ts; catalogue: assistant-capability.registry.spec.ts; API/SPA: service and page tests |
| Read environments | GET /app-projects/:id/environments → listEnvironments | app-projects.environments.list → ApplicationEnvironmentsService.listEnvironments | Read, tenant; effective OWNER/ADMIN; ai_assistants; no confirmation | Handler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts |
| Create an immutable release | POST /app-projects/:id/releases → createRelease | app-projects.releases.create → ApplicationEnvironmentsService.createRelease | Write, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation. Creating a release neither builds nor deploys | Handler 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 → buildReleaseArtifact | app-projects.artifacts.build → internal projects handler | Write, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation | application-projects-assistant-skill.handler.spec.ts; deployments service |
| Read a release artifact (no separate form) | GET /app-projects/:projectId/releases/:releaseId/artifact → getReleaseArtifact | app-projects.artifacts.get → internal projects handler | Read, tenant; effective OWNER/ADMIN; ai_assistants; no confirmation | Handler and catalogue; deployments service tests |
| Read per-environment connections | GET /app-projects/:projectId/environments/:environmentId/connections → getConnections | app-projects.connections.get → ApplicationEnvironmentsService.getConnections | Read, tenant; effective OWNER/ADMIN; ai_assistants; no confirmation. Returns references/diagnostics only, never credentials | Handler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts |
| Save environment connections | PUT /app-projects/:projectId/environments/:environmentId/connections → updateConnections | app-projects.connections.update → ApplicationEnvironmentsService.updateConnections | Write, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation. Preview accepts no productive references | Handler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts |
| Start a durable deployment | POST /app-operations → createOperation | app-projects.operations.create → AppOperationsService.create | Write, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation. Acceptance does not equal deployment success | Handler, catalogue and tenant-assistant-chat.service.spec.ts; app-operations.service.spec.ts; app-projects.page.spec.ts |
| Read operation state | GET /app-operations/:id → getOperation | app-projects.operations.get → AppOperationsService.get | Read, tenant; effective OWNER/ADMIN; ai_assistants; no confirmation | Handler and catalogue; app-operations.service.spec.ts; app-projects.page.spec.ts |
| Cancel a pending deployment | POST /app-operations/:id/cancel → cancelOperation | app-projects.operations.cancel → AppOperationsService.cancel | Destructive, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation | Handler, catalogue and tenant-assistant-chat.service.spec.ts; app-operations.service.spec.ts; app-projects.page.spec.ts |
| List runtime origins | GET /app-projects/:projectId/environments/:environmentId/runtime-origins → listRuntimeOrigins | app-projects.runtime-origins.list → internal projects handler | Read, tenant; effective OWNER/ADMIN; ai_assistants; no confirmation | Handler and catalogue; runtime-origin.spec.ts; SPA page |
| Register a runtime origin | POST /app-projects/:projectId/environments/:environmentId/runtime-origins → createRuntimeOrigin | app-projects.runtime-origins.register → internal projects handler | Write, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation | Handler and catalogue; runtime-origin.spec.ts; app-projects.page.spec.ts |
| Retire a runtime origin | DELETE /app-projects/:projectId/environments/:environmentId/runtime-origins/:originId → retireRuntimeOrigin | app-projects.runtime-origins.retire → internal projects handler | Destructive, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation | Handler and catalogue; runtime-origin.spec.ts; app-projects.page.spec.ts |
| Issue a scoped runtime session | POST /app-projects/:projectId/environments/:environmentId/runtime-sessions → createRuntimeSession | app-projects.runtime-sessions.issue → internal projects handler | Write, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation | Handler and catalogue; application-environments.service.spec.ts; app-projects.page.spec.ts |
| Revoke your own runtime session | DELETE /app-projects/runtime-sessions/:id → revokeRuntimeSession | app-projects.runtime-sessions.revoke → internal projects handler | Destructive, tenant; OWNER/ADMIN; ai_assistants; explicit confirmation | Handler 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.tsre-exportspathsfromgenerated/openapi.ts. The contract contains 12 internal/app-projectsand/app-operationsroutes; additionally, the/ai/skillsand/ai/assistantsschemas includeapp-projects.*literals inserviceKey. 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-dslkeeps 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.tskeeps a manualNIMOBASE_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.