rainforest-lab (Python package)

pip install rainforest-lab — the engine of the rainforest research framework.

This package implements the rainforest engine (v1 + v2.0 multi-agent deliberation + v2.1 trajectory primitives), four LLM Protocols, a LiteLLM reference adapter, and two reusable kits (dsl, gates) so each new domain plugin stays ~150 lines.

See the top-level README for the project vision; this README is package-level.

Install

pip install rainforest-lab
# Optional: LiteLLM reference adapter (~100 providers behind one interface)
pip install "rainforest-lab[litellm]"

30-second tour

from rainforest_lab import (
    DemoDomain, Forest, run_cycle,
    MockGardener, MockInspector, MockSkeptic,
    DeliberationConfig, ParallelGardenersConfig,
)

# Build a Forest, then drive one cycle with mocked LLMs (replace with real ones in production).
# See examples/quick_start.py for a runnable end-to-end demo.

• examples/quick_start.py — end-to-end demo with mocked LLMs.
• examples/bring_your_own_llm.py — plug your own LLM SDK in via the framework's builders.
• examples/write_your_own_domain.py — template for a new market plugin (~150 lines).

What's in here

Rigor invariants (test-guarded)

1. Gate completeness is a type invariant — a result cannot classify as fruit without a complete GateRecord and execution_mode == "tool_executed".
2. Single writer — cycle.run_cycle is the only forest-state mutator; deliberation and trajectory operators are pure (read-only on Forest).
3. Different-model skeptic — make_llm_skeptic refuses to run when its model family equals the gardener's.
4. No fruit by lineage — trajectory mutate / crossover produce children with final_classification = None; sick parents are excluded.
5. No silent fallback — LLM unavailability is always hard fail.

License

MIT. See ../LICENSE.