v0.16.3

SymbolicAI v0.16.3 – Release Notes

• Fixed example generation in instruct_llm for user-defined models and non-value unions.
• Added test coverage for union and optional-union cases.

Full Changelog: v0.16.2...v0.16.3

v0.16.2

SymbolicAI 0.16.2 – Release Notes

Core / LLMDataModel
• Schema simplification now recognises
– dict/mapping fields via additionalProperties
– primitive alternatives inside anyOf/oneOf/union blocks
• Definitions list includes non-object union variants.
• Union handling:
– Heuristic chooses the simplest subtype for examples.
– instruct_llm emits one example per union alternative and wraps them in [[Example N]] blocks.
• build_dynamic_llm_datamodel: removed cache; clearer field description.

Strategy
• contract:
– post_remedy default switched to False.
– Robust dynamic type inference: separate input/output paths, improved error messages.
– act() signature validation added.

Full Changelog: v0.16.1...v0.16.2

v0.16.1

SymbolicAI v0.16.1 – Release Notes

🆕 Added Developer Value

Dynamic Type Annotation in Contracts

• 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).

Graceful Failure and Type Checking Enhancements

• 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.

Documentation and Visualization

• 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.

Improved Local Engine Usability

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

🔧 Refactoring & Internal Improvements

Codebase Refactoring

• 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.

Retry Strategy Tuning

• 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.

Robust Logging and Exception Surface

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

🐛 Bug Fixes

• 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.

🧪 Test Coverage

• 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.

---

🚀 Upgrade Guide

• 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

v0.15.1

Release Notes – v0.15.1

• Fix: Contract pre- and post-validation now correctly propagate input/output when no validation methods are implemented.
• Fix: Return values restored for _validate_input and _validate_output to ensure data flow.
• Test: Added coverage for skip pre/post scenarios and post-validation without remedy.

Full Changelog: v0.15.0...v0.15.1

v0.15.0

SymbolicAI v0.15.0 – Release Notes

This release is almost entirely focused on developer-experience: easier installation, simpler APIs, tighter error handling, and a fresh batch of unit-tests.
Migration effort should be low (see “Breaking changes” at the end).

---

Highlights / Added value for developers

• Brand-new lightweight Web-Scraping stack
– New engine naive_webscraping (requests + trafilatura) and matching interface
– Does not need a browser, works in headless environments and CI
– Pre-seeds common consent/age cookies and follows meta-refresh redirects
– symai.core.scrape decorator supersedes fetch
– Extensive doc updates + tutorial (docs/ENGINES/webscraping_engine.md)

• First-class local Vector DB
– Dedicated interface naive_vectordb (wrapping the in-memory VectorDB)
– Supports add, search, config(save|load|purge) out of the box
– Embedding model auto-switches: falls back to SentenceTransformers if no remote key is present
– New default index path: ~/.symai/localdb/<index>.pkl

• Chatbot quality bump
– SymbiaChat now uses the new interfaces map (cfg_to_interface)
– [CRAWLER] tag replaced by [SCRAPER], [RETRIEVAL] by [FILE]
– Automatic long-term memory persistence through the new vector-db interface
– Verbose/debug mode now prints classification tags and scratch-pads via loguru

• Whisper improvements
– Device auto-fallback with helpful warnings
– get_bins() helper to chunk transcripts into N-minute windows
– More explicit error messages for unsupported models / missing install

• Infrastructure & packaging
– Project build now compatible with uv (pyproject.toml [tool.uv], README snippets)
– Core dependency list trimmed (removed accelerate), optional extras split into fine-grained groups (hf, webscraping, services, …)
– Dev group (dependency-groups.dev) with pytest and isort
– .symai folder is always created under the active debug dir (fixes path mix-ups)

---

Refactoring & code clean-up

• Crawler deprecation
– Removed selenium driver, driver helpers and old interface/engine (engine_selenium.py, extended.crawler, docs)
– All decorators, prompts, docs renamed from crawler to scraper

• VectorDB internals
– Large readability pass; duplicated code removed, warnings switched to CustomUserWarning
– VectorDBIndexEngine refactored for clearer control-flow, explicit error paths, deep-copied config, consistent naming

• Chat subsystem
– Switched to loguru logger
– Memory window size, top-k and index name configurable via constructor
– Redundant functions & unused variables removed

• Setup wizard slimmed down – now only shows an intro and creates an empty config; the previous CLI questions were outdated and are gone.

---

Bug fixes

