docs / env-kernel / overview

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 test stubs — make discrete, turn-based decisions; the kernel is the deterministic rule engine that resolves those decisions and evolves the world. 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; an env-builder agent never writes 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. Downstream apps drop primitives into kernel_primitives/*.py files that are auto-discovered at startup.
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, test 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.1.0 (alpha) · Python ≥ 3.11 · single runtime dependency (pydantic>=2.0) · 28 test files, ~353 tests, with determinism explicitly tested (tests/test_determinism.py). Freshly extracted from the Fareground platform (single initial commit); license intentionally unset (proprietary, TBD). Continuous time and physics are the newest features (Unreleased in the changelog). Known debt: runtime/engine.py (3,284 lines) is a self-acknowledged "god class" mid-extraction, and docs/ARCHITECTURE.md in the repo still describes the parent monorepo's layout — the docs here reflect the actual package.

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