Add MkDocs-based GitHub Pages documentation site with PR preview

.github/workflows/docs-preview.yml

@@ -0,0 +1,49 @@
+name: Preview docs on PR
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/gimkit/**"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: pr-preview-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        if: github.event.action != 'closed'
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs
+        if: github.event.action != 'closed'
+        run: pip install -r docs/requirements.txt
+
+      - name: Build docs
+        if: github.event.action != 'closed'
+        run: mkdocs build --strict
+
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./site
+          preview-branch: gh-pages
+          wait-for-pages-deployment: true

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/gimkit/**"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs
+        run: pip install -r docs/requirements.txt
+
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

Makefile

@@ -6,6 +6,8 @@ install:
 
 install-dev:
 	uv sync --all-groups --all-extras
+	uv run pre-commit install
+	uv pip install -r docs/requirements.txt
 
 lint:
 	uv run ruff check
@@ -22,9 +24,16 @@ test:
 pre-commit:
 	uv run pre-commit run --all-files
 
+docs-build:
+	uv run mkdocs build --strict
+
+docs-serve:
+	uv run mkdocs serve
+
 clean:
 	rm -rf .coverage
 	rm -rf dist
 	rm -rf .mypy_cache
 	rm -rf .pytest_cache
 	rm -rf .ruff_cache
+	rm -rf site

docs/api.md

@@ -0,0 +1,35 @@
+# API Reference
+
+This page is generated from source code docstrings via `mkdocstrings`.
+
+## Package
+
+::: gimkit
+
+## Core Modules
+
+::: gimkit.guides
+
+::: gimkit.schemas
+
+::: gimkit.contexts
+
+::: gimkit.dsls
+
+::: gimkit.prompts
+
+::: gimkit.log
+
+::: gimkit.exceptions
+
+## Model Backends
+
+::: gimkit.models.base
+
+::: gimkit.models.openai
+
+::: gimkit.models.vllm
+
+::: gimkit.models.vllm_offline
+
+::: gimkit.models.utils

docs/index.md

@@ -0,0 +1,24 @@
+# GIMKit
+
+**Guided Infilling Modeling Toolkit** — precise structured text generation using language models.
+
+GIMKit lets you define placeholders (masked tags) in text and have a language model fill them in. It gives you fine-grained control over model outputs through a typed tag system with optional regex constraints.
+
+[![PyPI Version](https://img.shields.io/pypi/v/gimkit?label=pypi%20package)](https://pypi.org/project/gimkit)
+[![Python Versions](https://img.shields.io/pypi/pyversions/gimkit.svg)](https://pypi.org/project/gimkit)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey)](https://pypi.org/project/gimkit)
+
+---
+
+## Features
+
+- **Masked tag system** — embed typed placeholders directly in f-strings.
+- **Regex constraints** — restrict model output to specific patterns.
+- **Named access** — retrieve results by tag name or index.
+- **Multiple backends** — OpenAI, vLLM (server and offline).
+- **Small-model friendly** — designed to work well with compact open-source models.
+
+## Design Philosophy
+
+- **Stable over feature** — reliability and correctness are prioritized above new features.
+- **Small open-source model first** — designed to work well with small, freely available language models.

docs/installation.md

@@ -0,0 +1,25 @@
+# Installation
+
+## Standard
+
+Install GIMKit using pip:
+
+```bash
+pip install gimkit
+```
+
+## With vLLM support
+
+Install with the optional `vllm` extra to enable the vLLM backends:
+
+```bash
+pip install gimkit[vllm]
+```
+
+!!! note
+    vLLM is only supported on Linux. On Windows and macOS, omit the `[vllm]` extra.
+
+## Requirements
+
+- Python 3.10 or later
+- Linux, macOS, or Windows

docs/quickstart.md

@@ -0,0 +1,35 @@
+# Quick Start
+
+Here is a minimal example using the OpenAI backend.
+
+## 1. Set up the client
+
+```python
+from openai import OpenAI
+from gimkit import from_openai, guide as g
+
+client = OpenAI()  # reads OPENAI_API_KEY from environment
+model = from_openai(client, model_name="gpt-4")
+```
+
+## 2. Create a query with masked tags
+
+```python
+result = model(f"Hello, {g(desc='a single word')}!", use_gim_prompt=True)
+print(result)  # Hello, world!
+```
+
+## 3. Run a structured form
+
+```python
+query = f"""
+Name: {g.person_name(name="name")}
+Email: {g.e_mail(name="email")}
+Favorite color: {g.select(name="color", choices=["red", "green", "blue"])}
+"""
+
+result = model(query, use_gim_prompt=True)
+print(result.tags["name"].content)   # e.g. Alice
+print(result.tags["email"].content)  # e.g. alice@example.com
+print(result.tags["color"].content)  # red | green | blue
+```

docs/requirements.txt

@@ -0,0 +1,4 @@
+mkdocs>=1.6.1
+mkdocs-material>=9.6.23
+mkdocstrings[python]>=0.30.0
+mkdocs-minify-plugin>=0.8.0

docs/usage.md

@@ -0,0 +1,87 @@
+# Usage Guide
+
+## Creating Masked Tags
+
+Use the `guide` helper (conventionally imported as `g`) to create masked tags:
+
+```python
+from gimkit import guide as g
+
+# Basic tag with description
+tag = g(name="greeting", desc="A friendly greeting")
+
+# Specialized tags
+name_tag  = g.person_name(name="user_name")
+email_tag = g.e_mail(name="email")
+phone_tag = g.phone_number(name="phone")
+word_tag  = g.single_word(name="word")
+
+# Selection from choices
+choice_tag = g.select(name="color", choices=["red", "green", "blue"])
+
+# Tag with regex constraint
+code_tag = g(name="code", desc="A 4-digit PIN", regex=r"\d{4}")
+```
+
+## Building Queries
+
+Masked tags can be embedded directly in Python f-strings:
+
+```python
+from gimkit import from_openai, guide as g
+from openai import OpenAI
+
+client = OpenAI()
+model = from_openai(client, model_name="gpt-4")
+
+query = f"""
+Name: {g.person_name(name="name")}
+Email: {g.e_mail(name="email")}
+Favorite color: {g.select(name="color", choices=["red", "green", "blue"])}
+"""
+
+result = model(query, use_gim_prompt=True)
+print(result)
+```
+
+## Accessing Results
+
+Tags in the result can be accessed by index or by name:
+
+```python
+result = model(query, use_gim_prompt=True)
+
+# Iterate over all tags
+for tag in result.tags:
+    print(f"{tag.name}: {tag.content}")
+
+# Access a specific tag by name
+print(result.tags["name"].content)
+
+# Access by index
+print(result.tags[0].content)
+
+# Modify tag content
+result.tags["email"].content = "REDACTED"
+```
+
+## Using vLLM
+
+```python
+from gimkit import from_vllm
+
+model = from_vllm(base_url="http://localhost:8000", model_name="your-model")
+result = model(query)
+```
+
+For offline inference without a running server:
+
+```python
+from gimkit import from_vllm_offline
+
+model = from_vllm_offline(model_name="your-model")
+result = model(query)
+```
+
+!!! note
+    `from_vllm` and `from_vllm_offline` require `pip install gimkit[vllm]` on Linux.

mkdocs.yml

@@ -0,0 +1,57 @@
+site_name: GIMKit
+site_url: https://sculptai.github.io/GIMKit
+site_description: Guided Infilling Modeling Toolkit — precise structured text generation with language models.
+site_author: Shichao Song
+repo_name: SculptAI/GIMKit
+repo_url: https://github.com/SculptAI/GIMKit
+
+theme:
+  name: material
+  language: en
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.top
+    - content.code.copy
+    - search.suggest
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Quick Start: quickstart.md
+  - Usage Guide: usage.md
+  - API Reference: api.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths:
+            - src
+          options:
+            show_source: true
+            show_root_heading: true
+            show_root_toc_entry: true
+  - minify:
+      minify_html: true
+
+markdown_extensions:
+  - admonition
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+
+exclude_docs: |
+  requirements.txt