Naive Bayes Laravel Package

Technical Evaluation

Package: assisted-mindfulness/naive-bayes — a PHP naive Bayes classifier for Laravel, now at 2.0.2.

Architecture fit. This is a self-contained statistical classifier, not an ML platform. It fits where we need lightweight, explainable text/document classification inside the PHP process — spam and abuse triage, ticket routing, intent tagging, sentiment bucketing, lead scoring on tokenized fields. It does not fit as a replacement for a hosted inference service or anything requiring embeddings, deep models, or GPU throughput. The key architectural question is whether classification belongs in the request path (cheap, synchronous, no external dependency) or in a queue worker (preferred if corpora are large). Given the pure-PHP nature, it is an attractive fit for teams that want to avoid adding a Python/sidecar service to an otherwise homogeneous Laravel stack.

Dependency surface. Narrow and well-understood: the package's stated dependency is brick/math, an arbitrary-precision arithmetic library used to keep probability multiplication from underflowing on long token sequences. That is the right technical choice for naive Bayes — naive Bayes multiplies many small probabilities, and native PHP floats degrade quickly. It also means our arithmetic correctness is inherited from a widely used, actively maintained third-party library rather than hand-rolled.

Integration feasibility. Standard Laravel package mechanics: composer require, auto-discovery of the service provider, config publishing, and typical usage of train/predict calls against a model. There is no runtime service to provision, no credentials, no network egress, no schema migration implied by the package itself. Initial feasibility is high — a spike should be days, not weeks.

Technical risk.

• 2.0.x maturity. A major version bump implies API change from 1.x. We are two patches into that line, so the public surface is still settling. Anything we build should be isolated behind a thin internal interface (e.g. a Classifier contract) so a future 2.1 or 3.0 does not ripple through domain code.
• Dependency-math drift (the actual content of 2.0.2). 2.0.2 widens the brick/math constraint from ^0.18 to ^0.18 || ^0.20. This is not a code change to the classifier — it is a resolution-policy change. Consequence: two environments running identical package code can resolve different brick/math versions, and therefore different precision/rounding behavior, depending on lockfile age and PHP version. Classifier output on borderline cases could differ between staging and production. This is the single most important thing to pin down.
• PHP version floor. brick/math 0.20 may carry a higher PHP minimum than 0.18. If any of our apps sit on an older PHP minor, the widened constraint can silently push Composer toward a version that breaks the platform requirement. Must be verified against our support matrix, not assumed.
• Bus factor. Maintenance is effectively one human plus Dependabot. A single maintainer is a real continuity risk for a component in the classification path. Mitigations: fork-and-vendor option, or keep the surface small enough to reimplement.
• Algorithmic limits. Naive Bayes assumes conditional independence of features, which is false for natural language. Expect decent precision, mediocre calibration, and poor performance on small or heavily imbalanced corpora. It is a strong baseline, not a ceiling.

Key questions to resolve before commitment.

1. Does the released 2.0.x code differ functionally from 2.0.1, or is 2.0.2 constraint-only? (Diff suggests the latter — verify.)
2. What PHP floor does brick/math 0.20 impose, and does it match our matrix?
3. Where does the trained model live — filesystem, database, cache? Is that storage safe for concurrent train/predict?
4. How large does the model get for our expected vocabulary and class count? Any size cap?
5. Is there Laplace/additive smoothing, and is it configurable? Zero-frequency handling is make-or-break for sparse text.
6. Are there tests, and does the package publish a benchmark or accuracy expectation?
7. Licence terms and whether a maintainer-succession plan is needed.

Integration Approach

Stack fit. Excellent for a Laravel monolith. Composer-native, no service to operate, no container images, no secrets management, no added latency budget beyond CPU time. It composes naturally with queued jobs, console commands for retraining, and Artisan scheduling for periodic model refresh. It is a poor fit only if we need sub-millisecond classification at very high volume, streaming feature updates, or model explainability at the token level beyond what naive Bayes natively gives.

Migration path. There is nothing to migrate from if this is greenfield; the package can sit alongside existing rule-based or keyword classifiers so we can shadow-run and compare decisions before cutting over. If replacing an external service, run both in parallel on live traffic, log disagreements, and cut over only when the disagreement rate and the resulting business metric (false positive rate in moderation, misroute rate in support) are acceptable. That shadow period is the real migration work — the code change is trivial, the trust-building is not.

Compatibility.

• Composer pinning. Do not rely on ^0.18 || ^0.20 resolving consistently. Pin brick/math explicitly in each application's composer.json and commit the lockfile. Treat any bump of brick/math as a classifier-affecting change requiring the regression check below.
• Version drift between apps. If this package lands in more than one application, standardize the brick/math pin across them, otherwise identical models can score differently per service.
• Laravel version coverage. Confirm the package's Illuminate constraints against our current LTS and the next one we plan to adopt; unconstrained or narrow Illuminate ranges are a common cause of painful framework upgrades.
• PHP coverage. Validate against the whole matrix, not just the default CI image.

