slashml · pr-test1 · Sep 16, 2025 · Sep 16, 2025 · Sep 16, 2025 · Sep 16, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -12,17 +12,20 @@ We love your input! We want to make contributing to Magemaker as easy and transp
 - Discussing the current state of the code
 - Submitting a fix
 - Proposing new features
+- Improving the documentation
 - Becoming a maintainer
 
+---
+
 ## Ways to Contribute
 
 ### 1. Report Issues
 
 If you encounter any bugs or have feature requests:
 
 1. Go to our GitHub repository
-2. Click on "Issues"
-3. Click "New Issue"
+2. Click on **Issues**
+3. Click **New Issue**
 4. Choose the appropriate template (Bug Report or Feature Request)
 5. Fill out the template with as much detail as possible
 
@@ -33,36 +36,158 @@ If you encounter any bugs or have feature requests:
 ### 2. Submit Pull Requests
 
 1. Fork the repo and create your branch from `main`
-2. If you've added code that should be tested, add tests
-3. If you've changed APIs, update the documentation
-4. Ensure the test suite passes
-5. Make sure your code lints
+2. If you've added code that should be tested, add **unit and/or integration tests** (see *Testing* below)
+3. If you've changed public-facing APIs or added a new feature, update **documentation** (docs live under the `docs/` folder)
+4. Ensure the test suite passes: `pytest -q`
+5. Run the auto-formatters and linters (see *Code Style*)
 6. Issue that pull request!
 
 <Card title="Creating a pull request" icon="github" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request">
   Create a Pull Request to propose and collaborate on changes to a repository.
 </Card>
 
-## Development Process
+---
+
+## Local Development Setup
+
+<Steps>
+  <Step title="Fork and Clone">
+    ```bash
+    git clone https://github.com/YOUR_USERNAME/magemaker.git
+    cd magemaker
+    ```
+  </Step>
+  <Step title="Create and Activate Virtualenv (optional but recommended)">
+    ```bash
+    python -m venv .venv
+    source .venv/bin/activate  # Linux / macOS
+    .venv\Scripts\activate     # Windows
+    ```
+  </Step>
+  <Step title="Install Dependencies (dev)">
+    ```bash
+    pip install -e ".[dev]"
+    ```
+  </Step>
+  <Step title="Run Tests">
+    ```bash
+    pytest -q
+    ```
+  </Step>
+  <Step title="Run the Local API Server (optional)">
+    If you are working on the FastAPI server (`server.py`) or the OpenAI-compatible proxy, you can spin it up locally:
+    ```bash
+    uvicorn server:app --reload --port 8000
+    ```
+    This requires AWS credentials in a `.env` file (see `configuration/Environment`).
+  </Step>
+</Steps>
+
+---
+
+## Code Style
+
+We use **Black**, **isort**, and **flake8** to maintain code quality.
+
+```bash
+black .
+isort .
+flake8
+```
+
+A pre-commit configuration is provided. You can install the Git hooks with:
 
-1. Fork the repo
-2. Create a new branch: `git checkout -b my-feature-branch`
-3. Make your changes
-4. Push to your fork and submit a pull request
-5. Wait for a review and address any comments
+```bash
+pre-commit install
+```
 
-## Pull Request Guidelines
+This will automatically run the formatters and linters before every commit.
 
