Give the AI subsystem one profile table and one collection, read everywhere
This commit is contained in:
Gmer4Lfe
@@ -0,0 +1,192 @@
|
||||
<?php
|
||||
// ═══════════════════════════════════════════════════════════════════════════════════════════════
|
||||
// PURPOSE
|
||||
// The one definition of what an AI profile is. Every consumer — the endpoint, the worker, the
|
||||
// shared chat include, the Scheduler dock — reads it from here instead of restating it.
|
||||
//
|
||||
// WHY THIS EXISTS
|
||||
// A profile used to be defined in five places: history depth in api/ai.php, capabilities in
|
||||
// include/ai.php, label/hint/depth again in the chat's JavaScript, a prompt branch in the
|
||||
// worker, and a label map in pages/scheduler.php. They had already drifted — the JavaScript
|
||||
// knew three profiles where PHP knew four, so the shared chat could not offer troubleshoot at
|
||||
// all and the Scheduler dock hand-rolled its own labels to compensate. The include carried a
|
||||
// comment telling the next person not to let the two tables diverge, which is a comment doing
|
||||
// a data structure's job.
|
||||
//
|
||||
// WHAT LIVES HERE, AND WHAT DELIBERATELY DOES NOT
|
||||
// Here: anything more than one file needs to agree on — the set of profiles, their labels and
|
||||
// hints, history depth, capabilities, and whether a profile is offered as a button.
|
||||
//
|
||||
// Not here: the system prompts. They are long, delicate, and have exactly one consumer, so
|
||||
// moving them would be churn against the most sensitive text in the subsystem for no reduction
|
||||
// in duplication. Tools/ai_chat_worker.php still owns them; it just keys off ids validated
|
||||
// here rather than an if-chain that invents its own vocabulary.
|
||||
//
|
||||
// CAPABILITIES ARE PER PROFILE, NOT PER CAPABILITY
|
||||
// The old table was inverted — capability => [profiles] — which reads well when adding a
|
||||
// capability and badly when answering the question actually asked at runtime, which is always
|
||||
// "what can this profile do". Same content, turned the right way round.
|
||||
//
|
||||
// A profile is a contract plus a set of inputs, and the inputs are the half that has to be
|
||||
// enforced rather than requested. The caps list is that half.
|
||||
//
|
||||
// It exists because the alternative already failed. The same permissions used to live as a
|
||||
// dozen `$profile === 'varaverk' || $profile === 'troubleshoot'` conditions spread across the
|
||||
// worker, and answering "may chat ever be shown a log?" meant reading all of them. It could —
|
||||
// a gate added for run-outcome questions granted it by omission, and the chat profile, whose
|
||||
// entire value is that it has NOT been shown this installation, was one phrasing away from
|
||||
// being handed a health sweep and 120 lines of log. Nothing about that was visible at the
|
||||
// point of the mistake. Here it would have been one missing word on one line.
|
||||
//
|
||||
// A capability is permission, not need. varaverk holds 'health' but only attaches it when the
|
||||
// question looks diagnostic; troubleshoot attaches it always. The gates decide whether an
|
||||
// input is warranted, this decides whether it is allowed, and a gate can never widen the grant.
|
||||
//
|
||||
// chat holding an empty capability list is a guarantee, not an oversight. Anything added to it
|
||||
// stops being general chat and becomes an assistant that sometimes lies about this
|
||||
// installation.
|
||||
//
|
||||
// EXPORTS
|
||||
// vv_ai_profiles() the whole table
|
||||
// vv_ai_profile($id) one entry, or null
|
||||
// vv_ai_profile_ok($id) is this a real profile
|
||||
// vv_ai_profile_turns($id) history depth in turns
|
||||
// vv_ai_profile_can($id,$cap) capability check
|
||||
// vv_ai_profile_caps($id) every capability a profile holds
|
||||
// vv_ai_profile_label($id) display name, falling back to the id
|
||||
// vv_ai_profiles_ui() those offered as buttons, in order
|
||||
// vv_ai_profiles_max_turns() deepest window of any profile
|
||||
// vv_ai_profiles_client() the subset the browser needs, for json_encode
|
||||
// vv_ai_profiles_script() publishes that subset as window.VvAiProfiles, once per page
|
||||
// ═══════════════════════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
// turns — conversation depth. Varaverk Assistant spends ~2500 of its 16384 on retrieved
|
||||
// passages so it cannot afford much; troubleshoot carries a whole log tail and can
|
||||
// afford least of all; the two that retrieve nothing can hold a real conversation.
|
||||
// caps — see VV_AI_CAP_MEANING below.
|
||||
// ui — appears in the profile bar. troubleshoot is false because it is entered by opening a
|
||||
// log on the Scheduler tab, not by choosing it: it is a context you are in, and a
|
||||
// button offering it from the dashboard would produce a troubleshooting contract with
|
||||
// nothing to troubleshoot.
|
||||
const VV_AI_PROFILES_DEF = [
|
||||
'varaverk' => [
|
||||
'label' => 'Varaverk Assistant',
|
||||
'short' => 'Assistant',
|
||||
'hint' => 'Answers only from Varaverk\'s own docs, with sources. Says so when they don\'t cover it.',
|
||||
'turns' => 3,
|
||||
'ui' => true,
|
||||
'caps' => ['retrieve', 'kind_filter', 'health', 'run_evidence', 'incidents', 'conf_lookup'],
|
||||
],
|
||||
'chat' => [
|
||||
'label' => 'General Chat',
|
||||
'short' => 'Chat',
|
||||
'hint' => 'Ordinary conversation. Hands anything about this install to the assistant on its own.',
|
||||
'turns' => 8,
|
||||
'ui' => true,
|
||||
'caps' => [],
|
||||
],
|
||||
'code' => [
|
||||
'label' => 'Code Sketcher',
|
||||
'short' => 'Code',
|
||||
'hint' => 'Drafts short scripts for Custom Scripts. First drafts — test before trusting.',
|
||||
'turns' => 4,
|
||||
'ui' => true,
|
||||
'caps' => ['code_scan'],
|
||||
],
|
||||
'troubleshoot' => [
|
||||
'label' => 'Troubleshoot',
|
||||
'short' => 'Troubleshoot',
|
||||
'hint' => 'Reasons from the log you have open, then the docs. Files a bug only when the evidence shows one.',
|
||||
'turns' => 2,
|
||||
'ui' => false,
|
||||
'caps' => ['retrieve', 'health', 'run_evidence', 'scoped_log', 'incidents', 'conf_lookup', 'file_bugs'],
|
||||
],
|
||||
];
|
||||
|
||||
// Documentation only — nothing branches on it. Kept beside the table because a capability name
|
||||
// with no stated meaning is how one ends up granted to a profile that should not have it.
|
||||
const VV_AI_CAP_MEANING = [
|
||||
'retrieve' => 'retrieval passages from the documentation index',
|
||||
'kind_filter' => 'the retrieval kind filter the page exposes',
|
||||
'health' => 'live health sweep measured at question time',
|
||||
'run_evidence' => 'run record and log tail for a script named in the question',
|
||||
'scoped_log' => 'log tail for whatever the operator currently has open',
|
||||
'incidents' => 'operator-written history of what previously went wrong with this thing',
|
||||
'conf_lookup' => 'deterministic "where does this conf key actually live" lookup',
|
||||
'file_bugs' => 'may file a bug report against Varaverk itself',
|
||||
'code_scan' => 'destructive-operation scan of generated shell',
|
||||
];
|
||||
|
||||
function vv_ai_profiles(): array { return VV_AI_PROFILES_DEF; }
|
||||
|
||||
function vv_ai_profile(string $id): ?array {
|
||||
return VV_AI_PROFILES_DEF[$id] ?? null;
|
||||
}
|
||||
|
||||
function vv_ai_profile_ok(string $id): bool {
|
||||
return isset(VV_AI_PROFILES_DEF[$id]);
|
||||
}
|
||||
|
||||
// Falls back rather than throwing. An unknown id reaching here is a caller that failed to
|
||||
// validate, and the shallowest window is the safe way to be wrong: it spends the least context.
|
||||
function vv_ai_profile_turns(string $id): int {
|
||||
return (int)(VV_AI_PROFILES_DEF[$id]['turns'] ?? 3);
|
||||
}
|
||||
|
||||
function vv_ai_profile_caps(string $id): array {
|
||||
return VV_AI_PROFILES_DEF[$id]['caps'] ?? [];
|
||||
}
|
||||
|
||||
function vv_ai_profile_can(string $id, string $cap): bool {
|
||||
return in_array($cap, VV_AI_PROFILES_DEF[$id]['caps'] ?? [], true);
|
||||
}
|
||||
|
||||
function vv_ai_profile_label(string $id): string {
|
||||
return VV_AI_PROFILES_DEF[$id]['label'] ?? $id;
|
||||
}
|
||||
|
||||
// Insertion order is the button order, and varaverk is first because the strict profile is the
|
||||
// one to land on: a misuse there costs "the docs don't cover that" rather than an invented claim
|
||||
// about the system.
|
||||
function vv_ai_profiles_ui(): array {
|
||||
return array_filter(VV_AI_PROFILES_DEF, fn($p) => !empty($p['ui']));
|
||||
}
|
||||
|
||||
// The cap api/ai.php applies when storing a conversation, which has to hold the deepest window
|
||||
// any profile could later ask for — a chat saved under one profile can be reopened under another.
|
||||
function vv_ai_profiles_max_turns(): int {
|
||||
return max(array_column(VV_AI_PROFILES_DEF, 'turns'));
|
||||
}
|
||||
|
||||
// What the browser needs, and nothing more. The prompts are not here to be sent and the server
|
||||
// re-derives depth and capability on every request regardless — this is for drawing buttons and
|
||||
// deciding whether to show the kind filter, not for the client to make policy with.
|
||||
function vv_ai_profiles_client(): array {
|
||||
$out = [];
|
||||
foreach (VV_AI_PROFILES_DEF as $id => $p) {
|
||||
$out[$id] = [
|
||||
'label' => $p['label'],
|
||||
'short' => $p['short'],
|
||||
'hint' => $p['hint'],
|
||||
'turns' => $p['turns'],
|
||||
'ui' => (bool)$p['ui'],
|
||||
'kind' => in_array('kind_filter', $p['caps'], true),
|
||||
];
|
||||
}
|
||||
return $out;
|
||||
}
|
||||
|
||||
// Publishes the registry to the browser as window.VvAiProfiles, once per page however many
|
||||
// surfaces ask for it. Emitted as its own tag so any script block that consumes it stays pure
|
||||
// JavaScript and remains syntax-checkable outside PHP.
|
||||
//
|
||||
// Both the shared chat include and the Scheduler dock call this. Before it existed the dock had
|
||||
// its own literal `{ code: 'Code', troubleshoot: 'Troubleshoot' }` map, which is how a fourth
|
||||
// copy of the profile list came to exist in the first place.
|
||||
function vv_ai_profiles_script(): void {
|
||||
static $done = false;
|
||||
if ($done) return;
|
||||
$done = true;
|
||||
echo '<script>window.VvAiProfiles = '
|
||||
. json_encode(vv_ai_profiles_client(), JSON_UNESCAPED_SLASHES) . ";</script>\n";
|
||||
}
|
||||
Reference in New Issue
Block a user