alphai-haystack 0.1.0__tar.gz

alphai_haystack-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.python-version.local
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Env / secrets
+.env
+*.local
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# uv
+uv.lock

alphai_haystack-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-07-28
+
+Initial release.
+
+- `AlphaAINewsFetcher`: the scored news feed as Haystack Documents, with `symbol` /
+  `category` / `min_relevance` / `collapse_stories` / `top_k` filters and per-run overrides.
+- `AlphaAIInsiderNewsFetcher`: SEC Form 4 insider events with a structured
+  `meta["insider"]` block.
+- Pipeline-safe serialization (`to_dict` / `from_dict`, API key as a `Secret`
+  env-var reference).

alphai_haystack-0.1.0/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.

alphai_haystack-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,137 @@
+# 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/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "alphai-haystack"
+dynamic = ["version"]
+description = "Haystack components for AlphaAI: AI-scored financial news and SEC Form 4 insider events as Documents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "AlphaAI", email = "support@alphai.io" }]
+keywords = [
+    "haystack",
+    "alphai",
+    "financial-news",
+    "stocks",
+    "sec",
+    "insider",
+    "rag",
+    "llm",
+    "agents",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+dependencies = [
+    "haystack-ai>=2.6,<3",
+    "alphai-sdk>=0.4.1,<1",
+]
+
+[project.urls]
+Homepage = "https://alphai.io"
+Documentation = "https://alphai.io/developers"
+Repository = "https://github.com/makeev/alphai-haystack"
+"API Reference" = "https://api.alphai.io/api/schema/"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    # Capped on purpose: CI runs `ruff format --check .`, and a ruff minor can
+    # widen what "formatted" means (0.16 started formatting Markdown code blocks).
+    # Bump deliberately, reformat in the same commit.
+    "ruff>=0.6,<0.17",
+    "mypy>=1.10",
+]
+
+[tool.hatch.version]
+path = "src/alphai_haystack/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/alphai_haystack"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4", "PIE", "RUF"]
+ignore = ["B008"]
+
+# python_version is 3.12 (not our 3.10 floor) because numpy 2.x stubs use
+# PEP 695 `type` statements, which mypy refuses to parse under 3.10/3.11.
+# 3.10 compatibility is held by ruff (target-version py310) and the CI matrix.
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src/alphai_haystack"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

alphai_haystack-0.1.0/src/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-0.1.0/src/alphai_haystack/_version.py

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

alphai_haystack-0.1.0/src/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/tests/conftest.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from datetime import date, datetime, timezone
+from decimal import Decimal
+from typing import Any
+
+import pytest
+from alphai.models.news import (
+    EnrichedArticle,
+    InsiderEvent,
+    OriginalArticle,
+    RichNewsArticle,
+)
+
+
+def make_article(
+    uid: str = "a1b2c3d4e5f60718",
+    title: str = "Nvidia beats on data-center revenue",
+    summary: str = "Q2 revenue came in above consensus, driven by data-center demand.",
+    tickers: list[str] | None = None,
+    relevance_score: int = 8,
+    category: str = "earnings",
+    insider: InsiderEvent | None = None,
+    sources_count: int | None = None,
+) -> RichNewsArticle:
+    return RichNewsArticle(
+        original=OriginalArticle(
+            uid=uid,
+            title=title,
+            url=f"https://example.com/{uid}",
+            time_published=datetime(2026, 7, 28, 12, 30, tzinfo=timezone.utc),
+            summary=summary,
+            source="Example Wire",
+            source_domain="example.com",
+        ),
+        enrichment=EnrichedArticle(
+            category=category,
+            tickers=tickers if tickers is not None else ["NVDA"],
+            relevance_score=relevance_score,
+        ),
+        insider=insider,
+        sources_count=sources_count,
+    )
+
+
+def make_insider_event() -> InsiderEvent:
+    return InsiderEvent(
+        side="sell",
+        transaction_code="S",
+        shares=Decimal("120000"),
+        avg_price_usd=Decimal("171.31"),
+        total_value_usd=Decimal("20557200.00"),
+        is_10b5_1=True,
+        insider_name="Jensen Huang",
+        insider_title="CEO",
+        is_officer=True,
+        transaction_date=date(2026, 7, 24),
+    )
+
+
+class FakeNewsResource:
+    """Records call kwargs and yields canned articles."""
+
+    def __init__(self, articles: list[RichNewsArticle]) -> None:
+        self.articles = articles
+        self.iter_calls: list[dict[str, Any]] = []
+        self.insider_calls: list[dict[str, Any]] = []
+
+    def iter(self, **kwargs: Any) -> Iterator[RichNewsArticle]:
+        self.iter_calls.append(kwargs)
+        max_items = kwargs.get("max_items")
+        yield from self.articles[:max_items]
+
+    def insider_iter(self, **kwargs: Any) -> Iterator[RichNewsArticle]:
+        self.insider_calls.append(kwargs)
+        max_items = kwargs.get("max_items")
+        yield from self.articles[:max_items]
+
+
+class FakeClient:
+    def __init__(self, articles: list[RichNewsArticle]) -> None:
+        self.news = FakeNewsResource(articles)
+
+
+@pytest.fixture()
+def articles() -> list[RichNewsArticle]:
+    return [make_article(uid=f"uid{i:013d}", title=f"Article {i}") for i in range(25)]

