v0.13.1

This is a patch release focused on refining the documentation to make SymbolicAI easier to use and extend.

✨ New & Improved

• Clearer Symbol Concepts: The README and documentation have been significantly improved to better explain the core concept of Syntactic (literal) vs. Semantic (neuro-symbolic) modes for Symbol objects. This should make it easier for new users to get started.
• Updated Custom Engine Guide: The guide for creating a custom engine has been updated to use the more modern GPTXChatEngine, reflecting current best practices.

🔧 Fixes & Changes

• Updated Search Engine Model: The default model for the Perplexity search engine (SEARCH_ENGINE_MODEL) has been updated from llama-3.1-sonar-small-128k-online to sonar.

📖 Documentation

• The main README.md has been rewritten to be more concise and welcoming, with better examples for Symbol and Contract.
• The large table of primitives in the README has been condensed, linking to the full documentation for a cleaner first impression.

Full Changelog: v0.13.0...v0.13.1

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.

v0.12.1

Release Notes - SymbolicAI v0.12.1

🐛 Bug Fixes

• Search Engine Model Override: Fixed OpenAI search engine to properly respect model parameter overrides, ensuring MetadataTracker works correctly
• Contract Validation Logic: Improved contract method validation logic for better error handling in edge cases

🔧 Maintenance & Infrastructure

• Google Gemini Models: Updated supported Gemini model identifiers to use prefix matching (gemini-2.5-pro-preview-, gemini-2.5-flash-preview-) for better compatibility with latest model snapshots
• Interface Naming: Added consistent name attribute initialization across all extended interfaces (25+ interfaces including blip_2, clip, dall_e, flux, python, terminal, etc.) for improved debugging and introspection

---

Full Changelog: v0.12.0...v0.12.1

v0.12.0

SymbolicAI v0.12.0 Release Notes

🎉 Major New Features

Google Gemini Support

• NEW: Added full support for Google Gemini models (gemini-2.5-pro-preview-05-06, gemini-2.5-flash-preview-05-20)
• NEW: Gemini reasoning engine with thinking trace support
• NEW: Multi-modal support for Gemini (images, videos, audio, documents)
• NEW: Token counting and cost estimation for Gemini models

OpenAI Search Engine

• NEW: Native OpenAI search capabilities with citation support
• NEW: Interface('openai_search') for web search with AI responses
• NEW: Configurable search context size and user location parameters
• NEW: Automatic citation extraction and formatting

Enhanced Function/Tool Calling

• IMPROVED: Universal function calling support across OpenAI, Claude, and Gemini
• NEW: Consistent metadata format for function calls across all engines
• NEW: Better error handling and multiple tool call detection

🔧 Significant Improvements

Metadata Tracking & Cost Estimation

• NEW: MetadataTracker component for detailed usage tracking
• NEW: RuntimeInfo utility for cost estimation and analytics
• NEW: Per-engine token counting and API call tracking
• IMPROVED: Better metadata aggregation across multiple engine calls

Engine Enhancements

• IMPROVED: Enhanced Claude reasoning engine with better thinking trace support
• IMPROVED: Updated model support for Claude 4.0 and Sonnet 4.0
• IMPROVED: Better streaming support across all engines
• IMPROVED: Consistent error handling with CustomUserWarning

Vision & Media Processing

• IMPROVED: Enhanced image processing across all vision-capable models
• NEW: Frame extraction support for video content
• IMPROVED: Better handling of media patterns in prompts

🐛 Bug Fixes

Core Fixes

• FIXED: Token truncation issues across different engines
• FIXED: Raw input processing for all engine types
• FIXED: Response format handling for JSON outputs
• FIXED: Self-prompting functionality across engines

Engine-Specific Fixes

• FIXED: Claude streaming response collection
• FIXED: OpenAI tool call argument parsing
• FIXED: Deepseek response format handling
• FIXED: Vision pattern removal in prompts

🔄 Breaking Changes

Deprecated Features

• REMOVED: Legacy experimental engines (Bard wrapper, GPT fine-tuner, etc.)
• REMOVED: Old completion-based OpenAI engine
• CHANGED: Standardized engine initialization patterns

API Changes

• CHANGED: Thinking configuration format for Claude (simplified structure)
• CHANGED: Consistent error handling across all engines
• CHANGED: Engine name property now required for all engines

📚 Documentation & Testing

Documentation Updates

• UPDATED: Comprehensive engine documentation with examples
• NEW: Cost estimation and metadata tracking examples
• UPDATED: Search engine configuration guides
• NEW: Multi-modal content processing examples

