Release v0.16.1 · ExtensityAI/symbolicai

SymbolicAI v0.16.1 – Release Notes

🆕 Added Developer Value

Native Python Types in Contracts:
The @contract decorator and contract system now fully support native Python types (e.g., str, int, list[int], dict[str, int], Optional[...], Union[...]) as inputs and outputs for pre, act, post, and forward methods.
- Automatic Model Wrapping:
  These types are automatically wrapped/unwrapped into internal LLMDataModel classes with a single value field for validation, reducing verbosity and enabling more concise contracts.
- Hybrid Contracts:
  Seamless mixing of LLMDataModel and native Python/typing types is now possible (e.g., LLMDataModel input and primitive list output).

Gracious Degradation (graceful=True):
Graceful mode suppresses exceptions and, if enabled, skips the final output type check. This allows flexible fallback behaviors in forward and is particularly useful for advanced error-handling scenarios.
Improved Exception Handling Flow:
All contract step errors are now consistently captured in self.contract_exception. Developers may choose to propagate these or handle as needed in their forward logic.

Comprehensive Contract Flow Diagram:
An PNG flowchart visualizing contract execution steps has been added to the docs (assets/images/contract_flow.png and docs/source/FEATURES/contracts.md) to aid developer understanding.
Expanded Documentation:
Updated the contracts.md with clear examples, explanation of contract result/exception/fallback handling, and dynamic type annotation details.

llama.cpp Compatibility Note:
Included tested commit and build setup references for users in the local engine documentation, increasing reproducibility.

Centralized Dynamic Model Creation:
Introduced build_dynamic_llm_datamodel using Pydantic’s create_model with LRU caching for efficient, reliable dynamic class creation.
Signature and Dynamic Model Checks:
Refactored contract internals (strategy.py) to automatically infer and enforce input/output type models—significantly reducing boilerplate for simple contracts.

Smarter Retry Defaults:
Lowered default retry delays (faster backoff, less jitter) for validation/remedy functions, resulting in speedier remediation attempts.
Improved Pause/Backoff Logic:
Retry backoff and jitter are now better parameterized per-attempt.

Consistent use of logger.exception across contract paths for full stack traces and easier debugging.

Type Coercion Oddities:
Fixed subtle type and identity propagation/validation bugs for contracts mixing LLMDataModels and primitives.
Output Model Handling:
Final output unwrapping and type error propagation behaves correctly in all graceful and non-graceful scenarios.
Constructor/Server Behavior:
Dual writes for SYMAI server configuration ensure consistency regardless of startup location.
Splash Screen Formatting:
UI cleanup in interactive menu for a more polished user experience.

Extensive Unit Testing for Dynamic Types:
Added robust tests for all dynamic annotation scenarios:
- str, int, list, dict, Optional, Union, and nested types
- Hybrid contracts mixing LLMDataModels and primitives
- Graceful vs. strict output checking
- Remedy behavior and error propagation
Multiple Test Cases Improved:
Expanded/cleaned up contract tests for state, error path, edge cases, and fallback handling.
Visualization Flow Invariant:
Flowchart confirms the correctness of the new, more generic contract machinery.

For Developers of Contract-Decorated Classes:
- You may now use standard Python/typing signatures directly anywhere in your contract methods!
- Older explicit LLMDataModel-based code remains fully compatible.
For Library Extenders:
- Use build_dynamic_llm_datamodel() to support arbitrary Python/typing types in new symbolic contract-based features.

Full Changelog: v0.15.1...v0.16.1