CMDB Assistant Developer Guide

🛠️ CMDB assistant - Developer Guide

Since 5.3.0 · #313 · User page: CMDB - The CMDB assistant · Foundations: CMDB - Developer Guide

The CMDB assistant is a conversation with an AI configuration manager about one company's CMDB. It interviews the analyst (what the company does, its services, what they run on, where, what the CMDB should answer), remembers what it learns, and proposes classes, properties, relationship types and configuration items, each applied with one click after a preview.

This page is for someone changing it. Read CMDB - Developer Guide §4 first: the assistant does not write the schema itself - it hands a plan to the same plan engine the Starter classes button uses, and it creates CIs through CmdbService.

The decisions it is built on:

• the conversation is private - one per analyst per company;
• what it learns is the company's - shared by everyone who works in that company;
• remembering saves at once, shown as a Noted chip with Undo (no approval per fact);
• schema proposals are add-only - nothing already there is changed or removed;
• CI proposals are created in the analyst's active company, and only from names the analyst gave;
• one-click Apply after a preview;
• the gate is CMDB module access + cmdb.classes - no new capability.

---

1. 📁 The files

	File	What it does
⚙️	includes/cmdb/assistant.php	Everything about the conversation: the company, threads, messages, facts (remember / forget / undo / edit), coverage and stage, the read tools, the system prompt, one turn, open, summarise, preview, apply, Start again. The file header is the map
⚙️	includes/cmdb/assistant_proposals.php	What it may propose: the schema and objects proposal types - tool definition, check, describe, preview and apply for each
⚙️	includes/ai_conversation.php	Shared with the Projects assistant: history with what each proposal became, the open/resume decision, the memory fold, the reply language
⚙️	includes/cmdb/schema_plan.php · includes/services/cmdb_schema.php	The plan engine (cmdbPlanResolve / cmdbPlanApply) and CmdbSchemaService - see CMDB - Developer Guide §4
⚙️	includes/services/cmdb.php	CmdbService::createInTransaction(), createRelationship(), announceCreated() - what an objects proposal is applied through
🔌	api/cmdb/assistant.php	Routing only. Every rule is in includes/cmdb/assistant.php
🖥️	cmdb/includes/header.php	The Assistant button and the panel markup, on every CMDB page
🖥️	cmdb/settings/index.php	The Classes tab's "what the assistant has learned" link (data-ca-open="learned")
🖥️	assets/js/cmdb-assistant.js	The panel: Conversation and Learned views, Noted chips, proposal cards, Review, the Continue chip after an Apply (§5)
🖥️	assets/js/cmdb-schema-preview.js	The schema preview (shared with Starter classes)
🖥️	assets/js/cmdb-object-preview.js	The configuration item preview - CmdbObjectPreview.open({resolved, onApply, title, intro})
🎨	assets/css/cmdb-assistant.css	.ca-*, on top of the shared .ai-chat-* panel styles
🗄️	database/freeitsm.sql · includes/db_verify_schema.php	cmdb_ai_threads, cmdb_ai_messages, cmdb_ai_facts
🗄️	includes/analyst_lifecycle.php	Threads and messages are personal (go when an analyst is removed); facts' *_by_analyst_id are history (kept)
🌍	lang/*/cmdb.php	cmdb.assistant.* and cmdb.help.assistant_*
📄	cmdb/help.php	The in-module help section The CMDB assistant
🧪	tests/cmdb-assistant.php · tests/cmdb-assistant-proposals.php · tests/projects-assistant.php	See §10

---

2. 🗄️ Tables

cmdb_ai_threads   (id, tenant_id, analyst_id, summary MEDIUMTEXT, summary_upto_id,
                   created_datetime, updated_datetime)
                  UNIQUE (tenant_id, analyst_id)          -- one private conversation per analyst per company

cmdb_ai_messages  (id, thread_id, role user|assistant, kind chat|open|resume, content,
                   proposals JSON, looked_at JSON, learned JSON, analyst_id,
                   model, tokens_in, tokens_out, created_datetime)

cmdb_ai_facts     (id, tenant_id, topic, subject, statement, source assistant|user,
                   source_message_id, created_by_analyst_id, updated_by_analyst_id,
                   created_datetime, updated_datetime)
                  UNIQUE (tenant_id, topic, subject)      -- remembering the same subject replaces it

• summary / summary_upto_id - the long-term memory: older turns folded into a few bullets, and the last message folded in.
• proposals - a JSON list on an assistant message: {type, args, summary, status, error?, result?}, status pending | applied | dismissed | failed.
• looked_at - the read tools the turn used (shown under the reply).
• learned - the facts the turn noted, each {id, topic, subject, statement, prev, undone?}. prev is the statement it replaced (null for a new fact) - which is what Undo puts back. A remember that changed nothing (§4) is not in it.
• cmdb_ai_messages.analyst_id - the thread's analyst, so the analyst lifecycle can remove a leaver's conversation on installs that have no foreign keys.
• source_message_id has no foreign key on purpose: Start again deletes the conversation, the facts stay.
• Topics: organisation, service, hosting, tracking, application, network, devices, dependency, ownership, exclude, convention (cmdbAssistTopics()). The first four are the core topics (cmdbAssistCoreTopics()).

🔴 TRAP: code never relies on these foreign keys. Installs built by Database Verification have none (see CMDB - Developer Guide §5), so Start again deletes the messages, then the thread, by id:

$conn->prepare("DELETE FROM cmdb_ai_messages WHERE thread_id = ?")->execute([(int)$thread['id']]);
$conn->prepare("DELETE FROM cmdb_ai_threads WHERE id = ?")->execute([(int)$thread['id']]);

---

3. 🏢 Whose is what - the company rules

• The company is always the analyst's active one - the top-bar switcher, getActiveTenantId(). cmdbAssistCompany() returns ['id' => real tenant id, 'name', 'multi'] and refuses (forbidden) a company the analyst may not reach. No request ever names a company.
• 🔴 TRAP: tenant_id is always the real id. The Default company is stored as its own id, never NULL - unlike cmdb_objects.tenant_id, where NULL means the default company. CI reads go through tenantScopeSqlFor($conn, $tenantId, 'o.tenant_id'), which resolves that difference.
• Classes, properties and relationship types are install-wide (shared by every company), so the prompt tells the model never to put a company's name in a class.
• CIs are per company. list_objects, list_classes' CI counts and the coverage counts read only this company's. An objects proposal stores the company_id it was made in; preview and apply refuse (forbidden) if the analyst's active company has changed since.

---

4. 💬 One turn - cmdbAssistTurn($conn, $ctx, $company, $mode, $text)

$mode is chat (the analyst wrote $text, cut to 4000 characters), open (a greeting for an empty conversation) or resume (a catch-up after 8 hours). open and resume send an internal instruction instead of user text and store only the reply.

1. Ready and configured - cmdbAssistReady() (else not_ready), then aiSettingsLoad($conn, 'cmdb_ai'); aiConfigured() false throws RuntimeException('not_configured').

2. Thread - cmdbAssistThread($conn, $tid, $analystId, true) creates it on first use. Only cmdbAssistTurn creates one: a GET never does.

3. Coverage - cmdbAssistCoverage(): facts per topic, the live counts (classes, properties, classes with properties, dependency object_refs, relationship types and how many carry impact, this company's CIs, asset types mapped to a class) and a stage:

   Stage	When	What the model is told to do
   interview	fewer than all four core topics have a fact	ask about the next uncovered topic (next_topic, from cmdbAssistInterviewOrder()), at most three questions, remember every answer
   design	core known, but fewer than four classes with properties or no CIs in this company	suggest classes and properties, propose_schema; once classes exist, offer propose_objects
   refine	both	gaps, naming, what to leave out; propose what is missing

4. History - aiConversationHistory($conn, 'cmdb_ai_messages', $threadId): the last 12 messages word for word, each assistant turn followed by [Proposed: ... - applied] so the model knows what became of its proposals. That annotation is how a Continue turn (§5) learns that a proposal was applied.

5. System prompt - cmdbAssistSystem(): who it is talking to and about which company, the rules (see The rules in the prompt below), the stage text, topics noted, the CMDB counts, the administrator's custom instructions (cmdb_ai_custom_instructions, capped at 2000 characters), the memory (summary), and the facts inside <cmdb_data>. Facts are capped at 150 and 6000 characters, newest first, then grouped by topic (cmdbAssistFactsBlock()); a line says how many older ones list_facts can read.

6. Tools - aiProviderChatTools($cfg, [..., 'max_rounds' => 5], cmdbAssistTools(), $run):

   Tool	Kind	What $run does
   list_classes · get_class · list_relationship_types · list_asset_types · list_objects · list_records · list_facts	read	cmdbAssistRead($conn, $tid, $name, $args, $ctx->companyScope) - text, this company only, never throws; the name goes in looked_at
   remember {topic, subject, statement}	memory	cmdbAssistRemember() - saves now; the fact goes in the turn's learned with its prev. Already known word for word: nothing written, no chip, the model is told Already known
   forget {fact_id}	memory	cmdbAssistForget() - this company's fact only
   propose_schema · propose_objects	proposal	the type's check; a pending proposal on the turn, or the refusal reason back to the model

7. Store - the user message (chat only), then the assistant message with proposals, looked_at, learned, model and tokens. Facts noted this turn get source_message_id. The thread's updated_datetime moves on.

8. Summarise - cmdbAssistSummarise() (§6).

A fact noted twice in one turn makes one chip that keeps the first prev, so Undo goes back to what was there before the turn:

foreach ($learned as $i => $l) if ($l['id'] === $f['id']) { $learned[$i]['statement'] = $f['statement']; return 'Noted (#' . $f['id'] . ').'; }
$learned[] = ['id' => $f['id'], 'topic' => $f['topic'], 'subject' => $f['subject'], 'statement' => $f['statement'], 'prev' => $f['prev']];

list_records {type, search?} - the records a CI may point at

People, locations, teams and the rest are FreeITSM records, not CIs: a CI points at one through a property of that record type (see Record references - Developer Guide). list_records lets the model see the real ones before it proposes CIs with such a property, so it uses their names exactly.

• type is one of cmdbRecordTypes() (an unknown one is answered with the list); search is optional.
• It calls cmdbRecordSearch($conn, $type, $q, $tenantId, $reach, CMDB_ASSIST_LIST_CAP) - the CI picker's own scope, with the active company and $ctx->companyScope as $reach: people and contracts of this company, locations of this company plus shared ones, any analyst, team or supplier, and only the companies the analyst can reach. That is why cmdbAssistRead() takes ?array $reach (null = every company).
• It answers Name (id N) lines, at most CMDB_ASSIST_LIST_CAP (50), with a search to narrow it line when capped. Before Database Verification has added the record-reference columns (cmdbRecordRefsReady()) it says so instead.
• Nothing matches: it says where that record type is added - People: People, or Tickets -> Users; Locations: System -> Locations (administrators) or Assets -> Settings -> Locations; Analysts: System -> Analysts; Teams: System -> Teams; Companies: System -> Companies; Suppliers: Contracts -> Suppliers; Contracts: Contracts - that the model cannot add them, and to offer to carry on with the property left empty.

The rules in the prompt

The HOW YOU WORK list in cmdbAssistSystem() is where behaviour is steered; the checks behind it are the backstop. Besides facts-as-data, three questions a turn and add-only proposals, it says:

• remember only what is new or changed - never again for something already in the facts;
• never mention fact ids, message ids or any other internal number to the user - tool results carry ids because forget needs them;
• only state what the facts or the user said - never assume what they have;
• people, teams, locations, companies, suppliers and contracts are never classes or CIs - a CI points at the record through a property of that type. If the CMDB still has an old class such as Person, say once that the record property types exist and suggest a property ("Support person", type person) instead;
• it cannot create records - when the user wants one, say where it is added (as list_records does);
• call list_records before proposing CIs with a record property, and use the names exactly;
• a dropdown whose options do not fit what the user said: never ask the user to pick a wrong option and never put one in a CI - suggest a record-type property (propose_schema) or adding the option by hand in CMDB -> Settings -> Classes, and leave that dropdown out meanwhile;
• after an applied schema with CIs promised, propose them now with propose_objects - the user has already said yes (the Continue chip, §5, gives it the turn to do so).

Remember, Undo and the Learned view

• cmdbAssistRemember() cleans the input (cmdbAssistCleanFact() - a known topic, subject up to 200 characters, statement up to 1000, whitespace collapsed), then replaces the statement of the same (company, topic, subject) or inserts one. It returns the fact plus prev and same.
• The same statement again is a no-op. When the stored statement matches (cmdbAssistSameStatement() - ignoring case, spacing and a closing . or !), cmdbAssistRemember() returns same => true and writes nothing - not the statement, not updated_by_analyst_id, not the time. The turn makes no chip and puts nothing in learned, and the model is told Already known (#id) - nothing changed. Do not note it again; remember only what is new or changed. A different statement still replaces as before, with a prev for Undo.
• Learned from a real trial: the model re-noted facts it already had on every turn, so the same Noted chip came back again and again. The no-op and the prompt rule stop it.
• cmdbAssistUndo() works only on the analyst's own thread and only once per chip: a new fact is forgotten, a changed one gets prev back, and the chip is marked undone.
• cmdbAssistFactSave() (Learned view, Edit) refuses a duplicate topic + subject and sets source = 'user'. cmdbAssistForget() and cmdbAssistForgetAll() are scoped by tenant_id. Forget everything leaves conversations as they are; Start again (cmdbAssistClear()) does the opposite.

Opening the panel - cmdbAssistOpen()

aiConversationOpenMode() decides: no thread or no message → open; the last message more than 8 hours old → resume; otherwise null, and the history is the welcome - no AI call.

---

5. 🧩 Proposals - the registry

cmdbAssistProposalTypes() in assistant.php registers each type. Adding a type is one entry plus its five functions; the tool appears in cmdbAssistTools() automatically.

function cmdbAssistProposalTypes(): array
{
    return [
        'schema' => ['tool' => cmdbAssistSchemaTool(), 'check' => 'cmdbAssistSchemaCheck', 'describe' => 'cmdbAssistSchemaDescribe',
                     'preview' => 'cmdbAssistSchemaPreview', 'apply' => 'cmdbAssistSchemaApply'],
        'objects' => ['tool' => cmdbAssistObjectsTool(), 'check' => 'cmdbAssistObjectsCheck', 'describe' => 'cmdbAssistObjectsDescribe',
                      'preview' => 'cmdbAssistObjectsPreview', 'apply' => 'cmdbAssistObjectsApply'],
    ];
}

Key	Signature	Job
tool	['name' => 'propose_<type>', 'description', 'schema']	what the model sees
check	(PDO, ActorContext, array $company, array $args): array|string	the arguments to store, or a string saying why not (sent back to the model as Not proposed: ...). A _notes key is told to the model and not stored
describe	(array $args): string	the card's one line, e.g. Services: 3 new classes, 14 properties
preview	(PDO, ActorContext, array $company, array $args): array	for the Review dialog - re-resolved against the live CMDB, reads only
apply	(PDO, ActorContext, array $company, array $args, array $opts): array	$opts['selection'] = the ticked line ids (null = every creatable line); returns what it made; throws (everything rolled back)

Statuses, and retrying a failure

cmdbAssistApply() takes the message id and the indexes the analyst ticked:

• only pending and failed items are acted on - an applied or dismissed one is skipped;
• dismiss sets dismissed;
• apply calls the type's apply as the analyst. Success: applied and result kept on the proposal. A throw: failed with the ServiceError message (anything else is logged and shown as a general error). Because apply rolls back completely, a failed proposal has made nothing and can be applied again.

The next turn's history carries each status, so the model never says a change was made until it was.

Continue - after an Apply

An Apply starts no assistant turn, so "I'll propose the CIs once you've applied the classes" would never happen on its own. The panel shows a Continue chip first among the suggestions while justApplied() in cmdb-assistant.js is true:

• the carryOn flag is set - by a successful Apply, cleared by the next message sent and by Start again; or
• the last message is the assistant's and one of its proposals is applied - the panel was reopened before carrying on.

Continue sends an ordinary chat message, I've applied it - carry on. (cmdb.assistant.chip_continue_ask). The history annotation [Proposed: ... - applied] tells the model what happened, and the prompt rule tells it to propose the promised CIs now.

Every line has an id

The preview's ticks send back line ids: the plan engine's own for a schema, and obj:<n> / rel:<n>:<m> for objects. Unticking a line in the preview also unticks what needs it; the server enforces the same (a line whose parent or target was not selected is skipped with reason_parent_not_selected).

---

6. 🧱 The schema type

propose_schema {title, relationship_types[], classes[] (with properties[]), usage[], parent_child[]} - the plan shape of includes/cmdb/schema_plan.php.

• check - cmdbAssistSchemaPlan() keeps only the plan's fields; cmdbPlanResolve() marks every line create / exists / conflict / invalid. A plan with nothing to create is refused with the reasons, so the model can fix it. Stored: {plan, counts}; lines that will be skipped go back to the model in _notes.
• preview - cmdbPlanResolve() again on the stored plan, plus can.relationship_types (the analyst's cmdb.relationship_types) and multi_company, for CmdbSchemaPreview.
• apply - cmdbPlanApply() as the analyst: add-only, one transaction, each line checked against its capability (relationship types need cmdb.relationship_types; without it those lines are skipped, not an error), idempotent. Then cmdbAssistSchemaConventions() keeps the plan's usage (Application runs on Server) and parent_child as convention facts - nothing in the schema holds them - only for classes that exist afterwards. That runs after the commit and never throws.

---

7. 🖥️ The objects type

propose_objects {title, objects: [{class_key, name, description, properties: {key: value}, parent, relationships: [{verb, to}]}]} - at most 25 (CMDB_ASSIST_MAX_OBJECTS).

cmdbAssistObjectsResolve($conn, $company, $args, $reach) is the one resolver, run at check, preview and apply. Reads only. For each object it decides create, exists (same name in that class in this company - skipped, never changed) or invalid with a reason:

• class by key or name (plural folding, as the plan engine);
• 🔴 a class that is really a record is refused - its name or key is in cmdbPlanRecordClassNames() (Person, Analyst, Team, Location, Company, Supplier, Contract and the aliases User, People, Staff, Employee, Tenant, Vendor, Site), reason r_record_class (point at the real one with a {type} property on a configuration item instead). People and places are records a CI points at, never CIs. Learned from a real trial: an install with the old demo Person class had David and Lucy proposed as CIs;
• each property by key or label, the value checked by type - number, date (TypedFields::parseDate), boolean (yes/no/true/false/1/0), dropdown (one of its options, case-insensitive), object_ref (a CI in this proposal or in this company, of the target class), and record types (person, team, location...) looked up with cmdbRecordSearch() - a name that matches nothing, or several, is left empty with a note, never refused;
• required properties must be filled;
• the parent and each relationship's target are another CI in the proposal or one already in this company - ambiguous names are refused;
• verbs match a relationship type's verb or inverse verb (the inverse sets forward = false, which swaps from and to);
• parent loops inside the proposal are refused, and anything that needs a refused line is refused too.

check returns every problem at once (fix these and propose again (or ask the user) - ...), refuses a proposal where everything is already there, and stores {title, objects, company_id, company_name, counts}.

apply - cmdbAssistObjectsApply():

1. refuses another company's proposal and an analyst without CMDB module access;
2. resolves again, so a CI made since the preview counts as already there;
3. in one transaction: objects in dependency order (a parent and an object_ref target first) through CmdbService::createInTransaction() - so company rules, required properties and typed values are the service's - then relationships through CmdbService::createRelationship(), skipping any that already exist;
4. anything failing rolls everything back and is rethrown;
5. cmdb.object.created fires for each new CI after the commit (CmdbService::announceCreated()).

$id = CmdbService::createInTransaction($conn, $ctx, [
    'class_id' => $ob['class_id'], 'name' => $ob['name'], 'parent_id' => $parent,
    'tenant_id' => (int)$company['id'], 'properties' => $props,
]);

It is idempotent: applying the same proposal again finds the CIs there and creates nothing. Returns {created: {objects, relationships}, counts, skipped: [{line, reason}], existing}.

---

8. 🔌 The API - api/cmdb/assistant.php

All JSON. POSTs need the CSRF token (csrf.js adds it to every same-origin fetch); a GET never writes.

GET
  -> {success, ready, ai_ready, can_set_up, company: {id, name, multi}, topics,
      coverage, messages, remembers, facts}          (the last four only when ready)

GET ?action=preview&message_id=N&index=I
  -> {success, type: "schema"|"objects", status, summary, resolved, ...}
     schema: + can: {relationship_types}, multi_company
     objects: + multi_company

POST {action, ...}  -> {success, messages, remembers, facts, coverage}
  open
  send        {text}
  undo        {message_id, fact_id}
  apply       {message_id, items: [i], selection?: ["obj:0", "rel:0:0", ...]}   + proposals
  dismiss     {message_id, items: [i]}                                         + proposals
  clear
  fact_save   {fact_id, topic, subject, statement}
  fact_delete {fact_id}
  forget_all

A provider problem on open / send is still success: true, with {ai_error: "not_configured" | "unreachable", detail} (the detail from aiExplainFailure(), at most 400 characters). A refusal is {success: false, error, code}; forbidden is HTTP 403.

🔴 TRAP: a proposal's arguments are never sent to the panel. cmdbAssistMessages() and the apply answer map each proposal to {type, summary, status, error, counts | result}. The preview is the only way to see what a proposal holds, and it is re-resolved on the server.

$props = array_map(function ($p) {
    return ['type' => $p['type'] ?? '', 'summary' => $p['summary'] ?? '', 'status' => $p['status'] ?? '', 'error' => $p['error'] ?? null, 'result' => $p['result'] ?? null];
}, $props);

---

9. 🔒 Permissions and readiness

Check	Where	Decides
CMDB module access	requireModuleAccessJson('cmdb')	the endpoint at all
cmdb.classes	requireCapabilityJson(Cap::CMDB_CLASSES); analystHasCapability() in header.php	the endpoint, and whether the panel is on the page
cmdb.ai	can_set_up	only whether a "Set up AI" link shows
cmdb.classes / cmdb.relationship_types	cmdbPlanApply(), per line	which schema lines are created
CMDB module access	cmdbAssistObjectsApply()	creating CIs (as api/cmdb/save_object.php, which asks no capability)
the active company	cmdbAssistCompany()	which company - refused if the analyst cannot reach it

Readiness is two separate things:

• cmdbAssistReady($conn) - have Database Verification's tables arrived? It counts four columns across the three tables in INFORMATION_SCHEMA, cached per request ($fresh = true asks again - a test renames a table). Not ready: the GET answers ready: false and every POST is refused with not_ready.
• cmdbAssistAiReady($conn) = aiFeatureReady($conn, 'cmdb_ai') - is the CMDB's AI provider set up (aiConfigured(), so a keyless custom endpoint counts)? The header shows the Assistant button only when it is. The panel is on the page for anyone with cmdb.classes either way, so the Learned view - reachable from the Classes tab - can be read and corrected with AI switched off.

---

10. 🧪 Tests

Test	Covers
tests/cmdb-assistant.php (104 checks)	opening greets; remember saves at once, the same subject replaces, Undo, forget; the identical remember is a no-op (nothing written, no chip, Already known sent back) with a changed-statement control that does replace; list_records reads this company's records only, with a ZZ second company's as the control; the Learned view (edit, duplicate refused, delete, forget everything - this company only); company isolation with a ZZ second company, each with a positive control; another analyst's conversation is private and the facts shared; the prompt (rules, facts as data, the cap); the stage; the memory fold; over HTTP: GET writes nothing, POST without CSRF refused, no cmdb.classes refused, not_configured, and not_ready with a table renamed
tests/cmdb-assistant-proposals.php (91 checks)	propose_schema: card, preview, ticked lines only, conventions, idempotent, refused when nothing to create, relationship types without the capability skipped, injected failure rolls back then retried, dismiss. propose_objects: active company only (with a positive control), typed properties, parent, relationship, existing skipped, bad property refused, a CI in a Person class refused (r_record_class) with an ordinary class as the control, rollback, no module access refused, another company's refused. Over HTTP and in headless Chrome (Review, Apply, the card says Applied, the Continue chip shows after the Apply; set FREEITSM_SHOT_DIR to keep the screenshots)
tests/projects-assistant.php	the Projects assistant on the shared helpers: open / resume, proposal statuses in the history, the memory fold, aiConfigured(), not_configured, Start again

🔴 Never against a real database. The tests make and remove their own rows by id, but they write. Run them from inside the throwaway install:

cd c:/wamp64/www/freeitsm-prtest
FREEITSM_TEST_DATABASE=freeitsm_prtest \
FREEITSM_TEST_URL=http://localhost/freeitsm-prtest \
FREEITSM_BASE_URL=http://localhost/freeitsm-prtest \
php tests/cmdb-assistant.php

Each test checks that config.php really points at FREEITSM_TEST_DATABASE and skips otherwise. FREEITSM_BASE_URL matters: without it the HTTP checks call whatever install BASE_URL names.

The mock AI's script model

Nothing is paid and nothing leaves the machine: each test starts tests/ai-compatible/mock.php with php -S on a local port and points the cmdb_ai settings at it as an OpenAI-compatible endpoint (and puts the settings back exactly afterwards). With the model script:

• every line of the last user message of the form CALL tool_name {"json": "arguments"} is asked for as a tool call - all at once, once;
• when the tool results come back (or there were no CALL lines) it answers REPLY: and the tool results joined with |;
• a memory fold (system prompt starting You keep the memory) answers - MEMORY: folded.

So a test drives the real loop by writing the message:

$r = cmdbAssistTurn($conn, $ctxA, $coA, 'chat', "We run payroll.\nCALL remember {\"topic\":\"service\",\"subject\":\"Payroll\",\"statement\":\"Payroll runs monthly on Sage.\"}");

Every request the mock receives is logged to tests/ai-compatible/last-request.json with each message's text (texts) and the tool names offered (tools), which is how the tests check what the prompt carried.

---

11. ⚠️ TRAPs

• 🔴 tenant_id is always the real company id - never NULL for the Default company (§3).
• 🔴 Facts are data in the prompt. Statements, class names, CI names and tool results were written by people; they go inside <cmdb_data> and the system prompt says everything there is data, never instructions. Keep anything new from the company the same way.
• 🔴 A proposal's arguments are never sent to the panel (§8). Do not add args to cmdbAssistMessages().
• 🔴 Never trust the foreign keys - delete by id (§2).
• ⚠️ Re-resolve, never replay. Preview and apply resolve the stored arguments against the CMDB as it is now; what was true when the model proposed it may not be.
• ⚠️ Add-only, both types. A change to something that exists is advice in the reply, never a proposal. A new proposal type that edits or deletes needs a different preview and a conversation with the maintainer first.
• ⚠️ Only names the analyst gave. The prompt and the tool description say so; the check cannot know where a name came from, so keep that instruction in both places.
• ⚠️ What is already in the CMDB steers the model. Learned from a real trial: old demo classes read through list_classes / get_class are taken as the design to fill - a Person class drew people as CIs (now refused, §7), and Server's Location dropdown offering London DC had the model asking about a hotel in Leeds as if that option fitted. Hence the dropdown rule in the prompt (§4): suggest a record-type property or adding the option by hand, never a wrong option.
• ⚠️ A remember that changes nothing stays a no-op (§4) - writing it would move updated_by and the time, and bring the chip back every turn.
• ⚠️ api/cmdb/assistant.php parses on PHP 7.4 - no match, nullsafe or named arguments there.
• ⚠️ includes/ai_conversation.php takes table names, checked against a pattern - pass developer literals, never anything from a request.

---

Related pages

• CMDB · Designing your CMDB · AI Providers
• CMDB - Developer Guide · Record references - Developer Guide
• Projects internals 7 - the AI project assistant (the other conversation on includes/ai_conversation.php)