lazyuvm 0.1.3

Local-first RTL verification helper for UVM scaffolds, protocol checks, logs, and reports.

LazyUVM

LazyUVM is a local-first RTL verification helper that turns simple Verilog/SystemVerilog modules into starter testbenches, protocol guesses, UVM skeletons, and simulation-log triage reports.

It is intentionally small: one Python file, no required Python packages, and optional local AI through Ollama.

The LazyUVM checked badge means the repository's smoke checks pass on GitHub Actions. It is a quick project-health signal, not silicon sign-off.

What It Does Today

• Scans RTL files and reports modules, parameters, ports, widths, and directions.
• Generates starter SystemVerilog testbenches.
• Infers common bus protocols from port names:
  • APB
  • AHB
  • AXI-Lite
  • AXI-Stream
• Prints a simple multi-file hierarchy tree from module instances.
• Reads simulator-style filelists with source files, include dirs, defines, and nested -f entries.
• Emits copy/paste Verilator, VCS, and Questa command lines from a project filelist.
• Resolves simple parameterized port widths such as [WIDTH-1:0] and [(DATA_WIDTH/8)-1:0].
• Runs lightweight static RTL checks for unresolved instances, unconnected ports, reset oddities, and obvious width mismatches.
• Cross-checks simple text spec rules against simulator log timelines.
• Generates UVM skeleton files:
  • interface
  • sequence item
  • driver
  • monitor
  • sequencer
  • sequence
  • agent
  • env
  • smoke test
  • top module
  • filelist
• Emits APB-aware driver and monitor handshake timing with reset guards and a generated pready timeout.
• Emits AXI-Lite-aware driver and monitor handshake timing across write address, write data, write response, read address, and read data channels.
• Emits protocol-aware SVA and coverage starter files:
  • APB setup/access/wait-state assertions
  • AXI-Lite valid/ready hold assertions
  • APB wait-state/read/write/error and AXI-Lite covergroup starter models
• Emits SystemVerilog bind files that attach generated SVA and coverage sentinels to the DUT.
• Runs a local auto-run loop that generates artifacts, lints with Verilator, compiles with iverilog, runs vvp, triages logs, and writes a Markdown report.
• Runs a seed-based local regression loop over selected modules and writes a PASS/FAIL case matrix.
• Runs a small regress.yaml test plan so projects can keep repeatable smoke tests in source control.
• Triages text coverage reports and suggests concrete next stimulus targets for low or missing coverage.
• Writes starter SystemVerilog directed-stimulus skeletons from coverage holes.
• Summarizes simulator logs with built-in rules, a time-ordered event timeline, and optional local Ollama AI.
• Stores and reuses explicit local-only log and coverage issue patterns when --learn-cache and --use-cache are used.
• Writes pattern-aware triage reports that combine log facts, spec cross-checks, local pattern packs, and optional local Ollama summaries.

Why This Exists

Research frameworks such as UVLLM and UVMarvel explore ambitious LLM-driven RTL verification flows. LazyUVM is deliberately narrower: a lightweight CLI that a student, junior engineer, or small team can clone and run locally in a few minutes.

Area	Research Frameworks	LazyUVM
Goal	Broad automated verification research	Fast local UVM scaffold generation
Setup	Larger framework and experiment flow	Single Python script
AI	Often benchmarked with large LLM workflows	Optional local Ollama model
First use	Read paper, configure stack, run experiments	Run one command on an RTL file
Current strength	Full research pipeline	Protocol-aware starter files

LazyUVM is not a replacement for a signoff verification flow. It is a bootstrap tool for getting from "I have RTL" to "I have a first UVM environment shape" quickly.

For the current package boundary, known limits, and modularization roadmap, see docs/architecture.md.

Installation

From a local checkout:

python3 -m pip install -e .
lazyuvm --version
lazyuvm --help

From the current main branch:

pipx install git+https://github.com/jeonghunx/LazyUVM.git

From PyPI's latest release:

pipx install lazyuvm

