Metadata-Version: 2.4
Name: reqsmart
Version: 0.1.0
Summary: Requirement qualification tool: extract, score, review, export
Author: Yanbing Li
License: BSL-1.1
Project-URL: Homepage, https://aisterna.com/smart-req
Keywords: requirements,quality,IEEE-29148,governance,traceability
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# smart-req

SMART Requirement Qualification Tool — extract requirements from specification PDFs, score them against quality gates, review with your team, and export gate-clean spreadsheets.

## Quick Start

### Install

**Option A — One-line installer (recommended):**

```bash
curl -sSL https://raw.githubusercontent.com/aisterna/smart-req/main/install.sh | bash
```

This checks prerequisites, creates an isolated environment, and adds `smart-req` to your PATH.

**Option B — Manual install:**

```bash
git clone https://github.com/aisterna/smart-req.git
cd smart-req
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### Prerequisites

- Python 3.11 or later ([download](https://www.python.org/downloads/))
- An Anthropic API key ([get one](https://console.anthropic.com/))

### Configure

```bash
smart-req configure
```

Enter your Anthropic API key when prompted. Optionally set a default client config:

```bash
smart-req configure --client mycompany
```

This is saved locally at `~/.smart-req/config.yaml`.

## Usage

### Step 1: Create a working directory

```bash
mkdir ~/dc28-sfs-review
cd ~/dc28-sfs-review
```

All output files will be saved here.

### Step 2: Extract requirements from your PDF

```bash
smart-req extract --input /path/to/your-spec.pdf
```

Extract specific sections only:

```bash
smart-req extract --input /path/to/SFS.pdf --sections 3.5,3.22
```

Output: `raw_extract.csv` — open in Excel to sanity-check before scoring.

### Step 3: Score against quality gates

```bash
smart-req score
```

Output: `manifest.xlsx` with four tabs:
- **Instructions** — what to do next
- **PASS** — requirements that passed all gates
- **REVIEW** — requirements with warnings
- **FAIL** — requirements with failures, including suggested fixes

### Step 4: Review (choose one)

**Option A — Spreadsheet review:**

1. Open `manifest.xlsx`
2. Go to REVIEW and FAIL tabs
3. Use the dropdown in the Decision column: **Accept**, **Modify**, or **Reject**
4. Add notes in the Engineer Notes column
5. Save the spreadsheet
6. Run:

```bash
smart-req finalize
```

**Option B — Browser review:**

```bash
smart-req review
```

A local browser UI opens. Click Accept/Modify/Reject for each requirement. When done, the server auto-exports and closes.

### Step 5: Done

Your final output:

```
your-spec_Final.xlsx       ← gate-clean requirements
your-spec_Final.audit.json ← audit trail (who decided what, when)
```

## Commands

| Command | What it does |
|---|---|
| `smart-req run` | **Full pipeline** — extract, score, review, export in one command |
| `smart-req extract` | PDF → requirements CSV |
| `smart-req score` | CSV → scored manifest (XLSX + JSON) |
| `smart-req review` | Browser-based HITL review |
| `smart-req finalize` | Import spreadsheet decisions → export final XLSX |
| `smart-req export` | Export final XLSX (after browser review) |
| `smart-req import-decisions` | Import decisions from spreadsheet only (advanced) |
| `smart-req configure` | Set API key and default client |

### Quickest path

```bash
# Browser review (one command does everything)
smart-req run --input /path/to/spec.pdf

