An AI is optional help with a person in charge. Sapling ships no model and no key. You connect the AI you already use, and only the helpers marked "AI" use it.
Providers#
The setting sapling.ai.provider chooses one:
| Provider | How it runs |
|---|---|
claude-code, codex, gemini | the command-line tool you have installed, with your own login. Each runs in its non-interactive, read-only mode, with no tools, no write access and no session kept. Gemini is not yet tested. |
openai-compatible | an HTTP address you name (sapling.ai.baseUrl): a hosted API, a company gateway, or a local model server such as Ollama or LM Studio. The key comes from an environment variable whose name you give in sapling.ai.apiKeyEnv. |
command | a command of your own: the instructions and the request arrive on its standard input, the answer leaves on its standard output. Your IT team can provide it. |
none | no AI. See Without AI. |
Sapling never reads, prints or stores a key in its settings.
What the AI does#
- Ask AI on a block or a paragraph: it proposes a change in its place in the page. Accept, Decline (with an optional reason) or Improve... with your words.
- The decision interview: it recommends an answer with its reason and alternatives; you decide.
- Chat: a question is answered briefly, and the protocol sentences shown under the answer are quotes that the compiler found word for word in the protocol. An invented quote is dropped.
- Tasks: answer the review findings, draft a section from the protocol, complete an estimand or a table, check consistency. Each makes proposals into the inbox.
Whatever the provider, every answer is compiled in its place first, and the compiler's messages go back to the AI until the block compiles or it gives up. A block that tries to write an approval or decide a decision is refused. An accepted block carries a comment drafted by: agent until you edit or confirm it.
What is sent#
Only to the provider you chose. In a request: your wording, the lines of the plan around the place, a short summary of the plan, the names the plan may use (populations, ADaM variables and their labels), the protocol sentences that fit, items of the knowledge base, counts from public SAPs, the errors and findings of the plan, your house rules, the lines the assistant learned from you, and the blocks you attached with @. No data records of a study go in unless you put them in the plan. The checkable list is on Data and AI.
Prepared ahead#
When you open a plan, and always when you open the interview, the AI is asked for the recommendations of the first open decisions in the background, so they are there when you reach them. This sends requests without a click. Set sapling.ai.prepare to false to stop it; the interview then asks only when you open it. sapling.ai.parallel limits how many requests run at once.
House rules and what it learns#
Sapling: Edit the House Rules opens .sapling/rules.md, plain sentences read in every request. Every accept, decline (with its reason), improvement and interview answer is appended to .sapling/learned.jsonl: the kind of block, a one-line title and what you said, with no data values. The relevant lines go into later requests, so the AI does not propose again what you declined. When you gave the same correction twice, the editor asks once whether to make it a house rule. Sapling: What the Assistant Has Learned opens or clears the file. Both files are plain text on your computer.
Speed#
In the benchmark of tools/copilot_bench.ts, on the first five open decisions of the pilot plan, counting clicks and typing only, with the AI's answers replayed from a recorded run and with no real user, the forms alone took from about 8 minutes (509 seconds) to under 2 minutes with the AI prepared ahead (68 to 87 seconds). That is a model of the work, not a study of people.
The AI cannot#
Approve a plan, answer an open decision, write your name, or write a waiver's reason for you. Those are a person's.