Mellea Contribs

May 20, 2026 · View on GitHub

Mellea Contribs

mellea-contribs is an incubation point for contributions to the Mellea ecosystem. This is the home for experimental and specialized extensions that are not yet part of the standard library. It is the right place for:

Domain-specific Components (legal, medical, code review, etc.)
Experimental Sampling Strategies under active research
Backend integrations for niche or self-hosted providers

This repo contains multiple framework integrations and supporting libraries for the Mellea generative programming framework. Each subpackage is independently testable but shares common dependencies through mellea-integration-core. The CI pipeline automatically discovers changes and runs appropriate tests with Python 3.11-3.13, Ollama support for backends, and configurable timeouts per package.

Mellea Contribs Overview

This document explains the organization of the mellea-contribs directory and the requirements for running CI/CD.

Resource List

Resource	Description
mellea-integration-core/	Core abstractions for framework integrations
crewai_backend/	CrewAI integration with Mellea
dspy_backend/	DSPy integration with Mellea
langchain_backend/	LangChain integration with Mellea
tools_package/	Generative tools and utilities library
reqlib_package/	Requirements library for validation

Subpackage Descriptions

Mellea Integration Core

Purpose: Core abstractions and utilities for building clean, maintainable integrations between Mellea and various AI frameworks
Key Features:
- Base integration class with common patterns
- Message conversion utilities (convert between framework and Mellea formats)
- Tool conversion and handling
- Requirements and strategy support
- Async/sync generation patterns
Dependencies: mellea>=0.3.2
Python Version: ≥3.11
CI Requirements: No Ollama needed (skip_ollama=true)
Timeout: 30 minutes

CrewAI Backend

Purpose: Enables CrewAI agents to use Mellea's generative programming capabilities
Key Features:
- CrewAI agent integration with Mellea
- Message and tool conversion for CrewAI format
- Inherits from MelleaIntegrationBase
Dependencies: mellea>=0.3.0, crewai>=0.1.0, mellea-integration-core
Python Version: ≥3.11
CI Requirements: Ollama support enabled
Timeout: 90 minutes (extended due to complex integration tests)

DSPy Backend

Purpose: DSPy integration enabling structured prompting with generative programming
Key Features:
- DSPy module integration with Mellea
- Structured prompting capabilities
- Inherits from MelleaIntegrationBase
Dependencies: dspy>=3.1.3, mellea>=0.3.2, mellea-integration-core
Python Version: ≥3.11
CI Requirements: Ollama support enabled
Timeout: 30 minutes

Langchain Backend

Purpose: LangChain integration for using Mellea within LangChain applications
Key Features:
- LangChain language model integration with Mellea
- Tool calling support
- Inherits from MelleaIntegrationBase
Dependencies: langchain, mellea>=0.3.x, mellea-integration-core
Python Version: ≥3.11
CI Requirements: Ollama support enabled
Timeout: 30 minutes

Tools Package

Purpose: Incubating generative programming tools and utilities
Key Features:
- Various tools for generative programming
- Robustness testing capabilities
- Requirements validation and sampling strategies
Dependencies: Multiple (see pyproject.toml for details)
Python Version: ≥3.11
CI Requirements: No Ollama needed (skip_ollama=true)
Timeout: 30 minutes

Requirements Library Package

Purpose: Requirements library for validation and constraints in generative systems
Key Features:
- Requirement specification and validation
- Integration with Mellea's validation framework
Dependencies: mellea>=0.3.x
Python Version: ≥3.11
CI Requirements: No Ollama needed (skip_ollama=true)
Timeout: 30 minutes

Tools

Robustness Testing — Test m-program consistency against semantic variations using BenchDrift

CI/CD Requirements

Architecture

The CI/CD pipeline uses a two-stage workflow:

discover-subpackages (ci.yml): Discovers which subpackages have changed
test (quality-generic.yml): Runs tests for each changed subpackage

Key Requirements

1. Environment Setup

Python Versions: Tests run on Python 3.11, 3.12, and 3.13
Package Manager: Uses uv for fast dependency management
Virtual Environment: uv sync --all-extras creates and manages the venv

2. Test Directory Structure

Each subpackage must have a test directory with the following structure:

<subpackage>/
├── tests/          # OR
├── test/           # OR
└── test/integration/  # (optional, ignored in CI)

The CI pipeline looks for either tests/ or test/ directory. Integration tests in test/integration/ are skipped.

3. Dependency Management

