api-stability.md

API Stability and Deprecation Policy

This document defines ToolGlot's public API guarantees and deprecation framework.

Public API Surface

The following symbols are considered public and stable unless explicitly marked deprecated:

• ToolKit
• ToolDefinition
• ToolParameter
• ToolCall
• ToolResult
• ModelCapabilities
• capabilities()
• parse_tool_calls()

Deprecated compatibility aliases are public but scheduled for removal:

• parse_calls() (deprecated, remove in v0.3.0, use parse_tool_calls())

Anything not listed here (internal modules, helper functions, implementation details) may change without notice.

Stability Tiers

• Stable: Public API listed above; backward-compatible across minor releases.
• Beta: Explicitly documented as beta; may change with migration notes.
• Internal: Not part of the public contract.

Deprecation Process

When deprecating a public API:

1. Keep old behavior functional during the deprecation window.
2. Emit DeprecationWarning with:
   • deprecated symbol
   • replacement symbol (if available)
   • planned removal version
3. Add release note entry under "Deprecations".
4. Remove only after the minimum deprecation window is complete.

Minimum Deprecation Windows

• Patch release: no removals of public API
• Minor release: deprecations may be introduced; removals require at least one full minor release warning window
• Major release: removals allowed for previously deprecated APIs with migration guidance

CI Enforcement

• Deprecation paths must have tests asserting warnings are emitted.
• PRs introducing deprecations must include:
  • warning tests
  • docs updates in this file
  • release note entry in release template