alphai_haystack-0.1.0/tests/test_fetchers.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import pytest
+from alphai.models.news import RichNewsArticle
+from haystack import Document
+
+from alphai_haystack import AlphaAIInsiderNewsFetcher, AlphaAINewsFetcher
+from alphai_haystack.fetchers import _to_document
+from conftest import FakeClient, make_article, make_insider_event
+
+
+def news_fetcher_with(articles: list[RichNewsArticle], **kwargs: object) -> AlphaAINewsFetcher:
+    fetcher = AlphaAINewsFetcher(**kwargs)  # type: ignore[arg-type]
+    fetcher._client = FakeClient(articles)  # type: ignore[assignment]
+    return fetcher
+
+
+def insider_fetcher_with(
+    articles: list[RichNewsArticle], **kwargs: object
+) -> AlphaAIInsiderNewsFetcher:
+    fetcher = AlphaAIInsiderNewsFetcher(**kwargs)  # type: ignore[arg-type]
+    fetcher._client = FakeClient(articles)  # type: ignore[assignment]
+    return fetcher
+
+
+def test_document_mapping() -> None:
+    document = _to_document(make_article())
+    assert isinstance(document, Document)
+    assert document.content is not None
+    assert document.content.startswith("Nvidia beats on data-center revenue")
+    assert "above consensus" in document.content
+    assert document.meta["uid"] == "a1b2c3d4e5f60718"
+    assert document.meta["tickers"] == ["NVDA"]
+    assert document.meta["category"] == "earnings"
+    assert document.meta["relevance_score"] == 8
+    assert document.meta["published_at"] == "2026-07-28T12:30:00+00:00"
+    assert document.meta["source_domain"] == "example.com"
+    assert "insider" not in document.meta
+
+
+def test_document_mapping_insider_block() -> None:
+    document = _to_document(make_article(insider=make_insider_event()))
+    insider = document.meta["insider"]
+    assert insider["side"] == "sell"
+    assert insider["shares"] == "120000"
+    assert insider["total_value_usd"] == "20557200.00"
+    assert insider["is_10b5_1"] is True
+    assert insider["insider_name"] == "Jensen Huang"
+    assert insider["transaction_date"] == "2026-07-24"
+
+
+def test_news_run_returns_top_k_documents(articles: list[RichNewsArticle]) -> None:
+    fetcher = news_fetcher_with(articles, top_k=5)
+    documents = fetcher.run()["documents"]
+    assert len(documents) == 5
+    assert documents[0].meta["title"] == "Article 0"
+
+
+def test_news_run_passes_init_filters(articles: list[RichNewsArticle]) -> None:
+    fetcher = news_fetcher_with(
+        articles, symbol="NVDA", category="earnings", min_relevance=7, collapse_stories=True
+    )
+    fetcher.run()
+    call = fetcher._client.news.iter_calls[0]  # type: ignore[union-attr]
+    assert call == {
+        "symbol": "NVDA",
+        "category": "earnings",
+        "min_relevance": 7,
+        "collapse_stories": True,
+        "max_items": 10,
+    }
+
+
+def test_news_run_overrides_beat_init(articles: list[RichNewsArticle]) -> None:
+    fetcher = news_fetcher_with(articles, symbol="NVDA", min_relevance=7, top_k=10)
+    fetcher.run(symbol="AMD", min_relevance=9, top_k=3)
+    call = fetcher._client.news.iter_calls[0]  # type: ignore[union-attr]
+    assert call["symbol"] == "AMD"
+    assert call["min_relevance"] == 9
+    assert call["max_items"] == 3
+
+
+def test_insider_run_passes_filters(articles: list[RichNewsArticle]) -> None:
+    fetcher = insider_fetcher_with(articles, symbol="NVDA", min_relevance=8, top_k=4)
+    documents = fetcher.run()["documents"]
+    assert len(documents) == 4
+    call = fetcher._client.news.insider_calls[0]  # type: ignore[union-attr]
+    assert call == {"symbol": "NVDA", "min_relevance": 8, "max_items": 4}
+
+
+def test_top_k_must_be_positive() -> None:
+    with pytest.raises(ValueError):
+        AlphaAINewsFetcher(top_k=0)
+    with pytest.raises(ValueError):
+        AlphaAIInsiderNewsFetcher(top_k=-1)
+
+
+def test_warm_up_uses_resolved_secret(monkeypatch: pytest.MonkeyPatch) -> None:
+    created: list[str] = []
+
+    class RecordingClient:
+        def __init__(self, api_key: str) -> None:
+            created.append(api_key)
+
+    monkeypatch.setattr("alphai_haystack.fetchers.Client", RecordingClient)
+    monkeypatch.setenv("ALPHAI_API_KEY", "ak_test_123")
+    fetcher = AlphaAINewsFetcher()
+    fetcher.warm_up()
+    fetcher.warm_up()  # second call must not create a second client
+    assert created == ["ak_test_123"]

