awreason

One reasoning interface over whichever backend you configured.

pip install awreason

from awreason import ReasoningClient

r = ReasoningClient("https://reason.example.com", token="...")
answer = r.reason("Why is the sky blue?", depth="deep")
print(answer)

awreason ask "why is the sky blue?" --depth deep
awreason health
awreason stats
awreason --self-test

The service origin comes from --url or AWREASON_URL, the token from --token or AWREASON_TOKEN. Neither is guessed — a reasoning client that quietly falls back to some default endpoint is sending your questions somewhere you did not choose.

What this is, and what it is not

It is a client. The reasoning engine, tool registry, and model selection stay in the service; this is the wire contract, packaged so anything can speak it.

That split is deliberate. The alternative was lifting a large service with many private imports into a package, which produces something that ModuleNotFoundErrors on your machine while reading as authoritative. A broken package is worse than no package.

The problem this package solves

You ask a question. The backend thinks deeply, traces through multiple reasoning phases, explores tool calls and their results, builds up a chain-of-thought — and returns you one paragraph.

That paragraph could be correct. It could be wrong. It could be incoherent. And you have no way to tell which without acting on it. The reasoning is in the backend's logs, not in your hands.

awreason opens it up. You get the session, the phases, the thoughts, the tool calls that led to the answer. You can read the chain. You can say "no, that's wrong" with evidence, not intuition. And you can learn why a correct answer was correct.

from awreason import ReasoningClient

r = ReasoningClient()

# Simple reasoning
answer = r.reason("complex problem")

# With full session introspection
async with r.session("MyAgent", "Why did this fail?") as sess:
    await sess.think("Let me analyze the logs...")
    logs = await sess.tool_call("fetch_logs", {"service": "api"})
    await sess.analyze(f"The logs show: {logs}")
    await sess.synthesize("The root cause is...")
    await sess.conclude("The failure was caused by...")

# Browse the reasoning tree
tree = r.get_session_tree(sess.id)
for thought in tree.thoughts:
    print(f"{thought.phase}: {thought.content}")

Two things it refuses to do

Return None on failure. A reasoning failure and a reasoning that found no conclusion are different facts. If the service cannot answer, ReasoningError is raised. Returned as None, an outage would be indistinguishable from an inconclusive result — and nobody investigates an inconclusive result.

Send an empty Authorization header. No token means no header at all. An empty Bearer is rejected differently from an absent one, and the difference sends you debugging the auth server instead of your config.

Depth levels

How deep to reason about a question:

SASE phases

Reasoning follows the SASE methodology:

• Situation: Assess the current state, gather context
• Analysis: Break down the problem, identify patterns
• Synthesis: Combine insights, form hypotheses
• Execution: Take action, validate results
• Complete: All phases done

Each phase is a place to put a check. The chain is inspectable.

--self-test

Every install can prove the client still holds its contract, with no service and no network:

$ awreason --self-test
  PASS  base URL is normalized, defaults are sensible
  PASS  token is optional, depth enum is correct
SELF-TEST: awreason ok

The aw family

Standalone tools that share one idea: replace something you would otherwise have to trust with something you can check.

Each installs on its own, works offline, and needs no account.

awnix is the ground floor — A Linux you can hand to an agent — immutable base, capabilities included.

The Aitherium ecosystem

Every repository here is public. Each publishes an aither-manifest.json beside its page, so any surface can read every sibling's — the network is browsable from any node in it.