AI Base for ERPNext: User Guide to Setup, Caps and Usage Logs

AI Base for ERPNext (technical name ki_erp_ai_base) connects ERPNext and any Frappe app to the AI providers you choose. You manage providers from one screen, set a hard monthly token cap per provider, and see every call in a usage log.

You can get the app from the store page: AI Base for ERPNext.

What AI Base is for

AI Base is a connection layer, not an assistant. You add a provider, paste your own API key, and any Frappe or ERPNext app (yours or ours) can call that model through one function. Every app gets the same logging and the same limits.

The main goal is control:

• Spending limits that hold. Each provider has a hard monthly token cap. It is checked before a call is sent, so a runaway script or a busy month can't produce a surprise bill.
• Full visibility. Every call is recorded with the user, model, feature, linked document, tokens, duration and result.
• Key safety. Keys are stored encrypted. AI users can use providers but never see the keys.

You pay the AI providers directly at their prices. AI Base adds no subscription and no commission on usage.

Who it helps

• Business owners who want AI inside ERPNext without open-ended costs.
• ERP admins who need to decide which providers are allowed, who can use them, and what each company spends.
• Developers building Frappe or ERPNext apps who want one function to call AI, with logging, caps and fallback already handled.

Requirements

• ERPNext 16 or Frappe 16. ERPNext is optional.
• Your own server, or a private bench on Frappe Cloud.
• Your own API key from at least one AI provider. The provider bills you directly.
• No extra dependencies: the app depends only on Frappe, and the Python libraries it uses ship with Frappe.

Version 15 and older are not supported.

Installation

1. Get the app on your bench:

bench get-app https://github.com/Kalvyai-erpnext/ki_erp_ai_base --branch version-16

2. Install it on your site:

bench --site <site> install-app ki_erp_ai_base

3. Reload the desk. An AI Base icon appears.

On Frappe Cloud, add the app to your private bench and install it on the site. [CHECK: Frappe Cloud steps for adding this app to a private bench]

Setup

1. Add a provider

1. Open AI Base › Providers › Add.
2. Choose the provider type. Supported types are OpenAI, Anthropic Claude, Google Gemini, xAI Grok, Azure OpenAI, Mistral, Cohere, Perplexity and NVIDIA NIM.
3. Paste your API key. A sensible default model is filled in for you.
4. Click Fetch Models to list every model your key can use, and pick one. If the model you want is not listed, type its name in.
5. If you use ERPNext with several companies, set the Company field, or leave it empty to share the provider with all companies.
6. Save.

2. Set a cap and test

1. Enter a monthly token cap for the provider. Zero means unlimited. [CHECK: exact field names for input and output token caps]
2. Click Test Connection. This sends a tiny prompt to confirm the key and model work.
3. If the test fails, check the key, the model name and (for Azure or self-hosted endpoints) the Base URL.

3. Give people access

Assign roles from the user record:

• AI User: can use the providers and see usage.
• AI Manager: can add providers and enter keys.

System Managers can also add providers and see keys.

Using the main features

Providers and models

All nine providers use the same form. To switch a feature to a different model, edit the provider and change the model, or add a second provider record. Use Fetch Models after you change keys, since the list depends on what your key can access.

Hard monthly token cap

The cap limits input and output tokens per provider per month.

1. Open the provider.
2. Set the cap. Zero means unlimited.
3. Save.

Before each call, AI Base checks the cap. When the cap is reached, calls to that provider stop until the next month or until a manager raises the cap. If you have other providers set up, fallback can pass the request to the next one (see below).

Usage log

Every call is logged with:

• Provider and model
• User
• Feature
• Linked document
• Company
• Tokens
• Duration
• Status

Failed calls are logged too. Tokens billed for a rejected answer still count toward the cap, so the log matches what providers charge you.

To review usage, open the usage log from the AI Base workspace. [CHECK: name and menu path of the usage log list] Use standard list filters to answer questions like "which feature used the most tokens this month" or "which documents were processed by AI yesterday".

Test Connection

Use Test Connection whenever you add a provider, rotate a key or change the model. It is a quick way to catch typos and expired keys before users run into errors.

Keys stay with managers

API keys are stored encrypted. AI Users can call providers through apps, but only AI Managers and System Managers can add providers and enter or see keys. Give the AI Manager role to the people who own billing with the AI providers, not to everyone who uses AI features.

Automatic fallback

Providers are tried in priority order. When one is busy, over its cap, or can't read the file being sent, the next one answers.

