No. A Person is a durable database row (biography, personality, interests, social graph). A GrokBot is an optional inference route mapped to the `social.deep` capability class. The runtime works at $0 with `MockProvider` — no GrokBot required.
Frequently Asked Questions
Straight answers about architecture, costs, providers, and common misconceptions.
Agents burn inference continuously. In GrokBot Society, only selected speakers (≤3) enter a model context. The core 5,000-person simulator profile keeps 4,985 people dormant at $0.
No. One model call renders a scene with up to 3 speakers. The other 997 people exist in SQLite but never touch a model. Cost ≈ meaningful interaction, not population × time.
Yes. A single structured generation (SceneOutput) returns messages from multiple speakers. The SocialDirector selects ≤3 speakers, compiles their contexts, and sends ONE request. The provider returns all messages in one response.
Yes — this is a core invariant. `ModelRouter` maps capability classes (`social.mock` → `social.nano` → `social.standard` → `social.deep`) to providers. Switching routes never touches Person identity, relationships, memories, or timeline.
Yes. Default config uses `MockProvider` (deterministic, $0) and `DeterministicProvider` (template-only, $0). Real providers (nano/standard/deep) are opt-in stubs that require API keys. GrokBot is an optional `social.deep` route.
Yes. `social.mock` and `social.deterministic` are always $0. The entire test suite (42 tests), the demo (`pnpm dev`), and the CLI all run at $0 on MockProvider. Paid inference is strictly opt-in.
God (`GodKernel`) is the deterministic society kernel — application software that wires services, enforces budgets, routes events, materializes Actors, and persists outcomes. God does NOT think continuously, is NOT a person, and does NOT generate text directly.
Four privacy scopes enforced at read time: `private` (person only), `person_user_shared` (person + operator), `circle` (circle members), `public` (anyone). `MemoryService.retrieveForScene` filters every memory by the viewer's scope access. No omniscient hive mind.
No. This is a provider-neutral runtime for persistent synthetic societies — people with biographies, relationships, roles, circles, and evolving histories. The demo includes diverse archetypes (friend, mentor, travel companion, intellectual, wildcard). Use cases: social simulation, worldbuilding, companion research, agent architecture research.
Yes. The `person_user_shared` memory scope and relationship dimensions (familiarity, trust, affection) model human↔synthetic bonds. The user is an actor in scenes (`USER_MESSAGE` events). Relationships evolve with inertia — one interaction ≠ spouse.
BudgetGovernor refuses the reservation → scene resolves to deterministic fallback (template lines from selected speakers). `blockedCalls` increments in telemetry. No silent retries, no silent degradation. Fail closed, always auditable.
`setKillSwitch(true)` makes every `IntelligenceGateway.generate` throw `KillSwitchError` → deterministic fallback. `usage().blockedCalls` increments. Health checks still work. The runtime stays alive; inference is what fails closed.
Content-hash keyed on [modelClass, shape, provider:model, ...contextSections]. Dependencies = selected person IDs. When a person's state changes, their ID invalidates relevant entries. `repeated_cache_thrash` breaker trips on >8 consecutive misses.
9 advisory+audit breakers: duplicate_inference, same_event_recursion, rapid_event_explosion, excessive_retries, repeated_provider_failure, participant_fan_out, context_explosion (hard), premium_model_escalation (hard), repeated_cache_thrash. They don't kill the process but surface runaway patterns.
Yes. Implement the `Provider` interface, register via `gateway.register()`, add route in `ModelRouter`. The `RemoteStubProvider` pattern shows the scaffold. Identity survives provider changes — routes are pure config.
A Role is a reusable behavior definition (e.g., 'friend', 'mentor'). Assigning a role creates zero agents and costs zero inference. An Agent would be a continuously running process — this architecture explicitly prevents that. Actors are ephemeral per-scene compositions of Person + Roles.
`proactiveTick(circleId?)` evaluates candidates: relevance → cooldown → budget → intensity → minRelevance. Default off → all candidates audited as `NO_ACTION` (0 calls). When enabled: pacing score ≥ threshold, outside cooldown, within daily budget → ONE `PROACTIVE_REACH` scene per reach, capped at `maxReachesPerTick`.
Shared-history memories stored once per pair (`person_user_shared` scope, `scopeRef` = other person ID). 'Emma & Leo's first trail ritual' exists once, visible to both. Idempotent: re-adding same landmark does nothing.
`sessionStart` creates a session with kind, circle, participants. `sessionAppend` adds messages (user or person). `sessionContext` returns bounded rolling window (6 messages) + participant cards (4). Durable log is full; prompt context is never.
`relationshipLearningRate = 0.15`. A proposed delta (e.g., +0.2 familiarity) only lands 15% per scene. Status ladder: stranger → acquaintance → friend → close_friend → best_friend → romantic_interest → partner → spouse. One interaction ≠ spouse.
Set API key (`OPENAI_API_KEY`, `GROK_API_KEY`, `SOCIETY_NANO_API_KEY`), update routes in config to point capability classes at real providers, ensure budget allows. The `RemoteStubProvider` automatically becomes available when its env key is set.