Kapso Python API: the Kapso class, method by method

Everything public is importable from the top-level kapso package.

from kapso import Kapso, Source, DeployStrategy

kapso = Kapso()

Constructor

Kapso(
    config_path: str | None = None,
    kg_index: str | None = None,
    bank: str | None = None,
)

Argument	What it does	Default
`config_path`	Path to a config file	the packaged `config.yaml`
`kg_index`	Path to an existing `.index` file. Without one, knowledge search is off	`None`
`bank`	Lesson-bank home directory. Overrides `learning.bank.local_path`	from config

Methods at a glance

Method	Returns	What it does
`evolve()`	`SolutionResult`	Run an experiment campaign against a goal
`research()`	`ResearchFindings`	Deep web research on an objective
`learn()`	`LessonResult`	Mine one finished campaign into the lesson bank
`learn_knowledge()`	`PipelineResult`	Fold outside sources into the knowledge graph
`deploy()`	`Software`	Turn a solution into running software
`index_kg()`	`str`	Index a corpus and write a `.index` file
`memory`	`MemoryStatus`	What this agent knows right now
`Kapso.status()`	`OperationStatusView`	Read any operation’s status file
`close()`	`None`	Release knowledge-search network clients

evolve

Runs the experiment campaign: design a candidate, implement it, score it, refine.

evolve(
    goal: str | None = None,
    context: list | None = None,
    output_path: str | None = None,
    initial_repo: str | None = None,
    max_iterations: int | None = None,
    time_budget_minutes: float | None = None,
    cost_budget: float | None = None,
    finalization_reserve_minutes: float | None = None,
    resume: bool = False,
    iteration_evaluator: IterationEvaluator | None = None,
    iteration_evaluator_failure_policy: str = "record",
    mode: str | None = None,
    coding_agent: str | None = None,
    eval_dir: str | None = None,
    data_dir: str | None = None,
    additional_context: str = "",
    serving_scope: dict | None = None,
    on_status = None,
) -> SolutionResult

Argument	What it does	Default
`goal`	The objective. State it so it can be scored. Required unless resuming, when it comes from the checkpoint	`None`
`context`	Extra context passed to the campaign, such as research findings	`None`
`output_path`	Where the solution repository is written	`None`
`initial_repo`	Start from an existing repository, path or GitHub URL	`None`
`max_iterations`	Maximum experiments; a resume keeps the launch’s cap	`10`
`time_budget_minutes`	Wall-clock budget, durable across resumes	`None`
`cost_budget`	Best-effort spend budget in USD	`None`
`finalization_reserve_minutes`	Wall clock escrowed for final checkout and evaluation	`None`
`resume`	Continue a compatible checkpoint in `output_path`. Every argument left out comes from the launch record; a passed mode, coding agent, `eval_dir`, config or index that differs is refused by name	`False`
`iteration_evaluator`	Score candidates with your own evaluator	`None`
`iteration_evaluator_failure_policy`	What to do when your evaluator raises	`"record"`
`mode`	Config mode, `GENERIC` or `MINIMAL`	from config
`coding_agent`	Override the agent that writes code	from config
`eval_dir`	Evaluation files directory	`None`
`data_dir`	Data files directory	`None`
`additional_context`	Free text appended to the campaign context	`""`
`serving_scope`	Restrict which banked lessons are served	`None`
`on_status`	Callback fired on each status heartbeat	`None`

solution = kapso.evolve(
    goal="Build a random forest classifier for Iris with accuracy > 0.9",
    max_iterations=10,
    output_path="./iris_solution",
)
print(solution.explain())

SolutionResult

Attribute	Type	What it holds
`goal`	`str`	The goal you gave it
`code_path`	`str`	Directory holding the winning code
`experiment_logs`	`list[str]`	One summary per experiment
`final_feedback`	`FeedbackResult`	The last feedback, including the stop decision
`metadata`	`dict`	Cost, iteration count, final evaluation, `stopped_reason`
`requests`	`list[dict]`	What the campaign is waiting on you for, when `stopped_reason` is `"waiting_for_user"`; empty otherwise
`final_score`	`float \| None`	Score of the delivered solution
`succeeded`	`bool`	Whether the goal was met
`explain()`	`str`	All of the above as readable text

