# UVM-Verification Project — Settings & State

## Project
- HF Space: `skumar889/semiconductor-pipeline` at `https://skumar889-semiconductor-pipeline.hf.space`
- GitHub: `saikumarstealth-creator/UVM-verification`
- Port: 7860 (Docker, HF Space)
- Frontend: Vite+React served as static files by FastAPI

## Generation Config Defaults (backend/schemas.py)
| Field | Default |
|---|---|
| design_name | (required) |
| protocol | (required) |
| model_type | "v2" |
| rl_strategy | "ucb" |
| enable_learning | true |
| strict_uvm | true |
| max_iterations | 1 |
| spec_yaml | (required) |

## ML Model Architecture
- **Tier 1**: TemplateModel — Jinja2 template rendering (fallback)
- **Tier 2**: EnhancedMLGenerationModelV2 — ensemble retrieval + RL + coverage-driven hybrid generation
  - `_select_generation_strategy()`: RL per-file-type Q-values aggregated, biased by coverage prediction
  - `_generate_by_retrieval()`: similarity search → SpecAdapter adaptation → validation
  - `_generate_by_llm()`: coverage-driven hybrid (generates targeted sequences for predicted gaps)
  - `_generate_by_template()`: Jinja2 fallback
  - RL: AdvancedReinforcementLearner with eligibility traces, experience replay, 4 exploration strategies (epsilon_greedy/softmax/UCB/thompson)
  - Coverage predictor: RandomForest + GBR + LinearRegression ensemble with Ridge meta-blender
- **Pipeline**: auto-training loop (generate → simulate → analyze → improve) up to max_iterations

## Key Files
- `src/models/coverage_predictor.py` — coverage prediction ensemble (15 features, 5000 synthetic samples)
- `src/models/enhanced_ml_model_v2.py` — main V2 model (1014 lines)
- `src/models/enhanced_ml_model.py` — V1 model (older, less sophisticated)
- `src/models/template_model.py` — Jinja2 template renderer
- `src/models/advanced_rl_learner.py` — RL with eligibility traces + experience replay
- `src/models/advanced_pattern_learner.py` — context-aware error pattern detection
- `src/models/similarity_index.py` — TF-IDF + structural similarity search
- `src/models/spec_adapter.py` — spec-to-spec adaptation with signal/register mapping
- `src/features/extractors.py` — SpecFeatureExtractor, RichSpecFeatureExtractor
- `src/pipeline.py` — TBPipeline with auto-training loop, SV check, quality score
- `src/evaluation/sv_checker.py` — Python-based SV syntax checker (no external tools needed)
- `src/evaluation/quality_score.py` — Composite quality score (completeness, syntax, RAL, coverage)
- `src/generation/engine.py` — GenerationEngine (model wrapper)
- `src/generation/templates/` — Jinja2 SV templates
- `backend/core/pipeline_manager.py` — HF Space backend pipeline orchestration
- `frontend/src/components/ConfigEditor.tsx` — UI generation config form
- `frontend/src/store/appStore.ts` — Zustand state store

## Key Decisions
- Replicate removed (free tier requires payment); all generation runs on HF Space CPU
- Coverage predictor uses synthetic training data (not real simulation feedback) — train on real data when available
- RL state: `{protocol}:{file_type}:{complexity_bucket}` (low/medium/high)
- Template files excluded from Docker via `.dockerignore`: `model_registry/`, `node_modules`, `__pycache__`, etc.
- **Phase 1 complete (Jun 2026)**: All 5 templates rewritten to be spec-driven — no more hallucinated registers
- `{% if p == "uart" %}` guards scope UART-specific blocks (scoreboard, sequence, test) cleanly
- SV syntax checker is Python-based (no iverilog/svlint dependency); runs on rendered `.sv` output

## Template Status (Post-Phase 2)
| Template | Status | Key Changes |
|---|---|---|
| `ral_model.sv.j2` | ✅ Spec-driven | Iterates `spec.registers` → register classes, block, adapter, predictor; no hardcoded UART names; `addr_bits` computed inline via `map\|max` (no `__setitem__` hack) |
| `coverage_collector.sv.j2` | ✅ Enhanced crosses | Added coverage crosses (baud×parity, baud×data_bits, parity×stop_bits, baud×frame); UART config CG with separate data_bits/stop_bits coverpoints |
| `scoreboard.sv.j2` | ✅ Record methods added | Added `record_tx()`, `record_rx()`, `record_error()`, `record_config()` for sequence→scoreboard integration |
| `sequence.sv.j2` | ✅ Production-grade | Response handling (`get_response`), helpers in `uart_base_seq` (no duplication), seq library, virtual seq, reset test, ASCII constraints, scoreboard record calls, factory override support |
| `sequence_item.sv.j2` | ✅ Enhanced | `uvm_object_utils_begin/end` with field macros, `error_type_e` enum, `do_print()`, `inject_error()` helper, `int unsigned delay` |
| `test.sv.j2` | ✅ UART tests expanded | Added `uart_reset_test`, `uart_virtual_test`; all UART-specific tests guarded by `{% if p == "uart" %}` |

## Pipeline additions (Jun 2026)
- **Step 6a2**: SV syntax check via `SVSyntaxChecker` — block structure, paren balance, type refs, protocol consistency, common pitfalls
- **Step 6a3**: Cross-file reference validation via `validate_generated_files()` — catches `reg_model.xxx` hallucinations where `xxx` not in spec registers; computes spec register/interf reference coverage
- **Step 6b**: AI quality score via `compute_quality_score()` — weighted composite including spec_coverage_score (35% weight); hallucination_penalty (-0.1 each, max -0.5)
- Results include `sv_check` dict, `quality_score` float, `cross_file_validation` dict (passed, hallucinations, spec_coverage)
- ZIP export at `GET /api/export-zip` — downloads all generated files as a single archive (wired to UI Download button)
- New files: `src/evaluation/cross_file_validator.py`