✓ Fixed .symai/config discovery when running in SYMAI_DEBUG=1 mode
✓ WhisperEngine no longer crashes if whisper is missing – clear ImportError with pip hint
✓ VectorDB.purge() cleared in-memory state and removes stale files
✓ semassert() returns boolean and no longer raises by default (tests rely on it)
✓ Various doc links, typos and outdated references (speech_engine → speech_to_text_engine, …)

---

Test coverage

• tests/engines/webscraping/… – crawls an online page in all output formats and extracts text from a PDF
• tests/engines/index/test_naive_vectordb_engine.py – add/search/save/load/purge happy path
• tests/engines/speech-to-text/test_whisper_engine.py – transcription + language detection paths
• tests/engines/symbolic/test_wolframalpha_engine.py – basic factual and math queries
  → Total lines under test up significantly; CI runtime down because Selenium was dropped.

---

Breaking changes

1. Interface("selenium"), core.fetch() and [CRAWLER] prompt tags were removed.
   → Use Interface("naive_webscraping") and [SCRAPER] instead.

2. Interface("vectordb") is replaced by Interface("naive_vectordb"), and operations now expect/return plain strings instead of zipped tuples.

3. Optional extra names changed (selenium → webscraping; new granular groups). Update your pip install symbolicai[…] commands.

4. Version bumped to 0.15.0 – pin accordingly in your environment files.

Enjoy the cleaner, lighter stack! Report issues or PRs on GitHub.

Full Changelog: v0.14.0...v0.15.0

v0.14.0

SymbolicAI v0.14.0 – Release Notes

High-level Summary
• New cloud provider support: Groq Cloud (Qwen-3, Llama-3.3, etc.)
• Cleaner, more consistent error messages across all LLM engines
• Significantly shorter “Getting Started” instructions—configuration is now managed via symai.config.json instead of a long list of environment variables
• Miscellaneous bug fixes, test improvements, and documentation pruning

────────────────────────────────────────────────────────

1. New Features
   • Groq Engine (symai.backend.engines.neurosymbolic.engine_groq)
   – Full neuro-symbolic wrapper for Groq Cloud’s OpenAI-compatible API
   – Supports reasoning models that expose <think> trace tags
   – Activate with:
   "NEUROSYMBOLIC_ENGINE_MODEL": "groq:qwen/qwen3-32b"
   – Token counting, vision, and parallel-tool calls are explicitly marked “Not Implemented” with clear warnings

• Thinking Trace Support Expansion
– Added support for Groq reasoning models alongside Claude, Gemini, and DeepSeek

2. Bug Fixes & Reliability
   • All LLM engines now emit a uniform error message
   Error during generation. Caused by: <original-exception>
   (replaces the provider-specific messages such as “Anthropic API request failed…”)

• Search Engines (OpenAI & Perplexity) wrapped API calls in try/except to avoid unhandled crashes

3. Developer / DX Improvements
   • Installation & Configuration Simplification
   – Removed long “export XYZ_API_KEY” snippets from README and docs
   – Single command symconfig bootstraps the config file and prints helpful hints
   – All optional dependencies (ffmpeg, selenium, etc.) now have a single warning block instead of per-OS commands

• Testing & CI
– Added semassert() helper for “weak assertions” that warn instead of fail when the model is flaky
– New marker @pytest.mark.skipif(NEUROSYMBOLIC.startswith('groq'), …) to skip tests that are not yet supported (token counting, vision)

4. Documentation & House-keeping
   • Removed the “Summary” section at the end of the neuro-symbolic engine doc (it was redundant)
   • Pruned the large “Pattern Matching & Intelligence Operations” block from the primitives doc—moved remaining examples into relevant sections
   • Updated code examples to use print(res) instead of print(res.value) for consistency with new return types

Full Changelog: v0.13.2...v0.14.0

v0.13.2

Bug Fixes

• Validation Retry Logic:
  The retry logic for validation in strategy.py has been improved. Previously, semantic validation errors could cause incorrect behavior, potentially skipping the final allowed attempt. The code now ensures that the maximum number of retries are respected (with N+1 total tries), and if semantic validation fails on the last allowed attempt, a clear error is propagated and logged.

• README Example Correction:
  Fixed a bug in the validate_some_field function in the README example (valid_sizes → valid_opts) to correctly match the list variable name.

Improvements

• Documentation Notes:
  • Added note in the README: The project name credits Allen Newell and Herbert Simon.
  • Added clearer information regarding enabling/disabling user warnings (SYMAI_WARNINGS=0) and community data collection features.
  • Cleaned up configuration documentation for clarity.

Full Changelog: v0.13.1...v0.13.2

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