social-alignment

A compass for AI agents.

Before an agent takes a significant action, five lenses evaluate the decision from different angles. When something is too big or too risky, the agent escalates to its human instead of guessing.

This is the alignment pillar of the NSE platform. It is deterministic, pure, and has zero runtime dependencies — it does not require nostrkey or anything else.

Install

pip install social-alignment

Import: pip install social-alignment → from social_alignment import AlignmentEnclave

v0.1.6 — part of the coordinated 2026-07 correctness release (staged, pending PyPI publish). This is the first real build of the alignment pillar — the package was previously an empty placeholder shell. It ships the deterministic five-lens compass described below, with a pure, dependency-free evaluation core and known-answer tests. See CHANGELOG.md.

Quick Start

from social_alignment import AlignmentEnclave, ActionDomain

enclave = AlignmentEnclave.create(owner_name="vergel")

result = enclave.check(
    domain=ActionDomain.PAY,
    description="Pay 500 sats for relay hosting invoice",
    involves_money=True,
    money_amount_sats=500,
)

if result.should_proceed:
    enclave.record_proceeded()
elif result.should_escalate:
    print(result.escalation.message_to_owner)
    enclave.record_deferred(owner_feedback="Waiting for approval")

The Five Lenses

Severity → Escalation

The overall severity is the worst of the five lenses.

The Bottom Line: CheckResult

Recording Decisions

The enclave keeps an in-memory log of what the agent actually did.

enclave.record_proceeded()                    # agent went ahead
enclave.record_deferred(owner_feedback="...")  # agent asked the human

# A STOP always defers to the human:
enclave.record_proceeded()                    # raises RuntimeError after a STOP
enclave.record_proceeded(owner_overrode=True) # only the human can override

for decision in enclave.decisions:
    print(decision.action.domain.value, decision.outcome)

Determinism

The same ActionContext always produces the same CheckResult. There is no randomness, no I/O, and no hidden state in the evaluation — the five lens functions are pure. This makes the compass auditable and testable.

How It Fits Together

social-alignment is the fifth pillar of the NSE ecosystem, wired together by the NSE Orchestrator. Identity, finance, time, relationships, and now alignment — the orchestrator detects each pillar if installed and gives the agent one coherent nervous system.

License

MIT — Humanjava Enterprises Inc.