diff --git a/.github/workflows/development.yml b/.github/workflows/development.yml index f18929dd..3450c758 100644 --- a/.github/workflows/development.yml +++ b/.github/workflows/development.yml @@ -37,11 +37,27 @@ jobs: - name: Run quality checks run: tox -e types + link-checks: + runs-on: ubuntu-latest + strategy: + matrix: + python: ["3.9"] + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - name: Install dependencies + run: pip install tox + - name: Run link checks + run: tox -e links + precommit-checks: runs-on: ubuntu-latest strategy: matrix: - python: ["3.9", "3.13"] + python: ["3.9"] steps: - uses: actions/checkout@v4 - name: Set up Python diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 6c2e4988..fcd0a515 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -38,11 +38,27 @@ jobs: - name: Run quality checks run: tox -e types + link-checks: + runs-on: ubuntu-latest + strategy: + matrix: + python: ["3.9"] + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - name: Install dependencies + run: pip install tox + - name: Run link checks + run: tox -e links + precommit-checks: runs-on: ubuntu-latest strategy: matrix: - python: ["3.9", "3.10", "3.11", "3.12", "3.13"] + python: ["3.9"] steps: - uses: actions/checkout@v4 - name: Set up Python diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 020cc2bd..2185d4b6 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -5,6 +5,22 @@ on: - cron: '0 0 * * *' # Runs at midnight every night jobs: + link-checks: + runs-on: ubuntu-latest + strategy: + matrix: + python: ["3.9"] + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - name: Install dependencies + run: pip install tox + - name: Run link checks + run: tox -e links + unit-tests: runs-on: ubuntu-latest strategy: diff --git a/.github/workflows/release-candidate.yml b/.github/workflows/release-candidate.yml index 2fc4e72b..e5a3ceed 100644 --- a/.github/workflows/release-candidate.yml +++ b/.github/workflows/release-candidate.yml @@ -6,6 +6,22 @@ on: - 'release/*' jobs: + link-checks: + runs-on: ubuntu-latest + strategy: + matrix: + python: ["3.9"] + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - name: Install dependencies + run: pip install tox + - name: Run link checks + run: tox -e links + unit-tests: runs-on: ubuntu-latest strategy: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c3b6a639..5499b525 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -51,6 +51,22 @@ jobs: password: ${{ secrets.PYPI_PUBLIC_AUTH }} whl: $(find dist -name '*.tar.gz') + link-checks: + runs-on: ubuntu-latest + strategy: + matrix: + python: ["3.9"] + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - name: Install dependencies + run: pip install tox + - name: Run link checks + run: tox -e links + unit-tests: runs-on: ubuntu-latest strategy: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index b161612e..5708a3fc 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,47 +1,77 @@ -# Community Code of Conduct +# GuideLLM Code of Conduct ## Our Pledge -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. ## Our Standards -Examples of behavior that contributes to creating a positive environment include: +Examples of behavior that contributes to a positive environment for our community include: -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community -Examples of unacceptable behavior by participants include: +Examples of unacceptable behavior include: -- The use of sexualized language or imagery and unwelcome sexual attention or advances -- Trolling, insulting/derogatory comments, and personal or political attacks +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks - Public or private harassment -- Publishing others' private information, such as a physical or electronic address, without explicit permission +- Publishing others’ private information, such as a physical or email address, without their explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting -## Our Responsibilities +## Enforcement Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. -Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope -This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team using the [Neural Magic Contact Us Form](https://neuralmagic.com/contact). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement through GitHub, Slack, or Email. All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. +**Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. -For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq +Community Impact Guidelines were inspired by [Mozilla’s code of conduct enforcement ladder](https://github.com/mozilla/diversity). -[homepage]: https://www.contributor-covenant.org +For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb58c5f0..5d3369b0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,68 +1,121 @@ # Contributing to GuideLLM -If you’re reading this, hopefully we have piqued your interest to take the next step. Join us and help make GuideLLM even better! As a contributor, here are some community guidelines we would like you to follow: +Thank you for considering contributing to GuideLLM! We welcome contributions from the community to help improve and grow this project. This document outlines the process and guidelines for contributing. -- [Code of Conduct](#code-of-conduct) -- [Ways to Contribute](#ways-to-contribute) -- [Bugs and Feature Requests](#bugs-and-feature-requests) -- [Question or Problem](#question-or-problem) -- [Developing GuideLLM](DEVELOPING.md) +## How Can You Contribute? -## Code of Conduct +There are many ways to contribute to GuideLLM: -Help us keep the software inclusive. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) in order to promote an environment that is friendly, fair, respectful, and safe. We want to inspire collaboration, innovation, and fun! +- **Reporting Bugs**: If you encounter a bug, please let us know by creating an issue. +- **Suggesting Features**: Have an idea for a new feature? Open an issue to discuss it. +- **Improving Documentation**: Help us improve our documentation by submitting pull requests. +- **Writing Code**: Contribute code to fix bugs, add features, or improve performance. +- **Reviewing Pull Requests**: Provide feedback on open pull requests to help maintain code quality. -## Ways to Contribute +## Getting Started -Whether you’re a newbie, dabbler, or expert, we appreciate you jumping in. +### Prerequisites -### Contributing Code +Before contributing, ensure you have the following installed: -- Make pull requests for addressing bugs, open issues, and documentation -- Neural Magic as the maintainer will do reviews and final merge +- Python 3.9 or higher +- pip (Python package manager) +- Tox +- Git -### Reporting In +### Setting Up the Repository -- See something, say something: bugs, documentation -- Propose new feature requests to Neural Magic +You can either clone the repository directly or fork it if you plan to contribute changes back: -### Helping Others +#### Option 1: Cloning the Repository -- Answer open discussion topics -- Spread the word about GuideLLM -- Teach and empower others. This is the way! +1. Clone the repository to your local machine: -## Bugs and Feature Requests + ```bash + git clone https://github.com/neuralmagic/guidellm.git + cd guidellm + ``` -Please search through existing issues and requests first to avoid duplicates. Neural Magic will work with you further to take next steps. +#### Option 2: Forking the Repository -- Go to: [GitHub Issues](https://github.com/neuralmagic/guidellm/issues) +1. Fork the repository by clicking the "Fork" button on the repository's GitHub page. -For bugs, include: +2. Clone your forked repository to your local machine: -- brief summary -- OS/Environment details -- steps to reproduce (s.t.r.) -- code snippets, screenshots/casts, log content, sample models -- add the GitHub label "bug" to your post + ```bash + git clone https://github.com//guidellm.git + cd guidellm + ``` -For feature requests, include: +For detailed instructions on setting up your development environment, please refer to the [DEVELOPING.md](https://github.com/neuralmagic/speculators/blob/main/DEVELOPING.md) file. It includes step-by-step guidance on: -- problem you’re trying to solve -- community benefits -- other relevant details to support your proposal -- add the GitHub label "enhancement" to your post +- Installing dependencies +- Running tests +- Using Tox for various tasks -For documentation edits, include: +## Code Style and Guidelines -- current state, proposed state -- if applicable, screenshots/casts -- add the GitHub label "documentation" to your post +We follow strict coding standards to ensure code quality and maintainability. Please adhere to the following guidelines: -## Question or Problem +- **Code Style**: Use [Black](https://black.readthedocs.io/en/stable/) for code formatting and [Ruff](https://github.com/charliermarsh/ruff) for linting. +- **Type Checking**: Use [Mypy](http://mypy-lang.org/) for type checking. +- **Testing**: Write unit tests for new features and bug fixes. Use [pytest](https://docs.pytest.org/) for testing. +- **Documentation**: Update documentation for any changes to the codebase. -Sign up or log in to our [**Neural Magic Community Slack**](https://neuralmagic.com/community/). We are growing the community member by member and happy to see you there. Don’t forget to search through existing discussions to avoid duplication! Thanks! +To check code quality locally, use the following Tox environment: -## Developing GuideLLM +```bash +tox -e quality +``` -Made it this far? Review [Developing GuideLLM](DEVELOPING.md) to get started. +To automatically fix style issues, use: + +```bash +tox -e style +``` + +To run type checks, use: + +```bash +tox -e types +``` + +## Submitting Changes + +1. **Create a Branch**: Create a new branch for your changes: + + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make Changes**: Commit your changes with clear and descriptive commit messages. + +3. **Run Tests and Quality Checks**: Before submitting your changes, ensure all tests pass and code quality checks are satisfied: + + ```bash + tox + ``` + +4. **Push Changes**: Push your branch to your forked repository (if you forked): + + ```bash + git push origin feature/your-feature-name + ``` + +5. **Open a Pull Request**: Go to the original repository and open a pull request. Provide a clear description of your changes and link any related issues. + +## Reporting Issues + +If you encounter a bug or have a feature request, please open an issue on GitHub. Include as much detail as possible, such as: + +- Steps to reproduce the issue +- Expected and actual behavior +- Environment details (OS, Python version, etc.) + +## Community Standards + +We are committed to fostering a welcoming and inclusive community. Please read and adhere to our [Code of Conduct](https://github.com/neuralmagic/speculators/blob/main/CODE_OF_CONDUCT.md). + +## License + +By contributing to Speculators, you agree that your contributions will be licensed under the [Apache License 2.0](https://github.com/neuralmagic/speculators/blob/main/LICENSE). diff --git a/DEVELOPING.md b/DEVELOPING.md index e94f6583..d91dc93d 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -1,259 +1,187 @@ -# Developer Documentation +# Developing for Speculators -## Introduction +Thank you for your interest in contributing to Speculators! This document provides detailed instructions for setting up your development environment, implementing changes, and adhering to the project's best practices. Your contributions help us grow and improve this project. -Welcome to the developer documentation for `guidellm`, a guidance platform for evaluating large language model deployments. This document aims to provide developers with all the necessary information to contribute to the project effectively. - -## Getting Started +## Setting Up Your Development Environment ### Prerequisites Before you begin, ensure you have the following installed: -- Python 3.8 or higher -- `pip` (Python package installer) -- `git` (version control system) +- Python 3.9 or higher +- pip (Python package manager) +- Tox +- Git -### Installation +### Cloning the Repository -1. Clone the repository: +1. Clone the repository to your local machine: ```bash git clone https://github.com/neuralmagic/guidellm.git cd guidellm ``` -2. Install the required dependencies: +2. (Optional) If you plan to contribute changes back, fork the repository and clone your fork instead: ```bash - pip install -e .[dev] + git clone https://github.com//guidellm.git + cd guidellm ``` -## Project Structure - -The project follows a standard Python project structure: - -```plaintext -guidellm/ -├── src/ -│ └── guidellm/ -├── tests/ -│ ├── unit/ -│ ├── integration/ -│ └── e2e/ -├── pyproject.toml -├── tox.ini -└── README.md -``` +### Installing Dependencies -- **src/guidellm/**: Main source code for the project. -- **tests/**: Test cases categorized into unit, integration, and end-to-end tests. +To install the required dependencies for the package and development, run: -## Development Environment Setup +```bash +pip install -e ./[dev] +``` -To set up your development environment, follow these steps: +The `-e` flag installs the package in editable mode, allowing you to make changes to the code without reinstalling it. The `[dev]` part installs additional dependencies needed for development, such as testing and linting tools. -1. Install pre-commit hooks: +## Implementing Changes - ```bash - pre-commit install - ``` +### Writing Code -2. Ensure all dependencies are installed: +1. **Create a Branch**: Create a new branch for your changes: ```bash - pip install -e .[dev] + git checkout -b feature/your-feature-name ``` -## Code Quality and Style Guidelines +2. **Make Changes**: Implement your changes in the appropriate files. Ensure that all public functions and classes have clear and concise docstrings. -We use several tools to maintain code quality and consistency: +3. **Update Documentation**: Update or add documentation to reflect your changes. This includes updating README files, docstrings, and any relevant guides. -### Ruff +## Running Quality, Style, and Type Checks -Ruff is used for linting and formatting checks. +We use Tox to simplify running various tasks in isolated environments. Tox standardizes environments to ensure consistency across local development, CI/CD pipelines, and releases. This guarantees that the code behaves the same regardless of where it is executed. -- Configuration is in `pyproject.toml`. -- To run Ruff: - ```bash - ruff check src tests - ``` +Additionally, to ensure consistency and quality of the codebase, we use [ruff](https://github.com/astral-sh/ruff) for linting and styling, [isort](https://pycqa.github.io/isort/) for sorting imports, [mypy](https://github.com/python/mypy) for type checking, and [mdformat](https://github.com/hukkin/mdformat) for formatting Markdown files. -### Isort - -Isort is used for sorting imports. - -- Configuration is in `pyproject.toml`. -- To sort imports: - ```bash - isort src tests - ``` - -### Flake8 - -Flake8 is used for linting. - -- Configuration is in `tox.ini`. -- To run Flake8: - ```bash - flake8 src tests --max-line-length 88 - ``` - -### MyPy - -MyPy is used for type checking. - -- Configuration is in `pyproject.toml`. -- To run MyPy: - ```bash - mypy src/guidellm - ``` - -## Testing - -We use `pytest` for running tests. - -### Running All Tests - -To run all tests: - -```bash -tox -``` +### Code Quality and Style -Additionally, all tests are marked with smoke, sanity, or regression tags for better organization. To run tests with a specific tag, use the `-m` flag: +To check code quality, including linting and formatting: ```bash -tox -- -m "smoke or sanity" +tox -e quality ``` -### Running Unit Tests - -The unit tests are located in the `tests/unit` directory. To run the unit tests, use the following command: +To automatically fix style issues: ```bash -tox -e test-unit +tox -e style ``` -### Running Integration Tests +### Type Checking -The integration tests are located in the `tests/integration` directory. To run the integration tests, use the following command: +To ensure type safety using Mypy: ```bash -tox -e test-integration +tox -e types ``` -### Running End-to-End Tests +### Link Checking -The end-to-end tests are located in the `tests/e2e` directory. To run the end-to-end tests, use the following command: +To ensure valid links added to the documentation / Markdown files: ```bash -tox -e test-e2e +tox -e links ``` -## Formatting, Linting, and Type Checking +### Automating Quality Checks with Pre-Commit Hooks (Optional) -### Running Quality Checks (Linting) +We use [pre-commit](https://pre-commit.com/) to automate quality checks before commits. Pre-commit hooks run checks like linting, formatting, and type checking, ensuring that only high-quality code is committed. -To run quality checks (ruff, isort, flake8, mypy), use the following command: +To install the pre-commit hooks, run: ```bash -tox -e quality +pre-commit install ``` -### Running Auto Formatting and Validation - -To run formatting checks and fixes (ruff, isort, flake8) for automatic formatting, use the following command: +This will set up the hooks to run automatically before each commit. To manually run the hooks on all files, use: ```bash -tox -e style +pre-commit run --all-files ``` -### Type Checking +## Running Tests -To run type checks (MyPy), use the following command: +For testing, we use [pytest](https://docs.pytest.org/) as our testing framework. We have different test suites for unit tests, integration tests, and end-to-end tests. To run the tests, you can use Tox, which will automatically create isolated environments for each test suite. Tox will also ensure that the tests are run in a consistent environment, regardless of where they are executed. -```bash -tox -e types -``` - -## Building the Project - -To build the project, use the following command: - -```bash -tox -e build -``` - -## Cleaning Up +### Running All Tests -To clean up build, dist, and cache files, use the following command: +To run all tests: ```bash -tox -e clean +tox ``` -## Continuous Integration/Continuous Deployment (CI/CD) +### Running Specific Tests -Our CI/CD pipeline is configured using GitHub Actions. The configuration files are located in the .github/workflows/ directory. You can run the CI/CD pipeline locally using act or similar tools. +- Unit tests (focused on individual components with mocking): -## Contributing + ```bash + tox -e test-unit + ``` -Please refer to the CONTRIBUTING.md file for guidelines on how to contribute to the project. +- Integration tests (focused on interactions between components ideally without mocking): -## Maintaining + ```bash + tox -e test-integration + ``` -Please refer to the MAINTAINERS file for maintenance guidelines and contact information. +- End-to-end tests (focused on the entire system and user interfaces): -## Project configuration + ```bash + tox -e test-e2e + ``` -The project configuartion is powered by _[`🔗 pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)_ +### Running Tests with Coverage -The project configuration entry point is represented by lazy-loaded `settigns` singleton object ( `src/config/__init__` ) +To ensure your changes are covered by tests, run: -The project is fully configurable with environment variables. With that configuration set you can load parameters to `LoggingSettings()` by using environment variables. Just run `export GUIDELLM__LOGGING__DISABLED=true` or `export GUIDELLM__LOGGING__NESTED=another_value` respectfully. The nesting delimiter is `__`. +```bash +tox -e test-unit -- --cov=speculators --cov-report=html +``` -### Environment variables +Review the coverage report to confirm that your new code is adequately tested. -| Name | Default value | Description | -| ------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `GUIDELLM__LOGGING__DISABLED` | `False` | Determines whether logger for the `guidellm` package is disabled or not | -| `GUIDELLM__LOGGING__LOG_LEVEL` | `INFO` | The level of `guidellm` package logging | -| `GUIDELLM__LOGGING__LOG_FILE` | `guidellm.log` | The name of a log file | -| `GUIDELLM__OPENAI__BASE_URL` | `http://localhost:8080` | The address to the **OpenAI-compatible** server.

