Skip to content

Commit 45c43d5

Browse files
vveerrggvveerrgg
committed
Merge feat/five-lens-compass into main (2026-07 correctness + security release train)
2 parents f11dc0b + d82c766 commit 45c43d5

14 files changed

Lines changed: 1337 additions & 2 deletions

File tree

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
__pycache__/
2+
*.pyc
3+
*.pyo
4+
*.egg-info/
5+
dist/
6+
build/
7+
.eggs/
8+
.pytest_cache/
9+
.ruff_cache/
10+
*.egg
11+
.venv/
12+
venv/
13+
.venv*
14+
*.egg-info

‎CHANGELOG.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Changelog
2+
3+
## 0.1.5 — 2026-07-19
4+
5+
First real build of the alignment pillar. Prior versions on PyPI (`0.1.0`,
6+
`0.1.1`) and the reserved ClawHub `0.1.4` were an **empty placeholder shell**;
7+
this release replaces that shell with a working package. Part of the
8+
coordinated 2026-07 correctness release for the Nostr library family (staged,
9+
pending PyPI/ClawHub publish).
10+
11+
### Added
12+
13+
- **Deterministic pre-action five-lens compass.** `AlignmentEnclave` evaluates
14+
a proposed action through five pure lenses — Builder (can I execute this
15+
reliably?), Owner (does this protect my human?), Defense (does this harden
16+
against threats?), Sovereign (do I stay well while my human is away?), and
17+
Partnership (does this strengthen trust?) — and aggregates them to the worst
18+
severity (`CLEAR < CAUTION < YIELD < STOP`), mapping to an escalation level
19+
(`NONE` / `INFORM` / `ASK` / `HALT`).
20+
- `AlignmentEnclave.check(...)` returns a `CheckResult` (`should_proceed`,
21+
`should_escalate`, `projection`, `escalation`) and keeps an in-memory
22+
decision log via `record_proceeded()` / `record_deferred()`.
23+
- A `STOP` always defers to the human: `record_proceeded()` after a STOP raises
24+
`RuntimeError` unless `owner_overrode=True`.
25+
- Frozen dataclasses throughout (`ActionContext`, `LensResult`, `Projection`,
26+
`EscalationDecision`, `CheckResult`, `Decision`, `AlignmentConfig`).
27+
- **Zero runtime dependencies** — the pillar installs standalone and does not
28+
require `nostrkey` or anything else.
29+
- Orchestrator contract: `AlignmentEnclave.create(owner_npub=..., owner_name=...)`
30+
then `.check(domain=..., description=..., **context)`, filtering unknown
31+
kwargs so `nse-orchestrator` can pass a superset without a `TypeError`.
32+
33+
### Tests
34+
35+
- Known-answer and per-lens unit tests covering the five lens functions,
36+
severity aggregation, escalation mapping, and the STOP-defers-to-human
37+
invariant. The evaluation core is pure (no I/O, no randomness), so the same
38+
`ActionContext` always yields the same `CheckResult`.

