Model Generator

A one-shot bootstrap code generator that turns JSON specifications into production-ready API backends — database models, API endpoints, tests, and migrations. The generator is stack-agnostic by design; it currently ships the python-fastapi stack (chosen with --stack, the default).

What It Does

• Database models — SQLAlchemy ORM with constraints, relationships, and indexes
• API models — Pydantic request/response schemas with validators
• API routes — FastAPI CRUD endpoints
• Tests — pytest contract tests with FactoryBoy factories (a full contract suite in the example project)
• Migrations — Alembic infrastructure

Install

model-generator is a build-time scaffolding tool, not a runtime dependency of the backends it generates. Install it as an isolated global CLI:

uv tool install model-generator-kit     # or: pipx install model-generator-kit

This puts model-gen and model-val on your PATH. For the interactive wizard, add the extra: uv tool install "model-generator-kit[interactive]".

The PyPI package is model-generator-kit (the name model-generator was already taken); the commands it installs are model-gen and model-val.

Quick Start

# In any project directory, scaffold from your JSON specs
model-gen models/ --target all

model-gen --version    # confirm the install

To try the bundled example from a clone of this repo:

git clone https://github.com/nuncaeslupus/model-generator && cd model-generator
uv sync --extra dev
cd examples/user-auth-project
uv run model-gen models/ --target all
uv venv && uv sync --extra dev
uv run pytest  # the generated contract suite passes

For your own project, see the Installation Guide.

Documentation

For Users

• Installation Guide — Install, configure, first project
• Model Design Guide — How to design comprehensive JSON specifications
• Usage Guide — CLI workflows, generation, cleanup, interactive mode
• Quick Reference — Lookup tables: field types, constraints, options
• Extending Generated Code — Business logic, custom routes, migrations

For Agents

• Model Design Questions — Systematic Q&A for eliciting model specs from users
• Template Extension Guide — Add types, templates, generators
• JSON Specification Reference — Exact format, every key, every option

Deep Dives

• Constraints — DB vs API constraint placement, cross-field constraints
• Completeness Guide — JSON specification checklist
• Custom Tests — Extending the generated test suite

For Contributors

• Skill Reusability — Core principles for reusable generation
• Project-Agnostic Rules — Coding rules for templates and scripts

Development

# Install in editable mode with dev dependencies
uv sync --extra dev

# Run the test suite
uv run pytest tests/ -v

Test Suite

Philosophy

Define specifications once in JSON. Generate production-ready scaffolds. Then maintain and evolve manually. The generated code is yours — no lock-in, no regeneration, full control.

Model Generator | Bootstrap Tool for API Backends | v0.1.4