# AI (Full)

---
source: /docs/ai.md

# AI

AI can help draft transactions, answer questions, build scripts, and prepare review work. Bkper keeps the source of truth in zero-sum Books: every transaction moves resources from one Account to another, balances are calculated from records, and events preserve review history.

## Where to start

Use the page that matches the task in front of you:

| If you want to...                                                                  | Start with...                                   |
| ---------------------------------------------------------------------------------- | ----------------------------------------------- |
| Turn financial source documents or emails into draft transactions                  | [Bkper Agent](https://bkper.com/docs/ai/bkper-agent.md)             |
| Ask questions from ChatGPT, Claude, or another hosted assistant without a terminal | [Bkper MCP](https://bkper.com/docs/ai/bkper-mcp-server.md)          |
| Connect an Open Responses client or agent harness to Bkper AI inference            | [Bkper AI Provider](https://bkper.com/docs/ai/bkper-ai-provider.md) |
| Build reports, scripts, reconciliations, imports, or repeatable workflows          | [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md)     |
| Understand included models, provider capabilities, and usage                       | [Models and Usage](https://bkper.com/docs/ai/models.md)             |
| Decide between connector access and terminal/local-tool workflows                  | [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md)               |
| Give Bkper documentation and API references to an AI assistant                     | [Docs for AI](https://bkper.com/docs/ai/docs-for-ai.md)             |
| Prepare tax or accounting review work with cited rules and professional handoff    | [OpenAccountants](https://bkper.com/docs/ai/openaccountants.md)     |

    - [Fundamentals](https://bkper.com/docs/ai/fundamentals.md): Understand LLMs, hallucinations, context, agents, and why financial numbers need deterministic checks.
    - [Docs for AI](https://bkper.com/docs/ai/docs-for-ai.md): Give AI assistants Bkper context using Markdown docs, llms.txt indexes, API references, and agent skills.
    - [Bkper Agent](https://bkper.com/docs/ai/bkper-agent.md): Automatic Book agent for files, attachments, descriptions, and transaction drafts.
    - [Bkper AI Provider](https://bkper.com/docs/ai/bkper-ai-provider.md): Connect any Open Responses client or agent harness using Bkper authentication.
    - [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md): Use the terminal agent with local files, shell commands, scripts, tests, and Bkper CLI context.
    - [Models and Usage](https://bkper.com/docs/ai/models.md): Compare included Bkper AI models, provider capabilities, usage rates, monthly allowances, and visibility.
    - [Bkper CLI Agent Security](https://bkper.com/docs/ai/cli-agent-security.md): Sandbox the Bkper CLI Agent, protect Bkper credentials, and scope Book permissions.
    - [Bkper MCP](https://bkper.com/docs/ai/bkper-mcp-server.md): Connect AI assistants to Bkper through conversational MCP tool calls and existing permissions.
    - [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md): Prefer CLI local tools when terminal access is available; use MCP for conversational connector access.
    - [Coding Agents](https://bkper.com/docs/ai/coding-agents.md): Build Bkper scripts, reports, apps, and integrations with grounded coding agents.
    - [OpenAccountants](https://bkper.com/docs/ai/openaccountants.md): Combine Bkper books, cited tax rules, AI-assisted worksheets, and professional review.

## Safety rule

Raw AI output is not final for balances, statements, reconciliations, taxes, or filing decisions. Use AI to draft, organize, explain, and build tools. Let Bkper records, deterministic checks, and human review carry the final financial answer.

---
source: /docs/ai/bkper-agent.md

# Bkper Agent

Bkper Agent turns documents and short descriptions into draft transactions inside Bkper. Use it to reduce data entry while keeping each result as a draft until you post it.

This page is a usage guide. The canonical app overview and current configuration reference live at [Bkper Agent](https://bkper.com/apps/bookbot.md).

> **Note: Source of truth**
> AI extraction creates drafts, not final records. In Bkper, drafts do not affect balances. Posted transactions move resources from one Account to another and update the Book.
## When it runs

Bkper Agent is installed automatically on every Book. You do not start a session or connect a separate assistant. It runs from Book events such as:

- **file uploaded** — extracts transactions from receipts, invoices, bills, statements, and CSVs;
- **transaction created** — updates transactions from attached files and uses descriptions to suggest dates, amounts, Accounts, hashtags, and properties;
- **transaction posted or updated** — learns from corrected drafts and improves future extraction patterns.

This is different from [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md), which is an interactive terminal assistant you start yourself for local files, scripts, tests, and Bkper CLI commands. It is also different from [Bkper MCP](https://bkper.com/docs/ai/bkper-mcp-server.md), which connects conversational assistants to Bkper through MCP tool calls.

For calculations, reports, reconciliations, or tax worksheets, use deterministic tools and reviewable scripts instead. See [AI Fundamentals for Finance](https://bkper.com/docs/ai/fundamentals.md).

## How documents become drafts

| Input                                    | What Bkper Agent does                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| Receipt, invoice, or bill                | One transaction with extracted date, amount, description, and properties |
| Bank or credit card statement            | One transaction per recognized statement row                             |
| CSV statement                            | Multiple transactions from rows                                          |
| File attached to an existing transaction | The existing transaction is updated and keeps the file                   |
| Email forwarded to a Book                | Attachments are parsed and kept with the resulting drafts                |

## Guide the Agent

Good results come from clear context and consistent corrections.

1. **Start from the right Account.** The Agent uses the selected context and historical transactions to infer the missing side of the movement.
2. **Use consistent descriptions and hashtags.** Reusing tags such as `#rent`, `#software`, or `#client_acme` gives the Agent stronger signals for future account matching.
3. **Correct drafts before posting.** Fix the date, amount, Accounts, description, hashtags, and properties. Posted corrections help the Agent improve future extraction.
4. **Prefer repeated corrections over one-off prompts.** If a vendor, bank, or statement format repeats, your corrected posted transactions become useful training examples.
5. **Add explicit instructions only for stable patterns.** If the same document type is repeatedly parsed wrong, add Account or Group instructions such as which column to use, which total to extract, or which property name to fill. Keep instructions factual and narrow.

For hashtag hygiene and account-matching signals, see [Hashtags](https://bkper.com/docs/guides/using-bkper/hashtags.md). For advanced prompt and parser properties, use the [Bkper Agent app reference](https://bkper.com/apps/bookbot.md#configuration).

## Before posting

Before posting an AI-created draft, check:

- **Date** — matches the transaction, purchase, service, posting, or payment date you intend to record.
- **Amount** — matches the source document or statement row.
- **From and To Accounts** — represent the actual resource movement in Bkper's from-to model.
- **Description and hashtags** — are searchable and consistent with your Book.
- **Properties** — include useful metadata, but not noisy values you do not report on.
- **Attachment** — belongs to the transaction and remains available as evidence.
- **Duplicates** — especially after importing statements or forwarding the same document twice.

If the draft is incomplete, keep it as a draft until the missing Account, date, amount, or evidence is resolved.

## Related guides

- [Bkper Agent app reference](https://bkper.com/apps/bookbot.md) — current capabilities, configuration properties, and supported file types.
- [Record Transactions by Email](https://bkper.com/docs/guides/using-bkper/record-by-email.md) — forward invoices, receipts, and statements to a Book.
- [Attachments](https://bkper.com/docs/guides/using-bkper/attachments.md) — keep documents with the transactions they support.
- [Hashtags](https://bkper.com/docs/guides/using-bkper/hashtags.md) — use tags consistently so the Agent can match patterns.
- [AI Fundamentals for Finance](https://bkper.com/docs/ai/fundamentals.md) — keep AI-assisted financial work reviewable and deterministic.

---
source: /docs/ai/bkper-ai-provider.md

# Bkper AI Provider

Bkper AI provides selected AI models through one endpoint using Bkper authentication and the AI allowance included with eligible plans. The Bkper CLI Agent is ready to use without a separate provider account or API keys. Other clients can connect through the [Open Responses `2026-04-24` contract](https://www.openresponses.org/specification/2026-04-24).

Bkper AI keeps provider credentials server-side. It routes requests, attributes usage, meters provider-reported tokens, and enforces the recorded monthly allowance. Compatible clients retain control of model and generation settings within provider-native capabilities.

Bkper AI returns model responses. It does not give a model access to Books, files, tools, or local commands. The consuming client controls those capabilities and their permissions.

## Requirements

You need:

- a Bkper account with an eligible subscription or trial allowance;
- a valid Bkper OAuth access token;
- a client that supports Open Responses with a custom base URL.

Requests are attributed to the authenticated Bkper user. Business and Professional subscriptions may use a shared domain allowance. See [Models and Usage](https://bkper.com/docs/ai/models.md) for allowance scope, current rates, and provider-native capabilities.

## Provider configuration

| Setting         | Value                                        |
| --------------- | -------------------------------------------- |
| Provider type   | Open Responses `2026-04-24` profile          |
| Base URL        | `https://ai.bkper.app/v1`                    |
| Authentication  | `Authorization: Bearer ` |
| Model discovery | `GET /v1/models`                             |
| Inference       | `POST /v1/responses`                         |

When a client asks for an API key, provide the Bkper access token. The client should send it as a bearer token. Do not use an OpenAI, Anthropic, or xAI API key with the Bkper AI base URL.

Bkper AI implements a documented subset of Open Responses. It does not claim full specification compliance.

## Get a token for local testing

Any supported Bkper OAuth flow can supply the access token. The Bkper CLI is a convenient way to obtain a short-lived token for local testing:

```bash
bkper auth login
export BKPER_TOKEN="$(bkper auth token)"
```

Treat the token as a secret. Do not commit it, print it in shared logs, or put it in a client-side application bundle.

## Send a complete request

This request uses one current model ID as an example. Use `GET /v1/models` or [Models and Usage](https://bkper.com/docs/ai/models.md) for the current portfolio.

```bash
curl --fail-with-body https://ai.bkper.app/v1/responses \
  -H "Authorization: Bearer ${BKPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "bkper-ai-source: my-harness" \
  --data '{
    "model": "openai/gpt-5.6-luna",
    "input": "Reply with exactly: connected",
    "store": false
  }'
```

The response is an Open Responses resource. Its `model` remains the public Bkper model ID, and `store` is always `false`.

The `bkper-ai-source` header is optional. Set it to a stable lowercase identifier such as `my-harness` when you want the usage dashboard to attribute requests to that client or application. The legacy `bkper-agent-id` header remains a fallback. Requests without a valid identifier appear with an unknown source.

## Stream a response

Set `stream` to `true` to receive semantic server-sent events:

```bash
curl --no-buffer --fail-with-body https://ai.bkper.app/v1/responses \
  -H "Authorization: Bearer ${BKPER_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "xai/grok-4.5",
    "input": "Explain the from-to movement model in one sentence.",
    "stream": true,
    "store": false
  }'
```

Each SSE `event:` name matches the event body's `type`. Sequence numbers increase monotonically. A stream ends with one terminal response event followed by `data: [DONE]`.

## Supported profile

The Phase 1 profile supports:

- all model IDs listed by `GET /v1/models`;
- string input and explicit conversation item arrays;
- system, developer, user, and assistant messages;
- text and image input;
- inline PDF input through Base64 `input_file.file_data` for models that advertise native file support;
- JSON Schema structured output through `text.format` for models that advertise native schema support;
- function tools, function calls, function outputs, and multiple tool calls where the model supports them;
- model-supported reasoning effort pass-through and reasoning summaries;
- encrypted reasoning continuity where the provider supplies it;
- `prompt_cache_key` for short cache and session affinity;
- complete JSON responses and semantic SSE streaming;
- explicit conversation history across supported models and providers.

The server validates model-specific file, structured-output, output, and reasoning settings before provider dispatch. Valid client values pass through unchanged. Omitted values remain omitted when the native provider protocol allows omission. Context overflow errors are normalized after the provider performs native tokenization. Provider-reported usage drives deterministic allowance settlement.

### Structured JSON output

Set `text.format.type` to `json_schema` and provide a standard JSON Schema. Bkper AI maps the schema to each model provider's native structured-output mechanism.

- `strict: true` is preserved only when the selected model can enforce the submitted schema subset.
- `strict: false` supports schemas that require provider-supported flexibility, such as typed dynamic maps.
- Malformed supported keywords and incompatible schemas fail before provider dispatch. Bkper AI never silently changes a strict schema to non-strict behavior.

The returned structured JSON is contained in the assistant `output_text` and should still be parsed and validated by the client before use.

### Inline PDF input

Use one inline PDF source with a filename:

```json
{
    "type": "input_file",
    "filename": "document.pdf",
    "file_data": "<base64>"
}
```

Bkper AI validates the Base64 content and selected model capability before dispatch. It sends inline content through the provider's native document input and does not upload it to a hidden provider Files API.

Inline files are available only on models that advertise native support. The current xAI model does not support inline `file_data`. Use `GET /v1/models` to inspect current capabilities.

## Stateless behavior

Bkper AI does not persist response state:

- omitted `store` behaves as `false`;
- `store: false` is accepted;
- `store: true` is rejected;
- continue conversations by sending explicit prior items in `input`.

`prompt_cache_key` is a bounded cache hint. It is not a persisted response identifier.

## Unsupported features

The current profile rejects:

- `previous_response_id`;
- background responses;
- response retrieval or deletion;
- client `metadata`;
- `input_file.file_id` and `input_file.file_url`;
- inline file types or models without advertised native support, including xAI inline files;
- remote HTTP/HTTPS image URLs for Gemini; send Gemini images as inline data URLs;
- hosted provider tools;
- compaction endpoints;
- WebSocket transport;
- image generation, audio, speech, batches, and fine-tuning.

Unsupported fields fail explicitly rather than being ignored or passed to only one provider.

## Errors

Errors use an Open Responses-shaped envelope with stable Bkper error codes.

| Status | Meaning                                                                           |
| ------ | --------------------------------------------------------------------------------- |
| `400`  | Invalid request, unavailable model, unsupported capability, or context overflow   |
| `401`  | Missing or invalid Bkper bearer token                                             |
| `402`  | The authenticated subscription payment is overdue                                 |
| `403`  | The account is not entitled to use Bkper AI                                       |
| `429`  | The monthly Bkper AI allowance is exhausted or the upstream provider is throttled |
| `499`  | The client aborted the request                                                    |
| `502`  | The selected upstream model provider or transport failed                          |

Bkper AI blocks new requests once the recorded monthly allowance is exhausted. There are no automatic paid Bkper AI overages and no automatic fallback to another protocol. Review the authenticated [Bkper AI usage dashboard](https://ai.bkper.app) for the current allowance and request attribution.

## Bkper CLI Agent

The Bkper CLI Agent uses Pi's standard `openai-responses` transport with Bkper authentication, source attribution, short prompt caching, and the public Bkper model IDs preconfigured.

```bash
bkper auth login
bkper agent
```

## Next steps

- [Compare models, provider capabilities, rates, and allowance rules](https://bkper.com/docs/ai/models.md).
- [Use the preconfigured Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md).
- [Review Bkper CLI Agent security](https://bkper.com/docs/ai/cli-agent-security.md).

---
source: /docs/ai/bkper-cli-agent.md

# Bkper CLI Agent

The Bkper CLI includes a built-in terminal AI agent. Use it when you want an agent to work with local files, shell commands, scripts, tests, and Bkper CLI context in the same local environment.

This is Bkper's recommended starting point for local AI-assisted development. The canonical install, authentication, and command reference lives at [Bkper CLI](https://bkper.com/apps/bkper-cli.md).

## Use it when

- You want an agent to inspect local project files or `AGENTS.md`.
- You need shell commands, pipes, scripts, tests, or exported CSVs.
- You are building a repeatable report, import, cleanup, or integration.
- You want deterministic checks instead of raw AI answers for financial outputs.

For conversational connector access without terminal commands, use [Bkper MCP](https://bkper.com/docs/ai/bkper-mcp-server.md). For the full decision guide, see [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md).

## Install on Windows with WSL

Run Bkper inside WSL rather than PowerShell. If WSL is not set up yet:

1. **Install WSL**

    Open **PowerShell as Administrator** and run:

    ```powershell
    wsl --install
    ```

    Restart Windows if prompted, then open **Ubuntu** from the Start menu and create your Linux username and password.

    Reference: [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install).

2. **Install Node.js**

    In the **Ubuntu terminal**, run:

    ```bash
    sudo apt update
    sudo apt install -y curl
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
    source ~/.bashrc
    nvm install --lts
    ```

    Reference: [Set up Node.js on WSL](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl).

3. **Install and open Bkper**

    Still in the **Ubuntu terminal**, run:

    ```bash
    npm i -g bkper
    bkper
    ```

    If the Bkper Agent opens, the installation is working.

    Reference: [Bkper CLI](https://bkper.com/apps/bkper-cli.md).

## Quick start

1. **Authenticate with Bkper**

    ```bash
    bkper auth login
    ```

    This authenticates the CLI Agent with the preconfigured Bkper AI provider. You can instead start the agent first and use `/login`; both flows share the same local credentials and identify the authenticated account by email. See [Bkper AI Provider](https://bkper.com/docs/ai/bkper-ai-provider.md) for the client-agnostic inference interface and [Models and Usage](https://bkper.com/docs/ai/models.md) for the current portfolio, provider capabilities, rates, and allowance policy.

2. **Start the terminal agent**

    ```bash
    bkper
    ```

    or:

    ```bash
    bkper agent
    ```

3. **Optionally connect another model provider**

    Type `/connect` to choose an external subscription or API-key provider. Use `/connect <provider>` to target one directly, such as `/connect openai` or `/connect anthropic`.

[Image: Bkper CLI Agent terminal interface showing the Bkper ASCII art header, command shortcuts, context, and an active input prompt]

## Why we recommend it

The Bkper CLI Agent is powered by [Pi Agent](https://pi.dev) with Bkper context built in: core concepts, SDK references, CLI commands, and the from-to accounting model.

We chose Pi because it is:

- **Token efficient** — lean context and tool loading for longer, cheaper sessions.
- **Well implemented** — a small, reliable core instead of a heavy black box.
- **Open source** — inspectable, extensible, and easier to improve.
- **Provider agnostic** — 15+ model providers, local models, and no vendor bias.
- **Bundled with Bkper** — one install gives you the agent plus Bkper domain context.

## Model providers

The Bkper CLI Agent ships with Bkper AI already configured, so no separate model-provider setup is required. Bkper authentication supplies the same access token accepted by the client-agnostic inference provider. See [Bkper AI Provider](https://bkper.com/docs/ai/bkper-ai-provider.md) to connect another compatible client. See [Models and Usage](https://bkper.com/docs/ai/models.md) for current rates, provider capabilities, and allowance rules.

The Bkper CLI applies its own operation profile to included models:

| CLI setting                             | Value          |
| --------------------------------------- | -------------- |
| Managed context window (GPT-5.6 models) | 272,000 tokens |
| Managed context window (Grok 4.5)       | 200,000 tokens |
| Maximum output                          | 32,000 tokens  |
| Luna, Terra, and Grok startup reasoning | High           |
| Sol startup reasoning                   | Medium         |

These are Bkper CLI client settings, not server-enforced Bkper AI limits. Other Open Responses clients can choose their own lower budgets and any provider-supported reasoning effort.

To use another provider, type `/connect` and choose a subscription or API key. External provider costs and terms are governed by that provider. We recommend [OpenCode Go](https://opencode.ai/go) for low-cost open-weight models. For external frontier model access, use a [Codex subscription](https://developers.openai.com/codex/pricing) — one of the most affordable ways to use frontier models in coding agents.

The authentication commands have distinct roles:

- `/login` and `/logout` manage Bkper authentication.
- `/connect [provider]` and `/disconnect [provider]` manage external model providers.

Once authenticated, you're in an interactive session. The agent can read your project files, run CLI commands, write code, and iterate with you — all with Bkper context already loaded.

## Built-in safety

The Bkper CLI Agent is configured to work in reviewable steps: inspect context, explain plans, show commands for Bkper writes, and wait for confirmation before mutating data. You still approve changes and review financial outputs.

## Starter prompts

```text
Explain the account types in this Bkper book and list anything that looks unusual.
```

```text
Find possible duplicate transactions from last month. Do not modify anything; show me the query and reasoning first.
```

```text
Write a script that exports a monthly profit and loss report from Bkper balances. Keep the calculation deterministic and add a simple test fixture.
```

```text
Review unchecked transactions from this month and suggest what needs attention. Do not post, check, or edit transactions.
```

```text
Prepare an exploratory tax worksheet for 2025 from my Bkper data. Use Bkper as the source of truth and mark assumptions explicitly.
```

## Watch walkthroughs

Optional walkthroughs:

- [Bkper CLI Agent walkthrough](https://www.youtube.com/watch?v=gFkOZjfEOf8)
- [Bkper CLI Agent workflow example](https://www.youtube.com/watch?v=0fSyYdwwR_I)
- [Lucas Meijer on Pi's minimal, hackable design philosophy](https://www.youtube.com/watch?v=fdbXNWkpPMY)
- [Pi Agent overview and capabilities](https://www.youtube.com/watch?v=Dli5slNaJu0)
- [Pi architecture explained: agent loop, tools, TUI, and more](https://www.youtube.com/watch?v=gTeujlv8qK0)

## Security

The agent runs with your local workspace access and the Bkper permissions of the account used by `bkper auth login`. Before using it with real data, read [Bkper CLI Agent Security](https://bkper.com/docs/ai/cli-agent-security.md).

## Reference

Use [Bkper CLI](https://bkper.com/apps/bkper-cli.md) for canonical installation, authentication, CLI command reference, and current agent behavior.

---
source: /docs/ai/bkper-mcp-server.md

# Bkper MCP

Bkper MCP is the hosted Model Context Protocol server for Bkper. It lets AI assistants call Bkper tools through your existing Bkper account permissions.

This page is a high-level orientation. The canonical setup, endpoint, and current capability reference lives at [Bkper MCP](https://bkper.com/apps/bkper-mcp.md).

## Use it when

- You want conversational assistant access to your Bkper books.
- You are doing quick, read-heavy exploration.
- You need connector-based access without terminal commands.
- Local files, shell commands, tests, and scripts are not required.

The hosted endpoint is:

```text
https://mcp.bkper.app/mcp
```

Follow [Bkper MCP](https://bkper.com/apps/bkper-mcp.md) for setup instructions because connector screens and capabilities can change.

## Try asking

Good first questions are narrow and reviewable:

- “List my books and show which one looks like the operating company.”
- “Show the main accounts and groups in this book.”
- “Summarize unchecked transactions from last month.”
- “Find transactions that may need review before reconciliation.”

For any write, give the assistant a standing instruction:

```text
Before making any change in Bkper, explain the exact plan and ask for my confirmation.
```

## Safety model

When you connect Bkper MCP:

- you authorize access with Bkper OAuth;
- your existing Bkper permissions still apply;
- Bkper remains the source of truth for books, transactions, groups, accounts, balances, permissions, lock dates, and audit history;
- write operations should require an explicit plan and your confirmation before they happen.

## Use CLI instead when

If your assistant can run terminal commands, prefer CLI local tools for Bkper work. MCP is usually not the strongest path for work that needs local artifacts:

- scripts and repeatable reports;
- shell pipes, `jq`, CSV transformations, or local files;
- app development;
- tests and deterministic build artifacts;
- long multi-turn work that benefits from project context.

For those workflows, use CLI local tools whenever possible. See [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md).

## Related pages

- [Bkper MCP](https://bkper.com/apps/bkper-mcp.md) — canonical setup and reference.
- [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md) — choose how an AI assistant should use Bkper.

---
source: /docs/ai/cli-agent-security.md

# Bkper CLI Agent Security

The Bkper CLI Agent runs in your terminal with local workspace access and the Bkper permissions of the account used by `bkper auth login`. A misconfigured local agent can read credentials, overwrite files, or modify live financial data.

This page covers the Bkper CLI Agent. Other AI tools and hosted connectors should be secured with their own vendor-specific controls.

> **Tip: Recommended safe setup**
> Run the Bkper CLI Agent in a sandbox. Authenticate with a secondary low-permission Bkper account. Log out when finished.
Three layers of protection keep Bkper CLI Agent work safe:

[Image: Three layers of agent security: sandbox isolation restricts what the agent can reach, credential protection controls how the agent authenticates, and permission scoping limits what the agent can do in Bkper]

## Sandbox isolation

The most effective way to limit the Bkper CLI Agent is to run it inside a sandbox — a container, micro-VM, or OS-level boundary that restricts what it can reach.

[Image: Sandbox isolation: the agent can only access project files, CLI, and SDK inside the sandbox boundary, while credentials, SSH keys, and other sensitive files on the host machine remain unreachable]

The Bkper CLI Agent may run local shell commands without per-command approval. Per-command approval sounds safe, but it creates friction that kills productivity when the agent needs to run builds, tests, and CLI commands.

That local autonomy should stay inside a restricted boundary. For Bkper writes, the agent should still show the plan or exact command and wait for your confirmation before modifying live financial data.

### Container or micro-VM sandboxing

Use a container or micro-VM boundary when the Bkper CLI Agent works with real data. We use Docker with [DevContainers](https://containers.dev) and [DevPod](https://devpod.sh) to get reproducible, isolated environments that work the same way locally and in the cloud.

Other sandbox tools worth knowing about:

- [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) — microVM-based sandboxes built for coding agents, with host-side credential injection
- [Gondolin](https://earendil-works.github.io/gondolin/) — lightweight micro-VMs with programmable network egress and secret injection
- [Podman](https://podman.io) — rootless, daemonless Docker alternative

## Credential protection

Even inside a sandbox, the Bkper CLI Agent can access any credentials present in that environment. The Bkper CLI stores OAuth credentials (including a refresh token) at `~/.config/bkper/.bkper-credentials.json`. If the agent can read that file, it can make API calls as you.

### Host-side credential injection

The most secure option. Your credentials never enter the sandbox — an HTTP proxy on the host intercepts outbound API requests and injects authentication headers before forwarding them. [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/security/credentials/) and [Gondolin](https://earendil-works.github.io/gondolin/) implement this pattern.

This works well with the Bkper CLI because only an explicit Bkper login—`bkper auth login` or `/login` inside the agent—starts the interactive device authorization flow. Regular CLI commands can proceed without local credentials and let the proxy add authentication.

### Login inside the sandbox, then logout cleanly

This is the simplest practical workflow for many teams. Authenticate inside the sandbox with a secondary low-permission account:

```bash
bkper auth login
```

When you are done, revoke the refresh token and remove the local credentials:

```bash
bkper auth logout
```

`bkper auth logout` does both:

- revokes the stored refresh token remotely when possible
- clears local credentials from disk

If remote revocation fails, the CLI still clears local credentials and warns that remote cleanup may need manual follow-up.

## Permission scoping

The Bkper CLI authenticates as the user who ran `bkper auth login`. If that user is the book owner, the Bkper CLI Agent has owner-level access — it can delete accounts, change sharing settings, and modify lock dates.

**Use a secondary account with limited permissions instead.** Log into the CLI with a different Google account (for example, a personal Gmail), then share the target book with that account at the appropriate level:

| Permission        | What the agent can do                                 | Good for                                 |
| ----------------- | ----------------------------------------------------- | ---------------------------------------- |
| **View Only**     | Read accounts, transactions, and balances             | Read-only scripts, reporting, analysis   |
| **Record Only**   | Create and delete drafts                              | Automated data entry with human review   |
| **Record & View** | Record drafts, post transactions, view data           | Most development and testing workflows   |
| **Editor**        | Full data management (accounts, groups, transactions) | Building apps that manage book structure |

Avoid granting **Owner** permission to the Bkper CLI Agent account. Owner access allows sharing changes, closing-date modifications, and other irreversible operations that should remain under direct human control.

For the full permissions matrix, see [Book Sharing — Permissions](https://bkper.com/docs/guides/using-bkper/book-sharing.md#permissions).

### Combining layers

A typical secure setup:

1. **Sandbox** — Bkper CLI Agent runs inside a DevContainer, Docker Sandbox, or micro-VM with only the project directory mounted
2. **Credentials** — either injected from the host, or authenticated inside the sandbox and explicitly revoked with `bkper auth logout` when work is done
3. **Permissions** — CLI authenticated as a secondary account with Record & View access

No single layer is bulletproof, but together they limit exposure to a narrow, time-bound, permission-scoped window.

---
source: /docs/ai/cli-vs-mcp.md

# CLI vs MCP

Bkper offers two ways for AI assistants to use your data:

- **MCP tool calls** connect an assistant directly to Bkper for conversational analysis.
- **CLI local tools** let an assistant work through your terminal, files, scripts, tests, and app workflows.

Default rule: if your assistant can run terminal commands, prefer CLI local tools for Bkper work. Use MCP when terminal access is not available, or when you specifically want conversational connector access.

CLI local tools can do the same Bkper operations as MCP, plus scripts, files, tests, builds, app workflows, and reusable artifacts. They are usually more efficient, cost-effective, and scalable for multi-turn or repeatable work because more execution happens outside the LLM context.

## Quick choice

| Choose...           | When you need...                                                                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP tool calls**  | conversational exploration, suspicious-transaction review, book-structure questions, guided analysis, or assistant access without a terminal |
| **CLI local tools** | setup scripting, app creation and management, build/deploy workflows, CSVs, local files, tests, repeatable reports, or auditable artifacts   |

### MCP tool calls

With MCP, the assistant calls Bkper tools directly. Each tool result returns to the LLM context before the next call, so context can grow across the session. This is useful for conversational analysis, but less efficient for long, repeatable workflows.

### CLI local tools

With CLI local tools, the assistant works through a local environment. It can create or run scripts, call command-line tools, and receive selected output. Scripts and pipes can also run without sending every intermediate result back to the LLM context.

## When CLI local tools fit best

CLI local tools give the agent more than Bkper access. They give it a working environment:

- **App lifecycle work** — setup, app creation, build, sync, deploy, and management workflows belong in the CLI local-tool path. MCP can help discuss app design, but it is not the app build/deploy environment.
- **Durable context** — files, exports, fixtures, scripts, and reports stay in the workspace.
- **Tool chaining** — commands can be piped together without adding every intermediate result to the LLM context.
- **Deterministic runs** — scripts and build engines can be run again with the same inputs and reviewed outputs.
- **Reusable work** — a report, app, migration, or reconciliation helper can be rerun, tested, improved, and committed.
- **Better review** — proposed changes can be shown as commands, diffs, CSVs, or generated artifacts before anything is applied.

Example:

```bash
bkper transaction list -b <bookId> -q 'on:2026-06' --format json \
  | jq '.items[] | {date, description, amount}'
```

That matters for finance: raw LLM output should not be the final answer for accounting numbers. When a workflow produces balances, statements, reconciliations, taxes, or batch changes, prefer a deterministic route that can be rerun and reviewed.

## Where MCP fits well

Use MCP when conversational access matters more than local files, scripts, or command-line workflows:

- asking an AI assistant to summarize book structure;
- listing books, accounts, groups, transactions, or balances;
- exploring data before deciding what to do next;
- reviewing or spotting suspicious transactions interactively;
- working from a device or environment where a terminal is not practical;
- giving an assistant controlled access through the Bkper connector.

MCP can also be useful inside local coding tools as an extra connector. But if the agent can already run shell commands, use the Bkper CLI for Bkper operations and app lifecycle work, and use MCP as a supplement when it fits the interaction.

## Recommended path

1. If your assistant can run terminal commands, install and authenticate the [Bkper CLI](https://bkper.com/apps/bkper-cli.md).
2. Use CLI local tools for multi-turn Bkper workflows, scripts, app lifecycle work, builds, tests, and auditable artifacts.
3. Use [Bkper MCP](https://bkper.com/docs/ai/bkper-mcp-server.md) when terminal access is unavailable or when you specifically want conversational connector access.

## Related pages

- [AI Fundamentals for Finance](https://bkper.com/docs/ai/fundamentals.md)
- [Docs for AI](https://bkper.com/docs/ai/docs-for-ai.md)
- [Bkper CLI Agent Security](https://bkper.com/docs/ai/cli-agent-security.md)

---
source: /docs/ai/coding-agents.md

# Coding Agents

AI coding agents are the fastest way to go from idea to working Bkper integration. They can scaffold projects, write SDK code, debug issues, and iterate with you in real time — as long as they have the right context about the platform.

Use this page when you already have a preferred coding agent, or when you want to compare agent harnesses. If you want Bkper's recommended first-party terminal workflow, start with [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md).

> **Tip: New to AI?**
> If you're new to how LLMs, context, and agents work, read [AI Fundamentals](https://bkper.com/docs/ai/fundamentals.md) first. It covers the mental model you need before building with AI.
> **Caution: Security**
> Coding agents run with your permissions. Follow each tool's own sandboxing, credential, and permission guidance. For Bkper's first-party terminal workflow, see [Bkper CLI Agent Security](https://bkper.com/docs/ai/cli-agent-security.md).
## Recommended default

If you don't already have a preferred coding agent, start with [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md). It ships with the Bkper CLI, has Bkper's from-to accounting model and CLI context built in, and can work with local files, shell commands, scripts, and tests in the same local environment.

Use the rest of this page when you want to bring Bkper context into another agent such as Claude Code, Cursor, Codex, OpenCode, Pi, or AMP.

## Other agents

Any coding agent can build effectively with Bkper when given the right context. Here are the ones we've used and recommend. The same approach also applies to general-purpose personal agents such as OpenClaw and Hermes Agent when they can run local tools.

| Agent                                                 | Type                   | Models                                                                             | What it is                                                         |
| ----------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [Pi Agent](https://pi.dev)                            | Terminal               | 15+ providers — Anthropic, OpenAI, Google, and more                                | Minimal, extensible harness — the engine behind Bkper CLI Agent    |
| [Claude Code](https://claude.com/product/claude-code) | Terminal, Desktop, IDE | Claude models                                                                      | Anthropic's full-featured agent across all surfaces                |
| [OpenCode](https://opencode.ai)                       | Terminal, Desktop, IDE | 75+ providers — free models included, works with Copilot and ChatGPT subscriptions | Open-source agent with the largest provider ecosystem              |
| [Codex](https://openai.com/codex/)                    | Terminal, Desktop, IDE | OpenAI — works with your ChatGPT plan                                              | OpenAI's open-source coding agent                                  |
| **[AMP](https://ampcode.com)**                        | Terminal               | Multiple providers — works with Claude, OpenAI, and more                           | Open-source coding agent built for AI-native development workflows |
| [Cursor](https://cursor.com)                          | Terminal, Desktop, IDE | Multiple providers built in                                                        | AI-native code editor with a terminal agent                        |

Each tool has its own way of loading project context. The next section explains how to provide Bkper knowledge to any of them.

## Add Bkper context

Bkper CLI Agent has context built in. For other agents, you need to provide it.

### Install the Bkper CLI plugin or skill

Install and authenticate the CLI first when the agent needs live Bkper access:

```bash
npm i -g bkper
bkper auth login
```

Then add Bkper context to your agent.

For Codex, add this repository as a plugin marketplace, then install the `bkper-cli` plugin from Codex's plugin directory:

```bash
codex plugin marketplace add bkper/bkper-cli
```

For Claude Code, install the Bkper CLI plugin from this repository's Claude marketplace:

```text
/plugin marketplace add bkper/bkper-cli
/plugin install bkper-cli@bkper
```

For other external agents that support the [Agent Skills standard](https://agentskills.io) and can run local shell commands, install the Bkper CLI skill:

```bash
npx skills add bkper/bkper-cli --skill bkper-cli
```

The Codex and Claude Code plugins package the same portable Bkper CLI skill for their native plugin flows. The skill gives other harnesses Bkper's from-to accounting model, CLI references, SDK pointers, and safety guardrails for operating the local `bkper` CLI. [Source on GitHub](https://github.com/bkper/bkper-cli/tree/main/skill).

### Direct Markdown access

If your agent doesn't support skills, or if you only need general Bkper knowledge without local CLI operations, load context manually. Every page on bkper.com is available as clean Markdown — append `.md` to any URL:

```text
https://bkper.com/docs/core-concepts.md
https://bkper.com/docs/api/bkper-js.md
https://bkper.com/docs/build.md
```

This strips navigation chrome and reduces token usage. See [Docs for AI](https://bkper.com/docs/ai/docs-for-ai.md) for all access methods.

Three URLs cover most Bkper development needs:

| URL                                                                 | What it covers                                                  |
| ------------------------------------------------------------------- | --------------------------------------------------------------- |
| [`/platform/agents.md`](https://bkper.com/platform/agents.md)       | Technical instincts, quality standards, domain sensibilities    |
| [`/docs/core-concepts.md`](https://bkper.com/docs/core-concepts.md) | The from-to model, account types, transactions, groups, queries |
| [`/docs/api/bkper-js.md`](https://bkper.com/docs/api/bkper-js.md)   | Full bkper-js SDK reference with TypeScript types               |

Use whichever combination your project needs.

### Project-level context files

For project-specific knowledge — which book you're working with, what accounts matter, what tags to use — add it to your agent's context file (`AGENTS.md`, `CLAUDE.md`, or equivalent):

```markdown
## Project context

- Book ID: abc123-def456
- Key accounts: Checking, Sales, Accounts Receivable
- Common tags: #invoice, #payment, #reconciled

## Rules

- All automated transactions must be created as drafts
- Use the #sync tag on all imported transactions
```

This gives the agent project-specific knowledge that no published doc can provide.

## Next steps

- [Your First App](https://bkper.com/docs/build/apps/first-app.md) — build and deploy a full Bkper app (a great task to pair with an AI agent)
- [CLI Scripting & Piping](https://bkper.com/docs/build/scripts/cli-pipelines.md) — automate data workflows with CLI pipes
- [Apps Overview](https://bkper.com/docs/build/apps/overview.md) — understand the Bkper Platform architecture

---
source: /docs/ai/docs-for-ai.md

# Docs for AI

Use this page when you want to give Bkper documentation to an AI assistant without copying entire web pages. It works for hosted chat tools and coding agents.

Every page on bkper.com is available as clean Markdown. Navigation chrome — sidebar, header, footer — is stripped, reducing token usage for AI tools.

## Formats

Three ways to get docs into your AI. Pick the one that matches your workflow.

### `llms.txt` — explore

A structured index of every article with descriptions. Start here when you want your AI to browse and pick what to read.

- [`/llms.txt`](https://bkper.com/llms.txt) — all site content
- [`/docs/llms.txt`](https://bkper.com/docs/llms.txt) — all docs
- [`/docs/ai/llms.txt`](https://bkper.com/docs/ai/llms.txt) — AI docs
- [`/docs/guides/llms.txt`](https://bkper.com/docs/guides/llms.txt) — user-facing guides
- [`/docs/build/llms.txt`](https://bkper.com/docs/build/llms.txt) — developer docs
- [`/docs/api/llms.txt`](https://bkper.com/docs/api/llms.txt) — API libraries at a glance

### `llms-full.txt` — deep dive

The complete text of every article in a scope. No links to chase, no extra requests. Use this when you need comprehensive context on a specific topic.

- [`/llms-full.txt`](https://bkper.com/llms-full.txt) — all site content
- [`/docs/llms-full.txt`](https://bkper.com/docs/llms-full.txt) — all docs
- [`/docs/ai/llms-full.txt`](https://bkper.com/docs/ai/llms-full.txt) — all AI docs
- [`/docs/build/apps/llms-full.txt`](https://bkper.com/docs/build/apps/llms-full.txt) — all app docs
- [`/docs/build/scripts/llms-full.txt`](https://bkper.com/docs/build/scripts/llms-full.txt) — all script docs

### `.md` — single page

Any individual page as Markdown. Use this when you already know the exact page you need.

Append `.md` to the URL:

```text
https://bkper.com/about.md
https://bkper.com/docs/core-concepts.md
https://bkper.com/docs/ai/cli-vs-mcp.md
```

```sh
curl https://bkper.com/docs/core-concepts.md
```

Or request it via the `Accept` header — no URL modification needed:

```sh
curl https://bkper.com/docs/core-concepts \
  -H "Accept: text/markdown"
```

The response includes an `x-markdown-tokens` header with the estimated token count, which agents can use to plan context window usage:

```text
HTTP/2 200
content-type: text/markdown; charset=utf-8
vary: Accept
x-markdown-tokens: 1850
```

Every documentation page also has a **View as Markdown** link in the right sidebar. It opens the current page's `.md` version in the same tab.

## API references

API reference endpoints compile the library overview and full spec into a single compact document optimized for agent workflows:

- [`/docs/api/rest.md`](https://bkper.com/docs/api/rest.md) — endpoints, parameters, and data models
- [`/docs/api/bkper-js.md`](https://bkper.com/docs/api/bkper-js.md) — bkper-js README + TypeScript definitions
- [`/docs/api/bkper-gs.md`](https://bkper.com/docs/api/bkper-gs.md) — bkper-gs README + TypeScript definitions
- [`/docs/api/bkper-api-types.md`](https://bkper.com/docs/api/bkper-api-types.md) — shared TypeScript type definitions
- [`/docs/api/bkper-web-auth.md`](https://bkper.com/docs/api/bkper-web-auth.md) — OAuth browser SDK

Compiled Markdown vs raw source:

| Library         | Raw tokens | `.md` tokens | Reduction |
| --------------- | ---------: | -----------: | --------: |
| REST API        |       ~38K |          ~9K |        4× |
| bkper-js        |       ~32K |         ~18K |      1.8× |
| bkper-gs        |       ~22K |         ~12K |      1.9× |
| bkper-api-types |       ~12K |          ~5K |      2.4× |
| bkper-web-auth  |        ~2K |          ~2K |       ~1× |

## Agent skills and plugins

For coding agents that support plugins or Agent Skills, use the Bkper CLI skill instead of manually pasting docs.

- [Coding Agents](https://bkper.com/docs/ai/coding-agents.md#install-the-bkper-cli-plugin-or-skill) — install the Codex plugin, Claude Code plugin, or portable Agent Skill.
- [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md) — use Bkper's first-party terminal agent with context built in.
- [Source on GitHub](https://github.com/bkper/bkper-cli/tree/main/skill) — inspect the generated skill package.

---
source: /docs/ai/fundamentals.md

# AI Fundamentals for Finance

Most people meet AI through a chat box. You type a question, you get an answer, and it feels like a calculator that talks. It is not. Working with AI in accounting — where numbers must be correct, not approximately correct — requires a different mental model.

This page covers the minimum you need: how Large Language Models behave, what to feed them, how to ask, how agents work, and the one rule that keeps AI usable for finance.

## LLM Nature

A Large Language Model does not look up answers. It predicts the most likely next word, piece by piece, with randomness baked in. Different models trade off speed for depth, but all share this nature.

The consequence is unintuitive: **the same prompt can produce different answers**. Ask an LLM to compute a tax three times and you may get three slightly different numbers. The fourth try might be wrong by a wider margin.

LLMs are **probabilistic**, not deterministic. Treat their direct output as a draft, never as a verdict.

## Hallucinations

When an LLM does not know something, it does not stop. It guesses — fluently, confidently, and often wrongly. It will invent account names that don't exist, cite tax rules that were never written, and reference invoices it has never seen. This is called **hallucination**, and it is not a bug to be patched away. It is a direct consequence of how the model works.

The lesson is simple: **never trust raw LLM output for facts**. Verify, ground, or — better — route the work through something deterministic.

## Context

Hallucinations get worse when the model has nothing to ground itself on. That is where context comes in.

An LLM only knows what is in its **context window** right now: your current prompt, the files you attached, the recent conversation. It does not know your books. It does not remember last week. Each session starts blank.

You build context by handing it relevant pieces — a chart of accounts, a transaction list, a policy document, a project's `AGENTS.md`, an installed skill. Persistent context, such as skills or project files, saves you from pasting the same information every time.

But context has a sweet spot. Too little, and the model invents. Too much, and it loses focus, mixes unrelated pieces, and slows down. **The key is curation** — give the model exactly what it needs to answer the question in front of it, nothing more.

The curve never touches zero because better context reduces hallucination risk; it does not make the model deterministic.

## Intent

Intent means telling AI what done looks like, not listing every step.

A useful prompt names four things: **outcome**, **reason**, **source of truth**, and **success criteria**.

#### Old habit: step-by-step

> “Open my book, filter transactions tagged `#sales` for Jan–Mar, sum the VAT column, convert to EUR, give me the total.”

You are scripting the work. The model can still misread a step, skip one, or invent around it.

#### Better habit: intent

> “I need the VAT I owe for Q1 2025, in EUR, ready to file. Use my Bkper book as the source of truth.”

You describe the outcome. The agent can decide which transactions to pull, which tag to trust, which math to run, and whether to answer directly or write a small script.

#### Success criteria

Pair intent with a concrete check: an expected total or range, a report shape that matches last quarter's, a reconciliation that should come out to zero, or a specific account whose closing balance you know. Without that, the model has no way to know when it is done — and neither do you.

## Agents

An **agent** is an LLM running in a loop with tools. At each step the model proposes an action, runs a tool — a CLI command, a script, an API call — and observes the result. That observation feeds the next step, which may be progress, a correction, a retry, or a different approach. The loop keeps turning until the success criteria are met.

This is the shape behind the [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md) and other tool-using AI assistants. The success criteria is what closes the loop — without it, a probabilistic engine running freely produces drift, not progress. And a loop is only as trustworthy as the tools inside it.

## AI in Accounting

AI fundamentals apply across finance. The accounting layer is where they get strict — because accounting numbers don't have a tolerance band.

Accounting cannot be 99% right. A balance sheet that is mostly correct is wrong. A tax filing that is approximately accurate is a problem. And no technique — better prompts, richer context, smarter agents — makes an LLM's output guaranteed correct. Errors will happen, and inside an agent loop they compound silently between checks.

So the rule is not _make the AI correct_. Nothing makes the AI correct. The rule is:

> **Never let unverified LLM output be the final word on a number.**

The practical question is how to keep verification cheap. That is what code is for.

When an LLM writes a script that computes the answer, you stop verifying outputs and start verifying the script. You read it once, test it, and trust it as long as it doesn't change. From then on the same inputs give the same outputs, auditable line by line. Verification becomes a one-time cost instead of a per-result cost.

That shifts the rule into a practical split:

- **Deterministic work** — tax calculations, reports, reconciliations, financial statements, balance computations — has a single correct answer that must be reproducible. Have the LLM write code or call a deterministic tool, then verify the code, not each output. The work becomes repeatable, auditable, and reusable.
- **Non-deterministic work** — spotting suspicious transactions, surfacing business insights, bootstrapping a chart of accounts, summarizing a period — has no single correct answer. Direct LLM output is acceptable here, but only as a draft for a human to review and decide on.

In both cases the human stays in the loop. AI doesn't remove the reviewer; it changes what arrives for review. With code carrying the deterministic load, the human is checking artifacts a human can actually check — a script, a report engine, an app — instead of re-checking every number the model emits.

## Further watching

- [“Never Trust An LLM”](https://www.youtube.com/watch?v=9VNG0h4pLh0) by Matt Pocock — a developer-oriented explanation of why LLM output must be verified instead of trusted directly.

## What's next

- [Docs for AI](https://bkper.com/docs/ai/docs-for-ai.md) — get Bkper docs and context into AI tools.
- [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md) — choose how an AI assistant should use Bkper.
- [Coding Agents](https://bkper.com/docs/ai/coding-agents.md) — build Bkper integrations with grounded coding agents.

---
source: /docs/ai/models.md

# Models and Usage

Bkper AI includes access to selected AI models with eligible Bkper plans. Sign in with Bkper instead of setting up separate provider accounts or API keys. Use the models through the Bkper CLI Agent or another compatible client, with usage tracked against one monthly allowance.

To configure authentication, endpoints, and compatible clients, see [Bkper AI Provider](https://bkper.com/docs/ai/bkper-ai-provider.md).

## Cost control by design

Bkper AI combines ready-to-use access with a centralized allowance:

- **Ready to use.** The Bkper CLI Agent connects with your Bkper login. No separate provider setup is required.
- **Included, not billed separately.** AI usage draws from a monthly allowance included in eligible plans. There is no separate AI bill.
- **Choose by task.** Switch among selected models based on the work, capability, and usage rate you need.
- **Centralized allowance enforcement.** Bkper AI meters provider-reported usage and blocks new requests once the recorded monthly allowance is exhausted. No automatic paid overages are charged.
- **Bring another provider when needed.** External providers remain available where supported and do not consume the Bkper AI allowance.

Requests already in flight can settle after the allowance snapshot used for admission. This means recorded usage can exceed the allowance slightly under concurrency, but Bkper does not automatically bill that difference as a paid AI overage.

## Choose a model

Choose a model based on its workload, cost, and capabilities. Clients can request lower output budgets and any reasoning effort listed for the selected model.

| Model | Best for | Capabilities |
| --- | --- | --- |
| **Gemini 3.5 Flash** `google/gemini-3.5-flash` | Fast Gemini model balancing multimodal reasoning, tool use, and cost. | Reasoning efforts: `low`, `medium`, `high`<br />Maximum context: 1,048,576 tokens<br />Maximum output: 65,536 tokens |
| **GPT-5.6 Luna** `openai/gpt-5.6-luna` | Cost-efficient GPT-5.6 model for fast, high-volume workloads. | Reasoning efforts: `none`, `low`, `medium`, `high`, `xhigh`<br />Maximum context: 1,050k tokens<br />Maximum output: 128k tokens |
| **GPT-5.6 Terra** `openai/gpt-5.6-terra` | Balanced GPT-5.6 model for capable, cost-efficient everyday work. | Reasoning efforts: `none`, `low`, `medium`, `high`, `xhigh`<br />Maximum context: 1,050k tokens<br />Maximum output: 128k tokens |
| **GPT-5.6 Sol** `openai/gpt-5.6-sol` | Frontier GPT-5.6 model for complex professional work, coding, and agentic workflows. | Reasoning efforts: `none`, `low`, `medium`, `high`, `xhigh`<br />Maximum context: 1,050k tokens<br />Maximum output: 128k tokens |
| **Grok 4.5** `xai/grok-4.5` | xAI's latest Grok for chat, coding, agentic tools, and lower hallucination risk. | Reasoning efforts: `low`, `medium`, `high`<br />Maximum context: 500k tokens<br />Maximum output: 500k tokens |

The table shows each model's maximum supported capabilities. Bkper CLI uses a 272,000-token context window for GPT-5.6 models and 200,000 tokens for Grok 4.5, with a 32,000-token maximum output. Other compatible clients can use the settings supported by each model.

## Usage rates

Usage rates reduce the included monthly allowance. They are not billed separately by Bkper.

**USD of included usage per one million tokens**

| Model | Input | Cache read | Cache write | Output |
| --- | ---: | ---: | ---: | ---: |
| Gemini 3.5 Flash | $1.50 | $0.15 | $0.00 | $9.00 |
| GPT-5.6 Luna | $1.00 | $0.10 | $1.25 | $6.00 |
| GPT-5.6 Terra | $2.50 | $0.25 | $3.125 | $15.00 |
| GPT-5.6 Sol | $5.00 | $0.50 | $6.25 | $30.00 |
| Grok 4.5 | $2.00 | $0.50 | $0.00 | $6.00 |

Input means tokens sent without a cache match. Cache read means reused input already stored by the provider. Cache write means input added to a provider cache. Output includes generated response and reasoning tokens reported by the provider.

## Monthly allowance

For paid plans:

> **Monthly AI usage allowance = 50% of normalized monthly software subscription value.**

The calculation works as follows:

- Monthly plans use the active recurring software subscription value.
- Annual plans divide the annual recurring value by 12, then apply 50%.
- Professional and custom plans use only the recurring software subscription component.
- Professional services, implementation, consulting, taxes, unrelated one-time charges, credits, refunds, and prorations do not increase the allowance.
- Free users receive a separately configured trial allowance. The 50% formula does not apply to Free.

The allowance is an inference entitlement. It is not cash, refund value, a separately billed balance, or transferable account credit.

The allowance resets monthly. Unused allowance does not roll over. The authenticated [Bkper AI usage dashboard](https://ai.bkper.app) is authoritative for your exact current allowance.

## Individual and pooled usage

Allowance scope follows the subscription:

- Free and Standard usage is assigned to the individual user.
- Business and Professional usage can be pooled when the subscription has domain-wide scope.
- Everyone sharing a pooled allowance reduces the same monthly total.

A pooled allowance does not make every user's request history visible to everyone. Visibility depends on the viewer's billing role.

## Usage visibility and privacy

The [Bkper AI usage dashboard](https://ai.bkper.app) separates allowance visibility from request attribution:

- Regular users see the shared allowance remaining and their own requests and usage.
- The billing or subscription administrator sees domain-wide usage attributed by user, AI model, and app or source.
- The dashboard does not expose prompts or responses.

Usage value is an estimate based on the published rates above. It shows how much of the included allowance a request consumed; it is not a separate Bkper charge.

## When the limit is reached

Bkper AI blocks new allowance-backed requests once the recorded monthly allowance is exhausted. There are **no automatic paid Bkper AI overages at launch**.

Bkper AI is not a lock-in: where supported, you can connect an external model provider at any time. External subscriptions, API keys, charges, privacy terms, and limits are governed by that provider and do not use the included Bkper AI allowance.

## How Bkper selects models

We build Bkper with the Bkper CLI Agent and use it every day. We test many models through real work and include only those that consistently work well for us within our cost and control constraints. The catalog is a practical, opinionated shortlist—not a directory of every available model.

Bkper prioritizes strong results at controlled cost — the efficient frontier of capability per dollar — rather than pursuing the highest benchmark score at any price. Selection also considers:

- results and reliability in daily agent workflows;
- provider capabilities and tool use;
- observed usage cost;
- model capabilities and controls;
- public benchmarks.

[Explore the live DeepSWE leaderboard](https://deepswe.datacurve.ai/).

DeepSWE measures long-horizon software-engineering work. It is one input into model selection, not a measure of accounting accuracy or a guarantee of performance in Bkper workflows.

## Model references

| Model | Provider | Released |
| --- | --- | --- |
| Gemini 3.5 Flash | [Google](https://deepmind.google/models/gemini/flash/) | 2026-05-19 |
| GPT-5.6 Luna | [OpenAI](https://openai.com/index/gpt-5-6/) | 2026-07-09 |
| GPT-5.6 Terra | [OpenAI](https://openai.com/index/gpt-5-6/) | 2026-07-09 |
| GPT-5.6 Sol | [OpenAI](https://openai.com/index/gpt-5-6/) | 2026-07-09 |
| Grok 4.5 | [xAI](https://x.ai/news/grok-4-5) | 2026-07-08 |

## Sources

Last synchronized: **2026-07-20**

- [Bkper AI provider-native capability catalog](https://ai.bkper.app/v1/models)
- [Models.dev model metadata](https://models.dev/models.json)
- [DeepSWE live leaderboard](https://deepswe.datacurve.ai/)
  

Models.dev metadata is provided under the MIT License. Provider names and logos remain trademarks of their respective owners.

## Next steps

- [Connect a client to Bkper AI](https://bkper.com/docs/ai/bkper-ai-provider.md).
- [Open the Bkper AI usage dashboard](https://ai.bkper.app).
- [Use the preconfigured Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md).

---
source: /docs/ai/openaccountants.md

# OpenAccountants

Use this path when a tax or accounting question needs grounded review. Bkper keeps the financial facts in your Book. [OpenAccountants](https://www.openaccountants.com) publishes source-cited tax rules and offers an accountant network. AI can organize the work, but filing, payment, and compliance decisions still need qualified review.

OpenAccountants describes its model as [open rules, cited sources, human accountability](https://www.openaccountants.com/how-it-works). In Bkper terms: **financial facts → cited rules → professional review**.

## Use it through Bkper

You can use OpenAccountants from Bkper through either AI path:

- **Bkper MCP** — connect [Bkper MCP](https://bkper.com/docs/ai/bkper-mcp-server.md), then ask your assistant to prepare a tax worksheet or find an accountant. The MCP server exposes `get_tax_rules` for public jurisdiction rules and `find_accountants` for referral candidates.
- **Bkper CLI Agent** — run [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md) when you want local files, scripts, or repeatable worksheets. The built-in Bkper context tells the agent how to combine Bkper balance reports with live OpenAccountants rule and referral endpoints.

In both paths, Bkper supplies the Book facts from balances, reports, and supporting records. OpenAccountants supplies public jurisdiction context or referral metadata. The OpenAccountants lookup should send only the jurisdiction, such as `BR`, `GB`, `US`, `US-CA`, or `CA-ON`, unless you explicitly approve sharing more context.

Ask for the business outcome, not the implementation. You do not need to name OpenAccountants, MCP tools, endpoints, balances, or reports.

The assistant should clarify the jurisdiction, period, scope, and review goal. It should use Bkper balances and reports as the primary Book facts, drill into transactions only when support or reconciliation is needed, and use OpenAccountants only for public rules or referral metadata unless you approve sharing more.

## How it works

1. **Ask the question.** Name the jurisdiction, period, and outcome.
2. **Prepare facts from Bkper.** Use balances and reports from the relevant Book as the primary tax facts. Use transaction-level detail only for support, exceptions, review, or reconciliation.
3. **Ground the rule research.** Use OpenAccountants tax-rule resources for the jurisdiction and keep citations with the worksheet.
4. **Review before action.** If it affects filing, payment, compliance, or a material decision, send the worksheet to a qualified accountant.

## Example

For a sales-tax question:

1. Start from Bkper balances and reports for the tax-relevant Accounts or Groups in the period.
2. Drill into transactions only to explain unusual balances, review exceptions, or provide supporting detail.
3. List assumptions and exceptions.
4. Use OpenAccountants for cited jurisdiction rules.
5. Send the worksheet and source references to a qualified accountant before filing or payment.

## Roles

- **Bkper** keeps the source-of-truth records: transactions, balances, Accounts, Groups, properties, files, review states, and Events.
- **OpenAccountants** provides maintained, source-cited tax-rule material, a [Tax Library](https://www.openaccountants.com/skills), and an [accountant network](https://www.openaccountants.com/network).
- **AI assistants** can draft worksheets and issue lists, but should share only the jurisdiction with OpenAccountants unless you approve more context.

Bkper does not automatically send private book data, transaction details, files, tax IDs, or personal details to OpenAccountants.

## What to prepare

Before handoff, prepare the smallest useful package:

- jurisdiction, Book or entity, and period;
- relevant balances and reports;
- transaction-level detail only when needed for support, exceptions, review, or reconciliation;
- assumptions, open questions, and disputed items;
- draft, unchecked, unusual, or missing-support items;
- supporting files only when you intentionally choose to share them.

## Limits and attribution

OpenAccountants provides general tax and accounting reference material and AI-assisted working-paper tools. Bkper provides source-of-truth financial records. Neither replaces qualified professional judgment. Treat outputs as drafts until reviewed.

Tax-rule resources and accountant-network referrals are provided by [OpenAccountants](https://www.openaccountants.com). Bkper does not endorse, employ, or independently vet specific accountants.

## Related pages

- [AI Fundamentals for Finance](https://bkper.com/docs/ai/fundamentals.md) — why raw LLM output is not final for numbers.
- [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md) — choose how an AI assistant should use Bkper.