tomevault-io Component Guide
Interactive wizard to help users pick the right happysimulator components for their simulation.
Instructions
Ask the user what system they want to model if not specified. Get a brief description of the scenario (e.g., "a web service with retries", "a factory with breakdowns", "a social network with opinion spread").
Read the project's CLAUDE.md for the full component catalog.
Map the user's scenario to the best-fit components. Use this decision tree:
Does it have a queue + processing?
→ QueuedResource (override handle_queued_event() and has_capacity())
→ With priority? Use PriorityQueue policy
→ With balking? Use BalkingQueue policy
→ With reneging? Use RenegingQueuedResource
Does it need load generation?
→ Deterministic: Source.constant(rate=N, target=entity)
→ Stochastic: Source.poisson(rate=N, target=entity)
→ Time-varying: Source.with_profile(profile=MyProfile(), target=entity)
→ Custom events: Implement EventProvider and pass to Source()
Does it involve a network of nodes?
→ Network + add_bidirectional_link() + link condition factories
→ Need partitions? network.partition([a], [b]) / partition.heal()
→ Need clock skew? NodeClock(FixedSkew(...)) or NodeClock(LinearDrift(...))
→ Need causal ordering? LamportClock, VectorClock, or HybridLogicalClock
Does it need consensus or replication?
→ Leader election + log replication: RaftNode
→ Classic consensus: PaxosNode or FlexiblePaxosNode
→ Eventual consistency: CRDTStore with GCounter, PNCounter, LWWRegister, ORSet
→ Primary-backup: PrimaryNode + BackupNode
→ Chain replication: ChainNode
Does it need resilience patterns?
→ Fail-fast after errors: CircuitBreaker
→ Limit concurrency: Bulkhead
→ Limit wait time: TimeoutWrapper
→ Backup request: Hedge
→ Graceful degradation: Fallback
Does it need rate limiting?
→ Token bucket: RateLimitedEntity + TokenBucketPolicy
→ Leaky bucket: RateLimitedEntity + LeakyBucketPolicy
→ Burst suppression (no throughput cap): Inductor
→ Adaptive: RateLimitedEntity + AdaptivePolicy
Does it need contended resources?
→ Resource("name", capacity=N) + yield resource.acquire(amount) + grant.release()
→ With preemption? PreemptibleResource
→ Pooled with fixed cycle? PooledCycleResource
Is it an industrial/operations scenario?
→ Assembly line: ConveyorBelt + InspectionStation
→ Batch processing: BatchProcessor
→ Shift-based staffing: ShiftSchedule + ShiftedServer
→ Equipment breakdowns: BreakdownScheduler
→ Inventory management: InventoryBuffer or PerishableInventory
→ Scheduled arrivals: AppointmentScheduler
→ Gate/valve control: GateController
→ Fan-out/fan-in: SplitMerge
→ Conditional routing: ConditionalRouter
Is it behavioral / agent-based?
→ Individual agents: Agent + PersonalityTraits + decision model
→ Population: Population.uniform() or Population.from_segments()
→ Social influence: Environment + influence model (DeGrootModel, BoundedConfidenceModel, VoterModel)
→ Stimuli: broadcast_stimulus(), price_change(), influence_propagation()
Does it need storage / database modeling?
→ Key-value: KVStore
→ With cache: CachedStore
→ Sharded: ShardedStore
→ LSM tree: LSMTree + compaction strategies
→ Transactions: TransactionManager with IsolationLevel
Does it need messaging / streaming?
→ Pub/sub: MessageQueue + Topic
→ Event log: EventLog + ConsumerGroup
→ Stream processing: StreamProcessor
→ Dead letters: DeadLetterQueue
What should collect results?
→ Latency tracking: Sink (auto-tracks from context["created_at"]) or LatencyTracker
→ Event counting: Counter
→ Throughput: ThroughputTracker
→ Time series: Probe + Data
Present the recommended components with:
- A brief explanation of why each was chosen
- A minimal wiring example showing how they connect
- The most relevant example file(s) from
examples/for reference
Ask if the user wants to scaffold the full simulation (
/happy-sim-scaffold).
Converted and distributed by TomeVault — claim your Tome and manage your conversions.