Metadata-Version: 2.4
Name: libspec
Version: 10.3.3
Summary: Spec-driven development library for LLM-assisted coding
Author-email: "Derek A. Rhodes" <physci@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/drhodes/libspec
Project-URL: Repository, https://github.com/drhodes/libspec
Project-URL: Bug Tracker, https://github.com/drhodes/libspec/issues
Keywords: specification,llm,codegen,spec-driven,development
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.8
Requires-Dist: jinja2>=3.1.6
Requires-Dist: mcp>=1.27.0
Requires-Dist: toml>=0.10.2
Requires-Dist: skillkit>=0.4.0
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: colored>=2.3.2
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: pyyaml>=6.0.2
Dynamic: license-file

# libspec

[![CI/CD](https://github.com/drhodes/libspec/actions/workflows/ci.yml/badge.svg)](https://github.com/drhodes/libspec/actions/workflows/ci.yml)
[![Documentation](https://github.com/drhodes/libspec/actions/workflows/docs.yml/badge.svg)](https://drhodes.github.io/libspec/)
[![License](https://img.shields.io/github/license/drhodes/libspec.svg)](https://github.com/drhodes/libspec/blob/main/LICENSE)

> **an ounce of spec is worth a pound of tokens**


`libspec` is a **Specification Management System** in Python. Similar in spirit 
to object-relation mapping (ORM), libspec uses an Object Specification Mapping 
to compile logical requirements into structured database snapshots. Instead of 
generating SQL, it tracks how requirements evolve over time.

By diff'ing snapshots and using a Model Context Protocol (MCP) server, it 
provides a centralized context layer for local coding agents to trace specs directly 
to generated code. The developer workflow is incremental and exploratory, less like 
gambling and more like delegating.

![the general idea](./docs/workflow1.png)


### Example Spec

Here is the specification `spec/err.py` used to establish fundamental code quality, error handling, and robustness constraints across the entire project via multiple inheritance:

```python
from libspec import Ctx, Feature, Requirement


# The Err docstrings are compiled into specification snapshots and 
# injected as prompt context for LLM code generation.
class Err(Ctx):
    """
    It is important that error handling be done excellently.

    If a function can fail, then it needs to do so in the most elegant way
    possible. Error reporting, handling, exceptions and all aspects of failure
    must be taken to extreme. It should be possible to understand the program
    by reading the error messages.

    When an error occurs there should be a story about the failure at each step
    of the way. What went wrong and why.
    """


class BoilerPlate(Ctx):
    """
    If you can see a way to reduce boiler plate, then do it.
    """


class FunctionLines(Ctx):
    """
    Try to keep functions under 20 lines.
    """


class Indentation(Ctx):
    """
    Try to keep indentation under 4 levels.
    """


class PreCondition(Ctx):
    """
    Functions should validate preconditions at their entry point.

    Instead of using `assert` statements (which can be disabled globally),
    raise explicit, descriptive exceptions (e.g., ValueError, TypeError, or
    custom domain exceptions) to robustly reject malformed input.
    """


class GlobalMutableState(Ctx):
    """
    Broadly you should avoid global mutable state.
    """


class PostCondition(Ctx):
    """
    Before a function returns, it should verify postconditions to ensure
    invariant properties hold true.

    Raise explicit, descriptive exceptions (such as RuntimeError or domain
    exceptions) rather than using `assert` statements to handle post-execution
    verification failures.
    """


# Composite specification aggregating precondition, postcondition, and global state avoidance guidelines.
class DefensiveProgramming(PreCondition, PostCondition, GlobalMutableState):
    pass


class Refactor(BoilerPlate, FunctionLines, Indentation):
    """
    Always keep an eye out for ways to generalize a function if it's utility
    might be helpful to other functions.

    Classes should be implemented in their own files with filename being the
    classname with correct naming convention
    """


class Robustness(DefensiveProgramming):
    """
    Always prioritize library-provided constructors for complex objects. Ensure
    all components are fully initialized before calling any state- mutating
    methods. Assume private internal state is uninitialized until the official
    constructor has returned. When extending library components, prioritize
    composition (pointers) over embedding by value to avoid risky state-copying
    bugs.

    Use dependency injection for system level objects for composability and to
    make testing easier.
    """


# Use multiple inheritance to endow Feature and Requirement specs with
# disciplined error handling guidance from above.
class Feat(Err, Refactor, Robustness, Feature):
    pass


class Req(Err, Refactor, Robustness, Requirement):
    pass
```

# The Object Model 

Each class declares a specification fragment that is optionally a
Jinja2 template string. More about that later...

## Inheritance

Inheritance means "does this and more." The inherited superclass
docstrings are normative, but compiled spec snapshots preserve them as
references instead of prepending their prose into the child docstring.
Renderers such as `libspec diff` can expand those refs when a review
needs the inherited context.

## Mixins 

Mixins help get around the diamond problem. (TODO: write more about this)

## Versioning

Note that the versioning of `libspec` is still being hammered
out. Currently, the version of `libspec` appears in generated spec snapshots
(`libspec-version` field). But, how diffs will be performed on
different versions is unexplored.

## Feature Branch & Multi-Commit Spec Diffing

When working on feature branches with intermediate commits, running `uv run libspec diff` right after a commit will report `No changes detected` because `HEAD` matches the live spec on disk.

To track the cumulative specification delta across all intermediate commits on a feature branch, pass the base branch target:

```bash
uv run libspec diff main
```

This tracks all specification additions, requirement modifications, and docstring changes relative to `main` throughout multi-stage development workflows.
