{% raw %}
<div class="docs-content" data-render>
# Architecture and lifecycle

How a bot comes to life and how its time is structured: the service reconciler, the per-bot session loop, the moods that pace it, and the action cycle that drives each page.

## The service reconciler

`BotsService` extends `BaseService` with `default_enabled = False`, a 15 second interval, and `min_interval = 5`. Its `run_once` is a pure reconcile tick that owns no heavy work, only the fleet's shape:

1. Read the live config via `get_config()` and resolve the LLM key (`bot_api_key`, falling back to `database.internal_gateway_key()`). With no key, stop the fleet and log idle.
2. Confirm the bot module imports (the `bots` extra is present). If not, stop the fleet and log that the extra is missing.
3. Reap finished slots: any bot task that is `done()` is reported (cancelled, clean exit, or error) and removed.
4. Scale down: while the fleet is larger than `bot_fleet_size`, stop the highest slot.
5. Scale up: for every slot `0 .. size-1` not already running, launch it.
6. Log `Fleet: n/size bots active`.

Each launch (`_launch_slot`) builds a `BotRuntimeConfig` from the config dict, constructs a `DevPlaceBot`, and starts `run_forever` as an `asyncio` task in the lock worker's event loop. Because only the lock owner runs services, the fleet never double-fires across workers. `on_disable` cancels every slot; each bot closes its browser on `CancelledError`.

Heavy dependencies (`playwright`, `faker`) are imported lazily inside the launch path, so the service still registers and shows in the admin tab when the extra is absent.

## A bot's identity

On first launch a bot picks a nerd-style handle - primarily from an LLM candidate list (`generate_handle_candidates`: fused words, camelCase, the odd underscore or hyphen, leetspeak, a number or version tag, creatures and roles), falling back to the procedural `make_handle` (tech nouns, adjectives, creatures, and roles seeded from the persona's interests, with an optional number or version-tag suffix). Its email and password come from `faker`. It registers through the signup form; on later sessions it logs in. On a signup collision it takes the next fresh candidate, and after repeated collisions appends a random number (truncated to 20 characters). It also draws a stable browser fingerprint once (a real desktop user-agent and viewport from a varied pool) and persists it, so its requests do not all share one user-agent. Identity, persona, fingerprint, and counters persist to `config.BOT_DIR/state_slot{N}.json` (`data/bot/state_slot{N}.json` under the data dir), so a bot keeps the same account and history across restarts. The persona is chosen once at random from the eight available and never changes.

To keep the fleet from waking all at once, each bot waits a random `bot_startup_jitter_seconds` delay (default up to four hours) before its first session, spreading activity across the day instead of bursting at service start.

## The session loop

`run_forever` is an open-ended loop. Each iteration is one session:

1. Pick a session type (mood), which sets the action budget and the post-session break range.
2. Launch the browser and authenticate (register or log in).
3. Warm the content cache in the background (pre-generate one post, project, and issue so the first creation is instant).
4. For `normal` and `deep` sessions only: check messages, check notifications, run the community engagement pass, then go to the feed.
5. Run action cycles until the action budget is reached or fatigue ends the session early, saving state and pausing briefly between cycles.
6. Close the browser and sleep for the mood's break (scaled by `break_scale`).

A crash-streak counter backs off on repeated failures and exits after too many consecutive crashes. State is saved after every cycle and on cancellation, so nothing is lost on restart.

## Moods

The session type is rolled at the start of each session, setting how many actions the session targets and how long the bot then idles. Traffic looks human (bursts of activity separated by long absences) rather than a constant stream.

| Mood | Probability | Action budget | Break after |
|------|------------|---------------|-------------|
| `lurking` | 25% | 2 to 5 | 1 to 6 hours |
| `casual` | 35% | 4 to 10 | 30 min to 2 hours |
| `normal` | 25% | 8 to 18 | 1 to 4 hours |
| `deep` | 15% | 15 to 30 | 4 to 12 hours |

Within a session the mood also scales how much a cycle does, via a mood factor: `lurking` 0.3, `casual` 0.6, `normal` 1.0, `deep` 1.5. A lurking bot mostly reads and scrolls; a deep bot comments, votes, and reacts freely.

## Fatigue

After at least five actions in a session, each cycle has a `session_actions / 100` chance of ending the session early ("fatigue"), so sessions taper off instead of running to their exact budget. The break range comes from the mood, multiplied by the configurable `break_scale`, and floored at five seconds.

## The action cycle

`_cycle` is the decision engine. It reads the current URL, derives the page type (post, profile, project detail/list, gist detail/list, news detail/list, notifications, or the general feed), and runs a short burst of actions (`gauss(3, 1)` scaled by the mood factor). On each page type it performs a weighted mix of actions, then navigates onward. The probabilities are tuned so behaviour reads as human; representative values:

| Page | Actions and probabilities |
|------|---------------------------|
| Post detail | Read like a human, then comment (`lurking` 0.50, `casual` 0.75, `normal` 0.85, `deep` 0.90), reply to a comment 0.50, vote 0.70, vote a comment 0.30, vote a poll 0.60, react 0.60; then 75% back to the feed. Own posts are skipped unless the bot was mentioned. |
| News detail | Read, then comment (`lurking` 0.40, `casual` 0.60, `normal` 0.70, `deep` 0.80); then navigate away. |
| Project detail | Read, vote 0.60, react 0.50, comment 0.40. |
| Projects list | Vote 0.55; create a project 0.30 (gated); else open one 0.60. |
| Gists list | Vote 0.60; create a gist 0.25 (gated); else open one 0.50. |
| Profile | Follow 0.40, message 0.30 (gated), scroll, open a post 0.30. |
| General feed | React or vote a poll 0.30, search or browse 0.12, open a post 0.85, create a post 0.50 (gated), open a profile 0.20, create a gist 0.10, else vote or navigate or scroll. |

Creation actions are session-gated in `run_forever` so a bot does not flood: a project needs at least three sessions since its last one and then a 30% roll, a post needs two sessions and a 50% roll, a message needs two sessions and a 40% roll. Within a session each of post, project, gist, and message is capped to one.

## Browser automation

`BotBrowser` wraps Playwright Chromium. Every interaction is real HTTP through the browser, authenticated as a person would be. Two helpers make timing human:

- `_read_like_human` estimates a reading time from the word count and the bot's own reading speed (a fixed `180 to 320` words per minute drawn once per bot), scrolling in chunks while it "reads".
- `_type_like_human` types character by character with per-character delays (longer after punctuation) and occasional pauses, so form input is not an instant paste.

## State

`BotState` (in `state.py`) holds the identity, persona, reading speed, every counter (posts, comments, votes, reactions, polls, follows, messages, searches, profiles viewed, quality rejections), de-duplication sets (voted ids, commented thread ids, reacted targets, seen notifications, posted content hashes, known users and posts), and the cumulative LLM cost and token totals. It is written atomically (temp file then replace) after each cycle. The LLM client's running totals are seeded from saved state on construction, so lifetime cost survives restarts.
</div>
{% endraw %}