How To Extend

How To Extend

Three common extensions, each a few lines. The reference is designed so that these are the only places you need to touch.

1. Plug in a real model (a new Capability Provider)

The whole point of the Capability Provider Model: swapping who answers a capability changes nothing above it.

from genesis_kernel import CapabilityProvider, Capability, Result

class MyModelProvider(CapabilityProvider):
    name = "my-llm"
    provides = [Capability.REASONING, Capability.PLANNING]
    leaves_box = True        # be honest: does invoking send data off-box?
    deterministic = False

    def available(self) -> bool:
        return bool(os.environ.get("MY_LLM_API_KEY"))   # skipped silently if absent

    def invoke(self, capability, request):
        # ... call your model ...
        return Result(ok=True, output=..., provider=self.name)

kernel.register_provider(MyModelProvider())   # register BEFORE the EchoProvider to prefer it

• Set leaves_box/deterministic truthfully — the router relies on them for sovereignty and reproducibility decisions.
• With no key, available() returns False and the router falls back — no crash.

2. Add a cognitive subsystem

from genesis_kernel import Subsystem, Capability, Event, Context

class ResearchSubsystem(Subsystem):
    name = "research"
    abi_version = "0.2"                     # a wrong version is refused at registration
    provides = [Capability.REASONING]

    def handle(self, event: Event, ctx: Context):
        ctx.spend(300)                      # account for compute before using it
        # ... do work; MUST NOT touch the outside world directly (ask the kernel) ...
        return event.derive("research.done", findings=[...])

kernel.register_subsystem(ResearchSubsystem())

Rules the ABI enforces: don't call another subsystem directly (compose via events), don't perform outside side effects directly, always spend() budget. See specs/kernel-abi.md.

3. Add a policy (tighten the system)

Registering a policy can only ever make the system more careful (most-restrictive-wins).

from genesis_kernel import Policy, HookPoint, Decision

class RateLimitPolicy(Policy):
    name = "ratelimit.r1"
    point = HookPoint.PRE_ACT
    def evaluate(self, event, ctx) -> Decision:
        if too_many_actions(ctx):
            return Decision(False, "rate limit exceeded", self.name)   # fail-closed friendly
        return Decision(True, "within limit", self.name)

kernel.register_policy(RateLimitPolicy())

Remember: any exception you raise becomes a deny (fail-closed), and both allow and deny are audited automatically.

Conformance

Whatever you add, keep the reference tests green — they are the conformance oracle:

cd reference && python tests/test_kernel.py

If your implementation disagrees with the reference on a lifecycle or fail-closed question, the reference is the tie-breaker.

---

→ Next: Contributing · Roadmap