📄 Sync docs with latest code changes

CONTRIBUTING.md

@@ -1,5 +1,5 @@
 ---
-title: CONTRIBUTING.md
+title: CONTRIBUTING
 description: How to contribute to Magemaker
 "og:title": "Contributing to Magemaker"
 ---
@@ -9,7 +9,7 @@ description: How to contribute to Magemaker
 We love your input! We want to make contributing to Magemaker as easy and transparent as possible, whether it's:
 
 - Reporting a bug
-- Discussing the current state of the code
+- Discussing the current state of the code or documentation
 - Submitting a fix
 - Proposing new features
 - Becoming a maintainer
@@ -21,8 +21,8 @@ We love your input! We want to make contributing to Magemaker as easy and transp
 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 +33,89 @@ 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
-6. Issue that pull request!
+2. If you've added code that should be tested, add tests (`pytest`)
+3. If you've changed APIs or behaviour, update the documentation (`.mdx` files)
+4. Ensure the test suite passes: `pytest`
+5. Make sure your code lints: `black . && isort . && flake8`
+6. Open 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
-
-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
+## Local Development Workflow
+
+<Steps>
+  <Step title="Clone & Install">
+    ```bash
+    git clone https://github.com/slashml/magemaker.git
+    cd magemaker
+    # Install core + dev dependencies
+    pip install -e ".[dev]"
+    ```
+  </Step>
+  <Step title="Run Unit Tests">
+    ```bash
+    pytest -q
+    ```
+  </Step>
+  <Step title="Run the Local API Server (Optional)">
+    ```bash
+    uvicorn server:app --reload --port 8000
+    ```
+    The server exposes:
+    - `GET /endpoint/{endpoint_name}` – Returns SageMaker endpoint metadata
+    - `POST /endpoint/{endpoint_name}/query` – Sends an inference request
+    - `POST /chat/completions` – OpenAI-compatible chat completion proxy
+  </Step>
+  <Step title="Preview Docs Changes">
+    Install Mintlify CLI once:
+    ```bash
+    npm i -g mintlify
+    ```
+    Then run at repo root:
+    ```bash
+    mintlify dev
+    ```
+  </Step>
+</Steps>
 
 ## Pull Request Guidelines
 
-- <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
+- <Icon icon="check" iconType="solid" /> Follow existing code style (`black`, `isort`, `flake8`)
+- <Icon icon="check" iconType="solid" /> Include or update tests
+- <Icon icon="check" iconType="solid" /> Update or create documentation pages for any new feature (see *Docs Style Guide* below)
+- <Icon icon="check" iconType="solid" /> Write clear commit messages (Conventional Commits preferred)
+
+### Docs Style Guide
+
+1. All docs live in `docs/` or a top-level `.mdx` file.
+2. Use MDX components already present in other pages (e.g. `<Card>`, `<Steps>`).
+3. For a **brand-new feature**, create a new page under an appropriate folder (e.g. `concepts/`, `tutorials/`) and reference it in `mint.json` (navigation update will be reviewed during PR).
+4. Screenshots should be placed in `docs/Images/` and referenced with a relative path.
+
+## Commit Message Convention
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation only
+- `style:` Formatting, missing semicolons, etc.
+- `refactor:` Code change that neither fixes a bug nor adds a feature
+- `test:` Adding or correcting tests
+- `chore:` Build process or auxiliary tools changes
+
+Example:
+```bash
+feat(api): add chat completions proxy endpoint
+```
 
 ## License
 
 By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.
 
 ## Questions?
 
