AI Toolbox

The AI features run on the Entirius AI toolbox, a separate service reached over HTTP through the shared client in entirius-django-utils (django_utils.toolbox). The rest of the platform (catalog, CMS, storefront, cart, checkout, imports) never calls it. An AI draft is saved for review; a person approves it before it is sent.

What Calls the Toolbox

Feature	Module	Toolbox call	In the CMS
AI message drafts (templates of the AI kind)	entirius-django-communicator	complete	Leads: the Communicate dialog of a company (Request draft); stage rules and follow-ups create drafts without a click
Rewrite of a draft	entirius-django-communicator	complete	Leads review: Rewrite with a note
Template test draft, model list	entirius-django-communicator	complete, list_models	Communicator template editor: Test generate, the model select
Lead intel analysis	entirius-django-leads	complete	Leads company card: Intel & hooks
Recipient pick	entirius-django-leads	complete	none (stage rules that let the AI pick the contact)
Catalog translations	entirius-django-pim-translator over entirius-django-utils-translator	estimate, create_job, get_job, get_job_results, list_jobs	PIM: Translate on selected products, Translate Store; Translation Jobs
Content translations	entirius-django-contentdb-translator over entirius-django-utils-translator	the same job calls	Builder: Translate All; Translation Jobs

Static message templates render without the toolbox in every state.

Toolbox States

django_utils.toolbox.status() answers one of four values:

• configured: enabled, the settings are present and the probe answers.
• disabled: AI_TOOLBOX_ENABLED = False. The toolbox is switched off on purpose. The instance is healthy; nothing is probed and nothing is cached.
• unconfigured: enabled, but the base URL, the API key or the channel is empty. A warning. No network call.
• unreachable: the settings are present and the probe fails. A warning. The probe is one GET models/ with a 5 s timeout, and its result is cached for 60 s.

Without the Toolbox

Feature	disabled	unconfigured	unreachable
AI message drafts	refused before anything is written: the admin API answers 503 AI_TOOLBOX_DISABLED, a stage rule run is recorded as skipped with the timeline line skipped: AI toolbox disabled, due AI follow-ups wait for the next run and contact rotations are tried again later	the draft is saved as failed with an alert; it is not retried	the draft is saved as failed with an alert and keeps its prompt; retry_failed_drafts runs a first draft of a thread again once the state is configured, at most COMMUNICATOR_DRAFT_RETRY_LIMIT times (default 3), and a recovered draft goes to review; follow-up drafts are not retried
Rewrite	refused, no version is created; 503 AI_TOOLBOX_DISABLED	a failed version with an alert; the reviewed draft stays in the queue	the same as unconfigured
Template test draft, model list	503 AI_TOOLBOX_DISABLED	503 AI_TOOLBOX_NOT_CONFIGURED	502 PROVIDER_ERROR, or 504 UPSTREAM_TIMEOUT on a timeout
Lead intel analysis	skipped with the timeline line analysis skipped: AI toolbox disabled, no alert, no failure counted; retry_failed_analyses runs it once the state is configured, while the site audit is still valid	fails for good with the timeline line analysis failed: AI_TOOLBOX_NOT_CONFIGURED and an alert	fails with a timeline line and an alert on the first failure; retry_failed_analyses runs it again once the state is configured, at most LEADS_INTEL_RETRY_LIMIT times (default 3)
Recipient pick	the first eligible contact is taken; the timeline gets recipient pick rejected: AI_TOOLBOX_DISABLED	the first eligible contact, with the same kind of timeline line	the first eligible contact, with the same kind of timeline line
Catalog and content translations	every translator call that reaches the toolbox answers 503 AI_TOOLBOX_DISABLED; the task that polls a running job returns without polling	with an empty base URL or key the translate endpoints answer 400 VALIDATION_ERROR, the job list and job detail 503 AI_TOOLBOX_NOT_CONFIGURED	502 PROVIDER_ERROR; the polling task retries every 30 s, up to 120 times

In the unreachable column a draft or an analysis is retried only after a connection failure, a timeout or a 5xx answer. A rejected key, an exceeded budget or a model the channel may not use is a permanent failure.

In the CMS, disabled and unconfigured block the AI actions: Rewrite with a note, Test generate, the model select and Estimate cost are disabled. Request draft stays clickable under the hint, and the API answers as in the table. unreachable keeps every action available with a warning, because the toolbox may answer again.

Where the State Shows

Health API. The toolbox.status check is a row of GET /api/munin/v2/health/ (admin). disabled is a passing row with state: disabled; unconfigured and unreachable are failing rows (medium and high severity). The public registry GET /api/munin/v2/ carries the same value as platform.toolbox.state, readable without credentials. The contract of the checks: Configuration Health.

CMS. unconfigured and unreachable raise the warning triangle in the header. disabled raises nothing: the panel of passing checks lists the AI toolbox row as “switched off”. Every screen with an AI action shows one hint per state:

• disabled: AI features are switched off on this instance
• unconfigured: AI features are available with the Entirius AI Toolbox
• unreachable: AI Toolbox is not responding — try again later

zeno. make setup runs make toolbox-check and never stops on its result. The summary prints toolbox mode: disabled when AI_TOOLBOX_ENABLED=0 (the default of .env.example), toolbox mode: degraded when the toolbox is enabled and make toolbox-check fails (an empty key, no answer, a rejected key), and toolbox mode: full otherwise. The last line repeats it: setup: done <N>s toolbox=<full|degraded|disabled> seeded=<yes|no>. The test side of the leads funnel: Leads End-to-End Testing.

Configuration

Setting	Default	Meaning
AI_TOOLBOX_ENABLED	True	False switches the toolbox off on purpose; the three settings below may then stay empty. Read as a truth value: convert an environment string before assigning it
AI_TOOLBOX_BASE_URL	""	address of the toolbox
AI_TOOLBOX_API_KEY	""	key sent in the X-API-Key header
AI_TOOLBOX_CHANNEL	""	the toolbox channel the instance calls

Every caller reads the same switch, base URL and key. Drafts and lead intel call the channel in AI_TOOLBOX_CHANNEL; the translators call the toolbox channel with the idx of the store channel being translated. The key belongs in settings_local.py only and is never committed. Timeouts, retries and the error classes: toolbox client reference.

Getting Access

The toolbox is not public: it has no public repository and no self-service signup. The base URL, the channel and the key come from the Entirius team: Contact the Entirius team. Until then AI_TOOLBOX_ENABLED = False keeps the instance healthy and quiet.

Next

Configuration Health