SymbolicAI

---
What is SymbolicAI?
SymbolicAI is a **neuro-symbolic** framework, combining classical Python programming with the differentiable, programmable nature of LLMs in a way that actually feels natural in Python.
It's built to not stand in the way of your ambitions.
It's easily extensible and customizable to your needs by virtue of its modular design.
It's quite easy to write your own engine, host locally an engine of your choice, or interface with tools like web search or image generation.
To keep things concise in this README, we'll introduce two key concepts that define SymbolicAI: **primitives** and **contracts**.
> ❗️**NOTE**❗️ The framework's name is intended to credit the foundational work of Allen Newell and Herbert Simon that inspired this project.
Primitives
At the core of SymbolicAI are Symbol objects—each one comes with a set of tiny, composable operations that feel like native Python.
Symbol comes in **two flavours**:
1. **Syntactic** – behaves like a normal Python value (string, list, int ‐ whatever you passed in).
2. **Semantic** – is wired to the neuro-symbolic engine and therefore *understands* meaning and
context.
Why is syntactic the default?
Because Python operators (==, ~, &, …) are overloaded in symai.
If we would immediately fire the engine for *every* bitshift or comparison, code would be slow and could produce surprising side-effects.
Starting syntactic keeps things safe and fast; you opt-in to semantics only where you need them.
How to switch to the semantic view
1. **At creation time**
2. **On demand with the .sem projection** – the twin .syn flips you back:
3. Invoking **dot-notation operations**—such as .map() or any other semantic function—automatically switches the symbol to semantic mode:
Because the projections return the *same underlying object* with just a different behavioural coat, you can weave complex chains of syntactic and semantic operations on a single symbol. Think of them as your building blocks for semantic reasoning. Right now, we support a wide range of primitives; check out the docs here, but here's a quick snack:
| Primitive/Operator | Category | Syntactic | Semantic | Description |
|--------------------|-----------------|:---------:|:--------:|-------------|
| == | Comparison | ✓ | ✓ | Tests for equality. Syntactic: literal match. Semantic: fuzzy/conceptual equivalence (e.g. 'Hi' == 'Hello'). |
| + | Arithmetic | ✓ | ✓ | Syntactic: numeric/string/list addition. Semantic: meaningful composition, blending, or conceptual merge. |
| & | Logical/Bitwise | ✓ | ✓ | Syntactic: bitwise/logical AND. Semantic: logical conjunction, inference, e.g., context merge. |
| symbol[index] = value | Iteration | ✓ | ✓ | Set item or slice. |
| .startswith(prefix) | String Helper | ✓ | ✓ | Check if a string starts with given prefix (in both modes). |
| .choice(cases, default) | Pattern Matching| | ✓ | Select best match from provided cases. |
| .foreach(condition, apply)| Execution Control | | ✓ | Apply action to each element. |
| .cluster(**clustering_kwargs?) | Data Clustering | | ✓ | Cluster data into groups semantically. Uses scikit-learn's HDBSCAN via symbolicai[cluster]. |
| .similarity(other, metric?, normalize?) | Embedding | | ✓ | Compute similarity between embeddings. |
| ... | ... | ...| ... | ... |
Contracts
They say LLMs hallucinate—but your code can't afford to. That's why SymbolicAI brings **Design by Contract** principles into the world of LLMs. Instead of relying solely on post-hoc testing, contracts help build correctness directly into your design, everything packed into a decorator that will operate on your defined data models and validation constraints: