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

If you cloned tutorials-py in the prerequisites, the code is already on your machine. cd in and run it:

bash

cd tutorials-py/01-hello
uv run main.py

Or follow the steps below to build it from scratch.

1. Install#

Create a new project and add the dependency:

bash

mkdir 01-hello && cd 01-hello
uv init
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 model'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

4. What just happened#

The model 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 model wrote the plan once, and your primitives produced the values.