====== Toweringmedia AI Core for Magento 2 — User Guide ======

===== Extension context =====

This is the user guide for **Toweringmedia AI Core** (''toweringmedia/module-ai-core''): the shared AI infrastructure layer required by all AI-capable Toweringmedia Magento 2 extensions. Configure your OpenAI-compatible provider, Google Gemini, speech-to-text, text-to-speech, call budgets, and safety gates once — Nora AI, Search Intelligence LLM, Product Builder, and other modules draw from the same runtime without re-implementing HTTP clients or budget logic.

===== Product page =====

  * [[https://toweringmedia.com/toweringmedia-ai-core-for-magento-2|Toweringmedia AI Core for Magento 2 — $399/month]]

===== Quick links =====

  * [[magento2:extensions:start|Magento 2 extension index]]
  * [[magento2:start|Magento 2 docs home]]
  * [[magento2:extensions:toweringmedia-module-nora-ai|Nora AI Extension]] (depends on AI Core)
  * [[magento2:extensions:toweringmedia-module-search-intelligence-llm|Search Intelligence LLM]] (depends on AI Core)

===== Overview =====

AI Core is the **mechanics layer** for AI on Magento 2. It does not ship storefront chat, SEO workflows, or product actions on its own. Domain modules register their tools via dependency injection and inherit all provider config, memory, budgeting, and audit infrastructure from AI Core.

  * One OpenAI-compatible API key and model configured in admin for all dependent extensions
  * Task Routing assigns different providers to chat, summarization, image generation, STT, and TTS
  * Dry Run = Yes by default — zero API spend until you explicitly opt in to live calls
  * Daily call budgets and per-run caps prevent runaway API spending
  * Agent runtime with bounded tool execution loop, policy gates, and layered memory
  * License validated remotely every few hours — monthly subscription must stay active

===== Installation =====

Install and validate in **staging** before production rollout.

<code bash>
composer require toweringmedia/module-ai-core
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
</code>

Requires ''toweringmedia/module-base'' ^1.1.25 (installed automatically via Composer).

===== Admin configuration path =====

''Stores → Configuration → Towering Media → AI Core Settings''

===== Configuration sections =====

==== License ====

Paste the AI Core license key from ''toweringmedia.com → My Extensions''. The license is validated remotely every few hours. Live AI calls are blocked when the monthly subscription is unpaid, even if you supply your own OpenAI API key.

^ Field ^ Notes ^
|| **License Key** | Paste from toweringmedia.com dashboard. Required for live calls. |

==== General ====

Master switches for the provider runtime.

^ Field ^ Default ^ Notes ^
|| **Enabled** | Yes | Master switch. Domain modules read this via ProviderConfigInterface. |
|| **Dry Run** | Yes | When Yes: packets build and shrink locally, zero API calls. Safe for CI and staging. |
|| **Enable Live API Calls** | No | Explicit production opt-in. Requires Enabled = Yes, Dry Run = No, a saved API key, and remaining daily budget. |

**Best practice:** leave Dry Run = Yes in staging and CI. Only flip to live in production with a saved license key and API key.

==== Chat Provider (OpenAI-compatible) ====

Primary provider for chat completions, summarization, and embeddings.

^ Field ^ Default ^ Notes ^
|| **API Base URL** | ''https://api.openai.com/v1'' | Provider root URL including ''/v1''. AI Core appends ''/chat/completions''. Works with Azure OpenAI, Ollama, or any compatible endpoint. |
|| **Model** | ''gpt-4o-mini'' | Chat completions model id. Used in the JSON request body and packet/summary cache keys. |
|| **API Key** | *(blank)* | Stored encrypted in ''core_config_data''. Sent as Bearer token on live calls only. Never commit real keys to git. |
|| **HTTP Timeout (seconds)** | 30 | Maximum wait for a provider HTTP response. |
|| **Max Output Tokens** | *(provider default)* | Provider output cap, not the packet input budget. |
|| **Embeddings Model** | ''text-embedding-3-small'' | Used for semantic routing and training exemplar seeding. |

==== Task Routing ====

Assigns the right provider to each AI task type. Chat and summarization share the OpenAI-compatible provider; image generation uses Google Gemini.

^ Task ^ Default Provider ^ Used by ^
|| Chat Completion Provider | OpenAI-compatible | Nora AI agent tool calls, conversational flows |
|| Summarization Provider | OpenAI-compatible | Context compression, summary-tier memory |
|| Image Generation Provider | Google Gemini | Product Builder photo editing |
|| Speech-to-Text Provider | OpenAI Whisper | Nora AI voice input |
|| Text-to-Speech Provider | OpenAI TTS | Nora AI voice responses |

==== Speech-to-Text (OpenAI Whisper) ====

Cloud STT for Nora voice input. Uses the shared OpenAI-compatible API key and base URL above.

^ Field ^ Default ^ Notes ^
|| **Enabled** | No | Master switch for Whisper transcription. Enable when using Nora AI voice. |
|| **STT Model** | ''whisper-1'' | Whisper model id. |

==== Text-to-Speech (OpenAI) ====

OpenAI neural TTS for Nora AI voice responses.

^ Field ^ Default ^ Notes ^
|| **Enabled** | No | Master switch for OpenAI TTS. |
|| **TTS Model** | ''tts-1-hd'' | OpenAI TTS model (''tts-1-hd'' or ''tts-1''). |
|| **Default Voice** | ''nova'' | Voice id (nova, alloy, shimmer, echo, fable, onyx). |

==== Budget and Rate Limits ====

CallBudgetGuard enforces daily budget and post-error cooldown.

^ Field ^ Default ^ Notes ^
|| **Daily Call Budget** | 50 | Maximum provider calls per store per UTC day. 0 = block all. Resets at midnight UTC. |
|| **Max Calls Per Run** | 5 | Per-orchestration cap. Prevents a single admin job or CLI run from exhausting the daily budget. |
|| **Max Input Tokens (packet budget)** | 4000 | Target token budget before deterministic packet shrinking. |
|| **Cooldown After Error (seconds)** | 60 | Blocks further calls after a recorded error. 0 disables cooldown. |

==== Google (Gemini) Image Provider ====

Subject-consistent image generation/editing via the Gemini Developer API. Powers "show my product on the customer's photo" features in Product Builder.

^ Field ^ Default ^ Notes ^
|| **Enabled** | No | Enable only when using Product Builder image features. |
|| **API Key** | *(blank)* | Stored encrypted. Separate from the OpenAI key. |
|| **Model** | ''gemini-2.0-flash-exp-image-generation'' | Gemini image generation model id. |

===== Dry run vs live calls =====

AI Core ships with **Dry Run = Yes** and **Enable Live API Calls = No** as safe defaults. In dry-run mode:

  * Packets are built and shrunk locally
  * Context memory reads and writes work normally
  * Summarization caches are populated from prior runs if available
  * Zero HTTP calls are made to any provider
  * No API cost

To promote to production:

  - Enter a valid license key in the **License** section
  - Enter a valid API key in the **Chat Provider** section
  - Set **Dry Run** = No
  - Set **Enable Live API Calls** = Yes
  - Set a realistic **Daily Call Budget**
  - Save config and flush cache

===== Agent runtime =====

AI Core provides a bounded agent runtime that consumer modules (Nora AI, Search Intelligence) use for multi-step, tool-calling workflows:

  * Route → Tool Execution → Compose loop with structured error handling
  * Tools register via Magento DI; AI Core owns orchestration and policy gates
  * No tool side effect proceeds without a policy approval from ''PolicyInterface''
  * Layered memory: raw recent → short summary → rolled-up summary → durable tiers
  * Context selection within token budget before prompt assembly
  * Audit events for every routing decision, tool execution, and compose step

Consumers must not fork the agent loop, provider gates, or memory store. See ''docs/SCOPE.md'' in the module repo.

===== Dependent modules =====

^ Module ^ Purpose ^
|| [[magento2:extensions:toweringmedia-module-nora-ai|Nora AI]] | Storefront AI customer service agent. Uses AI Core for agent runtime, multi-turn memory, STT, TTS, and all provider calls. |
|| Search Intelligence LLM | AI-powered SEO workflow orchestration. Uses AI Core's provider, packet budgeting, and call guards. |
|| Product Builder | AI-assisted product configuration and Gemini image editing. |

===== Validation checklist =====

  * License key saved; admin shows no license error
  * Dry run test passes: enable and trigger any AI feature — no HTTP calls made to provider
  * Live call test (staging with test API key): confirm chat completion returns successfully
  * Daily budget enforced: set budget to 1, trigger two calls — second call should be blocked
  * Cache cleared after every config change: ''php bin/magento cache:clean config full_page''

===== Troubleshooting =====

  * **Live calls blocked despite Enabled = Yes:** check that Dry Run = No, Enable Live API Calls = Yes, license is active, and daily budget > 0
  * **"License invalid" error:** paste the key fresh from toweringmedia.com; whitespace or trailing newline causes validation failure
  * **Packet budget exceeded:** increase Max Input Tokens or reduce the number of context sources sent by the domain module
  * **Cooldown blocking calls:** wait for the cooldown window, or set Cooldown After Error = 0 (not recommended for production)
  * **Embeddings failing:** confirm the Embeddings Model matches a model your API key has access to

===== Technical specifications =====

  * **Magento Version:** Magento 2.4.6+ (Open Source & Adobe Commerce)
  * **PHP Version:** 8.1, 8.2, 8.3, 8.4
  * **Composer package:** ''toweringmedia/module-ai-core''
  * **Composer repository:** ''composer.toweringmedia.com''
  * **Module name:** ''Toweringmedia_AiCore''
  * **Requires:** ''toweringmedia/module-base'' ^1.1.25
  * **Pricing:** $399/month platform subscription
  * **License:** Proprietary; remote entitlement validation

===== Related Magento 2 docs =====

  * [[magento2:extensions:start|Magento 2 extension index]]
  * [[magento2:start|Magento 2 docs home]]
  * [[start|Global docs home]]