Contributors can still run python3 rtl_scout.py ... directly from the repository, but lazyuvm ... is the preferred CLI.

Release Status

Current repository version: 0.1.3

Latest PyPI release: 0.1.2

• See CHANGELOG.md for the release history.
• See RELEASE_CHECKLIST.md before cutting a tag.
• See docs/releases/v0.1.2.md for the v0.1.2 release note draft.
• The GitHub Actions badge should be green before cutting a release tag.
• PyPI publishing is configured through .github/workflows/release.yml and PyPI Trusted Publishing.

Quick Start

From a checkout of the current main branch:

cd "/mnt/c/Users/jeonghun-dev/Documents/New project"

lazyuvm --version
lazyuvm check
lazyuvm report
lazyuvm regress
lazyuvm uvm
lazyuvm baseline save
lazyuvm baseline diff
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --no-ai

lazyuvm init writes a project-owned lazyuvm.toml. Commit that file so teammates and CI can run the same local verification flow without copying long command lines.

For a new RTL project:

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

For a new GitHub project that should get the full LazyUVM workflow:

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

The generated workflow installs LazyUVM from the package source passed with --package. The default is the PyPI package, lazyuvm. During unreleased development, pass a Git URL if you intentionally want CI to install from a branch.

For focused one-off examples, see the sections below for filelists, tool commands, regression, coverage triage, hierarchy, auto-run, log analysis, and reviewed pattern packs.

Project Config

lazyuvm.toml is the sticky project entry point:

[project]
filelist = "examples/files.f"
top = "apb_timer"
no_ai = true
ollama_model = "llama3.2:1b"
ai_timeout = 60
no_lint = false

[reports]
auto_dir = ".lazyuvm"
report = "LazyUVM_Report.md"
regress_file = "examples/regress.yaml"
regress_dir = ".lazyuvm_regress"
regress_report = "LazyUVM_Regression.md"
uvm_dir = "generated_uvm"
seeds = "1"
baseline = "lazyuvm_baseline.json"
coverage_report = "examples/coverage_report.txt"
coverage_threshold = 90.0

[registry]
cache_dir = ".lazyuvm_cache"
registry_dir = ".lazyuvm_registry"

[knowledge]
strict_modules = ["apb_timer", "axi_lite_gpio"]
strict_checks = ["missing_protocol_maps", "missing_register_maps", "no_reviewed_patterns"]
strict_require_registry_bundles = false

Once the config is committed, the project workflow becomes short and repeatable:

lazyuvm check     # hierarchy + static RTL checks
lazyuvm report    # auto-run + Markdown report
lazyuvm regress   # regress.yaml or seed regression
lazyuvm uvm       # generated UVM/SVA/coverage/bind skeletons
lazyuvm baseline save
lazyuvm baseline diff
lazyuvm pack stats
lazyuvm know query "apb timeout"
lazyuvm know recommend

The reviewable knowledge formats behind this workflow are documented in docs/knowledge_formats.md.

lazyuvm know query is the first knowledge-workflow command: it groups matching protocol maps, register/spec maps, reviewed patterns, packs, and bundles for one local question. It does not upload project data or ask an AI by default:

lazyuvm know query "pready never asserted"
lazyuvm know query "ctrl enable" --out LazyUVM_Knowledge_Query.md
lazyuvm know recommend --out LazyUVM_Knowledge_Recommend.md
lazyuvm know recommend --json --out LazyUVM_Knowledge_Recommend.json
lazyuvm know recommend --strict --module apb_timer
lazyuvm know doctor --strict

Use --strict when CI should fail on missing core project knowledge such as protocol maps, register maps, or reviewed patterns. Registry bundles are reported as recommendations, but they are not strict blockers by default. Projects can pin that policy in [knowledge]: use strict_modules to limit the enforced entry points, strict_checks to choose blocker recommendation codes, and strict_require_registry_bundles = true when a team bundle is mandatory. know recommend --strict and know doctor --strict use the same policy so local diagnostics and CI gates agree.

The repository includes a portable example bundle:

