# AI in Open Core HR

Connect your own AI provider, choose who can use each AI feature and keep usage within your limits.

AI in Open Core HR helps people write, answer everyday HR questions, fill in expense claims from receipts and answer questions about HR data, for office and field teams alike. Each feature comes from an add-on on the **Modules** page: the [AI writing assistant](https://czappstudio.com/docs/ai/writing-assistant) is free, the [HR assistant](https://czappstudio.com/docs/ai/hr-assistant), [Receipt scanning](https://czappstudio.com/docs/ai/receipt-scanning) and [Ask your HR data](https://czappstudio.com/docs/ai/ask-your-data) are paid add-ons. Every AI feature is a shortcut: people can still do the same work by hand.

AI is switched off on a new installation. Nobody sees an AI feature until an administrator connects a provider and tests it under **Settings → AI**, then turns AI on from the **AI** menu. Both need the **Manage AI** permission.

## Bring your own provider

You connect the AI provider you choose and use your own account with it, so its bill comes to you directly.

1. Open **Settings → AI**.
2. Under **Provider**, choose one:
   - **Claude**, **Gemini** or **OpenAI**: enter the API key from your account with that provider. Leave **Model** empty to use the recommended model, or pick one of the models your key can use.
   - **Custom or self-hosted**: enter the **Server address** of any server that speaks the OpenAI API, such as Ollama, LM Studio, vLLM, LiteLLM or your own gateway, and the **Model** name exactly as the server lists it. Enter an API key only if your server asks for one.
3. Select **Save**, then **Test connection**.

The key is stored encrypted and is never shown again. Text and files used in an AI action are sent to the provider you choose. With a self-hosted model they stay on your own network, so no data leaves it. The server running Open Core HR needs outbound access to the provider or to your server address.

## The connection test

The test asks the chosen model four small questions and shows each result as **Works**, **Not supported by this model** or **Could not be checked** with the reason.

| Ability | Needed for |
| --- | --- |
| Writes text | Every AI feature |
| Fills in forms | Reading a receipt |
| Looks up records | HR assistant answers from a person's own records, preparing requests, and Ask your HR data |
| Reads images | Reading a photo or scan of a receipt |

Hosted providers normally pass all four. A self-hosted model may pass only some; a feature that needs a missing ability cannot be switched on and says which part is missing. Changing the provider, model, server address or key clears the result, and AI features stop until you test again.

## Turn AI on and set limits

Day-to-day control is on the **AI** menu, which has three pages: **Overview**, **Features and access** and **Usage**.

1. Open **AI → Overview** and switch on **Turn on AI**. It is available once the provider has passed its test.
2. Set the **Monthly limit**, the most AI requests the whole workspace can make each month.
3. Set **Requests per person each month**, the most one person can make across all features.
4. Select **Save**. Enter `0` in either limit for no limit.

Overview also shows the connected provider, this month's requests against the limit, how many people used AI, and requests and tokens per feature.

When the workspace limit is reached, AI features show "This month's AI limit has been reached" until the next month or until you raise it. A person who reaches their own limit sees "You have used your AI allowance for this month"; nobody else is affected, and everything else keeps working.

## Choose who can use each feature

Open **AI → Features and access**. Every feature starts switched off.

1. Switch on each feature you want.
2. To limit a feature, select **Who can use it** and choose **Departments** and **People**. Leave both empty to allow everyone who has the permission.
3. Optionally set **Requests per person each month for this feature**, which replaces the general per-person limit for that feature.
4. Select **Done**, then **Save**.

Each feature also has its own permission on the **Roles** page. A person sees a feature only when AI is on, the feature is on, one of their roles has its permission, they are in a chosen department or named (if the feature is limited), and no limit has been reached. A feature with options of its own, such as what the HR assistant answers from, has a **More choices** link on its row. Employees have no AI settings of their own.

## Usage and privacy

Open **AI → Usage** and choose a month to see requests, people, tokens and requests that did not complete, broken down **By feature**, **By department** and **By person**. Your provider bills by tokens, so compare this page with its invoice.

For each request Open Core HR records only who made it, which feature, the model, the size of the request and when. Prompts, answers and files are not stored: only the counts, which are kept for 13 months.

## Hosted workspaces

On a hosted SaaS installation the service operator connects the provider under **Settings → AI** in the console, includes the AI add-ons in a plan and can set **AI requests a month** for that plan. Workspaces use the operator's provider and never see its key, so workspace administrators see only the **AI** menu. The plan's limit is shown beside the workspace's own monthly limit, and the lower of the two applies. See [Subscription](https://czappstudio.com/docs/saas/subscription) and [Hosting setup](https://czappstudio.com/docs/saas/hosting-setup).