Skip to content

Index

Backlog (how we work)

This folder is the single source of truth for planned and completed engineering work in AbstractVision.

Note: - docs/backlog/ is an internal engineering log (design notes + completion reports). - For current, user-facing docs and install/usage instructions, prefer docs/README.md and README.md.

Principles

  • Backlog items are self-contained: each task includes the outcome of research, key constraints, design choices, and the reasons for those choices (with references).
  • No test-driven special casing: implementation must be general-purpose logic, not tailored to tests.
  • Keep the public contract stable: preserve the integrator-facing API (VisionManager.generate_image/edit_image/generate_angles/generate_video/image_to_video/...).
  • Artifact-first outputs: generated images/videos must be representable as small JSON objects (refs), not inlined bytes, to support tool calling + workflows + third-party integrations.
  • Lightweight base install, explicit local runtimes: the default install supports shared contracts, the capability registry, artifact refs, the OpenAI-compatible HTTP backend, CLI glue, and AbstractCore plugin discovery without installing local inference runtimes. Local Diffusers is explicit through abstractvision[diffusers]; stable-diffusion.cpp python bindings are explicit through abstractvision[sdcpp]; abstractvision[local] installs both. Importing abstractvision should not eagerly import heavy runtime stacks unless needed (avoid model loads/weight downloads at import time; defer heavy backend imports until backend construction or first use).
  • Prefer permissive licensing: only adopt MIT/Apache/BSD-compatible components. If none exist, document feasibility and create a backlog item.

Note: older completed backlog items may describe either a “default Diffusers install” phase or earlier “heavy deps behind extras” plans. Treat pyproject.toml and the latest planned/completed packaging task as the source of truth.

Folder layout

  • docs/backlog/planned/: work to do next
  • docs/backlog/completed/: finished tasks with a completion report

Naming convention

Create new tasks as:

  • docs/backlog/planned/{NNN}_{short_description}.md

Rules: - NNN: zero-padded integer (e.g. 017) - short_description: snake_case, concise

Note: older tasks may use legacy names; do not rename unless a dedicated cleanup task exists.

Task template (required sections)

Every backlog item must include:

  • Title
  • Date
  • Status: Planned / Completed
  • Priority: P0/P1/P2
  • Main goal(s) and secondary goal(s)
  • Context / problem statement
  • Constraints
  • Research & references (links + key findings)
  • Decision (what we choose + why)
  • Dependencies (ADRs and other tasks)
  • Implementation plan (small steps, minimal surface area)
  • Success criteria
  • Test plan
  • Report (for completed tasks only)

See docs/backlog/template.md.

Work process (development cycle)

  1. Think, design, and plan with long-term consequences in mind; prefer the cleanest, simplest, most efficient approach.
  2. Write the task in docs/backlog/planned/{NNN}_{short_description}.md (self-contained, with research and decisions).
  3. Implement the task.
  4. Test and fix issues.
  5. Only when all tests pass, move the task to docs/backlog/completed/ and add the completion report at the end.
  6. For releases, ensure hygiene:
  7. update CHANGELOG.md
  8. bump abstractvision.__version__ in src/abstractvision/__init__.py