sumd 0.3.1

SUMD - Structured Unified Markdown Descriptor for AI-aware project documentation

SUMD

AI Cost Tracking

This project uses AI-generated code. Total cost: $4.6500 with 31 AI commits.

Generated on 2026-04-19 using openrouter/qwen/qwen3-coder-next

---

SUMD is a semantic project descriptor format in Markdown that defines intent, structure, execution entry points, and mental model of a system for both humans and LLMs.

What is SUMD?

SUMD (Structured Unified Markdown Descriptor) is a lightweight structured markdown format for AI-aware project descriptions. It serves as a single source of truth for project documentation, optimized for both human readability and LLM context injection.

Purpose

• Project descriptor: Defines API, CLI, workflows, endpoints, and system architecture
• AI-optimized: Structured for LLM consumption and automation tools
• Lightweight manifest: Bridges the gap between README, spec, and configuration files
• Context injection: Provides structured context for AI agents and tools

Use Cases

• Project documentation and specification
• Input for LLM context injection
• CI/CD workflow descriptions
• API and CLI mapping
• Structural project manifest

Installation

pip install sumd                  # stable
pip install sumd==0.2.0rc1        # latest release candidate

Developer Workflow

# health check — verify environment
task doctor

# run tests with coverage
task test

# quality gate (CC + vallm + coverage)
task pyqual

# build + publish (runs automatically when gates pass via pyqual pipeline)
task publish

Usage

CLI Commands

# Shortcut: scan current directory (detects if workspace or single project)
sumd .                          # equivalent to: sumd scan . --fix
sumd /path/to/project           # scan a specific directory

# Scan a workspace — auto-generate SUMD.md for every project found
sumd scan .                     # skip projects that already have SUMD.md
sumd scan . --fix               # overwrite existing SUMD.md
sumd scan . --fix --no-raw      # convert sources to structured Markdown instead of raw code blocks
sumd scan . --fix --analyze     # also run analysis tools (code2llm, redup, vallm)
sumd scan . --fix --analyze --tools code2llm,redup  # only selected tools
sumd scan . --fix --depth 2     # limit recursive search depth (default: unlimited)

# Section profiles — control how much is rendered in SUMD.md
sumd scan . --fix --profile minimal  # core sections only (metadata, architecture, workflows, dependencies, deployment)
sumd scan . --fix --profile light    # + interfaces, quality, configuration, environment, extras
sumd scan . --fix --profile rich     # + code analysis, source snippets, call graph, API stubs, test contracts (default)

# Generate SUMR.md (pre-refactoring analysis report for AI-aware refactorization)
sumd scan . --profile refactor       # creates SUMR.md — use sumr alias below
sumr .                               # shorthand: sumr <path> ≡ sumd scan <path> --profile refactor

# Lint / validate SUMD files
sumd lint SUMD.md               # validate a single file
sumd lint --workspace .         # validate all SUMD.md files in the workspace
sumd lint --workspace . --json  # output JSON results

# Generate project/map.toon.yaml (static code map — without code2llm)
sumd map ./my-project             # write to project/map.toon.yaml
sumd map ./my-project --force     # overwrite existing
sumd map ./my-project --stdout    # print to stdout

# Generate testql scenario scaffolds from OpenAPI spec
sumd scaffold ./my-project                  # all scenarios (api + smoke)
sumd scaffold ./my-project --type smoke     # only smoke tests
sumd scaffold ./my-project --type crud      # per-resource CRUD scenarios
sumd scaffold ./my-project --force          # overwrite existing files

# Run analysis tools on a single project
sumd analyze ./my-project                    # run all tools
sumd analyze ./my-project --tools code2llm   # only code2llm
sumd analyze ./my-project --force            # reinstall tools

Section Profiles

SUMD renders output in configurable profiles to trade off detail vs. token cost:

Profile	Sections	Use case
minimal	Metadata, Architecture, Workflows, Dependencies, Deployment	Quick overview, CI badges
light	+ Interfaces, Quality, Configuration, Environment, Extras	Standard documentation
rich	+ Code Analysis, Source Snippets, Call Graph, API Stubs, Test Contracts	LLM context injection (default)
refactor	Refactoring-focused analysis → generates SUMR.md	AI-aware pre-refactoring report

Python API

from sumd import parse, parse_file
from sumd.parser import validate_sumd_file

# Parse SUMD from string
document = parse(content)

# Parse SUMD from file
document = parse_file("SUMD.md")

# Validate SUMD file (markdown structure + codeblock format)
result = validate_sumd_file(Path("SUMD.md"))
# result = {"source": "SUMD.md", "markdown": [...], "codeblocks": [...], "ok": True}
if not result["ok"]:
    for issue in result["markdown"] + result["codeblocks"]:
        print(issue)

What is Embedded in SUMD.md?

SUMD auto-embeds the following sources from a project (when present):

Source	Contents	markpact kind
pyproject.toml	metadata, deps, entry points	parsed
Taskfile.yml	all tasks as raw YAML	markpact:taskfile
openapi.yaml	full OpenAPI spec (endpoints as sections)	markpact:openapi
testql-scenarios/**	all .testql.toon.yaml scenario files	markpact:testql
app.doql.less (preferred) or .css	DOQL styling	markpact:doql
pyqual.yaml	quality pipeline config	markpact:pyqual
goal.yaml	project intent	rendered
.env.example	env variables list	listed
Dockerfile	containerisation	listed
docker-compose.*.yml	services	listed
src/**/*.py modules	module list	listed
package.json	Node.js deps (dependencies + devDependencies)	listed
project/analysis.toon.yaml	static code analysis (CC, pipelines)	markpact:analysis
project/project.toon.yaml	project topology	markpact:analysis
project/evolution.toon.yaml	commit evolution	markpact:analysis
project/map.toon.yaml	module inventory, function signatures, CC metrics	markpact:analysis
project/duplication.toon.yaml	code duplication report	markpact:analysis
project/validation.toon.yaml	vallm validation results	markpact:analysis
project/calls.toon.yaml	call graph with hub metrics	markpact:analysis
project/compact_flow.mmd	compact call flow diagram	markpact:analysis
project/calls.mmd	full call graph	markpact:analysis
project/flow.mmd	execution flow	markpact:analysis
project/context.md	architecture analysis (code2llm)	inline markdown
project/README.md	analysis readme	inline markdown
project/prompt.txt	code2llm prompt used	markpact:analysis

Not embedded: *.png (binary images), index.html (generated visualisation), refactor-progress.txt, testql-scenarios/ inside project/.

project/map.toon.yaml is generated by sumd map (built-in, no extra deps). Other project/ files are generated by sumd analyze (invokes code2llm, redup, vallm).

Ecosystem Architecture

SUMD is part of a three-layer system:

┌─────────────────────────────────────────────────────────────┐
│                     SUMD (opis)                              │
│              Structured Unified Markdown Descriptor          │
│         Project description, intent, architecture            │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    DOQL (wykonanie)                          │
│              Declarative Object Query Language               │
│              Data manipulation and execution                 │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  Taskfile (runtime)                          │
│              Task runner and workflow execution              │
│              Automation and orchestration                   │
└─────────────────────────────────────────────────────────────┘

• SUMD → opis (description): Defines what the system is and how it should work
• DOQL → wykonanie (execution): Provides the language to manipulate and execute operations
• Taskfile → runtime: Manages the actual execution of workflows and tasks

License

Licensed under Apache-2.0.