-Feel free to contact us at [[email protected]](mailto:[email protected]) if you have any questions about contributing!
+Feel free to contact us at [[email protected]](mailto:[email protected]) or join our [Discord](https://discord.gg/SBQsD63d) if you have any questions about contributing!

README.md

@@ -1,24 +1,70 @@
-### These are docs for the [Magemaker-Docs](https://magemaker.slashml.com) documentation site.
+### Magemaker Documentation Repo
 
-The source code of magemaker is located at [Magemaker](https://github.com/slashml/magemaker)
+This repository contains **only the documentation** for the Magemaker project.  
+The actual source code for Magemaker lives in the main repo:
+[github.com/slashml/magemaker](https://github.com/slashml/magemaker).
 
-### Development
+---
+## Local Docs Development
 
-Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
+The docs are written in **Mintlify** (`.mdx` & `.md` files).  
+Follow the steps below to preview changes locally.
 
-```
+### 1. Install the Mintlify CLI
+
+```bash
 npm i -g mintlify
 ```
 
-you need to have Node.js installed to use npm.
+> You need Node.js ≥ 18.x for the command above to work.
 
-Run the following command at the root of your documentation (where mint.json is)
+### 2. Start the Docs Dev-Server
 
-```
+From the root of the documentation folder (where `mint.json` lives):
+
+```bash
 mintlify dev
 ```
 
-#### Troubleshooting
+Mintlify will build the site and serve it at `http://localhost:3000` with hot-reload.
+
+### 3. Troubleshooting
+
+• **`mintlify dev` isn’t running** – run `mintlify install` to re-install deps.  
+• **404 after reload** – ensure you’re inside the folder containing `mint.json`.  
+• **Port already in use** – pass a different port: `mintlify dev --port 4000`.
+
+---
+## Contributing to the Docs
+
+1. Fork the repo & create your branch: `git checkout -b docs/my-update`  
+2. Make your edits / add new pages (follow existing style & front-matter).  
+3. Preview with `mintlify dev`.  
+4. Open a Pull Request against `main`.
+
+### Writing Style
+
+• Use American English.  
+• Keep headings ≤ H3 where possible.  
+• Use `<Note>`, `<Warning>`, `<Steps>`, and `<CardGroup>` components when helpful.  
+• All code blocks MUST be fenced with the correct language for syntax-highlighting.
+
+### When You Add New Features to Code
+
+If the implementation introduces a **new public-facing capability** (CLI flag, API route, env-var, etc.) you **must**:
+
+1. Create a new `.mdx` page that documents it.  
+2. Update `mint.json` navigation if needed.  
+3. Link to the new page from at least one existing doc (Quick-Start, Concepts, or Tutorials).
+
+---
+## NEW – OpenAI-Compatible Proxy Docs
+
+Magemaker now ships a **FastAPI server** (`server.py`) that exposes OpenAI-style chat completions on top of your SageMaker endpoints.  
+The full usage guide lives in the new page:  
+`/concepts/openai-proxy` – please read it and keep it updated if you touch `server.py`.
+
+---
+## Need Help?
 
-- 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`
+Open a discussion on GitHub or email us at **[email protected]**.

concepts/contributing.mdx

@@ -45,6 +45,41 @@ We're excited that you're interested in contributing to Magemaker! This document
   </Step>
 </Steps>
 
+### Running the Local API Server (OpenAI-Compatible Proxy)
+
+The repository includes `server.py`, a FastAPI implementation that exposes an OpenAI-compatible `/v1/chat/completions` endpoint.
+
+```bash
+# From the project root
+uvicorn server:app --reload
+```
+
+Environment variables required for the proxy live in `.env` (created by Magemaker on first run). At minimum you need:
+
+```bash
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+# Optional
+HUGGING_FACE_HUB_KEY=...
+```
+
+You can now hit `http://localhost:8000/v1/chat/completions` with any OpenAI SDK that supports a custom base-url.
+
+<Note>
+  Detailed usage, parameters, and troubleshooting are documented in <Link href="/concepts/openai-proxy">OpenAI Proxy</Link>.
+</Note>
+
+### Previewing Documentation
+
+We use [Mintlify](https://mintlify.com) for the docs site. Install the CLI to preview docs locally:
+
+```bash
+npm i -g mintlify
+mintlify dev
+```
+
+Edits to `.mdx` or `.md` files will hot-reload in the browser.
+
 ## Development Guidelines
 
 ### Code Style
@@ -72,13 +107,16 @@ Run tests locally:
 pytest tests/
 ```
 
+If you add or modify the FastAPI proxy, include unit tests under `tests/` to cover the new behaviour.
+
 ### Documentation
 
 When adding new features, please update the relevant documentation:
 
-1. Update the README.md if needed
+1. Update `README.md` if needed
 2. Add/update docstrings for new functions/classes
-3. Create/update relevant .mdx files in the docs directory
+3. Create/update relevant `.mdx` files in the docs directory
+4. If you introduce a brand-new component (e.g., a new cloud provider module), also create a dedicated docs page following the structure in `concepts/` or `tutorials/`
 
 ## Pull Request Process
 
@@ -165,4 +203,4 @@ We are committed to providing a welcoming and inclusive experience for everyone.
 
 ## License
 
-By contributing to Magemaker, you agree that your contributions will be licensed under the Apache 2.0 License.
+By contributing to Magemaker, you agree that your contributions will be licensed under the Apache 2.0 License.