crayonmlx 0.1.0a1__py3-none-any.whl

crayonmlx/__init__.py

@@ -0,0 +1,3 @@
+"""CrayonMLX — a local drawing transformation studio for Apple Silicon."""
+
+__version__ = "0.1.0a1"

crayonmlx/__main__.py

@@ -0,0 +1,3 @@
+from crayonmlx.cli import main
+
+main()

crayonmlx/app.py

@@ -0,0 +1,134 @@
+"""Application composition: construct services once and close workers on shutdown."""
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from crayonmlx.engines.registry import default_engines
+from crayonmlx.generation.queue import GenerationQueue
+from crayonmlx.models.downloads import Downloads
+from crayonmlx.models.runtime import ModelRuntime
+from crayonmlx.paths import data_directory
+from crayonmlx.presets.library import ConfigRepository, PromptRepository
+from crayonmlx.presets.repository import PresetRepository
+from crayonmlx.storage.database import Database
+from crayonmlx.storage.secrets import TokenStore
+from crayonmlx.web.folders import router as folders_router
+from crayonmlx.web.library_routes import router as library_router
+from crayonmlx.web.model_routes import router as model_router
+from crayonmlx.web.routes import router
+from crayonmlx.web.storage_routes import router as storage_router
+
+
+@dataclass
+class Services:
+    root: Path
+    database: Database
+    presets: PresetRepository
+    prompts: PromptRepository
+    configs: ConfigRepository
+    tokens: TokenStore
+    engines: dict
+    queue: GenerationQueue
+    downloads: Downloads
+    runtime: ModelRuntime
+
+
+def create_app(data_dir: Path | None = None, engines: dict | None = None) -> FastAPI:
+    @asynccontextmanager
+    async def lifespan(app):
+        root = (data_dir or data_directory()).resolve()
+        database = Database(root)
+        runtime = ModelRuntime(root / "runtime", database.settings)
+        registry = engines if engines is not None else default_engines(runtime)
+        tokens = TokenStore(root)
+        queue = GenerationQueue(database, registry)
+        downloads = Downloads(tokens)
+        app.state.services = Services(
+            root,
+            database,
+            PresetRepository(root),
+            PromptRepository(root),
+            ConfigRepository(root),
+            tokens,
+            registry,
+            queue,
+            downloads,
+            runtime,
+        )
+        try:
+            yield
+        finally:
+            queue.close()
+            runtime.close()
+            downloads.close()
+
+    app = FastAPI(title="CrayonMLX", lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None)
+    app.add_middleware(TrustedHostMiddleware, allowed_hosts=["localhost", "127.0.0.1", "[::1]", "testserver"])
+
+    write_lock = asyncio.Lock()
+    app.state.pending_data_dir = None
+
+    @app.middleware("http")
+    async def local_requests(request: Request, call_next):
+        # Local disk operations must not be triggered by a form on a remote website.
+        if request.method not in {"GET", "HEAD", "OPTIONS"}:
+            origin = request.headers.get("origin")
+            if (origin and origin != str(request.base_url).rstrip("/")) or request.headers.get(
+                "sec-fetch-site"
+            ) == "cross-site":
+                return JSONResponse(
+                    {"detail": "Разрешены только запросы из локального интерфейса"}, status_code=403
+                )
+        if request.method not in {"GET", "HEAD", "OPTIONS"}:
+            async with write_lock:
+                if app.state.pending_data_dir:
+                    return JSONResponse(
+                        {
+                            "detail": "Папка данных перенесена. Перезапустите CrayonMLX, чтобы продолжить работу."
+                        },
+                        status_code=409,
+                    )
+                response = await call_next(request)
+        else:
+            response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Content-Security-Policy"] = (
+            "default-src 'self'; img-src 'self' blob:; style-src 'self'; script-src 'self'; frame-ancestors 'none'"
+        )
+        return response
+
+    @app.exception_handler(ValueError)
+    async def invalid_value(request, error):
+        return JSONResponse({"detail": str(error)}, status_code=422)
+
+    @app.exception_handler(OSError)
+    async def filesystem_error(request, error):
+        logging.getLogger(__name__).exception("Filesystem operation failed")
+        return JSONResponse(
+            {
+                "detail": "Не удалось прочитать или записать файл. Проверьте путь, права доступа и свободное место."
+            },
+            status_code=400,
+        )
+
+    web = Path(__file__).parent / "web"
+    app.include_router(router)
+    app.include_router(library_router)
+    app.include_router(folders_router)
+    app.include_router(model_router)
+    app.include_router(storage_router)
+    app.mount("/static", StaticFiles(directory=web / "static"), name="static")
+
+    @app.get("/")
+    def index():
+        return FileResponse(web / "index.html")
+
+    return app

