Kapso Evolve architecture: components and how they connect

Kapso is a set of pluggable components wired together by factories around a central orchestration loop. Swapping a coding agent, a search strategy or a knowledge backend is a config change, not a code change.

Component responsibilities

Kapso (main API)

The user-facing entry point that provides the four-pillar API:

class Kapso:
    def research(objective, mode, depth) -> ResearchFindings
    def learn(source) -> LessonResult              # mine one finished campaign
    def learn_knowledge(*sources, wiki_dir) -> PipelineResult  # ingest into the KG
    def evolve(goal, ...) -> SolutionResult
    def deploy(solution, strategy) -> Software
    def index_kg(wiki_dir, save_to) -> str

OrchestratorAgent

The central coordinator. Each iteration it computes budget progress, hands the strategy the problem statement plus the previous iteration’s feedback, runs one search iteration, and stops when the judge’s verdict says the goal is met (and the handler’s task semantics honor that vote) or a budget dial reaches 100%. The faithful loop sketch lives on the orchestrator page; solve() returns a SolveResult with the deliverable experiment and the stop reason.

Pluggable components

All major components are created via factories and can be swapped via configuration:

Component	Factory	Registered Types
Search Strategy	`SearchStrategyFactory`	`generic`
Knowledge Search	`KnowledgeSearchFactory`	`kg_graph_search`, `kg_llm_navigation`
Coding Agent	`CodingAgentFactory`	`claude_code` (default), `codex`, `gemini`, `openhands`, `oss_claude_code`, plus `aider` as an optional extra
Feedback Generator	Uses `CodingAgentFactory`	Same as coding agents (default: `claude_code`)

Configuration flow

Data flow

Problem Handler provides problem context
Experiment History accessed via MCP tools
Search Strategy generates and selects solutions
Experiment Workspace manages git branches
Coding Agent generates code and runs evaluation
Coding agent ends its session with XML result tags (summary, evaluation path and output, score)
Feedback Generator validates evaluation and decides stop/continue
RepoMemory tracks code understanding across experiments

Directory structure

