alphai-haystack 0.1.0__py3-none-any.whl

alphai_haystack/__init__.py

@@ -0,0 +1,12 @@
+"""Haystack components for the AlphaAI financial-news API (alphai.io)."""
+
+from ._version import VERSION
+from .fetchers import AlphaAIInsiderNewsFetcher, AlphaAINewsFetcher
+
+__version__ = VERSION
+
+__all__ = [
+    "AlphaAIInsiderNewsFetcher",
+    "AlphaAINewsFetcher",
+    "__version__",
+]

alphai_haystack/_version.py

@@ -0,0 +1 @@
+VERSION = "0.1.0"

alphai_haystack/fetchers.py

@@ -0,0 +1,252 @@
+"""Haystack components that turn AlphaAI's scored news feed into Documents.
+
+Every article on the feed already carries an AI enrichment layer (per-ticker
+impact analysis, a category, a 1-10 relevance score), so the components here
+do no scoring of their own — they fetch, filter, and map articles into
+:class:`haystack.Document` objects with the enrichment exposed as metadata.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any
+
+from alphai import Client
+from alphai.models import RichNewsArticle
+from haystack import Document, component, default_from_dict, default_to_dict
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+DEFAULT_TOP_K = 10
+
+
+def _plain(value: object) -> object:
+    """Convert SDK field values into JSON-friendly meta values."""
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    return value
+
+
+def _category_str(category: object) -> str:
+    return str(getattr(category, "value", category))
+
+
+def _to_document(article: RichNewsArticle) -> Document:
+    original = article.original
+    enrichment = article.enrichment
+    parts = [original.title.strip(), original.summary.strip()]
+    content = "\n\n".join(part for part in parts if part)
+    meta: dict[str, Any] = {
+        "uid": original.uid,
+        "url": original.url,
+        "title": original.title,
+        "source": original.source,
+        "source_domain": original.source_domain,
+        "published_at": _plain(original.time_published),
+        "tickers": list(enrichment.tickers),
+        "category": _category_str(enrichment.category),
+        "relevance_score": enrichment.relevance_score,
+    }
+    if article.sources_count is not None:
+        meta["sources_count"] = article.sources_count
+    if article.insider is not None:
+        event = article.insider
+        meta["insider"] = {
+            "side": event.side,
+            "transaction_code": event.transaction_code,
+            "shares": _plain(event.shares),
+            "avg_price_usd": _plain(event.avg_price_usd),
+            "total_value_usd": _plain(event.total_value_usd),
+            "is_10b5_1": event.is_10b5_1,
+            "insider_name": event.insider_name,
+            "insider_title": event.insider_title,
+            "is_officer": event.is_officer,
+            "is_director": event.is_director,
+            "is_ten_percent_owner": event.is_ten_percent_owner,
+            "transaction_date": _plain(event.transaction_date),
+        }
+    return Document(content=content, meta=meta)
+
+
+@component
+class AlphaAINewsFetcher:
+    """Fetches AI-scored financial news from AlphaAI as Haystack Documents.
+
+    Each Document's ``content`` is the article title plus summary; ``meta``
+    carries the enrichment (tickers, category, 1-10 ``relevance_score``,
+    source, url, publish time). Filters set in ``__init__`` are defaults and
+    can be overridden per ``run()`` call.
+
+    Requires an AlphaAI API key (free tier available, no card) — see
+    https://alphai.io/developers. The key is read from the ``ALPHAI_API_KEY``
+    environment variable by default.
+
+    ```python
+    from alphai_haystack import AlphaAINewsFetcher
+
+    fetcher = AlphaAINewsFetcher(symbol="NVDA", min_relevance=7)
+    documents = fetcher.run()["documents"]
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: Secret = Secret.from_env_var("ALPHAI_API_KEY"),
+        symbol: str | None = None,
+        category: str | None = None,
+        min_relevance: int | None = None,
+        collapse_stories: bool = False,
+        top_k: int = DEFAULT_TOP_K,
+    ) -> None:
+        """
+        :param api_key: AlphaAI API key. Defaults to the ``ALPHAI_API_KEY`` env var.
+        :param symbol: Only articles tagged with this ticker (e.g. ``"NVDA"``).
+        :param category: Only articles in this category (e.g. ``"earnings"``,
+            ``"mergers_acquisitions"``, ``"insider"``).
+        :param min_relevance: Only articles scored at or above this 1-10 floor.
+        :param collapse_stories: Collapse same-story coverage into one item.
+        :param top_k: Maximum number of Documents to return per run.
+        """
+        if top_k < 1:
+            raise ValueError("top_k must be at least 1")
+        self.api_key = api_key
+        self.symbol = symbol
+        self.category = category
+        self.min_relevance = min_relevance
+        self.collapse_stories = collapse_stories
+        self.top_k = top_k
+        self._client: Client | None = None
+
+    def warm_up(self) -> None:
+        """Create the underlying API client once."""
+        if self._client is None:
+            self._client = Client(api_key=self.api_key.resolve_value())
+
+    def to_dict(self) -> dict[str, Any]:
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            symbol=self.symbol,
+            category=self.category,
+            min_relevance=self.min_relevance,
+            collapse_stories=self.collapse_stories,
+            top_k=self.top_k,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AlphaAINewsFetcher:
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        result: AlphaAINewsFetcher = default_from_dict(cls, data)
+        return result
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        symbol: str | None = None,
+        category: str | None = None,
+        min_relevance: int | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """Fetch the newest matching articles.
+
+        :param symbol: Overrides the ticker filter set in ``__init__``.
+        :param category: Overrides the category filter set in ``__init__``.
+        :param min_relevance: Overrides the relevance floor set in ``__init__``.
+        :param top_k: Overrides the maximum number of Documents.
+        :returns: ``{"documents": [...]}`` — newest first.
+        """
+        self.warm_up()
+        assert self._client is not None
+        articles = self._client.news.iter(
+            symbol=symbol if symbol is not None else self.symbol,
+            category=category if category is not None else self.category,
+            min_relevance=min_relevance if min_relevance is not None else self.min_relevance,
+            collapse_stories=self.collapse_stories,
+            max_items=top_k if top_k is not None else self.top_k,
+        )
+        return {"documents": [_to_document(article) for article in articles]}
+
+
+@component
+class AlphaAIInsiderNewsFetcher:
+    """Fetches SEC Form 4 insider-trading events from AlphaAI as Documents.
+
+    Every item is one insider event (a filing's grouped buy/sell transactions)
+    with a structured ``meta["insider"]`` block: side, shares, average price,
+    total value, who traded, and whether it was a pre-planned 10b5-1 sale.
+    Relevance scores on this feed are deterministic from the event's summed
+    value, so ``min_relevance`` works as an "only large trades" dial.
+
+    ```python
+    from alphai_haystack import AlphaAIInsiderNewsFetcher
+
+    fetcher = AlphaAIInsiderNewsFetcher(min_relevance=7)
+    documents = fetcher.run()["documents"]
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: Secret = Secret.from_env_var("ALPHAI_API_KEY"),
+        symbol: str | None = None,
+        min_relevance: int | None = None,
+        top_k: int = DEFAULT_TOP_K,
+    ) -> None:
+        """
+        :param api_key: AlphaAI API key. Defaults to the ``ALPHAI_API_KEY`` env var.
+        :param symbol: Only events for this ticker (share-class siblings included).
+        :param min_relevance: 1-10 floor; higher means larger trades only.
+        :param top_k: Maximum number of Documents to return per run.
+        """
+        if top_k < 1:
+            raise ValueError("top_k must be at least 1")
+        self.api_key = api_key
+        self.symbol = symbol
+        self.min_relevance = min_relevance
+        self.top_k = top_k
+        self._client: Client | None = None
+
+    def warm_up(self) -> None:
+        """Create the underlying API client once."""
+        if self._client is None:
+            self._client = Client(api_key=self.api_key.resolve_value())
+
+    def to_dict(self) -> dict[str, Any]:
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            symbol=self.symbol,
+            min_relevance=self.min_relevance,
+            top_k=self.top_k,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AlphaAIInsiderNewsFetcher:
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        result: AlphaAIInsiderNewsFetcher = default_from_dict(cls, data)
+        return result
+
+    @component.output_types(documents=list[Document])
+    def run(
+        self,
+        symbol: str | None = None,
+        min_relevance: int | None = None,
+        top_k: int | None = None,
+    ) -> dict[str, list[Document]]:
+        """Fetch the newest matching insider events.
+
+        :param symbol: Overrides the ticker filter set in ``__init__``.
+        :param min_relevance: Overrides the relevance floor set in ``__init__``.
+        :param top_k: Overrides the maximum number of Documents.
+        :returns: ``{"documents": [...]}`` — newest first.
+        """
+        self.warm_up()
+        assert self._client is not None
+        articles = self._client.news.insider_iter(
+            symbol=symbol if symbol is not None else self.symbol,
+            min_relevance=min_relevance if min_relevance is not None else self.min_relevance,
+            max_items=top_k if top_k is not None else self.top_k,
+        )
+        return {"documents": [_to_document(article) for article in articles]}

