Implemented: AI plugin — AI/LLM capabilities in OFBiz services (OFBIZ-13408)

ai/.gitignore

@@ -0,0 +1,3 @@
+config/ai.properties
+CLAUDE.md
+docs/

ai/README.md

@@ -0,0 +1,160 @@
+# AI Plugin for Apache OFBiz
+
+An optional plugin that brings LLM agent capabilities to OFBiz using only framework-native patterns — no external AI SDK, no framework modifications.
+
+Apache JIRA: https://issues.apache.org/jira/browse/OFBIZ-13408  
+Documentation: https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=430407963
+
+## What it does
+
+Exposes a single OFBiz service — `agentRun` — that runs a named AI agent. Agents and tools are declared in XML. The plugin handles the LLM loop, tool dispatch, observability, permission enforcement, conversation memory, and human approval gating.
+
+No third-party AI SDK. Uses `java.net.http.HttpClient` and Jackson, both already present in the OFBiz runtime.
+
+## Prerequisites
+
+- OFBiz trunk (Java 17+)
+- An API key from OpenAI, Anthropic, or any OpenAI-compatible provider (Ollama, Groq, etc.)
+
+## Installation
+
+```bash
+cp plugins/ai/config/ai.properties.template plugins/ai/config/ai.properties
+```
+
+Edit `ai.properties` — set your provider block and API key (this file is gitignored, never commit it).
+
+## Configuration
+
+Named provider blocks — add as many as needed:
+
+```properties
+ai.provider.openai-default.model=gpt-4o-mini
+ai.provider.openai-default.apiKey=sk-...
+
+ai.provider.anthropic-default.baseUrl=https://api.anthropic.com/v1
+ai.provider.anthropic-default.model=claude-sonnet-4-6
+ai.provider.anthropic-default.apiKey=sk-ant-...
+ai.provider.anthropic-default.extraHeaders=anthropic-version:2023-06-01
+
+ai.provider.ollama-default.baseUrl=http://localhost:11434
+ai.provider.ollama-default.model=llama3
+```
+
+## Declaring tools and agents
+
+Tools are OFBiz services exposed to the LLM, declared in `ai/*.tools.xml` inside any component:
+
+```xml
+<tools xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <tool name="getProductionRunStatus"
+          service-name="getProductionRunStatus"
+          requires-approval="false">
+        <description>Returns the current status of a production run given its ID.</description>
+    </tool>
+    <tool name="updateProductionRunStatus"
+          service-name="updateProductionRunStatus"
+          requires-approval="true">
+        <description>Updates the status of a production run. Requires human approval.</description>
+    </tool>
+</tools>
+```
+
+Agents are declared in `ai/*.agent.xml`:
+
+```xml
+<agent name="mrp-assistant" provider="anthropic-default" max-iterations="8">
+    <system-prompt>You are an MRP analyst. Use the tools available to answer manufacturing queries.</system-prompt>
+    <tool-allow-list>
+        <tool name="getProductionRunStatus"/>
+        <tool name="updateProductionRunStatus"/>
+    </tool-allow-list>
+</agent>
+```
+
+The plugin scans all components' `ai/` directories at startup.
+
+## Usage
+
+Call `agentRun` from any Groovy script, service, or ECA:
+
+```groovy
+Map result = dispatcher.runSync("agentRun", [
+    agentName:   "mrp-assistant",
+    userMessage: "Which production runs are at risk this week?",
+    userLogin:   userLogin
+])
+String answer = result.assistantMessage
+```
+
+Multi-turn conversation — pass a `threadId`:
+
+```groovy
+Map result = dispatcher.runSync("agentRun", [
+    agentName:   "mrp-assistant",
+    userMessage: "What about next week?",
+    threadId:    "thread-abc123",
+    userLogin:   userLogin
+])
+// result.threadId — pass this back on the next call
+```
+
+Human approval — pass `approvalRequired: true` or mark individual tools with `requires-approval="true"`:
+
+```groovy
+Map result = dispatcher.runSync("agentRun", [
+    agentName:        "mrp-assistant",
+    userMessage:      "Update all at-risk runs to ON_HOLD.",
+    approvalRequired: true,
+    userLogin:        userLogin
+])
+if (result.stopReason == "approval_required") {
+    String proposalId = result.proposalId
+    // store proposalId — a reviewer calls approveAgentProposal or rejectAgentProposal
+}
+```
+
+## Services
+
+| Service | Purpose |
+|---|---|
+| `agentRun` | Run a named agent |
+| `approveAgentProposal` | Execute pending tools and resume the agent loop |
+| `rejectAgentProposal` | Reject a proposal; returns LLM acknowledgment |
+| `getUsageSummary` | Token usage and estimated cost, filterable by agent/user/date |
+| `getConversationHistory` | Messages for a thread in sequence order |
+| `archiveConversationThread` | Mark thread archived |
+| `aiGenerate` | Direct single-turn LLM call, no agent loop |
+| `aiGenerateStructured` | Structured JSON output constrained by schema |
+
+## Architecture
+
+```
+AiContainer (startup)
+    ├── ProviderRegistry  — reads ai.properties named blocks
+    ├── ToolCatalog       — scans all components' ai/*.tools.xml
+    └── AgentRegistry     — scans all components' ai/*.agent.xml
+
+agentRun
+    └── AgentRunner
+            ├── load thread history (if threadId)
+            ├── loop: AiHttpClient → LLM → tool dispatch → repeat
+            ├── persist AiAgentRun + AiAgentToolCall
+            └── save conversation messages (if threadId)
+```
+
+## Admin UI
+
+Mounted at `/ai` — requires `OFBTOOLS` permission.
+
+| Screen | URL |
+|---|---|
+| Run History | `/ai/control/FindAiAgentRun` |
+| Run Detail | `/ai/control/AiAgentRunDetail` |
+| Usage Dashboard | `/ai/control/AiUsageDashboard` |
+| Proposal Review | `/ai/control/FindAiAgentProposal` |
+| Thread Explorer | `/ai/control/FindAiConversationThread` |
+
+## Smoke test
+
+Start OFBiz, then: webtools → Service Engine → Run Service → `aiSmokeTest`

