synthline-ai 0.1.0__tar.gz

synthline_ai-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,20 @@
+# ==============================================================================
+# GitHub CODEOWNERS for SynthLine AI
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+# ==============================================================================
+
+# Global owner for all files across the repository
+* @thrive-spectrexq
+
+# Core package code and algorithms
+/src/ @thrive-spectrexq
+
+# CI/CD Workflows, GitHub actions & community health files
+/.github/ @thrive-spectrexq
+
+# Build & packaging configs
+/pyproject.toml @thrive-spectrexq
+/.gitignore @thrive-spectrexq
+
+# Testing suite
+/tests/ @thrive-spectrexq

synthline_ai-0.1.0/.github/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to SynthLine AI
+
+Thank you for your interest in contributing to SynthLine AI! We welcome bug fixes, documentation improvements, new defect generators, and workflow enhancements.
+
+## Code of Conduct
+
+Please be respectful, collaborative, and constructive in all discussions and code reviews.
+
+## Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/thrivecodes/synthline-ai.git
+   cd synthline-ai
+   ```
+
+2. Set up a Python 3.11+ virtual environment:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. Install in editable mode with development dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Workflow & Coding Standards
+
+- **Code Style & Linting**: We use [Ruff](https://astral.sh/ruff). Run:
+  ```bash
+  ruff check src tests
+  ruff format --check src tests
+  ```
+- **Type Checking**: We use strict [Mypy](https://mypy-lang.org/). Run:
+  ```bash
+  mypy src
+  ```
+- **Testing**: We write unit and integration tests using [pytest](https://pytest.org/). Run:
+  ```bash
+  pytest -v --cov=synthline_ai
+  ```
+- **Reproducibility**: If you implement or modify a procedural defect generator, ensure it accepts a `random_seed` and produces deterministic results across invocations.
+
+## Pull Request Guidelines
+
+1. Create a descriptive feature branch from `main`:
+   ```bash
+   git checkout -b feature/my-new-generator
+   ```
+2. Keep pull requests focused on a single change or feature.
+3. Ensure CI checks pass before requesting review.
+4. Fill out the PR template completely with test evidence.

synthline_ai-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,56 @@
+name: Bug Report
+description: Create a report to help us improve SynthLine AI
+title: "[BUG] <title>"
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a problem with SynthLine AI! Please provide as much detail as possible.
+  - type: input
+    id: version
+    attributes:
+      label: SynthLine AI Version / Commit
+      description: What version or git commit hash of SynthLine AI are you using?
+      placeholder: "e.g., 0.1.0 or commit abc1234"
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment Info
+      description: OS version and Python version
+      placeholder: "e.g., Windows 11 / Python 3.13.14"
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the Bug
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Provide reproducible steps or command-line invocation.
+      placeholder: |
+        1. Run `synthline-ai generate ...`
+        2. Inspect output directory ...
+        3. See error ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Traceback
+      description: Paste any error traceback or terminal logs.
+      render: shell

synthline_ai-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: SynthLine AI Discussions
+    url: https://github.com/thrivecodes/synthline-ai/discussions
+    about: Ask questions, share synthetic datasets, and connect with other users and researchers.

synthline_ai-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: Feature Request / Defect Generator Proposal
+description: Suggest an idea, defect generator, or workflow enhancement for SynthLine AI
+title: "[FEATURE] <title>"
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        We welcome feature suggestions and ideas for new defect generation algorithms!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: A clear and concise description of the motivation (e.g. need realistic paint bubble defects).
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Describe the Solution / Feature
+      description: Clear description of the proposed functionality, defect generation behavior, or export capability.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions or workarounds you've considered.
+  - type: dropdown
+    id: category
+    attributes:
+      label: Area / Category
+      options:
+        - Procedural Generator (Defect type)
+        - Ingestion & QA Checks
+        - Labeling & Masks
+        - Dataset Export (COCO, YOLO, etc.)
+        - Validation & Statistics
+        - CLI & Developer Experience
+        - Web / API Interface
+    validations:
+      required: true

synthline_ai-0.1.0/.github/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported Versions
+
+SynthLine AI is actively maintained. Security updates and patches are provided for the following releases:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+| < 0.1   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security and privacy of visual inspection datasets and codebases seriously.
+
+If you believe you have discovered a security vulnerability in SynthLine AI:
+
+1. **Do not** open a public issue.
+2. Please privately report the issue via GitHub's [Private Vulnerability Reporting](https://github.com/thrivecodes/synthline-ai/security/advisories/new) or contact the core maintainers directly.
+3. Include detailed steps to reproduce the issue, proof of concept, and any affected configurations.
+
+We aim to acknowledge reports within 48 hours and provide remediation or mitigation updates promptly.

synthline_ai-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Description
+
+Please describe the changes in this pull request and the rationale behind them.
+
+- Fixes #(issue)
+- Implements #(feature)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Code quality / refactoring / typing
+
+## Verification Checklist
+
+- [ ] My code follows the code style of this project (`ruff check .`, `ruff format --check .`)
+- [ ] I have added type annotations compatible with `mypy --strict`
+- [ ] I have added or updated unit/integration tests for my changes
+- [ ] All tests pass locally (`pytest`)
+- [ ] I have generated test outputs or verified reproducibility where applicable
+- [ ] I have updated relevant documentation / docstrings

synthline_ai-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-typecheck:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run Ruff Linting
+        run: ruff check src tests
+
+      - name: Run Ruff Formatting Check
+        run: ruff format --check src tests
+
+      - name: Run Mypy Type Check
+        run: mypy src
+
+  test:
+    name: Test Suite (Python ${{ matrix.python-version }} on ${{ matrix.os }})
+    needs: lint-and-typecheck
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run Pytest with Coverage
+        run: |
+          pytest -v --cov=synthline_ai --cov-report=xml --cov-report=term-missing tests/
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

synthline_ai-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,38 @@
+name: "CodeQL Analysis"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '0 6 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze Python Code
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        continue-on-error: true
+        with:
+          category: "/language:${{matrix.language}}"

synthline_ai-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify distributions with Twine
+        run: twine check dist/*
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build, github-release]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/synthline-ai
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

synthline_ai-0.1.0/.gitignore

@@ -0,0 +1,128 @@
+# ==============================================================================
+# Comprehensive .gitignore for SynthLine AI (Python / Computer Vision / ML)
+# ==============================================================================
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.dylib
+*.dll
+
+# C extensions
+*.obj
+*.o
+*.a
+*.lib
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+.conda/
+conda-env/
+
+# Installer logs & pip cache
+pip-log.txt
+pip-delete-this-directory.txt
+.pip-cache/
+
+# Unit test / coverage reporting
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Type checking / Linters
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# IDE & Editors
+.vscode/
+!.vscode/settings.json.example
+!.vscode/launch.json.example
+.idea/
+*.swp
+*.swo
+*~
+*.sublime-workspace
+*.sublime-project
+.project
+.pydevproject
+.settings/
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+[Dd]esktop.ini
+$RECYCLE.BIN/
+
+# Environment variables & secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.cert
+*.crt
+secrets.yaml
+secrets.json
+
+# SynthLine AI local run artifacts, seed caches & dataset outputs
+runs/
+exports/
+data/
+datasets/
+output/
+outputs/
+*.coco.json.bak
+*.yolo.bak
+benchmark_results/
+wandb/
+.tensorboard/

synthline_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-17
+
+### Added
+- **Production Packaging & PyPI Release Readiness**:
+  - Full PyPI specification with standard metadata, Trove classifiers, Apache-2.0 license, and project URLs.
+  - Sdist and wheel distribution packages verified clean by `twine check`.
+- **Standalone Dataset Exporter (`synthline-ai export`)**:
+  - CLI command converting existing generation runs into COCO JSON, YOLO format (`data.yaml`), or both, without re-executing generation.
+  - Automatic mask resolution supporting both direct and prefixed naming conventions.
+- **Interactive HTML Visual Inspector (`preview.html`)**:
+  - Self-contained, responsive dataset inspection gallery generated with each run.
+  - Interactive mode toggles (Generated Image vs. Mask Overlay), split filtering (Train, Val, Test), and defect metric badges.
+- **Curated Benchmarks & Example Utilities**:
+  - `examples/generate_sample_seeds.py`: Pure procedural generators for realistic industrial surfaces (brushed metal, polished ceramic, matte polymer).
+  - `examples/quickstart_pipeline.py`: Complete zero-mock Python API demonstration from seed loading to export and evaluation.
+  - `benchmarks/benchmark_sim2real.py`: Reproducible throughput and probe-model sim-to-real evaluation suite.
+- **Phase 4 Validation & Proof, Probe Models & Defect Variability**:
+  - `validation/probe_models.py`: 16-feature computer vision extraction pipeline, lightweight gradient boosting probe classifier measuring sim-to-real performance gap against real held-out inspection samples, and dataset feature diversity/variance scoring.
+  - `generation/procedural/variability.py`: `apply_defect_variability` applying per-defect HSV color shifts, opacity jitter, and morphological boundary roughness.
+  - Enhanced Quality Checks & Statistics in `validation/checks.py` & `validation/statistics.py`:
+    - Output image duplicate and near-duplicate detection via 64-bit dHash perceptual hashing.
+    - Distribution analysis for image brightness and contrast with statistical outlier identification (>2σ).
+    - Data partition leakage verification ensuring zero cross-split seed contamination.
+    - Per-split summary metrics and partition balance verification (`compute_split_statistics`).
+  - CLI `synthline-ai probe`: Command for evaluating generated dataset directories against real labeled reference images.
+  - `deduplication.py`: 64-bit perceptual difference hashing (`dHash`) and Hamming distance analysis detecting exact and near-duplicate seed images during ingestion QA.
+  - `randomization/lighting.py`: Directional illumination gradients, vignetting, and light falloff simulation matching factory line illumination shifts.
+  - `randomization/texture.py`: High-frequency sensor noise and low-frequency surface roughness micro-variations.
+  - `randomization/geometry.py`: Sub-pixel affine translations and micro-rotations keeping image and defect mask in strict pixel-perfect alignment.
+  - CLI options: `--variations`, `--lighting`, `--texture`, `--geometry` for generation customization.
+- **Phase 2 Local User Experience & Studio**:
+  - `synthline-ai ui`: Local web studio server command launching FastAPI/Uvicorn interface.
+  - Interactive Browser Studio UI: Adheres to SynthLine visual design tokens (warm editorial `#f5f4ef` palette, sans-serif typography, responsive sidebar/workspace grid).
+  - Project Workspace Management: Creation, deletion, listing, and inspection of defect datasets via `ProjectManager`.
+  - Drag-and-Drop Ingestion: Direct browser seed uploads with automatic Laplacian blur, brightness, and dimension quality checks.
+  - Interactive Generation Configuration: Real-time defect selection, count, severity, frequency, dataset splitting, and export format controls.
+  - Visual Contact Sheet Previews: Direct rendered contact sheets with mask overlay previews inside the studio interface.
+  - 1-Click ZIP Dataset Bundles: Complete ZIP archive downloads including images, binary masks, COCO annotations, YOLO datasets (`data.yaml`), and `report.json`.
+  - Comprehensive REST API endpoints (`/api/projects`, `/api/projects/{id}/seeds`, `/api/projects/{id}/runs`, `/api/projects/{id}/runs/{run_id}/download`, `/api/info`).
+- **Phase 1 Procedural Defect Generators**:
+  - `StainGenerator`: Organic splatter and liquid blotch generation with deformed polygonal geometry, edge-feathering Gaussian blur, natural color shifts, and precise binary masks.
+  - `DiscolorationGenerator`: Thermal discoloration, oxidation patina, and color bleaching via HSV color space transforms and elliptic gradient profiles.
+  - Frequency & Severity Controls: Dynamic stroke/spot density control (`frequency`) and defect strength scaling (`severity`).
+- **Seed-Aware Dataset Splitting (Leak Prevention)**:
+  - Source seeds are partitioned into disjoint `train`/`val`/`test` sets *before* generation variants are created, strictly preventing data leakage between splits.
+- **YOLO Dataset Export**:
+  - `export_yolo`: Normalized coordinate bounding boxes (`[x_center, y_center, width, height]`), partitioned image/label directories, and `data.yaml` specification.
+  - CLI support for format selection (`--format coco`, `--format yolo`, `--format all`).
+- **CLI Enhancements**:
+  - Added CLI options: `--defect {scratch,stain,discoloration}`, `--frequency`, `--format`, `--split`, `--train-ratio`, `--val-ratio`, `--test-ratio`.
+- **Phase 0 Foundation (Initial)**:
+  - Core ingestion engine with Laplacian blur analysis and brightness checks.
+  - Procedural scratch generator with curve interpolation.
+  - COCO annotation and metadata export.
+  - Contact sheet previews and dataset-level statistical validation.
+  - Comprehensive `.gitignore`, GitHub CI/CD matrix workflows, CodeQL security checks, release automation, and `CODEOWNERS` mapping.