lazyuvm pack bundle-validate examples/team_knowledge_bundle.json
lazyuvm pack bundle-import examples/team_knowledge_bundle.json --maps-out lazyuvm_imported_maps.toml

For the full local publish/pull loop, see docs/team_registry_demo.md.

The checked GitHub Actions workflow also smoke-tests this knowledge loop by validating the example bundle, running know query / know recommend, uploading the Markdown and JSON recommendation reports as an artifact, writing a short baseline/knowledge summary to the GitHub Actions run summary, and round-tripping a bundle through a temporary self-hosted registry.

Custom Protocol Maps

LazyUVM first tries protocol inference from familiar names such as psel, penable, and awvalid. Real projects often use names like cfg_sel, cfg_enable, or cfg_ack. Add a [protocols.<module>] section to lazyuvm.toml when a module uses project-specific naming:

[protocols.cfg_timer]
protocol = "APB"
pclk = "clk"
presetn = "rst_n"
paddr = "cfg_addr"
psel = "cfg_sel"
penable = "cfg_enable"
pwrite = "cfg_write"
pwdata = "cfg_wdata"
prdata = "cfg_rdata"
pready = "cfg_ack"
pslverr = "cfg_err"

Then run the normal project command:

lazyuvm uvm --config examples/custom_protocols.toml --uvm-dir /tmp/lazyuvm_custom_uvm

Generated UVM/SVA/coverage files use the real project port names while keeping the APB starter behavior. This is explicit project mapping, not semantic protocol discovery.

lazyuvm check, lazyuvm report, lazyuvm regress, lazyuvm baseline, and lazyuvm uvm validate these maps before trusting them. Missing required protocol signals, unknown canonical keys, and mapped ports that do not exist in the RTL are reported as errors.

To draft a map for custom names, use the suggestion command:

lazyuvm suggest-protocol-map examples/cfg_timer.sv --module cfg_timer --out suggested_protocols.toml
lazyuvm suggest-protocol-map --config examples/custom_protocols.toml --out suggested_protocols.toml

The output is a reviewable TOML snippet with per-signal confidence comments. It is not applied automatically; merge it into lazyuvm.toml only after review and validation.

Register/Spec Maps

Protocol maps explain how project-specific port names map onto APB/AXI-style signals. Register/spec maps explain what project registers mean. This is how LazyUVM avoids pretending that AI inferred ctrl[0] = enable; the team writes that knowledge once and commits it:

[registers.cfg_timer.timer_value]
address = "0x00"
width = 32
access = "rw"
reset = "0x00000000"
description = "Timer value register"

[fields.cfg_timer.timer_value.value]
bits = "31:0"
access = "rw"
reset = "0x00000000"
description = "Current timer value"

Validate and print the map:

lazyuvm regs --config examples/custom_protocols.toml

To draft a register/spec map from obvious signal names, use:

lazyuvm suggest-register-map examples/cfg_timer.sv --module cfg_timer --out suggested_registers.toml

The output is also review-first. LazyUVM may suggest timer_value as a register candidate, but address and reset facts remain TODO until the team checks the spec. Merge the snippet only after review, then run lazyuvm regs and lazyuvm check.

lazyuvm check and lazyuvm baseline save also validate register/spec maps, so broken team knowledge fails early instead of silently feeding bad generated artifacts.

Artifact Quality Gate

lazyuvm quality generates the UVM/SVA/coverage starter set into a quality workspace and checks that the artifact set is complete and structurally sane:

lazyuvm quality --config examples/custom_protocols.toml

It verifies required files, package includes, filelist references, missing-signal placeholders, TODO/FIXME markers, and balanced SystemVerilog structures such as module/endmodule, class/endclass, and task/endtask.

The same report now includes a knowledge recommendation summary so CI reviewers can see protocol-map, register-map, reviewed-pattern, and bundle gaps next to artifact quality findings.

This is a local CI smoke gate for generated starters. It does not claim to replace a commercial simulator compiling full UVM with a vendor library. Use --strict when you want warnings to fail CI too.

Team Knowledge Bundles