Testing Improvements

• NEW: Mandatory test markers for critical functionality
• IMPROVED: Engine-specific test coverage
• NEW: Function calling tests across all supported engines
• IMPROVED: Vision processing test coverage

🔧 Developer Experience

Configuration

• NEW: Simplified engine configuration patterns
• IMPROVED: Better error messages for missing API keys
• NEW: Engine-specific timeout and retry parameters

Utilities

• NEW: RuntimeInfo for usage analytics
• NEW: Enhanced prompt registry with custom delimiters
• IMPROVED: Better file handling and media processing utilities

📋 Dependencies

• ADDED: google-genai>=1.16.1 for Gemini support
• UPDATED: Various dependency versions for compatibility

🚀 Performance

• IMPROVED: Better token counting accuracy where supported
• IMPROVED: Optimized streaming response handling
• IMPROVED: Enhanced memory usage for large media files

---

Note: This release focuses heavily on expanding AI model support and improving the developer experience. The most accurate documentation is always the code itself - look for the mandatory test markers for guaranteed functionality.

Upgrade Notes:

• Update your configuration for any Claude thinking configurations
• Review engine-specific documentation for new capabilities
• Consider migrating to the new metadata tracking system for cost monitoring

Full Changelog: v0.11.0...v0.12.0

v0.11.0

Release Notes for v0.11.0

✨ New Features

• Contract Performance Statistics Tracking

  • Added a contract_perf_stats method to contract-decorated classes, which tracks and reports granular timing statistics (mean, std, min, max, percentage) for each contract operation: input validation, act execution, output validation, forward execution, total execution, and "overhead" (untracked contract time).
  • Unit tests exercise and validate this detailed performance statistics capability.

• Improved Type and Semantic Validation

  • The contract mechanism now leverages a single TypeValidationFunction to handle both type and semantic validation, streamlining error handling and remedy functions.
  • The previously separate SemanticValidationFunction is now unified, reducing code duplication and making semantic and type checks more consistent.

• Rich Field Descriptions for LLM Guidance

  • Strongly encourage and enforce the use of descriptive Field(description="...") for all LLMDataModel attributes. These descriptions are directly used to improve LLM prompting, validation, error messages, and data generation.
  • Updated documentation with clearer guidance and rationale on crafting informative descriptions and prompts.

🐛 Bug Fixes & Refactorings

• Refined Contract Input and Output Handling

  • The contract decorator now strictly enforces keyword arguments (no positional input) and validates the input type up-front.
  • Input object identity and propagation through the contract lifecycle are preserved and tested (no accidental re-instantiation).

• Improved Error Reporting & Context

  • Type and semantic validation errors are now accumulated and reported with greater clarity when remedy retries are enabled.
  • Error accumulation context is correctly passed to remedies, improving developer diagnostics.

• Act Method Refactoring

  • The act method inside contracts is validated for correct signature and type annotations.
  • If no act is defined, the input is propagated unchanged, simplifying state-modifying contracts.

• Output Type Checks

  • Output from contracts is checked against expected type annotation, with informative error messages if mismatches are detected.

• Contract Performance Test Coverage

  • New and expanded tests for:
    • End-to-end contract flows with state-modifying act methods.
    • Verification that the same input object is propagated and contract state changes are handled as expected.
    • Tracking and assertion of contract performance statistics.

• Codebase Cleanup

  • Removed unused imports (e.g., SemanticValidationError class and related references).
  • Simplified logic around data model registration and remedy handling.

📘 Documentation

• Expanded and clarified the documentation for contracts, field descriptions, prompt design, and the role of pre/post validation.
• Added best practices for driving LLMs with meaningful validation and semantic checks.
• Highlighted the separation of static contract prompts and dynamic input state.

Full Changelog: v0.10.0...v0.11.0

v0.10.0

SymbolicAI Release Notes (v0.10.0)

🚀 New Features

1. Contracts System & Design by Contract (DbC) Support

• Decorator-Based Contracts: Introduction of the @contract class decorator (inspired by Design by Contract principles) for Expression subclasses.
• Pre-conditions, Post-conditions, and Intermediate Actions: Classes can now define pre, act, and post methods to enforce input validation, intermediate processing, and output validation — all with optional LLM-based remedies.
• Rich Input and Output Modeling: Mandatory use of LLMDataModel (Pydantic-based) for all contract-associated data, providing structured validation and schema-driven prompting.
• LLM-Guided Self-Remediation: If enabled, contract failures in pre-conditions or post-conditions can be self-corrected by LLMs using descriptive error messages as corrective prompts.
• Enhanced Composability and Reliability: Contracts make AI components more robust and predictable, aiding in both integration and maintenance.
• Clear Fallback Behavior: Even when contracts fail, original forward logic executes with a clear success indicator and contract result for user-defined fallback strategies.

