If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/lengstrom/fast-style-transfer shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Stale and unlicensed — last commit 3y ago

• 16 active contributors
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 54% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live lengstrom/fast-style-transfer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/lengstrom/fast-style-transfer.

What it runs against: a local clone of lengstrom/fast-style-transfer — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in lengstrom/fast-style-transfer | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 1056 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lengstrom/fast-style-transfer. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lengstrom/fast-style-transfer.git
#   cd fast-style-transfer
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of lengstrom/fast-style-transfer and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "lengstrom/fast-style-transfer(\\.git)?\\b" \\
  && ok "origin remote is lengstrom/fast-style-transfer" \\
  || miss "origin remote is not lengstrom/fast-style-transfer (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "style.py" \\
  && ok "style.py" \\
  || miss "missing critical file: style.py"
test -f "src/transform.py" \\
  && ok "src/transform.py" \\
  || miss "missing critical file: src/transform.py"
test -f "src/optimize.py" \\
  && ok "src/optimize.py" \\
  || miss "missing critical file: src/optimize.py"
test -f "src/vgg.py" \\
  && ok "src/vgg.py" \\
  || miss "missing critical file: src/vgg.py"
test -f "evaluate.py" \\
  && ok "evaluate.py" \\
  || miss "missing critical file: evaluate.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1056 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1026d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/lengstrom/fast-style-transfer"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A TensorFlow-based CNN implementation that applies artistic style transfer from famous paintings to photos and videos in real-time (~100ms on a Titan X for 1024×680 images). It combines three key papers: Gatys' neural style algorithm, Johnson's perceptual losses for fast transfer, and Ulyanov's instance normalization to enable feed-forward style application rather than optimization-based approaches. Flat structure: style.py and transform_video.py are entry points at root level; src/ contains core modules (optimize.py for training, transform.py for inference, vgg.py for VGG19 feature extraction, utils.py for helpers). examples/ holds reference images (content, style, results, thumbs). setup.sh for environment configuration.

Computer vision researchers, artists, and developers who want to stylize images/videos with pre-trained style models without running expensive iterative optimization. Users who need sub-second inference on GPUs for interactive or batch processing applications.

Moderately mature but historical: the project is from 2016 and uses TensorFlow 1.x paradigms. No active commits visible in recent data, no CI/CD pipeline shown, and no test suite in file listing. It's a well-cited research implementation that works reliably for its specific use case but is not actively maintained.

Single-maintainer project (Logan Engstrom) with a custom academic license restricting commercial use. TensorFlow 1.x dependency likely creates compatibility issues with modern TF 2.x ecosystems. No visible test coverage or automated quality checks. Dependency freshness unknown from provided data.

No active development visible from file list. This is a stable, archived research artifact. The project demonstrates completed work rather than ongoing development.

Clone: git clone https://github.com/lengstrom/fast-style-transfer.git && cd fast-style-transfer. Install: bash setup.sh (sets up TensorFlow environment). Verify: python evaluate.py --checkpoint examples/style/udnie --in-path examples/content/stata.jpg --out-path /tmp/styled.jpg.

Daily commands: python style.py --style examples/style/udnie.jpg --train-path examples/content/ --checkpoint-dir checkpoints/ --test examples/content/stata.jpg (trains a new model). For inference: python evaluate.py --checkpoint checkpoints/fns.ckpt --in-path input.jpg --out-path output.jpg. For video: python transform_video.py --in-path input.mp4 --checkpoint checkpoints/fns.ckpt --out-path output.mp4.

• style.py — Main entry point for training style transfer models; orchestrates the entire training pipeline and model checkpoint saving.
• src/transform.py — Core feed-forward network that applies learned style transformations to input images; the inference engine used in production.
• src/optimize.py — Implements the training optimization loop including perceptual loss computation and gradient descent; critical for model convergence.
• src/vgg.py — Loads pre-trained VGG-16 network used for perceptual loss calculation; foundational to the style transfer algorithm.
• evaluate.py — Inference interface that applies trained models to images and videos; the user-facing evaluation module.
• transform_video.py — Video stylization pipeline; extends image stylization to frame sequences with optional optical flow handling.
• src/utils.py — Shared utilities for image I/O, preprocessing, and tensor operations; used across all modules.

