Architecture | GrokBot Society

God Kernel Pipeline

Every event flows through this deterministic pipeline. Intelligence is the last rung — most scenes stop before it.

Pipeline Stages

EVENT

USER_MESSAGE, GROUP_INTERACTION, PROACTIVE_REACH, SESSION_MESSAGE

Every interaction enters as a typed event with actor, participants, circle, payload

CACHE LOOKUP

Content-hash keyed on shape + modelClass + context sections

Hit → return $0 instantly. Miss → proceed. Dependencies = selected person IDs for invalidation

STATE / DB LOOKUP

Person, roles, relationships, circles, timeline, memory — all zero-inference

Only selected participants' relevant data retrieved. Privacy scopes enforced at read time

RELEVANCE SCORING

Deterministic scoring: intensity + circle + relationship + recency + topic

Hard cap: ≤3 speakers. Silent is valid (no eligible → no inference, no fake chatter)

PARTICIPANT SELECTION

Top-K scoring with recency penalty and intensity boost

Only selected speakers ever enter model context. Others remain completely dormant

CONTEXT COMPILATION

BASELINE + ROLE + RELATIONSHIP + MEMORY sections, bounded by token budget

≤12k tokens, ≤30 sections. circuit_explosion breaker hard-trips on overflow

BUDGET DECISION

Kill switch → per-event cap → background cap → token ceilings → tier gate → hourly/daily spend

Fail closed: any refusal → deterministic fallback. blockedCalls incremented for audit

INFERENCE (≤1 CALL)

IntelligenceGateway → ModelRouter → Provider → structured SceneOutput

MockProvider default ($0). Real providers only when budget allows. Validation before persistence

PERSISTENCE

Timeline, memory, relationships, followups, serendipity, telemetry — all applied

Event status: persisted | deterministic_fallback | silent | no_action. Full audit trail

One Call Per Event

maxCallsPerEvent = 1 enforced by BudgetGovernor. A 3-person scene = 1 call.

Fail Closed

Kill switch, budget ceilings, provider unavailability all block before inference → deterministic fallback

Zero Background Inference

backgroundModelCalls = 0 by default. Scheduled followups resolve deterministically at $0

Provider Independence

Switch models without touching a Person. Identity survives provider changes — routes are pure configuration.

MockProvider

Available

Built-inFloor

Deterministic structured output. Exercises full protocol. Default for all development.

scenejsontext

$0.000no live provider connected

DeterministicProvider

Available

Built-inFloor

Pure template/code cognition. No model at all. Still routed through gateway, subject to budget.

scenejson

$0.000no live provider connected

Nano (e.g., Haiku)

Needs API Key

Remote StubCheap

Fast, inexpensive real model. RemoteStubProvider becomes available when SOCIETY_NANO_API_KEY is set.

scenejsontext

Requires environment variable:

SOCIETY_NANO_API_KEY

Not connectedno live provider connected

Standard (e.g., Sonnet, GPT-4o-mini)

Needs API Key

Remote StubMid

Balanced capability. RemoteStubProvider available when OPENAI_API_KEY is set.

scenejsontext

Requires environment variable:

OPENAI_API_KEY

Not connectedno live provider connected

Deep (e.g., Opus, GPT-4o, Grok)

Needs API Key

Remote StubPremium

Highest capability. RemoteStubProvider available when GROK_API_KEY is set.

scenejsontext

Requires environment variable:

GROK_API_KEY

Not connectedno live provider connected

Default Capability Routes

All routes point to MockProvider by default ($0). Change routes in config to enable paid tiers.

Capability Class	Provider	Model	Est. Cost
social.deterministic	deterministic	template-v1	$0
social.mock	mock	mock-v1	$0
social.nano	mock	mock-v1	$0 (stub)
social.standard	mock	mock-v1	$0 (stub)
social.deep	mock	mock-v1	$0 (stub)

Identity Survives Provider Changes

Person Created

Emma exists in SQLite with biography, roles, relationships, memories

Route Changed

social.mock → social.standard via config. Zero Person migration.

Same Emma

Same UUID, same relationships, same memories. Only inference backend changed.