inbox and reply

A campaign pauses when a session needs something only you can provide; see the inbox. Two static methods act on a paused campaign directory.

Kapso.inbox(campaign: str) -> list[Request]
Kapso.inbox_ideas(campaign: str) -> dict[int, str]
Kapso.reply(campaign: str, request_id: int, note: str = "") -> SolutionResult | None

inbox returns the open requests, oldest first, each with id, key, hit, tried, fix and next_steps. inbox_ideas returns one line per node of the campaign, the idea a request was made for, keyed by node id; kapso inbox prints it as the for row. reply records the note and, once every request of the node that asked is answered, resumes the campaign in this process and returns its result. It returns None when another request of that node is still open, or when the campaign was started with an iteration_evaluator: the callback lives in your script, so call evolve() again there with resume=True. It raises while a live process holds the campaign.

research

research(
    objective: str,
    *,
    mode: ResearchMode | list[ResearchMode] = ["idea", "implementation"],
    depth: ResearchDepth = "deep",
) -> ResearchFindings

Argument	What it does	Default
`objective`	What to research	required
`mode`	`"idea"`, `"implementation"` or `"study"`, or a list of them	`["idea", "implementation"]`
`depth`	`"light"` or `"deep"`	`"deep"`

mode and depth are keyword-only.

findings = kapso.research(
    "QLoRA fine-tuning memory optimizations",
    mode=["idea", "implementation"],
    depth="deep",
)

ResearchFindings

Attribute	Type	What it holds
`query`	`str`	The objective you gave it
`ideas`	`list[Source.Idea]`	Approaches found
`implementations`	`list[Source.Implementation]`	Implementation references, with code
`report`	`Source.ResearchReport \| None`	Present when `mode` included `"study"`
`to_string()`	`str`	Findings as text, ready to pass as `evolve(context=[...])`
`to_dict()`	`dict`	The same as plain data

learn

Learns from one finished campaign: import it, mine it, grade the bank against it, then fold the result in as evidence-priced cards.

learn(
    source: SolutionResult | str,
    *,
    trajectory_id: str | None = None,
    learner_version: str | None = None,
    exam: bool = True,
    push: bool | None = None,
    on_status = None,
) -> LessonResult

Argument	What it does	Default
`source`	A `SolutionResult`, a path to a campaign directory, or a trajectory id already in the store	required
`trajectory_id`	Store id when importing a directory	derived from the goal or directory name
`learner_version`	Update-crew version	`learning.update_crew.default_version`
`exam`	Run the hindcast exam against the pinned pre-lesson bank head first. `False` is for development replays only	`True`
`push`	Push the bank commit to the bank’s `origin` remote	auto: pushes when the bank has an `origin` remote
`on_status`	Callback fired on each status heartbeat	`None`

lesson = kapso.learn(solution)
print(lesson.explain())

LessonResult

Attribute	Type	What it holds
`trajectory_id`	`str`	Id of the trajectory that was learned from
`bank_head_after`	`str`	Bank commit written by this lesson
`cards_created`	`list[str]`	New cards the update crew wrote
`cards_updated`	`list[str]`	Existing cards the lesson modified
`exam_report_path`	`str \| None`	Hindcast exam report, when `exam=True`
`lesson_report_path`	`str \| None`	The lesson report
`admitted`	`bool`	Whether the lesson was admitted to the bank
`explain()`	`str`	The above as readable text

learn_knowledge

Folds outside sources into the knowledge graph. This is the other memory: learn() mines your own campaigns, learn_knowledge() imports other people’s work.

learn_knowledge(
    *sources: Source.Repo | Source.Solution | Source.Idea
            | Source.Implementation | Source.ResearchReport | ResearchFindings,
    wiki_dir: str = "data/wikis",
    skip_merge: bool = False,
    kg_index: str | None = None,
    github_org: str | None = None,
    is_private: bool | None = None,
    on_status = None,
) -> PipelineResult

Argument	What it does	Default
`*sources`	One or more sources. A `ResearchFindings` can be passed directly	required
`wiki_dir`	Where extracted wiki pages are written	`"data/wikis"`
`skip_merge`	Extract pages without merging them into the graph	`False`
`kg_index`	Index to merge into	from the constructor
`github_org`	Organisation for a staging repository	`None`
`is_private`	Whether that repository is private	from config

