SoulverCore: a natural language math engine shipped as a closed binary framework

What it is, and the fact that you get a binary rather than the source

SoulverCore is a natural language math engine written in Swift and used by the popular notepad calculator Soulver. The packaging is the first thing to understand, because it decides who can use it. It is offered here as a closed-source xcframework, a licence is required for commercial use, and it may be used for personal and non-commercial projects. So the repository does not contain the engine's source code, it contains the packaged binary and the sample projects and the documentation. The primary language is Swift, the licence is a custom one GitHub cannot classify with the text in LICENSE.md, and the last push to the repository was on 2026-08-23. The releases are 3.4.0 on 2026-04-01, 3.5.0 on 2026-05-15 and 3.5.1 on 2026-08-23.

The four design goals, and the performance number behind them

The design goals section is four lines and each is a constraint on how you will use it. Sensible defaults for most use cases, which are the same defaults used by Soulver. A high level of customizability, through set phrase variables, adding new units and defining custom natural language functions. Excellent performance, given as 7k or more calculations per second on Apple silicon devices. And no third party dependencies, which for a closed binary that you cannot audit the contents of is a meaningful claim. The performance goal is separate from the latency claim, and the README states the second separately, that most expressions are evaluated in less than half a millisecond. It also notes that while the calculator classes are thread-safe, there is typically no need to perform single calculations off the main thread of your application, which is the kind of practical note that saves an unnecessary dispatch.

The API surface, and what a calculation actually looks like

You create a Calculator with a customization, .standard for the defaults, and call calculate with a string. The result is an object with a stringValue property, so the first example calculates 123 + 456 and prints 579. The rest of the surface is visible in the examples. Unit conversions, 65 kg in pounds giving 143.3 lb. Percentage phrases, 40 is what % of 90 giving 44.44%, and the inverse $150 is 25% on what giving $120. Date and calendar arithmetic, 3:45pm + 4 hr 10 min giving 7:55 pm. Time zone conversion, 9:35am in New York to Japan giving 10:35 pm. Date arithmetic with mixed units, January 30 2020 + 3 months 2 weeks 5 days giving May 19, 2020. And compound interest, $25k over 10 years at 7.5% giving $51,525.79. The engine also supports annotating a calculation with commenting words that have no effect on the result, so $10 for lunch + 15% tip gives $11.50, which is the feature that makes it feel like a notepad rather than a formula entry.

import SoulverCore

let calculator = Calculator(customization: .standard)
let result = calculator.calculate("123 + 456")
print("The answer is \(result.stringValue)") // prints 579

Variables, formatting preferences and locale

Three extension points sit around the core calculate call. A VariableList lets a calculation refer to named values, with Variable entries carrying a name and a value string, and you pass it into the calculate call with a with parameter, so a calculation of variable 1 + variable 2 returns 579. A FormattingPreferences controls the output, with a dp property for decimal places and options for thousands separators, and setting it on the calculator makes pi come out as 3.14 rather than a long expansion. And locale is respected, since SoulverCore follows the decimal separator and thousands separator of the device's system locale, and you can convert a customization to another locale, so EngineCustomization.standard.convertTo with a de_DE locale gives a calculator that reads 1,2 + 3,4 as 4,6 with a comma as the decimal separator. The engine is localised into German, Russian, French, Spanish, Italian, Japanese, Korean and simplified Chinese, and the languages are additive, so a German user can use both English and German syntax.

var formattingPreferences = FormattingPreferences()
formattingPreferences.dp = 2 // decimal places
calculator.formattingPreferences = formattingPreferences

calculator.calculate("π") // 3.14

Currency rates, and the difference between hard-coded and live

The standard customization uses hard-coded rates for 190 real-world and crypto currencies, which is a reasonable default for a calculator that must work offline, but it means the rates go stale. To support live currency conversion you set the currencyRateProvider property on the calculator's EngineCustomization to an object conforming to CurrencyRateProvider. One implementation ships with the framework, ECBCurrencyRateProvider, which fetches 33 popular fiat currencies from the European Central Bank and needs no API key, and the README shows updating the rates with a completion handler and then calculating a conversion. The distinction between 190 hard-coded currencies and 33 live ones is worth noting, since the coverage of the live provider is much narrower than the coverage of the built-in table, and the crypto currencies are only in the hard-coded set.

The toolchain and the platform story

The requirements are specific and they are the first thing to check. You need Xcode 26 or later, which means the Swift 6.2 toolchain, and the SoulverCore binary is built with Swift 6.2. The framework is distributed as a binary framework with builds for macOS as a universal binary, iOS and iPadOS, and Mac Catalyst, and the minimum deployment targets are macOS 13.5, iOS and iPadOS 16, and Mac Catalyst 16. Windows, Linux and Android builds are available too, but through a separate repository, SoulverCore-Multiplatform, so the main package here is the Apple one. Installation is through the Swift Package Manager, by adding the package dependencies URL in Xcode, and there is a manual route where the xcframework zip is attached as a binary asset to every tagged release and you drag the framework into the Frameworks, Libraries and Embedded Content section of your target. The repository also carries MacSample and iosSample projects and a SoulverCoreSamples.xcworkspace to show a working setup.

String parsing, and the boundary of what the engine covers

The last documented capability is not really a calculation feature but a parsing one. SoulverCore can parse data out of strings in a type-safe way, using a natural and memorable syntax that the README says is much more user friendly than regex for many tasks, and the details are in a separate StringParsing repository. It also includes a natural language date parsing engine that is more versatile than a fixed format. So the framework is two things joined together, a calculation engine and a parser that can pull typed values out of a sentence. That pairing is the reason the topics list runs from math-engine and expression-evaluator to date-parser and notepad-calculator, because the product idea is a calculator that also reads what you typed. The limitation to hold in mind is that a closed binary cannot be extended at the source level, so a parsing or calculation feature you need that the engine does not have is not something you can add yourself, only configure around with phrase variables and custom units.

Editorial conclusion

SoulverCore suits an iOS or macOS developer who wants the Soulver calculation language inside an app, and who can accept a binary dependency with a commercial licence. It is the wrong choice if you need the source, because the engine is distributed closed source as a binary framework, and a poor fit for a cross platform project on the budget of a small team, since the commercial licence is required and the non-Apple platforms are a separate multiplatform repository. Before adopting it, read the licence terms rather than the README, because the difference between free for non-commercial and licensed for commercial is the whole commercial decision, and note the toolchain requirement of Xcode 26 and Swift 6.2 with a minimum of macOS 13.5.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. soulverteam/SoulverCore on GitHub