How codelion/adaptive-classifier works
Project type and purpose
• This is a Python library (adaptive-classifier) designed to provide a flexible, continuously-learning text classification system built on top of HuggingFace transformers.
• It exposes a simple API (AdaptiveClassifier) that lets users add examples, make predictions, persist state, push to/pull from the HF Hub, and supports specialized modes (hallucination detection, LLM routing, config optimization).
File structure
• Top-level:
• src/adaptive_classifier: core library code
– classifier.py: main API surface
– models.py: model‐loading & embedding logic
– memory.py: prototype memory management
– ewc.py: elastic weight consolidation (avoiding catastrophic forgetting)
• scripts/: standalone tools & evaluations (router, hallucination detector, etc.)
• examples/: user-facing example scripts
• docs/: API.md and supplementary docs
• tests/: unit tests for classifier and memory
• config files: pyproject.toml, setup.py, requirements.txt, GitHub Actions workflow
README for additional insights
• The library fuses three core components:
a) Transformer Embeddings (HuggingFace)
b) Prototype Memory (faiss or in-memory prototypes)
c) Adaptive Neural Layer (continual learning / EWC)
• There are multiple “personalities” of the classifier (hallucination detector, router, config optimizer) driven by the same underlying architecture.
a. Main Components
1) Client / User Code (examples, API consumers)
2) AdaptiveClassifier API (classifier.py)
3) Model Loader & Embedding Module (models.py + transformers)
4) Prototype Memory Store (memory.py + faiss-cpu/gpu)
5) Adaptive Neural Layer (in-process training, ewc.py)
6) Persistence Layer (save/load via safetensors, HF Hub integration)
7) Scripts & Evaluation Tools (scripts/…)
b. Relationships & Interactions
• User code calls AdaptiveClassifier methods (add_examples, predict, save, load).
• AdaptiveClassifier orchestrates:
• retrieving embeddings from the transformer model
• querying/inserting prototypes in memory
• running adaptive training steps via the neural layer (EWC to prevent forgetting)
• serializing/deserializing state to disk or HF Hub
• Scripts import the same AdaptiveClassifier and run specialized evaluation pipelines (router eval, hallucination detector eval).
• CI pipeline (GitHub Actions) runs tests and publishes package.
c. Architectural Patterns & Principles
• Modular separation: embedding, memory, adaptation, persistence
• Dependency inversion: core library depends on abstracted model & memory back-ends
• Continuous learning loop: data flows from add_examples → memory update → neural adaptation → updated classifier
• Extensibility: same core pipeline powers multiple “flavors” (classifier, router, detector)
d. Key Technologies, Frameworks & Libraries
• Python ≥3.8
• PyTorch ≥2.0 & HuggingFace transformers
• safetensors (fast, secure weight storage)
• faiss-cpu/gpu for efficient prototype retrieval
• GitHub Actions for CI/CD
• Optional HF Hub for model distribution
Final Advice
• You capture both inference (predict) and training (add_examples + EWC) flows.
• Don’t forget the persistence layer (disk + HF Hub) and the role of GitHub Actions for testing/deployment.
• Keep it extensible: illustrate how new “personalities” (hallucination detector, router) reuse the same core pipeline.