diff --git a/AGENTS.md b/AGENTS.md index 748e7b18..60384a7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,19 +23,25 @@ ollama serve # Start Ollama (required for most tests) uv run pytest # Default: qualitative tests, skip slow tests uv run pytest -m "not qualitative" # Fast tests only (~2 min) uv run pytest -m slow # Run only slow tests (>5 min) -uv run pytest # Run ALL tests including slow -uv run ruff format . && uv run ruff check . # Lint & format +uv run pytest --co -q # Run ALL tests including slow (bypass config) +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 @@ -101,7 +107,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..579fccf1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,395 @@ +# 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:** See the [Pull Request Process](#pull-request-process) section below for detailed steps. + +### 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. + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. Please report unacceptable behavior +to melleaadmin@ibm.com. + +## 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/download) (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 (skip qualitative tests, ~2 min) +uv run pytest -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](https://google.github.io/styleguide/pyguide.html#381-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 + +### Commit Messages + +Follow [Angular commit format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit): + +``` +: + + + +