Skip to main content

​
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:
ComponentFactoryRegistered Types
Search StrategySearchStrategyFactoryllm_tree_search, linear_search
Context ManagerContextManagerFactorytoken_efficient, kg_enriched, cognitive
Knowledge SearchKnowledgeSearchFactorykg_graph_search, kg_llm_navigation
Coding AgentCodingAgentFactoryaider, gemini, claude_code, openhands
EvaluatorEvaluatorFactoryno_score, regex_pattern, llm_judge, …
Stop ConditionStopConditionFactorynever, threshold, plateau, …

​
Configuration Flow

​
Data Flow

  1. Problem Handler provides problem context and evaluation
  2. Context Manager gathers problem + history + knowledge
  3. Search Strategy generates and selects solutions
  4. Experiment Workspace manages git branches
  5. Coding Agent generates code from solutions
  6. Problem Handler evaluates code and returns scores
  7. 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
│   ├── evaluators/          # Score evaluation
│   │   ├── base.py          # Evaluator ABC
│   │   ├── builtin.py       # Built-in evaluators
│   │   └── factory.py       # EvaluatorFactory
│   └── stop_conditions/     # Early stopping
│       ├── base.py          # StopCondition ABC
│       ├── builtin.py       # Built-in conditions
│       └── factory.py       # StopConditionFactory
│
├── execution/               # Execution layer
│   ├── orchestrator.py      # OrchestratorAgent
│   ├── solution.py          # SolutionResult dataclass
│   │
│   ├── search_strategies/   # Solution exploration
│   │   ├── base.py          # SearchStrategy ABC
│   │   ├── factory.py       # SearchStrategyFactory
│   │   ├── llm_tree_search.py
│   │   └── linear_search.py
│   │
│   ├── context_manager/     # Context gathering
│   │   ├── base.py          # ContextManager ABC
│   │   ├── factory.py       # ContextManagerFactory
│   │   └── types.py         # ContextData dataclass
│   │
│   ├── experiment_workspace/ # Git workspace management
│   │   ├── experiment_workspace.py
│   │   └── experiment_session.py
│   │
│   ├── coding_agents/       # Code generation
│   │   ├── base.py          # CodingAgentInterface ABC
│   │   ├── factory.py       # CodingAgentFactory
│   │   └── adapters/        # Agent implementations
│   │       ├── aider_agent.py
│   │       ├── gemini_agent.py
│   │       ├── claude_code_agent.py
│   │       └── openhands_agent.py
│   │
│   ├── ideation/            # Solution generation
│   │   └── repo_memory_react.py
│   │
│   └── prompts/             # Prompt templates
│       ├── coding_agent_implement.md
│       └── coding_agent_debug.md
│
├── knowledge/               # Knowledge system
│   ├── search/              # KG search backends
│   │   ├── base.py          # KnowledgeSearch ABC
│   │   ├── factory.py       # KnowledgeSearchFactory
│   │   ├── kg_graph_search.py
│   │   └── kg_llm_navigation_search.py
│   │
│   ├── learners/            # Knowledge learning pipeline
│   │   ├── knowledge_learner_pipeline.py
│   │   ├── knowledge_merger.py
│   │   ├── sources.py       # Source type wrappers
│   │   └── ingestors/       # Stage 1: source → WikiPages
│   │       ├── base.py
│   │       ├── factory.py
│   │       ├── repo_ingestor/
│   │       ├── experiment_ingestor.py
│   │       └── research_ingestor.py
│   │
│   ├── web_research/        # Deep web research
│   │   ├── deep_web_research.py
│   │   └── prompts/
│   │
│   └── wiki_structure/      # Wiki page definitions
│
├── memory/                  # Memory systems
│   ├── cognitive_controller.py
│   ├── episodic.py
│   └── types.py
│
├── repo_memory/             # Repository memory
│   ├── manager.py           # RepoMemoryManager
│   ├── builders.py          # LLM-based model building
│   └── observation.py       # Section extraction
│
└── 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("llm_tree_search")
class LlmSteeredTreeSearch(SearchStrategy):
    ...

# Creation
strategy = SearchStrategyFactory.create(
    strategy_type="llm_tree_search",
    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: "linear_search"
      params: { ... }
    coding_agent:
      type: "aider"
      model: "gpt-4o-mini"
    context_manager:
      type: "token_efficient"
    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

Tree Search

LLM-guided solution exploration

Knowledge System

How knowledge is acquired and used

Components

Deep dive into core components