Hello, OpenSymbolicAI

The five-minute first win: a working agent that plans and executes a small arithmetic task. The finished project is two files: calculator.py (the agent) and main.py (runs it). Clone it from the card above to follow along, or build it step by step below.

1. Install#

OpenSymbolicAI is published to PyPI as opensymbolicai-core (the import name is opensymbolicai). It needs Python 3.12+. With uv:

bash

uv add opensymbolicai-core

2. Write a three-primitive agent#

A primitive is the core building block: a typed, documented method the planner is allowed to call. The base class PlanExecute turns a written task into a plan and executes it.

python

# calculator.py
from opensymbolicai.blueprints import PlanExecute
from opensymbolicai.core import primitive


class Calculator(PlanExecute):
    """A tiny calculator agent with three primitives."""

    @primitive(read_only=True)
    def add(self, a: float, b: float) -> float:
        """Add two numbers."""
        return a + b

    @primitive(read_only=True)
    def multiply(self, a: float, b: float) -> float:
        """Multiply two numbers."""
        return a * b

    @primitive(read_only=True)
    def subtract(self, a: float, b: float) -> float:
        """Subtract b from a."""
        return a - b

The type annotations are the LLM's contract, and the docstrings are its guidance. You'll learn what read_only does in Track 2.

3. Run it#

Point the agent at a local model and give it a task in plain English:

python

# main.py
from calculator import Calculator
from opensymbolicai.llm import LLMConfig

llm = LLMConfig(provider="ollama", model="qwen2.5-coder:7b")
agent = Calculator(llm=llm)

result = agent.run("what is 7 times 8 minus 3")
print(result.result)  # 53

bash

uv run main.py

Ollama runs locally, so no API key is required. Pull the model first if you haven't already:

bash

ollama pull qwen2.5-coder:7b

4. What just happened#

The LLM didn't do the arithmetic. It wrote a plan, a small program like result = subtract(multiply(7, 8), 3), and your primitives ran it in plain Python in your own process.

The numbers never went into a follow-up prompt. The LLM wrote the plan once, and your primitives produced the values.