AI in Noderyx — Noderyx Documentation

01

Enable a provider

AI is disabled until you opt in. The client is dependency-free, talks to OpenAI's Responses API or Anthropic's Messages API, and keeps credentials on the server.

.env

AI_ENABLED=true
AI_PROVIDER=openai
OPENAI_API_KEY=your_server_key
OPENAI_MODEL=gpt-5.6-sol

NOTE

Restart the server after changing .env. AI_PROVIDER=claude is accepted as an alias for anthropic.

02

…or Claude

The Anthropic block reads its own credentials and defaults. Thinking tokens count against the output budget, so give Claude more room than an OpenAI-tuned ceiling.

.env

AI_ENABLED=true
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=your_server_key
ANTHROPIC_MODEL=claude-opus-5
AI_MAX_OUTPUT_TOKENS=4000

03

Shared environment reference

These variables apply whichever provider you choose.

AI_ENABLED false by default. The explicit feature switch.

AI_PROVIDER openai or anthropic (claude).

AI_REASONING_EFFORT none, low, medium, high, xhigh, or max.

AI_VERBOSITY low, medium, or high.

AI_MAX_OUTPUT_TOKENS Output ceiling for cost and latency control.

AI_INPUT_LIMIT Maximum prompt characters accepted by the client.

AI_TIMEOUT_MS Provider request timeout.

AI_INSTRUCTIONS Application-wide behavior instructions.

AI_STORE Whether the provider may retain response state. OpenAI only.

04

Provider credentials

Only the block matching AI_PROVIDER is read, so both can live in .env.example without ambiguity.

OPENAI_API_KEY / OPENAI_MODEL Secret key and model. Default gpt-5.6-sol.

OPENAI_BASE_URL Override for compatible gateways.

ANTHROPIC_API_KEY / ANTHROPIC_MODEL Secret key and model. Default claude-opus-5.

ANTHROPIC_BASE_URL API base URL.

ANTHROPIC_FALLBACKS Let Anthropic answer a declined request on a fallback model.

05

Choosing a model

Pick for the job, not for the benchmark. Model ids are complete as written—never append a date suffix.

gpt-5.6-sol — the OpenAI flagship default.
gpt-5.6-terra — a more balanced cost/intelligence tradeoff.
gpt-5.6-luna — high-volume, cost-sensitive work.
claude-opus-5 — the Claude default; strongest for coding and long agentic work.
claude-sonnet-5 — near-Opus quality at lower cost.
claude-haiku-4-5 — high-volume, latency-sensitive work.

06

Generate inside a route

Resolve the registered service and call generate() with feature-specific instructions. Everything stays on the server.

server.js

app.post("/api/summarize", async ({ body, service, json }) => {
  const result = await service("ai").generate(body.text, {
    instructions: "Summarize this text in three plain-language bullets.",
    reasoningEffort: "low",
    verbosity: "low"
  });
  return json({ summary: result.text, responseId: result.id });
});

NOTE

In a controller, use this.service("ai").

07

Continuing a conversation

OpenAI can continue from a previous response id. Claude is stateless, so pass the earlier turns as history instead.

JAVASCRIPT

// OpenAI
await service("ai").generate("And in one sentence?", {
  previousResponseId: first.id
});

// Claude
await service("ai").generate("And in one sentence?", {
  history: [
    { role: "user", content: "Explain event loops." },
    { role: "assistant", content: first.text }
  ]
});

NOTE

previousResponseId throws an unsupported_option error on Claude—use history there.

08

Provider differences worth knowing

The client hides the transport, not the behavior. These five differences explain most surprises.

Thinking counts against the output budget on Claude—an OpenAI-tuned ceiling can truncate an answer mid-sentence.
AI_REASONING_EFFORT maps to Claude's effort levels; none disables thinking entirely.
AI_VERBOSITY becomes a system instruction on Claude, which has no verbosity parameter.
AI_STORE is ignored on Claude—there is no server-side response state to retain.
safetyIdentifier is sent as safety_identifier on OpenAI and metadata.user_id on Claude.

09

Handling refusals and errors

A declined request raises AIError with code refusal. With ANTHROPIC_FALLBACKS on, Anthropic first retries on a fallback model, so a refusal reaching your code means the whole chain declined.

server.js

import { AIError } from "noderyx-framework";

try {
  const result = await service("ai").generate(text);
  return json({ text: result.text });
} catch (error) {
  if (error instanceof AIError && error.code === "refusal") {
    return abort(422, "That request could not be answered");
  }
  throw error;
}

10

Build responsible features

The cost of an AI feature is not only tokens. These are the habits that keep one from becoming an incident.

Keep the API key on the server, and rotate it immediately if it is ever exposed.
Authenticate AI routes and add a tighter per-user rate limit for expensive actions.
Validate input, cap input and output sizes, and set timeouts.
Tell users when content is AI-generated and give them a way to correct it.
Require confirmation before AI performs destructive or external actions.
Pass a stable pseudonymous safetyIdentifier for signed-in users, never a direct personal identifier.

11

Testing

Use a mocked fetch. Tests should never call a live provider—they would be slow, non-deterministic, and expensive.

TERMINAL

npm test

NOTE

Never send provider credentials to the browser, and never put a key in a view or a client bundle.