Metadata-Version: 2.4
Name: forge-spec
Version: 0.2.0
Summary: Spec-Driven Development for Forge — structured acceptance criteria, SLSA Level 2 attestation, and spec-gated evolution.
Project-URL: Homepage, https://github.com/angelnicolasc/forge
Project-URL: Repository, https://github.com/angelnicolasc/forge
Project-URL: Issues, https://github.com/angelnicolasc/forge/issues
Project-URL: Changelog, https://github.com/angelnicolasc/forge/blob/main/CHANGELOG.md
Author-email: Angel DiCerutti <angelnicolascorzo@gmail.com>
License-Expression: Apache-2.0
Keywords: acceptance,agents,attestation,compliance,llm,slsa,spec
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: forge-os-core==0.2.0
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog<26.0,>=24.0
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == 'llm'
Description-Content-Type: text/markdown

# forge-spec

Spec-Driven Development for the Forge agent harness.

Define what an agent run must achieve (`spec.yaml`), verify it against real
`RunResult` output, and generate SLSA Level 2-inspired attestations for
compliance and audit trails.

## Installation

```bash
pip install forge-spec
# With LLM-assisted spec refinement:
pip install forge-spec[llm]
```

## Quick start

```python
from forge_spec import SpecDef, AcceptanceCriterion, SpecRunner

spec = SpecDef(
    name="no-show-optimizer",
    description="Reduce appointment no-show rate",
    objectives=["Reduce no-show rate by 15%"],
    acceptance_criteria=[
        AcceptanceCriterion(
            id="ac-001",
            description="Run completes successfully",
            check_type="assertion",
            expected="run_result.status == 'completed'",
        ),
        AcceptanceCriterion(
            id="ac-002",
            description="Output contains recommendations",
            check_type="contains",
            expected="recommendation",
        ),
    ],
)

runner = SpecRunner()
verify_result, attestation = await runner.run_pipeline(spec, run_result)
print(f"Compliance: {verify_result.compliance_rate:.0%}")
```

## spec.yaml format

```yaml
name: no-show-optimizer
version: "0.1.0"
description: Reduce appointment no-show rate
objectives:
  - Reduce no-show rate by at least 15%
constraints:
  - id: no-model-swap
    description: Preserve the primary LLM model during evolution
    mutation_kinds_blocked:
      - model_swap
acceptance_criteria:
  - id: ac-001
    description: Run must complete successfully
    check_type: assertion
    expected: "run_result.status == 'completed'"
    weight: 2.0
  - id: ac-002
    description: Output mentions recommendations
    check_type: contains
    expected: recommendation
risks:
  - id: risk-001
    description: Model hallucination in recommendations
    likelihood: 0.3
    impact: 0.8
    mitigation: Use structured output validation
```

## Technical debt

See DEVLOG.md for DT entries introduced in Phase 4.
