# RFC (Overview): Restructuring mellea-contribs for Bleeding-Edge Contributions

[avinash2692]

RFC (Overview): Restructuring mellea-contribs for Bleeding-Edge Contributions

• Status: Draft
• Author: Avinash Balakrishnan
• Created: 2026-05-14
• Repo: generative-computing/mellea-contribs (independent of generative-computing/mellea)

---

1. Executive Summary — Why We Need This

Mellea has no sanctioned home for bleeding-edge contributions — novel sampling algorithms, third-party framework bridges (DSPy, LangChain, CrewAI), domain-specific requirements, and incubating research code. The mellea-contribs repo was created to fill that gap, but six subpackages in, it's already accumulating the kind of structural drift that becomes unfixable at scale: inconsistent layouts, ad-hoc CI, no archival story for unmaintained code, and import paths that bear no relation to where the code would live if it graduated into core.

Two concrete consequences today:

• A contributor with a new sampling idea has no clear path from "I have working code" to "Mellea users can pip install this."
• A contributor whose subpackage stops being maintained has no clean way to step away — and unrelated contributors have no way to ship around their broken code.

Both gaps compound as contribs grows. There are six subpackages now, not sixty. This is the cheap moment to lock in structure.

This RFC proposes three load-bearing changes:

1. Subpackages mirror core's internal layout so graduation into core is mechanical.
2. A clean eviction contract so unmaintained code exits without blocking anyone.
3. Graduation as a first-class motion so promising contribs work has a documented path into core.

The structure (1) makes graduation (3) cheap. The eviction contract (2) keeps the repo healthy as new contributions arrive. They reinforce each other; neither works alone.

2. Proposed Structure: Mirror Core mellea/

The headline change: a contribs subpackage's source layout is identical to where its code would live if it were in core mellea.

Examples:

If the code would live in core at…	…it lives in contribs at…
mellea/stdlib/sampling_algos/my_algo.py	mellea_contribs/stdlib/sampling_algos/my_algo.py
mellea/stdlib/frameworks/dspy.py	mellea_contribs/stdlib/frameworks/dspy/
mellea/stdlib/requirements/python_imports.py	mellea_contribs/stdlib/requirements/python_imports.py
mellea/backends/my_experimental_backend.py	mellea_contribs/backends/my_experimental_backend.py

The only path difference between contribs and core is the top-level prefix: mellea_contribs. vs. mellea..

What this gives us

• A predictable place for new contributions. A contributor doesn't have to invent where their sampler "belongs" — it goes where it would go in core, full stop. The decision is already made.
• A mental model that matches what users already know. If you understand core's layout, you understand contribs's layout. Imports are obvious from the file's purpose.
• Per-subpackage installability. Each subpackage is its own PyPI distribution under a meta-package's extras (uv add "mellea-contribs[stdlib.frameworks.dspy]"), so users pull only what they need and heavy dependencies don't leak across subpackages.
• A single, enforceable contract for new contributions. Every subpackage looks the same: same pyproject.toml shape, same test directory name, same required files (OWNERS, README.md, tests/, examples/). Drift becomes a CI failure, not a reviewer's burden.

The full RFC explains how the contribution path works (cookiecutter scaffold, validate-structure CI gate); this overview just commits to the shape.

3. Graduation: From Contribs to Core

The structure (Section 2) directly enables graduation as a near-zero-cost motion. When a contribs subpackage proves itself — stable API, sustained user adoption, owners willing to commit to core's stability bar — it can move into core via:

git mv mellea-contribs/.../mellea_contribs/<path>  mellea/mellea/<path>

…plus a one-prefix import bump for users:

- from mellea_contribs.stdlib.sampling_algos.my_algo import MyAlgo
+ from mellea.stdlib.sampling_algos.my_algo          import MyAlgo

That's the entire mechanical change. No file restructuring, no API redesign, no rewrite. The contribs side leaves a re-export shim with a DeprecationWarning for one Mellea release cycle, then drops it.

Why this matters

Graduation that costs a rewrite never happens. Promising experimental code stagnates in contribs because the migration tax is too high, or worse, gets reimplemented from scratch in core, losing the original contributor's involvement. By making the contribs path identical to the eventual core path, the cost of graduation collapses to a code review and a search-and-replace — and the original author stays in the loop because their code, not a rewritten version, is what lands.

What graduation is and isn't

This RFC commits to:

• The structure that enables cheap graduation.
• The principle that graduation is the success outcome for contribs subpackages — not an exception, not a detour.

This RFC explicitly does not commit to:

• A graduation policy (criteria, approvals, version-bump expectations). That's a per-subpackage decision and deserves its own RFC when the first candidate is ready.
• A schedule or quota for graduations.

The point here is that the option is structurally cheap. When and how to exercise it remains an editorial call.

4. Eviction: Clean Exits for Unmaintained Code

The flip side of "make it easy to contribute" is "make it safe to leave." Without a documented eviction path, contribs becomes a junkyard of half-maintained code that scares off both new contributors (who don't want to inherit ambiguity) and users (who can't tell which subpackages are alive).

What we commit to

When a contribs subpackage breaks and its OWNERS don't fix it within a documented grace window, we archive it:

• The package is dropped from mellea-contribs[all] and from the meta-package's published extras list.
• The directory stays in the repo with an ARCHIVED.md explaining why and how to revive — code is never deleted.
• Past PyPI releases of the archived subpackage remain installable for users who depended on a specific version.
• Revival is always available: any contributor can open a PR that restores green CI and re-acknowledges ownership, and the subpackage rejoins the release.

What this gives us

