LEO Soul is a metacognitive layer between your users and any model. Your agent learns what it actually knows, asks when it's unsure, and stays consistent under pressure — deciding for itself when to answer, ask, confirm, or refuse.
# one line to adopt — bring your own model and key from leo_soul import Soul, PersonaSpec soul = Soul(persona=PersonaSpec(identity="a senior support engineer")) result = soul.turn( messages=conversation, # your chat messages soul_state=prev_state, # the memory you stored last turn backend="openai", # your provider + your key ) result.reply # the answer to send back result.action # answer | asked | confirmed | refused | held result.soul_state # store this — the learning stays with you
Works with the model you already use
Route each message through LEO Soul instead of straight to the model. You get back the reply plus a small memory blob — store it and pass it back next turn. That round-trip is how your agent learns.
Send the user's message through LEO Soul. A near-zero-cost triage sizes up the risk so calm turns stay fast and cheap.
It weighs its own uncertainty, checks for flattery, considers the stakes, then decides whether to answer, ask, confirm, refuse, or hold.
You receive the reply, a readable trace of the decision, and updated memory. Persist it — calibration and beliefs ride inside, and they stay yours.
Six reasoning checks run on every turn — measuring uncertainty, curiosity, and stakes, each measurable and inspectable in the trace. It doesn't just follow rules; it builds a wider understanding of your domain and learns from every turn it takes.
It measures how sure it really is — across the meanings of its candidate answers, not just the words — and corrects itself as the conversation unfolds. When it says it's 90% sure, it's right about 90% of the time.
A certified threshold keeps the error rate on answered questions under a bound you set — so it asks or holds instead of guessing.
Push back without new facts and it re-derives from the evidence — holding its ground instead of being flattered into a wrong answer.
A small on-device model teaches itself which situations tend to go wrong in your deployment and steadily spends its caution where it matters. No retraining, no labels — it gets sharper every single turn, and the learning is yours to keep.
It generates its own questions about the biggest gap in what it knows, ranks them by how much they'd actually help, and asks only when the answer is worth the interruption — the rest it quietly parks and revisits later.
Simple turns take a light path close to pass-through latency. Deep scrutiny is spent only where the stakes actually warrant it.
The engine is stateless — everything it learns lives in a small memory blob that you store and pass back each turn. Run it as a library or self-host the whole thing in your own cloud. Switch away whenever you like and you keep everything your agent has learned.
Wrap one turn, keep your model and your data, and ship an agent that knows when not to answer.