search-articles

Query articles using category filters and BM25 keyword search

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 6, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a robust solution for high-precision article retrieval using the BM25 ranking algorithm and structured category filtering. It solves the problem of navigating large document repositories by allowing users to combine full-text keyword searches with specific metadata filters, delivering ranked results in multiple formats (JSON, CSV, Table) for both human readability and automated data processing.

Use Cases

  • Research & Discovery: Efficiently locate specific scientific or news articles within a large corpus by combining domain-specific category filters with technical keywords.
  • Knowledge Management: Enable users to browse internal document libraries with pagination and snippets, making it easier to find relevant information without manual sorting.
  • Data Pipeline Integration: Utilize the JSON and CSV output capabilities to pipe search results into other automation tools or LLM workflows for summarization and analysis.
  • Content Auditing: Use the category listing and filtering features to audit the distribution of topics across an article database.
namesearch-articles
descriptionQuery articles using category filters and BM25 keyword search
version3.0.0
providerfastpaip
runtimepython3
tags[search, articles, bm25, filtering, query]

Search Articles

Query articles using structured category filters and BM25 full-text keyword search.

Usage

# List available categories
python search.py --list-categories

# Browse all articles
python search.py --limit 10

# Filter by categories
python search.py --categories NEWS SCIENTIFIC

# Keyword search (BM25 full-text search)
python search.py --keywords "machine learning"

# Combined filters
python search.py --categories SCIENTIFIC --keywords "biology"

# JSON output for piping
python search.py --keywords "API" --format json | jq '.results[].id'

Parameters

Parameter Type Description
--list-categories flag List all available article categories
--categories list Filter by categories (NEWS, SCIENTIFIC, etc.)
--keywords string BM25 full-text search keywords
--limit int Maximum results (default: 10)
--offset int Pagination offset (default: 0)
--format choice Output: table, json, csv
--output path Output file for json/csv

Output Formats

Table (default)

                 Search Results (3 found)
┏━━━━┳━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ Category   ┃ Score ┃ Snippet                  ┃
┡━━━━╇━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 6  │ SCIENTIFIC │ 0.15  │ ...machine learning...   │
└────┴────────────┴───────┴──────────────────────────┘

JSON

{
  "results": [
    {
      "id": 6,
      "raw_article": "...",
      "category": "SCIENTIFIC",
      "keyword_score": 0.15,
      "snippet": "...machine learning..."
    }
  ],
  "metadata": {
    "total_results": 3,
    "query_time_ms": 42.5,
    "strategies_used": ["bm25_keyword_search", "category_filter"]
  }
}

CSV

id,raw_article,category,keyword_score,snippet
6,"...","SCIENTIFIC",0.15,"...machine learning..."

Examples

See references/examples.md for 30+ usage examples including:

  • Category filtering
  • Keyword search strategies
  • Date range queries
  • Pagination
  • Composing with jq, grep, and other tools
  • Batch processing workflows