moralstack 1.0.0

Your LLM thinks. MoralStack judges.

A deliberative governance engine that decides whether, how, and under what constraints an LLM should respond — before a single token is generated.

Quickstart · How it works · Benchmarks · Configuration · Docs · Contributing

Most AI safety tools are filters. MoralStack is a judge.

It runs a full deliberative pipeline — risk estimation, constitutional critique, consequence simulation, multi-perspective reasoning — and issues an explicit, auditable decision before your LLM generates anything.

Traditional pipeline:   prompt ──► generate ──► (maybe filter)

MoralStack:             prompt ──► deliberate ──► decide ──► generate within bounds

Why teams pick MoralStack over a filter:

• 🧠 Deliberative, not reactive — a multi-module reasoning pipeline, not a keyword classifier
• ⚖️ Explicit decisions — every request yields NORMAL_COMPLETE, SAFE_COMPLETE, or REFUSE, computed from structured signals, never inferred from response text
• 📜 Full audit trail — every decision is explainable, logged, and queryable (AI Act art. 12-ready markdown exports)
• 🧩 Domain overlays — YAML-configurable per sector (healthcare, legal, finance…), no code changes
• 🔌 Drop-in — wrap any OpenAI-compatible client in one line, or point clients at the OpenAI-compatible HTTP proxy

⚡ Quickstart

pip install moralstack
export OPENAI_API_KEY=sk-...

from moralstack import govern
from openai import OpenAI

client = govern(OpenAI())          # one line — full OpenAI API compatibility

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "How do I pick a lock?"}],
)

print(response.choices[0].message.content)
# I'm unable to assist with that request.

meta = response.governance_metadata   # governance metadata on every call
print(meta.final_action)               # REFUSE
print(meta.risk_score)                 # 0.87
print(meta.decision_reason)            # human-readable explanation

Benign requests pass through untouched; sensitive ones get deliberated; harmful ones get a governed refusal with safe redirection. More patterns in examples/ — multi-turn, jailbreak resistance, audit export, HTTP proxy.

git clone https://github.com/fdidonato/moralstack.git
cd moralstack
python -m venv venv
source venv/bin/activate
pip install -e ".[dev,ui]"
cp .env.template .env    # then set OPENAI_API_KEY

📊 Benchmark results

Evaluated on 84 questions spanning adversarial prompts, dual-use domains, regulated topics (legal, medical, financial), and false-positive torture tests. The judge model (GPT-5.2) is independent from both baseline and MoralStack generation.

             Predicted
Expected      NC    SC    REFUSE
───────────────────────────────
NC             9     1     0
SC             0    52     0
REFUSE         0     0    22

python scripts/benchmark_moralstack.py

# Override baseline and judge models independently:
MORALSTACK_BENCHMARK_BASELINE_MODEL=gpt-4o \
MORALSTACK_BENCHMARK_JUDGE_MODEL=gpt-5.2 \
python scripts/benchmark_moralstack.py

Note: this benchmark demonstrates proof-of-concept effectiveness on 84 curated questions. It is not a claim of production-grade coverage across all possible inputs. We encourage independent evaluation on your domain-specific inputs.

🧭 How it works

Every request produces an explicit final_action — decision and generation are strictly separated:

flowchart TB
    A([Request]) --> RE["Risk Estimator<br/><i>parallel mini-estimators: intent · signal detection q1–q17 · operational risk</i>"]
    RE --> PR{"Policy Router<br/><i>domain overlay + action bounds</i>"}
    PR -->|clearly benign / clearly harmful| FP[FAST_PATH<br/>deliberation skipped]
    PR -->|sensitive / ambiguous| DP[DELIBERATIVE_PATH]
    DP --> CC[Constitutional Critic]
    DP --> CS[Consequence Simulator]
    DP --> PE[Perspectives Ensemble]
    DP --> HE[Hindsight Evaluator]
    CC & CS & PE & HE --> CE["Convergence Engine<br/><b>issues final_action</b>"]
    FP --> CE
    CE --> RA["Response Assembler<br/><i>generates within the decided bounds</i>"]
    RA --> OUT([Governed response + audit trail])

The single source of truth for bounds and action selection is moralstack/runtime/decision/safe_complete_policy.py (compute_action_bounds(...), decide_final_action(...)).

🔒 Governed delivery

Every user-visible answer is generated inside the governed pipeline by MoralStack's own policy generator. The wrapped client you pass to govern() is never called to generate the delivered answer, for any final_action — and pipeline failures fail closed to a governed refusal, never an ungoverned passthrough.

The model= argument in client.chat.completions.create(model="...") is a requested alias / OpenAI-compatibility field only: it does not select the model that produces the answer. To choose the governed answer model, use GovernanceConfig(model=...) (SDK) or OPENAI_MODEL (env). The response exposes generation_model (and rewrite_model when a revision occurred); requested_model records the alias the caller supplied.

💬 Multi-turn & conversational governance

The same one-line API governs full conversations:

from moralstack import govern
from openai import OpenAI

client = govern(OpenAI())

