v2.3.0: Core Refactor, Type Safety & Observability

Summary

Version v2.3.0 represents a major architectural maturity milestone for Star Ground. This release transitions the build system to uv, decomposes the monolithic core library into a modular package, enforces strict type safety, and introduces a Debug Console for improved observability.

Significant performance optimizations have been applied to the PDF parsing kernel, and the codebase now adheres to strict Mypy and Ruff standards.

---

New Features

• Debug Console & Observability: * Added a real-time Debug Console to the UI that streams application logs.
  • Implemented a downloadable log artifact system ("Download Debug Logs") for better error reporting.
  • Errors are now categorized into "Total Failure" (Red) and "Partial Success" (Yellow).
• Updated Visuals: Refreshed the repository demonstration with a new GIF and improved README.md layout using HTML for better scaling.

Architecture & Refactoring

• Core Library Decomposition: * Refactored the monolithic bom_lib.py into a structured package (src/bom_lib/) with dedicated modules for parsing, sourcing, and management.
  • Implemented the Strategy Pattern for PDF parsing, separating Regex and Table extraction strategies.
• Strict Typing: * Replaced "Stringly Typed" dictionaries with concrete Classes and Dataclasses.
  • Introduced the Inventory(UserDict) class to encapsulate component logic.
  • Introduced the ProjectSlot dataclass for type-safe session state management.
• Separation of Concerns: * Decoupled business logic from the UI layer (app.py).
  • Extracted file I/O and URL fetching into loader.py.
  • Moved "Nerd Economics" and sourcing rules to constants.py.

Performance

• Parsing Optimization: * Implemented Regex Pre-compilation to eliminate redundant compilation cycles.
  • Refactored the parser to use Single-Pass Page Iteration, significantly reducing I/O overhead for large batches.
• Numeric Caching: Added caching for float value calculations (e.g., parsing 10k -> 10000.0), converting downstream lookups from $O(n)$ to $O(1)$.
• Deployment Size: Optimized requirements.txt generation by stripping development dependencies (e.g., pytest, mypy) using uv export --no-dev.

Bug Fixes

• Docker: Fixed exec format error crashes on Linux containers by ignoring local macOS/Linux .venv binaries via .dockerignore.
• Duplicate Projects: * Fixed issues where selecting the same project multiple times created duplicate PDF artifacts.
  • Quantities now sum correctly while documentation is deduplicated in the Master ZIP.
• Circular Imports: Resolved circular dependency chains within the new bom_lib package structure.

Build & Developer Experience

• Modern Build System: * Replaced pip with uv for Docker builds, improving resolution speed and reliability.
  • Migrated the build backend to Hatchling.
• Code Quality: * Enforced Strict Mypy checking (check_untyped_defs = true).
  • Enabled additional Ruff rules (T20, PT, C4) for cleaner code.
  • Standardized all docstrings to Google Style.
• Testing: * Added a "Golden Master" workflow for updating regression snapshots via pytest --snapshot-update.
  • Added .gitattributes to treat PDFs and locks as binary, preventing merge conflicts.

v2.2.1: Docker Stability, UV Migration & Tooling Modernization

🚀 Summary

This patch release focuses on infrastructure stability and developer experience. It overhauls the Docker build process to use uv for deterministic builds, aligns the project on Python 3.13 to prevent upstream breakages, and introduces modern linting standards with Ruff.

🏗 Build & Infrastructure

• Docker Migration to uv: Replaced pip with uv sync in the Dockerfile. This ensures the container environment exactly matches uv.lock, resolving hash mismatch errors caused by stale requirements.txt files.
• Context Isolation: Updated .dockerignore to exclude the local .venv, fixing cross-platform binary compatibility errors ("exec format error") when running the container.
• Python 3.13 Alignment: Downgraded the target Python version from 3.14-dev to 3.13-stable in both GitHub Actions and Docker to ensure reliability.
• Release Automation: Fixed a misconfiguration in pyproject.toml that prevented bump-my-version from correctly updating the package name in uv.lock.

🛠 Code Quality & Tooling

• Ruff Adoption: Replaced legacy linters with Ruff. Added comprehensive configuration to pyproject.toml and applied auto-fixes across the codebase.
• Linting Refactors: Manually refactored complex logic in app.py and src/pdf_generator.py (e.g., simplifying nested conditionals) to satisfy stricter code style rules.
• Pre-commit Fixes: Updated the mypy hook to use uv run mypy. This ensures type checking uses the project's actual dependencies rather than an isolated, incomplete environment.

v2.2.0: The Star Ground Rebrand

"Pedal BOM Manager" is now Star Ground.

This release marks a complete identity shift for the project. We have moved from a utility script for guitar pedals to a generalized "Single Source of Truth" logistics engine for analog electronics.

