SDK best practices

Reuse one client

Create one Nirmos instance per API key and API origin. Reuse preserves prompt cache value and gives all product calls consistent configuration.

Keep secrets server-side

Never place API keys in browser or mobile bundles. Route user requests through a trusted application server with its own authorization checks.

Prefer active prompts for product behavior

Reference the active prompt version for normal application traffic:

prompt: { id: "support-reply", version: "active", variables }

Pin a numeric version for evaluations, replays, audits, and regulated workflows.

Treat prompt activation as a release

Test new prompt versions with representative data before activation. Record a useful commit message. Monitor quality, errors, token use, and latency after release.

Validate model output

Provider-side JSON or schema controls reduce malformed output but do not replace application validation. Parse and validate before writing to databases, calling tools, or making consequential decisions.

Set time budgets

Set a client timeout, then choose narrower per-operation limits where user latency matters. Propagate AbortSignal from inbound requests and job cancellation.

Retry deliberately

Let the SDK retry safe prompt retrievals. Use workload-aware queues and retry budgets for generation operations. Do not blindly retry non-idempotent requests after network uncertainty.

Log normalized metadata

At minimum, log:

• requestId
• traceId
• model
• provider
• latency
• input and output tokens
• application feature or operation name

Do not log API keys, private prompt variables, full user messages, or generated content unless your data policy explicitly permits it.

Handle unknown additive values

Providers, models, finish reasons, and stream events evolve. Ignore values your application does not use instead of failing closed on every new string.

Control prompt cache freshness

Use the default cache for most applications. Choose a shorter TTL for rapid prompt rollouts and a longer TTL for high-throughput, low-change workloads. Use cache: "reload" for administrative verification, not on every request.

Test the full path

Before release, test:

• one non-streaming chat response
• a fragmented stream and final completion
• tool calls or structured output if used
• prompt cache hit and forced reload
• missing prompt variables
• embedding dimensions and ordering
• image URL or base64 handling
• authentication, rate-limit, timeout, and server error paths

Keep contract tests at the application boundary. Avoid depending on undocumented HTTP payload details hidden by the SDK.