LazyUVM's moat is reviewed local knowledge, not secret telemetry. A team can export protocol maps, register/spec maps, and reviewed pattern cache entries as one portable bundle:

lazyuvm pack --config examples/custom_protocols.toml bundle-export team_cfg_timer_bundle.json
lazyuvm pack bundle-validate team_cfg_timer_bundle.json
lazyuvm pack bundle-import team_cfg_timer_bundle.json --maps-out lazyuvm_imported_maps.toml
lazyuvm pack bundle-diff old_bundle.json team_cfg_timer_bundle.json

Importing a bundle merges reviewed patterns into the local cache, but it does not silently edit lazyuvm.toml. Protocol/register map sections are written to a reviewable TOML snippet so a human can inspect them before merging.

Self-hosted teams can publish and pull bundles through the file-based registry:

lazyuvm pack --config examples/custom_protocols.toml bundle-publish cfg_timer_basics
lazyuvm pack bundle-pull cfg_timer_basics --maps-out lazyuvm_imported_maps.toml

Search the accumulated local knowledge without opening every JSON/TOML file by hand:

lazyuvm know search apb timeout
lazyuvm know show protocols.cfg_timer
lazyuvm know doctor

CI Bootstrap

lazyuvm init-ci creates the files a project needs to make LazyUVM part of the normal team workflow:

lazyuvm.toml
regress.yaml
LAZYUVM_BADGE.md
.github/workflows/lazyuvm.yml

The generated workflow installs LazyUVM from the package source passed with --package, runs lazyuvm check, lazyuvm report, lazyuvm regress, validates the local pattern-pack state, and then compares against lazyuvm_baseline.json when one exists. If no baseline exists yet, CI saves an initial one for that run so the workflow can pass before the team commits a reviewed baseline. Add --strict-knowledge when the generated workflow should fail on the configured [knowledge] policy from day one.

Baseline snapshots also track local knowledge counts such as protocol maps, register maps, fields, reviewed patterns, and registry bundles. That makes lazyuvm baseline diff show whether the team's reusable verification memory is growing along with the RTL checks.

Use --force only when you intentionally want to overwrite generated files.

Team Pattern Packs

lazyuvm pack is the product-style workflow for team-reviewed local bug patterns. It uses the [registry] paths in lazyuvm.toml, so teams can share trusted patterns without any external service:

lazyuvm pack report
lazyuvm pack search paddr
lazyuvm pack show b5064cf
lazyuvm pack review b5064cf --note "APB setup/access timeout seen in smoke regressions"
lazyuvm pack export team_apb_patterns.json
lazyuvm pack import team_apb_patterns.json
lazyuvm pack publish apb_smoke
lazyuvm pack list
lazyuvm pack pull apb_smoke
lazyuvm pack validate
lazyuvm pack doctor --strict
lazyuvm pack doctor

By default, lazyuvm pack export exports only reviewed entries. Use --all when you deliberately want a raw cache backup. Use pack validate before publishing or sharing a team pack. It checks for empty packs, missing metadata, unreviewed registry entries, and reviewed entries without review notes. Use pack doctor --strict in CI when you want the same health check to fail on validation issues. Use plain pack doctor when a teammate says their cache or shared registry is not behaving as expected.

Generated files appear under:

generated_uvm/apb_timer/

The UVM generator now also writes assertion and coverage sentinels:

generated_uvm/apb_timer/lazyuvm_apb_timer_sva.sv
generated_uvm/apb_timer/lazyuvm_apb_timer_coverage.sv
generated_uvm/apb_timer/lazyuvm_apb_timer_bind.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_sva.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_coverage.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_bind.sv

The bind files use SystemVerilog bind plus implicit port connections, so the generated sentinels can be attached to the DUT without editing the original RTL.

Generated outputs are ignored by Git because they can be recreated at any time.

Filelist Project Linker

Real RTL projects often compile from a files.f file instead of a single source path. LazyUVM can now use that same project entry point:

