# 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

Choose the task that best matches what you want to accomplish:

    - [Process documents](http://preview.bkper.com/docs/ai/bkper-agent.md): Turn receipts, invoices, statements, emails, and attachments into draft transactions.
    - [Work with an AI assistant](http://preview.bkper.com/docs/ai/cli-vs-mcp.md): Choose conversational Bkper access or a local workflow with files, scripts, and tests.
    - [Build with AI](http://preview.bkper.com/docs/ai/coding-agents.md): Create Bkper reports, scripts, apps, and integrations with a coding agent.
    - [Understand AI safely](http://preview.bkper.com/docs/ai/fundamentals.md): Learn how AI behaves and why financial outputs need deterministic checks and human review.

### More AI topics

- [Bkper CLI Agent](http://preview.bkper.com/docs/ai/bkper-cli-agent.md) — work with local files, commands, scripts, and Bkper context.
- [Bkper MCP](http://preview.bkper.com/docs/ai/bkper-mcp-server.md) — connect a hosted assistant through conversational tool calls.
- [Models and Usage](http://preview.bkper.com/docs/ai/models.md) — compare models, capabilities, rates, and allowances.
- [Bkper AI Provider](http://preview.bkper.com/docs/ai/bkper-ai-provider.md) — connect a compatible inference client using Bkper authentication.
- [Docs for AI](http://preview.bkper.com/docs/ai/docs-for-ai.md) — give Bkper documentation and API references to an assistant.
- [CLI Agent Security](http://preview.bkper.com/docs/ai/cli-agent-security.md) — protect credentials and scope local agent permissions.
- [OpenAccountants](http://preview.bkper.com/docs/ai/openaccountants.md) — prepare tax or accounting work for 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](http://preview.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](http://preview.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](http://preview.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 Accounting](http://preview.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](http://preview.bkper.com/docs/guides/using-bkper/hashtags.md). For advanced prompt and parser properties, use the [Bkper Agent app reference](http://preview.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](http://preview.bkper.com/apps/bookbot.md) — current capabilities, configuration properties, and supported file types.
- [Record Transactions by Email](http://preview.bkper.com/docs/guides/using-bkper/record-by-email.md) — forward invoices, receipts, and statements to a Book.
- [Attachments](http://preview.bkper.com/docs/guides/using-bkper/attachments.md) — keep documents with the transactions they support.
- [Hashtags](http://preview.bkper.com/docs/guides/using-bkper/hashtags.md) — use tags consistently so the Agent can match patterns.
- [AI Fundamentals for Accounting](http://preview.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](http://preview.bkper.com/docs/ai/models.md) for allowance scope, current rates, and model 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`                         |

The live `GET /v1/models` response is authoritative for the current default model, available IDs, capabilities, limits, and effective usage rates. Generic integrations can start with `default_model`. Capability-sensitive integrations should inspect the selected entry in `data` instead of relying on model IDs or capabilities shown in examples.

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.

## Model IDs

Bkper AI publishes stable, versionless, slash-free family IDs such as `gpt-luna`, `grok`, and `gemini-flash`.

A family ID remains stable when Bkper upgrades its concrete provider revision. Provider revisions are an internal serving detail rather than a public version-pinning contract.

Older versioned and publisher-prefixed IDs still work as compatibility aliases, but they resolve to the current model family rather than pinning an older revision. Catalogs, responses, and usage reports return the canonical family ID.

## 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](http://preview.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": "gpt-luna",
    "input": "Reply with exactly: connected",
    "store": false
  }'
```

The response is an Open Responses resource. Its `model` contains the canonical 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": "grok",
    "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.

## Privacy, retention, and caching

**Zero data retention where available. Minimum retention everywhere.** Bkper disables provider application storage on every request and keeps prompt and response content out of usage logs.

Bkper applies these boundaries across the inference path:

- omitted `store` becomes `false`, and `store: true` is rejected before provider dispatch;
- Bkper usage records contain attribution, status, token, cache, and cost metadata—not prompt or response content;
- detailed Bkper usage events are retained for 180 days, while daily aggregate usage remains available for allowance enforcement and reporting;
- Cloudflare AI Gateway payload logging is disabled, while content-free request metadata remains available for observability;
- exact, non-streaming structured JSON requests and responses may be cached by Cloudflare for up to 24 hours; other response requests bypass this cache;
- provider-native prompt caches may hold content temporarily under the selected provider's caching policy.

Provider retention controls differ:

| Provider                   | Bkper configuration                                                                                                | Provider retention boundary                                                                                                                                                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **xAI**                    | `store: false`; Zero Data Retention is active for Bkper's xAI team                                                 | Prompt and response retention is disabled under the enabled Zero Data Retention control.                                                                                                                                                                           |
| **OpenAI**                 | `store: false`; Bkper organization API-call logging is disabled                                                    | API data is not used for training by default. Customer content may remain in abuse-monitoring logs for up to 30 days because Bkper does not currently have OpenAI Zero Data Retention.                                                                             |
| **Google Gemini paid API** | `store: false`; Bkper avoids Search and Maps grounding, the File API, and explicit context caching                 | Paid API content is not used for training. Content may be retained for limited abuse monitoring because Bkper's AI Studio project does not currently have approved Zero Data Retention. Gemini may also use project-isolated in-memory caching for up to 24 hours. |
| **Fireworks AI**           | `store: false`; Zero Data Retention is active by default; used as the current serving route for open-weight models | Fireworks does not log or persist prompt or generation data for open models without explicit opt-in. Prompt caching may retain data in volatile memory for several minutes. `store: false` prevents Response API conversation storage.                             |

Public model identity is independent of serving infrastructure. The catalog's `owned_by` field identifies the model creator. Bkper may change a serving route or upgrade the concrete provider revision without changing the canonical model family ID.

Caching is separate from response state and logging. A cache can temporarily retain an exact request and response without creating a retrievable conversation or including that content in usage logs. `prompt_cache_key` may be retained as usage metadata and displayed in the usage dashboard, so use an opaque identifier rather than customer or financial information.

Provider policies and Bkper configurations can change. Review these primary references for the current boundaries:

- [Google Gemini API zero data retention](https://ai.google.dev/gemini-api/docs/zdr)
- [OpenAI platform data controls](https://developers.openai.com/api/docs/guides/your-data)
- [Fireworks AI zero data retention](https://docs.fireworks.ai/guides/security_compliance/data_handling)
- [Cloudflare AI Gateway caching](https://developers.cloudflare.com/ai-gateway/features/caching/)
- [Cloudflare AI Gateway logging](https://developers.cloudflare.com/ai-gateway/observability/logging/)

## 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

- [Browse the generated AI API reference](http://preview.bkper.com/docs/api/ai.md).
- [Download the canonical OpenAPI specification](https://ai.bkper.app/openapi.json).
- [Compare models, capabilities, rates, and allowance rules](http://preview.bkper.com/docs/ai/models.md).
- [Use the preconfigured Bkper CLI Agent](http://preview.bkper.com/docs/ai/bkper-cli-agent.md).
- [Review Bkper CLI Agent security](http://preview.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. For installation, authentication, and the command reference, see [Bkper CLI](http://preview.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](http://preview.bkper.com/docs/ai/bkper-mcp-server.md). For the full decision guide, see [CLI vs MCP](http://preview.bkper.com/docs/ai/cli-vs-mcp.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](http://preview.bkper.com/docs/ai/bkper-ai-provider.md) for the client-agnostic inference interface and [Models and Usage](http://preview.bkper.com/docs/ai/models.md) for the current portfolio, model 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`.

## 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](http://preview.bkper.com/apps/bkper-cli.md).

[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

Bkper AI is already configured, so no separate model-provider setup is required. The CLI loads the current catalog and default from `GET /v1/models`; an explicitly saved model remains selected while it is available. See [Models and Usage](http://preview.bkper.com/docs/ai/models.md) for the current portfolio, capabilities, rates, and allowance rules.

To use an external subscription or API key instead, type `/connect` and choose a provider. External costs, limits, and privacy terms are governed by that provider.

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

## 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](http://preview.bkper.com/docs/ai/cli-agent-security.md).

## Reference

Use [Bkper CLI](http://preview.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](http://preview.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](http://preview.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](http://preview.bkper.com/docs/ai/cli-vs-mcp.md).

## Related pages

- [Bkper MCP](http://preview.bkper.com/apps/bkper-mcp.md) — canonical setup and reference.
- [CLI vs MCP](http://preview.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](http://preview.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 paths for AI assistants: **MCP** for conversational connector access and **CLI local tools** for work involving a terminal, files, scripts, or tests.

If your assistant can run terminal commands, prefer CLI local tools. Use MCP when terminal access is unavailable or when conversational access is the goal.

## 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.

## Related pages

- [AI Fundamentals for Accounting](http://preview.bkper.com/docs/ai/fundamentals.md)
- [Docs for AI](http://preview.bkper.com/docs/ai/docs-for-ai.md)
- [Bkper CLI Agent Security](http://preview.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](http://preview.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](http://preview.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](http://preview.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](http://preview.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.

## Use Bkper AI as a model provider

Model-provider configuration and Bkper project context are separate concerns. If an external coding agent supports Open Responses with a custom base URL, it can use Bkper AI for inference with Bkper authentication and the included AI allowance. The agent still needs the Bkper context described below to understand Books, resource movements, SDKs, and safe operations.

See [Bkper AI Provider](http://preview.bkper.com/docs/ai/bkper-ai-provider.md) for the endpoint, authentication, live model discovery, supported profile, and privacy boundaries.

## 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](http://preview.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

- [Shared App Source](http://preview.bkper.com/docs/build/apps/shared-app-source.md) — let teammates and coding agents continue from one private app codebase
- [Your First App](http://preview.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](http://preview.bkper.com/docs/build/scripts/cli-pipelines.md) — automate data workflows with CLI pipes
- [Apps Overview](http://preview.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`](http://preview.bkper.com/llms.txt) — all site content
- [`/docs/llms.txt`](http://preview.bkper.com/docs/llms.txt) — all docs
- [`/docs/ai/llms.txt`](http://preview.bkper.com/docs/ai/llms.txt) — AI docs
- [`/docs/guides/llms.txt`](http://preview.bkper.com/docs/guides/llms.txt) — user-facing guides
- [`/docs/build/llms.txt`](http://preview.bkper.com/docs/build/llms.txt) — developer docs
- [`/docs/api/llms.txt`](http://preview.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`](http://preview.bkper.com/llms-full.txt) — all site content
- [`/docs/llms-full.txt`](http://preview.bkper.com/docs/llms-full.txt) — all docs
- [`/docs/ai/llms-full.txt`](http://preview.bkper.com/docs/ai/llms-full.txt) — all AI docs
- [`/docs/build/apps/llms-full.txt`](http://preview.bkper.com/docs/build/apps/llms-full.txt) — all app docs
- [`/docs/build/scripts/llms-full.txt`](http://preview.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`](http://preview.bkper.com/docs/api/rest.md) — accounting endpoints, parameters, and data models
- [`/docs/api/ai.md`](http://preview.bkper.com/docs/api/ai.md) — model discovery, response operations, streaming events, and schemas
- [`/docs/api/bkper-js.md`](http://preview.bkper.com/docs/api/bkper-js.md) — bkper-js README + TypeScript definitions
- [`/docs/api/bkper-gs.md`](http://preview.bkper.com/docs/api/bkper-gs.md) — bkper-gs README + TypeScript definitions
- [`/docs/api/bkper-api-types.md`](http://preview.bkper.com/docs/api/bkper-api-types.md) — shared TypeScript type definitions
- [`/docs/api/bkper-web-auth.md`](http://preview.bkper.com/docs/api/bkper-web-auth.md) — OAuth browser SDK

The canonical machine-readable AI contract is available at [`https://ai.bkper.app/openapi.json`](https://ai.bkper.app/openapi.json).

Compiled Markdown vs raw source:

| Library         | Raw tokens | `.md` tokens | Reduction |
| --------------- | ---------: | -----------: | --------: |
| REST API        |       ~38K |          ~9K |        4× |
| AI API          |       ~19K |         ~28K |         — |
| 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× |

The AI API Markdown is larger than its minified JSON source because it preserves every OpenAPI 3.1 contract object while adding navigable headings.

## 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](http://preview.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](http://preview.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 Accounting

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](http://preview.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](http://preview.bkper.com/docs/ai/docs-for-ai.md) — get Bkper docs and context into AI tools.
- [CLI vs MCP](http://preview.bkper.com/docs/ai/cli-vs-mcp.md) — choose how an AI assistant should use Bkper.
- [Coding Agents](http://preview.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](http://preview.bkper.com/docs/ai/bkper-ai-provider.md).

## 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.

Public IDs identify stable Bkper model families. Bkper can upgrade the concrete provider revision behind a family without changing its public ID, saved client configuration, or usage-report identity.

| Model | Best for | Capabilities |
| --- | --- | --- |
| **DeepSeek Flash** `deepseek-flash` | Fast, economical reasoning, coding, and long-context work. | Reasoning efforts: `high`, `max`<br />Maximum context: 300k tokens<br />Maximum output: 64k tokens |
| **Gemini Flash** `gemini-flash` | Fast multimodal reasoning and tool use with balanced usage rates. | Reasoning efforts: `minimal`, `low`, `medium`<br />Maximum context: 1,048,576 tokens<br />Maximum output: 65,536 tokens |
| **GPT Luna** `gpt-luna` | Cost-efficient GPT model for fast, high-volume workloads. | Reasoning efforts: `high`, `xhigh`, `max`<br />Maximum context: 272k tokens<br />Maximum output: 64k tokens |
| **GPT Terra** `gpt-terra` | Balanced GPT model for capable, cost-efficient everyday work. | Reasoning efforts: `high`<br />Maximum context: 200k tokens<br />Maximum output: 32k tokens |
| **Grok** `grok` | General-purpose model for chat, coding, and agentic tool use. | Reasoning efforts: `low`, `medium`, `high`<br />Maximum context: 200k tokens<br />Maximum output: 32k tokens |

The table shows each model's maximum supported capabilities through Bkper AI. Bkper CLI loads the current context window, output limit, and reasoning profile for every model from the live catalog. Compatible clients can request lower output budgets and any listed reasoning effort.

## How usage works

Bkper AI is included with eligible plans and controlled through one monthly allowance:

- The Bkper CLI Agent connects with your Bkper login; no separate provider setup is required.
- Model usage reduces the included allowance and is not billed separately.
- New requests stop when the recorded allowance is exhausted; there are no automatic paid overages.
- External providers remain available where supported and do not consume the Bkper AI allowance.

Requests already in flight may settle after the allowance check, so recorded usage can slightly exceed the limit under concurrency. Bkper does not bill that difference as an AI overage.

## 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 |
| --- | ---: | ---: | ---: | ---: |
| DeepSeek Flash | $0.18 | $0.035 | $0.00 | $0.35 |
| Gemini Flash | $1.90 | $0.19 | $0.00 | $9.40 |
| GPT Luna | $0.25 | $0.025 | $0.31 | $1.50 |
| GPT Terra | $2.50 | $0.25 | $3.10 | $15.00 |
| Grok | $2.50 | $0.38 | $0.00 | $7.50 |

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, the monthly AI allowance equals the normalized monthly software subscription value:

- Monthly plans use the recurring monthly software subscription value.
- Annual plans divide the recurring annual software subscription value by 12.

Only recurring software subscription value counts. Professional services, implementation, consulting, taxes, one-time charges, credits, refunds, and prorations do not increase the allowance. Free users receive a separately configured trial allowance.

The allowance resets monthly and unused value does not roll over. It is an inference entitlement—not cash, refund value, or transferable credit. The authenticated [Bkper AI usage dashboard](https://ai.bkper.app) shows 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;
- effective model 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 creators

| Model | Creator |
| --- | --- |
| DeepSeek Flash | [DeepSeek](https://www.deepseek.com/) |
| Gemini Flash | [Google](https://ai.google.dev/gemini-api/docs/models) |
| GPT Luna | [OpenAI](https://openai.com/api/) |
| GPT Terra | [OpenAI](https://openai.com/api/) |
| Grok | [xAI](https://x.ai/api) |

## Sources

Last synchronized: **2026-08-21**

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

Models.dev provider assets are provided under the MIT License. Model creator names and logos remain trademarks of their respective owners.

## Next steps

- [Browse the generated AI API reference](http://preview.bkper.com/docs/api/ai.md).
- [Connect a client to Bkper AI](http://preview.bkper.com/docs/ai/bkper-ai-provider.md).
- [Open the Bkper AI usage dashboard](https://ai.bkper.app).
- [Use the preconfigured Bkper CLI Agent](http://preview.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](http://preview.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](http://preview.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 Accounting](http://preview.bkper.com/docs/ai/fundamentals.md) — why raw LLM output is not final for numbers.
- [CLI vs MCP](http://preview.bkper.com/docs/ai/cli-vs-mcp.md) — choose how an AI assistant should use Bkper.