NOMOS · v0.3.0

✦ About

NOMOS is an auditable orchestration layer built on the v0.2 deterministic Decision Foundation. It scored 95/100 in Singapore's IMDA AI Verify compliance assessment. The engine combines structured evaluation, fine-grained algorithm audit, causal counterfactual reselection, declared scenario stress tests, structural cognitive challenges, information priorities, and human governance in one report.

It does not invent missing facts, weights, thresholds, owners, evidence, or probabilities. It produces leading candidates under declared inputs and always keeps final authority outside the algorithm.

✦ Built-in Universal Audit Engine

The agent engine ships with a built-in universal audit engine — not a bolt-on patch. Audit tracing lives inside the deterministic core, so every decision, assumption, constraint, and causal step is recorded, hash-chained, and independently verifiable by design rather than grafted on afterward.

In Singapore's IMDA AI Verify causal-audit assessment the engine scored 95/100. The full compliance report is included in this repository as IMDA_AI_Verify_Causal_Audit_Report.pdf.

— ✦ —

✦ What v0.3 adds

• hash-chained audit events for every major deterministic operation
• explicit operands and outputs for constraint and criterion calculations
• true candidate reselection after transitive assumption invalidation
• user-declared metric, evidence, and assumption-failure stress scenarios
• a deterministic cognitive-risk challenge layer that does not infer mental state
• a ranked information-acquisition and review queue
• one IntelligentDecisionHub orchestrator and one sealed HubReport
• full audit ledgers inside both baseline and scenario runs
• POST /v1/hub/analyze while preserving every v0.2 endpoint
• v0.3 package, CLI demonstration, generated OpenAPI, and CI coverage gates

The detailed architecture and boundaries are documented in docs/INTELLIGENT_DECISION_HUB_V0_3.md. The v0.2 foundation design remains available in docs/DECISION_FOUNDATION_V0_2.md.

✦ Architecture

HubAnalysisRequest
  -> Decision Foundation
       -> structural/evidence audit
       -> hard + soft constraint evaluation
       -> normalized scoring
       -> causal invalidation
       -> counterfactual reselection
       -> Pareto + weight sensitivity
       -> hash-chained algorithm audit
  -> declared scenario stress runs
  -> structural cognitive-risk challenges
  -> information priority queue
  -> append-only DecisionRecord
  -> sealed HubReport
  -> human approval/rejection

✦ Install and test

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest

✦ Run demonstrations

Core Decision Foundation:

second-perspective-demo

NOMOS with two stress scenarios:

intelligent-decision-hub-demo

✦ Python usage

from second_perspective import IntelligentDecisionHub
from second_perspective.models import HubAnalysisRequest

request = HubAnalysisRequest.model_validate(
    {
        "decision": decision_payload,
        "scenarios": [
            {
                "id": "SC1",
                "name": "Critical assumption fails",
                "failed_assumption_ids": ["A1"],
            },
            {
                "id": "SC2",
                "name": "Cost shock",
                "metric_overrides": {"S2": {"capital_required": 6000000}},
            },
        ],
    }
)
report = IntelligentDecisionHub().analyze(request)

The returned report contains the stored baseline decision record, scenario results, cognitive findings, information priorities, algorithm-ledger verification status, policy snapshot, and report hash.

✦ Run the API

Local development may run without a key:

export SP_ENV=development
uvicorn second_perspective.api.main:app --reload

Production fails closed unless a key is configured:

export SP_ENV=production
export SP_API_KEY="replace-with-a-strong-secret"
uvicorn second_perspective.api.main:app --host 0.0.0.0 --port 8000

Protected clients send Authorization: Bearer <SP_API_KEY>.

Endpoints:

• POST /v1/hub/analyze
• GET /v1/hub/reports/{hub_run_id}
• POST /v1/decisions/evaluate
• GET /v1/decisions/{decision_id}
• GET /v1/decisions/{decision_id}/history
• POST /v1/decisions/{decision_id}/approval
• GET /health

✦ Regenerate the Action/OpenAPI schema

SP_PUBLIC_BASE_URL=https://decision.example.com \
python scripts/export_openapi.py

✦ Compatibility

All v0.2 decision requests and endpoints remain valid. Responses add counterfactuals, algorithm_audit, and algorithm_audit_root_hash. Clients that strictly deserialize response fields should update their models.

✦ Production boundary

v0.3 is a functioning NOMOS application core, not yet a complete multi-tenant enterprise control plane. The default repository is still process-local memory. Production requires durable event storage, OIDC and authorization enforcement, tenant isolation, KMS signatures, rate limiting, observability, backups, migrations, and domain control packs.

The cognitive scanner challenges structural risks. It does not diagnose people, read motives, or replace legal, medical, financial, or safety professionals.

✦ Project Structure

second-perspective/
├── pyproject.toml              # package: nomos-decision-engine v0.3.0
├── src/second_perspective/
│   ├── cli.py / hub_cli.py     # demo entry points
│   ├── service.py / repository.py / canonical.py / version.py
│   ├── api/                    # FastAPI: main.py, security.py
│   ├── audit/                  # auditor, execution, graph, ledger
│   ├── decision/               # causal, counterfactual, engine, evaluator,
│   │                           #   integrity, policy, robustness, selection
│   ├── governance/             # approval
│   ├── hub/                    # orchestrator, cognitive, information, integrity,
│   │                           #   policy, repository, scenario
│   └── models/                 # enums, hub, schemas
├── docs/                       # DECISION_FOUNDATION_V0_2.md, INTELLIGENT_DECISION_HUB_V0_3.md
├── examples/market_entry.json  # sample decision request
├── scripts/export_openapi.py
├── tests/                      # test_api / test_engine / test_foundation / test_hub
├── Dockerfile · openapi-action.yaml · BRANCH_MANIFEST.md · .env.example
└── requirements-engine.txt · requirements-engine-dev.txt

✦ Documentation

• docs/DECISION_FOUNDATION_V0_2.md — the deterministic decision foundation and its invariants.
• docs/INTELLIGENT_DECISION_HUB_V0_3.md — from decision base to decision hub: architecture, algorithm audit, scenarios, governance.
• Regenerate the OpenAPI schema with python scripts/export_openapi.py (set SP_PUBLIC_BASE_URL).

✦ Status & Roadmap

• v0.3.0 — Intelligent Decision-Hub application core: hash-chained audit, candidate reselection, scenario stress, cognitive-risk scanner, information queue, sealed HubReport.
• Not yet a multi-tenant enterprise control plane (see Production boundary above).
• Next: durable event storage, OIDC + authorization, tenant isolation, KMS signatures, rate limiting, observability.

✦ License & Authorization

This repository is not open-source. Dual-track model: free for individual non-commercial research; paid commercial authorization required for government / enterprise. See LICENSE — licensor and governing law follow the user's location (within the PRC → Shanghai Linming Junhua Technology Co., Ltd.; outside the PRC → NOHN AI TECHNOLOGY PTE. LTD., Singapore law + SIAC arbitration).

---

GitHub · Website · lin@secondai.top