Metadata-Version: 2.4
Name: specl
Version: 0.2.0
Summary: RDF-native, SHACL-validated specifications for spec-driven AI development
Author: Zachary Welz
License: MIT
Project-URL: Homepage, https://github.com/zwelz3/specl
Project-URL: Repository, https://github.com/zwelz3/specl
Project-URL: Issues, https://github.com/zwelz3/specl/issues
Project-URL: Changelog, https://github.com/zwelz3/specl/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rdflib>=7.0
Requires-Dist: pyshacl>=0.25
Provides-Extra: assist
Dynamic: license-file

![specl](./static/logo-sm.png)

# specl

RDF-native, SHACL-validated specifications for spec-driven AI development.

Specs are authored in markdown with stable IDs (`R1.2`, `US3`), translated to RDF, validated against a tiered SHACL shapes graph, and scored for maturity. Designed to be the durable source of truth that AI coding agents read before they write.

## Install

```bash
pip install -e .
```

## Quick start

```bash
# Translate the specl_explorer spec to Turtle
specl-translate specs/specl_explorer/spec.md specs/specl_explorer/spec.ttl

# Validate with explanations
specl-validate validate specs/specl_explorer/spec.ttl src/specl/shapes.ttl --explain

# Maturity score
specl-validate score specs/specl_explorer/spec.ttl src/specl/shapes.ttl

# Diff two versions (auto-appends CHANGELOG.spec.md)
specl-validate diff old.ttl new.ttl

# Badge
specl-validate badge specs/specl_explorer/spec.ttl src/specl/shapes.ttl --out badge.svg

# LLM gap interrogator (requires local Ollama)
specl-assist gaps specs/specl_explorer/spec.ttl src/specl/shapes.ttl --model llama3.1

# Consistency check
specl-assist check specs/specl_explorer/spec.ttl --model llama3.1
```

## Severity tiers

SHACL shapes are split two ways so specs can evolve:

- **Violations** — structural. Always fail. A spec that violates these is broken.
- **Warnings** — production-readiness. Accumulate during prototyping, block only when `ekga:status "production"`.

The gate reads status from the spec itself, so no CI reconfiguration is needed as the spec matures.

## Layout

```
specl/
├── src/specl/          # Python package
│   ├── spec_to_rdf.py      # markdown -> Turtle
│   ├── validate_spec.py    # validate / diff / score / badge
│   ├── spec_assistant.py   # LLM gap interrogator + consistency checker
│   ├── shapes.ttl          # tiered SHACL shapes
│   ├── core.ttl            # ekga-core ontology stub
│   └── explorer.html       # lightweight read-only spec viewer
├── specs/
│   ├── ekga/               # Enterprise Knowledge Graph App (WIP)
│   ├── html_presenter/     # Interactive HTML presentations
│   ├── pptx_templater/     # PowerPoint corporate template filler
│   └── excel_service/      # Excel generation service
├── .github/workflows/      # CI validation
└── .pre-commit-config.yaml
```

## Spec explorer

Open `src/specl/explorer.html` in a browser and drop a generated `spec.ttl` file to browse requirements, user stories, and open issues. Read-only, zero build, no server.

## Authoring

Write specs in markdown under `specs/<name>/spec.md`. Use ID-bulleted lists for requirements (`R1.1`), user stories (`US1`), and open issues. The spec file itself carries YAML frontmatter with `spec_id`, `title`, `version`, and `status`. See `specs/ekga/spec.md` for the reference example.

## Deferred features

See `specs/ekga/ISSUES.md` for traceability registries, domain extension patterns, and other items scheduled for future iterations.