alphai_haystack-0.1.0/tests/test_serialization.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import pytest
+
+from alphai_haystack import AlphaAIInsiderNewsFetcher, AlphaAINewsFetcher
+
+
+def test_news_fetcher_to_dict_from_dict_roundtrip(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ALPHAI_API_KEY", "ak_test_123")
+    fetcher = AlphaAINewsFetcher(
+        symbol="NVDA", category="earnings", min_relevance=7, collapse_stories=True, top_k=5
+    )
+    data = fetcher.to_dict()
+
+    init = data["init_parameters"]
+    assert init["symbol"] == "NVDA"
+    assert init["category"] == "earnings"
+    assert init["min_relevance"] == 7
+    assert init["collapse_stories"] is True
+    assert init["top_k"] == 5
+    # The secret must serialize as an env-var reference, never as the raw key.
+    assert init["api_key"]["type"] == "env_var"
+    assert "ak_test_123" not in str(data)
+
+    restored = AlphaAINewsFetcher.from_dict(data)
+    assert restored.symbol == "NVDA"
+    assert restored.top_k == 5
+    assert restored.api_key.resolve_value() == "ak_test_123"
+
+
+def test_insider_fetcher_to_dict_from_dict_roundtrip(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ALPHAI_API_KEY", "ak_test_123")
+    fetcher = AlphaAIInsiderNewsFetcher(symbol="AAPL", min_relevance=9, top_k=3)
+    data = fetcher.to_dict()
+
+    init = data["init_parameters"]
+    assert init["symbol"] == "AAPL"
+    assert init["min_relevance"] == 9
+    assert init["top_k"] == 3
+    assert init["api_key"]["type"] == "env_var"
+
+    restored = AlphaAIInsiderNewsFetcher.from_dict(data)
+    assert restored.symbol == "AAPL"
+    assert restored.min_relevance == 9
+
+
+def test_fetchers_are_pipeline_serializable(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The components must survive a full Pipeline YAML round-trip."""
+    from haystack import Pipeline
+
+    monkeypatch.setenv("ALPHAI_API_KEY", "ak_test_123")
+    pipeline = Pipeline()
+    pipeline.add_component("news", AlphaAINewsFetcher(symbol="NVDA"))
+    pipeline.add_component("insider", AlphaAIInsiderNewsFetcher(min_relevance=8))
+
+    yaml_text = pipeline.dumps()
+    assert "ak_test_123" not in yaml_text
+
+    restored = Pipeline.loads(yaml_text)
+    news = restored.get_component("news")
+    assert isinstance(news, AlphaAINewsFetcher)
+    assert news.symbol == "NVDA"