crayonmlx/cli.py

@@ -0,0 +1,12 @@
+"""Local-only application entry point."""
+
+import argparse
+
+import uvicorn
+
+
+def main():
+    parser = argparse.ArgumentParser(description="CrayonMLX — локальная студия для рисунков")
+    parser.add_argument("--port", type=int, default=8787)
+    arguments = parser.parse_args()
+    uvicorn.run("crayonmlx.app:create_app", factory=True, host="127.0.0.1", port=arguments.port)

crayonmlx/engines/__init__.py

@@ -0,0 +1 @@
+"""CrayonMLX engines components."""

crayonmlx/engines/base.py

@@ -0,0 +1,17 @@
+"""Render contract. Adapters render through the application-owned model runtime."""
+
+from pathlib import Path
+from typing import Protocol
+
+from crayonmlx.schemas import Preset
+
+
+class RenderEngine(Protocol):
+    id: str
+    name: str
+    base_models: tuple[str, ...]
+    supports_strength: bool
+
+    def available(self) -> bool: ...
+
+    def render(self, preset: Preset, model: Path, source: Path, output: Path) -> dict | None: ...

crayonmlx/engines/mflux.py

@@ -0,0 +1,91 @@
+"""MFLUX CLI adapters run in isolated processes so Metal memory is released per job."""
+
+import os
+import platform
+import subprocess
+import sys
+from importlib.util import find_spec
+from pathlib import Path
+
+from crayonmlx.schemas import Preset
+
+
+class MfluxEngine:
+    def __init__(self, runtime=None):
+        self.runtime = runtime
+
+    def available(self) -> bool:
+        return (
+            platform.system() == "Darwin" and platform.machine() == "arm64" and find_spec("mflux") is not None
+        )
+
+    def command(self, preset: Preset, model: Path, source: Path, output: Path) -> list[str]:
+        parameters = preset.parameters
+        return [
+            sys.executable,
+            "-m",
+            self.module,
+            "--model",
+            str(model),
+            "--base-model",
+            preset.base_model,
+            "--prompt",
+            preset.blocks.compose(),
+            "--seed",
+            str(parameters.seed),
+            "--steps",
+            str(parameters.steps),
+            "--width",
+            str(parameters.width),
+            "--height",
+            str(parameters.height),
+            *(["--quantize", str(parameters.quantize)] if parameters.quantize is not None else []),
+            "--output",
+            str(output),
+            *self.image_arguments(preset, source),
+        ]
+
+    def render(self, preset: Preset, model: Path, source: Path, output: Path) -> dict | None:
+        if not self.available():
+            raise RuntimeError("Нужен Mac Apple Silicon и MFLUX. Установите: uv sync или uv tool install .")
+        if self.runtime is not None:
+            return self.runtime.render(self, preset, model, source, output)
+        # Generation must never trigger implicit network access or ignore missing weights.
+        environment = {**os.environ, "HF_HUB_OFFLINE": "1", "TRANSFORMERS_OFFLINE": "1"}
+        log = output.with_suffix(".log")
+        with log.open("w", encoding="utf-8") as stream:
+            result = subprocess.run(
+                self.command(preset, model, source, output),
+                env=environment,
+                stdout=stream,
+                stderr=subprocess.STDOUT,
+                check=False,
+            )
+        if result.returncode or not output.is_file():
+            tail = log.read_text(encoding="utf-8", errors="replace")[-3000:]
+            raise RuntimeError(f"MFLUX не завершил генерацию. Проверьте полноту и тип модели.\n{tail}")
+
+
+class FluxEngine(MfluxEngine):
+    id = "mflux-flux"
+    name = "MFLUX · FLUX.1 image-to-image"
+    module = "mflux.models.flux.cli.flux_generate"
+    base_models = ("dev", "schnell", "krea-dev")
+    supports_strength = True
+
+    def image_arguments(self, preset: Preset, source: Path) -> list[str]:
+        result = ["--image-path", str(source), "--image-strength", str(preset.parameters.image_strength)]
+        if preset.base_model != "schnell":
+            result += ["--guidance", str(preset.parameters.guidance)]
+        return result
+
+
+class QwenEditEngine(MfluxEngine):
+    id = "mflux-qwen-edit"
+    name = "MFLUX · Qwen Image Edit"
+    module = "mflux.models.qwen.cli.qwen_image_edit_generate"
+    base_models = ("qwen-image-edit-2511", "qwen-image-edit")
+    supports_strength = False
+
+    def image_arguments(self, preset: Preset, source: Path) -> list[str]:
+        return ["--image-paths", str(source), "--guidance", str(preset.parameters.guidance)]

