Versioning and compatibility

The SDK follows semantic versioning.

• Patch releases fix bugs and improve internal behavior without changing documented use.
• Minor releases add backward-compatible capabilities, types, options, resources, and response fields.
• Major releases are reserved for unavoidable breaking changes and include migration guidance.

Stable boundaries

The following are public compatibility boundaries:

• package root exports
• Nirmos constructor options
• product namespace names
• documented resource methods
• documented request properties
• normalized response properties
• error class inheritance and documented fields

HTTP wire formats, internal transport classes, cache implementation, provider payloads, and parser details are not public API. Nirmos can improve them without requiring application changes.

Extensible strings

Model identifiers, routing strategies, finish reasons, image options, and stream event names can expand as the platform changes. Their TypeScript types preserve known autocomplete values while allowing future strings.

Do not write exhaustive code that crashes on an unknown provider, finish reason, or stream event:

switch (event.type) {
  case "content.delta":
    consume(event.delta);
    break;
  default:
    // Ignore events this application does not use.
    break;
}

Additive response fields

Applications should read documented fields they need and ignore additional fields. Minor releases may add optional metadata or new event types.

Deprecation policy

When a public API must be replaced:

1. A backward-compatible replacement is introduced.
2. The old API is marked deprecated in types and documentation.
3. Both remain available through a documented migration window.
4. Removal occurs only in a major release.

Security defects or upstream platform shutdowns may require faster action. Nirmos will document those exceptions clearly.

Pinning

Applications can use normal semver ranges:

{
  "dependencies": {
    "@nirmos/sdk": "^1.0.0"
  }
}

Use a lockfile and automated dependency updates. Test SDK upgrades with representative chat, streaming, prompt, embedding, and image requests before production rollout.