Quickstart

from kapso.kapso import Kapso, DeployStrategy

# Initialize Kapso
kapso = Kapso()

# Build a solution — Kapso runs experiments automatically
# The developer agent builds evaluation dynamically and the feedback generator
# validates results and decides when to stop
solution = kapso.evolve(
    goal="Build a random forest classifier for the Iris dataset with accuracy > 0.9",
    max_iterations=10,
)

# Deploy and run
deployed_program = kapso.deploy(solution, strategy=DeployStrategy.LOCAL)
result = deployed_program.run({"data_path": "./test.csv"})

# Cleanup
deployed_program.stop()

# Basic usage
kapso evolve --goal "Build a random forest classifier for the Iris dataset"

# With options
kapso evolve \
    --goal "Build a feature engineering pipeline for tabular data" \
    --iterations 10 \
    --coding-agent aider

# List available options
kapso --list-agents

============================================================
EVOLVING: Build a random forest classifier for the Iris dataset
============================================================
  Max iterations: 10
  Coding agent: from config

Running experiments...
Experiment 1: Developer agent implementing solution...
Experiment 1: Running evaluation in kapso_evaluation/...
Experiment 1: Feedback generator validating results...
Experiment 1 completed with cumulative cost: $0.125
####################################################################################################
Experiment with score 0.92:
# Solution: Random forest with GridSearchCV hyperparameter tuning...
# Feedback: Good progress! Accuracy 0.92 meets the > 0.9 target. Goal achieved.
####################################################################################################

============================================================
Evolution Complete
============================================================
Solution at: ./workspace
Experiments run: 1
Total cost: $0.125
Goal achieved: Yes

from kapso.kapso import Kapso

kapso = Kapso()

# Research returns ResearchFindings with ideas and implementations
# mode: "idea" | "implementation" | "both" (default: "both")
# depth: "light" | "deep" (default: "deep")

findings = kapso.research(
    "unsloth FastLanguageModel example",
    mode="both",
    depth="deep",
)

# Use research as context for evolving
solution = kapso.evolve(
    goal="Fine-tune a model with Unsloth + LoRA",
    context=[findings.to_string()],
    output_path="./models/unsloth_v1",
)

solution.goal             # Original goal
solution.code_path        # Path to generated code
solution.experiment_logs  # List of experiment summaries
solution.final_feedback   # FeedbackResult with stop decision and score
solution.metadata         # Cost, iterations, final evaluation

# Check if goal was achieved
if solution.succeeded:
    print(f"Goal achieved with score: {solution.final_score}")

cd ./models/iris_v1
git branch -a
# * experiment_2  (best solution)
#   experiment_1
#   experiment_0
#   main