2. Act Method Support

• Contracts can include an optional act method for intermediate transformations between input validation and output production, with strict signature/type checking.

3. Enhanced Logging & Verbose Mode

• Verbose mode uses rich panels for visually appealing and structured logging of contract-related operations, error panels, schemas, and dynamic prompts.

4. Error Accumulation Option

• New accumulate_errors switch for contract decorators allows error messages to be accumulated and shown to the model across multiple remedy attempts to aid LLM self-correction.

5. Developer Tooling Improvements

• contract_perf_stats() provides per-call timing information to help optimize contract execution and debugging.

6. Extensive Documentation

• New FEATURES/contracts.md: Comprehensive guide on contracts, their parameters, execution flow, developer patterns, and practical examples.

7. Detailed Testing

• Addition of tests/contract/test_contract.py with thorough coverage for contract flow, act method, fallback logic, signature checks, contract state management, and various edge cases.

---

🐞 Bug Fixes & Minor Improvements

• input_type_validation error message is now more detailed and informative.
• Contract decorator and remedies now properly distinguish between positional and keyword arguments, preventing ambiguity.
• Output type validation strictly checks for correct types, preventing silent contract malfunctions.
• Original forward argument passing has been improved to ensure correct input after contract handling.
• Improved clarity in docstrings, method comments, and public documentation for easier onboarding.
• Numerous logging messages refined for clarity and utility.

---

📚 Documentation

• docs/source/FEATURES/contracts.md: In-depth, example-driven guide to symbolic contracts, covering all decorator parameters, remedy workflow, fallback/forward execution, and best practices.
• SUMMARY.md is updated to include the new Contracts section in documentation navigation.

---

Full Changelog: v0.9.5...v0.10.0

v0.9.5

Release Notes – v0.9.5

Bug Fixes & Improvements

• Packaging Improvements:

  • Updated pyproject.toml to change the [tool.setuptools.packages.find] include pattern from ["symai"] to ["symai*"]. This fixed a nasty import bug.
    This ensures that all subpackages (e.g., symai.submodule) are now correctly included during package builds and distributions.

• Testing Configuration:

  • Adjusted pytest.ini to deselect the specific test tests/engines/neurosymbolic/test_nesy_engine.py::test_token_truncator, likely to address a test flakiness or to temporarily ignore a known issue.
  • Minor cleanup to remove an unnecessary trailing line.

• General Maintenance:

  • Version bumped from 0.9.4 to 0.9.5 in symai/__init__.py to reflect the new release.
  • Updated .gitignore to ignore .bash_history files, helping prevent accidental commits of shell history.

---

Full Changelog: v0.9.4...v0.9.5

v0.9.4

Release Notes for v0.9.4

---

🔧 Improvements

• Updated Documentation Link
  • Changed the main documentation badge and link in the README from ReadTheDocs to the new GitBook documentation.
  • Added new Twitter badge for @futurisold to the README alongside existing social and contribution links.

🐛 Bug Fixes

• No direct bug fixes were indicated in this diff.

🔢 Version Update

• Bumped the version in symai/__init__.py from 0.9.3 to 0.9.4.

---

Full Changelog: v0.9.3...v0.9.4

v0.9.3

Release Notes

Version 0.9.3

🆕 New Features

• Neuro-Symbolic Engine Documentation
  • Completely new, comprehensive documentation added for the "Neuro-Symbolic Engine" (docs/source/ENGINES/neurosymbolic_engine.md).
  • Covers usage patterns, backend differences, function/tool calls, JSON enforcement, thinking trace, vision input, token handling, preview mode, and more.
  • Highlights model-specific usage (OpenAI, Claude, Deepseek, llama.cpp, HuggingFace).
• Documentation Overhaul
  • Switched documentation system to GitBook structure:
    • New .gitbook.yaml configuration pointing to Markdown-based docs.
    • Added SUMMARY.md for navigation and topic overview.
  • Documentation hierarchy is now streamlined and modernized.
  • Reorganized Engines, Features, Tutorials, and Tools in clear sections.