kapso.learn_knowledge(
    Source.Repo("https://github.com/huggingface/trl"),
    findings,
    wiki_dir="data/wikis",
)

Source variants

Variant	Takes
`Source.Repo(url)`	A repository URL
`Source.Solution(obj)`	A `SolutionResult`
`Source.Idea(query, source, content)`	A research idea
`Source.Implementation(query, source, content)`	An implementation reference
`Source.ResearchReport(...)`	A study-mode research report

PipelineResult

Attribute	Type	What it holds
`sources_processed`	`int`	How many sources were read
`total_pages_extracted`	`int`	Wiki pages produced
`extracted_pages`	`list[WikiPage]`	The pages themselves
`merge_result`	`MergeResult \| None`	What the merge changed
`errors`	`list[str]`	Anything that failed
`created` / `edited`	`int`	Counts of pages the merge created and edited
`success`	`bool`	No errors, or pages were still extracted despite them

deploy

deploy(
    solution: SolutionResult,
    strategy: DeployStrategy = DeployStrategy.AUTO,
    env_vars: dict[str, str] | None = None,
    coding_agent: str | None = None,
    model: str | None = None,
) -> Software

Argument	What it does	Default
`solution`	The result to deploy	required
`strategy`	`AUTO`, `LOCAL`, `DOCKER`, `MODAL`, `BENTOML` or `LANGGRAPH`	`AUTO`
`env_vars`	Environment variables for the deployed software	`None`
`coding_agent`	Agent behind the selector and adapter sessions	from config (`deployment.coding_agent`)
`model`	The model that agent is asked for	from config (`deployment.model`)

deployed = kapso.deploy(solution, strategy=DeployStrategy.LOCAL)
result = deployed.run({"data_path": "./test.csv"})
deployed.stop()

AUTO picks a strategy for you. See Deployment strategies.

index_kg

Indexes a corpus and returns the path of the .index file it wrote.

index_kg(
    wiki_dir: str | None = None,
    data_path: str | None = None,
    save_to: str = None,
    search_type: str | None = None,
    force: bool = False,
) -> str

Argument	What it does	Default
`wiki_dir`	Wiki directory to index	`None`
`data_path`	JSON data file to index, as an alternative to `wiki_dir`	`None`
`save_to`	Where to write the `.index` file	required in practice
`search_type`	`kg_graph_search` or `kg_llm_navigation`	from config
`force`	Clear existing data before indexing	`False`

index_path = kapso.index_kg(
    wiki_dir="data/wikis",
    save_to="data/indexes/finetuning.index",
)

kapso = Kapso(kg_index=index_path)

memory

A property, not a method. Reports what this agent knows across both stores.

status = kapso.memory
print(status.explain())

Attribute	Type	What it holds
`knowledge_index`	`str \| None`	The loaded `.index`, if any
`knowledge_enabled`	`bool`	Whether knowledge search is on
`bank_head`	`str \| None`	Current lesson-bank commit
`store_trajectories`	`int \| None`	Trajectories in the store
`explain()`	`str`	The above as readable text

status

A static method. Reading a run needs no constructed agent.

Kapso.status(path: str) -> OperationStatusView

view = Kapso.status("./campaign")
print(view.explain())

path accepts a workspace, a status file, or a directory of status files. view.explain() renders the same screen as kapso watch.

close

Releases the knowledge-search network clients: Weaviate, Neo4j and embeddings.

kapso.close()

Idempotent, and registered at construction to run on exit, so scripts finish without unclosed-socket warnings. Calling it early is safe; index_kg() and learn_knowledge() reconnect.

CLI

The same operations from the command line

Configuration

Every key in config.yaml

Related pages: CLI · Configuration · CLI 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.

​Constructor

​Methods at a glance

​evolve

​SolutionResult

​inbox and reply

​research

​ResearchFindings

​learn

​LessonResult

​learn_knowledge

​Source variants

​PipelineResult

​deploy

​index_kg

​memory

​status

​close

​Related

CLI