Skip to main content
Kapso routes every model call one of two ways. Completions — research, reranking, graph navigation, repo memory, commit messages, benchmark utilities — run as read-only coding-agent CLI sessions, configured by the platform’s inference block. Embeddings are the one call that still goes to a provider SDK directly, through LLMBackend’s single embedding route.

​
Inference roles

The inference block names a default CLI and model, then overrides per role:
A role inherits every default key it does not override, so repo_memory: {} is the default spec verbatim. Inference sessions never write (sandbox: read-only), and a failed or empty session raises rather than degrading silently.
The packaged config’s inference block is the base layer; an inference: block in the file you pass with --config / config_path deep-merges over it, so overriding one key never forfeits the rest. Coding-agent models — such as coding_agent.model — stay explicit in your mode config because their provider and authentication are part of that agent’s configuration.
Kapso.research() runs on the research role, whose web_search: true carries the CLI’s live-web tool; depth="light" requests medium search context and depth="deep" high.

​
The embedding route

LLMBackend keeps exactly one semantic role:
Experiment-store semantic search and knowledge search resolve their embedding model through it. Unknown role keys and empty model values are configuration errors, caught when the backend is created — before an experiment starts.

​
Retry semantics

Provider-backed calls retry only failures that are usually safe to repeat:
  • connection and timeout failures;
  • HTTP 408, 409, 425, and 429 responses;
  • HTTP 500, 502, 503, and 504 responses;
  • provider exceptions classified as rate limits, timeouts, connection errors, service unavailability, or internal server errors.
Authentication, permission, bad-request, context-window, invalid configuration, and programming errors are raised immediately. Kapso does not sleep and retry a bad API key or a malformed call. The retry budget comes from the mode’s retry block; max_attempts includes the initial call:
The delay before retry number n is capped exponential backoff:
With jitter: true, Kapso uses full jitter — a random delay between zero and the calculated cap — to avoid synchronized retry storms. With jitter: false, the calculated delay is used exactly. When transient failures exhaust all attempts, LLMRetryError reports the operation, resolved model, and attempt count while preserving the provider exception as its cause. defaults.retry.request_timeout_seconds additionally hands the provider client a hard per-request wall clock, so a connection the server abandons mid-stream cannot block the calling thread forever.

​
Standalone use

ModelRouter, RetryPolicy, LLMRetryError, and is_transient_llm_error are public from kapso.core for components that need to inspect or compose the shared behavior.

Configuration

The inference block

Coding agents

Agents versus inference roles
Related pages: Configuration · Coding agents · Orchestrator Kapso is an open-source framework by Leeroo that builds software toward measurable goals through experiment campaigns. Source code: github.com/Leeroo-AI/kapso · Install: pip install leeroo-kapso · Every page as plain text: llms.txt.