feat: add Python modelparams package and refresh catalog

.github/workflows/ci.yml

@@ -82,3 +82,113 @@ jobs:
 
       - name: Type-level tests (tsd)
         run: npm run test:types --workspace=modelparams
+
+  modelparams-python:
+    name: modelparams Python package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Generate Python catalog and types
+        run: npm run codegen:python
+
+      - name: Verify Python generated files are in sync
+        run: |
+          if [[ -n "$(git status --porcelain -- packages/modelparams-python/src/modelparams/_generated packages/modelparams-python/src/modelparams/types)" ]]; then
+            echo "::error::Generated Python package files are out of date."
+            echo "Run \`npm run codegen:python\` locally and commit the result."
+            git status --short -- packages/modelparams-python/src/modelparams/_generated packages/modelparams-python/src/modelparams/types
+            exit 1
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install Python dependencies
+        run: uv sync --project packages/modelparams-python --extra dev --locked
+
+      - name: Lint and format check
+        run: |
+          uv run --project packages/modelparams-python ruff check packages/modelparams-python
+          uv run --project packages/modelparams-python ruff format --check packages/modelparams-python/src packages/modelparams-python/tests
+
+      - name: Typecheck
+        run: uv run --project packages/modelparams-python mypy --config-file packages/modelparams-python/pyproject.toml packages/modelparams-python/src/modelparams packages/modelparams-python/tests/typecheck
+
+      - name: Test
+        run: uv run --project packages/modelparams-python pytest packages/modelparams-python/tests
+
+      - name: Build and verify distributions
+        run: |
+          uv build --project packages/modelparams-python
+          uv run --project packages/modelparams-python twine check packages/modelparams-python/dist/*
+
+      - name: Smoke-test installed wheel
+        run: |
+          smoke_dir="$(mktemp -d)"
+          python -m venv "$smoke_dir/venv"
+          "$smoke_dir/venv/bin/pip" install packages/modelparams-python/dist/*.whl
+          cd "$smoke_dir"
+          "$smoke_dir/venv/bin/python" -c 'import modelparams; assert len(modelparams.MODEL_IDS) > 0; assert modelparams.validate_params("openai/gpt-4.1", {"temperature": 0.5}) == {"temperature": 0.5}'
+
+  modelparams-python-compat:
+    name: Python ${{ matrix.python-version }} compatibility
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --project packages/modelparams-python --extra dev --locked --python "${{ matrix.python-version }}"
+
+      - name: Test
+        run: uv run --project packages/modelparams-python --python "${{ matrix.python-version }}" pytest packages/modelparams-python/tests
+
+  modelparams-python-min-pydantic:
+    name: Python 3.10 + Pydantic 2.10
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Install minimum Pydantic
+        run: |
+          uv sync --project packages/modelparams-python --extra dev --locked --python "3.10"
+          uv pip install --python packages/modelparams-python/.venv/bin/python "pydantic==2.10.*"
+
+      - name: Test
+        run: |
+          packages/modelparams-python/.venv/bin/python -c 'import pydantic; assert pydantic.__version__.startswith("2.10.")'
+          packages/modelparams-python/.venv/bin/pytest packages/modelparams-python/tests

.github/workflows/release-modelparams-python.yml

@@ -0,0 +1,140 @@
+name: Release modelparams Python
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "models/**"
+      - "packages/modelparams-python/**"
+      - "src/schema/model.ts"
+      - "src/data/load.ts"
+      - ".github/workflows/release-modelparams-python.yml"
+  workflow_dispatch:
+    inputs:
+      force_level:
+        description: "Force bump level (overrides auto-detect)"
+        required: false
+        type: choice
+        options: ["auto", "patch", "major"]
+        default: "auto"
+
+concurrency:
+  group: release-modelparams-python
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    outputs:
+      next: ${{ steps.bump.outputs.next }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Validate catalog
+        run: npm run validate
+
+      - name: Generate Python catalog and types
+        run: npm run codegen:python
+
+      - name: Verify generated files are in sync
+        run: |
+          if [[ -n "$(git status --porcelain -- packages/modelparams-python/src/modelparams/_generated packages/modelparams-python/src/modelparams/types)" ]]; then
+            echo "::error::Generated Python package files are out of date."
+            git status --short -- packages/modelparams-python/src/modelparams/_generated packages/modelparams-python/src/modelparams/types
+            exit 1
+          fi
+
+      - name: Compute next version
+        id: bump
+        run: npx tsx packages/modelparams-python/scripts/compute-version.ts
+        env:
+          FORCE_LEVEL: ${{ inputs.force_level }}
+
+      - name: Set up Python
+        if: steps.bump.outputs.next != ''
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        if: steps.bump.outputs.next != ''
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install, test, and build
+        if: steps.bump.outputs.next != ''
+        env:
+          NEXT: ${{ steps.bump.outputs.next }}
+        run: |
+          uv sync --project packages/modelparams-python --extra dev --locked
+          uv version --project packages/modelparams-python "$NEXT"
+          uv run --project packages/modelparams-python ruff check packages/modelparams-python
+          uv run --project packages/modelparams-python ruff format --check packages/modelparams-python/src packages/modelparams-python/tests
+          uv run --project packages/modelparams-python pytest packages/modelparams-python/tests
+          uv run --project packages/modelparams-python mypy --config-file packages/modelparams-python/pyproject.toml packages/modelparams-python/src/modelparams packages/modelparams-python/tests/typecheck
+          uv build --project packages/modelparams-python
+          uv run --project packages/modelparams-python twine check packages/modelparams-python/dist/*
+
+      - name: Smoke-test installed wheel
+        if: steps.bump.outputs.next != ''
+        run: |
+          smoke_dir="$(mktemp -d)"
+          python -m venv "$smoke_dir/venv"
+          "$smoke_dir/venv/bin/pip" install packages/modelparams-python/dist/*.whl
+          cd "$smoke_dir"
+          "$smoke_dir/venv/bin/python" -c 'import modelparams; assert len(modelparams.MODEL_IDS) > 0; assert modelparams.validate_params("openai/gpt-4.1", {"temperature": 0.5}) == {"temperature": 0.5}'
+
+      - name: Upload distributions
+        if: steps.bump.outputs.next != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: modelparams-python-distributions
+          path: packages/modelparams-python/dist/
+          if-no-files-found: error
+
+      - name: Skip publish
+        if: steps.bump.outputs.next == ''
+        run: echo "::notice::No Python package or catalog change since the latest release."
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    if: needs.build.outputs.next != ''
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      actions: read
+      contents: write
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: modelparams-python-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+      - name: Create GitHub release and tag
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: "modelparams-py@${{ needs.build.outputs.next }}"
+          name: "modelparams-py@${{ needs.build.outputs.next }}"
+          target_commitish: ${{ github.sha }}
+          generate_release_notes: true

.gitignore

@@ -4,6 +4,12 @@ node_modules/
 packages/*/dist/
 packages/*/*.tsbuildinfo
 .cache/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
 *.log
 .DS_Store
 .env

.prettierignore

@@ -5,4 +5,6 @@ coverage/
 *.min.js
 *.min.css
 packages/modelparams/src/generated/
+packages/modelparams-python/src/modelparams/_generated/
+packages/modelparams-python/src/modelparams/types/
 packages/*/dist/