• A safe exit for maintainers. "I'm moving teams" or "I lost interest" is a recoverable state, not a guilt-trip. The contract makes it explicit that walking away is fine.
• A predictable signal for users. "Is this contribs subpackage alive?" has an answer: check whether it's in the latest mellea-contribs[all]. No more guessing from commit timestamps.
• Failure isolation. A broken subpackage cannot block the rest of contribs from releasing or unrelated contributors from merging.
• Reversibility. Archival never destroys code or history; someone who finds the package via a search engine two years later can read what was there and decide whether to revive it.

The full RFC specifies the implementation: a 21-day timeline driven by per-subpackage CI failures, owner-pings via auto-opened issues, and the release-time logic that drops red subpackages from the next published [all] extra. This overview just commits to the contract.

5. How These Three Pieces Fit Together

Read in order:

• Structure (Section 2) says: every subpackage looks like core, installable on its own.
• Graduation (Section 3) says: when a subpackage matures, the structure makes promotion to core mechanical.
• Eviction (Section 4) says: when a subpackage atrophies, the structure lets us archive it without collateral damage.

A contribs subpackage's lifecycle, end-to-end:

flowchart LR
    A([New contribution]) -->|cookiecutter PR<br/>passes structure gate| B[Active in contribs]

    B -->|stable + adopted<br/>graduation RFC merged| G([Graduated to core mellea])
    B -->|CI red, no fix in 21 days| C[Archived]

    C -->|revival PR<br/>restores green CI| B

    G -.->|deprecation shim<br/>one release cycle| B

    classDef terminal fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#000
    classDef archived fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#000
    classDef active   fill:#cce5ff,stroke:#0066cc,stroke-width:2px,color:#000
    classDef start    fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#000

    class A start
    class B active
    class C archived
    class G terminal

Loading

Reading the diagram:

• Solid arrows are state transitions a subpackage actually goes through.
• Dashed arrow is the temporary back-compat shim that lets users migrate their imports after a graduation — it isn't really another life as a contribs subpackage, just a courtesy re-export that gets removed after one release cycle.
• "Graduated to core mellea" is the success terminal state. "Archived" is the failure-mode terminal state, but it's recoverable: a revival PR moves the subpackage back to Active.
• The structure (Section 2) is what makes both terminal states cheap — graduation because the file already lives at the right path, archival because the subpackage was never load-bearing for anyone else's CI or imports.

6. What's Out of Scope

• Cookiecutter mechanics, CI workflow YAML, migration-PR breakdown. All in the full RFC (feat-mellea-contribs-restructure.md).
• GPU-heavy nightly testing of contribs against real models. Real e2e and qualitative coverage requires GPUs and credentials that the v1 hermetic CI smoke intentionally avoids. TBD; designed separately once the right team owns it.
• A graduation policy. Per-subpackage, future RFCs.
• Bringing contribs into the core repo's git tree. Settled — contribs stays an independent repo.
• API stability for contribs subpackages. They are 0.x; breaking changes between minors are fine and expected.

7. The Decision This RFC Is Asking For

Three commitments:

1. Contribs subpackages mirror core's internal layout going forward; existing six get migrated to the mirror over ~one release cycle.
2. Graduation into core is a documented success outcome for contribs subpackages, structurally cheap by construction.
3. Eviction (archive-without-delete) is the documented exit path for unmaintained subpackages.

If these three land, the implementation work in the full RFC follows as plumbing. If any of them is wrong, the full RFC's plumbing is solving the wrong problem.

[psschwei]

I'm on board with the general plan

[ajbozarth]

I've re-read this a couple times and I'm a big fan of the overall pitch, but I have reservations about the mirroring of mellea's structure. I'm having trouble putting it into words but it feels like it's unnecessary complex compared to each contrib being in their own dirs. Perhaps enforcing the dir structure per contrib rather than combining them would work?

[avinash2692]

Ah, I think I might need to clarify in the RFC. I meant to convey that I wanted to enforce the dir structure for each contrib. So even if you’re only contributing , say a backend, you’ll still have all the other folders from the main repo mirrored using a cookiecutter template. This should make both the call signature more I intuitive and graduating more easy.

[ajbozarth]

example paths like this was what confused me:

mellea_contribs/stdlib/sampling_algos/my_algo.py

In actuality it would be (using the crewai contrib path):

mellea_contribs/crewai_backend/src/mellea_crewai/stdlib/sampling_algos/my_algo.py

[jakelorocco]

I second this. As long as we still have clear subpackage folders, I am okay with this change.

[nrfulton]

Graduation into core is a documented success outcome for contribs subpackages, structurally cheap by construction.

I'd back off of this framing.

The success path for something in mellea-contribs is that it's heavily used from mellea-contribs.

The primary motivation for mirroring stdlib structure is that it makes things easier to find and use. E.g., my-thing/sampling/my-algo instead of my-thing/blah-de-blah/my-algo.

We shouldn't frame inclusion in generative-computing/mellea as "more successful" than a contribution that isn't included.

[nrfulton]

Per-subpackage installability. Each subpackage is its own PyPI distribution under a meta-package's extras (uv add "mellea-contribs[stdlib.frameworks.dspy]"), so users pull only what they need and heavy dependencies don't leak across subpackages.

I think we want this to be more like mellea-contribs/dspy, right? Also, that's not what stdlib.frameworks is for (although the thing it is for we haven't done and maybe won't do).

[nrfulton]

Problem statement:

1. We want the standard "batteries included" installation of Mellea is:

uv pip install mellea[all] mellea-contribs[all]

This one-liner gets you all the toys and is the "how to get started" install instruction.

2. We want an OWNERS and auto-eviction mechanism, so that the responsibility for maintaining the firehose of generated code stays with the person generating the code rather than sitting with us. That's why we don't want to do mellea/experimental.

The graduation thing isn't false but is mostly a red herring.