Metadata-Version: 2.4
Name: lazyuvm
Version: 0.8.4
Summary: Local-first RTL verification knowledge platform for UVM scaffolds, reviewed maps, pattern packs, and CI gates.
Author: LazyUVM contributors
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/jeonghunx/LazyUVM
Project-URL: Repository, https://github.com/jeonghunx/LazyUVM
Project-URL: Issues, https://github.com/jeonghunx/LazyUVM/issues
Keywords: rtl,systemverilog,uvm,verification,verification-knowledge,eda
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# LazyUVM

[![LazyUVM checked](https://github.com/jeonghunx/LazyUVM/actions/workflows/lazyuvm.yml/badge.svg)](https://github.com/jeonghunx/LazyUVM/actions/workflows/lazyuvm.yml)
[![PyPI](https://img.shields.io/pypi/v/lazyuvm.svg)](https://pypi.org/project/lazyuvm/)

LazyUVM is a local-first Git-native verification knowledge layer for RTL
projects.

Start from RTL, generate starter verification artifacts, capture reviewed
protocol/register/behavior knowledge, and turn simulator output into
CI-readable evidence.

LazyUVM is not trying to replace VCS, Xcelium, Questa, Verilator, or vManager.
It makes their output reviewable, local, Git-tracked, and CI-friendly.

```text
RTL + lazyuvm.toml + simulator reports
  -> LazyUVM
  -> UVM/cocotb/C-header starters
  -> spec/register/behavior/coverage/waiver traceability
  -> Markdown/JSON evidence for local review and CI
```

LazyUVM is deliberately local-first: no required cloud service, no required
third-party Python dependencies, and optional local Ollama summaries only when a
user explicitly asks for local AI help.

## Try It In 3 Minutes

Install from PyPI:

```bash
pipx install lazyuvm
lazyuvm --version
```

Then print the shortest runnable demo:

```bash
lazyuvm demo quickstart
```

That demo shows the copy/paste path from a public coverage report to normalized
LazyUVM evidence and a gate report. It does not require a simulator, private
spec PDF, cloud service, or local AI.

## Product Boundary

LazyUVM is not a simulator.

LazyUVM is not a vManager replacement.

LazyUVM is not sign-off verification.

It sits next to those tools as a Git-native evidence layer:

```text
VCS / Xcelium / Questa / Verilator / existing reports
  -> LazyUVM normalized evidence
  -> Git review, CI summaries, manifests, and local knowledge reuse
```

## Why Use It

Most verification projects lose knowledge across specs, spreadsheets, old
emails, waiver notes, coverage reports, and personal debug history. LazyUVM
keeps that knowledge close to the code:

| Need | LazyUVM gives you |
| --- | --- |
| Start a project quickly | RTL scan, project config, starter UVM/SVA/coverage/cocotb output |
| Keep intent reviewable | `lazyuvm.toml` protocol maps, register maps, behavior specs, spec references |
| Reuse knowledge | reviewed pattern packs, local pack dependencies, lockfiles, overlay diffs |
| Review simulator output | normalized `lazyuvm.eda_report.v1` JSON from VCS/Questa/Xcelium/Verilator-style reports |
| Keep CI honest | `lazyuvm gate` Markdown/JSON evidence, waiver checks, manifest verification |
| Use AI safely | facts-only context for optional local Ollama explanations; humans still approve |

The useful stickiness is not hidden telemetry. It is the team's reviewed
verification knowledge living in Git.

## Pick Your Path

LazyUVM has a lot of commands, but most users should start with only one path:

| User | Start with | Add later | Avoid at first |
| --- | --- | --- | --- |
| Student / open-source RTL | `demo quickstart`, `check`, `uvm`, `cocotb`, `coverage parse` | `regs --c-header`, `spec --coverage-plan` | strict gates, waivers, pack policy |
| Solo developer / small team | `init`, `check`, `gate`, `know trace`, `know manifest` | reviewed waivers, pack reuse, `init-ci` | enterprise-style process too early |
| Startup / design house | CI gate, EDA report JSON, C headers, cocotb/UVM starters | pack lockfiles, overlay diff, waiver governance | public packs without review |
| Enterprise / existing EDA flow | `coverage parse`, `gate --eda-report-json`, offline/security docs | strict waiver policy, manifests, local AI review bundle | claims of sign-off replacement |

The adoption rule is simple: begin with local evidence, then add governance only
when the team is ready to review it.

## Install

From a checkout:

```bash
python3 -m pip install -e .
lazyuvm --version
```

For command discovery:

```bash
lazyuvm --help
lazyuvm demo --help
```

Older one-off flags still exist behind `lazyuvm legacy --help`, but new project
work should use `lazyuvm.toml` and the project commands below.

## Five-Minute Path

Create a project config:

```bash
lazyuvm init --filelist path/to/files.f --top your_top_module
```

Run local checks and starter exports:

```bash
lazyuvm check
lazyuvm uvm
lazyuvm cocotb --out-dir generated_cocotb
lazyuvm regs --c-header --out regs.h
```

Validate reviewed knowledge:

```bash
lazyuvm regs
lazyuvm spec
lazyuvm know trace --out LazyUVM_Traceability.md
lazyuvm know manifest --out LazyUVM_Knowledge_Manifest.json
```

Turn the current state into CI evidence:

```bash
lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json --report LazyUVM_Gate.md
```

Add GitHub Actions when the local flow is stable:

```bash
lazyuvm init-ci --filelist path/to/files.f --top your_top_module --repo OWNER/REPO --cocotb
```

## EDA Report Flow

LazyUVM v0.7 adds a small adapter contract for simulator and coverage reports.
The goal is to absorb report output into the same Git-reviewed evidence loop,
not to replace the simulator.

```bash
lazyuvm coverage parse reports/vcs_urg.txt \
  --tool vcs \
  --json-out LazyUVM_EDA_Report.json \
  --out LazyUVM_EDA_Report.md

lazyuvm gate \
  --eda-report-json LazyUVM_EDA_Report.json \
  --json-out LazyUVM_Gate.json \
  --report LazyUVM_Gate.md

lazyuvm spec trace --json --out LazyUVM_Spec_Trace.json
```

Bundle the local JSON evidence into a static CI artifact:

```bash
lazyuvm report bundle \
  --gate-json LazyUVM_Gate.json \
  --eda-report-json LazyUVM_EDA_Report.json \
  --spec-trace-json LazyUVM_Spec_Trace.json \
  --out LazyUVM_Report
```

Open `LazyUVM_Report/index.html` for the overview,
`LazyUVM_Report/coverage.html` for coverage-hole review,
`LazyUVM_Report/waivers.html` for waiver health, or
`LazyUVM_Report/spec_trace.html` for source-coordinate traceability.

Supported starter profiles:

| Profile | Typical source |
| --- | --- |
| `vcs` | Synopsys VCS URG-style summaries |
| `questa` | Siemens Questa vcover-style summaries |
| `xcelium` | Cadence Xcelium IMC-style summaries |
| `verilator` / `lcov` | Verilator and LCOV-style text reports |
| `generic` | simple line-oriented coverage notes |

See [docs/v0.7_stabilization.md](docs/v0.7_stabilization.md) for the stable
`lazyuvm.eda_report.v1` fields and the `coverage parse -> gate` handoff.
See [docs/report_bundle.md](docs/report_bundle.md) for the v0.8 static report
bundle skeleton.

## Typical Team Workflow

1. Commit `lazyuvm.toml`.
2. Add reviewed protocol/register/behavior/spec references as the project
   becomes understood.
3. Parse coverage or simulator reports into LazyUVM JSON.
4. Run `lazyuvm gate` locally and in CI.
5. Review Markdown/JSON evidence in pull requests.
6. Use packs, waivers, and manifests only when the team actually needs them.

That progression matters. Teams should not start by enabling every feature.
Start with a small reviewed config, then add governance as it pays for itself.

## Documentation Map

Do not read every document first. Pick one path:

| If you want to... | Start here |
| --- | --- |
| Find a runnable sample | [examples/README.md](examples/README.md) |
| Try the product flow | [docs/team_governance_demo.md](docs/team_governance_demo.md) |
| Understand PR repair commands | [docs/pr_workflow_cookbook.md](docs/pr_workflow_cookbook.md) |
| Export UVM, cocotb, C headers, and CI evidence | [docs/export_targets.md](docs/export_targets.md) |
| Reuse local knowledge packs | [docs/pack_reuse_workflow.md](docs/pack_reuse_workflow.md) |
| Parse EDA reports in CI | [docs/eda_ci_recipes.md](docs/eda_ci_recipes.md) |
| Review offline/security boundaries | [docs/eda_offline_adoption.md](docs/eda_offline_adoption.md) |
| Use local AI safely | [docs/ai_review_workflow.md](docs/ai_review_workflow.md) |

The full documentation index is [docs/README.md](docs/README.md).

## Local AI Boundary

LazyUVM does not ask AI to sign off RTL.

```text
LazyUVM = extract facts, link evidence, write stable JSON/Markdown
AI      = optionally explain those facts in local prose
Human   = review, approve, sign off
```

Useful commands:

```bash
lazyuvm know context "coverage closure" --gate-json LazyUVM_Gate.json --out LazyUVM_AI_Context.json
lazyuvm know context-verify LazyUVM_AI_Context.json
lazyuvm know prompt --context-json LazyUVM_AI_Context.json --out LazyUVM_AI_Prompt.txt
lazyuvm know explain "coverage closure" --context-json LazyUVM_AI_Context.json --ai --out LazyUVM_Knowledge_Explain.md
lazyuvm know guard --context-json LazyUVM_AI_Context.json --ai-output LazyUVM_Knowledge_Explain.md
```

AI output is a reading aid, not a reviewed fact or root-cause decision.

## Who It Is For

LazyUVM is a practical fit for:

- students and open-source RTL projects that need repeatable verification
  structure without enterprise tooling;
- small teams that want Git-reviewed protocol/register/spec knowledge;
- teams already using commercial simulators but wanting lightweight PR evidence;
- engineers who want local-first AI summaries without uploading design data.

It is not a substitute for a mature enterprise sign-off flow. If your company
already has vManager, Verdi, VCS, Xcelium, Questa, Jasper, or internal dashboards,
LazyUVM should complement that flow by making local evidence easier to review.

For enterprise conversations, the safest framing is:

```text
LazyUVM does not replace the enterprise flow.
LazyUVM turns local RTL knowledge and EDA output into reviewable Git/CI evidence.
```

## Release Status

Current repository version: `0.8.4`

Latest tagged release: `0.8.4`

Latest release note: [docs/releases/v0.8.4.md](docs/releases/v0.8.4.md)

See [CHANGELOG.md](CHANGELOG.md) for release history and
[RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md) before cutting a tag.

For small public-safe contributions, see [CONTRIBUTING.md](CONTRIBUTING.md).
For sensitive reports and private design-data boundaries, see
[SECURITY.md](SECURITY.md).

## Project Philosophy

The project is intentionally boring where it matters:

- local files over hidden services;
- reviewable TOML/JSON/Markdown over opaque databases;
- explicit spec/register/behavior links over magic inference;
- deterministic CI evidence over unverifiable AI claims;
- human approval over automated sign-off.

That is the adoption path: make the first local workflow useful, then let teams
keep more of their verification memory in a format they can review, diff, and
carry between projects.
