docs: modernize README to follow Ruby open source best practices

- Add badges for gem version, CI status, and license
- Add table of contents for easier navigation
- Add Ruby compatibility matrix (3.1-3.4)
- Improve installation with Bundler instructions
- Use collapsible sections for GSL install and benchmarks
- Add syntax highlighting to all code blocks
- Add Development section with setup and test instructions
- Add Contributing guidelines
- Improve examples (spam filter, persistence, LSI search)
- Reorganize structure with Quick Start sections

Closes #76

Author: cardmagic

README.md

@@ -1,157 +1,258 @@
-## Welcome to Classifier
+# Classifier
 
-Classifier is a general module to allow Bayesian and other types of classifications.
+[![Gem Version](https://badge.fury.io/rb/classifier.svg)](https://badge.fury.io/rb/classifier)
+[![CI](https://github.com/cardmagic/classifier/actions/workflows/ruby.yml/badge.svg)](https://github.com/cardmagic/classifier/actions/workflows/ruby.yml)
+[![License: LGPL](https://img.shields.io/badge/License-LGPL_2.1-blue.svg)](https://opensource.org/licenses/LGPL-2.1)
 
-## Download
+A Ruby library for text classification using Bayesian and Latent Semantic Indexing (LSI) algorithms.
 
-* https://github.com/cardmagic/classifier
-* gem install classifier
-* git clone https://github.com/cardmagic/classifier.git
+## Table of Contents
 
-## Dependencies
+- [Installation](#installation)
+- [Bayesian Classifier](#bayesian-classifier)
+- [LSI (Latent Semantic Indexing)](#lsi-latent-semantic-indexing)
+- [Performance](#performance)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
-The `fast-stemmer` gem is required:
+## Installation
 
-    gem install fast-stemmer
+Add to your Gemfile:
+
+```ruby
+gem 'classifier'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install classifier
+```
 
 ### Optional: GSL for Faster LSI
 
-For faster LSI classification, install the GNU Scientific Library and its Ruby bindings.
+For significantly faster LSI operations, install the [GNU Scientific Library](https://www.gnu.org/software/gsl/).
+
+<details>
+<summary><strong>Ruby 3.4+</strong></summary>
+
+The released `gsl` gem doesn't support Ruby 3.4+. Install from source:
+
+```bash
+# Install GSL library
+brew install gsl        # macOS
+apt-get install libgsl-dev  # Ubuntu/Debian
+
+# Build and install the gem
+git clone https://github.com/cardmagic/rb-gsl.git
+cd rb-gsl
+git checkout fix/ruby-3.4-compatibility
+gem build gsl.gemspec
+gem install gsl-*.gem
+```
+</details>
+
+<details>
+<summary><strong>Ruby 3.3 and earlier</strong></summary>
+
+```bash
+# macOS
+brew install gsl
+gem install gsl
+
+# Ubuntu/Debian
+apt-get install libgsl-dev
+gem install gsl
+```
+</details>
+
+When GSL is installed, Classifier automatically uses it. To suppress the GSL notice:
+
+```bash
+SUPPRESS_GSL_WARNING=true ruby your_script.rb
+```
+
+### Compatibility
+
+| Ruby Version | Status |
+|--------------|--------|
+| 3.4          | Supported |
+| 3.3          | Supported |
+| 3.2          | Supported |
+| 3.1          | Supported |
+
+## Bayesian Classifier
+
+Fast, accurate classification with modest memory requirements. Ideal for spam filtering, sentiment analysis, and content categorization.
+
+### Quick Start
+
+```ruby
+require 'classifier'
+
+classifier = Classifier::Bayes.new('Spam', 'Ham')
+
+# Train the classifier
+classifier.train_spam "Buy cheap viagra now! Limited offer!"
+classifier.train_spam "You've won a million dollars! Claim now!"
+classifier.train_ham "Meeting scheduled for tomorrow at 10am"
+classifier.train_ham "Please review the attached document"
+
+# Classify new text
+classifier.classify "Congratulations! You've won a prize!"
+# => "Spam"
+```
+
+### Persistence with Madeleine
 
-#### Ruby 3.4+
+```ruby
+require 'classifier'
+require 'madeleine'
 
-The released `gsl` gem doesn't support Ruby 3.4+. Install from source with the compatibility fix:
+m = SnapshotMadeleine.new("classifier_data") {
+  Classifier::Bayes.new('Interesting', 'Uninteresting')
+}
 
-    # Install GSL library
-    brew install gsl        # macOS
-    apt-get install libgsl-dev  # Ubuntu/Debian
+m.system.train_interesting "fascinating article about science"
+m.system.train_uninteresting "boring repetitive content"
+m.take_snapshot
 
-    # Build and install the gem from the compatibility branch
-    git clone https://github.com/cardmagic/rb-gsl.git
-    cd rb-gsl
-    git checkout fix/ruby-3.4-compatibility
-    gem build gsl.gemspec
-    gem install gsl-*.gem
+# Later, restore and use:
+m.system.classify "new scientific discovery"
+# => "Interesting"
+```
 
-#### Ruby 3.3 and earlier
+### Learn More
 
-    # macOS
-    brew install gsl
-    gem install gsl
+- [Bayesian Filtering Explained](http://www.process.com/precisemail/bayesian_filtering.htm)
+- [Wikipedia: Bayesian Filtering](http://en.wikipedia.org/wiki/Bayesian_filtering)
+- [Paul Graham: A Plan for Spam](http://www.paulgraham.com/spam.html)
 
-    # Ubuntu/Debian
-    apt-get install libgsl-dev
-    gem install gsl
+## LSI (Latent Semantic Indexing)
 
-LSI works without GSL using a pure Ruby implementation. When GSL is installed, Classifier automatically uses it with no configuration needed.
+Semantic analysis using Singular Value Decomposition (SVD). More flexible than Bayesian classifiers, providing search, clustering, and classification based on meaning rather than just keywords.
 
-To suppress the GSL notice when not using it:
+### Quick Start
 
-    SUPPRESS_GSL_WARNING=true ruby your_script.rb
+```ruby
+require 'classifier'
 
-## Bayes
+lsi = Classifier::LSI.new
 
-A Bayesian classifier by Lucas Carlson. Bayesian Classifiers are accurate, fast, and have modest memory requirements.
+# Add documents with categories
+lsi.add_item "Dogs are loyal pets that love to play fetch", :pets
+lsi.add_item "Cats are independent and love to nap", :pets
+lsi.add_item "Ruby is a dynamic programming language", :programming
+lsi.add_item "Python is great for data science", :programming
 
-### Usage
+# Classify new text
+lsi.classify "My puppy loves to run around"
+# => :pets
 
-    require 'classifier'
-    b = Classifier::Bayes.new 'Interesting', 'Uninteresting'
-    b.train_interesting "here are some good words. I hope you love them"
-    b.train_uninteresting "here are some bad words, I hate you"
-    b.classify "I hate bad words and you" # returns 'Uninteresting'
+# Get classification with confidence score
+lsi.classify_with_confidence "Learning to code in Ruby"
+# => [:programming, 0.89]
+```
 
-    require 'madeleine'
-    m = SnapshotMadeleine.new("bayes_data") {
-        Classifier::Bayes.new 'Interesting', 'Uninteresting'
-    }
-    m.system.train_interesting "here are some good words. I hope you love them"
-    m.system.train_uninteresting "here are some bad words, I hate you"
-    m.take_snapshot
-    m.system.classify "I love you" # returns 'Interesting'
+### Search and Discovery
 
-Using Madeleine, your application can persist the learned data over time.
+```ruby
+# Find similar documents
+lsi.find_related "Dogs are great companions", 2
+# => ["Dogs are loyal pets that love to play fetch", "Cats are independent..."]
 
-### Bayesian Classification
+# Search by keyword
+lsi.search "programming", 3
+# => ["Ruby is a dynamic programming language", "Python is great for..."]
+```
 
-* http://www.process.com/precisemail/bayesian_filtering.htm
-* http://en.wikipedia.org/wiki/Bayesian_filtering
-* http://www.paulgraham.com/spam.html
+### Learn More
 
-## LSI
+- [Wikipedia: Latent Semantic Analysis](http://en.wikipedia.org/wiki/Latent_semantic_analysis)
+- [C2 Wiki: Latent Semantic Indexing](http://www.c2.com/cgi/wiki?LatentSemanticIndexing)
 
-A Latent Semantic Indexer by David Fayram. Latent Semantic Indexing engines
-are not as fast or as small as Bayesian classifiers, but are more flexible, providing
-fast search and clustering detection as well as semantic analysis of the text that
-theoretically simulates human learning.
+## Performance
 
-### Usage
+### GSL vs Native Ruby
 
-    require 'classifier'
-    lsi = Classifier::LSI.new
-    strings = [ ["This text deals with dogs. Dogs.", :dog],
-              ["This text involves dogs too. Dogs! ", :dog],
-              ["This text revolves around cats. Cats.", :cat],
-              ["This text also involves cats. Cats!", :cat],
-              ["This text involves birds. Birds.",:bird ]]
-    strings.each {|x| lsi.add_item x.first, x.last}
+GSL provides dramatic speedups for LSI operations, especially `build_index` (SVD computation):
 
-    lsi.search("dog", 3)
-    # returns => ["This text deals with dogs. Dogs.", "This text involves dogs too. Dogs! ",
-    #             "This text also involves cats. Cats!"]
+| Documents | build_index | Overall |
+|-----------|-------------|---------|
+| 5         | 4x faster   | 2.5x    |
+| 10        | 24x faster  | 5.5x    |
+| 15        | 116x faster | 17x     |
 
-    lsi.find_related(strings[2], 2)
-    # returns => ["This text revolves around cats. Cats.", "This text also involves cats. Cats!"]
+<details>
+<summary>Detailed benchmark (15 documents)</summary>
 
-    lsi.classify "This text is also about dogs!"
-    # returns => :dog
+```
+Operation              Native          GSL      Speedup
+----------------------------------------------------------
+build_index            0.1412       0.0012       116.2x
+classify               0.0142       0.0049         2.9x
+search                 0.0102       0.0026         3.9x
+find_related           0.0069       0.0016         4.2x
+----------------------------------------------------------
+TOTAL                  0.1725       0.0104        16.6x
+```
+</details>
 
-    lsi.classify_with_confidence "This text is also about dogs!"
-    # returns => [:dog, 1.0]
+### Running Benchmarks
 
-Please see the Classifier::LSI documentation for more information. It is possible to index, search and classify
-with more than just simple strings.
+```bash
+rake benchmark              # Run with current configuration
+rake benchmark:compare      # Compare GSL vs native Ruby
+```
 
-### Latent Semantic Indexing
+## Development
 
-* http://www.c2.com/cgi/wiki?LatentSemanticIndexing
-* http://www.chadfowler.com/index.cgi/Computing/LatentSemanticIndexing.rdoc
-* http://en.wikipedia.org/wiki/Latent_semantic_analysis
+### Setup
 
-## Benchmarks
+```bash
+git clone https://github.com/cardmagic/classifier.git
+cd classifier
+bundle install
+```
 
-Run benchmarks to compare LSI performance:
+### Running Tests
 
-    rake benchmark              # Run with current configuration
-    rake benchmark:compare      # Compare GSL vs native Ruby
+```bash
+rake test                        # Run all tests
+ruby -Ilib test/bayes/bayesian_test.rb  # Run specific test file
 
-### GSL vs Native Ruby Comparison
+# Test without GSL (pure Ruby)
+NATIVE_VECTOR=true rake test
+```
 
-| Documents | build_index | Overall Speedup |
-|-----------|-------------|-----------------|
-| 5         | 4x          | 2.5x            |
-| 10        | 24x         | 5.5x            |
-| 15        | 116x        | 17x             |
+### Console
 
-Sample comparison (15 documents):
+```bash
+rake console
+```
 
-    Operation              Native          GSL      Speedup
-    ----------------------------------------------------------
-    build_index            0.1412       0.0012       116.2x
-    classify               0.0142       0.0049         2.9x
-    search                 0.0102       0.0026         3.9x
-    find_related           0.0069       0.0016         4.2x
-    ----------------------------------------------------------
-    TOTAL                  0.1725       0.0104        16.6x
+## Contributing
 
-The `build_index` operation (SVD computation) dominates total time and benefits most from GSL. Install GSL for production use with larger document sets.
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -am 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
 ## Authors
 
-* Lucas Carlson  (lucas@rufy.com)
-* David Fayram II (dfayram@gmail.com)
-* Cameron McBride (cameron.mcbride@gmail.com)
-* Ivan Acosta-Rubio (ivan@softwarecriollo.com)
+- **Lucas Carlson** - *Original author* - lucas@rufy.com
+- **David Fayram II** - *LSI implementation* - dfayram@gmail.com
+- **Cameron McBride** - cameron.mcbride@gmail.com
+- **Ivan Acosta-Rubio** - ivan@softwarecriollo.com
 
-This library is released under the terms of the GNU LGPL. See LICENSE for more details.
+## License
 
+This library is released under the [GNU Lesser General Public License (LGPL) 2.1](LICENSE).