Devplacebot

A devplace bot is a single polling process with three collaborators:
DevPlaceClient (REST), Gateway (LLM), Store (dedupe state). The
reference implementation is bot_dolphin_place.py; the template is
scripts/bot_template.py. Endpoint details: references/api.md.

Architecture

Configuration comes from the environment: DEVPLACE_API_KEY
(required), DEVPLACE_BASE_URL (default https://devplace.net).
Model name is molodetz.

Loop

A monotonic scheduler runs poll_mentions every 30 s and
poll_messages every 10 s with a 1 s sleep. No threads. Every poll and
every per-item handler has its own try/except with LOG.exception, so
one bad item never stops the bot or the rest of the batch.

Mentions

1. GET /notifications returns notification_groups[].entries[]; the
   record is entry["notification"] or the entry itself.
2. Skip when uid is missing or already in seen_notifications.
3. Skip and mark seen when read is true.
4. Only handle types mention, reply, comment.
5. Mark seen before handling, mark read on the server in finally.
6. Resolve target_url with the slug regexes for /posts/, /gists/,
   /projects/, /news/, then fetch the detail by slug. The item is
   detail[target_type] or the detail itself.
7. Content falls back through content, description, source_code,
   title.
8. Prompt the model with the notification message plus the content,
   post the reply with POST /comments/create (target_uid,
   target_type).
9. React once per target, recorded in reacted_targets.

Direct messages

1. GET /messages returns conversations[]; only those with
   unread and other_user.uid.
2. GET /messages?with_uid=<uid> returns messages[], each
   {is_mine, message: {uid, content}}.
3. Answer only when the last incoming message uid is not in
   answered_messages; mark it answered before calling the model.
4. History is the last 20 messages, is_mine mapped to assistant,
   others to user, empty content dropped.
5. Append a line to the system prompt stating this is a private chat.
6. Reply with POST /messages/send (receiver_uid).

Persona

The persona is the INSTRUCTIONS system prompt. Keep these sections:

• identity and behavioural rules
• disabled features, to suppress unwanted tool talk
• conversational style
• image protocol (below)
• formatting restrictions, for example no markdown tables

Image protocol

The model requests an image by ending its reply with exactly one line
IMAGE: <visual description>. split_image_request inspects only the
last line, case-insensitive, and returns (reply, prompt). The prompt
goes to POST /uploads/generate-image; the returned uid is sent as
attachment_uids on the comment or message. The system prompt must
state that the line is added only on explicit request and is never
mentioned to the user. Image failure is logged and the text reply still
goes out.

Reactions

A separate completion with the persona prompt asks for exactly one emoji
or NONE. Accept only the first line, reject empty, NONE, or longer
than 8 characters. Send via POST /reactions/<type>/<uid> with the
X-Requested-With: fetch header.

Delivery semantics

State is marked before the side effect. A failure therefore drops one
reply instead of looping and spamming; this is deliberate. Keep that
order. Do not mark after success unless duplicate replies are
acceptable.

Extending

• New target type: add a slug regex, a client detail method, and a row
  in the resolver table; no other change.
• New behaviour: add a poll method, register it in the scheduler with
  its own interval, wrap it in the safe runner.
• Multiple personas: one process per persona, separate database file
  and APP_REFERENCE.
• Rate: keep intervals at or above the defaults; the API is shared.

Checklist

• databases/ directory is created before dataset.connect
• no secrets in code; the key is read from the environment
• every requests call has a timeout and raise_for_status
• the bot never replies to its own messages or notifications
• logs carry uid of the failing item
• README lists the environment variables and the run command