README.md

@@ -36,6 +36,26 @@ await new OpenAI().chat.completions.create({ model: "gpt-4.1", messages, ...para
 
 Defaults, runtime validation, and the helper APIs are in the [package README](packages/modelparams/README.md).
 
+## Python
+
+```bash
+pip install modelparams
+```
+
+Generated `TypedDict` definitions provide model-specific autocomplete and static checking, while
+Pydantic validates untrusted values at runtime:
+
+```python
+from modelparams import validate_params
+from modelparams.types.openai import Gpt_4_1Params
+
+params: Gpt_4_1Params = {"max_tokens": 1024, "temperature": 0.7}
+validated = validate_params("openai/gpt-4.1", params)
+```
+
+Defaults, catalog helpers, and validation details are in the
+[Python package README](packages/modelparams-python/README.md).
+
 ## API
 
 Prefer raw JSON?
@@ -58,6 +78,7 @@ npm install
 npm run dev          # http://localhost:3000
 npm run build        # → dist/
 npm run validate     # check every YAML
+npm run codegen:python # regenerate the Python package catalog and types
 npm test
 ```
 

models/cerebras/zai-glm-4.7.yaml

@@ -0,0 +1,85 @@
+# yaml-language-server: $schema=https://modelparams.dev/api/v1/schema.json
+provider: cerebras
+authType: api_key
+model: zai-glm-4.7
+params:
+  - path: max_completion_tokens
+    type: integer
+    label: Max tokens
+    description: Maximum number of output tokens the model may generate, including reasoning tokens.
+    range:
+      min: 1
+    group: generation_length
+  - path: temperature
+    type: number
+    label: Temperature
+    description: Controls randomness. Lower values make outputs more focused; higher values make them more varied. Adjust this or top_p, not both.
+    range:
+      min: 0
+      max: 2
+      step: 0.1
+    group: sampling
+  - path: top_p
+    type: number
+    label: Top P
+    description: Controls nucleus sampling by limiting generation to tokens within the selected cumulative probability.
+    range:
+      min: 0
+      max: 1
+      step: 0.01
+    group: sampling
+  - path: frequency_penalty
+    type: number
+    label: Frequency penalty
+    description: Penalizes tokens by how often they have appeared, reducing verbatim repetition.
+    default: 0
+    range:
+      min: -2
+      max: 2
+      step: 0.1
+    group: sampling
+  - path: presence_penalty
+    type: number
+    label: Presence penalty
+    description: Penalizes tokens that have already appeared, encouraging the model to introduce new topics.
+    default: 0
+    range:
+      min: -2
+      max: 2
+      step: 0.1
+    group: sampling
+  - path: seed
+    type: integer
+    label: Seed
+    description: Seed used for best-effort deterministic sampling when reproducible outputs are desired.
+    group: sampling
+  - path: stop
+    type: string
+    label: Stop
+    description: A string or list of strings where the API will stop generating further tokens. Cerebras accepts up to four stop sequences.
+    group: generation_length
+  - path: reasoning_effort
+    type: enum
+    label: Reasoning effort
+    description: Controls how much reasoning the model performs before answering. 'none' disables reasoning.
+    values:
+      - none
+      - low
+      - medium
+      - high
+    group: reasoning
+  - path: clear_thinking
+    type: boolean
+    label: Clear thinking
+    description: When true, the model's thinking from previous turns is excluded from the conversation context; when false, it is preserved, which is useful for agentic workflows.
+    default: true
+    group: reasoning
+  - path: response_format.type
+    type: enum
+    label: Response format
+    description: Forces the response into plain text or a JSON object.
+    default: text
+    values:
+      - text
+      - json_object
+    group: output_format