crayonmlx/engines/process.py

@@ -0,0 +1,59 @@
+"""Process transport, independent of model lifecycle and GPU imports."""
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from uuid import uuid4
+
+
+class WorkerProcess:
+    def __init__(self, root: Path):
+        self.root = root / uuid4().hex
+        self.root.mkdir(parents=True)
+        self.log = (self.root / "worker.log").open("w", encoding="utf-8")
+        self.process = subprocess.Popen(
+            [sys.executable, "-m", "crayonmlx.engines.worker", str(self.root)],
+            stdin=subprocess.PIPE,
+            stdout=self.log,
+            stderr=subprocess.STDOUT,
+            text=True,
+            env={**os.environ, "HF_HUB_OFFLINE": "1", "TRANSFORMERS_OFFLINE": "1"},
+        )
+
+    def request(self, payload):
+        identifier = uuid4().hex
+        response = self.root / f"{identifier}.json"
+        self.process.stdin.write(json.dumps({**payload, "request_id": identifier}) + "\n")
+        self.process.stdin.flush()
+        while not response.exists():
+            if self.process.poll() is not None:
+                tail = (self.root / "worker.log").read_text(encoding="utf-8", errors="replace")[-2000:]
+                raise RuntimeError(f"Процесс MLX остановился.\n{tail}")
+            time.sleep(0.1)
+        result = json.loads(response.read_text())
+        response.unlink()
+        if not result["ok"]:
+            raise RuntimeError(result["error"])
+        return result
+
+    def snapshot(self):
+        path = self.root / "status.json"
+        return json.loads(path.read_text()) if path.exists() else {}
+
+    def alive(self):
+        return self.process.poll() is None
+
+    def close(self):
+        if self.process.poll() is None:
+            self.process.terminate()
+            try:
+                self.process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                self.process.kill()
+                self.process.wait()
+        if self.process.stdin:
+            self.process.stdin.close()
+        self.log.close()

crayonmlx/engines/registry.py

@@ -0,0 +1,20 @@
+"""Explicit registry: new engines implement the contract without changing the queue."""
+
+from crayonmlx.engines.base import RenderEngine
+from crayonmlx.engines.mflux import FluxEngine, QwenEditEngine
+from crayonmlx.schemas import Preset
+
+
+def default_engines(runtime=None) -> dict[str, RenderEngine]:
+    return {engine.id: engine for engine in (FluxEngine(runtime), QwenEditEngine(runtime))}
+
+
+def validate_engine(engines: dict[str, RenderEngine], preset: Preset) -> RenderEngine:
+    engine = engines.get(preset.engine)
+    if engine is None:
+        raise ValueError("Неизвестный движок")
+    if preset.base_model not in engine.base_models:
+        raise ValueError("Базовая модель несовместима с выбранным движком")
+    if not preset.blocks.compose():
+        raise ValueError("Заполните хотя бы один блок промпта")
+    return engine

crayonmlx/engines/worker.py