The name Star Ground references the circuit design topology where all signal paths converge to a single clean reference point. This tool serves the same function for your inventory data.

⚡ Key Changes

🎨 Identity & UI

• Rebrand: Application is now fully branded as Star Ground.
• New Home: The hosted application is now live at star-ground.streamlit.app.
• Philosophy: The documentation and UI now reflect the "Single Source of Truth" engineering metaphor.

📦 Artifacts

• Renamed Outputs: Downloaded files are now generic and professional:
  • pedal_shopping_list.csv → shopping_list.csv
  • Pedal_Build_Pack_Complete.zip → Star_Ground_Artifacts.zip
• PDFs: Field Manuals and Sticker Sheets now carry the "Star Ground" title.

🏗 Infrastructure

• Repository Migration: Project is now hosted at jacksonfergusondev/star-ground.
• Docker Registry: Images are now published to ghcr.io/jacksonfergusondev/star-ground.
• Lockfiles: Refreshed uv.lock and requirements.txt to reflect the package rename.

🐛 Fixes

• Feedback Mechanism: The feedback form now correctly routes to the "Star Ground Feedback" sheet.
• Documentation: Updated ROADMAP.md and CONTRIBUTING.md to remove legacy project references.

v2.1.2 - Docker Build Optimization

This patch release strictly targets the container build process to reduce image bloat and accelerate context transfer.

Changes

• Pruned Build Context: Updated .dockerignore to exclude high-mass development artifacts (examples/, tools/) and non-production metadata (CONTRIBUTING.md, uv.lock).
• Layer Hygiene: Prevents local development configurations (.vscode, .idea) from leaking into the production image layers.

v2.1.1 - Apple Silicon Support

🍎 Multi-Architecture Docker Support

This patch release fixes a compatibility issue for users on Apple Silicon (M1/M2/M3) and other ARM64 devices.

🐛 Fixes

• Docker Compatibility: The automated build pipeline now uses QEMU to produce multi-architecture images.
  • Fixed: no matching manifest for linux/arm64 error on macOS.
  • Supported Platforms: linux/amd64 (Intel/AMD) and linux/arm64 (Apple Silicon).

No changes to application code.

v2.1.0 - The "Modern Stack" Update (Python 3.13, UV, & Docker)

🚀 Major Infrastructure Upgrade

This release modernizes the entire build stack, moving from legacy pip management to the ultra-fast uv toolchain, upgrading the core runtime to Python 3.13, and introducing automated Docker container delivery.

✨ New Features

• Automated Docker Delivery: You no longer need to build the container from source! Pre-built, signed images are now automatically pushed to the GitHub Container Registry on every release.

  docker run -p 8501:8501 ghcr.io/jacksonfergusondev/pedal-bom-manager:latest

• Python 3.13 Support: The application core and CI/CD pipeline have been upgraded to target Python 3.13, leveraging the latest performance improvements and strict typing features.

⚡ Performance & Tooling

• Migrated to uv: Dependency resolution is now instant and deterministic.
  • Added uv.lock for reproducible builds across all environments.
  • Added pyproject.toml as the single source of truth for project configuration.
• Strict Streamlit Compatibility: The build process now auto-generates a hash-locked requirements.txt specifically for Streamlit Cloud stability.

🧹 Housekeeping

• Consolidated Config: Removed loose .ini files (mypy.ini, pytest.ini) and requirements-dev.txt in favor of centralized TOML configuration.
• CI/CD Hardening:
  • Removed the legacy build matrix in favor of strict "Production Parity" testing.
  • Increased test suite timeouts to handle PDF generation reliably in CI.
  • Added a Docker Build Status badge to the README.

v2.0.0: The Publishing House Update

Overview

Version 2.0.0 marks the completion of the "Publishing House" roadmap, transforming the application from a BOM parser into a full-stack Manufacturing Resource Planning (MRP) tool for DIY electronics. This release introduces the generation of physical assembly artifacts (Field Manuals, Sticker Sheets) and finalizes the transition to a lossless, provenance-tracking data structure.

Before (v1.0.0):

Basic BOM parsing and shopping list generation

After (v2.0.0):

Complete workflow with Field Manuals, Sticker Sheets, and inventory management

🚀 New Features

The "Publishing House" (Documentation Generation)

• Field Manuals: A new PDF generation engine creates assembly-focused checklists.
  • Z-Height Sorting: Components are ordered by physical height (Resistors → Sockets → Caps → Electros → Mechanicals) to optimize the soldering workflow.
  • Batch Deduplication: References are normalized (e.g., Qty: 1 per pedal) regardless of total batch size.
  • Visual Safety: Polarized components and critical warnings are highlighted in red.