# Spreadsheet review (two commands)
smart-req run --input /path/to/spec.pdf --spreadsheet
# fill in decisions in manifest.xlsx, save, then:
smart-req finalize
```

## Quality Gates

### Default (IEEE 29148 Baseline — 6 gates)

Six universal gates derived from IEEE/ISO/IEC 29148:2018 Clause 5.2.5:

| Gate | IEEE 29148 Characteristic | What it checks |
|---|---|---|
| **RQ1** Unambiguous | §5.2.5(c) | Single interpretation. No vague terms. |
| **RQ2** Verifiable | §5.2.5(l) | Can be proven by test, analysis, or inspection. |
| **RQ3** Singular | §5.2.5(i) | One concern per requirement. |
| **RQ4** Appropriate | §5.2.5(a) | Right abstraction level. WHAT, not HOW. |
| **RQ5** Traceable | §5.2.5(k) | Maps to source AND to implementation + verification. |
| **RQ6** Complete | §5.2.5(b) | All values specified. No TBDs. |

### Domain Templates

Pre-built gate configurations for regulated industries. Copy a template and customize:

| Template | Standards | Additional gates |
|---|---|---|
| `telecom.md` | TL9000, ITU-T, RFC 2119 | Protocol compliance, keyword compliance, interface completeness, interop reference |
| `aerospace-do178c.md` | DO-178C, ARP 4754A | DAL allocation, derived req flagging, safety traceability, verification method |
| `medical-iec62304.md` | IEC 62304, ISO 14971, FDA | Safety class, hazard traceability, intended use, SOUP identification |
| `automotive-iso26262.md` | ISO 26262, ASPICE | ASIL allocation, freedom from interference, fault handling, bidirectional trace |

```bash
cp config/templates/telecom.md ~/.smart-req/clients/mycompany/gates.md
smart-req configure --client mycompany
```

### Further customization

After applying a template, you can add domain terms to suppress false positives on your terminology:

```bash
# Create domain_terms.md in your client config
cat > ~/.smart-req/clients/mycompany/domain_terms.md << 'EOF'
## Domain-Specific Terms
- [your acronyms and defined terms here]
- [terms that sound vague but have precise meaning in your domain]
EOF
```

For gates fully tailored to your methodology and document conventions, contact support@aisterna.com.

## Example

```bash
# Full pipeline on a 100-page SFS document
mkdir ~/dc28-review && cd ~/dc28-review

smart-req extract --input ~/Documents/my-spec.pdf
# → 480 requirements extracted (45s)

smart-req score
# → 347 PASS, 98 REVIEW, 35 FAIL (12 min)

smart-req review
# → Browser opens, review 133 items, auto-exports when done

