bench get-app https://github.com/KirkGamo/erp_ai

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=KirkGamo%2Ferp_ai)](https://frappegems.com/gems/apps/KirkGamo/erp_ai)

ERP AI — AI Assistant for ERPNext

ERP AI is a standalone Frappe app that embeds an AI assistant directly into ERPNext. It supports natural language ERP querying, multi-turn conversational analytics grounded in live data, predictive insights (demand forecasting, cash flow projections, inventory depletion), and a customer AI assistant — all powered by a dual-LLM router supporting OpenAI, Groq, and Ollama.

---

Features

💬 AI Chat Assistant

A floating chat widget on every ERPNext page. Supports: - Natural language ERP queries (show me unpaid invoices this month) - Financial report summarization - Smart global search across DocTypes - AI-assisted document creation for 13 DocTypes with confirmation flow - Inventory monitoring — reorder alerts, slow-moving items, expiry tracking - Accounting assistance — overdue receivables, cash flow, reconciliation, follow-up email drafts - Workflow guidance — ERPNext error explanations and how-to answers - Automatic error dialog interception with "Explain this error" button

📊 AI Dashboard Insights

A live alert card on the ERPNext Home workspace showing: - Overdue receivables - Low inventory items - Negative cash flow - Slow-moving inventory - Unallocated payments - Sales trend drops

Each alert has an "Ask AI →" button that sends the real figures directly to the chat assistant.

🤖 Customer AI Assistant

A sidebar widget injected into every Customer form showing: - Purchase history summary (configurable window) - Top purchased items with frequency badges - AI-generated narrative: most ordered, spending trend, likely next order - Free-text question input for custom queries

📈 Conversational Analytics

Multi-turn data analysis in the chat widget: - Ask follow-up questions that reference prior results - Session state persisted in Redis per login session - All responses grounded in live SQL data — no hallucination - Supported query types: top selling items, revenue by customer, monthly trends, overdue invoices, stock levels

🔮 Predictive Insights

A dashboard widget on the Home workspace with three forecast types, each saved as an AI Forecast record: - Demand Forecast — projected quantity and revenue per item - Cash Flow Projection — 30/60/90-day net cash position - Inventory Depletion — days-to-stockout per item

---

Installation

Prerequisites

• Frappe v15
• ERPNext v15
• Redis (included with Frappe bench)
• One of: OpenAI API key, Groq API key, or local Ollama installation

Install the app

bench get-app https://github.com/KirkGamo/erp_ai
bench --site  install-app erp_ai
bench --site  migrate
bench build --app erp_ai
bench restart

---

Configuration

Set these via bench --site set-config:

Key	Description	Default
openai_api_key	OpenAI or Groq API key	—
openai_api_base	API base URL	https://api.openai.com/v1
openai_model	Model name	gpt-4o
ollama_base_url	Local Ollama endpoint (fallback)	http://localhost:11434
ollama_model	Ollama model name (fallback)	llama3:8b
ai_rate_limit	Max AI requests per user per hour	50

Option A — OpenAI

bench --site  set-config openai_api_key "sk-..."
bench --site  set-config openai_model "gpt-4o"

Option B — Groq (free tier)

bench --site  set-config openai_api_key "gsk_..."
bench --site  set-config openai_api_base "https://api.groq.com/openai/v1"
bench --site  set-config openai_model "llama-3.3-70b-versatile"

Get a free Groq API key at https://console.groq.com

Option C — Ollama (fully local)

ollama pull llama3:8b
bench --site  set-config ollama_base_url "http://localhost:11434"
bench --site  set-config ollama_model "llama3:8b"

Remove openai_api_key from site config to force Ollama as primary.

---

AI Settings (DocType)

After installation, configure AI behaviour via Settings → AI Settings:

Field	Default	Description
Purchase History Window	12 months	How far back to look for customer insights
Minimum Transaction Count	3	Minimum invoices for a customer to qualify
Minimum Total Spend	0	Minimum spend threshold (0 = disabled)
Forecast Horizon	30 days	How far ahead forecasts project
Forecast Training Window	6 months	Historical data used for forecasts
Session Context Turns	5	Rolling Q&A pairs in analytics sessions

---

DocTypes

DocType	Type	Purpose
AI Action Log	Standard	Audit trail for every AI-assisted create/confirm action
AI Conversation	Standard	Per-user chat session turn history
AI Settings	Single	Global configuration for all AI features
AI Forecast	Standard	Forecast records auto-named FCST-YYYY-#####

---

Architecture

erp_ai/
├── ai/
│   ├── llm_router.py                      # Dual-provider LLM (OpenAI/Groq primary, Ollama fallback)
│   ├── intent_router.py                   # Classifies user intent across 10 categories
│   ├── context_manager.py                 # Builds per-user ERP context for each LLM call
│   ├── permission_guard.py                # Wraps Frappe permissions
│   ├── insights.py                        # Dashboard alert collectors
│   ├── doctype_config.py                  # Config registry for AI data entry DocTypes
│   ├── prompts/                           # System prompt templates
│   └── handlers/
│       ├── query_handler.py               # NL → frappe.get_list()
│       ├── report_handler.py              # Financial report fetch + LLM summarization
│       ├── search_handler.py              # Fuzzy search across DocTypes
│       ├── data_entry_handler.py          # Draft document creation with confirmation flow
│       ├── inventory_handler.py           # Reorder, slow-moving, expiry monitoring
│       ├── accounting_handler.py          # Overdue, cash flow, reconciliation, follow-up drafts
│       ├── guidance_handler.py            # ERPNext error explanations + how-to guidance
│       ├── customer_assistant_handler.py  # Purchase history analysis + recommendations
│       ├── conversational_analytics_handler.py  # Multi-turn analytics with Redis session
│       └── predictive_insights_handler.py # Demand, cash flow, inventory depletion forecasts
├── api/
│   └── ai_chat.py                         # Whitelisted REST endpoints
├── erp_ai/
│   └── doctype/                           # AI DocTypes
└── public/js/
    ├── ai_chat_widget.js                  # Floating chat UI
    ├── ai_insights_widget.js              # Dashboard insights card
    ├── ai_customer_assistant_widget.js    # Customer form sidebar widget
    └── ai_predictive_widget.js            # Home workspace forecast widget

---

LLM Router

Every AI call goes through LLMRouter: - Primary: OpenAI or any OpenAI-compatible provider (Groq recommended for free tier) - Fallback: Ollama (local, fully private) - Automatic failover on quota errors, timeouts, or unavailability

from erp_ai.ai.llm_router import LLMRouter
router = LLMRouter()
response = router.call(messages=[...], system_prompt="...")

---

License

MIT — see license.txt

Author

Kirk Gamo — github.com/KirkGamo