Skip to content

feat: add a minimal alpha detector API - #9

Draft
Albertsr wants to merge 1 commit into
masterfrom
codex/minimal-stable-api
Draft

feat: add a minimal alpha detector API#9
Albertsr wants to merge 1 commit into
masterfrom
codex/minimal-stable-api

Conversation

@Albertsr

Copy link
Copy Markdown
Owner

Why

The repository contains valuable handwritten implementations, but it has not had a small, tested interface that readers can depend on without navigating the historical experiment scripts.

This PR extracts the narrowest useful API while keeping the original files and algorithmic choices visible.

What changed

  • Add the installable anomaly_detection package.
  • Expose only:
    • MahalanobisDetector
    • PCAReconstructionDetector
  • Give both detectors the same contract:
    • fit(X)
    • score_samples(X), with larger values meaning more anomalous
    • predict(X), with anomaly=1 and normal=0
  • Document contamination, threshold-count, tie, validation, and fitted-state behavior.
  • Use a pseudo-inverse for singular Mahalanobis covariance matrices.
  • Preserve the repository's handwritten cumulative PCA reconstruction-error aggregation while avoiding repeated PCA fits.
  • Add package metadata, API documentation, migration notes, and English/Chinese README entry points.
  • Keep RobustPCC and Kernel PCA outside the public API until their threshold semantics and compatibility risks are characterized separately.

Preservation and impact

This is an additive extraction, not a rewrite:

  • historical scripts are not deleted, renamed, or redirected;
  • characterization tests compare the new calculations with the handwritten implementations;
  • frozen numeric fixtures protect the score definitions;
  • the API is explicitly alpha-stage and does not claim production readiness or full semantic-versioning stability.

Checks

  • 15/15 public API, edge-case, determinism, and legacy-equivalence tests passed.
  • Source distribution and wheel built successfully.
  • Independent wheel installation and import/fit/score/predict smoke test passed.
  • Strict UTF-8 and replacement-character checks passed.
  • Sensitive-pattern scan passed.
  • git diff --check passed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant