Liking cljdoc? Tell your friends :D

ai

Framework-aware AI tooling for Wagoe applications. Unlike a generic assistant, it knows Wagoe’s conventions: FC/IS, ports, kebab↔snake naming, Malli schemas, and HoneySQL syntax.

Features

NL Scaffolding - parse a natural language description into a scaffolding spec
Error Explainer (experimental) - explain a stack trace with Wagoe-specific context
Test Generator (experimental) - generate a complete test namespace for a source file
SQL Copilot (experimental) - translate a description into HoneySQL format
Documentation Wizard - generate AGENTS.md, OpenAPI YAML, or README

The test generator shows the model the public API and the Malli schemas of every namespace the source requires, plus its module’s schema namespace. Before writing, it lints the answer and checks each fixture tagged ^{:schema s} against s, reading the file without evaluating it; a fixture whose value is not literal data is reported as not checked. A failing answer goes back to the model once; if it still fails, nothing is written unless you pass --force.

--run also loads the answer and runs its tests, in a separate JVM that keeps only PATH, HOME, LANG and WAG_ENV from your environment, and every test must pass. This runs code the model wrote before anyone has read it. The child is not a sandbox: it can read your files and reach the network.

The error explainer, test generator and SQL copilot are experimental for 1.0: their answers can be confidently wrong, so review them before use. bb ai explain prints the error’s own WGE code and Fix: text before the model’s summary.

CLI commands

# NL scaffolding (interactive confirm)
bb scaffold ai "product module with name, price, stock"

# NL scaffolding (non-interactive)
bb scaffold ai "product module with name, price, stock" --yes

# Explain a stack trace (experimental)
bb ai explain --file stacktrace.txt

# Generate test namespace (experimental)
bb ai gen-tests libs/user/src/wagoe/user/core/validation.clj

# Generate HoneySQL from description (experimental)
bb ai sql "find active users with orders in the last 7 days"

# Generate documentation
bb ai docs --module libs/user --type agents
bb ai docs --module libs/user --type openapi
bb ai docs --module libs/user --type readme

