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

v0.9.1

Release Notes for Version 0.9.1

New Features

• Dynamic Engine Switching: Introduced DynamicEngine context manager which allows dynamically switching neurosymbolic engine models. This improves flexibility in using different models within the same context.
• Engine Mapping for Neurosymbolic Engines: Added a new ENGINE_MAPPING that maps supported model names to their respective engine classes for easier integration and management.
• Split Model Support: The models for Anthropic, DeepSeek, and OpenAI have been delineated into specific categories (Chat, Reasoning, Completion, and Embedding models) for better clarity and management.

Improvements

• Config Management Enhancement: Replaced multiple instances of self.config = SYMAI_CONFIG with self.config = deepcopy(SYMAI_CONFIG) to ensure configurations are isolated for each engine instance.
• Enhanced Logging and Error Handling: Improved logging details including stack traces for better debugging and error tracking within the _process_query and _process_query_single functions.
• Functionality Testing and Validation: Added several new test cases, especially focusing on testing dynamic engine switching and fallback query executions to ensure robustness.

Bug Fixes

• Token Computation Correction: Fixed the incorrect computation of artifacts in the GPTXChatEngine and GPTXReasoningEngine classes.
• Payload Adjustments: Adjustments on payload preparation for the GPTXChatEngine especially for chatgpt-4o-latest, ensuring certain fields are correctly omitted.
• Argument Preparation Bug Fixes: Fixed issues in _prepare_argument to properly handle raw input and enhance preprocessing capabilities.
• Self Prompt Improvements: Improved self-prompting logic in Symbol to ensure correct responses and validation.
• Signature and Type Annotations: Updates on the usage of inspect.Signature methods for resolving return annotations, ensuring compatibility with Python's typing system.

Others

• Refactoring & Cleanup: Conducted significant code refactoring and cleanup, including reorganizing the test suite and renaming test files for better maintainability and clarity.
• Warning & Constraint Handling: Adjusted warnings and constraint handling to improve message clarity for developers working with the library.

Full Changelog: v0.9.0...v0.9.1

v0.9.0

These changes expand SymbolicAI's capabilities with next-generation models from OpenAI, DeepSeek, and Anthropic.

Major Changes

New Models Support

• Added support for Claude 3.7 Sonnet with extended thinking capabilities
• Added support for OpenAI's o1 and o3-mini models with reasoning mode
• Added DeepSeek Reasoner model support

New Reasoning Features

• Implemented structured reasoning support across multiple LLM providers:
  • Claude 3.7 with extended thinking (up to 64k tokens for thinking)
  • OpenAI's o1/o3 models with reasoning mode
  • DeepSeek Reasoner with explicit reasoning capabilities

Engine Improvements

• Refactored Anthropic Claude engines for improved response handling
• Added support for streaming responses with Claude models
• Improved token counting and context management
• Enhanced tool use support across different model providers

Architecture Changes

• Modularized request payload preparation with cleaner code structure
• Improved error handling for API interactions
• Added consistent handling for reasoning/thinking outputs

Developer Experience

• Better handling of max_tokens vs max_completion_tokens for OpenAI models
• More consistent self-prompting behavior
• Enhanced JSON response format support

Dependencies

• Added loguru (≥0.7.3) for improved logging
• Added aiohttp (≥3.11.13) for async HTTP requests

Version Update

• Increased version from 0.8.0 to 0.9.0

Full Changelog: v0.8.0...v0.9.0