Metadata-Version: 2.4
Name: rainforest-lab
Version: 0.1.0
Summary: Honest multi-agent research framework — engine + DSL/gates kits + LLM Protocols
Project-URL: Homepage, https://github.com/KrakenP/rainforest-lab
Project-URL: Documentation, https://github.com/KrakenP/rainforest-lab/tree/master/python
Project-URL: Source, https://github.com/KrakenP/rainforest-lab
Project-URL: Issues, https://github.com/KrakenP/rainforest-lab/issues
Author: Rainforest Lab Contributors
License-Expression: MIT
Keywords: agent-skill,factor-mining,llm,multi-agent,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.20
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pandas-stubs>=2.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Requires-Dist: types-jsonschema>=4.20; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: litellm
Requires-Dist: litellm>=1.40; extra == 'litellm'
Description-Content-Type: text/markdown

# 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](../README.md) for the project vision; this README is package-level.

## Install

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

## 30-second tour

```python
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

| Module | What |
|---|---|
| `state` · `validate` · `classify` | Canonical state model + fail-loud validator + result classification |
| `weather` · `seeds` · `roles` · `events` · `handoff` | Per-cycle attention router, seed scoring/nursery, agent-attributed events, schema'd handoff protocol |
| `cycle` · `deliberation` · `trajectories` | The cycle driver, v2.0 multi-agent deliberation, v2.1 trajectory evolution primitives |
| `domain` | The `ResearchDomain` ABC + `cache_dir()` helper |
| `dsl.types` · `dsl.parser` · `dsl.evaluator` · `dsl.random_formula` | The DSL kit |
| `gates.factor_gates` · `gates.matched_random` · `gates.profiles` | The gates kit |
| `llm.protocols` · `llm.builders` · `llm.litellm_adapter` · `llm.mocks` | LLM-agnostic protocols + builders + reference adapter |
| `domains.demo` | Reference domain plugin using the kits |

## 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`](../LICENSE).
