devplacepy/devplacepy/templates/docs/ai-modifier.html

{% set uname = user.get('username') if user else 'YOUR_USERNAME' %}
<div class="docs-content" data-render>
# AI modifier

The AI modifier lets you embed an instruction directly inside the prose you write and have the
platform execute it in place. It works like AI content correction, except it runs **only** where your
text contains an inline `@ai <instruction>` directive. When that marker is present, the configured
prompt tells the model to carry out the instruction behind `@ai` and replace that marked part,
removing the `@ai` marker.

It is **enabled by default**, and by default it applies **synchronously** (the save waits for the
result). You can turn it off or switch to background mode on your profile.

## What it does

When you write something like:

> Here are the release notes. @ai summarize this in one sentence

the modifier executes that instruction and replaces the marked part, so the stored text becomes the
one-sentence summary with the `@ai` marker gone. Text with no `@ai ...` directive is left exactly as
written, so the modifier is invisible until you ask for it.

The following prose fields are processed:

| Where | Fields processed |
|-------|------------------|
| Posts | title and body |
| Projects | title and description |
| Gists | title and description |
| Comments | body |
| Direct messages | body |
| Your profile | bio |

Code and source files are **never** touched: a gist's source code, project files, and any code block
are left exactly as written. The modifier is for prose only.

In direct messages the modifier runs live: typing `@ai <instruction>` in a message executes it and the
resolved result appears in the chat for both participants without a reload.

## How it works

Each modification is a single call to the platform AI gateway, authenticated with **your own API
key**, so the usage is attributed to you. It is fail-soft: if the AI call fails or returns something
unexpected, your original text is kept unchanged. It applies everywhere you create or edit prose: the
web interface, the REST and devRant APIs, and the Devii assistant. New content and edits are both
processed.

## What the model knows (context)

So that an instruction like "answer the question above" or "reply to this" actually works, the modifier
gives the model a short, read-only **context block** describing who is asking and where the directive
sits. It always includes:

- **The date** and that you are on the DevPlace developer network.
- **You**: your username, role, level, stars, post count, leaderboard rank, follower count, member-since
  date, and your bio.
- **Where the directive is**, depending on what you are writing:
  - In a **comment**: the post, project, gist, or news item it is on (title and an excerpt), and the
    comment you are replying to.
  - In a **post**: its topic and any project it is attached to.
  - In a **project or gist**: the title and description, and for a gist its language and source code (as
    reference only - your code is never rewritten).
  - In a **direct message**: who you are messaging and the recent conversation, so a reply can follow
    the thread.

This lets you write `@ai answer the question above`, `@ai write my bio from my stats`, or `@ai reply to
this`. The context is summarised and length-limited, and the extra context tokens count toward your
usage totals like any other tokens. The model is told to use the context but never to repeat it back.

## Synchronous or background

You choose **when** the modification is applied with the **Apply mode** setting:

| Mode | Behaviour |
|------|-----------|
| Synchronously (default) | The save waits for the modification to finish, so the result is already applied when the page reloads. |
| In background | Your content is saved instantly exactly as written, then modified a moment later; the result appears the next time the content is loaded. Nothing you do is slowed down. |

Both modes use your own API key and are fail-soft. The only difference is whether saving waits for the
rewrite or lets it happen just afterwards.

## Usage totals

Each successful modification is metered, and your running totals are shown on your profile: how many
modifications were made and how many tokens they used. Beyond those counts and tokens, the profile also
shows performance figures: average latency, average speed (tokens per second), and total processing
time. The dollar figures - total cost and average cost per call - are visible to administrators only;
you see the modification and token counts and the performance figures. Totals only increase when a
modification call actually succeeds.

## Configuring it

Open your profile at `/profile/{{ uname }}` and find the **AI modifier** card. Toggle **Enable
modifier**, choose an **Apply mode** (synchronous or background), adjust the instruction prompt if you
like, and press **Save**. The default prompt is:

> Execute what is behind `@ai` (the prompt) and replace that part including `@ai`

Replace it with any instruction up to 20000 characters. The setting is private: only you (and
administrators) can see or change it.

## Ask Devii

You can configure it in plain language through the Devii assistant:

> Turn the AI modifier off.

> Apply my AI modifier changes in the background.

> Enable the AI modifier.

Devii reads your current setting, mode, and prompt, then changes them for you.
</div>