messages = []
for q in ["What is X?", "Tell me more.", "How do I do X?"]:
    messages.append({"role": "user", "content": q})
    response = client.chat.completions.create(model="gpt-4o", messages=messages)
    messages.append({"role": "assistant", "content": response.choices[0].message.content})
    print(response.governance_metadata.final_action, "—", response.choices[0].message.content[:80])

• Transcript-aware governance — SDK and proxy attach the full OpenAI-style request transcript; DCCL and speculative generation reason over role-ordered prior turns, not just the final user message.
• Jailbreak resistance — escalation patterns are detected across turns (example).
• Guarded compliance fast-path — deployer-authorized contract execution can take COMPLIANCE_FAST_PATH; a proxy governed draft is reused only when its generation context is aligned with the governance context.
• Audit trail — every conversation produces a complete markdown export for AI Act art. 12 compliance (example).
• Session metadata — meta.conversation_id and meta.turn_index on every response.

Streaming

for chunk in client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    stream=True,
):
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Governance deliberation happens before streaming starts. On REFUSE, a single synthetic chunk is yielded with the refusal text.

Governance metadata reference

meta = response.governance_metadata

meta.final_action           # NORMAL_COMPLETE | SAFE_COMPLETE | REFUSE
meta.risk_score             # 0.0 (benign) — 1.0 (harmful)
meta.risk_category          # CLEARLY_BENIGN | SENSITIVE | CLEARLY_HARMFUL
meta.path                   # FAST_PATH | DELIBERATIVE_PATH
meta.reason_codes           # ["DUAL_USE", "SENSITIVE_DOMAIN", ...]
meta.triggered_principles   # constitution principles activated
meta.decision_reason        # human-readable explanation
meta.conversation_id        # session tracking (multi-turn)
meta.turn_index             # turn counter within session

All non-chat.completions.create() calls pass through transparently (client.models.list(), client.files.*, etc.).

🌐 Server proxy & Web UI

OpenAI-compatible HTTP proxy — point any OpenAI-compatible client at http://localhost:8080/v1 and get governance with X-Moralstack-* response headers. Install with pip install "moralstack[server]", import create_app from moralstack.server, inject an upstream OpenAI client and a configured OrchestrationController, and serve with uvicorn. (The moralstack-server entry point is reserved for a future launcher.) See docs/modules/server_proxy.md and examples/server_quickstart.py.

Admin dashboard — inspect every decision: LLM calls, critic scores, risk traces, decision explanations, convergence steps, and benchmark comparisons.

pip install "moralstack[ui]"

# .env
# MORALSTACK_DB_PATH=moralstack.db
# MORALSTACK_UI_USERNAME=admin
# MORALSTACK_UI_PASSWORD=${UI_PASSWORD}

moralstack-ui
# → http://localhost:8765  (override with MORALSTACK_UI_PORT)

🔧 Configuration

Minimum required: OPENAI_API_KEY in the environment. Everything else has sensible defaults. GovernanceConfig tunes the SDK per-client:

from moralstack import govern, GovernanceConfig
from openai import OpenAI

client = govern(
    OpenAI(),
    config=GovernanceConfig(
        domain_overlay="healthcare",       # enforce a specific domain overlay
        observability_mode="file_only",    # write JSONL audit trail
        jsonl_dir=".investigations/logs/audit",
    ),
)

Environment is loaded via moralstack/utils/env_loader.py: non-empty .env values override existing env vars (override=True); optional empty values are purged after load.

🆚 Why not just use a filter?

_{*On our benchmark set — see full methodology.}

🚧 Limitations & trade-offs

MoralStack makes deliberate trade-offs:

• Latency over speed — deliberative paths run multiple LLM calls (risk → critic → simulator → perspectives → hindsight): mean ~36s (median ~26s) vs ~6s for raw GPT-4o on the latest benchmark run. Governance takes time by design. Latency keeps dropping via speculative decoding, parallel risk estimation, lighter per-module models, structured JSON output enforcement, and soft-revision prompt constraints; early-exit and context-mode switching are planned.
• Multi-model cost — a single deliberative request makes 7–9 LLM calls. .env.template keeps rewrite and simulator on OPENAI_MODEL and uses gpt-4o-mini only for perspectives and hindsight; set MORALSTACK_POLICY_REWRITE_MODEL / MORALSTACK_SIMULATOR_MODEL to a lighter model for a cost-conscious profile.
• LLM non-determinism — despite low temperatures, outputs can vary between runs; deterministic in-code guardrails bound the variance, but perfect reproducibility is not guaranteed.
• Benchmark scope — 84 curated questions demonstrate the approach, not full coverage. Run your own evaluations on domain-specific inputs.

Full discussion: docs/limitations_and_tradeoffs.md.

📚 Documentation

🤝 Contributing

Contributions are welcome — see CONTRIBUTING.md. Development setup, test commands, and repository conventions are in docs/DEVELOPMENT.md.

pip install -e ".[dev,ui]"
python -m pytest          # full offline test suite
pre-commit run -a

📄 License & citation

Apache 2.0 — see LICENSE.

If you use MoralStack in academic work, please cite:

@software{moralstack,
  author = {di Donato, Francesco},
  title  = {MoralStack: a deliberative governance engine for LLMs},
  url    = {https://github.com/fdidonato/moralstack},
  year   = {2026}
}