Particle swarm

Skill AllanWessels/Bratan/skills/particle-swarm

Bratan is a self-improving Retrieval-Augmented Generation framework built on an adversarial three-agent loop

Install

npx -y skills add AllanWessels/Bratan --skill particle-swarm

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use this skill when the Blue Team needs to optimize over a mixed continuous + discrete + categorical space too large for grid search and too rough for Bayesian Optimization's Gaussian-Process surrogate. PSO and its evolutionary cousins (CMA-ES, GA) navigate jagged surfaces by maintaining a population of candidates that pull toward both individual and global bests.

SKILL.md

3.2 KB, 715 tokens by cl100k_base, as published. Nobody here has run it

Particle Swarm Optimization

When to use

The search space mixes continuous (chunk_size, temperature), discrete (k, top_n), and categorical (embedding model, reranker model, prompt variant) parameters.
The response surface is rough / multimodal — small parameter changes cause large score changes. BO's GP surrogate assumes smoothness and performs poorly here.
You have enough budget to evaluate a population (typically 10–20 particles) over 5–10 generations on the prejudge.

When not to use

Smooth, low-dimensional, continuous space → use BO.
Small enumerable space → use grid sweep.
Single most-important parameter → ablate it, then tune.
You can't afford a few hundred prejudge evaluations. PSO trades sample efficiency for surface-robustness; that trade only pays off when the prejudge is cheap.

The procedure

Define the swarm. 10–20 particles, each a full parameter vector sampled uniformly from the search space.
Each generation:
- Evaluate every particle on eval.py --subset --mode prejudge.
- Update each particle's velocity using its personal best and the global best, with the canonical PSO update:
```
v ← w·v + c1·r1·(p_best − x) + c2·r2·(g_best − x)
x ← x + v
```
  Defaults: inertia w=0.7, cognitive c1=1.5, social c2=1.5, r1, r2 ~ U(0, 1).
- Clamp categorical / discrete dimensions to the nearest valid value after the update.
Terminate when the global-best composite plateaus for 3 generations, or when the budget is hit.
Oracle-validate the global best on the full test set. If it doesn't beat the incumbent, treat the entire PSO run as a low-confidence signal and do not persist.

Variants worth knowing

CMA-ES — Covariance Matrix Adaptation Evolution Strategy. Strictly better than vanilla PSO on continuous-only spaces, but doesn't natively handle categorical parameters. Use when your search space goes fully numeric.
NSGA-II — multi-objective evolutionary algorithm. Use when the Blue Team wants the Pareto frontier of (composite, cost) or (composite, latency), not just the max-composite point.

Why PSO earns its keep here

The pipeline's response surface is genuinely rough. Swapping the embedding model from bge-large to nomic-embed doesn't just shift the score by epsilon — it relocates the entire chunking + retrieval sweet spot. PSO's population-based exploration catches those discrete regime shifts in a way that single-point BO often misses.

Composes with

ablation — ablate first to factor the problem and reduce dimensionality.
bayesian-optimization — once PSO identifies the right region, BO inside that region refines the continuous axes.