ls *_Final.*
# your-spec_Final.xlsx
# your-spec_Final.audit.json
```

## First Run: What to Expect

When you run smart-req for the first time **without a custom client config**, here's what happens:

### The good

- Requirements with real quality issues (vague, untestable, compound, incomplete) are correctly flagged
- Suggested fixes are actionable — you can Accept them directly
- The 5 default quality gates catch universal problems that apply to any domain

### The noise

- **Domain terms flagged as ambiguous (~15-30% of warnings):** Terms like "traffic-affecting fault" or "NETCONF" have precise meaning in your domain, but the default scorer doesn't know that. These show up as G1/Specific warnings.
- **Missing domain-specific checks:** The default 5 gates cover universal requirement quality. Your domain may need additional gates (interface completeness, protocol compliance, safety traceability).

### What to do about it

**1. Just Reject the false positives (5 minutes):** The dropdown makes this fast. Your rejections are recorded in the audit trail — they don't slow you down.

**2. Apply a domain template (10 minutes):** Pick the template for your industry. This adds domain-specific gates and reduces noise immediately:

```bash
mkdir -p ~/.smart-req/clients/mycompany
cp config/templates/telecom.md ~/.smart-req/clients/mycompany/gates.md
smart-req configure --client mycompany
smart-req score    # now uses your domain gates
```

Available templates: `telecom.md`, `aerospace-do178c.md`, `medical-iec62304.md`, `automotive-iso26262.md`.

**3. Add your domain terms (1 hour):** Create a terms list so your team's vocabulary stops triggering false warnings:

```bash
cat > ~/.smart-req/clients/mycompany/domain_terms.md << 'EOF'
## Domain-Specific Terms
- [your acronyms and defined terms here]
- [terms that sound vague but have precise meaning in your domain]
EOF
```

Re-score — false positives drop to <5%.

**4. Professional onboarding (2-3 hours):** Gates fully tailored to your methodology, document conventions, and quality standards. Contact support@aisterna.com.

### Example: Reducing noise step by step

Suppose your spec contains this requirement:

> "The system shall support NETCONF for NBI configuration management."

**Step 0 — Default scoring result:**
```
RQ1 Unambiguous: FAIL — "support" is a prohibited vague term (support what exactly?)
RQ2 Verifiable:  FAIL — no testable criteria (which NETCONF operations? which datastore?)
RQ6 Complete:    FAIL — no protocol version, no transport, no error handling
Suggested fix: "The system shall implement NETCONF (RFC 6241) over SSH (RFC 6242)
for NBI configuration management, supporting <get>, <get-config>, <edit-config>,
and <lock> operations on the running and candidate datastores."
```

Three failures. The suggested fix is good but aggressive — maybe you only need some of those operations.

**After Step 1 (Reject):** You click Reject on RQ1: "support has defined meaning in our NBI spec — it means implement all mandatory operations per our NBI compliance matrix." Audit trail records your justification. RQ2 and RQ6 failures are legitimate — you Accept those fixes.

**After Step 2 (Telecom template):** You applied `telecom.md`. Now the scoring also checks TQ1 (Protocol Compliance) and TQ3 (Interface Completeness):
```
TQ1 Protocol Compliance: FAIL — no NETCONF version (RFC 6241 vs RFC 4741?)
TQ3 Interface Completeness: FAIL — no operations, no datastore, no error handling specified
```
The template catches what the baseline missed — and the failures are more precise.

**After Step 3 (Domain terms):** You added to `domain_terms.md`:
```
- NBI (Northbound Interface — management plane access)
- NETCONF, RESTCONF, SNMP (management protocols)
- "support" when followed by a protocol name (means implement per compliance matrix)
```
Now RQ1 no longer flags "support NETCONF" as vague. Only the real gaps (RQ2, RQ6, TQ1, TQ3) remain.

**After Step 4 (Professional onboarding):** iSterna adds a custom gate:
```
### CQ1: NBI Compliance Matrix Reference
- Pass: NBI requirement references the compliance matrix row/column
        specifying mandatory vs optional operations for this protocol.
- Fail: NBI requirement without compliance matrix reference.
```
Now every NBI requirement is automatically checked against your compliance matrix — something no generic template could know about.

### Typical results by configuration

| Configuration | False positive rate | Gates | Setup time |
|---|---|---|---|
| Default (no config) | 15-30% | 6 RQ baseline | 0 min |
| Domain template | 10-15% | 6 RQ + 4 domain | 10 min |
| Template + domain terms | 3-5% | 6 RQ + 4 domain | 1 hour |
| Professional onboarding | <3% | Custom (8-12 gates) | 2-3 hours with specialist |

---

## FAQ

**How much does it cost?**
LLM costs depend on document size. A 100-page SFS (~480 requirements) costs approximately $15-25 for extraction + scoring using Claude Sonnet.

**Can I use a different LLM?**
Currently Claude only. Pass `--model claude-opus-4-6` for higher quality at higher cost, or `--model claude-sonnet-4-20250514` (default) for the best cost/quality balance.

**Does my data leave my machine?**
Requirement text is sent to the Anthropic API for extraction and scoring. No data is stored by the tool beyond your local machine. Review and export are fully offline.

**Can I re-score after editing the CSV?**
Yes. Edit `raw_extract.csv`, then run `smart-req score` again. The manifest is regenerated from scratch.

**What if I disagree with a gate score?**
Reject it. The Decision column lets you override any gate result with a justification. Rejected items keep their original text and your reason is recorded in the audit trail.

## License

Business Source License 1.1 (BSL-1.1). See [LICENSE](LICENSE) for details.
