reqsmart 0.1.0__tar.gz

reqsmart-0.1.0/LICENSE

@@ -0,0 +1,60 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             iSterna Inc.
+Licensed Work:        smart-req v0.1.0
+                      The Licensed Work is (c) 2026 iSterna Inc.
+Additional Use Grant: You may make use of the Licensed Work for internal
+                      evaluation and non-commercial purposes. Commercial use
+                      requires a separate license from the Licensor.
+Change Date:          2030-03-21
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: support@aisterna.com
+
+Notice
+
+Business Source License 1.1 (BSL-1.1)
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under the
+terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently
+in effect as described in this License, you must purchase a commercial license
+from the Licensor, its affiliated entities, or authorized resellers, or you must
+refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.

reqsmart-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+recursive-include config/default *.md
+recursive-include config/templates *.md
+include config/clients/README.md

reqsmart-0.1.0/PKG-INFO

@@ -0,0 +1,352 @@
+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.