docs / env-kernel / overviewgithub.com/Fareground/env-kernel ↗

env-kernel

A deterministic, game-agnostic simulation kernel — LLMs are brains, code is physics.

fg-env-kernel is the engine underneath Fareground's simulations. You describe a world as declarative data (JSON/dict), and the kernel compiles it into an executable, deterministic, multi-agent simulation. Agents — real LLMs, cheap heuristics, or scripted stubs — make discrete, turn-based decisions; the kernel is the deterministic rule engine that resolves those decisions and evolves the world. The entry point is one line: simulate(template) — built-in seeded random agent, finished World back, world.summary() to read the outcome. The usage ladder runs simulate() → the Kernel/World facade (your own decision_fn, per-kernel registries) → load_world and the raw engine. The engine knows nothing about chess, markets, or elections — those are just configurations.

The core idea

Declarative worlds. A world is a WorldTemplate split into three logical layers: schema (entity types, resources, relations, space, time), rules (actions, triggers, terminations, domain modules), and viz (rendering hints, opaque to the kernel). Everything is data; whoever authors a world — an agent or you — emits JSON only, never Python.
Determinism guarantee. Given a template, a seed, and a decision_fn, a run is fully reproducible and serializable end-to-end. One seeded RNG is shared into every stochastic subsystem, and replay produces a deterministic step-by-step trace.
Extensibility via registries. New mechanics plug in through registries and decorators — @effect, @precondition, @resolution, @phase, @termination — never by editing the engine core. Drop-in kernel_primitives/*.py discovery is opt-in (explicit discover() or the KERNEL_PRIMITIVES_DIR env var), and registry.fork() gives each Kernel its own isolated primitive registry.
Continuous time + physics. Between agent turns, the world need not sit still: an event-driven clock and a coupled-ODE RK4 integrator evolve numeric state continuously, so action durations and reaction speed become part of strategy. Predator/prey, SIR epidemics, logistic growth, and price discovery are first-class citizens.

Separation of concerns

Layer	Owns	Examples
Agent (`decision_fn`)	Choices	LLM, heuristic, scripted stub
Kernel runtime	Rules & consequences	preconditions, resolution, effects, termination
Physics & dynamics	Continuous evolution	coupled ODEs, property drift, world events
Template	The world itself	entity types, actions, physics block, win conditions

The same world runs identically with real LLM agents or deterministic stubs — the agent interface is a plain callback, with no LLM dependency anywhere in the kernel.

Status

Version 0.2.0 (alpha), on PyPI (pip install fg-env-kernel) · Python ≥ 3.11 · single runtime dependency (pydantic>=2.0) · ships py.typed. Extracted from the Fareground platform; licensed under Apache-2.0. Newest in 0.2.0: the simulate()/Kernel/World SDK facade, template validation at load (TemplateError), and opt-in primitive discovery (breaking: no more import-time auto-discovery).

→ Start with Getting started · Concepts · API reference · Examples