• Enhanced Argument Support
  • Argument class in symai/core.py now always initializes return_metadata property, improving consistency and capability for backend engines to return extra metadata.

🐛 Bug Fixes

• Anthropic Claude Engine Fixes
  • Fixed empty prompt edge case: Ensures user prompt is non-empty ("N/A") to avoid Anthropic API errors.
  • Proper handling of JSON response format by stripping wrapping Markdown code fences (```json, ```
    `) so the output is pure JSON.
  • When "thinking trace" is enabled, metadata is correctly populated with the model's "thinking" output.
• DeepSeek Reasoning Engine Fixes
  • Now always returns answer content as the main output and thinking trace under metadata["thinking"], matching documented examples.

⚡ Other Improvements

• Docs Clean-Up
  • Removed all Sphinx-based files and REST/rst sources, including configuration files, API reference, and build artifacts. Old ReadTheDocs and Sphinx themes are now deprecated.
  • Updated all doc links and cross-references to work with the new Markdown- and GitBook-based structure.
• Documentation Content Improvements
  • More explicit explanations and structure in Features, Tools, and Tutorials (headings, options, and section hierarchies improved).
  • Outdated rst-formatted docs are removed, new Markdown-based docs are in place.

🔧 Internal/Infrastructure

• Incremented project version to 0.9.3.
• Set up for future multi-engine documentation and easier addition of new backends or features.
• Codebase now explicitly sets the SYMAI_VERSION = "0.9.3".

---

Full Changelog: v0.9.2...v0.9.3

v0.9.2

Release Notes: v0.9.2

---

✨ New Features

• Unified Drawing Interface

  • Added a new high-level drawing interface with two main options:
    • gpt_image: Unified wrapper for OpenAI image APIs (supports dall-e-2, dall-e-3, gpt-image-*). Exposes OpenAI’s full Images API, including advanced parameters (quality, style, moderation, background, output_compression, variations, edits—see updated docs).
    • flux: Simplified interface for Black Forest Labs’ Flux models via api.us1.bfl.ai.
  • Both interfaces now return a list of local PNG file paths for easy downstream consumption.
  • Documented all parameters and new interface usage for both engines.

• New Engines

  • Added symai.backend.engines.drawing.engine_gpt_image for OpenAI's latest Images API.
  • Deprecated/removed legacy engine_dall_e.py in favor of unified engine_gpt_image.py.

• Extended Interfaces

  • New public classes: symai.extended.interfaces.gpt_image and updated flux interface for consistency and enhanced discoverability.
  • Added comprehensive tests for drawing engines covering all models and modes (create, variation, edit).

---

🛠️ Improvements & Fixes

• Flux Engine

  • Now downloads result images as temporary local PNG files. Handles non-None payload.
  • Uses correct API endpoint (api.us1.bfl.ai).
  • Cleans up error handling, makes API parameters robust against None values.

• OpenAI Model Support

  • Added support for cutting-edge OpenAI models:
    • Chat/Vision: gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
    • Reasoning: o4-mini, o3
  • Updated max context/response tokens for new models (gpt-4.1* supports up to ~1M context, 32k response tokens).
  • Tiktoken fallback: If initialization fails or support is missing for a new OpenAI model, falls back to "o200k_base" encoding, shows a warning.

• OpenAI Mixin Enhancements

  • Refined token calculations and model support for new OpenAI and BFL models.
  • Ensured consistent handling of context/response tokens as new models are released.

---

📚 Documentation

• Overhauled docs/source/ENGINES/drawing_engine.md:
  • Clearly describes new unified drawing API, how to use models, available parameters, and best practices.
  • Includes ready-to-use code examples for both OpenAI and Flux pathways.

---

🧪 Testing

• Comprehensive pytest suite for drawing engines now included (tests/engines/drawing/test_drawing_engine.py).
• Tests gpt_image create, variation, edit; tests Flux for all supported models.
• Verifies correct output (generated images exist and are valid).

---

⚠️ Breaking/Behavioral Changes

• Legacy DALL·E Engine removed (engine_dall_e.py). Use gpt_image for all OpenAI image generation.
• All engine calls now return image file paths (as list), not just URLs.
• Some parameter names and behaviors have changed (see updated docs).

---

If you use programmatic image generation, especially OpenAI’s DALL·E or gpt-image models, please update your code and refer to the new documentation. The new design offers greater flexibility, future-proofing for new models and APIs, and consistent developer ergonomics.

---

Full Changelog: v0.9.1...v0.9.2