diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..295b77e --- /dev/null +++ b/.gitignore @@ -0,0 +1,27 @@ + +# ── GSD baseline (auto-generated) ── +.DS_Store +Thumbs.db +*.swp +*.swo +*~ +.idea/ +.vscode/ +*.code-workspace +.env +.env.* +!.env.example +node_modules/ +.next/ +dist/ +build/ +__pycache__/ +*.pyc +.venv/ +venv/ +target/ +vendor/ +*.log +coverage/ +.cache/ +tmp/ diff --git a/.gsd/KNOWLEDGE.md b/.gsd/KNOWLEDGE.md new file mode 100644 index 0000000..cdc3b7d --- /dev/null +++ b/.gsd/KNOWLEDGE.md @@ -0,0 +1,20 @@ +# Project Knowledge + +Append-only register of project-specific rules, patterns, and lessons learned. +Agents read this before every unit. Add entries when you discover something worth remembering. + +## Rules + +| # | Scope | Rule | Why | Added | +|---|-------|------|-----|-------| + +## Patterns + +| # | Pattern | Where | Notes | +|---|---------|-------|-------| + +## Lessons Learned + +| # | What Happened | Root Cause | Fix | Scope | +|---|--------------|------------|-----|-------| +| L001 | pypotrace fails to build from pip | Requires system packages: `libpotrace-dev`, `libagg-dev`, `pkg-config` | `apt-get install -y libpotrace-dev libagg-dev pkg-config` before `pip install pypotrace` | engine build, Docker | diff --git a/.gsd/STATE.md b/.gsd/STATE.md deleted file mode 100644 index af602be..0000000 --- a/.gsd/STATE.md +++ /dev/null @@ -1,20 +0,0 @@ -# GSD State - -**Active Milestone:** M001: Kerf Engine — Raster-to-Vector Pipeline & API -**Active Slice:** S01: Core Pipeline — Preprocessing + Vectorization -**Phase:** executing -**Requirements Status:** 0 active · 0 validated · 0 deferred · 0 out of scope - -## Milestone Registry -- 🔄 **M001:** Kerf Engine — Raster-to-Vector Pipeline & API -- ⬜ **M002:** M002 -- ⬜ **M003:** M003 - -## Recent Decisions -- None recorded - -## Blockers -- None - -## Next Action -Execute T01: Repository scaffolding + Engine project setup in slice S01. diff --git a/.gsd/event-log.jsonl b/.gsd/event-log.jsonl index d8a5e2e..619c5a5 100644 --- a/.gsd/event-log.jsonl +++ b/.gsd/event-log.jsonl @@ -4,3 +4,4 @@ {"cmd":"plan-slice","params":{"milestoneId":"M001","sliceId":"S01"},"ts":"2026-03-26T03:55:00.035Z","actor":"agent","hash":"b4e65a48e7b42f57","session_id":"5b5a1848-fcbc-4200-aa49-5260215f4e78"} {"cmd":"plan-slice","params":{"milestoneId":"M001","sliceId":"S02"},"ts":"2026-03-26T03:55:23.088Z","actor":"agent","hash":"7990d7932192bfde","session_id":"5b5a1848-fcbc-4200-aa49-5260215f4e78"} {"cmd":"plan-slice","params":{"milestoneId":"M001","sliceId":"S03"},"ts":"2026-03-26T03:55:42.360Z","actor":"agent","hash":"2d5b99521edd6ccd","session_id":"5b5a1848-fcbc-4200-aa49-5260215f4e78"} +{"cmd":"complete-task","params":{"milestoneId":"M001","sliceId":"S01","taskId":"T01"},"ts":"2026-03-26T04:07:03.179Z","actor":"agent","hash":"5a804380eb33710e","session_id":"f5306801-4a7b-4a78-9c7a-c96e61e0b90b"} diff --git a/.gsd/gsd.db b/.gsd/gsd.db deleted file mode 100644 index 159e90a..0000000 Binary files a/.gsd/gsd.db and /dev/null differ diff --git a/.gsd/gsd.db-shm b/.gsd/gsd.db-shm deleted file mode 100644 index 940be3e..0000000 Binary files a/.gsd/gsd.db-shm and /dev/null differ diff --git a/.gsd/gsd.db-wal b/.gsd/gsd.db-wal deleted file mode 100644 index 68cfdad..0000000 Binary files a/.gsd/gsd.db-wal and /dev/null differ diff --git a/.gsd/milestones/M001/slices/S01/S01-PLAN.md b/.gsd/milestones/M001/slices/S01/S01-PLAN.md index 7760932..b9d5435 100644 --- a/.gsd/milestones/M001/slices/S01/S01-PLAN.md +++ b/.gsd/milestones/M001/slices/S01/S01-PLAN.md @@ -4,7 +4,7 @@ **Demo:** After this: POST /engine/trace with a PNG logo returns valid SVG using both Potrace and VTracer modes ## Tasks -- [ ] **T01: Repository scaffolding + Engine project setup** — 1. Create the repo directory structure at /vmPool/r/repos/xpltdco/kerf/ +- [x] **T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified** — 1. Create the repo directory structure at /vmPool/r/repos/xpltdco/kerf/ 2. Set up engine/ as a Python project with pyproject.toml 3. Pin dependencies: fastapi, uvicorn, opencv-python-headless, pypotrace, vtracer, python-multipart, Pillow 4. Create engine/main.py with FastAPI app skeleton diff --git a/.gsd/milestones/M001/slices/S01/tasks/T01-SUMMARY.md b/.gsd/milestones/M001/slices/S01/tasks/T01-SUMMARY.md new file mode 100644 index 0000000..174cfce --- /dev/null +++ b/.gsd/milestones/M001/slices/S01/tasks/T01-SUMMARY.md @@ -0,0 +1,82 @@ +--- +id: T01 +parent: S01 +milestone: M001 +provides: [] +requires: [] +affects: [] +key_files: ["engine/pyproject.toml", "engine/main.py", "engine/.gitignore", "README.md"] +key_decisions: [] +patterns_established: [] +drill_down_paths: [] +observability_surfaces: [] +duration: "" +verification_result: "pip install -e .[dev] succeeded. uvicorn starts, /docs returns Swagger UI, /health returns ok." +completed_at: 2026-03-26T04:07:03.124Z +blocker_discovered: false +--- + +# T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified + +> Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified + +## What Happened +--- +id: T01 +parent: S01 +milestone: M001 +key_files: + - engine/pyproject.toml + - engine/main.py + - engine/.gitignore + - README.md +key_decisions: + - (none) +duration: "" +verification_result: passed +completed_at: 2026-03-26T04:07:03.137Z +blocker_discovered: false +--- + +# T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified + +**Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified** + +## What Happened + +Created engine/ directory structure with subdirectories for pipeline/, api/, and tests/fixtures/. Set up pyproject.toml with setuptools build backend, all required dependencies pinned, and dev extras. Created main.py with a FastAPI app skeleton exposing /health and /docs. Installed system C libraries for pypotrace. + +## Verification + +pip install -e .[dev] succeeded. uvicorn starts, /docs returns Swagger UI, /health returns ok. + +## Verification Evidence + +| # | Command | Exit Code | Verdict | Duration | +|---|---------|-----------|---------|----------| +| 1 | `pip install -e .[dev]` | 0 | pass | 45000ms | +| 2 | `curl http://localhost:8000/docs` | 0 | pass | 500ms | +| 3 | `curl http://localhost:8000/health` | 0 | pass | 200ms | + + +## Deviations + +Adapted repo path from /vmPool/r/repos/xpltdco/kerf/ to working directory. Installed system packages for pypotrace. + +## Known Issues + +pypotrace requires system C deps (libpotrace-dev, libagg-dev, pkg-config) — must be in Docker image. + +## Files Created/Modified + +- `engine/pyproject.toml` +- `engine/main.py` +- `engine/.gitignore` +- `README.md` + + +## Deviations +Adapted repo path from /vmPool/r/repos/xpltdco/kerf/ to working directory. Installed system packages for pypotrace. + +## Known Issues +pypotrace requires system C deps (libpotrace-dev, libagg-dev, pkg-config) — must be in Docker image. diff --git a/.gsd/state-manifest.json b/.gsd/state-manifest.json index 508ea80..bd32a4a 100644 --- a/.gsd/state-manifest.json +++ b/.gsd/state-manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "exported_at": "2026-03-26T03:55:42.360Z", + "exported_at": "2026-03-26T04:07:03.179Z", "milestones": [ { "id": "M001", @@ -402,19 +402,24 @@ "milestone_id": "M001", "slice_id": "S01", "id": "T01", - "title": "Repository scaffolding + Engine project setup", - "status": "pending", - "one_liner": "", - "narrative": "", - "verification_result": "", + "title": "Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified", + "status": "complete", + "one_liner": "Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified", + "narrative": "Created engine/ directory structure with subdirectories for pipeline/, api/, and tests/fixtures/. Set up pyproject.toml with setuptools build backend, all required dependencies pinned, and dev extras. Created main.py with a FastAPI app skeleton exposing /health and /docs. Installed system C libraries for pypotrace.", + "verification_result": "pip install -e .[dev] succeeded. uvicorn starts, /docs returns Swagger UI, /health returns ok.", "duration": "", - "completed_at": null, + "completed_at": "2026-03-26T04:07:03.124Z", "blocker_discovered": false, - "deviations": "", - "known_issues": "", - "key_files": [], + "deviations": "Adapted repo path from /vmPool/r/repos/xpltdco/kerf/ to working directory. Installed system packages for pypotrace.", + "known_issues": "pypotrace requires system C deps (libpotrace-dev, libagg-dev, pkg-config) — must be in Docker image.", + "key_files": [ + "engine/pyproject.toml", + "engine/main.py", + "engine/.gitignore", + "README.md" + ], "key_decisions": [], - "full_summary_md": "", + "full_summary_md": "---\nid: T01\nparent: S01\nmilestone: M001\nkey_files:\n - engine/pyproject.toml\n - engine/main.py\n - engine/.gitignore\n - README.md\nkey_decisions:\n - (none)\nduration: \"\"\nverification_result: passed\ncompleted_at: 2026-03-26T04:07:03.137Z\nblocker_discovered: false\n---\n\n# T01: Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified\n\n**Created engine/ Python project with FastAPI skeleton, all dependencies installed and verified**\n\n## What Happened\n\nCreated engine/ directory structure with subdirectories for pipeline/, api/, and tests/fixtures/. Set up pyproject.toml with setuptools build backend, all required dependencies pinned, and dev extras. Created main.py with a FastAPI app skeleton exposing /health and /docs. Installed system C libraries for pypotrace.\n\n## Verification\n\npip install -e .[dev] succeeded. uvicorn starts, /docs returns Swagger UI, /health returns ok.\n\n## Verification Evidence\n\n| # | Command | Exit Code | Verdict | Duration |\n|---|---------|-----------|---------|----------|\n| 1 | `pip install -e .[dev]` | 0 | pass | 45000ms |\n| 2 | `curl http://localhost:8000/docs` | 0 | pass | 500ms |\n| 3 | `curl http://localhost:8000/health` | 0 | pass | 200ms |\n\n\n## Deviations\n\nAdapted repo path from /vmPool/r/repos/xpltdco/kerf/ to working directory. Installed system packages for pypotrace.\n\n## Known Issues\n\npypotrace requires system C deps (libpotrace-dev, libagg-dev, pkg-config) — must be in Docker image.\n\n## Files Created/Modified\n\n- `engine/pyproject.toml`\n- `engine/main.py`\n- `engine/.gitignore`\n- `README.md`\n", "description": "1. Create the repo directory structure at /vmPool/r/repos/xpltdco/kerf/\n2. Set up engine/ as a Python project with pyproject.toml\n3. Pin dependencies: fastapi, uvicorn, opencv-python-headless, pypotrace, vtracer, python-multipart, Pillow\n4. Create engine/main.py with FastAPI app skeleton\n5. Create engine/requirements.txt or use pyproject.toml deps\n6. Add .gitignore, initial README.md\n7. Verify: pip install works, uvicorn starts the empty app", "estimate": "30min", "files": [ @@ -798,5 +803,39 @@ "superseded_by": null } ], - "verification_evidence": [] + "verification_evidence": [ + { + "id": 1, + "task_id": "T01", + "slice_id": "S01", + "milestone_id": "M001", + "command": "pip install -e .[dev]", + "exit_code": 0, + "verdict": "pass", + "duration_ms": 45000, + "created_at": "2026-03-26T04:07:03.124Z" + }, + { + "id": 2, + "task_id": "T01", + "slice_id": "S01", + "milestone_id": "M001", + "command": "curl http://localhost:8000/docs", + "exit_code": 0, + "verdict": "pass", + "duration_ms": 500, + "created_at": "2026-03-26T04:07:03.124Z" + }, + { + "id": 3, + "task_id": "T01", + "slice_id": "S01", + "milestone_id": "M001", + "command": "curl http://localhost:8000/health", + "exit_code": 0, + "verdict": "pass", + "duration_ms": 200, + "created_at": "2026-03-26T04:07:03.124Z" + } + ] } \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..91a5596 --- /dev/null +++ b/README.md @@ -0,0 +1,26 @@ +# Kerf + +Modular raster-to-vector conversion engine + 2D sign/patch design canvas. + +## Repository Structure + +``` +engine/ — Kerf Engine (standalone API, Python/FastAPI) +app/ — Kerf App frontend (React) [future] +server/ — Kerf App backend API [future] +docker/ — Dockerfiles and compose configs [future] +``` + +## Kerf Engine + +The engine is a self-contained FastAPI service that accepts raster images and returns clean vector output (SVG, DXF). + +### Quick Start + +```bash +cd engine +pip install -e ".[dev]" +uvicorn main:app --host 0.0.0.0 --port 8000 +``` + +API docs available at `http://localhost:8000/docs`. diff --git a/engine/.gitignore b/engine/.gitignore new file mode 100644 index 0000000..8165030 --- /dev/null +++ b/engine/.gitignore @@ -0,0 +1,2 @@ +*.egg-info/ +.eggs/ diff --git a/engine/api/__init__.py b/engine/api/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/engine/main.py b/engine/main.py new file mode 100644 index 0000000..8ba9053 --- /dev/null +++ b/engine/main.py @@ -0,0 +1,14 @@ +"""Kerf Engine — raster-to-vector conversion API.""" + +from fastapi import FastAPI + +app = FastAPI( + title="Kerf Engine", + description="Raster-to-vector conversion pipeline with Potrace and VTracer modes", + version="0.1.0", +) + + +@app.get("/health") +async def health(): + return {"status": "ok"} diff --git a/engine/pipeline/__init__.py b/engine/pipeline/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/engine/pyproject.toml b/engine/pyproject.toml new file mode 100644 index 0000000..5390ba1 --- /dev/null +++ b/engine/pyproject.toml @@ -0,0 +1,28 @@ +[build-system] +requires = ["setuptools>=68.0", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "kerf-engine" +version = "0.1.0" +description = "Kerf Engine — raster-to-vector conversion pipeline" +requires-python = ">=3.11" +dependencies = [ + "fastapi>=0.110", + "uvicorn[standard]>=0.29", + "opencv-python-headless>=4.9", + "pypotrace>=0.3", + "vtracer>=0.6", + "python-multipart>=0.0.9", + "Pillow>=10.2", +] + +[tool.setuptools.packages.find] +include = ["pipeline*", "api*"] + +[project.optional-dependencies] +dev = [ + "pytest>=8.0", + "httpx>=0.27", + "ruff>=0.3", +] diff --git a/engine/tests/__init__.py b/engine/tests/__init__.py new file mode 100644 index 0000000..e69de29