1. Add two or more providers.
2. Set their priority. [CHECK: field name and ordering rule for provider priority]
3. Test each one.

A common setup is a main provider with a reasonable cap and a second provider as backup.

Reading PDFs and photos

Apps can send PDFs and images (JPEG, PNG, WebP, TIFF). Photos are rotated upright and resized to 2,400 px before sending, which keeps token use down.

Native PDF reading works with OpenAI, Claude and Gemini. Image input depends on the model you choose. If a provider can't read a file, fallback moves to the next provider.

Structured JSON answers

Developers can pass a JSON schema and get back a Python dict, ready to write into ERPNext fields without parsing free text. Support for JSON schemas depends on the model.

Calling AI from your own app

1. Declare the dependency in your app's hooks.py:

required_apps = ["ki_erp_ai_base"]

2. Call generate() from ki_erp_ai_base.api and handle the exceptions it raises:

from ki_erp_ai_base.api import generate
# [CHECK: import path for BudgetExceeded, ProviderBusy, FileNotSupported, AIError]

try:
    result = generate(
        # [CHECK: parameter names for prompt, model/provider, feature,
        #  linked document, files, JSON schema and timeout]
    )
except BudgetExceeded:
    # A monthly cap was reached. Tell the user; do not retry.
    pass
except ProviderBusy:
    # Temporary failure. Safe to retry later.
    pass
except FileNotSupported:
    # The provider can't read this file type.
    pass
except AIError:
    # Permanent failure. Log it and stop.
    pass

Usage is logged automatically, so you don't need to write your own logging.

Self-hosted models and gateways

Set the provider's Base URL to your Ollama, vLLM or NVIDIA NIM endpoint, or to a gateway or proxy. Then use Test Connection to confirm it works.

Multi-company

With ERPNext installed, each provider and usage entry has a Company, and User Permissions on Company apply. A provider without a company is shared by all companies. This lets each company have its own keys and caps, and lets you report AI costs per company.

Tips

• Start with a low cap. Raise it once you see real usage in the log.
• Set up a backup provider so a busy provider or a reached cap doesn't stop work.
• Run long jobs in the background. Calls time out after 70 seconds by default. Keep the timeout below your web worker timeout and use a background job (for example frappe.enqueue) for large documents or batches.
• Fill in the feature and linked document when calling from code, so the usage log tells you where tokens went.
• Re-test after key rotation with Test Connection.
• Match model to task. Pick a model that supports images, PDFs or JSON schemas if your feature needs them.

Limitations

• It is a connector, not an assistant. AI Base gives your ERPNext and custom apps a safe way to call AI. Features that use it are built on top.
• Model-dependent capabilities. Image input, native PDF reading and JSON schemas depend on the model you choose. Native PDF reading works with OpenAI, Claude and Gemini.
• Timeouts. Calls time out after 70 seconds by default. You can set this per provider or per call. [CHECK: name of the timeout field on the provider]
• Version 16 only. Frappe / ERPNext 15 and older are not supported.

FAQ

Is it free?

Yes. The app is free and open source under the MIT licence. You use your own API keys and pay the AI providers directly at their prices. There is no subscription and no commission.

What happens when the monthly cap is reached?

Calls to that provider stop until the next month or until a manager raises the cap. The cap is checked before each call is sent, so you are never billed past it.

Can developers use it in their own apps?

Yes. Add required_apps = ["ki_erp_ai_base"] to hooks.py and call generate() from ki_erp_ai_base.api. It raises BudgetExceeded when a cap is reached, ProviderBusy for temporary failures you can retry, FileNotSupported when a provider can't read a file, and AIError for permanent ones. Usage is logged automatically.

Can I use a self-hosted model?

Yes. Set the Base URL to your Ollama, vLLM or NVIDIA NIM endpoint, or to a gateway or proxy.

Does it work with several companies?

Yes. With ERPNext installed, each provider and usage entry has a Company, and User Permissions on Company apply. A provider without a company is shared by all companies.

Does it need ERPNext?

No. It needs only Frappe, so CRM, Helpdesk, HRMS or your own Frappe apps can use it too.

Where do I get it?

From the store page: AI Base for ERPNext.

How KalvyAI can help

AI Base is the foundation. If you want AI features built on top of it, such as reading supplier invoices into ERPNext, drafting replies in Helpdesk, or agents that work with human approvals, budgets and an audit trail, our team builds and connects ERPNext, Odoo and Shopify systems and can help you plan and ship them. We can also help with installation on your own server or Frappe Cloud bench, multi-company setup and caps. Contact us to talk about your setup.