Metadata-Version: 2.5
Name: langchain-hackernews
Version: 0.1.0
Summary: LangChain retriever integration for Hacker News — search stories, fetch the front page, and retrieve full comment threads without API keys.
Project-URL: Homepage, https://github.com/urraf/langchain-hackernews
Project-URL: Repository, https://github.com/urraf/langchain-hackernews
Project-URL: Documentation, https://github.com/urraf/langchain-hackernews#readme
Project-URL: Bug Tracker, https://github.com/urraf/langchain-hackernews/issues
Author: Farhan
License-Expression: MIT
License-File: LICENSE
Keywords: ai,hackernews,hn,langchain,llm,rag,retriever
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🚀 langchain-hackernews

[![PyPI version](https://badge.fury.io/py/langchain-hackernews.svg)](https://badge.fury.io/py/langchain-hackernews)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**LangChain retrievers for Hacker News** — search stories, fetch the front page, and retrieve full comment threads as LangChain `Document` objects. **No API keys required.**

Perfect for building RAG applications that can search tech news, analyze discussions, and stay up to date with Hacker News.

## ✨ Features

| Retriever | What it does | API Key Required? |
|---|---|---|
| `HackerNewsSearchRetriever` | Search HN stories by keyword | ❌ No! |
| `HackerNewsFrontPageRetriever` | Fetch current top/best/new stories | ❌ No! |
| `HackerNewsCommentsRetriever` | Fetch a full discussion thread | ❌ No! |

## 📦 Installation

```bash
pip install langchain-hackernews
```

## 🚀 Quick Start

### Search Hacker News Stories

```python
from langchain_hackernews import HackerNewsSearchRetriever

retriever = HackerNewsSearchRetriever(
    max_results=5,
    sort_by="relevance",  # or "date" for newest first
)

docs = retriever.invoke("langchain python")

for doc in docs:
    print(f"📰 {doc.page_content}")
    print(f"   👍 {doc.metadata['points']} points | 💬 {doc.metadata['num_comments']} comments")
```

### Fetch the Front Page

```python
from langchain_hackernews import HackerNewsFrontPageRetriever

retriever = HackerNewsFrontPageRetriever(
    page_type="top",  # "top", "best", "new", "ask", "show", "job"
    max_results=10,
)

# The query is ignored for the front page
docs = retriever.invoke("fetch")

for doc in docs:
    print(f"#{doc.metadata['rank']} — {doc.page_content}")
```

### Fetch a Comment Thread

```python
from langchain_hackernews import HackerNewsCommentsRetriever

retriever = HackerNewsCommentsRetriever(max_results=50)

# Pass the story URL or ID
docs = retriever.invoke("https://news.ycombinator.com/item?id=40243419")

for doc in docs:
    indent = "  " * doc.metadata["depth"]
    print(f"{indent}💬 {doc.metadata['author']}: {doc.page_content[:80]}...")
```

## 📄 License

MIT — see [LICENSE](LICENSE) for details.