lazyuvm --filelist examples/files.f --hierarchy
lazyuvm --filelist examples/files.f --checks
lazyuvm --filelist examples/files.f --auto-run --no-ai

Supported filelist syntax:

+incdir+include
+define+SIMULATION
+define+WIDTH=32
-f nested_files.f
rtl/top.sv
rtl/block.sv

File paths and nested filelists are resolved relative to the filelist that mentions them. --auto-run passes include dirs and defines through to Verilator and Icarus Verilog, then records the exact reproduce commands in the Markdown report.

Tool Command Generator

LazyUVM can turn a project filelist into copy/paste commands for common RTL tools without launching licensed software:

lazyuvm --filelist examples/files.f --emit-tool verilator
lazyuvm --filelist examples/files.f --emit-tool vcs
lazyuvm --filelist examples/files.f --emit-tool questa

Example output:

verilator --lint-only --sv -f examples/files.f
vcs -sverilog -full64 -f examples/files.f
vlog -sv -f examples/files.f

When you pass --module, LazyUVM treats it as the top/module hint:

lazyuvm --filelist examples/files.f --emit-tool verilator --module chip_top
lazyuvm --filelist examples/files.f --emit-tool vcs --module chip_top
lazyuvm --filelist examples/files.f --emit-tool questa --module chip_top

Regression Runner

For a small local regression:

lazyuvm --filelist examples/files.f --regress --seeds 1,2,3 --no-ai

This writes:

LazyUVM_Regression.md
.lazyuvm_regress/

The regression runner:

• generates a smoke testbench for each selected module
• passes +LAZYUVM_SEED=<seed> into vvp
• repeats each module across the requested seed list
• keeps each case in its own workspace folder
• records lint, compile, simulation, and overall PASS/FAIL status in a Markdown matrix

Seed ranges are supported:

lazyuvm --filelist examples/files.f --regress --seeds 1-10 --module chip_top --no-ai

This is still an early screening loop, not signoff. Its job is to make local smoke regressions cheap enough to run constantly.

For a project-owned regression plan:

lazyuvm --regress-file examples/regress.yaml --no-ai

Example regress.yaml:

tests:
  - name: apb_smoke
    files: files.f
    module: apb_timer
    seeds: 1,2

  - name: axi_smoke
    files: files.f
    module: axi_lite_gpio
    seeds: 1,2

Paths in the YAML file are resolved relative to that YAML file, so a test plan under examples/ can simply use files: files.f.

Supported keys:

• name: test name shown in reports
• files or filelist: one filelist path or a short list
• module or top: module to run
• seeds: comma list or range such as 1,2,3 or 1-10

Coverage Triage

For a text coverage report:

lazyuvm --analyze-coverage examples/coverage_report.txt --no-ai

LazyUVM extracts:

• coverage percentages such as line, branch, toggle, and functional coverage
• common vendor-style table rows with covered/total/percent columns
• ratio-only rows such as 0/1 when the row looks like coverage data
• low coverage metrics below a threshold
• explicit miss lines such as 0 hits, Hits: 0, Count = 0, uncovered, not covered, and never hit
• rule-based next stimulus ideas for APB, AXI-Lite, reset, FSM, and toggle holes

To change the low-coverage threshold:

lazyuvm --analyze-coverage examples/coverage_report.txt --coverage-threshold 80 --no-ai

To write the analysis to a file:

lazyuvm --analyze-coverage examples/coverage_report.txt --coverage-md LazyUVM_Coverage.md --no-ai

With Ollama available, omit --no-ai to add a local summary on top of the rule-based findings.

To generate starter SystemVerilog stimulus tasks from the same coverage holes:

lazyuvm --analyze-coverage examples/coverage_report.txt --coverage-stimulus-dir generated_stimulus --module apb_timer --no-ai
lazyuvm --analyze-coverage examples/vendor_coverage_report.txt --coverage-stimulus-dir generated_stimulus --module apb_timer --no-ai

This writes a skeleton such as:

generated_stimulus/lazyuvm_apb_timer_coverage_stimulus.sv

