From 3fea3322841ed0270fc830b8f6c7596c8bab0971 Mon Sep 17 00:00:00 2001 From: Alex Bozarth Date: Tue, 27 Jan 2026 15:20:08 -0600 Subject: [PATCH 1/4] docs: create contributing doc moves development and contributing documentation into a standard CONTRIBUTING.md and update current docs to reference it Also includes fixes for incorrect test commands and dir structure Signed-off-by: Alex Bozarth --- AGENTS.md | 20 ++- CONTRIBUTING.md | 380 ++++++++++++++++++++++++++++++++++++++++ README.md | 101 ++--------- docs/AGENTS_TEMPLATE.md | 4 +- docs/tutorial.md | 25 +-- 5 files changed, 414 insertions(+), 116 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md index b7b2950d..53cae257 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,20 +11,26 @@ AGENTS.md — Instructions for AI coding assistants (Claude, Cursor, Copilot, Co pre-commit install # Required: install git hooks uv sync --all-extras --all-groups # Install all deps (required for tests) ollama serve # Start Ollama (required for most tests) -uv run pytest -m "not qualitative" # Skips LLM quality tests (~2 min) -uv run pytest # Full suite (includes LLM quality tests) -uv run ruff format . && uv run ruff check . # Lint & format +uv run pytest test/ -m "not qualitative" # Fast: tests only, skip quality checks (~2 min) +uv run pytest # Full suite (tests + examples + quality checks) +uv run ruff format . # Format code +uv run ruff check . # Lint code +uv run mypy . # Type check ``` **Branches**: `feat/topic`, `fix/issue-id`, `docs/topic` ## 2. Directory Structure | Path | Contents | |------|----------| -| `mellea/stdlib` | Core: Sessions, Genslots, Requirements, Sampling, Context | -| `mellea/backends` | Providers: HF, OpenAI, Ollama, Watsonx, LiteLLM | -| `mellea/helpers` | Utilities, logging, model ID tables | +| `mellea/core/` | Core abstractions: Backend, Base, Formatter, Requirement, Sampling | +| `mellea/stdlib/` | Standard library: Sessions, Components, Context | +| `mellea/backends/` | Providers: HF, OpenAI, Ollama, Watsonx, LiteLLM | +| `mellea/formatters/` | Output formatters for different types | +| `mellea/templates/` | Jinja2 templates | +| `mellea/helpers/` | Utilities, logging, model ID tables | | `cli/` | CLI commands (`m serve`, `m alora`, `m decompose`, `m eval`) | | `test/` | All tests (run from repo root) | +| `docs/examples/` | Example code (run as tests via pytest) | | `scratchpad/` | Experiments (git-ignored) | ## 3. Test Markers @@ -57,7 +63,7 @@ Pre-commit runs: ruff, mypy, uv-lock, codespell | Ollama refused | Run `ollama serve` | ## 8. Self-Review (before notifying user) -1. `uv run pytest -m "not qualitative"` passes? +1. `uv run pytest test/ -m "not qualitative"` passes? 2. `ruff format` and `ruff check` clean? 3. New functions typed with concise docstrings? 4. Unit tests added for new functionality? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..727b18ab --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,380 @@ +# Contributing to Mellea + +Thank you for your interest in contributing to Mellea! This guide will help you [get started](#getting-started) with developing and contributing to the project. + +## Contribution Pathways + +There are several ways to contribute to Mellea: + +### 1. Contributing to This Repository +Contribute to the Mellea core, standard library, or fix bugs. This includes: +- Core features and bug fixes +- Standard library components (Requirements, Components, Sampling Strategies) +- Backend improvements and integrations +- Documentation and examples +- Tests and CI/CD improvements + +**Process:** +1. **Open an issue** describing the bug or feature +2. **Wait for triage** from the core team +3. **Fork and follow the setup instructions** below +4. **Make your changes** following our coding standards +5. **Open a PR** and follow the automated workflow + +### 2. Applications & Libraries +Build tools and applications using Mellea. These can be hosted in your own repository. For observability, use a `mellea-` prefix. + +**Examples:** +- `github.com/my-company/mellea-legal-utils` +- `github.com/my-username/mellea-swe-agent` + +### 3. Community Components +Contribute experimental or specialized components to [mellea-contribs](https://github.com/generative-computing/mellea-contribs). + +**Note:** For general-purpose Components, Requirements, or Sampling Strategies, please **open an issue** first to discuss whether they should go in the standard library (this repository) or mellea-contribs. + +## Getting Started + +### Prerequisites + +- Python 3.10 or higher (3.13+ requires [Rust compiler](https://www.rust-lang.org/tools/install) for outlines) +- [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or conda/mamba +- [Ollama](https://ollama.com/) (for local testing) + +### Installation with `uv` (Recommended) + +1. **Fork and clone the repository:** + ```bash + git clone ssh://git@github.com//mellea.git + cd mellea/ + ``` + +2. **Setup virtual environment:** + ```bash + uv venv .venv + source .venv/bin/activate # On Windows: .venv\Scripts\activate + ``` + +3. **Install with all dependencies:** + ```bash + uv sync --all-extras --all-groups + ``` + + Or for minimal development setup: + ```bash + uv pip install -e ".[all]" --group dev --group notebook --group docs + ``` + +4. **Install pre-commit hooks (Required):** + ```bash + pre-commit install + ``` + +### Installation with `conda`/`mamba` + +1. **Fork and clone the repository:** + ```bash + git clone ssh://git@github.com//mellea.git + cd mellea/ + ``` + +2. **Run the installation script:** + ```bash + conda/install.sh + ``` + +This script handles environment setup, dependency installation, and pre-commit hook installation. + +### Verify Installation + +```bash +# Start Ollama (required for most tests) +ollama serve + +# Run fast tests (tests only, skip quality checks) +uv run pytest test/ -m "not qualitative" +``` + +## Directory Structure + +| Path | Contents | +|------|----------| +| `mellea/core` | Core abstractions: Backend, Base, Formatter, Requirement, Sampling | +| `mellea/stdlib` | Standard library: Session, Context, Components, Requirements, Sampling, Intrinsics, Tools | +| `mellea/backends` | Backend providers: HF, OpenAI, Ollama, Watsonx, LiteLLM | +| `mellea/formatters` | Output formatters and parsers | +| `mellea/helpers` | Utilities, logging, model ID tables | +| `mellea/templates` | Jinja2 templates for prompts | +| `cli/` | CLI commands (`m serve`, `m alora`, `m decompose`, `m eval`) | +| `test/` | All tests (run from repo root) | +| `docs/` | Documentation, examples, tutorials | + +## Coding Standards + +### Type Annotations + +**Required** on all core functions: + +```python +def process_text(text: str, max_length: int = 100) -> str: + """Process text with maximum length.""" + return text[:max_length] +``` + +### Docstrings + +**Docstrings are prompts** - the LLM reads them, so be specific. + +Use **Google-style docstrings**: + +```python +def extract_entities(text: str, entity_types: list[str]) -> dict[str, list[str]]: + """Extract named entities from text. + + Args: + text: The input text to analyze. + entity_types: List of entity types to extract (e.g., ["PERSON", "ORG"]). + + Returns: + Dictionary mapping entity types to lists of extracted entities. + + Example: + >>> extract_entities("Alice works at IBM", ["PERSON", "ORG"]) + {"PERSON": ["Alice"], "ORG": ["IBM"]} + """ + ... +``` + +### Code Style + +- **Ruff** for linting and formatting +- Use `...` in `@generative` function bodies +- **Prefer primitives over classes** for simplicity +- Keep functions focused and single-purpose +- Avoid over-engineering + +### Formatting and Linting + +```bash +# Format code +uv run ruff format . + +# Lint code +uv run ruff check . + +# Fix auto-fixable issues +uv run ruff check --fix . + +# Type check +uv run mypy . +``` + +## Development Workflow + +### Branch Naming + +Use descriptive branch names with prefixes: +- `feat/topic` - New features +- `fix/issue-id` - Bug fixes +- `docs/topic` - Documentation updates +- `test/topic` - Test additions/fixes +- `refactor/topic` - Code refactoring + +### Commit Messages + +Follow [Angular commit format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit): + +``` +: + + + +