model-generator-kit 0.1.0__py3-none-any.whl

model_generator/stacks/python-fastapi/config.yaml

@@ -0,0 +1,403 @@
+# Python FastAPI Stack Configuration
+# Maps abstract types to SQLAlchemy/Pydantic implementations
+#
+# NOTE: Project-specific config (name, description) should be in:
+#       <project-root>/.model-generator.yaml
+#
+# See .model-generator.example.yaml in the skill directory for template.
+
+stack:
+  name: python-fastapi
+  description: Python with FastAPI, SQLAlchemy, Pydantic
+  version: "1.0"
+
+# Required Python packages for generated code
+dependencies:
+  runtime:
+    - "fastapi>=0.109.0"
+    - "uvicorn>=0.27.0"
+    - "sqlalchemy>=2.0.0"
+    - "alembic>=1.13.0"
+    - "pydantic>=2.0.0"
+    - "aiosqlite>=0.19.0"
+  # Conditional: only needed when model has password fields
+  conditional:
+    password_field:
+      - "bcrypt>=4.0.0"
+    encrypted_binary:
+      - "cryptography>=42.0.0"
+  dev:
+    - "pytest>=7.0.0"
+    - "pytest-xdist>=3.0.0"
+    - "httpx>=0.26.0"
+    - "factory-boy>=3.3.0"
+    - "faker>=22.0.0"
+    - "mutmut>=3.0.0,<3.5.0"
+
+# Output paths relative to project root
+paths:
+  # Infrastructure (generated once)
+  base: backend/src/database/models/base.py
+  engine: backend/src/database/engine.py
+  main: backend/src/main.py
+  errors: backend/src/api/errors.py
+  validators: backend/src/api/validators.py
+  test_conftest_root: tests/conftest.py
+  # Domain-specific (generated per domain)
+  database_models: backend/src/database/models
+  factories: backend/src/database/models/factories
+  api_models: backend/src/api/models
+  api_routes: backend/src/api/routes
+  api_tests: tests/contract/api
+  enums: backend/src/database/models/enums.py
+  constraints: backend/src/database/models/constraints.py
+  migrations: alembic
+
+# Type mappings: abstract -> concrete
+types:
+  uuid:
+    database:
+      column: "Column(Uuid, primary_key={primary_key}, default=uuid.uuid4)"
+      imports:
+        - "from sqlalchemy import Column, Uuid"
+        - "import uuid"
+    api_response: "str | None"
+    api_request: "str"
+
+  financial:
+    database:
+      column: "Column(Numeric({precision}, {scale}), nullable={nullable}, default=Decimal(\"{default}\"))"
+      imports:
+        - "from sqlalchemy import Column, Numeric"
+        - "from decimal import Decimal"
+    api_response: "str | None"
+    api_request: "str"
+    validators:
+      - validate_non_negative_decimal
+      - validate_positive_decimal
+
+  percentage:
+    database:
+      column: "Column(Numeric(5, 4), nullable={nullable}, default=Decimal(\"{default}\"))"
+      imports:
+        - "from sqlalchemy import Column, Numeric"
+        - "from decimal import Decimal"
+    api_response: "str | None"
+    api_request: "str"
+    validators:
+      - validate_percentage
+
+  counter:
+    database:
+      column: "Column(Integer, nullable={nullable}, default={default})"
+      imports:
+        - "from sqlalchemy import Column, Integer"
+    api_response: "int | None"
+    api_request: "int"
+    validators:
+      - validate_non_negative_int
+      - validate_positive_int
+
+  # "integer" is an alias for "counter" — normalized at load time.
+  # Use "integer" for generic integers (e.g., HTTP status, nanosecond timestamps).
+  # Use "counter" for monotonically increasing values (e.g., retry counts).
+  integer:
+    database:
+      column: "Column(Integer, nullable={nullable}, default={default})"
+      imports:
+        - "from sqlalchemy import Column, Integer"
+    api_response: "int | None"
+    api_request: "int"
+    validators:
+      - validate_non_negative_int
+      - validate_positive_int
+
+  text:
+    database:
+      column: "Column(String({max_length}), nullable={nullable}, unique={unique})"
+      imports:
+        - "from sqlalchemy import Column, String"
+    api_response: "str | None"
+    api_request: "str"
+    field_args: "max_length={max_length}"
+
+  longtext:
+    database:
+      column: "Column(Text, nullable={nullable})"
+      imports:
+        - "from sqlalchemy import Column, Text"
+    api_response: "str | None"
+    api_request: "str"
+
+  boolean:
+    database:
+      column: "Column(Boolean, nullable={nullable}, default={default})"
+      imports:
+        - "from sqlalchemy import Column, Boolean"
+    api_response: "bool | None"
+    api_request: "bool"
+
+  binary:
+    database:
+      column: "Column(LargeBinary, nullable={nullable})"
+      imports:
+        - "from sqlalchemy import Column, LargeBinary"
+    api_response: "bytes | None"
+    api_request: "bytes"
+
+  datetime:
+    database:
+      column: "Column(DateTime(timezone=True), nullable={nullable})"
+      column_with_default: "Column(DateTime(timezone=True), server_default=func.now(), nullable={nullable})"
+      column_with_update: "Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable={nullable})"
+      imports:
+        - "from sqlalchemy import Column, DateTime"
+        - "from sqlalchemy.sql import func"
+    api_response: "str | None"
+    api_request: "str"
+    conversion: ".isoformat() + 'Z'"
+
+  enum:
+    database:
+      column: 'Column(SQLEnum({enum_name}, native_enum=False), nullable={nullable}, default={enum_name}.{default})'
+      imports:
+        - "from sqlalchemy import Column, Enum as SQLEnum"
+        - "from .enums import {enum_name}"
+    api_response: "{enum_name} | None"
+    api_request: "{enum_name}"
+    api_imports:
+      - "from {{{{ config.paths.database_models | path_to_import }}}}.enums import {enum_name}"
+
+  json_object:
+    database:
+      column: "Column(JSON, nullable={nullable}, default=dict)"
+      imports:
+        - "from sqlalchemy import Column, JSON"
+    api_response: "dict[str, Any] | None"
+    api_request: "dict[str, Any]"
+    api_imports:
+      - "from typing import Any"
+
+  json_array:
+    database:
+      column: "Column(JSON, nullable={nullable}, default=list)"
+      imports:
+        - "from sqlalchemy import Column, JSON"
+    api_response: "list[Any] | None"
+    api_request: "list[Any]"
+    api_imports:
+      - "from typing import Any"
+
+  reference:
+    database:
+      column: 'Column(Uuid, ForeignKey("{reference_table}.{reference_column}", ondelete="{on_delete}"), nullable={nullable}, index=True)'
+      imports:
+        - "from sqlalchemy import Column, Uuid, ForeignKey"
+    api_response: "str | None"
+    api_request: "str"
+
+# Timestamp patterns
+timestamps:
+  created_at:
+    column: "created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)"
+    imports:
+      - "from sqlalchemy import Column, DateTime"
+      - "from sqlalchemy.sql import func"
+
+  updated_at:
+    column: "updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)"
+    imports:
+      - "from sqlalchemy import Column, DateTime"
+      - "from sqlalchemy.sql import func"
+
+# Constraint patterns
+constraints:
+  non_negative:
+    check: 'CheckConstraint("{field} >= 0", name="ck_{table}_{field}_non_negative")'
+    imports:
+      - "from sqlalchemy import CheckConstraint"
+
+  positive:
+    check: 'CheckConstraint("{field} > 0", name="ck_{table}_{field}_positive")'
+    imports:
+      - "from sqlalchemy import CheckConstraint"
+
+  range:
+    check: 'CheckConstraint("{field} >= {min} AND {field} <= {max}", name="ck_{table}_{field}_range")'
+    imports:
+      - "from sqlalchemy import CheckConstraint"
+
+  length:
+    check: 'CheckConstraint("length({field}) >= {min}", name="ck_{table}_{field}_length")'
+    imports:
+      - "from sqlalchemy import CheckConstraint"
+
+  pattern:
+    # Pattern validation typically done at API level, not database
+    api_validator: true
+
+  depends:
+    check: 'CheckConstraint("{field} {operator} {other_field}", name="ck_{table}_{field}_{other_field}")'
+    imports:
+      - "from sqlalchemy import CheckConstraint"
+
+# Index patterns
+indexes:
+  single:
+    pattern: 'Index("ix_{table}_{field}", "{field}")'
+    imports:
+      - "from sqlalchemy import Index"
+
+  composite:
+    pattern: 'Index("ix_{table}_{fields_joined}", {fields_quoted})'
+    imports:
+      - "from sqlalchemy import Index"
+
+  unique:
+    pattern: 'UniqueConstraint({fields_quoted}, name="uq_{table}_{fields_joined}")'
+    imports:
+      - "from sqlalchemy import UniqueConstraint"
+
+# Relationship patterns
+relationships:
+  one_to_many:
+    parent: 'relationship("{target}", back_populates="{back_populates}", cascade="{cascade}")'
+    child_fk: 'Column(Uuid, ForeignKey("{parent_table}.id", ondelete="{on_delete}"), nullable={nullable}, index=True)'
+    child_rel: 'relationship("{parent}", back_populates="{back_populates}")'
+
+  many_to_one:
+    fk: 'Column(Uuid, ForeignKey("{target_table}.id", ondelete="{on_delete}"), nullable={nullable}, index=True)'
+    rel: 'relationship("{target}", back_populates="{back_populates}")'
+
+  one_to_one:
+    parent: 'relationship("{target}", back_populates="{back_populates}", uselist=False, cascade="{cascade}")'
+    child_fk: 'Column(Uuid, ForeignKey("{parent_table}.id", ondelete="{on_delete}"), nullable={nullable}, unique=True)'
+    child_rel: 'relationship("{parent}", back_populates="{back_populates}")'
+
+# API patterns
+api:
+  response_model:
+    suffix: Response
+    base_class: BaseModel
+    config: "model_config = ConfigDict(from_attributes=True)"
+    imports:
+      - "from pydantic import BaseModel, ConfigDict"
+
+  create_request:
+    prefix: Create
+    suffix: Request
+    base_class: BaseModel
+    imports:
+      - "from pydantic import BaseModel, Field"
+
+  update_request:
+    prefix: Update
+    suffix: Request
+    base_class: BaseModel
+    imports:
+      - "from pydantic import BaseModel, Field"
+
+  validators:
+    non_negative_decimal:
+      import: "from {{{{ config.paths.api_models.rsplit('/', 1)[0] | path_to_import }}}}.validators import validate_non_negative_decimal"
+      usage: "_validate_{field} = field_validator('{field}')(validate_non_negative_decimal)"
+
+    positive_decimal:
+      import: "from {{{{ config.paths.api_models.rsplit('/', 1)[0] | path_to_import }}}}.validators import validate_positive_decimal"
+      usage: "_validate_{field} = field_validator('{field}')(validate_positive_decimal)"
+
+    percentage:
+      import: "from {{{{ config.paths.api_models.rsplit('/', 1)[0] | path_to_import }}}}.validators import validate_percentage"
+      usage: "_validate_{field} = field_validator('{field}')(validate_percentage)"
+
+    non_negative_int:
+      import: "from {{{{ config.paths.api_models.rsplit('/', 1)[0] | path_to_import }}}}.validators import validate_non_negative_int"
+      usage: "_validate_{field} = field_validator('{field}')(validate_non_negative_int)"
+
+    positive_int:
+      import: "from {{{{ config.paths.api_models.rsplit('/', 1)[0] | path_to_import }}}}.validators import validate_positive_int"
+      usage: "_validate_{field} = field_validator('{field}')(validate_positive_int)"
+
+    timestamp_after:
+      import: "from {{{{ config.paths.api_models.rsplit('/', 1)[0] | path_to_import }}}}.validators import validate_timestamp_after"
+      usage: "validate_timestamp_after(self.{later}, self.{earlier}, '{later}', '{earlier}')"
+
+# Naming conventions
+naming:
+  table: snake_case
+  model: PascalCase
+  field: snake_case
+  enum: PascalCase
+  enum_value: snake_case
+  constraint: "ck_{table}_{description}"
+  index: "ix_{table}_{fields}"
+  unique: "uq_{table}_{fields}"
+  fk: "fk_{table}_{field}"
+
+# Code style (opt-in overrides — absent keys yield tool-native defaults)
+# Surfaced via .model-generator.yaml:
+#   style:
+#     python_version: "3.12"   # drives requires-python + mypy python_version
+#     line_length: 100         # emitted as [tool.ruff] line-length
+#     quote_style: "single"    # emitted as [tool.ruff.format] quote-style
+#     indent_style: "tab"      # emitted as [tool.ruff.format] indent-style
+style:
+  quote_style: double
+  indent_style: space
+  type_hints: true
+  docstrings: true
+  section_headers: true
+  section_header_format: "# ====== {section} ======"
+
+# Quality tools
+quality:
+  linter: "ruff check --fix ."
+  formatter: "ruff format ."
+  type_checker: "mypy . --explicit-package-bases"
+
+# Factory configuration for test data generation
+# Maps field name patterns to Faker methods
+factory:
+  # Field name inference: if field name contains key, use the faker method
+  # Format: pattern: "faker_method" or pattern: {method: "faker_method", args: {...}}
+  field_name_inference:
+    email: "email()"
+    first_name: "first_name()"
+    last_name: "last_name()"
+    username: "user_name()"
+    phone: "phone_number()"
+    address: "address()"
+    company: "company()"
+    url: "url()"
+    password: "password()"
+    description: "text(max_nb_chars=200)"
+    notes: "text(max_nb_chars=200)"
+    title: "sentence(nb_words=4)"
+    name: "name()"
+    city: "city()"
+    country: "country()"
+    state: "state()"
+    zip_code: "postcode()"
+    postal_code: "postcode()"
+    credit_card: "credit_card_number()"
+    ssn: "ssn()"
+    ip_address: "ipv4()"
+    mac_address: "mac_address()"
+    user_agent: "user_agent()"
+    file_name: "file_name()"
+    file_path: "file_path()"
+    mime_type: "mime_type()"
+    slug: "slug()"
+    color: "color_name()"
+    hex_color: "hex_color()"
+    latitude: "latitude()"
+    longitude: "longitude()"
+    currency_code: "currency_code()"
+    locale: "locale()"
+    language_code: "language_code()"
+    job: "job()"
+    job_title: "job()"
+
+  # Default text length when no max_length specified
+  default_text_length: 50
+