## Phase 2 Enhancements (Jun 2026) — AI Quality & UVM Completeness
- **sequence.sv.j2**: Major enhancement — response handling (`get_response`), duplicate helpers moved to `uart_base_seq` (reduces code 30-40%), sequence library (`uart_seq_lib`), virtual sequence (`uart_virtual_seq`), reset test (`uart_reset_test_seq`), ASCII constraint mode, scoreboard integration (`record_tx`/`record_rx`/`record_error`/`record_config`), `req`/`rsp` declarations
- **coverage_collector.sv.j2**: Added coverage crosses (`cross_baud_parity`, `cross_baud_data_bits`, `cross_parity_stop_bits`, `cross_baud_frame`), separate `cp_data_bits`/`cp_stop_bits` coverpoints
- **scoreboard.sv.j2**: Added `record_tx()`, `record_rx()`, `record_error()`, `record_config()` record methods for sequence integration
- **test.sv.j2**: Added `uart_reset_test` and `uart_virtual_test` classes
- **quality_score.py**: Enhanced with `sequence_score` metric, `to_dict()` (syntax/ral/coverage/sequence/overall scores), `generate_report()` JSON report method
- **pipeline.py**: Generates `ai_quality_report.json` and `coverage_summary.html` in output dir; sequence quality auto-detection from generated content

## Phase 3 (Jun 2026) — IP-XACT, CI/CD, Simulator Wrappers, Rich Dashboard
- **VCS Simulator Wrapper** (`src/simulation/vcs.py`): `VcsSimulator` implements `Simulator` with vlogan+vcs+simv pipeline; coverage parsing from log
- **Questa Simulator Wrapper** (`src/simulation/questa.py`): `QuestaSimulator` implements `Simulator` with vlib+vlog+vsim pipeline; coverage parsing from log
- **Both simulators wired** into `TBPipeline._create_simulator()` factory — `vcs` and `questa` entries added
- **IP-XACT Converter** (`src/data/ipxact.py`): `IPXACTConverter` class with bidirectional `to_ipxact()` / `from_ipxact()` — converts DesignSpec YAML ↔ IEEE 1685 XML; covers memory maps, registers, fields, reset values, access policies, bus interfaces, ports, parameters, vectors
- **IP-XACT export** in pipeline (`pipeline.py`): auto-generates `{design}.ipxact.xml` in output dir after coverage report
- **IP-XACT API endpoint** (`backend/main.py`): `GET /api/generate/{task_id}/ipxact` — downloads IP-XACT XML
- **Rich Dashboard HTML** (`pipeline.py::generate_coverage_html_report`): Replaced basic coverage report with full dashboard featuring: grid KPI cards (AI Quality, Simulation Coverage, RAL Readiness, Generated Files), coverage heatmap with 5-epoch trend per metric, per-test breakdown table (8 test types with coverage %, pass/fail status), AI quality scores with inline bar indicators, per-register coverage table, dark GitHub-style theme
- **GitLab CI/CD** (`.gitlab-ci.yml`): Full pipeline — lint (ruff+mypy), test (3.10/3.11/3.12 with coverage), generate (YAML+RTL smoke tests), regression (APB smoke), schema validation, GitLab Pages dashboard publication
- **GitLab CI helper** (`src/cicd/gitlab_ci.py`): module with `main()` to write `.gitlab-ci.yml`
- **`src/cicd/`** package created with `__init__.py`

## Known Issues
- `SpecFeatures.from_spec()` in coverage_predictor.py may fail if spec object doesn't have expected attributes (handled by heuristic fallback)
- V2 model's `_use_llm` flag defaults to False — coverage-driven hybrid path only activates when `use_llm=True`
- SV `{N{1'b1}}` concatenation pattern clashes with Jinja2 `{{ }}` — use `'1` (SV fill-ones literal) instead in templates
- **Docker entrypoint is `backend.main:app`**, not `src.api.server:app` — changes to API must go in `backend/main.py`
- IP-XACT converter does not handle hierarchical address blocks, cross-domain references, or bus abstraction definitions — these are rare in UVM testbench generation
- Dashboard trend data is simulated (5 epochs with pseudo-random variance) — real trend data from multi-iteration runs will replace this

## Next Steps
1. Wire cross_file_validation results into React frontend metrics display
2. Guard hardcoded UART register references (`reg_model.lcr`, `reg_model.dll`, etc.) in scoreboard/sequence/test behind a check that those registers actually exist in the spec
3. Add more protocol templates (AXI4, AHB, Wishbone)
4. Generate architecture diagram from spec  
5. Add register covergroups to the generated HTML coverage report
6. Add AXI4-Lite and APB4 protocol definitions with full signal sets
7. Create regression in CI for all 6 supported protocols

## Important Paths (Docker/HF Space)
- Backend root: `/app/backend/`
- Frontend dist: `/app/frontend/dist/`
- Templates: `/app/src/generation/templates/`
- Output: `/app/output/`

## Known Issues
- `SpecFeatures.from_spec()` in coverage_predictor.py may fail if spec object doesn't have expected attributes (handled by heuristic fallback)
- V2 model's `_use_llm` flag defaults to False — coverage-driven hybrid path only activates when `use_llm=True`
- SV `{N{1'b1}}` concatenation pattern clashes with Jinja2 `{{ }}` — use `'1` (SV fill-ones literal) instead in templates
- **Docker entrypoint is `backend.main:app`**, not `src.api.server:app` — changes to API must go in `backend/main.py`