Metadata-Version: 2.4
Name: sumd
Version: 0.1.11
Summary: SUMD - Structured Unified Markdown Descriptor for AI-aware project documentation
Project-URL: Homepage, https://github.com/tom/statement
Project-URL: Repository, https://github.com/tom/statement
Author-email: Tom Sapletta <tom@sapletta.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: documentation,llm,markdown,project-descriptor,sumd
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: toml>=0.10.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# SUMD

## AI Cost Tracking

![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.90-brightgreen) ![AI Model](https://img.shields.io/badge/AI%20Model-openrouter%2Fqwen%2Fqwen3-coder-next-lightgrey)

This project uses AI-generated code. Total cost: **$0.9000** with **6** AI commits.

Generated on 2026-04-18 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/models/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

```bash
pip install sumd
```

## Usage

### CLI Commands

```bash
# Validate a SUMD document
sumd validate SUMD.md

# Display information about a SUMD document
sumd info SUMD.md

# Export SUMD to different formats
sumd export SUMD.md --format json --output sumd.json
sumd export SUMD.md --format yaml --output sumd.yaml
sumd export SUMD.md --format toml --output sumd.toml
sumd export SUMD.md --format markdown --output sumd.md

# Generate SUMD from structured format
sumd generate sumd.json --format json --output SUMD.md
sumd generate sumd.yaml --format yaml --output SUMD.md
sumd generate sumd.toml --format toml --output SUMD.md

# Extract specific section
sumd extract SUMD.md --section intent
```

### Python API

```python
from sumd import parse, parse_file, validate

# Parse SUMD from string
document = parse(content)

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

# Validate SUMD document
errors = validate(document)
if errors:
    print("Validation errors:", errors)
else:
    print("SUMD document is valid")
```

## 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.
