v0.13.0

SymbolicAI v0.13.0 Release Notes

This release introduces a major overhaul of the core API, focusing on clarity, power, and developer experience. We've simplified how you interact with semantic operations, massively improved our documentation, and added powerful new features.

✨ Highlights

• New Primitives API: We've introduced a more intuitive way to work with semantic operations. The old only_nesy=True flag is now deprecated. You can now enable semantic behavior on a Symbol either at creation time with semantic=True or on-the-fly using the .sem property. For standard Python behavior, use the .syn property or simply use the symbol as is.

    # Old way (deprecated)
    # Symbol('Hello my enemy', only_nesy=True) - 'enemy' + 'friend'

    # New way
    Symbol('Hello my enemy', semantic=True) - 'enemy' + 'friend'
    # Or on-the-fly
    Symbol('Hello my enemy').sem - 'enemy' + 'friend'

• Massive Documentation Overhaul: We've rewritten our README.md from the ground up to be more intuitive. It now features a comprehensive table of all supported primitives, detailing their syntactic and semantic behavior. We've also added a brand new, in-depth Primitives Cheat-Sheet with runnable examples for every operation.

• New map Primitive: A powerful new .map() primitive has been added for semantic mapping over iterables. You can now apply natural language instructions to transform elements in lists, tuples, sets, and dictionaries, while preserving the container type.

    # Convert fruits to vegetables, leave other items unchanged
    sym_list = Symbol(['apple', 'banana', 'cat', 'dog'])
    result = sym_list.map('convert all fruits to vegetables')
    # Expected output might be: ['carrot', 'broccoli', 'cat', 'dog']

🚀 New Features & Enhancements

• Semantic startswith/endswith: The .startswith() and .endswith() methods can now be used in semantic mode to check for conceptual prefixes or suffixes (e.g., Symbol("The apple fell", semantic=True).startswith("fruit") would return True).
• Improved Clustering: The .cluster() primitive now uses the more robust HDBSCAN algorithm (from scikit-learn) and allows you to pass custom clustering parameters as kwargs.
• Enhanced Multiprocessing: The @parallel decorator is now significantly more efficient, reusing multiprocessing pools instead of creating new ones for each call. This leads to better performance and resource management for parallel tasks.
• Flexible Search Engine: The GPTXSearchEngine can now be initialized with a specific API key and model, making it easier to use in diverse configurations.
• Generation Control: Many decorators (summarize, equals, correct, etc.) now accept a stop parameter for more precise control over text generation.

🐛 Bug Fixes & Improvements

• Improved Prompts: Prompts for logical and symbolic expression evaluation have been completely overhauled with more intuitive examples, leading to better and more reliable results.
• Robust Data Parsing: The internal ASTPostProcessor is now more powerful and can recursively parse nested data structures, improving the reliability of operations that return complex objects like lists of dictionaries.
• Updated Gemini Models: Updated supported Google model names to the latest stable versions (e.g., gemini-2.5-pro).
• Code Correction: The .correct() method now requires an exception object, allowing it to provide much more context-aware code corrections.

⚠️ Breaking Changes & Deprecations

• API Change for Semantic Operations: The only_nesy and iterate_nesy parameters in the Symbol constructor are deprecated. Please use semantic=True or the .sem property to enable neuro-symbolic behavior.
• Class Rename: SymbolArithmeticPrimitives has been renamed to SymbolOperatorPrimitives to better reflect its scope.

📚 Documentation

• New Example Notebooks: We've added new notebooks for Primitives and Contracts in the examples/ directory, providing interactive, hands-on tutorials.
• Documentation Cleanup: Old documentation pages for engines and some features have been marked as outdated, with pointers to our more current and comprehensive DeepWiki page.
• Legacy Notebooks: Older notebooks have been moved to a legacy/ directory to signify they may not reflect the latest API changes.
• Running Tests: The README.md now includes instructions on how to run the test suite locally.