model_generator/stacks/python-fastapi/templates/_shared/_base.j2

@@ -0,0 +1,26 @@
+{#-
+  Base Macros
+  Common header and formatting macros used across all templates.
+-#}
+
+{#- Generated file marker - consistent warning across all templates -#}
+{% macro generated_marker() -%}
+# THIS CODE WAS INITIALLY GENERATED BY model-generator
+{%- endmacro %}
+
+{#- Full-width section divider (for major file sections) -#}
+{% macro section_divider(title) -%}
+# ============================================================================
+# {{ title | upper }}
+# ============================================================================
+{%- endmacro %}
+
+{#- Inline section header (for class subsections, indented) -#}
+{% macro section_header(title) -%}
+    # ====== {{ title }} ======
+{%- endmacro %}
+
+{#- Banner-style section (for routes/tests, centered title) -#}
+{% macro section_banner(title) -%}
+# ==================== {{ title | upper }} ====================
+{%- endmacro %}

model_generator/stacks/python-fastapi/templates/_shared/_entity.j2

@@ -0,0 +1,48 @@
+{#-
+  Entity Utility Macros
+  Primary key extraction, name transformations, and entity utilities.
+-#}
+
+{#- Get the primary key field name for an entity -#}
+{% macro get_primary_key_field(entity) -%}
+{%- for field_name, field in entity.fields.items() -%}
+{%- if field.primary_key | default(false) -%}
+{{ field.api_field_name | default(field_name) }}
+{%- endif -%}
+{%- endfor -%}
+{%- endmacro %}
+
+{#- Pluralize a name (simple English rules) -#}
+{#- Handles: y -> ies, s/x/ch/sh -> es, otherwise -> s -#}
+{% macro pluralize(name) -%}
+{%- if name.endswith('y') and name[-2:-1] not in 'aeiou' -%}
+{{ name[:-1] }}ies
+{%- elif name.endswith(('s', 'x', 'ch', 'sh')) -%}
+{{ name }}es
+{%- else -%}
+{{ name }}s
+{%- endif -%}
+{%- endmacro %}
+
+{#- Convert snake_case to kebab-case for URL paths -#}
+{% macro to_kebab_case(name) -%}
+{{ name | replace('_', '-') }}
+{%- endmacro %}
+
+{#- Convert CamelCase to snake_case -#}
+{% macro to_snake_case(name) -%}
+{%- set ns = namespace(result='') -%}
+{%- for char in name -%}
+{%- if char.isupper() and loop.index0 > 0 -%}
+{%- set ns.result = ns.result ~ '_' ~ char.lower() -%}
+{%- else -%}
+{%- set ns.result = ns.result ~ char.lower() -%}
+{%- endif -%}
+{%- endfor -%}
+{{ ns.result }}
+{%- endmacro %}
+
+{#- Get entity display name (snake_case to Title Case) -#}
+{% macro entity_display_name(entity_name) -%}
+{{ entity_name.replace('_', ' ').title() }}
+{%- endmacro %}

model_generator/stacks/python-fastapi/templates/_shared/_examples.j2

@@ -0,0 +1,50 @@
+{#-
+  OpenAPI Example Generation Macros
+  Generates sample values for API documentation.
+-#}
+
+{#- Generate an example value for a field -#}
+{#- for_update: use alternative values for update requests -#}
+{#- enums: shared enums dict for resolving enum field values -#}
+{% macro example_value(field, field_name, for_update=false, enums=none) -%}
+{%- set api_name = field.api_field_name | default(field_name) -%}
+{%- if field.type == 'uuid' -%}
+"123e4567-e89b-12d3-a456-426614174000"
+{%- elif field.type == 'text' and 'email' in field_name.lower() -%}
+"{% if for_update %}updated.{% endif %}user@example.com"
+{%- elif field.type == 'text' and field_name == 'username' -%}
+"{% if for_update %}updated_{% endif %}john_doe"
+{%- elif field.type == 'text' and 'name' in field_name.lower() -%}
+"{% if for_update %}Updated {% endif %}{{ field_name.replace('_', ' ').title() }}"
+{%- elif field.type == 'text' -%}
+"{% if for_update %}updated_{% endif %}{{ field_name }}_example"
+{%- elif field.type == 'longtext' -%}
+"This is a {% if for_update %}updated {% endif %}longer text field with more content."
+{%- elif field.type == 'reference' -%}
+"ref-123e4567"
+{%- elif field.type == 'financial' -%}
+"{% if for_update %}2000{% else %}1000{% endif %}"
+{%- elif field.type == 'percentage' -%}
+"{% if for_update %}0.2{% else %}0.15{% endif %}"
+{%- elif field.type == 'counter' -%}
+{% if for_update %}84{% else %}42{% endif %}
+{%- elif field.type == 'boolean' -%}
+{% if field.default == false %}false{% else %}true{% endif %}
+{%- elif field.type == 'datetime' -%}
+"2025-12-31T23:59:59Z"
+{%- elif field.type == 'enum' -%}
+{%- set enum_val = field.default | default('') -%}
+{%- if not enum_val and field.enum_name is defined and enums is mapping and field.enum_name in enums -%}
+{%- set ev = enums[field.enum_name].get('values', []) -%}
+{%- if ev -%}
+{%- set first = ev[1] if for_update and ev | length > 1 else ev[0] -%}
+{%- set enum_val = first.value if first is mapping else first -%}
+{%- endif -%}
+{%- endif -%}
+"{{ (enum_val or 'UNKNOWN') | upper }}"
+{%- elif field.type == 'json_object' -%}
+{"key": "value", "nested": {"data": 123}}
+{%- elif field.type == 'json_array' -%}
+["item1", "item2", "item3"]
+{%- endif -%}
+{%- endmacro %}

model_generator/stacks/python-fastapi/templates/_shared/_fields.j2

@@ -0,0 +1,48 @@
+{#-
+  Field Utility Macros
+  Type hint generation and field detection utilities.
+-#}
+
+{#- Check if a field is required (either explicitly or as non-auto-generated PK) -#}
+{% macro is_field_required(field) -%}
+{%- if field.required or (field.primary_key | default(false) and not field.auto_generate | default(true)) -%}
+true
+{%- endif -%}
+{%- endmacro %}
+
+{#- Generate Python type hint for a field -#}
+{#- for_response: response models use | None, request models use Optional or default -#}
+{% macro python_type_hint(field, field_name, for_response=false) -%}
+{%- if field.type == 'uuid' -%}
+str{{ ' | None' if for_response else '' }}
+{%- elif field.type in ['text', 'longtext'] -%}
+str{{ ' | None' if for_response else '' }}
+{%- elif field.type == 'reference' -%}
+str{{ ' | None' if for_response else '' }}
+{%- elif field.type in ['financial', 'percentage'] -%}
+str{{ ' | None' if for_response else '' }}
+{%- elif field.type == 'counter' -%}
+int{{ ' | None' if for_response else '' }}
+{%- elif field.type == 'boolean' -%}
+bool{{ ' | None' if for_response else '' }}
+{%- elif field.type == 'datetime' -%}
+str{{ ' | None' if for_response else '' }}
+{%- elif field.type == 'enum' -%}
+{{ field.enum_name }}{{ ' | None' if for_response else '' }}
+{%- elif field.type == 'json_object' -%}
+dict[str, Any]{{ ' | None' if for_response else '' }}
+{%- elif field.type == 'json_array' -%}
+list[{{ field.list_type | default('Any') }}]{{ ' | None' if for_response else '' }}
+{%- else -%}
+Any
+{%- endif -%}
+{%- endmacro %}
+
+{#- Check if any fields need the Any type import -#}
+{% macro needs_any_import(entity) -%}
+{%- for field_name, field in entity.fields.items() -%}
+{%- if field.type in ['json_object', 'json_array'] -%}
+true
+{%- endif -%}
+{%- endfor -%}
+{%- endmacro %}