ai/ai/ecommerce-promo-advisor.agent.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<agents>
+    <agent name="PromoAdvisor"
+           provider="openai-default"
+           max-iterations="6">
+
+        <system-prompt><![CDATA[
+You are a merchandising advisor for Open For Business, an ecommerce store selling Gizmos and Widgets.
+
+Your job is to help the merchandising team decide which products to put on promotion and at what price.
+
+When asked about promotions:
+1. Call getProductPriceSummary to understand current pricing and margins.
+2. Call getProductInventorySummary to check stock availability.
+3. Call getRecentOrderActivity to see how the product is selling.
+4. Reason over the data: a good promotion candidate has healthy stock, slow recent sales,
+   and room between cost and list price to offer a meaningful discount.
+5. Recommend a specific promotional price that is above average cost but below the default price,
+   and explain your reasoning with the actual numbers.
+
+When the user asks you to apply a promotion:
+- Confirm the product ID, price, and duration before calling setProductPromoPrice.
+- Only call setProductPromoPrice once you have explicit user confirmation.
+- Inform the user that the price change will require manager approval before it goes live.
+
+Products available in this store: GZ-1000 (Tiny Gizmo), GZ-1001 (Nan Gizmo),
+GZ-2002 (Square Gizmo), GZ-2644 (Round Gizmo), GZ-5005 (Purple Gizmo),
+GZ-1004 (Rainbow Gizmo), GZ-1005 (.NIT Gizmo), GZ-7000 (Massive Gizmo),
+GZ-8544 (Big Gizmo), GZ-9290 (His/Her Gizmo), WG-1111 (Micro Chrome Widget),
+WG-5569 (Tiny Chrome Widget), WG-9943 (Giant Widget), WG-9944 (Giant Widget with Feature Explosion).
+        ]]></system-prompt>
+
+        <tool name="getProductPriceSummary"/>
+        <tool name="getProductInventorySummary"/>
+        <tool name="getRecentOrderActivity"/>
+        <tool name="setProductPromoPrice"/>
+    </agent>
+</agents>

ai/ai/ecommerce-promo.tools.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<tools>
+
+    <tool name="getProductPriceSummary"
+          service="getProductPriceSummary">
+        <description>Look up all active USD prices for a product: default (selling) price, list price,
+average cost, promotional price, and competitive (competitor) price. Use this first to understand
+a product's current pricing and margin before recommending a promotion.</description>
+    </tool>
+
+    <tool name="getProductInventorySummary"
+          service="getProductInventorySummary">
+        <description>Return the total available-to-promise (ATP) inventory quantity for a product across
+all warehouses, plus a per-facility breakdown. Use this to check whether we have enough stock
+to support a promotion before recommending one.</description>
+    </tool>
+
+    <tool name="getRecentOrderActivity"
+          service="getRecentOrderActivity">
+        <description>Return the number of orders, total quantity sold, and total revenue for a product
+over the last N days (default 30). Use this to assess whether a product is selling well
+or needs a promotional push.</description>
+    </tool>
+
+    <tool name="setProductPromoPrice"
+          service="setProductPromoPrice"
+          requires-approval="true"
+          required-permission="CATALOG_PRICE_MAINT">
+        <description>Create a SPECIAL_PROMO_PRICE for a product in USD, active for the specified number
+of days (default 7). This is a WRITE operation that changes the live store price and requires
+manager approval before it executes. Only call this when the user has confirmed they want to
+proceed with the promotion.</description>
+    </tool>
+
+</tools>

ai/ai/sample.agent.xml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<agents>
+    <agent name="SampleAgent"
+           provider="openai-default"
+           model="gpt-4o-mini"
+           max-iterations="4">
+
+        <system-prompt><![CDATA[
+You are a helpful assistant. Use the available tools to answer questions.
+        ]]></system-prompt>
+
+        <tool name="aiSmokeTest"/>
+    </agent>
+</agents>

ai/ai/sample.tools.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<tools>
+    <tool name="aiSmokeTest"
+          service="aiSmokeTest">
+        <description>Run the AI smoke test to verify the AI plugin is working.</description>
+    </tool>
+</tools>

ai/build.gradle

@@ -0,0 +1,21 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+dependencies {
+}