Skip to content

Contributing

Jump to bottom
The Duskfall Portal Crew edited this page Jun 12, 2026 · 1 revision

Contributing

Guidelines for contributing to the Ktiseos Nyx Trainer project.

Ways to Contribute

Bug Reports

  • Search existing issues before creating new reports
  • Include: GPU model, OS, Python and Node.js versions, browser
  • Specify: local or cloud deployment
  • Attach diagnostics_*.txt output
  • Provide clear reproduction steps

Feature Requests

  • Review existing issues and discussions for similar requests
  • Clearly articulate the problem your feature solves
  • Provide specific implementation details

Code Contributions

Priority areas:

  • Frontend UI — React component improvements, user experience
  • API Layer — FastAPI endpoint fixes, validation improvements
  • Dataset Management — Upload workflows, tagging, captioning
  • Training Integration — Kohya SS parameter support, TOML generation
  • Performance — Memory optimization, training speed
  • Documentation — Code docs, user guides, examples
  • Platform Support — Cross-platform compatibility

Development Process

Setup

  1. Fork and clone the repository
  2. Create a descriptive branch (e.g. feature/dataset-validation, fix/training-toml-bug)
  3. python installer.py — set up backend dependencies
  4. cd frontend && npm install — set up frontend
  5. Start services for testing

Tech Stack Reference

Layer Technology Key Files
Frontend Next.js 16, React 19, TypeScript frontend/app/, frontend/components/
UI Components shadcn/ui (Radix primitives) frontend/components/ui/
API Client Typed fetch wrapper frontend/lib/api.ts
Validation Zod (frontend), Pydantic (backend) frontend/lib/validation.ts, services/models/
API Routes FastAPI api/routes/
Services Python business logic services/
Training Vendored Kohya SS + LyCORIS trainer/derrian_backend/
Config Generation TOML services/trainers/kohya_toml.py

Code Standards

TypeScript / Frontend:

  • Always use shadcn/ui components — never raw <input>, <select>, <button>
  • Use @/ path aliases for imports
  • All components must be TypeScript
  • 'use client' for components with state, effects, or event handlers
  • Follow accessibility best practices (semantic HTML, ARIA, keyboard nav)
  • API calls go through lib/api.ts

Python / Backend:

  • PEP 8 with reasonable flexibility
  • Pydantic models with Field() descriptions for all request/response types
  • Literal types for enum validation on API route models
  • Type hints for all function parameters and return values
  • Cross-platform file paths (os.path.join(), pathlib.Path)
  • Do not lint or reformat trainer/derrian_backend/

Three-Layer Architecture

When adding features, update all three layers consistently:

  1. Frontend (lib/api.ts, lib/validation.ts) — TypeScript types and Zod schemas
  2. API Route (api/routes/) — FastAPI endpoint with route-level Pydantic model
  3. Service Layer (services/) — Business logic with service-level Pydantic model

Field names, types, and defaults must match across all layers.

Testing Requirements

Pre-submission:

  • npx tsc --noEmit in frontend/ — must pass cleanly
  • npm run build in frontend/ — must complete without errors
  • Confirm intended behavior works in browser
  • Check edge cases and invalid inputs
  • Verify existing functionality is unaffected

Running tests:

pip install -r requirements_dev.txt
pytest tests/test_api_plumbing.py -v

Tests are GPU-free and mock all ML dependencies. New tests go in tests/. Tests requiring a real GPU: mark with @pytest.mark.slow.

Pull Request Process

  • Clear explanation of changes and their purpose
  • Reference related issues (Fixes #number or Related to #number)
  • Respond constructively to code review feedback
  • Update documentation to reflect behavioral changes

What Not to Do

  • Do not add Jupyter notebook references to any file
  • Do not modify vendored code in trainer/derrian_backend/ without discussion
  • Do not run git submodule commands — there are no submodules
  • Do not change 0.0.0.0 server bindings
  • Do not hardcode absolute paths
  • Do not write macOS-only or Unix-only code
  • Do not create markdown audit files unless asked
  • Do not add platform-specific npm packages directly (causes EBADPLATFORM on other OSes)

Legal

By submitting contributions, you agree that:

  • Your contributions are licensed under the project's MIT license
  • You have legal rights to submit the contributed code
  • Your contributions do not violate third-party copyrights or licenses

Getting Help

  • General questions: GitHub Discussions
  • Technical issues: Search existing issues before creating new ones
  • Specific problems: Comment on relevant PRs or issues

This project is built with neurodivergent-friendly workflows — clear structure, consistent patterns, and helpful error messages are valued.

Clone this wiki locally