Versioning and compatibility

The package is currently a pre-1.0 release (0.1.0). It uses semantic versions, but applications should review release notes closely while the public surface is still stabilizing.

• Patch releases fix bugs and improve internal behavior.
• Pre-1.0 minor releases can include public API changes.
• After a stable 1.0 release, major versions will identify breaking public API changes.

Documented surface

The following make up the current public SDK surface:

• 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, 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. Releases may add optional metadata or new event types.

Deprecation policy

When a public API must be replaced, release notes should identify the replacement and migration path. Do not assume a long deprecation window before 1.0.

Pinning

While the package is pre-1.0, pin the version deliberately:

{
  "dependencies": {
    "@nirmos/sdk": "0.1.0"
  }
}

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