Metadata-Version: 2.4
Name: mafhoom
Version: 0.1.0
Summary: Machine-Assisted Formalization of Hardware Objectives, Obligations, and Mandates
Author-email: Shiva Ahir <shivaahir158@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/shivaahir158/mafhoom
Project-URL: Repository, https://github.com/shivaahir158/mafhoom
Project-URL: Issues, https://github.com/shivaahir158/mafhoom/issues
Keywords: hardware,verification,requirements,NLP,SystemVerilog,SVA,formal-verification,specification,HRIR
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.39.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: networkx>=3.2.0
Requires-Dist: PyMuPDF>=1.23.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: matplotlib>=3.8.0; extra == "all"
Dynamic: license-file

# MAFHOOM

[![CI](https://github.com/shivaahir158/mafhoom/actions/workflows/ci.yml/badge.svg)](https://github.com/shivaahir158/mafhoom/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**Machine-Assisted Formalization of Hardware Objectives, Obligations, and Mandates**

MAFHOOM is an NLP compiler for hardware specifications. It accepts natural-language hardware requirements and compiles them into a typed, machine-readable Hardware Requirement Intermediate Representation (HRIR), on which deterministic analyses and artifact-generation backends operate.

## Quick Start

### Installation

```bash
pip install mafhoom                # From PyPI
pip install mafhoom[embeddings]    # With embedding-based duplicate detection
pip install -e ".[dev]"            # Development install from source
```

### Offline Demo (no API key required)

```bash
mafhoom demo
```

This runs the full pipeline on a FIFO controller specification, producing:
- Extracted requirements and HRIR objects
- Ambiguity, contradiction, duplicate, and completeness findings
- SystemVerilog Assertion candidates
- Verification test plan entries
- Traceability matrix and coverage report

### With Claude API

```bash
export ANTHROPIC_API_KEY="your-key-here"
mafhoom models                          # List available models
mafhoom compile examples/fifo_spec.md   # Full pipeline
```

### Hybrid Mode (rules + Claude FP filtering)

```bash
mafhoom compile examples/fifo_spec.md --mode hybrid
```

Uses rule-based extraction and deterministic analysis, then sends adjudicable findings (contradictions, ambiguities, near-duplicates) to Claude for true/false positive classification.

## CLI Commands

```bash
mafhoom version                         # Show version
mafhoom models                          # List Claude models
mafhoom ingest PATH                     # Ingest a document
mafhoom extract PATH                    # Extract requirements
mafhoom compile PATH [--output DIR]     # Full pipeline
mafhoom compile-project P1 P2 ...       # Multi-doc compilation
mafhoom analyze PATH                    # Run analysis passes
mafhoom export-hrir PATH --fmt csv      # Export HRIR (json/yaml/csv)
mafhoom generate-assertions PATH        # Generate SVA from HRIR
mafhoom generate-tests PATH             # Generate test plans
mafhoom html-report PATH                # Interactive HTML report
mafhoom diff OLD_PATH NEW_PATH          # Change impact analysis
mafhoom demo                            # Offline demonstration
mafhoom report RUN_DIR                  # Report from a run
mafhoom evaluate SPEC [--gold GOLD]     # Evaluate across systems
mafhoom run-experiment SPEC SYSTEM      # Run single system
mafhoom validate-dataset PATH           # Validate dataset
```

## Pipeline Architecture

```
Document ingestion
        |
Layout-aware text segmentation
        |
Candidate requirement detection (rule-based / Claude)
        |
Atomic requirement decomposition
        |
Semantic parsing -> HRIR construction
        |
Normalization
        |
Deterministic compiler passes (8 passes)
        |
[Hybrid mode] Claude finding filter (FP removal)
        |
Artifact generation backends
        |
Evaluation and reporting
```

## Compiler Passes

1. **Schema Validation** - Invalid fields, ranges, references
2. **Ambiguity Detection** - Vague terms, unclear references, with safe pronoun context filtering
3. **Completeness** - Missing information (timeout values, reset polarity, etc.) with spec-wide context
4. **Duplicate Detection** - Exact, normalized, and near-duplicate requirements
5. **Contradiction Detection** - Numeric, timing, modality, and polarity conflicts with entity overlap gating
6. **Timing Consistency** - Impossible bounds, conflicting deadlines
7. **State Consistency** - Unreachable states, missing transitions
8. **Dependency Analysis** - Requirement graph, decomposition siblings, shared-target edges

## Supported Formats

- Markdown (`.md`)
- Plain text (`.txt`)
- PDF (`.pdf`)
- DOCX (`.docx`)
- JSON (`.json`)
- JSONL (`.jsonl`)

## Running Tests

```bash
# Unit tests (no API key needed)
python3 -m pytest tests/unit/ -v

# Integration tests (no API key needed)
python3 -m pytest tests/integration/ -v

# All offline tests (225 tests)
python3 -m pytest tests/ -v -k "not Live"

# API tests (requires ANTHROPIC_API_KEY)
python3 -m pytest tests/api/ -v -m api
```

## Benchmark Results

### Pipeline Output (10 clean specs, 549 requirements)

| Spec | Reqs | HRIR | Findings |
|------|------|------|----------|
| ADC Controller | 66 | 97 | 16 |
| APB | 53 | 83 | 12 |
| AXI-Lite | 58 | 96 | 24 |
| Cache Controller | 69 | 102 | 15 |
| DMA | 62 | 105 | 15 |
| FIFO | 28 | 35 | 15 |
| I2C | 55 | 106 | 20 |
| Interrupt Controller | 56 | 83 | 10 |
| SPI | 51 | 91 | 10 |
| UART | 51 | 81 | 19 |
| **Total** | **549** | **879** | **156** |

### Seeded Defect Detection (43 defects across 8 evaluated specs)

- **Recall: 100%** (43/43 seeded defects detected)
- **Total FPs: 80** across evaluated specs (most are valid findings beyond the seeded defects)
- Clean spec F1: 50.0% - 66.7% | Dirty spec F1: 43.5% - 52.6%

### Dirty Variant Results

| Spec | Reqs | HRIR | Findings |
|------|------|------|----------|
| FIFO (dirty) | 49 | 61 | 18 |
| UART (dirty) | 53 | 71 | 17 |
| Cache Controller (dirty) | 66 | 93 | 14 |

## Configuration

Configuration files are in `configs/`. Key settings:

```yaml
api:
  model: ""              # Claude model (or set MAFHOOM_MODEL env var)
  temperature: 0.0       # Low for structured extraction
  cache_read: true       # Use cached API responses
  cache_write: true      # Save API responses to cache

analysis:
  duplicate_threshold: 0.85
  contradiction_candidate_threshold: 0.6

experiment:
  random_seed: 42
  output_dir: "results"
```

## Project Structure

```
mafhoom/          # Core package
  models/         # HRIR schema, enums, findings
  ingestion/      # Document parsers
  extraction/     # Requirement detection, decomposition, semantic parsing
  normalization/  # Signal, timing, unit normalization
  ontology/       # Hardware ontology (YAML)
  passes/         # Deterministic compiler passes + hybrid filter
  backends/       # SVA, test plan, traceability generation
  api/            # Claude API client with caching
  evaluation/     # Metrics and evaluation
  experiments/    # Experiment runner
  pipeline.py     # Main pipeline orchestration
  cli.py          # CLI interface
  config.py       # Configuration management
prompts/          # Versioned Claude prompts
configs/          # YAML configuration files
data/             # Datasets, annotations, and gold standards
examples/         # Example specifications
scripts/          # Evaluation and benchmark scripts
tests/            # Unit, integration, API tests (225 tests)
docs/             # Documentation
```

## Documentation

- [Architecture](docs/architecture.md)
- [HRIR Specification](docs/hrir_specification.md)
- [Experiment Design](docs/experiments.md)
- [API Usage](docs/api_usage.md)
- [Reproducibility](docs/reproducibility.md)
- [Annotation Guidelines](docs/annotation_guidelines.md)
- [Limitations](docs/limitations.md)

## License

MIT
