# What is SymbolicAI? A Neuro-Symbolic Python Framework for LLM Integration

> Explore SymbolicAI, a neuro-symbolic Python framework integrating LLMs with deterministic code. Discover its dual-mode Symbol abstraction for seamless hybrid AI development.

- Repository: [ExtensityAI/symbolicai](https://github.com/extensityai/symbolicai)
- Tags: tutorial
- Published: 2026-03-01

---

**SymbolicAI is a neuro-symbolic framework that merges deterministic Python programming with differentiable large language model (LLM) operations through a dual-mode Symbol abstraction.**

SymbolicAI (the `symbolicai` package from the extensityai/symbolicai repository) enables developers to combine classical Python execution with generative AI capabilities. The framework centers on a **neuro-symbolic** architecture where code operates in two interchangeable modes: fast syntactic execution and semantic LLM-driven computation. This design allows ordinary Python code to transparently invoke large language models when contextual understanding is required, while maintaining deterministic behavior by default.

## The Symbol Abstraction: Core of SymbolicAI

At the heart of SymbolicAI lies the **`Symbol`** class defined in [`symai/symbol.py`](https://github.com/extensityai/symbolicai/blob/main/symai/symbol.py). This abstraction represents values that can function as both standard Python objects and semantic entities connected to neuro-symbolic engines. The `Symbol` class implements dual-mode behavior through the `SYMBOL_PRIMITIVES` mapping in [`symai/ops/primitives.py`](https://github.com/extensityai/symbolicai/blob/main/symai/ops/primitives.py), enabling operator overloading that works both syntactically and semantically.

### Dual-Mode Operation: Syntactic vs Semantic

Symbols operate in two distinct modes controlled by the `semantic` parameter and the `.sem` / `.syn` properties:

**Syntactic mode** (default) treats the Symbol as a plain Python value, executing standard string, list, or numeric operations without side effects. This mode ensures fast, deterministic execution.

**Semantic mode** wires the Symbol to a neuro-symbolic engine, allowing the symbol to "understand" meaning and context through LLM processing. This enables fuzzy, conceptual operations like semantic containment or conceptual addition.

```python
from symai import Symbol

# Syntactic (default) – behaves like a plain Python string

s_syn = Symbol("Cats are adorable")
print("feline" in s_syn)          # → False (pure Python)

# Semantic – wired to the neuro-symbolic engine

s_sem = Symbol("Cats are adorable", semantic=True)
print("feline" in s_sem)          # → True (LLM-driven semantic check)

```

### On-Demand Semantic Projection

You can switch between modes dynamically using the `.sem` and `.syn` properties without recreating the Symbol:

```python
s = Symbol("Cats are adorable")   # syntactic by default

print("feline" in s.sem)          # → True  (semantic view)

print("feline" in s)              # → False (syntactic view)

```

## Operator Overloading and SYMBOL_PRIMITIVES

SymbolicAI overloads Python operators (`==`, `+`, `&`, etc.) via `SYMBOL_PRIMITIVES` in [`symai/ops/primitives.py`](https://github.com/extensityai/symbolicai/blob/main/symai/ops/primitives.py) to work in both modes. The default remains syntactic to minimize execution costs, but operations automatically promote to semantic processing when any operand is in semantic mode.

```python
a = Symbol("I love cats")
b = Symbol("and dogs")
c = a + b                         # semantic composition if either operand is semantic

print(c)                          # → "I love cats and dogs" (conceptual merge)

```

The `Expression` subclass in [`symai/symbol.py`](https://github.com/extensityai/symbolicai/blob/main/symai/symbol.py) extends this behavior with lazy evaluation and deeper integration into the engine stack.

## Design-by-Contract with the @contract Decorator

The framework brings **Design-by-Contract** principles to LLM-driven code through the `@contract` decorator implemented in [`symai/strategy.py`](https://github.com/extensityai/symbolicai/blob/main/symai/strategy.py). This system automatically validates inputs and outputs against Pydantic models, retries failed operations with remedies, and ensures type safety.

```python
from symai import Expression
from symai.strategy import contract
from symai.models import LLMDataModel
from pydantic import Field

class AddModel(LLMDataModel):
    a: int = Field(description="first integer")
    b: int = Field(description="second integer")

@contract(pre_remedy=True, post_remedy=True)
class Add(Expression):
    def forward(self, a: int, b: int) -> int:
        return a + b

result = Add()(a=2, b=3)   # validates against AddModel, retries on failure

print(result)              # → 5

```

## EngineRepository and Modular Backend Architecture

SymbolicAI employs a modular engine architecture centered on the **`EngineRepository`** singleton in [`symai/functional.py`](https://github.com/extensityai/symbolicai/blob/main/symai/functional.py). This repository manages pluggable engines for neurosymbolic processing, embeddings, search, drawing, and other capabilities. The system queries the appropriate engine based on operation type, allowing the same codebase to switch between local execution, CI environments, and remote servers without code changes.

## Decorator-Based LLM Integration

High-level LLM interactions are exposed through decorators defined in [`symai/core.py`](https://github.com/extensityai/symbolicai/blob/main/symai/core.py). The `zero_shot` decorator packages arguments, queries the `neurosymbolic` engine via `EngineRepository`, and returns processed results:

```python
from symai import zero_shot

@zero_shot(prompt="Summarize the following text:")
def summarize(text: str) -> str:
    ...

summary = summarize("Python is a versatile language …")

```

## Hierarchical Configuration Management

Configuration in SymbolicAI follows a hierarchical resolution order defined in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py): debug settings override environment variables, which override global configuration. This hierarchy ensures consistent behavior across local development, continuous integration, and production deployments.

## Summary

- **SymbolicAI** is a neuro-symbolic framework combining deterministic Python with generative LLM capabilities through the `symbolicai` package.
- The **`Symbol`** class in [`symai/symbol.py`](https://github.com/extensityai/symbolicai/blob/main/symai/symbol.py) provides dual-mode operation (syntactic/semantic) via `SYMBOL_PRIMITIVES` in [`symai/ops/primitives.py`](https://github.com/extensityai/symbolicai/blob/main/symai/ops/primitives.py).
- Operators overload to work both deterministically and semantically, defaulting to fast syntactic execution unless `semantic=True` or `.sem` is accessed.
- The **`@contract`** decorator in [`symai/strategy.py`](https://github.com/extensityai/symbolicai/blob/main/symai/strategy.py) enforces Design-by-Contract validation with automatic retries and remedy strategies.
- **EngineRepository** in [`symai/functional.py`](https://github.com/extensityai/symbolicai/blob/main/symai/functional.py) provides a singleton-based modular backend system for pluggable neuro-symbolic engines.
- Configuration resolves hierarchically (debug → environment → global) via [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) to support multiple deployment contexts.

## Frequently Asked Questions

### What is SymbolicAI used for?

SymbolicAI enables Python developers to integrate large language model capabilities into traditional codebases without sacrificing determinism. It is used for neuro-symbolic computing tasks where operations require both strict programmatic logic and semantic understanding, such as intelligent document processing, automated reasoning, and hybrid AI pipelines.

### How does the Symbol class differ from regular Python strings?

The **`Symbol`** class extends Python primitives with a dual-mode architecture defined in [`symai/symbol.py`](https://github.com/extensityai/symbolicai/blob/main/symai/symbol.py). While it behaves like a standard string in syntactic mode, it can switch to semantic mode where operations are processed by LLMs through the neuro-symbolic engine, enabling conceptual rather than literal comparisons and operations.

### What is the purpose of the @contract decorator?

The **`@contract`** decorator in [`symai/strategy.py`](https://github.com/extensityai/symbolicai/blob/main/symai/strategy.py) implements Design-by-Contract methodology for LLM-driven functions. It automatically validates inputs and outputs against specified Pydantic models, handles retries with remedy strategies when LLM calls fail, and ensures that operations return properly typed results.

### Where is the engine configuration managed in SymbolicAI?

Engine registration and querying are handled by the **`EngineRepository`** singleton class in [`symai/functional.py`](https://github.com/extensityai/symbolicai/blob/main/symai/functional.py). The framework uses a hierarchical configuration system defined in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) that checks debug flags, environment variables, and global settings to determine which backend engines to instantiate.