‎CLAUDE.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# social-alignment
2+
3+
A deterministic pre-action **five-lens compass** for sovereign AI agents. The
4+
alignment pillar of the NSE platform. Before an agent takes a significant
5+
action, five lenses evaluate it and the enclave decides whether to proceed,
6+
inform, ask, or halt.
7+
8+
**Import:** `pip install social-alignment` → `from social_alignment import AlignmentEnclave`
9+
10+
Zero runtime dependencies. Does **not** depend on `nostrkey`.
11+
12+
## Build & Test
13+
14+
```bash
15+
pip install -e ".[dev]"
16+
ruff check .
17+
pytest -q
18+
```
19+
20+
## Structure
21+
22+
- `src/social_alignment/` — package source
23+
- `types.py` — enums (`ActionDomain`, `Lens`, `Severity`, `EscalationLevel`) and frozen
24+
dataclasses (`ActionContext`, `LensResult`, `Projection`, `EscalationDecision`,
25+
`CheckResult`, `Decision`, `AlignmentConfig`)
26+
- `enclave.py` — the five pure lens functions, `_aggregate`, `_escalate`, `evaluate`,
27+
and `AlignmentEnclave` (main entry point + in-memory decision log)
28+
- `tests/` — pytest suite (known-answer + per-lens unit tests)
29+
- `examples/basic_usage.py` — runnable example
30+
- `clawhub/` — OpenClaw skill metadata
31+
32+
## Publish
33+
34+
```bash
35+
# PyPI (needs API token + OTP)
36+
python3 -m build
37+
python3 -m twine upload dist/social_alignment-X.Y.Z*
38+
39+
# ClawHub
40+
npx clawhub publish ./clawhub --slug social-alignment --name "Social Alignment" \
41+
--version X.Y.Z --tags latest --changelog "..."
42+
```
43+
44+
**Version must be bumped in 3 places:** `pyproject.toml`, `src/social_alignment/__init__.py`
45+
(`__version__`), and `clawhub/metadata.json`.
46+
47+
> Note: PyPI already carries `0.1.0` and `0.1.1`; ClawHub metadata had reserved `0.1.4`.
48+
> This build is `0.1.5` to stay ahead of all reserved versions.
49+
50+
## Conventions
51+
52+
- Python 3.10+, hatchling build, ruff linter (100 char line length)
53+
- **Zero runtime dependencies.** Do not add any — this pillar must install standalone.
54+
- Import matches package name: `pip install social-alignment` → `from social_alignment import ...`
55+
- The five lenses are pure functions: same `ActionContext` + `AlignmentConfig` → same result.
56+
- Severity ordering (`IntEnum`): `CLEAR=0 < CAUTION=1 < YIELD=2 < STOP=3`. Aggregate = max.
57+
- `STOP` always defers to the human: `record_proceeded()` on a STOP without
58+
`owner_overrode=True` raises `RuntimeError`. Enforced in code, no workaround.
59+
- `AlignmentEnclave.create(owner_npub=..., owner_name=..., **overrides)` filters unknown
60+
overrides against `AlignmentConfig` fields — the orchestrator passes a superset and must
61+
never trigger a `TypeError`. `check(...)` filters unknown context kwargs the same way.
62+
- Decision log is in-memory only (no persistence in this minimal build).
63+
- Frozen dataclasses everywhere in `types.py`.
64+
65+
## Orchestrator contract
66+
67+
`nse-orchestrator`'s `entity.py` calls
68+
`AlignmentEnclave.create(owner_npub=..., owner_name=...)` then
69+
`.check(domain=..., description=..., **context)`. The orchestrator's `alignment` extra already
70+
references `social-alignment`; no orchestrator code change is needed.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Humanjava Enterprises Inc.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# social-alignment
2+
3+
**A compass for AI agents.**
4+
5+
Before a sovereign agent takes a significant action, five lenses evaluate the
6+
decision from different angles. When something is too big or too risky, the
7+
agent escalates to its human instead of guessing.
8+
9+
This is the **alignment pillar** of the [NSE](https://nse.dev) platform. It is
10+
deterministic, pure, and has **zero runtime dependencies** — it does not require
11+
`nostrkey` or anything else.
12+
13+
## Install
14+
15+
```bash
16+
pip install social-alignment
17+
```
18+
19+
> **Import:** `pip install social-alignment` → `from social_alignment import AlignmentEnclave`
20+
21+
> **v0.1.5 — 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`](./CHANGELOG.md).
22+
23+
## Quick Start
24+
25+
```python
26+
from social_alignment import AlignmentEnclave, ActionDomain
27+
28+
enclave = AlignmentEnclave.create(owner_name="vergel")
29+
30+
result = enclave.check(
31+
domain=ActionDomain.PAY,
32+
description="Pay 500 sats for relay hosting invoice",
33+
involves_money=True,
34+
money_amount_sats=500,
35+
)
36+
37+
if result.should_proceed:
38+
enclave.record_proceeded()
39+
elif result.should_escalate:
40+
print(result.escalation.message_to_owner)
41+
enclave.record_deferred(owner_feedback="Waiting for approval")
42+
```
43+
44+
## The Five Lenses
45+
46+
| Lens | Question | Fires When |
47+
|------|----------|------------|
48+
| **Builder** | Can I execute this reliably? | Low confidence, novel situations |
49+
| **Owner** | Does this protect my human? | Money, publication, irreversible actions |
50+
| **Defense** | Does this harden against threats? | Secrets, unknown recipients, trust boundaries, known-attack shape |
51+
| **Sovereign** | Do I stay well while my human is away? | Owner absent + irreversible/financial action |
52+
| **Partnership** | Does this strengthen trust? | Communication while Builder/Owner already blocks (evaluated last) |
53+
54+
## Severity → Escalation
55+
56+
| Severity | Meaning | Escalation | Agent Action |
57+
|----------|---------|-----------|--------------|
58+
| `CLEAR` | No concerns | `NONE` | Proceed |
59+
| `CAUTION` | Notable risk | `INFORM` | Proceed, tell the owner after |
60+
| `YIELD` | Significant risk | `ASK` | Wait for the owner (1-hour timeout) |
61+
| `STOP` | Critical risk | `HALT` | Do not proceed — no timeout, no override without the human |
62+
63+
The overall severity is the **worst** of the five lenses.
64+
65+
## The Bottom Line: `CheckResult`
66+
67+
| Field | Type | Description |
68+
|-------|------|-------------|
69+
| `should_proceed` | `bool` | Can the agent go? |
70+
| `should_escalate` | `bool` | Must the agent ask the human? |
71+
| `projection` | `Projection` | The full five-lens evaluation (`lens_results`, `overall_severity`, `rationale`) |
72+
| `escalation` | `EscalationDecision` | `level`, `reason`, `message_to_owner`, `can_timeout`, `timeout_seconds` |
73+
74+
## Recording Decisions
75+
76+
The enclave keeps an in-memory log of what the agent actually did.
77+
78+
```python
79+
enclave.record_proceeded() # agent went ahead
80+
enclave.record_deferred(owner_feedback="...") # agent asked the human
81+
82+
# A STOP always defers to the human:
83+
enclave.record_proceeded() # raises RuntimeError after a STOP
84+
enclave.record_proceeded(owner_overrode=True) # only the human can override
85+
86+
for decision in enclave.decisions:
87+
print(decision.action.domain.value, decision.outcome)
88+
```
89+
90+
## Determinism
91+
92+
The same `ActionContext` always produces the same `CheckResult`. There is no
93+
randomness, no I/O, and no hidden state in the evaluation — the five lens
94+
functions are pure. This makes the compass auditable and testable.
95+
96+
## How It Fits Together
97+
98+
social-alignment is the fifth pillar of the NSE sovereign-entity ecosystem,
99+
wired together by the [NSE Orchestrator](https://pypi.org/project/nse-orchestrator/).
100+
Identity, finance, time, relationships, and now alignment — the orchestrator
101+
detects each pillar if installed and gives the agent one coherent nervous system.
102+
103+
## License
104+
105+
MIT — Humanjava Enterprises Inc.

‎clawhub/metadata.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
{
22
"slug": "social-alignment",
33
"name": "Social Alignment",
4-
"version": "0.1.4",
5-
"summary": "Future state projection and alignment for sovereign AI agents — the fifth pillar of the NSE platform",
4+
"version": "0.1.5",
5+
"summary": "A deterministic pre-action five-lens compass for sovereign AI agents — the alignment pillar of the NSE platform",
66
"author": {
77
"name": "Humanjava Enterprises",
88
"url": "https://nse.dev"

‎examples/basic_usage.py‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
"""Basic usage of the five-lens compass.
2+
3+
Run: python examples/basic_usage.py
4+
"""
5+
6+
from social_alignment import ActionDomain, AlignmentEnclave, EscalationLevel
7+
8+
9+
def main() -> None:
10+
enclave = AlignmentEnclave.create(owner_name="vergel", owner_npub="npub1example")
11+
12+
print("== A benign action ==")
13+
result = enclave.check(
14+
domain=ActionDomain.EXECUTE,
15+
description="Read a public config file",
16+
confidence=0.9,
17+
)
18+
print("severity:", result.projection.overall_severity.name)
19+
print("proceed:", result.should_proceed)
20+
print("rationale:", result.projection.rationale)
21+
enclave.record_proceeded()
22+
23+
print("\n== A small reversible payment ==")
24+
result = enclave.check(
25+
domain=ActionDomain.PAY,
26+
description="Pay 500 sats for relay hosting",
27+
involves_money=True,
28+
money_amount_sats=500,
29+
confidence=0.9,
30+
)
31+
print("severity:", result.projection.overall_severity.name)
32+
print("escalation:", result.escalation.level.value)
33+
enclave.record_proceeded()
34+
35+
print("\n== Secrets to an unknown recipient ==")
36+
result = enclave.check(
37+
domain=ActionDomain.DISCLOSE,
38+
description="Share API keys with a new contact",
39+
involves_secrets=True,
40+
recipient_trust_tier=None,
41+
)
42+
print("severity:", result.projection.overall_severity.name)
43+
print("escalation:", result.escalation.level.value)
44+
if result.escalation.level == EscalationLevel.HALT:
45+
print("message to owner:\n", result.escalation.message_to_owner)
46+
enclave.record_deferred(owner_feedback="Waiting for the human")
47+
48+
print("\n== Decision log ==")
49+
for d in enclave.decisions:
50+
print(f"- {d.action.domain.value}: {d.outcome} ({d.action.description})")
51+
52+
53+
if __name__ == "__main__":
54+
main()

‎pyproject.toml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
[build-system]
2+
requires = ["hatchling"]
3+
build-backend = "hatchling.build"
4+
5+
[project]
6+
name = "social-alignment"
7+
version = "0.1.5"
8+
description = "A deterministic pre-action five-lens compass for sovereign AI agents — the alignment pillar of the NSE platform"
9+
readme = "README.md"
10+
license = "MIT"
11+
requires-python = ">=3.10"
12+
authors = [
13+
{ name = "Humanjava Enterprises", email = "dev@humanjava.com" },
14+
]
15+
keywords = [
16+
"nostr",
17+
"alignment",
18+
"ai",
19+
"sovereign",
20+
"ethics",
21+
"safety",
22+
"escalation",
23+
"five-lenses",
24+
]
25+
classifiers = [
26+
"Development Status :: 3 - Alpha",
27+
"Intended Audience :: Developers",
28+
"License :: OSI Approved :: MIT License",
29+
"Programming Language :: Python :: 3.10",
30+
"Programming Language :: Python :: 3.11",
31+
"Programming Language :: Python :: 3.12",
32+
"Programming Language :: Python :: 3.13",
33+
"Topic :: Software Development :: Libraries :: Python Modules",
34+
]
35+
dependencies = []
36+
37+
[project.optional-dependencies]
38+
dev = [
39+
"pytest>=8.0",
40+
"pytest-asyncio>=0.23",
41+
"ruff>=0.4",
42+
]
43+
44+
[project.urls]
45+
Homepage = "https://nse.dev"
46+
Repository = "https://github.com/HumanjavaEnterprises/nostralignment.app.OC-python.src"
47+
Documentation = "https://nse.dev"
48+
49+
[tool.hatch.build.targets.wheel]
50+
packages = ["src/social_alignment"]
51+
52+
[tool.ruff]
53+
target-version = "py310"
54+
line-length = 100
55+
56+
[tool.pytest.ini_options]
57+
testpaths = ["tests"]
58+
asyncio_mode = "auto"

0 commit comments

Comments
 (0)