@@ -0,0 +1,137 @@
+"""Persistent MLX process. Commands arrive on stdin; atomic files carry responses/status."""
+
+import gc
+import json
+import sys
+import threading
+import time
+import traceback
+from pathlib import Path
+
+from crayonmlx.schemas import Preset
+
+
+class Telemetry:
+    def __init__(self, root, mx):
+        self.root, self.mx = root, mx
+        self.lock = threading.Lock()
+        self.state = {"phase": "starting", "step": 0, "total_steps": None}
+        self.started = None
+        self.stopped = threading.Event()
+        self.thread = threading.Thread(target=self._sample, daemon=True)
+        self.thread.start()
+
+    def update(self, **values):
+        with self.lock:
+            self.state.update(values)
+            self._write()
+
+    def _write(self):
+        state = {
+            **self.state,
+            "memory_active_bytes": self.mx.get_active_memory(),
+            "memory_cache_bytes": self.mx.get_cache_memory(),
+            "memory_peak_bytes": self.mx.get_peak_memory(),
+            "elapsed_seconds": round(time.monotonic() - self.started, 1) if self.started else 0,
+        }
+        temporary = self.root / "status.tmp"
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        temporary.replace(self.root / "status.json")
+
+    def _sample(self):
+        while not self.stopped.wait(1):
+            with self.lock:
+                self._write()
+
+    def call_before_loop(self, config, **kwargs):
+        self.update(
+            phase="denoising", step=0, total_steps=max(0, config.num_inference_steps - config.init_time_step)
+        )
+
+    def call_in_loop(self, t, config, latents, **kwargs):
+        self.mx.eval(latents)  # Report completed work, not just lazily scheduled GPU operations.
+        self.update(phase="denoising", step=t - config.init_time_step + 1)
+
+    def call_after_loop(self, **kwargs):
+        self.update(phase="decoding")
+
+
+def load_model(payload):
+    from mflux.models.common.config import ModelConfig
+
+    config = ModelConfig.from_name(model_name=payload["base_model"])
+    if payload["engine"] == "mflux-flux":
+        from mflux.models.flux.variants.txt2img.flux import Flux1
+
+        model_class = Flux1
+    elif payload["engine"] == "mflux-qwen-edit":
+        from mflux.models.qwen.variants.edit.qwen_image_edit import QwenImageEdit
+
+        model_class = QwenImageEdit
+    else:
+        raise ValueError("Unsupported MLX adapter")
+    return model_class(model_config=config, quantize=payload["quantize"], model_path=payload["model_path"])
+
+
+def render(model, payload):
+    preset = Preset.model_validate(payload["preset"])
+    params = preset.parameters
+    arguments = dict(
+        seed=params.seed,
+        prompt=preset.blocks.compose(),
+        width=params.width,
+        height=params.height,
+        num_inference_steps=params.steps,
+        guidance=params.guidance,
+    )
+    if preset.engine == "mflux-flux":
+        arguments.update(image_path=payload["source"], image_strength=params.image_strength)
+    else:
+        arguments.update(image_paths=[payload["source"]], image_path=payload["source"])
+    image = model.generate_image(**arguments)
+    image.save(path=payload["output"])
+
+
+def main():
+    import mlx.core as mx
+
+    root = Path(sys.argv[1])
+    telemetry = Telemetry(root, mx)
+    model = None
+    try:
+        for line in sys.stdin:
+            payload = json.loads(line)
+            response = root / f"{payload['request_id']}.json"
+            try:
+                if payload["action"] == "load":
+                    telemetry.update(phase="loading", step=0, total_steps=None)
+                    model = load_model(payload)
+                    mx.eval(model.parameters())
+                    model.callbacks.register(telemetry)
+                elif payload["action"] == "render":
+                    if model is None:
+                        raise RuntimeError("Model is not loaded")
+                    telemetry.started = time.monotonic()
+                    mx.reset_peak_memory()
+                    telemetry.update(phase="preparing", step=0, total_steps=None)
+                    render(model, payload)
+                    gc.collect()
+                    mx.clear_cache()
+                else:
+                    raise ValueError("Unknown command")
+                telemetry.update(phase="ready", effective_quantize=getattr(model, "bits", None))
+                result = {"ok": True}
+            except Exception as error:
+                traceback.print_exc()
+                telemetry.update(phase="error")
+                result = {"ok": False, "error": str(error)}
+            temporary = response.with_suffix(".tmp")
+            temporary.write_text(json.dumps(result), encoding="utf-8")
+            temporary.replace(response)
+    finally:
+        telemetry.stopped.set()
+        telemetry.thread.join(timeout=2)
+
+
+if __name__ == "__main__":
+    main()

crayonmlx/generation/__init__.py

@@ -0,0 +1 @@
+"""CrayonMLX generation components."""

crayonmlx/generation/queue.py