src/kapso/
├── kapso.py                 # Main Kapso API
├── cli.py                   # CLI entry point
├── config.yaml              # Default configuration
│
├── core/                    # Core utilities
│   ├── config.py            # YAML config loading
│   ├── llm.py               # LLMBackend (embeddings) + retry policy
│   ├── cli_inference.py     # Completions as coding-agent CLI sessions
│   ├── preflight.py         # Per-verb requirement checks (kapso doctor)
│   └── prompt_loader.py     # Prompt template loading
│
├── environment/             # Problem environment
│   └── handlers/            # Problem handlers
│       ├── base.py          # ProblemHandler ABC
│       └── generic.py       # GenericProblemHandler
│
├── execution/               # Execution layer
│   ├── orchestrator.py      # OrchestratorAgent
│   ├── solution.py          # SolutionResult dataclass
│   │
│   ├── search_strategies/   # Solution exploration
│   │   ├── base.py          # SearchStrategy ABC
│   │   ├── factory.py       # SearchStrategyFactory
│   │   ├── strategies.yaml  # Strategy presets
│   │   └── generic/         # The shipped strategy
│   │       ├── strategy.py
│   │       ├── ideation.py / implementation.py
│   │       ├── feedback_flow.py / feedback_generator/
│   │       └── expansion_lanes.py
│   │
│   ├── types.py             # ContextData, ExperimentHistoryProvider
│   │
│   ├── experiment_workspace/ # Git workspace management
│   │   ├── experiment_workspace.py
│   │   └── experiment_session.py
│   │
│   ├── coding_agents/       # Code generation
│   │   ├── base.py          # CodingAgentInterface ABC
│   │   ├── factory.py       # CodingAgentFactory
│   │   ├── agents.yaml      # Agent registry
│   │   └── adapters/        # Agent implementations
│   │       ├── claude_code_agent.py
│   │       ├── codex_agent.py
│   │       ├── gemini_agent.py
│   │       ├── openhands_agent.py
│   │       ├── oss_claude_code_agent.py
│   │       └── aider_agent.py
│   │
│   └── memories/            # Memory systems
│       ├── experiment_memory/  # Experiment history storage
│       └── repo_memory/        # Repository understanding
│
├── knowledge_base/          # Knowledge graph
│   ├── types.py             # Source types, ResearchFindings
│   │
│   ├── search/              # KG search backends
│   │   ├── base.py          # KnowledgeSearch ABC
│   │   ├── factory.py       # KnowledgeSearchFactory
│   │   ├── kg_graph_search.py
│   │   ├── kg_llm_navigation_search.py
│   │   └── workflow_search.py  # Find starter repos
│   │
│   ├── learners/            # Knowledge learning pipeline
│   │   ├── knowledge_learner_pipeline.py
│   │   ├── sources.py       # Source type wrappers
│   │   ├── merger/          # Stage 2: WikiPages → KG
│   │   │   └── knowledge_merger.py
│   │   └── ingestors/       # Stage 1: source → WikiPages
│   │       ├── base.py
│   │       ├── factory.py
│   │       └── repo_ingestor/
│   │
│   └── wiki_structure/      # Wiki page definitions
│
├── researcher/              # Deep web research
│   ├── researcher.py
│   └── prompts/
│
├── gated_mcp/               # MCP server with selective tool exposure
│   ├── server.py            # Internal gates (idea, code, research, etc.)
│   ├── presets.py           # Gate definitions + external server config (leeroopedia-mcp)
│   └── gates/
│
└── deployment/              # Deployment pipeline
    ├── base.py              # Software, DeployConfig
    ├── factory.py           # DeploymentFactory
    ├── software.py          # DeployedSoftware
    ├── selector/            # Strategy selection
    ├── adapter/             # Code adaptation
    └── strategies/          # Deployment strategies
        ├── local/
        ├── docker/
        ├── modal/
        ├── bentoml/
        └── langgraph/

Key design patterns

Factory pattern

All pluggable components use factories with decorator-based registration:

# Registration
@register_strategy("generic")
class GenericSearch(SearchStrategy):
    ...

# Creation
strategy = SearchStrategyFactory.create(
    strategy_type="generic",
    problem_handler=handler,
    llm=llm,
    coding_agent_config=config,
    params=params,
)

Configuration modes

Configuration is organized into modes that bundle related settings:

modes:
  GENERIC:
    search_strategy:
      type: "generic"
      params: { ... }
    coding_agent:
      type: "claude_code"
      model: "claude-opus-5"
    knowledge_search:
      type: "kg_graph_search"
      enabled: true
      preset: "DEFAULT"

Git-based experiment isolation

Each experiment runs on its own git branch, enabling:

Parallel experimentation
Easy rollback to any state
Parent/child lineage across candidates
RepoMemory inheritance across branches

Execution Flow

Step-by-step execution process

Feedback Generator

How evaluation is validated and feedback generated

Knowledge graph

How knowledge is acquired and used

Components

Deep dive into core components

Related pages: Execution Flow · Feedback Generator · Knowledge graph · Components 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 Evolve architecture: components and how they connect

Component responsibilities

Kapso (main API)

OrchestratorAgent

Pluggable components

Configuration flow

Data flow

Directory structure

Key design patterns

Factory pattern

Configuration modes

Git-based experiment isolation

Execution Flow

Feedback Generator

Knowledge graph

Components

​Component responsibilities

​Kapso (main API)

​OrchestratorAgent

​Pluggable components

​Configuration flow

​Data flow

​Directory structure

​Key design patterns

​Factory pattern

​Configuration modes

​Git-based experiment isolation

​Related

Execution Flow

Feedback Generator

Knowledge graph

Components

Component responsibilities

Kapso (main API)

OrchestratorAgent

Pluggable components

Configuration flow

Data flow

Directory structure

Key design patterns

Factory pattern

Configuration modes

Git-based experiment isolation

Related