The generated file contains task stubs for holes such as APB wait states, AXI-Lite backpressure, reset edges, toggles, and generic directed bins. It also records parsed targets such as source locations, coverpoints, bins, branch conditions, and likely protocol signals. It intentionally leaves BFM/UVM calls as TODO comments because real projects name their sequence APIs differently.

Hierarchy Scan

For a folder with multiple RTL files:

lazyuvm --hierarchy examples
lazyuvm --hierarchy --module chip_top examples

This prints top-module candidates and a simple instance tree, for example:

chip_top [AXI-Lite 95%, APB 80%]
|-- apb_timer u_timer [APB 90%]
`-- axi_lite_gpio u_gpio [AXI-Lite 100%]

Width Solver

For parameterized designs:

lazyuvm --widths examples/axi_lite_gpio.sv

This resolves simple integer expressions in packed ranges:

axi_lite_gpio:
  parameters:
    ADDR_WIDTH = 12 => 12
    DATA_WIDTH = 32 => 32
  ports:
    input awaddr: [ADDR_WIDTH-1:0] => 12 bits
    input wstrb: [(DATA_WIDTH/8)-1:0] => 4 bits

Static Checks

For a quick local RTL review:

lazyuvm --checks examples

LazyUVM checks what it can prove from the local source:

• unresolved module instances
• unconnected named child ports
• obvious parent/child port width mismatches
• clock-like modules without reset-like inputs
• reset-like ports with suspicious directions

These checks are intentionally conservative: if LazyUVM cannot infer a width confidently, it avoids guessing a mismatch.

Auto-Run Report

For a one-command local triage loop:

lazyuvm --auto-run examples/apb_timer.sv

This writes:

LazyUVM_Report.md
.lazyuvm/

The auto-run loop:

• scans the RTL
• runs lightweight static RTL checks
• generates a starter testbench
• generates UVM skeleton files
• lints the RTL with Verilator when available
• compiles with iverilog
• runs with vvp
• triages lint/compile/simulation logs
• optionally asks local Ollama for an explanation
• writes patch suggestions under .lazyuvm/patches/

If Verilator is not installed or you only want the simulator path:

lazyuvm --auto-run --no-lint examples/apb_timer.sv

Safety rule: LazyUVM does not modify your RTL source files during auto-run. Patch suggestions are isolated for manual review.

Local AI Log Analysis

AI is optional. The rule-based analyzer works without Ollama:

lazyuvm --analyze-log examples/sim_error.log --no-ai
lazyuvm --analyze-log examples/timing_trace.log --no-ai

The log analyzer extracts suspicious lines and a compact timeline before local AI is used:

Timeline:
  100ns L3 [event] signals: psel=1, penable=0, pwrite=1
  120ns L5 [error] signals: penable=1, penable=0, psel=1, pready=0
  130ns L7 [fatal] signals: psel=1, penable=0, pready=0

With Ollama:

curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2:1b

lazyuvm --analyze-log examples/sim_error.log --ollama-model llama3.2:1b

Spec-Aware Log Cross-Check

For a small spec/log comparison:

lazyuvm --analyze-log examples/timing_trace.log --spec examples/spec.txt --no-ai

LazyUVM extracts simple requirement lines containing words such as must, shall, within N cycles, after reset, and remain high until, then compares the supported rules against the log timeline.

Example requirement:

PENABLE must assert one cycle after PSEL is asserted.
PSEL must remain high until PREADY.

The checker is intentionally conservative. It reports direct evidence from the timeline, for example:

Spec expects `penable` after `psel`, but timeline never shows `penable=1` before the failure evidence.

This is a fact cross-check, not a full natural-language spec verifier.

Local Pattern Cache

LazyUVM does not upload project data. By default, it only prints analysis results. If you explicitly add --learn-cache, it stores a small local pattern entry under .lazyuvm_cache/patterns.json.

lazyuvm --analyze-log examples/timing_trace.log --spec examples/spec.txt --learn-cache --no-ai
lazyuvm --analyze-coverage examples/coverage_report.txt --learn-cache --no-ai
lazyuvm --cache-report

After patterns are learned, use --use-cache to compare the current log or coverage report with the local project memory:

lazyuvm --analyze-log examples/timing_trace.log --spec examples/spec.txt --use-cache --no-ai
lazyuvm --analyze-coverage examples/coverage_report.txt --use-cache --no-ai

For a shareable Markdown debug report, use pattern-aware triage:

lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --no-ai
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --ai

The first command is fully rule-based. The second command adds a local Ollama summary when a model is available. In both cases, LazyUVM uses extracted log facts and local pattern-pack matches as evidence; pattern matches are prior debugging memory, not proof.

After a human confirms the issue, close the debug-to-pack loop in one command:

lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --learn-reviewed --note "confirmed APB setup/access timeout" --no-ai
lazyuvm pack show b5064cf

--learn-reviewed stores the current pattern and marks it reviewed immediately. Use it only after someone has checked the evidence.

The cache keeps normalized fingerprints, categories, repeated-hit counts, signal names found in timelines, and short rule-based hints. Cache matching uses local fingerprints plus category, signal, and hint-token overlap. It is meant to become a private project memory, not hidden telemetry.

Use a custom cache folder when you want to keep experiments separate:

lazyuvm --analyze-log examples/timing_trace.log --learn-cache --cache-dir /tmp/lazyuvm_cache --no-ai
lazyuvm --analyze-log examples/timing_trace.log --use-cache --cache-dir /tmp/lazyuvm_cache --no-ai

For team sharing without a central server, export and import the cache as a plain JSON file:

lazyuvm --cache-export lazyuvm_patterns.json
lazyuvm --cache-import lazyuvm_patterns.json
lazyuvm --cache-report

Import merges by fingerprint. Re-importing the same file updates matching entries instead of duplicating them, so teams can pass around a reviewed pattern pack in source control, chat, or an internal artifact store.

For a reviewed team pattern pack, mark only trusted entries before exporting:

lazyuvm --cache-report
lazyuvm --cache-review b5064cf --review-note "APB setup/access timeout seen in smoke regressions"
lazyuvm --cache-export-reviewed lazyuvm_reviewed_patterns.json
lazyuvm --cache-import lazyuvm_reviewed_patterns.json

The shorter project workflow is preferred once lazyuvm.toml exists:

lazyuvm pack report
lazyuvm pack search paddr
lazyuvm pack show b5064cf
lazyuvm pack review b5064cf --note "APB setup/access timeout seen in smoke regressions"
lazyuvm pack export lazyuvm_reviewed_patterns.json
lazyuvm pack import lazyuvm_reviewed_patterns.json
lazyuvm pack validate

pack review, pack unreview, --cache-review, and --cache-unreview accept unique fingerprint prefixes, so you do not need to type the full hash.

For a self-hosted team registry, publish reviewed packs into a shared folder:

lazyuvm --registry-dir /shared/lazyuvm_registry --registry-publish apb_smoke
lazyuvm --registry-dir /shared/lazyuvm_registry --registry-list
lazyuvm --registry-dir /shared/lazyuvm_registry --registry-pull apb_smoke

With lazyuvm.toml, use the product commands:

lazyuvm pack publish apb_smoke
lazyuvm pack list
lazyuvm pack pull apb_smoke
lazyuvm pack doctor --strict

The registry is just files:

lazyuvm_registry.json
packs/apb_smoke.json

That makes it usable with an internal Git repo, shared drive, artifact store, or any company-controlled file server. No external service is required.

As the cache grows, inspect and prune it:

lazyuvm --cache-stats
lazyuvm --cache-prune 100
lazyuvm --cache-stats

Pruning keeps the highest-count and most recently seen entries first. Use export before pruning if you want a backup:

lazyuvm --cache-export lazyuvm_patterns_backup.json
lazyuvm --cache-prune 100

License

LazyUVM is released under GPLv3. Commercial licensing can be considered separately for companies that need different terms.

This is not legal advice; talk to a lawyer before using any open-source license strategy commercially.