@@ -0,0 +1,87 @@
+"""One render worker, durable job snapshots and immutable per-job file locations."""
+
+import json
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+from pathlib import Path
+from secrets import randbelow
+from uuid import uuid4
+
+from crayonmlx.engines.registry import validate_engine
+from crayonmlx.models.catalog import resolve_model
+from crayonmlx.models.identity import identify_model
+from crayonmlx.schemas import GenerationRequest
+from crayonmlx.storage.database import Database
+
+logger = logging.getLogger(__name__)
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class GenerationQueue:
+    def __init__(self, database: Database, engines: dict):
+        self.database = database
+        self.engines = engines
+        self.executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="crayonmlx-render")
+
+    def submit(self, request: GenerationRequest, image) -> dict:
+        request = request.model_copy(deep=True)
+        settings = self.database.settings()
+        model = resolve_model(Path(settings.models_dir), request.model)
+        if not self.database.model_enabled(str(model)):
+            raise ValueError("Модель выключена. Включите её в разделе «Модели».")
+        identity = identify_model(model)
+        request.preset.engine = identity.engine
+        request.preset.base_model = identity.base_model
+        engine = validate_engine(self.engines, request.preset)
+        if request.preset.parameters.seed == -1:
+            request.preset.parameters.seed = randbelow(2**32)
+        identifier = uuid4().hex
+        directory = Path(settings.output_dir) / identifier
+        directory.mkdir(parents=True, exist_ok=False)
+        source, output = directory / "source.png", directory / "result.png"
+        image.save(source, format="PNG")
+        snapshot = request.model_dump()
+        snapshot["model_path"] = str(model)
+        snapshot["prompt"] = request.preset.blocks.compose()
+        metadata = json.dumps(snapshot, ensure_ascii=False, indent=2)
+        (directory / "generation.json").write_text(metadata, encoding="utf-8")
+        self.database.add_job(
+            dict(
+                id=identifier,
+                created_at=now(),
+                status="queued",
+                request=metadata,
+                source=str(source),
+                output=str(output),
+            )
+        )
+        self.executor.submit(self._run, identifier, engine, request.preset, model, source, output)
+        return self.database.job(identifier)
+
+    def _run(self, identifier, engine, preset, model, source, output):
+        self.database.update_job(identifier, status="running", started_at=now())
+        try:
+            if not self.database.model_enabled(str(model)):
+                raise ValueError("Модель была выключена до начала задания")
+            execution = engine.render(preset, model, source, output) or {}
+            if not output.is_file():
+                raise RuntimeError("Движок не сохранил результат")
+            metadata_path = output.with_name("generation.json")
+            metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+            metadata["execution"] = execution
+            temporary = metadata_path.with_suffix(".tmp")
+            temporary.write_text(json.dumps(metadata, ensure_ascii=False, indent=2), encoding="utf-8")
+            temporary.replace(metadata_path)
+            self.database.update_job(
+                identifier, status="completed", finished_at=now(), execution=json.dumps(execution)
+            )
+        except Exception as error:
+            logger.exception("Render failed: %s", identifier)
+            self.database.update_job(identifier, status="failed", error=str(error), finished_at=now())
+
+    def close(self):
+        self.executor.shutdown(wait=True)

crayonmlx/models/__init__.py

@@ -0,0 +1 @@
+"""CrayonMLX models components."""

crayonmlx/models/catalog.py

@@ -0,0 +1,40 @@
+"""Discover manually downloaded Diffusers or MFLUX checkpoint directories."""
+
+from pathlib import Path
+
+from crayonmlx.models.identity import model_description
+from crayonmlx.paths import child_path
+
+MARKERS = ("model_index.json", "config.json", "transformer", "vae", "text_encoder", "mflux_model.json")
+
+
+def is_checkpoint(path: Path) -> bool:
+    return path.is_dir() and any((path / marker).exists() for marker in MARKERS)
+
+
+def list_models(root: Path) -> list[dict]:
+    if not root.is_dir():
+        return []
+    # A directory may itself be a checkpoint, or contain named checkpoints.
+    paths = [root] if is_checkpoint(root) else sorted(root.iterdir())
+    return [
+        {
+            "id": "." if path == root else path.name,
+            "name": path.name,
+            "path": str(path),
+            **model_description(path),
+        }
+        for path in paths
+        if not path.name.startswith(".")
+        and is_checkpoint(path)
+        and path.resolve().is_relative_to(root.resolve())
+    ]
+
+
+def resolve_model(root: Path, identifier: str) -> Path:
+    path = root.resolve() if identifier == "." else child_path(root, identifier)
+    if not is_checkpoint(path):
+        raise ValueError(
+            "Не найдена локальная папка модели. Нужен полный checkpoint, а не отдельный файл весов."
+        )
+    return path