Kapso deployment architecture: the strategy plugin model

Deployment is a plugin system. A selector picks a target, an adapter rewrites the solution for it, and a runner executes it — and each target is a self-contained directory that can be added without touching core code.

Component	Module	Role
DeploymentFactory	`factory.py`	Orchestrates selection, adaptation, and runner creation
SelectorAgent	`selector/agent.py`	LLM-based strategy selection
AdapterAgent	`adapter/agent.py`	Code transformation for target platform
StrategyRegistry	`strategies/base.py`	Auto-discovery of strategy plugins
Runner	`strategies/*/runner.py`	Infrastructure-specific execution
DeployedSoftware	`software.py`	Unified wrapper for user interaction

Module breakdown

Directory structure

src/kapso/deployment/
├── __init__.py              # Public exports
├── base.py                  # Data models and abstractions
├── factory.py               # DeploymentFactory orchestration
├── software.py              # DeployedSoftware unified wrapper
├── selector/
│   ├── agent.py             # SelectorAgent (strategy selection)
│   ├── selection_prompt.md  # LLM prompt template
│   └── correction_prompt.md # Error correction prompt
├── adapter/
│   ├── agent.py             # AdapterAgent (code transformation)
│   ├── adaptation_prompt.txt # LLM prompt template
│   └── validator.py         # Adaptation validation
└── strategies/
    ├── base.py              # Runner ABC, StrategyRegistry
    ├── README.md            # Strategy development guide
    ├── local/               # Local strategy plugin
    ├── docker/              # Docker strategy plugin
    ├── modal/               # Modal strategy plugin
    ├── bentoml/             # BentoML strategy plugin
    └── langgraph/           # LangGraph strategy plugin

Core components

DeploymentFactory (`factory.py`)

The orchestrator that manages the full deployment pipeline. Responsibilities:

Coordinate selection, adaptation, and runner creation
Handle strategy validation
Create unified Software instances

Flow:

# Phase 1: Selection
if strategy == DeployStrategy.AUTO:
    setting = cls._select_strategy(config, strategies)
else:
    setting = cls._create_setting(strategy)

# Phase 2: Adaptation  
adaptation = cls._adapt_repo(config, setting, strategies)

# Phase 3: Runner creation
runner = cls._create_runner(config, setting, adaptation)

# Phase 4: Wrap in unified interface
return DeployedSoftware(config=config, runner=runner, info=info)

SelectorAgent (`selector/agent.py`)

LLM-based strategy selection that analyzes code and chooses the optimal deployment target. Responsibilities:

Gather selector instructions from all strategies
Query coding agent to analyze repository
Return DeploymentSetting with chosen strategy

Method	Input	Output
`select()`	`SolutionResult`, optional `allowed_strategies`	`DeploymentSetting`
`explain()`	`SolutionResult`	`str` human-readable explanation

AdapterAgent (`adapter/agent.py`)

Code transformation and deployment using coding agents. Responsibilities:

Create adapted workspace (copy of original)
Load adapter instructions for target strategy
Run coding agent to transform code
Extract endpoint URL and run interface from output

Method	Input	Output
`adapt()`	`SolutionResult`, `DeploymentSetting`	`AdaptationResult`

Key Output Extraction: The adapter looks for special XML tags in the coding agent’s output:

<run_interface>{"type": "function", "module": "main", "callable": "predict"}</run_interface>
<endpoint_url>https://my-app.modal.run</endpoint_url>

StrategyRegistry (`strategies/base.py`)

Auto-discovery system for deployment strategies. Responsibilities:

Scan strategies/ directory on startup
Load configuration and instructions for each strategy
Provide access to strategy metadata and runner classes

Method	Input	Output
`list_strategies()`	optional `allowed: List[str]`	`List[str]`
`get_strategy()`	`name: str`	`DeployStrategyConfig`
`get_runner_class()`	`name: str`	`type` (Runner subclass)

Runner (abstract base class)

Infrastructure-specific execution handler.

class Runner(ABC):
    @abstractmethod
    def run(self, inputs: Union[Dict, str, bytes]) -> Any:
        """Execute with inputs and return result."""

    @abstractmethod
    def start(self) -> None:
        """Start or restart a stopped runner back to ready state."""

    @abstractmethod
    def stop(self) -> None:
        """Stop and cleanup resources."""

    @abstractmethod
    def is_healthy(self) -> bool:
        """Check if runner is healthy and ready."""

Runner	Strategy	Execution Method
`LocalRunner`	local	Python `importlib` + function call
`DockerRunner`	docker	HTTP requests to container
`ModalRunner`	modal	`modal.Function.remote()`
`BentoMLRunner`	bentoml	HTTP to BentoCloud/local
`LangGraphRunner`	langgraph	LangGraph Platform API

DeployedSoftware (`software.py`)

Unified wrapper that users interact with.

class DeployedSoftware(Software):
    def run(self, inputs) -> Dict[str, Any]:
        """Execute and return normalized response."""
        
    def stop(self) -> None:
        """Stop the software and cleanup."""
        
    def logs(self) -> str:
        """Get execution logs."""
        
    def is_healthy(self) -> bool:
        """Check if software is running."""

Data models

The dataclasses that travel between these components — DeployConfig, DeploymentSetting, AdaptationResult, DeploymentInfo — are listed field-by-field in the API reference.

How are strategies discovered?

Each strategy is a self-contained directory:

strategies/{name}/
├── config.yaml               # Strategy configuration
├── selector_instruction.txt  # When to use this strategy
├── adapter_instruction.txt   # How to adapt code
├── runner.py                 # Runtime execution class
└── __init__.py               # Exports

config.yaml structure

name: modal
provider: modal
interface: function

runner_class: ModalRunner

default_resources:
  gpu: T4
  memory: 16Gi

run_interface:
  type: modal
  function_name: predict

How strategies are discovered

On first use, StrategyRegistry scans the strategies/ directory
Each subdirectory with both instruction files is registered
Runner classes are lazy-loaded from runner.py when needed

Adding a new strategy is adding a directory - no code changes required in the core system.

Strategies Reference

Detailed guide to each deployment strategy

Adding New Strategies

Step-by-step guide to add your own deployment targets

Related pages: Strategies Reference · Adding New Strategies · Deployment 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.

Getting started

Evolve system

Knowledge graph

Trajectory learning

Research

Deployment

Benchmarks

Kapso deployment architecture: the strategy plugin model

Module breakdown

Directory structure

Core components

DeploymentFactory (`factory.py`)

SelectorAgent (`selector/agent.py`)

AdapterAgent (`adapter/agent.py`)

StrategyRegistry (`strategies/base.py`)

Runner (abstract base class)

DeployedSoftware (`software.py`)

Data models

How are strategies discovered?

config.yaml structure

How strategies are discovered

Strategies Reference

Adding New Strategies

​Module breakdown

​Directory structure

​Core components

​DeploymentFactory (factory.py)

​SelectorAgent (selector/agent.py)

​AdapterAgent (adapter/agent.py)

​StrategyRegistry (strategies/base.py)

​Runner (abstract base class)

​DeployedSoftware (software.py)

​Data models

​How are strategies discovered?

​config.yaml structure

​How strategies are discovered

​Related

Strategies Reference

Adding New Strategies

Module breakdown

Directory structure

Core components

DeploymentFactory (`factory.py`)

SelectorAgent (`selector/agent.py`)

AdapterAgent (`adapter/agent.py`)

StrategyRegistry (`strategies/base.py`)

Runner (abstract base class)

DeployedSoftware (`software.py`)

Data models

How are strategies discovered?

config.yaml structure

How strategies are discovered

Related