bb ai sql shows the model the tables and columns your migrations create (migrations/, resources/migrations/ and the libraries' own), tables your description names first. Tables a library creates in code are listed by name only. An answer that names a table or column outside that schema is sent back once and then refused, and with no tables found it refuses rather than guess. The query is never run.

Prerequisites per provider

The config a provider needs is written by bb setup --ai-provider <name>; what the provider needs outside the config is this table. The project boots without any of it — the first AI call is what fails.

Provider Before the first call answers

Provider	Before the first call answers
`:ollama`	Install Ollama (https://ollama.com/download), pull the configured model (`ollama pull qwen2.5-coder:7b` for the default), and keep it running — the service calls `localhost:11434`. No API key, no data leaves the machine.
`:anthropic`	Create a key at https://console.anthropic.com/settings/keys and export `ANTHROPIC_API_KEY` (or put it in `.env` and load it with `set -a; source .env; set +a` — plain `source` does not export, so the JVM would not see it).
`:openai`	Create a key at https://platform.openai.com/api-keys and export `OPENAI_API_KEY`.
`:replicate`	Create a token at https://replicate.com/account/api-tokens and export `REPLICATE_API_TOKEN`.

:ollama

Install Ollama (https://ollama.com/download), pull the configured model (ollama pull qwen2.5-coder:7b for the default), and keep it running — the service calls localhost:11434. No API key, no data leaves the machine.

:anthropic

Create a key at https://console.anthropic.com/settings/keys and export ANTHROPIC_API_KEY (or put it in .env and load it with set -a; source .env; set +a — plain source does not export, so the JVM would not see it).

:openai

Create a key at https://platform.openai.com/api-keys and export OPENAI_API_KEY.

:replicate

Create a token at https://replicate.com/account/api-tokens and export REPLICATE_API_TOKEN.

bb doctor --ci names a missing key for the hosted providers. It does not probe whether Ollama is running.

Provider strategy

:provider is required; the service refuses to start without one. Ollama keeps data on the machine. A :fallback provider answers when the primary fails:

;; Offline-first (Ollama, no API key)
:wagoe/ai-service
{:provider :ollama
 :model    "qwen2.5-coder:7b"
 :base-url "http://localhost:11434"}

;; Anthropic
:wagoe/ai-service
{:provider :anthropic
 :model    "claude-haiku-4-5-20251001"
 :api-key  #env ANTHROPIC_API_KEY}

;; Ollama primary + Anthropic fallback
:wagoe/ai-service
{:provider  :ollama
 :model     "qwen2.5-coder:7b"
 :base-url  "http://localhost:11434"
 :fallback  {:provider :anthropic
              :api-key  #env ANTHROPIC_API_KEY}}

The bb ai commands use :wagoe/ai-service from the active config when it names a provider other than :no-op. Otherwise the first variable set picks: ANTHROPIC_API_KEY → OPENAI_BASE_URL (an OpenAI-compatible endpoint) → OPENAI_API_KEY → REPLICATE_API_TOKEN → OLLAMA_URL, then Ollama on localhost:11434. AI_MODEL overrides the model.

Key namespaces

Namespace Layer Responsibility

Namespace	Layer	Responsibility
`wagoe.ai.ports`	shared	`IAIProvider` protocol: `complete`, `complete-json`, `provider-name`
`wagoe.ai.core.prompts`	core	Pure prompt builders for all 5 features
`wagoe.ai.core.context`	core	Pure context extractors (module names, stack traces, function signatures)
`wagoe.ai.core.parsing`	core	Pure response parsers (JSON, module spec, SQL, test code)
`wagoe.ai.shell.providers.ollama`	shell	Ollama HTTP adapter
`wagoe.ai.shell.providers.anthropic`	shell	Anthropic API adapter
`wagoe.ai.shell.providers.openai`	shell	OpenAI API adapter
`wagoe.ai.shell.providers.replicate`	shell	Replicate API adapter
`wagoe.ai.shell.providers.no-op`	shell	Test stub
`wagoe.ai.shell.service`	shell	Public API: `scaffold-from-description`, `explain-error`, `generate-tests`, `sql-from-description`, `generate-docs`
`wagoe.ai.shell.repl`	shell	REPL helpers: `explain`, `sql`, `gen-tests`

wagoe.ai.ports

shared

IAIProvider protocol: complete, complete-json, provider-name

wagoe.ai.core.prompts

core

Pure prompt builders for all 5 features

wagoe.ai.core.context

core

Pure context extractors (module names, stack traces, function signatures)

wagoe.ai.core.parsing

core

Pure response parsers (JSON, module spec, SQL, test code)

wagoe.ai.shell.providers.ollama

shell

Ollama HTTP adapter

wagoe.ai.shell.providers.anthropic

shell

Anthropic API adapter

wagoe.ai.shell.providers.openai

shell

OpenAI API adapter

wagoe.ai.shell.providers.replicate

shell

Replicate API adapter

wagoe.ai.shell.providers.no-op

shell

Test stub

wagoe.ai.shell.service

shell

Public API: scaffold-from-description, explain-error, generate-tests, sql-from-description, generate-docs

wagoe.ai.shell.repl

shell

REPL helpers: explain, sql, gen-tests

REPL usage

(require '[wagoe.ai.shell.repl :as ai])

;; Bind a service
(ai/set-service! (integrant.repl.state/system :wagoe/ai-service))

;; Use helpers
(ai/explain "ClassNotFoundException: wagoe.user.core.user")
(ai/sql "find all users who logged in today")
(ai/gen-tests "libs/user/src/wagoe/user/core/validation.clj")

Testing

clojure -M:test :ai

❮admin audience❯

Can you improve this documentation? These fine people already did:
thijscreemers & Thijs CreemersEdit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts

`Ctrl`+`k`	Jump to recent docs
`←`	Move to previous article
`→`	Move to next article
`Ctrl`+`/`	Jump to the search field

Raise an issue Browse cljdoc source Chat on Slack

× close