OpenAI live base url is `https://api.openai.com/v1` | -| `GUIDELLM__OPENAI__API_KEY` | `invalid` | Corresponds to the **OpenAI-compatible** server API key.

If you look for the live key - check [this link](https://platform.openai.com/api-keys). | +## Opening a Pull Request -
+1. **Push Changes**: Push your branch to your forked repository (if you forked): -## Project configuration + ```bash + git push origin feature/your-feature-name + ``` -The project configuartion is powered by _[`🔗 pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)_ +2. **Open a Pull Request**: Go to the original repository and open a pull request. Use the following template for your pull request description: -The project configuration entrypoint is represented by lazy-loaded `settigns` singleton object ( `src/config/__init__` ) + ```markdown + # Title; ex: Add feature X to improve Y -The project is fully configurable with environment variables. All the default values and + ## Summary: -```py -class NestedIntoLogging(BaseModel): - nested: str = "default value" + Short paragraph detailing the pull request changes and reasoning in addition to any relevant context. -class LoggingSettings(BaseModel): - # ... - disabled: bool = False + ## Details: + - Detailed list of changes made in the pull request -class Settings(BaseSettings): - """The entrypoint to settings.""" + ## Test Plan: - # ... - logging: LoggingSettings = LoggingSettings() + - Detailed list of steps to test the changes made in the pull request + ## Related Issues -settings = Settings() -``` + - List of related issues or other pull requests; ex: "Fixes #1234" + ``` -With that configuration set you can load parameters to `LoggingSettings()` by using environment variables. Just run `export GUIDELLM__LOGGING__DISABLED=true` or `export GUIDELLM__LOGGING__NESTED=another_value` respectfully. The nesting delimiter is `__` +3. **Address Feedback**: Respond to any feedback from reviewers and make necessary changes. -## Contact and Support +## Additional Resources -If you need help or have any questions, please open an issue on GitHub or contact us at support@neuralmagic.com. +- [CONTRIBUTING.md](https://github.com/neuralmagic/speculators/blob/main/CONTRIBUTING.md): Guidelines for contributing to the project. +- [CODE_OF_CONDUCT.md](https://github.com/neuralmagic/speculators/blob/main/CODE_OF_CONDUCT.md): Our expectations for community behavior. +- [tox.ini](https://github.com/neuralmagic/speculators/blob/main/tox.ini): Configuration for Tox environments. +- [.pre-commit-config.yaml](https://github.com/neuralmagic/speculators/blob/main/.pre-commit-config.yaml): Configuration for pre-commit hooks. diff --git a/README.md b/README.md index 6639ebdf..a46fd411 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ Or from source code using pip: pip install git+https://github.com/neuralmagic/guidellm.git ``` -For detailed installation instructions and requirements, see the [Installation Guide](https://github.com/neuralmagic/guidellm/tree/main/docs/install.md). +For detailed installation instructions and requirements, see the [Installation Guide](https://github.com/neuralmagic/guidellm/blob/main/docs/install.md). ### Quick Start @@ -64,7 +64,7 @@ vllm serve "neuralmagic/Meta-Llama-3.1-8B-Instruct-quantized.w4a16" For more information on starting a vLLM server, see the [vLLM Documentation](https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html). -For information on starting other supported inference servers or platforms, see the [Supported Backends documentation](https://github.com/neuralmagic/guidellm/tree/main/docs/backends.md). +For information on starting other supported inference servers or platforms, see the [Supported Backends documentation](https://github.com/neuralmagic/guidellm/blob/main/docs/backends.md). #### 2. Run a GuideLLM Benchmark @@ -98,7 +98,7 @@ For more details about the metrics and definitions, please refer to the [Metrics By default, the full results, including complete statistics and request data, are saved to a file `benchmarks.json` in the current working directory. This file can be used for further analysis or reporting, and additionally can be reloaded into Python for further analysis using the `guidellm.benchmark.GenerativeBenchmarksReport` class. You can specify a different file name and extension with the `--output` argument. -For more details about the supported output file types, please take a look at the [Outputs documentation](raw.githubusercontent.com/neuralmagic/guidellm/main/docs/outputs.md). +For more details about the supported output file types, please take a look at the [Outputs documentation](https://github.com/neuralmagic/guidellm/blob/main/docs/outputs.md). #### 5. Use the Results @@ -157,16 +157,16 @@ The `guidellm benchmark` command is used to run benchmarks against a generative ### Documentation -Our comprehensive documentation offers detailed guides and resources to help you maximize the benefits of GuideLLM. Whether just getting started or looking to dive deeper into advanced topics, you can find what you need in our [documentation](https://github.com/neuralmagic/guidellm/tree/main/docs). +Our comprehensive documentation offers detailed guides and resources to help you maximize the benefits of GuideLLM. Whether just getting started or looking to dive deeper into advanced topics, you can find what you need in our [documentation](https://github.com/neuralmagic/guidellm/blob/main/docs). ### Core Docs -- [**Installation Guide**](https://github.com/neuralmagic/guidellm/tree/main/docs/install.md) - This guide provides step-by-step instructions for installing GuideLLM, including prerequisites and setup tips. -- [**Backends Guide**](https://github.com/neuralmagic/guidellm/tree/main/docs/backends.md) - A comprehensive overview of supported backends and how to set them up for use with GuideLLM. -- [**Data/Datasets Guide**](https://github.com/neuralmagic/guidellm/tree/main/docs/datasets.md) - Information on supported datasets, including how to use them for benchmarking. -- [**Metrics Guide**](https://github.com/neuralmagic/guidellm/tree/main/docs/metrics.md) - Detailed explanations of the metrics used in GuideLLM, including definitions and how to interpret them. -- [**Outputs Guide**](https://github.com/neuralmagic/guidellm/tree/main/docs/outputs.md) - Information on the different output formats supported by GuideLLM and how to use them. -- [**Architecture Overview**](https://github.com/neuralmagic/guidellm/tree/main/docs/architecture.md) - A detailed look at GuideLLM's design, components, and how they interact. +- [**Installation Guide**](https://github.com/neuralmagic/guidellm/blob/main/docs/install.md) - This guide provides step-by-step instructions for installing GuideLLM, including prerequisites and setup tips. +- [**Backends Guide**](https://github.com/neuralmagic/guidellm/blob/main/docs/backends.md) - A comprehensive overview of supported backends and how to set them up for use with GuideLLM. +- [**Data/Datasets Guide**](https://github.com/neuralmagic/guidellm/blob/main/docs/datasets.md) - Information on supported datasets, including how to use them for benchmarking. +- [**Metrics Guide**](https://github.com/neuralmagic/guidellm/blob/main/docs/metrics.md) - Detailed explanations of the metrics used in GuideLLM, including definitions and how to interpret them. +- [**Outputs Guide**](https://github.com/neuralmagic/guidellm/blob/main/docs/outputs.md) - Information on the different output formats supported by GuideLLM and how to use them. +- [**Architecture Overview**](https://github.com/neuralmagic/guidellm/blob/main/docs/architecture.md) - A detailed look at GuideLLM's design, components, and how they interact. ### Supporting External Documentation diff --git a/pyproject.toml b/pyproject.toml index 4d0c2164..a78b1fc5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -95,6 +95,9 @@ dev = [ "types-PyYAML~=6.0.1", "types-requests~=2.32.0", "types-toml", + + # link checking + "mkdocs-linkcheck~=1.0.6", ] [project.urls] diff --git a/tox.ini b/tox.ini index 201a4e4d..08fc27b9 100644 --- a/tox.ini +++ b/tox.ini @@ -61,6 +61,15 @@ commands = mypy --check-untyped-defs +[testenv:links] +description = Run link checks for root and docs markdown files +deps = + .[dev] +commands = + mkdocs-linkcheck ./ + mkdocs-linkcheck docs/ + + [testenv:build] description = Build the project deps =