Architecture

Overview

Kapso uses a modular architecture with pluggable components connected through factories. The system is designed around a central orchestration loop that coordinates experimentation.

Component Responsibilities

Kapso (Main API)

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

class Kapso:
    def research(objective, mode, depth) -> Source.Research
    def learn(*sources, wiki_dir) -> PipelineResult
    def evolve(goal, ...) -> SolutionResult
    def deploy(solution, strategy) -> Software
    def index_kg(wiki_dir, save_to) -> str

OrchestratorAgent

The central coordinator that manages the solve loop:

def solve(self, experiment_max_iter, time_budget_minutes, cost_budget):
    for i in range(experiment_max_iter):
        # Calculate budget progress (0-100)
        budget_progress = max(time, iterations, cost) * 100

        # Check stopping conditions
        if self.problem_handler.stop_condition() or budget_progress >= 100:
            break

        # Get enriched context (problem + KG + history)
        context = self.context_manager.get_context(budget_progress)

        # Check if LLM decided COMPLETE
        if self.context_manager.should_stop():
            break

        # Run one search iteration
        self.search_strategy.run(context, budget_progress)

Pluggable Components

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

Component	Factory	Registered Types
Search Strategy	`SearchStrategyFactory`	`generic`, `benchmark_tree_search`
Knowledge Search	`KnowledgeSearchFactory`	`kg_graph_search`, `kg_llm_navigation`
Coding Agent	`CodingAgentFactory`	`aider`, `gemini`, `claude_code`, `openhands`
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
Developer Agent returns structured JSON with evaluation results
Feedback Generator validates evaluation and decides stop/continue
RepoMemory tracks code understanding across experiments

Directory Structure

src/
├── kapso.py                 # Main Kapso API
├── cli.py                   # CLI entry point
├── config.yaml              # Default configuration
│
├── core/                    # Core utilities
│   ├── config.py            # YAML config loading
│   ├── llm.py               # LLM backend (OpenAI, etc.)
│   └── 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/         # Claude Code + MCP gates
│   │   │   └── strategy.py
│   │   └── benchmark_tree_search.py  # For MLE/ALE benchmarks
│   │
│   ├── 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
│   │       ├── aider_agent.py
│   │       ├── gemini_agent.py
│   │       ├── claude_code_agent.py
│   │       └── openhands_agent.py
│   │
│   └── memories/            # Memory systems
│       ├── experiment_memory/  # Experiment history storage
│       └── repo_memory/        # Repository understanding
│
├── knowledge_base/          # Knowledge system
│   ├── 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: "aider"
      model: "gpt-4o-mini"
    context_manager:
      type: "kg_enriched"
    knowledge_search:
      type: "kg_graph_search"
      enabled: true

Git-Based Experiment Isolation

Each experiment runs on its own git branch, enabling:

Parallel experimentation
Easy rollback to any state
Tree-based solution exploration
RepoMemory inheritance across branches

Next Steps

Execution Flow

Step-by-step execution process

Feedback Generator

How evaluation is validated and feedback generated

Knowledge System

How knowledge is acquired and used

Components

Deep dive into core components

Getting Started

Evolve System

Knowledge System & Learning

Research

Deployment

Benchmarks

Architecture

Overview

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

Next Steps

Execution Flow

Feedback Generator

Knowledge System

Components

​Overview

​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

​Next Steps

Execution Flow

Feedback Generator

Knowledge System

Components

Overview

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

Next Steps