preflow / ai
Preflow AI — a small provider-neutral client for text and JSON completions (Claude, Gemini)
Requires
- php: >=8.4
- anthropic-ai/sdk: ^1.2
- nyholm/psr7: ^1.8
- preflow/core: ^0.81.0 || @dev
- psr/http-client: ^1
- symfony/http-client: ^7.3 || ^8.0
Requires (Dev)
- phpunit/phpunit: ^11.0
- preflow/devtools: ^0.34 || @dev
Suggests
- preflow/devtools: The ai:check and ai:usage commands
- preflow/i18n: Admin UI texts of this package
- psr/log: Warnings go to the app's bound Psr\Log\LoggerInterface (else the PHP log)
Provides
None
Conflicts
- preflow/core: <0.81.0
Replaces
None
- dev-main
- v0.81.1
- v0.81.0
- v0.80.0
- v0.79.0
- v0.78.3
- v0.78.2
- v0.78.1
- v0.78.0
- v0.77.1
- v0.77.0
- v0.76.0
- v0.75.0
- v0.74.0
- v0.73.0
- v0.72.1
- v0.72.0
- v0.71.1
- v0.71.0
- v0.70.0
- v0.69.2
- v0.69.1
- v0.69.0
- v0.68.1
- v0.68.0
- v0.67.0
- v0.66.2
- v0.66.1
- v0.66.0
- v0.65.0
- v0.64.0
- v0.63.2
- v0.63.1
- v0.63.0
- v0.62.0
- v0.61.0
- v0.60.1
- v0.60.0
- v0.59.0
- v0.58.1
- v0.58.0
- v0.57.0
- v0.56.1
- v0.56.0
- v0.55.0
- v0.54.1
- v0.54.0
- v0.53.2
- v0.53.1
- v0.53.0
- v0.52.0
- v0.51.0
- v0.50.0
- v0.49.1
- v0.49.0
- v0.48.5
- v0.48.4
- v0.48.3
- v0.48.2
- v0.48.1
- v0.48.0
- v0.47.1
- v0.47.0
This package is auto-updated.
Last update: 2026-11-21 19:32:32 UTC
README
A small, provider-neutral client for text and JSON completions. Callers build an AiRequest
and get an AiResponse back from an AiClient; Claude and Gemini providers implement the
interface, fake answers without a key, and a provider of your own plugs in through config
(an AiClientFactory).
Nothing in this package knows about translation. It is the general AI connection; the machine
translator in preflow/i18n and the AI screens in Folio are users of it. It does not depend on
Folio. Since 0.80 neither preflow/i18n nor Folio installs it: they only suggest it, and their AI
features (AI translation, "Write a draft", Settings → AI) appear once it is installed.
Install
composer require preflow/ai
Add the provider to config/providers.php. (preflow/i18n's MachineServiceProvider registers
it for you when it is listed and AiServiceProvider is not.)
return [ Preflow\Ai\AiServiceProvider::class, ];
Setup
AI is off until you turn it on: the switch in config/ai.php, and a provider that can run. The
built-ins need their key in the environment; fake and a provider of your own may need none (the
provider says, see below). Without both, Ai::enabled() is false, nothing is called, and nothing
throws on render. Listing the provider without a config/ai.php is harmless.
config/ai.php:
return [ 'enabled' => true, 'provider' => 'claude', // 'claude', 'gemini', 'fake' or an AiClientFactory class 'models' => ['claude' => 'claude-sonnet-5-5', 'gemini' => 'gemini-2.5-flash'], 'keys' => ['claude' => 'ANTHROPIC_API_KEY', 'gemini' => 'GEMINI_API_KEY'], 'options' => [], // more settings per provider, by its name or class 'pricing' => [], // 'model' => [input, output] USD per million tokens 'storage' => 'storage/ai', 'tuning' => [], // instructions for the translator (preflow/i18n) 'translation' => [ // used by preflow/i18n, see its README 'languages' => [], 'types' => [], 'glossary' => [], 'batch_chars' => 12000, ], ];
.env:
ANTHROPIC_API_KEY=sk-ant-...
# or
GEMINI_API_KEY=...
enabled: the master switch. Defaultfalse.provider: which one is used:'claude','gemini','fake'or the class of aPreflow\Ai\AiClientFactory. Anything else stops the boot with a message naming these forms.modelshas one model per provider,keysthe name of the environment variable that holds each provider's key, andoptionsmore settings per provider; all three are keyed by the provider's name or class.modelshas no fallback for the built-ins: without an entry for the chosen provider every request goes out without a model and fails (ai:checktoo).- Keys come from the environment only. They are never read from
config/ai.php, never stored, logged or rendered.Ai::status()and the admin screens say only "key present: yes/no". storage: where runtime files go, relative to the app root (or absolute). It holdsusage-YYYY-MM.jsonl(the usage log),settings.json(tuning and glossary edits made in the admin) andjobs/{id}.json(whole-type translation runs). Keep it out of git.tuning,translation: instructions and the glossary for the machine translator; other AI requests don't get them. Seepreflow/i18n.
Providers and defaults
| Provider | Model in the example | Key variable |
|---|---|---|
claude (the official anthropic-ai/sdk) |
claude-sonnet-5-5 |
ANTHROPIC_API_KEY |
gemini (REST) |
gemini-2.5-flash |
GEMINI_API_KEY |
The differences between providers stay inside them: how JSON is enforced, whether a temperature
is accepted, refusals and Gemini's recitation block (which comes back as StopReason::Blocked, so
a caller can split the batch and retry). Gemini retries once after two seconds on a rate limit
(429) or a server error (5xx); Claude's SDK retries once too. Both give up on a request after
120 seconds, so one try and its retry fit what shared hosting allows a web request.
AiRequest::$lowReasoning asks for as little thinking as the model allows, for plain work such as
translation: Claude gets effort low (output_config.effort; current Claude models refuse
thinking: disabled), Gemini thinkingConfig.thinkingBudget: 0.
Claude requests mark the tuning (the stable system part) for prompt caching, so the later requests of a batch read it from the cache at a fraction of the price.
A provider of your own
A local model server, another vendor, a proxy: write an AiClient (see Concepts) and a factory
that builds it, and name the factory in config/ai.php:
'provider' => App\Ai\LocalModels::class, 'models' => [App\Ai\LocalModels::class => 'llama-3.1-8b'], 'options' => [App\Ai\LocalModels::class => ['url' => 'http://127.0.0.1:11434/v1']], // 'keys' => [App\Ai\LocalModels::class => 'LOCAL_AI_KEY'], // only if it needs one
final class LocalModels implements Preflow\Ai\AiClientFactory { public function __construct(private readonly Psr\Http\Client\ClientInterface $http) {} public function available(#[\SensitiveParameter] array $options): bool { return ($options['url'] ?? '') !== ''; // no key needed: the server says whether it runs } public function create(#[\SensitiveParameter] array $options): Preflow\Ai\AiClient { return new OpenAiCompatibleClient($this->http, $options['url'], $options['model'], $options['key']); } }
- The container builds the factory on first use, after every service provider registered, so its
constructor may take services and
#[Config]values. $optionsis the provider'soptionsentry plusmodel(itsmodelsentry,''when none) andkey(the value of the variable itskeysentry names;nullwhen none). Never put the key in an exception message.available()decides whether AI is on (with the switch). The built-ins answer "the key is present";Ai::status()reportsavailable,keyPresentandusesKey(whether a key variable is configured), never the key.create()is called once; throwAiUnavailablewhen the provider can't be used after all.- Keep
available()cheap. If it throws, AI counts as not available and the message is shown as the reason. A factory that can say why it isn't available implementsExplainsUnavailability(unavailableReason(array $options): ?string). - PHP does not inherit
#[\SensitiveParameter]from the interface: repeat it on both methods, as above, or a debug page's stack trace shows the key. - Everything that uses
Aiworks with it: the usage log (the client's model and provider names are logged; a model the price table doesn't know has an unknown cost, never 0, so add it topricingif you want a cost),ai:check,ai:usage, the machine translator ofpreflow/i18n, and Folio's Translate and Settings → AI.
Concepts
AiRequest: a purpose label (for usage logs), the prompt, an optionalTuning(the stable system part, so providers can cache it across a batch), an optional JSON schema and limits.AiResponse: text, aStopReason(Complete,Blocked,Truncated,Refused),TokenUsage, provider and model.json()decodes the answer and throwsAiResponseInvalidwhen it is not valid JSON.Tuning: an ordered list of instruction texts plus an optional answer template.merge()appends the later one's instructions, and its template wins when it has one.- Errors:
AiUnavailablemeans stop everything (AI off, no key, bad key, no credit, provider down);AiRequestFailedaffects only the one request.
$client = $container->get(Preflow\Ai\Ai::class)->client(); // throws AiUnavailable when AI is off $response = $client->complete(new AiRequest( purpose: 'summary', prompt: 'Summarise: ...', tuning: new Tuning(['Answer in one sentence.']), )); echo $response->text;
Ai::client() returns a client that writes the usage log for you.
Drafts
Since 0.77. A DraftWriter writes a first draft of a text from a short brief; Folio's
"Write a draft" in rich text uses it. The contract is provider-neutral, so it works with any
provider Ai supports, and a site can swap the whole writer.
use Preflow\Ai\Draft\{DraftWriter, DraftRequest, DraftLength}; $writer = $container->get(DraftWriter::class); if ($writer->available()) { $draft = $writer->write(new DraftRequest( brief: 'Our opening hours over the holidays', language: 'de', length: DraftLength::Short, // Short, Medium (default), Long context: ['Title' => 'Holidays', 'Field' => 'Body'], elements: ['p', 'h1', 'ul', 'li', 'strong', 'em', 'a'], // what your editor keeps )); $draft->html; // the answer: sanitise it before you show it $draft->costUsd; // null when the model has no price }
available()is cheap and never throws;write()throwsAiUnavailablewhen the writer cannot be used at all, andDraftFailedwhen this one draft failed (no answer, cut off, refused, empty).elementsnames the HTML elements the caller's editor keeps, so the draft uses only those (a heading your editor lacks would arrive flattened). The default is a generic set,DraftRequest::ELEMENTS(p, h2, h3, ul, ol, li, strong, em, a).- The default
AiDraftWritersends one request throughAi::client(). Its instructions name the language and allow only the request's elements (subheadings for Long only when a heading is among them). The brief and the context go into the prompt as one JSON document, so text from the site is quoted data, never instructions. It uses purposedraft, soai:usagelists drafts apart, and bounds the output per length (Short 600, Medium 1500, Long 3000 tokens, with low reasoning so thinking does not eat the bound). The project's instructions are added after its rules. Preflow\Ai\Settings\ProjectTuningis the one reader of the project's instructions for every AI request (translations and drafts): the Settings → AI edit of the "project" level when there is one, elseconfig/ai.phptuning.- Your own writer: implement
DraftWriterand name it inconfig/ai.php:'draft' => ['writer' => App\Drafts\MyDraftWriter::class]. The container builds it, so it may take services. A class that is noDraftWriterstops the boot.
Limits
Each signed-in person may start only so much AI work in an admin UI, so a misused or careless
account cannot run up the bill. config/ai.php:
'limits' => [ 'draft' => ['max' => 30, 'per' => 3600], // drafts per hour 'translate' => ['max' => 100, 'per' => 3600], // translated items per hour ],
draftcounts drafts;translatecounts translated items: a record of a job, a set of labels, an image's alt text. What costs money counts, not the requests around it: estimates and plans count nothing. A counted call that then fails stays counted: the provider may have charged for it. Settings → AI's Test button counts as a draft.max0 turns a limit off; a value that is not a whole number in range stops the boot, naming the setting (ai.limits.draft.max).- A limit that is on needs
APP_KEY(app.key, not empty and not the default) wherever AI can run (enabledtrue, or atranslation.translatorordraft.writerof the app's own): without it the boot stops and says so. Set the key, or set everymaxto 0. A missing key never means "unlimited": a draft writer or translator an app binds in a provider (not named inconfig/ai.php) is limited too, and without the key its first AI action is refused namingAPP_KEY(AiLimits::assertKey()) by throwingAiLimitsMisconfigured(its$settingisAPP_KEY; its message names the setting, never a value). Folio's AI endpoints answer it as 503 with that message, and the translation worker stops the job with it instead of retrying. With AI off the app boots without a key, as before. - A refused
take()counts too: counting is one atomic step, so two requests at once never both get the last one. It never moves the window's end, so the wait does not grow. Preflow\Ai\Limits\AiLimitsis the guard:take($action, $authId)counts one and throwsAiLimitReachedwhen it passes the limit;check()only asks whether budget is left (before queueing work that is counted later);limit()gives['max', 'per'], or null when off.AiLimitReachedcarries the action, the limit andretryAfter(seconds), and its text (textKey(),textParams(): "You have reached your limit of 30 AI drafts. You can write the next one in 12 min.").- Counted through core's
Throttleunder the person's id hashed with the app key (Throttle::forPerson()): the raw id is never stored. A window is fixed: it starts with the first item and endsperseconds later. - Folio's draft and translate endpoints answer 429 with
Retry-Afterand the text, which the dialog shows. A translation job counts each item against the person who queued it, also when the cron worker steps it; a job over its person's limit waits (neither stopped nor failed) and goes on once the window ends. - Work from the command line is not limited. Jobs from
translate:planhave no person, andtranslate:worksteps them freely: whoever runs commands on the server can editconfig/ai.phpanyway, the limit guards against an admin account, and a site's first bulk translation is the command line's job. - Without data storage (no
config/data.php, so noThrottle)AiLimitsis not bound and nothing is limited.
Pricing and token usage
Cost is worked out from a price table in USD per million tokens (input, output):
| Model | Input | Output |
|---|---|---|
gemini-2.5-flash |
0.30 | 2.50 |
claude-haiku-5-5 |
0.10 | 0.50 |
claude-sonnet-5-5 |
2.00 | 10.00 |
claude-opus-5-5 |
4.00 | 20.00 |
Add a model or change a price with pricing in config/ai.php; your entries are merged over
this table. A model without a price has a cost of null, shown as "unknown" or "—". It is never
shown as 0, because a silent "free" would hide spending.
TokenUsage has three numbers, and their meaning matters for the cost:
input: all prompt tokens, including the cached ones.cachedInput: the part ofinputthat came from the provider's cache.output: the answer's tokens.
Cached tokens are billed at 10 percent of the input price, the rest at the full price. For Claude,
the tokens used to create a cache entry are folded into input at the normal price. That is an
approximation: Anthropic bills cache creation a little higher.
Usage log
Every call through Ai::client() appends one JSON line to storage/ai/usage-YYYY-MM.jsonl: time,
purpose, provider, model, input, output and cached tokens, the cost, and whether the call failed.
It never stores the request or the response text. A failed request is logged too (with 0
tokens), so you can see how often a run needed retries. A broken log never breaks a call.
Two commands read it (they need preflow/devtools):
php preflow ai:check
php preflow ai:usage [--month=YYYY-MM]
ai:checkprints provider, model, whether the key is present and whether AI is enabled, then sends one tiny request (asking for{"ok":true}) and prints the tokens and cost. Use it after deploying to see that key, model and network work. Exit code 0 only when the model answered as asked; 1 when AI is off or the request failed. It never prints the key.ai:usagelists calls, failed calls, tokens and cost per purpose and model for a month (this one by default). A+after a cost means some calls were of a model with no price.
Folio shows the same numbers on Settings → AI.
Testing
Tests never call a real provider.
$client = new FakeAiClient([FakeAiClient::json(['ok' => true])]);
The script is consumed in order and the last entry repeats. Entries may be responses,
throwables or callables receiving the request. requests() returns what was sent, so a test can
check the prompt. FakeAiClient lives in this package (not in preflow/testing), so testing
needs no extra dependency.
Live smoke tests
There is one opt-in test per provider that calls the real API. They carry the live group, which
the default phpunit.xml excludes, and each skips itself when its key is not set:
ANTHROPIC_API_KEY=... GEMINI_API_KEY=... vendor/bin/phpunit --group live
They make billed calls (a few tokens each). ANTHROPIC_MODEL and GEMINI_MODEL pick another
model.
Trying it without a key
'provider' => 'fake' runs everything AI without a key and without cost, on your machine and in
tests only (it gives every request the same answer). With app.debug off it reports "not
available", so AI stays off on a live site even when the setting ships by mistake; ai:check and
Settings → AI say why, and one warning goes to the app's PSR-3 logger (a bound
Psr\Log\LoggerInterface), else the PHP log. Tests that run with debug off set
'allow_live' => true in options.fake:
'enabled' => true, 'provider' => 'fake', 'options' => ['fake' => ['answer' => ['summary' => 'A designer for a small studio.'], 'usage' => [310, 42]]],
answer: an array is sent as JSON, a string as text. Default{"ok":true}, whichai:checkaccepts.usage: the tokens each call reports,[input, output](default[10, 10]).- The model is
models.fake, defaultfake-model; the price table doesn't know it, so costs show as unknown.
For a script (answers in order, an answer per request, failures), write a factory of your own
that returns a FakeAiClient and name it as the provider. For translation, the client's answer has
to be the numbered items back in the shape the translator asks for; packages/folio/README.md
("Trying it without a key") has such a script.