• Transform Network (src/transform.py) (TensorFlow, residual blocks, instance normalization) — Learned CNN that maps content → styled output; core inference engine trained per style
  • Failure mode: Poorly trained model → generic or distorted output; insufficient training data → mode collapse to single style
• VGG Feature Extractor (src/vgg.py) (TensorFlow, VGG-16, ImageNet weights) — Pre-trained ImageNet network; computes perceptual loss to ensure style & content matching during training
  • Failure mode: Missing weights file → cannot compute loss, training fails; incompatible TF version → weight loading errors
• Optimization Loop (src/optimize.py) (TensorFlow optimizer (Adam), loss functions, gradient computation) — Gradient descent trainer; balances style loss, content loss, and regularization to minimize perceptual distance
  • Failure mode: Diverging loss → unstable training; learning rate too high → oscillation; too low → slow convergence
• Inference Pipeline (evaluate.py, transform_video.py) (TensorFlow session management, image I/O (PIL/scipy)) — User-facing APIs; loads trained checkpoint and applies stylization to single images or video streams
  • Failure mode: Corrupted checkpoint → model load fails; unsupported image format → preprocessing error; OOM → batch too large
• Utilities (src/utils.py) (NumPy, PIL, SciPy) — Image loading, resizing, normalization, denormalization, tensor conversions
  • Failure mode: Missing dependencies → import error; invalid image path → file not found; incompatible dimensions → shape mismatch in network

• User input (image/video file) → src/utils.py — Load and preprocess image to normalized tensor [1, H, W, 3], resize if needed
• src/utils.py → src/transform.py (trained model) — Pass normalized tensor through feed-forward network for style transfer
• src/transform.py output → src/utils.py — Denormalize and clip output tensor back to valid image range [0, 255]
• src/utils.py → Output image/video file — Encode tensor to JPEG/PNG/MP4 and write to disk
• Content + style images (training) → src/optimize.py — Load training batch

Train a new style transfer model

1. Prepare training data directories (content images and style reference image) (style.py)
2. Run style.py with --style, --content, --output flags to train the model (style.py)
3. Model checkpoint will be saved to the output directory; verify loss curves converged (src/optimize.py)

Stylize a new image or video

1. For images, run evaluate.py with --model and --input-image flags (evaluate.py)
2. For videos, run transform_video.py with --model and --input-video flags instead (transform_video.py)
3. Output is saved to specified directory; stylization is single-pass, ~100ms per image (evaluate.py)

Modify the style transfer network architecture

1. Edit the residual block definitions and upsampling layers in transform.py (src/transform.py)
2. Ensure input/output tensor shapes remain compatible with src/optimize.py loss computation (src/optimize.py)
3. Re-run training with modified architecture; monitor convergence via loss logs (style.py)

Add a new perceptual loss layer or feature extractor

1. Modify vgg.py to add new layer hooks or use a different pre-trained network (src/vgg.py)
2. Update optimize.py to compute losses from new feature layers (src/optimize.py)
3. Retrain models with new loss weights to evaluate impact (style.py)

• TensorFlow (1.x) — Enables efficient GPU-accelerated CNN inference and training; VGG-16 pre-trained weights readily available; mature at time of project (2016)
• VGG-16 (pre-trained ImageNet) — Provides rich perceptual features for loss computation without needing style-specific labels; standard in neural style transfer literature
• Instance Normalization (Ulyanov et al.) — Stabilizes training and reduces batch-size dependency; enables faster convergence vs batch normalization for style transfer
• Residual block architecture — Allows deep networks to train effectively; preserves content structure while applying style transformations

• Single feed-forward pass (no recurrence, no iterative refinement)

  • Why: Enables real-time inference (~100ms); necessary for practical video stylization
  • Consequence: Lower stylization quality than iterative optimization methods (e.g., LBFGS); traded quality for speed per project goal

• Frame-by-frame video processing without optical flow by default

  • Why: Simpler implementation; works across diverse content
  • Consequence: Possible temporal flicker in videos; users can enable flow-based smoothing but at computational cost

• Pre-trained VGG-16 frozen (not fine-tuned)

  • Why: Reduces training time and data requirements; VGG features generalize well
  • Consequence: Loss function is fixed to ImageNet-learned features; may not perfectly align with human style perception

