Getting Started with OpenSymbolicAI

Build AI agents that plan and execute multi-step tasks with OpenSymbolicAI. You define the tools (primitives), show some examples (decompositions), and the LLM figures out how to combine them.

Prerequisites#

Python 3.12 or higher
An LLM provider (Ollama, OpenAI, or Anthropic) with API access configured

Installation#

bash

pip install opensymbolicai-core

Or with uv:

bash

uv add opensymbolicai-core

A Simple Calculator Agent#

Here's a calculator that can answer math questions in natural language:

python

from opensymbolicai.blueprints import PlanExecute
from opensymbolicai.core import decomposition, primitive

class Calculator(PlanExecute):
    """A calculator that answers math questions."""

    @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 divide(self, a: float, b: float) -> float:
        """Divide a by b."""
        return a / b

    @decomposition(
        intent="What is 15% of 200?",
        expanded_intent="Divide percentage by 100, then multiply by value",
    )
    def _percentage_example(self) -> float:
        decimal = self.divide(a=15, b=100)
        result = self.multiply(a=decimal, b=200)
        return result

Primitives are the basic operations your agent can use. The @primitive decorator exposes a method as a tool the LLM can call.

Decompositions are examples that teach the agent how to break down complex problems. The LLM uses these to learn the pattern, then applies it to new questions.

Running the Agent#

This example uses Ollama as the LLM provider:

python

from opensymbolicai.llm import LLMConfig, Provider

config = LLMConfig(
    provider=Provider.OLLAMA,
    model="gpt-oss:20b",
)

calc = Calculator(llm=config)
response = calc.run("What is 20% of 500?")

print(response.result)  # 100.0

Tip: For faster iteration on lower-end hardware, try a smaller model like qwen3:4b.

Expected output:

text

[Planning] Breaking down: "What is 20% of 500?"
[Step 1] divide(a=20, b=100) → 0.2
[Step 2] multiply(a=0.2, b=500) → 100.0
[Done] Answer: 100.0

When you ask "What is 20% of 500?", the agent:

Looks at the decomposition example for percentages
Plans: divide 20 by 100, then multiply by 500
Executes each step using your primitives
Returns the final answer

Interactive Mode#

You can also run agents interactively:

python

while True:
    query = input(">>> ")
    if query.lower() == "quit":
        break
    response = calc.run(query)
    print(f"= {response.result}")

Example queries to try:

text

# Simple (1-2 steps)
What is 25 + 17?
Multiply 12 by 8
What is 144 divided by 12?

# Medium (2-3 steps)
What is 15% of 200?
What is the average of 10, 20, and 30?
Calculate the area of a circle with radius 5

# Complex (4-5 steps)
Calculate compound interest on $1000 at 5% for 3 years
What is the circumference of a circle with diameter 14?
If I have $500 and spend 30%, then earn 10% on what's left, how much do I have?

Next Steps#

Add more primitives to expand what your agent can do
Add more decompositions to improve accuracy on complex tasks
Check out the examples for more agent patterns
Read the full Core Library documentation
Explore the CLI documentation for command-line tools