• Sticker Sheets: Generates Avery 5160-compatible labels for part binning.
  • Smart Compression: Component references are intelligently condensed (e.g., R1, R2, R3, R4 → R1-R4) to maximize legibility on small labels.
• Master Zip Bundle: A "Download All" feature aggregates the Shopping List, Inventory CSV, Field Manuals, Sticker Sheets, and original Source PDFs into a single, timestamped archive.

Inventory & Logistics Engine

• Net Need Calculation: Users can now upload a "User Inventory" CSV. The system calculates max(0, BOM - Stock) to determine actual purchasing requirements.
• Risk-Weighted "Nerd Economics": Purchasing buffers are now applied dynamically based on component risk profiles.
  • Capacitors: Bifurcated logic applies high safety buffers (+5) to cheap MLCCs and minimal buffers (+1) to expensive Electrolytics.
  • High-Value Items: Enclosures and Switches now default to exact counts (Zero buffer).
• Circular Economy: Added a "Download Updated Inventory" button to export the new stock state (Old Stock + Buy Qty - BOM Qty) for the next build cycle.

Presets & Ingestion

• Preset Library: Added a curated library of standard builds (e.g., "Tube Screamer", "Klon Centaur") accessible via a hierarchical UI selector (Source → Category → Project).
• PedalPCB Integration: The parser now automatically detects "PCB" line items and generates deep links to pedalpcb.com in the Master BOM.
• URL Ingestion: Users can now import BOMs directly via URL, with robust error handling for network timeouts.

🛠 Core Logic & Parsing Improvements

Hybrid Parsing Strategy

The PDF parsing engine has been overhauled to use a Hybrid Strategy:

1. Table Extraction: Extracts high-confidence data from grid-based BOM tables.
2. "Hail Mary" Regex: Runs a secondary regex pass to capture off-board components (Pots/Switches) that often reside outside the main table structure.
3. Semantic Sanity Checks: Added guard clauses to prevent keyword collisions (e.g., preventing "Phase Locked Loop" from parsing as a generic "Loop" component).

Snapshot Regression Testing

Migrated from mock-based testing to a Golden Master snapshot framework. The parser now validates outputs against canonical JSON snapshots of real-world PDFs to strictly enforce data integrity across refactors.

🐛 Bug Fixes

• Infinite Hardware Duplication: Fixed a critical state mutation bug where hardware injection modified the live session state object, causing components to duplicate on every UI interaction.
• Streamlit Race Conditions: Resolved title flickering and widget state loss by refactoring input logic into callbacks and moving config execution to the top-level scope.
• Ghost Data: Fixed issues where metadata strings (e.g., "Revision 03.02.20") were being parsed as component values.
• Export Naming: Fixed a bug where mixing preset types caused the "Source Documents" folder to export incorrect filenames.

📚 Documentation

• Added ROADMAP.md as the single source of truth for architectural milestones.
• Added CONTRIBUTING.md and CODE_OF_CONDUCT.md to support open-source collaboration.

v1.6.0: The Supply Chain Update

This release transforms the application from a simple build calculator into a full-scale ERP (Enterprise Resource Planning) system for DIY guitar pedals. It introduces a Logistics Engine that understands your existing inventory, calculates purchasing deficits ("Net Need"), and supports complex batch manufacturing via Dynamic Slots.

It also fundamentally refactors the data model from a simple counter to a Lossless Architecture, tracking the provenance of every component to ensure that R1 from a Big Muff is never confused with R1 from a Tube Screamer.

📦 The Logistics Engine

• Inventory Subtraction: You can now upload a stock.csv (Category, Part, Qty). The engine calculates your Net Need (max(0, BOM - Stock)), allowing you to see exactly what you lack.
• Smart "Nerd Economics": Purchasing buffers (rounding up to 10, +5 safety margin) are now applied only to the Net Need (the deficit), preventing over-ordering when you already have partial stock.
• The Circular Economy: Added a "Download Updated Inventory" feature. This generates a new CSV for your next session (Old Stock + Buy Qty - BOM Qty), automating your inventory management loop.

🏭 Dynamic Production Lines

• Multi-Project Batching: The single "Pedal Count" input has been replaced by Dynamic Slots. You can now define multiple distinct projects in a single session (e.g., "2x Big Muff" + "1x Tube Screamer").
• Per-Slot Quantity: Logic now scales strictly by slot. The parser duplicates component references (['R1', 'R1']) based on slot quantity, ensuring the backend data matches physical reality.
• Global Hardware Injection: "Missing/Critical" items (Enclosures, Jacks) are now calculated based on the sum of all active slots.

🧬 Unified "Lossless" Core

