Skip to main content

CurryTruck

Tests

Finding the best solution, one ingredient at a time.

You've got shifts to fill, routes to drive, a budget to split, and a model with eleven knobs. Every choice pulls against another.

CurryTruck.

pip install currytruck

CurryTruck is a general-purpose optimization toolkit for Python. It helps you find optimal or near-optimal solutions to problems involving constraints, limited resources, and competing objectives — in pure Python, with zero dependencies.


The Menu

Module Dish Algorithms
🌶️ spice Parameter optimization Grid search, random search
🥘 blend Combinatorial optimization 0/1 knapsack, subset selection
🍲 simmer Iterative optimization Gradient descent (with momentum, bounds)
🔥 heat Global optimization Simulated annealing, genetic algorithms
📖 recipe Constraint satisfaction Backtracking + forward checking
👅 taste Objective evaluation Penalties, weighted scores, benchmark functions
🍽️ portion Resource allocation Linear programming (two-phase simplex)
⚖️ balance Multi-objective optimization Pareto fronts, non-dominated sorting
🚚 serve Results and reporting Rankings, convergence statistics

Every optimizer returns the same Result object — x (best solution), score, history, n_evals, converged, message — so results from different algorithms can be compared and reported the same way.

Import functions directly, or use the modules as namespaces:

from currytruck import simulated_annealing, linprog
from currytruck import heat, portion   # heat.simulated_annealing, portion.linprog

🌶️ spice — Parameter Optimization

Season to taste. The objective is called with each parameter set as keyword arguments.

from currytruck import grid_search, random_search

r = grid_search(train_and_score, {"depth": [3, 5, 8], "lr": [0.01, 0.1]}, maximize=True)
r.x        # {'depth': 5, 'lr': 0.1}

r = random_search(
    train_and_score,
    {
        "depth": (2, 12),            # int range   -> uniform integer
        "lr": (0.001, 0.3),          # float range -> uniform float
        "kernel": ["rbf", "linear"], # list        -> random choice
    },
    n_iter=200, seed=42, maximize=True,
)

🥘 blend — Combinatorial Optimization

from currytruck import knapsack, best_subset

# Which ingredients fit in a 50kg truck for the most value?
r = knapsack(values=[60, 100, 120], weights=[10, 20, 30], capacity=50)
r.x       # [1, 2]  (indices)
r.score   # 220

# Best 3-person team by combined skill, with at most one senior
r = best_subset(people, objective=team_skill, size=3,
                constraint=lambda team: sum(p.senior for p in team) <= 1)

knapsack is exact — dynamic programming for integer weights, branch-and-bound for real-valued ones. best_subset is exhaustive up to max_evals candidate subsets, then falls back to greedy forward selection.

🍲 simmer — Gradient Descent

Low and slow.

from currytruck import gradient_descent

r = gradient_descent(loss, x0=[0.0, 0.0], lr=0.05, momentum=0.9)
r = gradient_descent(loss, x0, grad=my_gradient)         # analytic gradient
r = gradient_descent(loss, x0, bounds=[(0, 1), (0, None)])  # projected onto a box

Without grad=, a central-difference numerical gradient is used.

🔥 heat — Global Optimization

Turn up the heat to escape local optima.

from currytruck import simulated_annealing, genetic_algorithm, reverse_neighbor

# Continuous
r = simulated_annealing(f, x0=[4.0, 4.0], bounds=[(-5, 5), (-5, 5)], heat=4, seed=1)

# Delivery route — search over orderings
r = simulated_annealing(route_length, x0=list(range(n_stops)), neighbor=reverse_neighbor)

# Genetic algorithm: vector mode or permutation mode
r = genetic_algorithm(f, bounds=[(-5, 5)] * 10, population=80, generations=300)
r = genetic_algorithm(route_length, permutation=range(n_stops), patience=50)

🔥 The Heat Guide

heat takes a heat level (1–5). Higher heat means more exploration.

Heat Annealing start temp GA mutation rate Vibe
1 × 0.1 1% Mild. Barely leaves home.
2 × 0.5 5% A little warmth.
3 × 1.0 10% Medium. The default.
4 × 2.0 20% Getting spicy. Wanders far.
5 × 5.0 40% Napalm. Explores everything.

📖 recipe — Constraint Satisfaction

from currytruck import Recipe

shifts = ["morning", "evening", "night"]
r = (
    Recipe()
    .add_variable("ann", shifts)
    .add_variable("bob", shifts)
    .add_variable("cat", shifts)
    .all_different(["ann", "bob", "cat"])
    .add_constraint("ann", lambda s: s != "night")
)
r.solve().x
# Find the best schedule, not just a valid one:
r.solve(objective=lambda a: a["bob"] == "morning", maximize=True).x

