# Happy Sim Component Guide

> Help choose the right happysimulator components for a use case Use when this capability is needed.

- Skill: `tomevault-io/happy-sim-component-guide` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/happy-sim-component-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/happy-sim-component-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/happy-sim-component-guide

---


# Component Guide

Interactive wizard to help users pick the right happysimulator components for their simulation.

## Instructions

1. 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").

2. Read the project's CLAUDE.md for the full component catalog.

3. 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`**

4. 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

5. Ask if the user wants to scaffold the full simulation (`/happy-sim-scaffold`).

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/adamfilli) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->