Metadata-Version: 2.4
Name: genforge
Version: 0.1.0
Summary: A unified, PyTorch-based framework for generative-modeling techniques with a clean control layer.
Keywords: generative-models,diffusion,flow-matching,score-based,discrete-diffusion,guidance,control,pytorch
Author: Monish Lokhande
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: torch>=2.2
Requires-Dist: numpy>=1.26
Requires-Dist: hydra-core>=1.3
Requires-Dist: omegaconf>=2.3
Requires-Dist: scipy>=1.11 ; extra == 'flow'
Requires-Dist: wandb>=0.16 ; extra == 'logging'
Requires-Dist: tqdm>=4.66 ; extra == 'logging'
Requires-Dist: tiktoken>=0.7 ; extra == 'text'
Requires-Dist: datasets>=2.18 ; extra == 'text'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/MonishLokhande/genforge
Project-URL: Repository, https://github.com/MonishLokhande/genforge
Project-URL: Documentation, https://github.com/MonishLokhande/genforge#readme
Project-URL: Issues, https://github.com/MonishLokhande/genforge/issues
Provides-Extra: flow
Provides-Extra: logging
Provides-Extra: text
Description-Content-Type: text/markdown

# genforge

A unified, PyTorch framework for generative modeling — score/diffusion SDEs, probability-flow
ODEs, flow matching / OT-CFM, stochastic interpolants, and discrete (D3PM-style) diffusion — with a
clean **control layer** for conditioning, guidance, constraints, and amortized control.

The idea: a generative model is one process that turns a simple starting distribution (usually noise)
into data, and every way of steering it —
conditioning, guidance, constraints, planning — is the **same move**: reweight that process so the
outcomes you want become more likely. The process, the steering, and how the steering is approximated
are separate, swappable parts. A full documentation site (architecture, experiments, extending) is coming soon.

## Install

**Use it as a library:**

```bash
pip install genforge          # or: uv add genforge
```

The bundled `experiment/` tree used in the Quickstart below ships with the **source clone**, not
the PyPI wheel — running `forge train experiment=...` requires `git clone` + `uv sync`, not just
`pip install genforge`.

**Develop / run the bundled experiments:**

```bash
git clone https://github.com/MonishLokhande/genforge
cd genforge
uv sync                   # core (light: 2-D distributions)
uv sync --extra flow      # + OT-CFM (scipy)
uv sync --extra text      # + real BPE / streamed corpora (tiktoken, datasets)
uv sync --extra logging   # + experiment logging (wandb) + progress bars (tqdm)
```

Robotics adapters are a **dependency group**, not an extra (one dependency installs from git):
`uv sync --group robotics` (mujoco, robomimic, gym-pusht/aloha, minari).

## Quickstart

```bash
uv run forge list                                       # registered components
uv run forge train  experiment=distributions/ddpm/base
uv run forge sample experiment=distributions/ddpm/base  # or: sample checkpoint=<path>.pt
```

## Layout

Every component registers via `@register(category, name)` and is wired by a config-driven builder in
dependency order — adding one is a single decorated class plus a config leaf, no other wiring.

- **`src/forge/`** — the framework only: `core` (registry · builder · interfaces · protocols ·
  plugins), `spaces`, `schedules`, `models`, `methods`, `samplers`, `costs`, `control`,
  `preprocessing`, `runners`. Protocols, ABCs, and generic utilities — never concrete env code.
- **`envs/`** — concrete, swappable **data-source plugins** (environment + dataset + processor per
  package). An experiment loads them via its `plugins:` field; they are not baked into the core.
  Contracts: [`core/protocols.py`](src/forge/core/protocols.py).
- **`experiment/`** — Hydra base+delta bundles, selected with `experiment=<family>/<variant>/<method>`.

## Experiments

Selected with `experiment=<family>/<variant>/<method>`.

| Family | What |
|---|---|
| `distributions/*` | Continuous 2-D — DDPM, flow matching, stochastic-interpolant SDE, DDIM; control via projection / guidance / CBF; value guidance. |
| `discrete/d3pm/base` | Discrete (absorbing) diffusion on a toy categorical target. |
| `text/char/*` | Discrete diffusion LM, char-level — `d3pm` / `mdlm` / `sedd`. |
| `text/tinystories/*` | The **same** methods at real GPT-2 BPE (vocab 50258, needs `--extra text`). |
| `trajectory/plan/base` | Goal-conditioned trajectory planning (flat-tensor windowing, endpoint-pinned). |
| `robotics/*` | Offline-RL trajectory planning (maze2d, locomotion) and closed-loop diffusion policies (robomimic, pusht, aloha); needs `--group robotics`. |

`text/char/*` and `text/tinystories/*` are two variants of one **`text` family** (a single env plugin
`envs.text` registers both) — the same absorbing + transformer + `{d3pm,mdlm,sedd}` rig; only the
tokenizer (char vs. real BPE) and scale differ.

```bash
uv run forge train experiment=text/char/d3pm/small                     # char-level LM
uv run --extra text forge train experiment=text/tinystories/d3pm/small # same method, real BPE
```

## Documentation

A full documentation site — installation, architecture, experiments, and extending — is coming soon.
Until then, this README plus the inline docstrings across `src/forge/` are the reference.

## License

MIT — see [LICENSE](LICENSE).

## Citation

If you use genforge in your work, please cite it — citation metadata is in [CITATION.cff](CITATION.cff).