• Provenance Tracking: The internal data structure has transitioned from a simple int to a PartData dictionary that tracks source metadata. This paves the way for future features like project-specific bin labels.
• Range Expansion Fix: The core ingestion kernel now universally expands ranges like R1-R4 into distinct entries (R1, R2, R3, R4) across all input methods (Text, CSV, and PDF).
• Unified Hardware Model: Hardware injection now mutates the inventory in-place rather than appending a sidecar list. This solves sorting artifacts (e.g., 3.3k LED resistors now sort correctly into the "Resistors" block) and enables granular filtering toggles for "Hardware Kit" and "Extras".

✨ Performance & Polish

• Google Sheets Caching: Implemented a 1-hour TTL cache for the Google Sheets API client, significantly reducing latency when submitting feedback.
• Filtering: Added an "Advanced Options" panel to toggle the visibility of the Hardware Kit and Sockets.

---

🔮 What's Next: Phase 2b & v2.0.0

This release completes Phase 2a ("Logistics") of the roadmap. The next milestone will be v2.0.0, which will arrive after the completion of Phase 2b: The Publishing House.

Phase 2b will focus on generating physical assets to aid the build process, leveraging the new "Lossless" data structure:

• Sticker Generator: A PDF engine (using fpdf2) that generates Avery 5160 labels for parts bins, grouping components by value and listing their reference designators.
• Field Manual: A printable "Build Guide" PDF that sorts the BOM by Z-Height (Resistors first, Electrolytics last) and highlights polarized components for safer soldering.

v1.5.0: The Silicon Sommelier Update

This release upgrades the application's brain, transforming it from a simple parts organizer into a domain expert on analog circuit topology.

It introduces a Mojo Upgrade Engine and a Texture Generator, allowing the tool to recommend high-fidelity or vintage-correct substitutions for standard components based on their physical properties (slew rate, bandwidth, and forward voltage).

🧠 Expert System Upgrades

• The "Mojo" Engine (ICs): The tool now understands the sonic difference between op-amps.

  • Contextual Recs: Instead of generic lists, it suggests alternatives based on engineering traits: OPA2134 for "Studio Clean" (high slew rate), NJM4558 for "Vintage Correct" (BJT bandwidth limiting), and OP07 for modern RAT stability.
  • Tech-Aware: Notes now explain why a sub works (e.g., "Required for 0.3V/µs slew-induced distortion").

• Texture Generators (Diodes): The diode engine now targets clipping characteristics.

  • Clipping Profiles: Recommends 1N4001 for "Tube-like" smoothing (slow reverse recovery), IR LED for "Goldilocks" drive (1.2V drop), or BAT41 for stable Germanium emulation.

⚡ Domain Logic Refinements

• Class 1 Ceramics: The capacitor logic now specifically recommends Class 1 Ceramic (C0G / NP0) for pF-range caps to prevent microphonics in high-gain stages, replacing the generic MLCC label.
• Fuzz Logic: The parser now detects "Fuzz" PCB names and automatically suggests Germanium Transistors (with a positive ground warning), ensuring builders do not miss these critical, hard-to-source components.
• Obsolete Mapping: Requests for JRC4558 are now strictly mapped to NJM4558 to ensure valid search results at modern vendors.

🐛 Bug Fixes

• Search Mapping: Fixed an issue where vintage part names would generate dead search links.
• Recommendation Engine: Fixed a Pylance dead-code issue where the expert system would crash on legacy 2-tuple data structures.

v1.4.0: The Document Scanner Update

This release eliminates the manual transcription step for PedalPCB builds. It introduces a PDF Ingestion Engine, allowing you to drag and drop official build documentation directly into the tool alongside your standard CSVs.

It integrates pdfplumber to perform visual table extraction, ensuring that complex, multi-line layouts are parsed as accurately as structured data.

📄 PDF Ingestion Support

• PedalPCB Native: The tool now explicitly supports PedalPCB build documents. It visually scans pages for "Parts List" tables, identifying them via header validation (LOCATION, VALUE) while ignoring non-BOM data like drill templates.
• Visual Layout Engine: Unlike standard text scrapers, the new engine understands grid geometry. It correctly reassembles components that span multiple lines (e.g., Resistor on line 1, 1/4W on line 2) into a single, clean entry.

🔀 Unified Workflow

• Mixed-Mode Uploads: The "Upload CSV" tab has been upgraded to "Upload Files". You can now batch upload .csv exports from KiCad and .pdf docs from PedalPCB in a single action. The app intelligently routes each file to the correct parser based on extension.

🛠️ Technical Improvements

• Heuristic Detection: The parser uses a heuristic scan to identify BOM tables even if they appear deep in the document (e.g., Page 4).
• Resilience: Added robust error handling for "dirty" PDF data, cleaning up extra whitespace and irregular column widths before processing.
• Test Coverage: Added a new suite of mocked unit tests (unittest.mock) to verify PDF extraction logic without requiring physical files in the CI pipeline.