Metadata-Version: 2.5
Name: langchain-alphai
Version: 0.1.0
Summary: LangChain tools and retriever for AlphaAI: AI-scored financial news and SEC Form 4 insider events.
Project-URL: Homepage, https://alphai.io
Project-URL: Documentation, https://alphai.io/developers
Project-URL: Repository, https://github.com/makeev/langchain-alphai
Project-URL: API Reference, https://api.alphai.io/api/schema/
Author-email: AlphaAI <support@alphai.io>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,alphai,financial-news,insider,langchain,llm,rag,sec,stocks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: alphai-sdk<1,>=0.4.2
Requires-Dist: langchain-core<2,>=1.0.0
Provides-Extra: dev
Requires-Dist: langchain-tests==1.1.9; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=9; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# langchain-alphai

LangChain tools and a retriever for [AlphaAI](https://alphai.io) — AI-scored,
ticker-linked financial news and SEC Form 4 insider events, built for AI agents
and trading bots.

Every article on the AlphaAI feed is enriched before you see it: per-ticker
impact analysis, one of 14 categories, and a 1-10 market-relevance score. The
components here fetch and filter that feed — no scraping, no scoring of your
own.

- `AlphaAINewsSearch` — the scored news feed with ticker / category / relevance filters
- `AlphaAIInsiderNews` — SEC Form 4 insider events with a structured who-sold-what block
- `AlphaAITickerSentiment` — 7-day bullish/neutral/bearish rollup for one ticker
- `AlphaAIInsiderSummary` — 30-day insider buy/sell rollup for one ticker
- `AlphaAINewsRetriever` — the feed as LangChain `Document`s for RAG pipelines

## Install

```bash
pip install langchain-alphai
```

Requires Python 3.10+.

## Authentication

Create an API key at [alphai.io/developers](https://alphai.io/developers) — the
free tier works without a card. Export it as `ALPHAI_API_KEY`, or pass
`api_key=...` to any component.

```bash
export ALPHAI_API_KEY="ak_live_..."
```

## Use the tools in an agent

```python
from langchain.agents import create_agent

from langchain_alphai import (
    AlphaAIInsiderNews,
    AlphaAIInsiderSummary,
    AlphaAINewsSearch,
    AlphaAITickerSentiment,
)

agent = create_agent(
    model="claude-sonnet-4-5",
    tools=[
        AlphaAINewsSearch(),
        AlphaAIInsiderNews(),
        AlphaAITickerSentiment(),
        AlphaAIInsiderSummary(),
    ],
)

agent.invoke({"messages": [("user", "Are NVDA insiders selling, and does the news explain why?")]})
```

Each tool also works standalone:

```python
from langchain_alphai import AlphaAINewsSearch

tool = AlphaAINewsSearch(min_relevance=7)  # instance defaults, overridable per call
tool.invoke({"symbol": "NVDA", "max_results": 5})
```

```python
{
    "results": [
        {
            "uid": "788e477c66f3849b",
            "url": "https://...",
            "title": "Nvidia beats on data-center revenue",
            "summary": "Q2 revenue came in above consensus...",
            "source": "Example Wire",
            "source_domain": "example.com",
            "published_at": "2026-08-14T12:30:00+00:00",
            "tickers": ["NVDA"],
            "category": "earnings",
            "relevance_score": 8,
        }
    ]
}
```

Insider events add a structured `insider` block — side, shares, average price,
total dollar value, who traded, and whether the sale was a pre-planned 10b5-1:

```python
from langchain_alphai import AlphaAIInsiderNews

AlphaAIInsiderNews().invoke({"symbol": "NVDA", "min_relevance": 7})
```

On the insider feed the relevance score is deterministic from the event's
summed dollar value, so `min_relevance` works as an "only large trades" dial.

## Use the retriever for RAG

The query is a ticker symbol (crypto uses `BTC-USD`, foreign listings the Yahoo
suffix, e.g. `VOD.L`); an empty query returns the market-wide feed.

```python
from langchain_alphai import AlphaAINewsRetriever

retriever = AlphaAINewsRetriever(min_relevance=7, k=5)
docs = retriever.invoke("NVDA")

docs[0].page_content  # title + summary
docs[0].metadata  # tickers, category, relevance_score, url, source, ...
```

## Filters

| Parameter | Where | Meaning |
|---|---|---|
| `symbol` | news + insider tools | One ticker; share-class siblings included on the insider feed |
| `category` | news tool, retriever | One of 14: `earnings`, `mergers_acquisitions`, `regulation`, `macro_economy`, `sector_analysis`, `market_movers`, `technology`, `commodities`, `crypto`, `ipo`, `geopolitics`, `insider`, `corporate_actions`, `other` |
| `min_relevance` | news + insider tools, retriever | 1-10 floor; 7+ keeps only high-signal articles |
| `collapse_stories` | news tool, retriever (constructor) | Collapse syndicated same-story coverage into one item |
| `max_results` / `k` | all | Cap on returned items |
| `include_analysis` | news tool (constructor) | Add per-ticker AI sentiment + impact summary to each result |

## Async

Every tool implements `ainvoke`, and the retriever `_aget_relevant_documents`,
over the SDK's native async client:

```python
await AlphaAINewsSearch().ainvoke({"symbol": "NVDA"})
```

## Rate limits

Limits are per AlphaAI account, two-layer (per-minute burst + per-day volume):
Free 20/min · 100/day, Basic 60/min · 10,000/day, Pro 150/min · 100,000/day.
News-archive depth is tiered too (30/90 days / full archive). The underlying
[alphai-sdk](https://pypi.org/project/alphai-sdk/) retries 429s with backoff
automatically.

## Links

- Developer guide: <https://alphai.io/developers>
- API reference: <https://api.alphai.io/api/schema/>
- MCP server (same feed, for MCP-speaking agents): <https://alphai.io/mcp>

AlphaAI output is AI-generated financial information for research, not
investment advice — see [alphai.io/terms](https://alphai.io/terms).