alphai_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: alphai-haystack
+Version: 0.1.0
+Summary: Haystack components for AlphaAI: AI-scored financial news and SEC Form 4 insider events as Documents.
+Project-URL: Homepage, https://alphai.io
+Project-URL: Documentation, https://alphai.io/developers
+Project-URL: Repository, https://github.com/makeev/alphai-haystack
+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,haystack,insider,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.1
+Requires-Dist: haystack-ai<3,>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# alphai-haystack
+
+[![PyPI](https://img.shields.io/pypi/v/alphai-haystack)](https://pypi.org/project/alphai-haystack/)
+[![CI](https://github.com/makeev/alphai-haystack/actions/workflows/ci.yml/badge.svg)](https://github.com/makeev/alphai-haystack/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[Haystack](https://haystack.deepset.ai) components for [AlphaAI](https://alphai.io) — AI-scored
+financial news and SEC Form 4 insider events, delivered as Haystack `Document` objects.
+
+Every article on the AlphaAI feed is enriched at ingest: per-ticker impact analysis, a category,
+and a 1-10 relevance score. SEC Form 4 filings become structured insider events about 6 minutes
+after they hit EDGAR. These components fetch that feed so your pipelines and agents can reason
+over pre-scored market news instead of raw headlines.
+
+## Components
+
+- **`AlphaAINewsFetcher`** — the main news feed. Filter by ticker, category, and a relevance
+  floor; optionally collapse same-story coverage into one item.
+- **`AlphaAIInsiderNewsFetcher`** — SEC Form 4 insider events with a structured
+  `meta["insider"]` block: side, shares, average price, total value, who traded, and whether it
+  was a pre-planned 10b5-1 sale.
+
+## Installation
+
+```bash
+pip install alphai-haystack
+```
+
+## API key
+
+Get a free key at [alphai.io/developers](https://alphai.io/developers) (free tier: 20 requests
+per minute, 100 per day, no card). The components read it from the `ALPHAI_API_KEY` environment
+variable by default:
+
+```bash
+export ALPHAI_API_KEY="ak_..."
+```
+
+## Usage
+
+### Standalone
+
+```python
+from alphai_haystack import AlphaAINewsFetcher
+
+fetcher = AlphaAINewsFetcher(symbol="NVDA", min_relevance=7)
+documents = fetcher.run()["documents"]
+
+for doc in documents:
+    print(doc.meta["relevance_score"], doc.meta["title"])
+```
+
+### Insider events
+
+```python
+from alphai_haystack import AlphaAIInsiderNewsFetcher
+
+fetcher = AlphaAIInsiderNewsFetcher(min_relevance=7)  # higher floor = larger trades
+for doc in fetcher.run()["documents"]:
+    insider = doc.meta["insider"]
+    print(insider["insider_name"], insider["side"], insider["total_value_usd"], doc.meta["tickers"])
+```
+
+### In a pipeline
+
+A minimal market-brief pipeline: fetch scored news for a ticker, hand it to an LLM.
+
+```python
+from haystack import Pipeline
+from haystack.components.builders import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+
+from alphai_haystack import AlphaAINewsFetcher
+
+template = """Summarize what moved {{ symbol }} today, using only these articles:
+{% for doc in documents %}
+- {{ doc.content }} (relevance {{ doc.meta.relevance_score }}/10)
+{% endfor %}
+"""
+
+pipeline = Pipeline()
+pipeline.add_component("news", AlphaAINewsFetcher(min_relevance=6, collapse_stories=True))
+pipeline.add_component("prompt", PromptBuilder(template=template))
+pipeline.add_component("llm", OpenAIGenerator(model="gpt-4o-mini"))
+pipeline.connect("news.documents", "prompt.documents")
+pipeline.connect("prompt", "llm")
+
+result = pipeline.run({"news": {"symbol": "NVDA"}, "prompt": {"symbol": "NVDA"}})
+print(result["llm"]["replies"][0])
+```
+
+Both components implement `to_dict`/`from_dict`, so pipelines serialize to YAML and back; the
+API key is stored as an environment-variable reference, never as the raw value.
+
+## Document shape
+
+`content` is the article title plus summary. `meta` carries:
+
+| Key | Type | Notes |
+|---|---|---|
+| `uid` | str | Stable article id (use with the AlphaAI article endpoint) |
+| `url` | str | Original article URL |
+| `title`, `source`, `source_domain` | str | |
+| `published_at` | str | ISO 8601 |
+| `tickers` | list[str] | Tickers the article affects |
+| `category` | str | One of 14 categories (`earnings`, `insider`, `crypto`, ...) |
+| `relevance_score` | int | 1-10, assigned at ingest |
+| `sources_count` | int | Only when `collapse_stories=True` |
+| `insider` | dict | Insider feed only: side, shares, avg price, total value, who |
+
+## Run parameters
+
+`run()` accepts per-call overrides for the filters set in `__init__`: `symbol`, `category`
+(news fetcher only), `min_relevance`, and `top_k`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check . && ruff format --check .
+mypy src/alphai_haystack
+pytest
+```
+
+Tests run fully offline against a fake client.
+
+## Links
+
+- [AlphaAI developer docs](https://alphai.io/developers)
+- [OpenAPI schema](https://api.alphai.io/api/schema/)
+- [Python SDK (`alphai-sdk`)](https://github.com/makeev/alphai-sdk) — this package is a thin
+  Haystack layer over it
+- [MCP server](https://alphai.io/mcp) — the same feed for MCP-speaking agents
+
+## License
+
+MIT

alphai_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+alphai_haystack/__init__.py,sha256=tl0EDjXAX8rBYpym-4XGNIOINFaCHz7vzc40R1cA-Yw,289
+alphai_haystack/_version.py,sha256=CpXi3jGlx23RvRyU7iytOMZrnspdWw4yofS8lpP1AJU,18
+alphai_haystack/fetchers.py,sha256=P2O8CZ12lpYRfQyAS6vjsjTF5zF0SN4rtySausYG2NM,9806
+alphai_haystack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+alphai_haystack-0.1.0.dist-info/METADATA,sha256=FLsaFh3CVcEvUbm5xfn_EsXWiwSG4zAnScxNJGEdjIM,6120
+alphai_haystack-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+alphai_haystack-0.1.0.dist-info/licenses/LICENSE,sha256=4T4cfri1G0YoudJcTv8EiNmTf2ElLYTybG22ZrMfCVs,1064
+alphai_haystack-0.1.0.dist-info/RECORD,,

alphai_haystack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

alphai_haystack-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlphaAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.