esoi

Keep the best implementation of every part of your system in use, chosen by measurement.

esoi is the Python library and command for ESOI (Evolvable Structure that Optimizes Intent). You declare what a part of your system is for, write alternative implementations of it side by side, and measure them on the same cases. The library then runs the measured winner wherever that part is called, so replacing an implementation changes no caller.

• Declare once, where the code is. @solution names the interface and @implementation names each alternative.
• Measure and record. esoi run scores an implementation on your cases and records the result with the commit and the cases it was measured on.
• Select by the metric. esoi leaderboard ranks the alternatives, esoi select --promote makes the leader the default, and esoi lock pins it for production.
• Keep the structure sound. esoi check verifies the repository against its own records, and esoi hygiene scans for secrets and private data before a public push.

Python 3.11 or later. The core has no dependencies. Apache-2.0.

Install

pip install esoi
pip install "esoi[sheets]"   # with Google Sheets sync

A commit that is not released yet:

pip install "esoi @ git+https://github.com/JoshuaMathias/evolvable-structure.git@<commit>#subdirectory=implementations/python"

From a checkout: pip install -e implementations/python.

Quick start

from esoi import implementation, solution

@solution("greet-a-person")                  # declare once, where the code is
def greet(name: str) -> str: ...

@implementation("greet-a-person", "plain")
def plain(name: str) -> str:
    return f"Hello, {name}!"

greet("Ada")                                 # call: the project default, from the records
greet("Ada", using="plain")                  # or by name for one call

esoi init                   # scaffold a small example repository that already passes
esoi check                  # every rule; --strict also rejects results recorded on uncommitted code
esoi records sync           # the records follow what the code declares
esoi run greet_a_person --impl plain --record   # measure
esoi leaderboard
esoi select --promote       # promote the winner of the solution's own metric

The full walk through is docs/how-to/apply-with-tools.md.

Modules

Reference: configuration, evaluation components, rules.

Using the table from your code (the advanced layer)

from esoi.runtime.implementation_selection.select import Selector

selector = Selector.from_config(config)      # the table `selection` names; an entry without a "default" takes the records' `selected`
implementation = selector.resolve("greet", overrides={"greet": "loud"})

The decorators above and this table are one set of names; see Declare, call, measure, promote.

Tests

python -m pytest implementations/python/tests          # from the repository root; offline, no network

tests/test_components.py runs this repository's own evaluation components, and tests/test_self.py checks the repository against its own structure.