Package Format: Each subpackage is a Python package with pyproject.toml
Build System:
- crewai_backend, dspy_backend, langchain_backend, mellea-integration-core: Use hatchling
- tools_package: Uses pdm-backend
- reqlib_package: Uses appropriate build backend
Local Path Dependencies: Subpackages can reference each other via path-based dependencies in pyproject.toml:
```
[tool.uv.sources]
mellea-integration-core = { path = "../mellea-integration-core" }
```

4. Ollama Setup (for backends)

Some subpackages require Ollama for testing:

Skip Ollama: mellea-integration-core, reqlib_package, tools_package
Include Ollama: crewai_backend, dspy_backend, langchain_backend

When Ollama is enabled:

Ollama service is installed and started
Model granite4:micro is pulled for testing

5. Test Execution

cd <subpackage>
uv sync --all-extras          # Install all dependencies including dev extras
uv run -- pytest -v tests/    # Run tests (or test/ if tests/ doesn't exist)

6. Pytest Configuration

Each subpackage's pyproject.toml should include pytest markers for test organization:

[tool.pytest.ini_options]
testpaths = ["tests"]
markers = [
    "integration: marks tests as requiring integration setup",
    "llm: marks tests making LLM calls",
    "slow: marks slow tests",
]
asyncio_mode = "auto"

7. Code Quality Tools

Standard tools configured in each subpackage:

Ruff: Linting and formatting (configured in pyproject.toml)
MyPy: Type checking (configured in pyproject.toml)
Pytest: Testing framework with coverage support

CI Trigger Conditions

The CI pipeline triggers when:

Push to main: Changes detected in mellea_contribs/ directory
Pull Request: Changes detected in mellea_contribs/ directory
Workflow Changes: Any change to .github/workflows/ci.yml or .github/workflows/quality-generic.yml

CI Discovery Logic

The discovery step:

Gets changed files compared to base ref (PR base or HEAD~1 for push)
Extracts unique subpackage directories that changed
If workflow files changed, tests ALL subpackages
Creates a test matrix with custom settings per subpackage:
- skip_ollama: Whether to skip Ollama installation
- timeout_minutes: Custom timeout (default 30, extended to 90 for crewai_backend)

CI Parallelization

Max Parallel Jobs: 6 concurrent subpackages
Python Versions: Tests run sequentially per Python version (max-parallel: 1)
Concurrency Groups: Uses PR number or branch name for cancellation of in-progress jobs

Setting Up a New Subpackage for CI

To add a new subpackage to the CI pipeline:

1. Create Package Structure

new_backend/
├── pyproject.toml
├── README.md
├── src/
│   └── mellea_<framework>/
│       ├── __init__.py
│       └── integration.py
└── tests/  # or test/
    ├── __init__.py
    ├── test_integration.py
    └── integration/
        └── test_advanced.py

2. Configure pyproject.toml

[project]
name = "mellea-<framework>"
version = "0.1.0"
description = "<Framework> integration for Mellea"
requires-python = ">=3.11"

dependencies = [
    "mellea>=0.3.0",
    "mellea-integration-core",
    "<framework>",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "pytest-asyncio>=0.21.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/mellea_<framework>"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

[tool.uv.sources]
mellea-integration-core = { path = "../mellea-integration-core" }

3. Configure CI Settings

Update .github/workflows/ci.yml discover-subpackages step to add custom settings if needed:

skip_ollama: (if test("<new_backend>") then true else false end),
timeout_minutes: (if test("<new_backend>") then 60 else 30 end)

4. Verify Locally

cd new_backend
uv sync --all-extras
uv run -- pytest -v tests/

Troubleshooting

Common CI Failures

"No tests/ or test/ directory found"
- Solution: Create tests/ or test/ directory with test files
Import errors for mellea-integration-core
- Solution: Ensure pyproject.toml has correct path reference:
```
[tool.uv.sources]
mellea-integration-core = { path = "../mellea-integration-core" }
```
Ollama timeout issues
- Solution: CI has 30-90 minute timeout, may need to skip heavy ollama tests locally
Python version incompatibility
- Solution: Verify requires-python in pyproject.toml matches supported versions
Missing dev dependencies
- Solution: Add pytest and other test dependencies to [project.optional-dependencies] dev

Local Development

Install All Subpackages Locally

cd mellea_contribs/mellea-integration-core
pip install -e ".[dev]"

cd ../crewai_backend
pip install -e ".[dev]"

# ... repeat for other subpackages

Run Tests Locally

cd <subpackage>
uv sync --all-extras
uv run -- pytest -v tests/

Code Quality Checks

# Lint
ruff check src/

# Format
ruff format src/

# Type check
mypy src/