Or functionally: solve_csp(variables, constraints, objective=..., all_solutions=True).

👅 taste — Objective Evaluation

from currytruck import penalized, weighted_sum, counted
from currytruck.taste import rastrigin, rosenbrock   # benchmark functions

# Turn a constrained problem into an unconstrained one: g(x) <= 0
f = penalized(cost, [lambda x: x[0] + x[1] - 10], weight=1e4)

score = weighted_sum({"cost": 120, "delay": 3}, {"cost": 1.0, "delay": 25.0})
f = counted(expensive_objective)   # f.calls tracks evaluations

🍽️ portion — Linear Programming

from currytruck import linprog, allocate

# maximize 3x + 5y  st  x <= 4,  2y <= 12,  3x + 2y <= 18
r = linprog([3, 5], A_ub=[[1, 0], [0, 2], [3, 2]], b_ub=[4, 12, 18], maximize=True)
r.x, r.score     # [2.0, 6.0], 36.0

# Split a budget across options
r = allocate(100_000, returns={"ads": 1.4, "seo": 1.2, "events": 1.6},
             maximum={"events": 20_000}, minimum={"seo": 10_000})
r.x   # {'ads': 70000.0, 'seo': 10000.0, 'events': 20000.0}

Supports A_eq/b_eq equalities and per-variable (lo, hi) bounds (None = unbounded). Raises InfeasibleError or UnboundedError when appropriate.

⚖️ balance — Multi-Objective Optimization

from currytruck import pareto_search

front = pareto_search(
    [lambda p: p.risk, lambda p: p.expected_return],
    portfolios,
    maximize=[False, True],   # minimize risk, maximize return
)

Also: dominates, pareto_front, pareto_rank (non-dominated sorting), crowding_distance.

🚚 serve — Results and Reporting

from currytruck import serve

runs = [simulated_annealing(f, x0, seed=s) for s in range(5)]
print(serve.leaderboard(runs))
print(serve.report(serve.best(runs)))
serve.convergence(runs[0])   # initial/final, improvement, iteration_of_best, plateau

Real-World Uses

Problem Reach for
Employee scheduling recipe
Delivery route optimization heat with reverse_neighbor or permutation=
Resource allocation across projects portion.allocate, blend.knapsack
Investment allocation under risk limits portion.linprog, balance
Manufacturing waste / efficiency portion.linprog, taste.penalized + heat
ML hyperparameters, custom objectives spice, simmer
Game AI and tactics heat, blend.best_subset

Exceptions

All exceptions inherit from CurryTruckError and from ValueError, so existing except ValueError code keeps working: InvalidHeatLevel, InfeasibleError, UnboundedError, EmptySpaceError.


The Food Truck Fleet

Package Focus
thaitruck Batch DataFrame cleaning, merging, profiling, caching
sushitruck Streaming ingestion and connectors
ramentruck ML/AI toolkit
currytruck Mathematical optimization

License

MIT © Babble Baz

Metadata

Release files for currytruck 2026.11.16

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for currytruck 2026.11.16
File Size Uploaded Provenance Actions
currytruck-2026.11.16.tar.gz 38.5 kB Without provenance Details for currytruck-2026.11.16.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for currytruck 2026.11.16
File Interpreter ABI Platform Actions
currytruck-2026.11.16-py3-none-any.whl Python 3 none any Details for currytruck-2026.11.16-py3-none-any.whl

Total release size: 70.9 kB

Release files / currytruck-2026.11.16.tar.gz

Download URL currytruck-2026.11.16.tar.gz
Size 38.5 kB
Tags Source
SHA-256 checksum
How to use checksums
a9d7b19e3e72cc6dd12f050912c1a9168e8cbfef970b9b6cc3aae106fdaa9b86
BLAKE2b-256 checksum
How to use checksums
4c935bed9cd9f2382921216b916454427c16c6e0b8cc0e07dc2e2c66930959b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.9

Release files / currytruck-2026.11.16-py3-none-any.whl

Download URL currytruck-2026.11.16-py3-none-any.whl
Size 32.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e589d5f2acded0c2f63a033bacefe7c79bcb2e3225ed08cf22b0ec58dc56a0e3
BLAKE2b-256 checksum
How to use checksums
1a2b03f22f78f1d2b4d9bc7a13162068c739bd5c973a9689ed0df6eeb45cf0a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.9

Security for currytruck 2026.11.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2026.11.16 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page