• Per-image inference with no batch processing utility exposed

  • Why: Simpler API for end-users; matches typical deployment scenario
  • Consequence: Cannot easily batch multiple images for higher throughput; each image is a separate graph execution

• Real-time style transfer in video playback (targets post-hoc stylization only)
• Interactive style transfer (no live preview during training)
• Support for arbitrary audio with styled video output
• Cross-domain style transfer (requires training a new model per style)
• Web UI or REST API (command-line interface only)

TensorFlow version lock: Code assumes TF 1.x (likely uses tf.Session, tf.placeholder, static graphs) — TF 2.x eager execution will break it. Model checkpoint format: .ckpt files are TF 1.x binary format; requires matching TensorFlow version to load. VGG19 weights: Code likely downloads pre-trained weights on first run — requires internet and disk space. GPU requirement: Inference shown as ~100ms on Titan X; CPU inference will be orders of magnitude slower. No batch processing in evaluate.py visible — single-image or single-video frame approach may be inefficient at scale.

• Gram Matrix — Core to style representation in this project — the optimize.py loss function uses Gram matrices of VGG feature maps to capture painting style independent of content, making the loss function possible
• Perceptual Loss (Feature-Space Loss) — Johnson's key innovation used in optimize.py — comparing activations in VGG layers rather than raw pixel values allows realistic stylization without blurriness, core to why this is 'fast'
• Instance Normalization — Ulyanov's technique applied in transform.py for the generator network — replaces batch norm to make stylization independent of batch statistics, critical for per-image consistency
• Residual Networks (ResNets) — The feed-forward generator in transform.py uses residual blocks (skip connections) to preserve content detail while applying style, enabling realistic output
• Total Variation Loss — Included in optimize.py's loss function to smooth artifacts and reduce noise in generated images; prevents checkerboard patterns in output
• Feed-Forward Network (vs. Optimization-Based) — This entire project exists because Johnson's insight was to replace iterative pixel optimization (slow) with a single forward pass through a CNN (fast); understand this distinction to grasp why style.py trains once then evaluate.py runs instantly
• VGG19 Feature Extraction — vgg.py uses pre-trained VGG19 layers (relu3_4, relu4_4, etc.) to extract semantic content and style statistics; these specific layers are proven optimal for style transfer by Gatys et al.

• jcjohnson/fast-neural-style — Johnson's original Torch-based fast style transfer (one of the three papers this repo is based on); the reference implementation
• openai/clip — Modern alternative using CLIP embeddings for content preservation in style transfer; represents the next-generation approach
• facebookresearch/pix2pixHD — Generative model for high-quality image-to-image translation; related feed-forward architecture for visual synthesis

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for src/utils.py and src/transform.py

The repo lacks any visible test files (.py test files in tests/ or similar). Given that src/utils.py and src/transform.py contain core utility and image transformation logic, adding comprehensive unit tests would improve reliability and make it easier for contributors to catch regressions. This is especially important for image processing code where subtle bugs can be hard to spot visually.

• [ ] Create tests/ directory with init.py
• [ ] Add test_utils.py covering functions in src/utils.py (e.g., image loading, preprocessing)
• [ ] Add test_transform.py covering core transformation logic in src/transform.py
• [ ] Add pytest configuration (pytest.ini or setup.cfg with test discovery rules)
• [ ] Document test running instructions in README.md
• [ ] Ensure tests can be run via pytest or similar standard command

Add GitHub Actions workflow for model inference validation

The repo has .github/FUNDING.yml but no visible CI/CD workflows. Adding a GitHub Action that validates the pre-trained style transfer models work end-to-end would catch model corruption or dependency breakage early. Given that style.py, transform.py, and evaluate.py exist, a workflow could run inference on an example image and verify output shape/quality.

• [ ] Create .github/workflows/inference-test.yml
• [ ] Workflow should: download or use example content from examples/content/
• [ ] Load a pre-trained model and run transform.py on a test image
• [ ] Verify output image dimensions and that processing completes without error
• [ ] Add basic sanity checks (output file exists, is valid image format, non-zero size)
• [ ] Document in docs.md or README.md how to run the workflow locally

Add comprehensive README section for evaluate.py with example commands

evaluate.py exists in the root but docs.md and README.md don't explain how to use it, what metrics it computes, or provide example invocations. Contributors trying to validate trained models or compare style transfer quality lack clear guidance. This is a specific gap preventing evaluation workflow adoption.