Sequencing.

1. Spike (1 sprint). Install in a scratch app, train on a representative corpus, measure accuracy against a hand-labelled holdout. Kill or continue here on evidence.
2. Constraint hardening. Pin brick/math, capture the resolved version, and record the PHP/Laravel floor that actually works.
3. Adapter layer. Wrap the package in an internal interface with our own DTOs for training examples, labels, and predictions. This is the insurance policy against 2.x churn and the exit ramp if the package is abandoned.
4. Golden-dataset regression harness. Fixed corpus plus fixed expected outputs, committed to CI. Run it on every dependency change. This is the control that makes brick/math drift visible rather than silent.
5. Persistence and retraining. Decide the model store deliberately — versioned artifact in object storage or a DB blob, with the training-set snapshot retained for reproducibility. Never train in place, and never overwrite a live model without a validated replacement.
6. Shadow deployment, then progressive rollout behind a flag with a kill switch to the prior classifier.
7. Operationalize. Retraining schedule, drift monitoring, accuracy dashboards.

Operational Impact

Maintenance. Low day-to-day maintenance, but not zero. Two ongoing costs: (a) dependency churn — Dependabot PRs like the ones in 2.0.2 arrive at the package's cadence and, through it, at ours, so we need a routine to evaluate them rather than auto-merging; (b) model lifecycle — accuracy decays as the world drifts (new spam patterns, new product names, new support topics), so retraining is a recurring operational task with an owner, a schedule, and a quality gate, not a one-off setup step.

Support. There is no commercial support and a single-maintainer profile. Internal support burden is modest because the domain is well-understood and the code footprint is small, but the responsible posture is: assume we may need to maintain a fork. Keeping our usage inside a thin adapter makes that fork survivable. Budget a modest amount of engineering familiarity rather than assuming any given developer can debug precision issues unaided.

Scaling. Two distinct cost curves, and they should be planned separately.

• Inference is cheap and horizontally scalable — it is a bag-of-tokens scoring pass, linear in document length and vocabulary hits. It scales with request volume like any other pure-CPU work, which means it scales with our web tier. Memory is the model, not the request.
• Training is the expensive side: one pass over the corpus, but the corpus grows and the vocabulary grows with it. Vocabulary growth is superlinear in memory if unpruned — enforce a minimum-document-frequency cutoff and a maximum feature count from day one, or the model artifact will quietly balloon until it no longer fits comfortably in a worker. Training should be a queued or scheduled job with a memory ceiling, never on the request path.
• Storage: the artifact is loaded per process; if we run many small workers, loading a large model repeatedly is wasted I/O. Cache it per-worker and consider keeping the model size bounded by design.

Failure modes.

• Silent precision drift from brick/math version differences — the signature risk of this particular release. Mitigated by the golden-dataset harness; without it, symptoms appear as unexplained shifts in classification rates weeks later.
• Dependency resolution failure on deploy if the widened constraint interacts badly with an app's PHP version — a build-time failure, cheap and visible, which is the good kind.
• Zero-frequency collapse on unseen tokens if smoothing is absent or misconfigured — classifier becomes confidently wrong on new vocabulary. Test with deliberately unfamiliar input.
• Class imbalance producing a model that predicts the majority class for everything and reports high headline accuracy. Track per-class precision/recall, not aggregate accuracy.
• Model file corruption or partial write during concurrent retrain while serving — requires atomic swap of a versioned artifact.
• Training/serving skew if preprocessing (tokenization, stopwords, casing) differs between the training script and the request path — the most common real-world cause of "it worked offline" failures. Share one preprocessing path.
• Abandonment. No patch for a framework compatibility break. Exit cost is low given the adapter; the trigger to act is an unresolvable dependency in the next Laravel upgrade.

Ramp-up. Fast for competent Laravel developers — an experienced engineer is productive in a day on the API, and the concepts (tokenization, prior, likelihood, smoothing) are standard. The non-obvious part is evaluation discipline: choosing a holdout set, avoiding leakage, reading confusion matrices, and knowing when naive Bayes is simply the wrong model. Plan for a short internal write-up on evaluation methodology alongside the integration work; that documentation will prevent more incidents than any code review of the wrapper.

Verdict on 2.0.2. No functional change, no API change, no deprecation — a dependency-constraint widening plus a routine bump. Adopt without ceremony if brick/math is pinned and the regression harness exists. The release is unremarkable in itself; its value to us is as a reminder that this package's dependency graph is a moving part we must control on our side.