Getting Started

Getting Started

The reference implementation is standard-library only — no pip install, no API key, no GPU. If you have Python 3.9+, you can run the whole thing right now.

1. Clone

git clone https://github.com/ElmatadorZ/genesis-os-blueprint.git
cd genesis-os-blueprint/reference

2. Run the reference

python examples/run_mission.py     # end-to-end tour + full audit trace
python tests/test_kernel.py        # 13 deterministic, offline conformance checks
# or, with pytest installed:
python -m pytest

3. What you'll see

run_mission.py walks five scenarios and prints why every decision was made:

Scenario	What it proves
Mission A — legitimate audit	the full lifecycle PRE_PLAN → PRE_ACT → PRE_VALIDATE → PRE_COMMIT → PRE_RESPONSE
Reality Grading	a hypothesis graded against evidence → a Validated Episode
Mission B — fabrication attempt	denied at PRE_ACT (never-fabricate, mechanised)
Mission C — over-budget goal	denied at PRE_PLAN (budget never overflows)
Mission D — write under read-only mandate	denied at PRE_PLAN (mandate enforced)
Capability routing	a sovereign request skips a provider that leaves the box

The printed audit trace is the point of the architecture: you can see exactly why each step was allowed or denied.

4. Use it in your own code

from genesis_kernel import build_default_kernel

kernel = build_default_kernel()
outcome = kernel.dispatch_mission("write docs/audit/report.md")
print(outcome.status)                 # COMPLETE
print(kernel.telemetry.explain())     # the full 'why'

Next steps

• Understand the shape of the system → Architecture Overview
• Plug in a real model, add a subsystem, or add a policy → How To Extend
• Read the normative contracts → specs/

Requirements & scope

• Python: 3.9 or newer. CI runs on 3.9 / 3.11 / 3.12.
• Dependencies: none (standard library only, by design).
• Scope: this is a reference, not a production framework — it favours legibility over throughput (the store is a dict, the "model" is a deterministic EchoProvider). See the warranty disclaimer in the LICENSE.