-- <Icon icon="check" iconType="solid" /> Update documentation as needed
-- <Icon icon="check" iconType="solid" /> Add tests if applicable
-- <Icon icon="check" iconType="solid" /> Follow the existing code style
-- <Icon icon="check" iconType="solid" /> Keep PRs small and focused
-- <Icon icon="check" iconType="solid" /> Write clear commit messages
+---
+
+## Testing
+
+All new features **must** include tests. We use **pytest** for our test suite:
+
+- **Unit tests** live next to the module being tested (e.g. `magemaker/gcp/test_*.py`).
+- **Integration tests** should be marked with `@pytest.mark.integration` so they can be skipped in CI if needed.
+- When adding a new cloud provider or API route, include at least one happy-path test and one failure test.
+
+Run the full test suite:
+
+```bash
+pytest
+```
+
+Run only fast unit tests:
+
+```bash
+pytest -m "not integration"
+```
+
+---
+
+## Documentation
+
+Documentation lives in the `docs/` folder and is built with [Mintlify](https://www.mintlify.com/).
+
+<Steps>
+  <Step title="Install Mintlify CLI">
+    ```bash
+    npm install -g mintlify
+    ```
+  </Step>
+  <Step title="Preview Docs Locally">
+    ```bash
+    mintlify dev
+    ```
+  </Step>
+  <Step title="Add / Update Pages">
+    Create or edit `.mdx`/`.md` files under `docs/` following the existing structure. Make sure to add your page to `mint.json` **navigation** if it should appear in the sidebar.
+  </Step>
+</Steps>
+
+When you introduce a new user-facing capability (e.g., the FastAPI server or a new cloud deployment target), **create a dedicated docs page** and cross-link it from relevant sections.
+
+---
+
+## Pull Request Checklist
+
+<Checklist>
+  <Check icon="check">Code builds & tests pass (`pytest`)</Check>
+  <Check icon="check">Documentation updated</Check>
+  <Check icon="check">Linters/formatters run</Check>
+  <Check icon="check">Commits follow Conventional Commits</Check>
+</Checklist>
+
+---
+
+## Commit Message Convention
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation changes
+- `style:` Code style (formatting) changes
+- `refactor:` Code refactor (no behaviour change)
+- `test:` Adding or updating tests
+- `chore:` Build processes or auxiliary tooling
+
+Example:
+
+```bash
+feat(api): add OpenAI-compatible /chat/completions route
+```
+
+---
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.
+By contributing, you agree that your contributions will be licensed under the **Apache 2.0 License**.
+
+---
 
 ## Questions?
 
-Feel free to contact us at [support@slashml.com](mailto:support@slashml.com) if you have any questions about contributing!
+Feel free to contact us at [support@slashml.com](mailto:support@slashml.com) or join the discussion on GitHub.
diff --git a/README.md b/README.md
@@ -1,24 +1,80 @@
-### These are docs for the [Magemaker-Docs](https://magemaker.slashml.com) documentation site.
+### Magemaker Documentation
 
-The source code of magemaker is located at [Magemaker](https://github.com/slashml/magemaker)
+This repository contains the **documentation site** for [Magemaker](https://github.com/slashml/magemaker).  
+If you are looking for the actual source-code, visit the Magemaker repo above.  
 
-### Development
+---
 
-Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
+## Local Development Workflow
 
-```
-npm i -g mintlify
-```
+Follow the steps below to preview documentation updates or to add new pages.
 
-you need to have Node.js installed to use npm.
+### 1. Install Mintlify CLI
 
-Run the following command at the root of your documentation (where mint.json is)
+We use the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to run the docs locally.
 
+```bash
+npm i -g mintlify   # requires Node >= 16
 ```
+
+<Note>
+If you receive a "command not found" error after installation, make sure your global npm
+bin folder is in your $PATH.
+</Note>
+
+### 2. Start the Docs Site
+
+Run the following command from the root of the documentation repository (the folder that
+contains `mint.json`).
+
+```bash
 mintlify dev
 ```
 
-#### Troubleshooting
+This spins-up a hot-reloading server at `http://localhost:3000` where you can preview your
+changes.
+
+### 3. Update / Add Pages
+
+1. Create or edit `.mdx` / `.md` files inside the docs tree (see `mint.json` for the
+   navigation structure).  
+2. Follow the existing component conventions (front-matter, `<Card/>`, `<Steps/>`, etc.).  
+3. Commit the new/updated files and open a Pull Request.
+
+### Troubleshooting
+
+• **`mintlify dev` isn’t running** – Execute `mintlify install` to re-install
+  dependencies.  
+• **404 after launch** – Make sure you are in the directory that contains
+  `mint.json`.  
+• **Styles/components look off** – Delete the `node_modules` folder and run
+  `mintlify install` again.
+
+
+---
+
+## Contributing Docs
+
+See the main project’s **Contributing** guide for coding standards. When updating docs:
+
+1. Ensure every new feature in the code-base has at least one corresponding docs page.
+2. Cross-link related pages for better discoverability.
+3. Run the full docs site locally (`mintlify dev`) and verify:
+   • Navigation entry exists.  
+   • No broken links / images.  
+   • Dark-mode renders correctly.
+
+<Warning>
+Never commit secrets or `.env` files to the documentation repository.
+</Warning>
+
+
+## Related Resources
+
+• **Production Docs Site:** <https://magemaker.slashml.com>  
+• **API Proxy Docs:** Newly added – see "Core Concepts → API Proxy" in the left sidebar for
+  information on the FastAPI server included with Magemaker.
+
+---
 
-- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
-- Page loads as a 404 - Make sure you are running in a folder with `mint.json`
+Happy documenting! 🎉
diff --git a/about.mdx b/about.mdx
@@ -1,43 +1,65 @@
 ---
 title: About
-description: Deploy open source AI models to AWS, GCP, and Azure in minutes
+description: Deploy open-source AI models to AWS, GCP, and Azure in minutes
 "og:title": "Magemaker"
 ---
 
 ## About Magemaker
 
-Magemaker is a Python tool that simplifies the process of deploying open source AI models to your preferred cloud provider. Instead of spending hours digging through documentation, Magemaker lets you deploy Hugging Face models directly to AWS SageMaker, Google Cloud Vertex AI, or Azure Machine Learning.
+Magemaker is a Python-based DevOps toolkit that lets you turn any open-source AI model into a production-ready, fully managed endpoint on **AWS SageMaker, GCP Vertex AI, or Azure Machine Learning**—all from a single CLI.
 
-## What we're working on next
+Key capabilities:
 
-- More robust error handling for various edge cases
-- Verbose logging
-- Enabling / disabling autoscaling
-- Enhanced multi-cloud support features
+<CardGroup cols={3}>
+  <Card title="Multi-Cloud Deploy" icon="cloud">
+    Deploy to AWS, GCP, or Azure with a single YAML file or interactive CLI.
+  </Card>
+  <Card title="Fine-Tuning" icon="rocket">
+    One-command fine-tuning pipeline for Hugging Face models on SageMaker.
+  </Card>
+  <Card title="OpenAI-Compatible API" icon="plug">
+    Built-in FastAPI server (`server.py`) that exposes your SageMaker endpoints via `/chat/completions`—drop-in replacement for the OpenAI API.
+  </Card>
+</CardGroup>
 
-Do submit your feature requests at https://magemaker.featurebase.app/
+## What’s New 🎉
 
-## Known issues
+1. **OpenAI-Compatible Proxy**  
+   Run `python server.py` to expose any deployed SageMaker endpoint at `/chat/completions` (see the new [API Proxy Guide](/concepts/api-proxy)).
+2. **Environment-Driven Config**  
+   Most settings (cloud credentials, custom `CONFIG_DIR`, default region, etc.) are now auto-detected from `.env`.
 
-- Querying within Magemaker currently only works with text-based models
-- Deleting a model is not instant, it may show up briefly after deletion
-- Deploying the same model within the same minute will break
-- Hugging-face models on Azure have different Ids than their Hugging-face counterparts. Follow the steps specified in the quick-start guide to find the relevant models
-- For Azure deploying models other than Hugging-face is not supported yet. 
-- Python3.13 is not supported because of an open-issue by Azure. https://github.com/Azure/azure-sdk-for-python/issues/37600
+## Roadmap
 
+- More robust error handling for edge cases
+- Verbose / structured logging
+- Autoscaling enable / disable per deployment
+- Enhanced multi-cloud feature parity (fine-tuning & managed datasets on GCP/Azure)
+- API proxy hardening (streaming, function-calling, rate-limits)
 
-If there is anything we missed, do point them out at https://magemaker.featurebase.app/
+Have a feature request? Add it at https://magemaker.featurebase.app/
 
+## Known Issues
+
+<Warning>
+These are temporary limitations. Check the GitHub Issues board for the latest status.
+</Warning>
+
+- Only text-based pipelines are supported for querying (no vision/multimodal yet)
+- Endpoint deletion is asynchronous; the name may linger for ~60 s after deletion
+- Deploying the **same** model within the **same minute** can fail due to name collision
+- Azure model IDs differ from Hugging Face IDs (see [Quick Start](/quick-start))
+- Azure: only Hugging Face models are currently supported
+- Python 3.13 is not yet supported (Azure SDK issue [#37600](https://github.com/Azure/azure-sdk-for-python/issues/37600))
+
+If we missed something, let us know on https://magemaker.featurebase.app/
 
 ## License
 
-Distributed under the Apache 2.0 License. See `LICENSE` for more information.
+Distributed under the Apache 2.0 License. See `LICENSE` for details.
 
 ## Contact
 
-You can reach us, faizan & jneid, at [faizan|jneid@slashml.com](mailto:support@slashml.com).
-
-You can give feedback at https://magemaker.featurebase.app/
+Questions or feedback? Reach out to **Faizan & Jneid** at <mailto:support@slashml.com>.
 
-We'd love to hear from you! We're excited to learn how we can make this more valuable for the community and welcome any and all feedback and suggestions.
+We’d love to hear your ideas for making Magemaker even better!