Inside LibraryPulse
A source-backed overview of the Python platform and its public portfolio companion.
The print button opens your browser’s print dialog; choose Save as PDF. These are newly authored public project notes, not employer or client documents.
1. Project overview
LibraryPulse is the portfolio display name for Smart Library ML Platform. Its intended purpose is to connect library borrowing data with patron analytics and book discovery. This review is based on source revision 489da5d; source inspection is not a deployment or performance certification.
The public companion presents circulation summaries from browser-generated fictional records. The Python repository separately contains ingestion modules, feature engineering, recommendation components, API endpoints, orchestration code, and a Streamlit application.
Intended users: librarians investigating borrowing trends, collection teams exploring demand, and technical reviewers inspecting an end-to-end ML design. Actual library adoption requires approved data, privacy review, operational validation, and deployment hardening.
2. Architecture & source evidence
| Layer | Source | Observed behavior |
|---|---|---|
| Ingestion | lms_connector.py | Loads CSV or generates synthetic borrowing records. The implemented loader does not connect directly to a live LMS database. |
| Recommendation fusion | hybrid_engine.py | Fits ALS, SVD, TF-IDF, and optional BERT components; combines scores and applies rules. Default weights are 0.35, 0.25, 0.20, and 0.20 respectively. |
| API | api/main.py | Fits the engine during startup. Defines recommendation, similar-book, explanation, health, and model-information endpoints. |
| Original UI | dashboard/app.py | Streamlit pages for overview, patrons, books, recommendations, model health, and API testing. Loads local data or synthetic fallbacks. |
| Monitoring | drift_detector.py | Contains drift calculations, including a simulated prediction-score path. Its output must not be presented as observed production model health. |
| Public companion | demo.js | Static HTML/CSS/JavaScript. Calculates summaries locally with no Python API, credentials, or private records. |
Python data flow: borrowing data → features and model fitting → hybrid recommendations → FastAPI / Streamlit. The portfolio companion is independent of this runtime; GitHub Pages serves its static files only.
3. Demo data dictionary
The companion uses a seeded JavaScript generator: seed 42, 1,200 transactions, 120 possible fictional borrowers, 12 fictional titles, six genres, and six months in 2024. It is a separate fixture inspired by the repository’s borrowing schema, not an export of the Python generator. Records remain unchanged on refresh.
| Field | Meaning |
|---|---|
transaction_id | Unique synthetic checkout identifier. |
patron_id | Fictional borrower identifier with a DEMO prefix. No identity mapping exists. |
book_id | Fictional title identifier, not a physical-copy inventory ID. |
book_title | Invented title for illustration. |
genre | One of six categories assigned consistently per title. |
checkout_date | ISO date in January–June 2024. Days are limited to 1–28 for generation simplicity. |
loan_duration_days | Generated integer from 7 to 28, not a measured real loan duration. |
Metric definitions: checkouts = matching row count; distinct borrowers = unique patron IDs in those rows; titles borrowed = unique book IDs in those rows; mean loan days = arithmetic mean of matching durations. The title ranking counts checkouts per book and resolves ties alphabetically.
No branch inventory, hold queues, age, names, addresses, email, employer data, or lending-policy information is included. Do not infer population behavior, seasonal effects, or model quality from this fixture.
4. Evaluation & limitations
No measured ML improvement is claimed. The repository README leaves Precision@10, Recall@10, NDCG@10, and training times as TBD. The public companion shows calculated synthetic-data summaries, not model benchmarks.
- The hybrid engine includes four components, but an ensemble is not automatically better than a simple baseline.
- Some monitoring code generates simulated drift or recommendation samples. Replace these with persisted reference distributions and actual inference logs before operational use.
- The original Streamlit dashboard accepts an API URL. A public deployment should use a server-configured, approved endpoint rather than allowing arbitrary server-side requests.
- The API currently fits models during startup. A hardened deployment should load versioned artifacts and independently validate startup, readiness, access controls, and resource limits.
- Forecasting, acquisition optimization, and branch transfers are proposed extensions, not features of this portfolio demo.
Recommended evaluation protocol
- Use chronological train/validation/test windows and keep future borrowing events out of training features.
- Compare a popularity baseline with ALS, TF-IDF, and the hybrid model using the same candidate set and top-K definition.
- Report Precision@10, Recall@10, NDCG@10, catalog coverage, and separate cold-start performance, along with split dates and sample counts.
- Measure API latency under a documented workload. Treat any latency target in source comments as a target until measured.
- Run privacy and access-control checks before a pilot. Use opt-in personalization and librarian oversight for operational decisions.
5. Dashboard user guide
- Open the analytics demo. No login is required.
- Select a month or genre. All four metrics, both charts, and the title table update together.
- Use Reset filters to return to the complete dataset.
- Download filtered CSV to inspect the exact synthetic records behind the visible summaries.
- Use the source links to inspect the Python implementation. This demo does not invoke its recommendation API.
All filters and actions support keyboard use. Chart values also appear as text. The documents can be read without JavaScript, downloaded as Markdown, or printed using your browser.