• [ ] Review evaluate.py to understand its inputs, metrics, and outputs
• [ ] Add 'Evaluation' section to README.md with purpose statement
• [ ] Provide 2-3 concrete example commands showing: (a) evaluating on examples/content/, (b) interpreting output metrics
• [ ] Document required arguments and optional flags
• [ ] Link to or explain how evaluate.py relates to the papers cited (Gatys, Johnson, Ulyanov)
• [ ] Consider adding a code snippet showing typical eval workflow in docs.md

• Add unit tests for src/utils.py and src/transform.py — currently no test/ directory visible, making refactoring risky. Start by writing tests for feed-forward inference and argument parsing.
• Port evaluate.py to TensorFlow 2.x eager execution — would unblock modern Python/TF stacks and reduce maintenance burden. Document the API changes required.
• Add batch image stylization to evaluate.py — README shows single-image example but real-world users often process directories; implement --in-path /dir/ --recursive with batching for throughput gains.

The codebase presents moderate security concerns primarily related to missing dependency management, insufficient input validation, and unsafe model loading practices. The project is a machine learning application focused on style transfer without explicit security hardening. Critical gaps include: (1) no visible dependency pinning mechanism, (2) potential arbitrary file read vulnerabilities in image/video processing, (3) unsafe TensorFlow model loading from untrusted sources, and (4) no resource limits to prevent denial of service. The absence of a security policy and input validation across multiple entry points are significant concerns. Recommended actions: establish strict dependency management, implement comprehensive input validation, add resource limits, verify model sources, and create security documentation.

• High · Missing Dependency Pinning and Package File — Repository root - missing requirements.txt or setup.py. No package dependency file (requirements.txt, setup.py, or Pipfile) was provided for analysis. This makes it impossible to verify if the project uses outdated or vulnerable versions of TensorFlow and other dependencies. The project relies on TensorFlow which has a history of security vulnerabilities. Fix: Create and maintain a requirements.txt file with pinned versions of all dependencies. Regularly update and audit dependencies using tools like 'pip-audit' or 'safety'. Specify minimum and maximum version constraints to prevent uncontrolled updates.
• Medium · Potential Arbitrary File Read via Model Loading — src/transform.py, evaluate.py, style.py, transform_video.py. The evaluate.py, transform.py, and style.py files likely load TensorFlow models and process user-supplied images without visible input validation. Arbitrary file paths could be passed to image processing functions, potentially exposing sensitive files on the system. Fix: Implement strict input validation on file paths. Use whitelisting for allowed directories. Avoid allowing arbitrary file paths from user input. Validate file types and sizes before processing. Consider using secure file handling libraries.
• Medium · Missing Input Validation on Video Processing — transform_video.py. The transform_video.py file processes video files without visible security checks. Malformed or malicious video files could potentially trigger buffer overflows or denial of service through resource exhaustion (memory, CPU, disk space). Fix: Add file size limits and format validation before processing. Implement timeout mechanisms for processing. Validate video codec and container formats. Add resource limits (memory, CPU) for long-running operations.
• Medium · Unsafe Model Serialization (TensorFlow) — src/optimize.py, src/transform.py, src/vgg.py. The project uses TensorFlow for model loading. Without explicit verification, untrusted .pb or checkpoint files could execute arbitrary code if loaded from untrusted sources, as TensorFlow models can contain serialized Python code. Fix: Only load models from trusted sources with cryptographic verification (checksums/signatures). Disable custom Python operations if not needed. Use TensorFlow's SavedModel format with strict validation. Implement model source verification mechanisms.
• Low · Missing Security Documentation — Repository root. No security policy (SECURITY.md) or vulnerability disclosure guidelines are present in the repository. Users cannot easily report security issues, and security best practices for users are not documented. Fix: Create a SECURITY.md file with vulnerability reporting guidelines and contact information. Document security best practices for users (e.g., model source verification, input validation).
• Low · Potential Resource Exhaustion Risk — style.py, transform_video.py, evaluate.py. No visible rate limiting, resource quotas, or maximum input size constraints in the style transfer scripts. Large images, videos, or batch operations could lead to denial of service through memory exhaustion or excessive computation. Fix: Implement maximum file size limits. Add memory usage monitoring and limits. Implement timeout mechanisms. Document resource requirements and limitations for users.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.