secfeed-crewai 0.1.0__tar.gz

secfeed_crewai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SecFeed
+
+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.

secfeed_crewai-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: secfeed-crewai
+Version: 0.1.0
+Summary: SEC EDGAR tools for CrewAI agents: 10-K/10-Q sections, financial statements, insider trades, 8-Ks
+License: MIT
+Project-URL: Homepage, https://secfeedapi.com
+Project-URL: Source, https://github.com/secfeedapi/secfeed-crewai
+Keywords: crewai,sec,edgar,10-k,insider trading,financial statements,agents,tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: secfeed>=0.1.3
+Requires-Dist: crewai>=0.80
+Dynamic: license-file
+
+# SEC filing tools for CrewAI
+
+Give your CrewAI agents SEC EDGAR data: 10-K and 10-Q sections, XBRL financial statements, Form 4 insider trades and 8-K reports. Powered by the [SecFeed API](https://secfeedapi.com).
+
+No vector store, no embeddings and no OpenAI key needed for the tools: SecFeed returns the exact filing section (Risk Factors, MD&A, Business), and the tool hands your agent the paragraphs that match its question.
+
+```bash
+pip install "secfeed-crewai @ git+https://github.com/secfeedapi/secfeed-crewai"
+export SECFEED_API_KEY=sf_...   # free key: https://secfeedapi.com/signup/
+```
+
+```python
+from crewai import Agent
+from secfeed_crewai import SearchTenKTool, FinancialStatementsTool, InsiderTradesTool
+
+analyst = Agent(
+    role="Equity analyst",
+    goal="Explain NVDA's risks and financial health from its filings",
+    backstory="You only trust primary sources.",
+    tools=[SearchTenKTool(), FinancialStatementsTool(), InsiderTradesTool()],
+)
+```
+
+## Tools
+
+| Tool | What the agent gets | API calls |
+|---|---|---|
+| `SearchTenKTool` | The paragraphs of the latest 10-K that answer a question, from the right section (Business, Risk Factors, MD&A, Market Risk), with the filing link | 2 |
+| `SearchTenQTool` | Same for the latest 10-Q | 2 |
+| `FinancialStatementsTool` | Income statement, balance sheet and cash flow from XBRL, last periods side by side | 1 |
+| `InsiderTradesTool` | Latest Form 4 trades: who, role, buy or sell, shares, price, value, 10b5-1 flag | 1 |
+| `RecentEightKTool` | Latest 8-K reports and the items each one covers, with links | 2 |
+
+`all_tools()` returns all five. The plain functions behind them live in `secfeed_crewai.core` and work without CrewAI (LangChain, LlamaIndex, plain scripts).
+
+Example output of `InsiderTradesTool` for MSFT:
+
+```
+MSFT insider transactions (3817 on file, latest 3):
+- 2026-11-10 ... (EVP, Chief Marketing Officer): open market sale 5.00K sh @ 531.0 = $2.65M
+- 2026-11-09 ... (EVP, Chief Financial Officer): open market sale 5.91K sh @ 544.2359 = $3.22M, 10b5-1 plan
+```
+
+## Example: stock research crew
+
+`examples/stock_analysis/main.py` runs three agents (filings researcher, financial analyst, memo writer) and writes `memo-<TICKER>.md`:
+
+```bash
+export OPENAI_API_KEY=...        # or any model CrewAI supports:
+export MODEL=gpt-4o-mini         # e.g. MODEL=anthropic/<model> or MODEL=openrouter/<model>
+python examples/stock_analysis/main.py NVDA
+```
+
+A full run makes about a dozen SecFeed calls (tested: 11 for AMD), so the free trial covers it.
+
+## Coming from the CrewAI stock analysis example?
+
+The classic CrewAI stock analysis example looks up the latest filing, downloads the whole HTML page, splits it into chunks and embeds them with OpenAI to answer a question. These tools replace that whole file:
+
+```python
+# before
+from tools.sec_tools import SECTools
+tools = [SECTools.search_10q, SECTools.search_10k]
+
+# after
+from secfeed_crewai import SearchTenQTool, SearchTenKTool
+tools = [SearchTenQTool(), SearchTenKTool()]
+```
+
+You drop `unstructured`, `faiss` and the embeddings call, and the agent reads the actual section instead of random chunks of the page.
+
+## Also available
+
+- [secfeed](https://pypi.org/project/secfeed/) Python and Node SDKs for every SecFeed endpoint (13F holdings, Form D, full text search, XBRL frames and more)
+- [SecFeed MCP server](https://secfeedapi.com/mcp/) for Claude, Cursor and other MCP clients
+
+## License
+
+MIT

secfeed_crewai-0.1.0/README.md

@@ -0,0 +1,79 @@
+# SEC filing tools for CrewAI
+
+Give your CrewAI agents SEC EDGAR data: 10-K and 10-Q sections, XBRL financial statements, Form 4 insider trades and 8-K reports. Powered by the [SecFeed API](https://secfeedapi.com).
+
+No vector store, no embeddings and no OpenAI key needed for the tools: SecFeed returns the exact filing section (Risk Factors, MD&A, Business), and the tool hands your agent the paragraphs that match its question.
+
+```bash
+pip install "secfeed-crewai @ git+https://github.com/secfeedapi/secfeed-crewai"
+export SECFEED_API_KEY=sf_...   # free key: https://secfeedapi.com/signup/
+```
+
+```python
+from crewai import Agent
+from secfeed_crewai import SearchTenKTool, FinancialStatementsTool, InsiderTradesTool
+
+analyst = Agent(
+    role="Equity analyst",
+    goal="Explain NVDA's risks and financial health from its filings",
+    backstory="You only trust primary sources.",
+    tools=[SearchTenKTool(), FinancialStatementsTool(), InsiderTradesTool()],
+)
+```
+
+## Tools
+
+| Tool | What the agent gets | API calls |
+|---|---|---|
+| `SearchTenKTool` | The paragraphs of the latest 10-K that answer a question, from the right section (Business, Risk Factors, MD&A, Market Risk), with the filing link | 2 |
+| `SearchTenQTool` | Same for the latest 10-Q | 2 |
+| `FinancialStatementsTool` | Income statement, balance sheet and cash flow from XBRL, last periods side by side | 1 |
+| `InsiderTradesTool` | Latest Form 4 trades: who, role, buy or sell, shares, price, value, 10b5-1 flag | 1 |
+| `RecentEightKTool` | Latest 8-K reports and the items each one covers, with links | 2 |
+
+`all_tools()` returns all five. The plain functions behind them live in `secfeed_crewai.core` and work without CrewAI (LangChain, LlamaIndex, plain scripts).
+
+Example output of `InsiderTradesTool` for MSFT:
+
+```
+MSFT insider transactions (3817 on file, latest 3):
+- 2026-11-10 ... (EVP, Chief Marketing Officer): open market sale 5.00K sh @ 531.0 = $2.65M
+- 2026-11-09 ... (EVP, Chief Financial Officer): open market sale 5.91K sh @ 544.2359 = $3.22M, 10b5-1 plan
+```
+
+## Example: stock research crew
+
+`examples/stock_analysis/main.py` runs three agents (filings researcher, financial analyst, memo writer) and writes `memo-<TICKER>.md`:
+
+```bash
+export OPENAI_API_KEY=...        # or any model CrewAI supports:
+export MODEL=gpt-4o-mini         # e.g. MODEL=anthropic/<model> or MODEL=openrouter/<model>
+python examples/stock_analysis/main.py NVDA
+```
+
+A full run makes about a dozen SecFeed calls (tested: 11 for AMD), so the free trial covers it.
+
+## Coming from the CrewAI stock analysis example?
+
+The classic CrewAI stock analysis example looks up the latest filing, downloads the whole HTML page, splits it into chunks and embeds them with OpenAI to answer a question. These tools replace that whole file:
+
+```python
+# before
+from tools.sec_tools import SECTools
+tools = [SECTools.search_10q, SECTools.search_10k]
+
+# after
+from secfeed_crewai import SearchTenQTool, SearchTenKTool
+tools = [SearchTenQTool(), SearchTenKTool()]
+```
+
+You drop `unstructured`, `faiss` and the embeddings call, and the agent reads the actual section instead of random chunks of the page.
+
+## Also available
+
+- [secfeed](https://pypi.org/project/secfeed/) Python and Node SDKs for every SecFeed endpoint (13F holdings, Form D, full text search, XBRL frames and more)
+- [SecFeed MCP server](https://secfeedapi.com/mcp/) for Claude, Cursor and other MCP clients
+
+## License
+
+MIT

secfeed_crewai-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "secfeed-crewai"
+version = "0.1.0"
+description = "SEC EDGAR tools for CrewAI agents: 10-K/10-Q sections, financial statements, insider trades, 8-Ks"
+requires-python = ">=3.10"
+readme = "README.md"
+license = {text = "MIT"}
+dependencies = ["secfeed>=0.1.3", "crewai>=0.80"]
+keywords = ["crewai", "sec", "edgar", "10-k", "insider trading", "financial statements", "agents", "tools"]
+
+[project.urls]
+Homepage = "https://secfeedapi.com"
+Source = "https://github.com/secfeedapi/secfeed-crewai"
+
+[tool.setuptools]
+packages = ["secfeed_crewai"]

secfeed_crewai-0.1.0/secfeed_crewai/__init__.py

@@ -0,0 +1,8 @@
+"""SEC EDGAR tools for CrewAI agents, powered by the SecFeed API (https://secfeedapi.com)."""
+__version__ = "0.1.0"
+
+try:
+    from .tools import (FinancialStatementsTool, InsiderTradesTool, RecentEightKTool, SearchTenKTool,  # noqa: F401
+                        SearchTenQTool, all_tools)
+except ImportError:  # crewai not installed: the plain functions in secfeed_crewai.core still work
+    pass

secfeed_crewai-0.1.0/secfeed_crewai/core.py

@@ -0,0 +1,172 @@
+"""Plain functions behind the CrewAI tools. No CrewAI import here, so they work in any agent framework (or none).
+
+Every function returns compact text sized for an LLM context window, and costs one or two SecFeed API calls.
+"""
+import os
+import re
+
+from secfeed import Client, SecFeedError
+
+# Which part of a filing answers which kind of question. 10-K items: 1 Business, 1A Risk Factors, 7 MD&A, 7A market risk.
+# 10-Q items: part1item2 MD&A, part2item1a risk factor updates.
+SECTIONS = {
+    "10-K": {"business": "1", "risk": "1A", "mdna": "7", "market_risk": "7A"},
+    "10-Q": {"business": "part1item2", "risk": "part2item1a", "mdna": "part1item2", "market_risk": "part1item3"},
+}
+ROUTES = [  # (words in the question, section) checked in order; MD&A is the default
+    (("risk", "threat", "uncertain", "litigation", "regulat", "lawsuit"), "risk"),
+    (("interest rate", "currency", "foreign exchange", "hedg", "market risk"), "market_risk"),
+    (("product", "segment", "customer", "competit", "employee", "strategy", "business model", "what does"), "business"),
+]
+SECTION_NAMES = {"business": "Business", "risk": "Risk Factors", "mdna": "Management's Discussion and Analysis",
+                 "market_risk": "Market Risk"}
+STOP = set("the a an of to in and or for on is are was were be by with what how did does do its it this that from as at "
+           "which who their they has have had last year quarter company".split())
+MAX_CHARS = 6000
+
+
+def client(api_key=None):
+    key = api_key or os.environ.get("SECFEED_API_KEY")
+    if not key:
+        raise SecFeedError("Set SECFEED_API_KEY (free key at https://secfeedapi.com/signup/)")
+    return Client(key)
+
+
+def _section_for(question):
+    q = question.lower()
+    for words, section in ROUTES:
+        if any(w in q for w in words):
+            return section
+    return "mdna"
+
+
+def _terms(text):
+    return {w for w in re.findall(r"[a-z][a-z0-9&\-]+", text.lower()) if w not in STOP and len(w) > 2}
+
+
+def best_passages(text, question, max_chars=MAX_CHARS):
+    """Paragraphs of `text` ranked by how many of the question's words they contain, kept in document order.
+    Simple keyword ranking: no embeddings, no vector store, no extra API key."""
+    paras = [p.strip() for p in re.split(r"\n\s*\n", text) if len(p.strip()) > 80]
+    terms = _terms(question)
+    if not paras:
+        return text[:max_chars]
+    scored = sorted(range(len(paras)), key=lambda i: -len(terms & _terms(paras[i])))
+    keep, size = set(), 0
+    for i in scored:
+        if size + len(paras[i]) > max_chars and keep:
+            continue
+        keep.add(i)
+        size += len(paras[i])
+        if size >= max_chars:
+            break
+    return "\n\n".join(paras[i] for i in sorted(keep))
+
+
+_FILINGS, _SECTIONS = {}, {}  # per-process caches: agents often ask several questions about the same filing
+
+
+def latest_filing(sf, ticker, form):
+    k = (ticker.upper(), form)
+    if k not in _FILINGS:
+        res = sf.filings(f'ticker:{ticker.upper()} AND formType:"{form}"', size=1)
+        _FILINGS[k] = (res.get("filings") or [None])[0]
+    return _FILINGS[k]
+
+
+def _section_text(sf, url, item):
+    if (url, item) not in _SECTIONS:
+        _SECTIONS[(url, item)] = sf.extract(url, item)
+    return _SECTIONS[(url, item)]
+
+
+def search_filing(ticker, question, form="10-K", section=None, api_key=None):
+    """Answer material for `question` from the company's latest 10-K or 10-Q: picks the right section (or `section`:
+    business, risk, mdna, market_risk), then returns the most relevant paragraphs."""
+    sf = client(api_key)
+    form = form.upper()
+    if form not in SECTIONS:
+        return "form must be 10-K or 10-Q"
+    f = latest_filing(sf, ticker, form)
+    if not f:
+        return f"No {form} found for {ticker}. Check the ticker."
+    section = section if section in SECTIONS[form] else _section_for(question)
+    try:
+        text = _section_text(sf, f["linkToFilingDetails"], SECTIONS[form][section])
+    except SecFeedError as e:
+        return f"Could not read {SECTION_NAMES[section]} of {f['companyName']} {form} filed {f['filedAt']}: {e}"
+    head = (f"{f['companyName']} ({ticker.upper()}) {form} filed {f['filedAt']}, section: {SECTION_NAMES[section]}\n"
+            f"Source: {f['linkToFilingDetails']}\n\n")
+    return head + best_passages(text, question)
+
+
+def _money(v):
+    try:
+        v = float(v)
+    except (TypeError, ValueError):
+        return str(v)
+    for div, unit in ((1e9, "B"), (1e6, "M"), (1e3, "K")):
+        if abs(v) >= div:
+            return f"{v / div:,.2f}{unit}"
+    return f"{v:,.2f}"
+
+
+def financials(ticker, form="10-K", api_key=None):
+    """Income statement, balance sheet and cash flow from the latest 10-K or 10-Q (XBRL), newest periods first."""
+    sf = client(api_key)
+    rows = sf.financial_statements(ticker.upper(), form_type=form.upper(), n=1)
+    if not rows:
+        return f"No XBRL financial statements found for {ticker}."
+    data = rows[0]
+    out = [f"{ticker.upper()} {form.upper()} financial statements (accession {data.get('accessionNo')}), USD unless noted"]
+    for name, items in data.items():
+        if not isinstance(items, dict):
+            continue
+        out.append(f"\n{name}")
+        for concept, facts in list(items.items())[:25]:
+            if not isinstance(facts, list):
+                continue
+            vals = []
+            for x in [x for x in facts if not x.get("segment")][:2]:
+                p = x.get("period") or {}
+                when = p.get("endDate") or p.get("instant") or ""
+                vals.append(f"{when}: {_money(x.get('value'))}")
+            if vals:
+                out.append(f"  {concept}: " + "; ".join(vals))
+    return "\n".join(out)[:12000]
+
+
+CODES = {"P": "open market buy", "S": "open market sale", "A": "grant", "M": "option exercise", "F": "tax withholding",
+         "G": "gift"}
+
+
+def insider_trades(ticker, code=None, limit=20, api_key=None):
+    """Latest Form 4 insider transactions. code: P (buys), S (sales) or None for all."""
+    sf = client(api_key)
+    res = sf.insider_trades(ticker=ticker.upper(), code=code, size=min(int(limit), 50))
+    tx = res.get("transactions") or []
+    if not tx:
+        return f"No insider transactions found for {ticker}."
+    out = [f"{ticker.upper()} insider transactions ({res.get('total')} on file, latest {len(tx)}):"]
+    for t in tx:
+        o = (t.get("owners") or [{}])[0]
+        role = o.get("officerTitle") or ("Director" if o.get("isDirector") else "10% owner" if o.get("isTenPercentOwner") else "")
+        val = f" = ${_money(t['shares'] * t['price'])}" if t.get("shares") and t.get("price") else ""
+        plan = ", 10b5-1 plan" if t.get("aff10b5one") else ""
+        out.append(f"- {t.get('tx_date')} {o.get('name')} ({role}): {CODES.get(t.get('code'), t.get('code'))} "
+                   f"{_money(t.get('shares'))} sh @ {t.get('price')}{val}{plan}")
+    return "\n".join(out)
+
+
+def recent_8k(ticker, limit=10, api_key=None):
+    """Latest 8-K current reports with the items each one covers (earnings, deals, leadership, etc.)."""
+    sf = client(api_key)
+    f = latest_filing(sf, ticker, "8-K")
+    if not f:
+        return f"No 8-K found for {ticker}."
+    res = sf.events_8k(cik=f["cik"], size=min(int(limit), 50))
+    out = [f"{f['companyName']} ({ticker.upper()}) latest 8-K reports:"]
+    for e in res.get("filings") or []:
+        items = "; ".join(f"{i['item']} {i['title']}" for i in e.get("items") or [])
+        out.append(f"- {e.get('filed')}: {items}  {e.get('url')}")
+    return "\n".join(out)

secfeed_crewai-0.1.0/secfeed_crewai/tools.py

@@ -0,0 +1,85 @@
+"""CrewAI tools for SEC EDGAR data via the SecFeed API. Set SECFEED_API_KEY in the environment."""
+from typing import Literal, Optional, Type
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from . import core
+
+
+class FilingQuestion(BaseModel):
+    ticker: str = Field(..., description="Stock ticker, e.g. NVDA")
+    question: str = Field(..., description="What you want to find out from the filing")
+    section: Optional[str] = Field(
+        None, description="Optional: business, risk, mdna or market_risk. Picked from the question when left empty.")
+
+
+class SearchTenKTool(BaseTool):
+    name: str = "Search latest 10-K"
+    description: str = ("Reads the company's latest annual report (10-K) and returns the passages most relevant to the "
+                        "question, with a link to the filing. Good for business model, risk factors and full-year results.")
+    args_schema: Type[BaseModel] = FilingQuestion
+
+    def _run(self, ticker: str, question: str, section: Optional[str] = None) -> str:
+        return core.search_filing(ticker, question, "10-K", section or None)
+
+
+class SearchTenQTool(BaseTool):
+    name: str = "Search latest 10-Q"
+    description: str = ("Reads the company's latest quarterly report (10-Q) and returns the passages most relevant to the "
+                        "question, with a link to the filing. Good for the most recent quarter's results and outlook.")
+    args_schema: Type[BaseModel] = FilingQuestion
+
+    def _run(self, ticker: str, question: str, section: Optional[str] = None) -> str:
+        return core.search_filing(ticker, question, "10-Q", section or None)
+
+
+class FinancialsInput(BaseModel):
+    ticker: str = Field(..., description="Stock ticker, e.g. NVDA")
+    form: Literal["10-K", "10-Q"] = Field("10-K", description="10-K for annual figures, 10-Q for the latest quarter")
+
+
+class FinancialStatementsTool(BaseTool):
+    name: str = "Financial statements"
+    description: str = ("Income statement, balance sheet and cash flow figures from the latest 10-K or 10-Q, taken from "
+                        "the filing's XBRL data, with the last few periods side by side.")
+    args_schema: Type[BaseModel] = FinancialsInput
+
+    def _run(self, ticker: str, form: str = "10-K") -> str:
+        return core.financials(ticker, form)
+
+
+class InsiderInput(BaseModel):
+    ticker: str = Field(..., description="Stock ticker, e.g. NVDA")
+    code: Optional[str] = Field(None, description="P for open market buys only, S for sales only, empty for all")
+    limit: int = Field(20, description="How many transactions, up to 50")
+
+
+class InsiderTradesTool(BaseTool):
+    name: str = "Insider trades"
+    description: str = ("Latest Form 4 insider transactions for a company: who traded, their role, buy or sell, shares, "
+                        "price, value and whether it was under a 10b5-1 plan.")
+    args_schema: Type[BaseModel] = InsiderInput
+
+    def _run(self, ticker: str, code: Optional[str] = None, limit: int = 20) -> str:
+        code = (code or "").strip().upper()[:1] or None
+        return core.insider_trades(ticker, code if code in ("P", "S") else None, limit)
+
+
+class EightKInput(BaseModel):
+    ticker: str = Field(..., description="Stock ticker, e.g. NVDA")
+    limit: int = Field(10, description="How many reports, up to 50")
+
+
+class RecentEightKTool(BaseTool):
+    name: str = "Recent 8-K reports"
+    description: str = ("The company's latest 8-K current reports and what each one covers (earnings releases, material "
+                        "agreements, leadership changes, other events), with links.")
+    args_schema: Type[BaseModel] = EightKInput
+
+    def _run(self, ticker: str, limit: int = 10) -> str:
+        return core.recent_8k(ticker, limit)
+
+
+def all_tools():
+    return [SearchTenKTool(), SearchTenQTool(), FinancialStatementsTool(), InsiderTradesTool(), RecentEightKTool()]

secfeed_crewai-0.1.0/secfeed_crewai.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: secfeed-crewai
+Version: 0.1.0
+Summary: SEC EDGAR tools for CrewAI agents: 10-K/10-Q sections, financial statements, insider trades, 8-Ks
+License: MIT
+Project-URL: Homepage, https://secfeedapi.com
+Project-URL: Source, https://github.com/secfeedapi/secfeed-crewai
+Keywords: crewai,sec,edgar,10-k,insider trading,financial statements,agents,tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: secfeed>=0.1.3
+Requires-Dist: crewai>=0.80
+Dynamic: license-file
+
+# SEC filing tools for CrewAI
+
+Give your CrewAI agents SEC EDGAR data: 10-K and 10-Q sections, XBRL financial statements, Form 4 insider trades and 8-K reports. Powered by the [SecFeed API](https://secfeedapi.com).
+
+No vector store, no embeddings and no OpenAI key needed for the tools: SecFeed returns the exact filing section (Risk Factors, MD&A, Business), and the tool hands your agent the paragraphs that match its question.
+
+```bash
+pip install "secfeed-crewai @ git+https://github.com/secfeedapi/secfeed-crewai"
+export SECFEED_API_KEY=sf_...   # free key: https://secfeedapi.com/signup/
+```
+
+```python
+from crewai import Agent
+from secfeed_crewai import SearchTenKTool, FinancialStatementsTool, InsiderTradesTool
+
+analyst = Agent(
+    role="Equity analyst",
+    goal="Explain NVDA's risks and financial health from its filings",
+    backstory="You only trust primary sources.",
+    tools=[SearchTenKTool(), FinancialStatementsTool(), InsiderTradesTool()],
+)
+```
+
+## Tools
+
+| Tool | What the agent gets | API calls |
+|---|---|---|
+| `SearchTenKTool` | The paragraphs of the latest 10-K that answer a question, from the right section (Business, Risk Factors, MD&A, Market Risk), with the filing link | 2 |
+| `SearchTenQTool` | Same for the latest 10-Q | 2 |
+| `FinancialStatementsTool` | Income statement, balance sheet and cash flow from XBRL, last periods side by side | 1 |
+| `InsiderTradesTool` | Latest Form 4 trades: who, role, buy or sell, shares, price, value, 10b5-1 flag | 1 |
+| `RecentEightKTool` | Latest 8-K reports and the items each one covers, with links | 2 |
+
+`all_tools()` returns all five. The plain functions behind them live in `secfeed_crewai.core` and work without CrewAI (LangChain, LlamaIndex, plain scripts).
+
+Example output of `InsiderTradesTool` for MSFT:
+
+```
+MSFT insider transactions (3817 on file, latest 3):
+- 2026-11-10 ... (EVP, Chief Marketing Officer): open market sale 5.00K sh @ 531.0 = $2.65M
+- 2026-11-09 ... (EVP, Chief Financial Officer): open market sale 5.91K sh @ 544.2359 = $3.22M, 10b5-1 plan
+```
+
+## Example: stock research crew
+
+`examples/stock_analysis/main.py` runs three agents (filings researcher, financial analyst, memo writer) and writes `memo-<TICKER>.md`:
+
+```bash
+export OPENAI_API_KEY=...        # or any model CrewAI supports:
+export MODEL=gpt-4o-mini         # e.g. MODEL=anthropic/<model> or MODEL=openrouter/<model>
+python examples/stock_analysis/main.py NVDA
+```
+
+A full run makes about a dozen SecFeed calls (tested: 11 for AMD), so the free trial covers it.
+
+## Coming from the CrewAI stock analysis example?
+
+The classic CrewAI stock analysis example looks up the latest filing, downloads the whole HTML page, splits it into chunks and embeds them with OpenAI to answer a question. These tools replace that whole file:
+
+```python
+# before
+from tools.sec_tools import SECTools
+tools = [SECTools.search_10q, SECTools.search_10k]
+
+# after
+from secfeed_crewai import SearchTenQTool, SearchTenKTool
+tools = [SearchTenQTool(), SearchTenKTool()]
+```
+
+You drop `unstructured`, `faiss` and the embeddings call, and the agent reads the actual section instead of random chunks of the page.
+
+## Also available
+
+- [secfeed](https://pypi.org/project/secfeed/) Python and Node SDKs for every SecFeed endpoint (13F holdings, Form D, full text search, XBRL frames and more)
+- [SecFeed MCP server](https://secfeedapi.com/mcp/) for Claude, Cursor and other MCP clients
+
+## License
+
+MIT

secfeed_crewai-0.1.0/secfeed_crewai.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+secfeed_crewai/__init__.py
+secfeed_crewai/core.py
+secfeed_crewai/tools.py
+secfeed_crewai.egg-info/PKG-INFO
+secfeed_crewai.egg-info/SOURCES.txt
+secfeed_crewai.egg-info/dependency_links.txt
+secfeed_crewai.egg-info/requires.txt
+secfeed_crewai.egg-info/top_level.txt
+tests/test_core.py

secfeed_crewai-0.1.0/secfeed_crewai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

secfeed_crewai-0.1.0/secfeed_crewai.egg-info/requires.txt

@@ -0,0 +1,2 @@
+secfeed>=0.1.3
+crewai>=0.80

secfeed_crewai-0.1.0/secfeed_crewai.egg-info/top_level.txt

@@ -0,0 +1 @@
+secfeed_crewai

secfeed_crewai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

secfeed_crewai-0.1.0/tests/test_core.py

@@ -0,0 +1,32 @@
+"""Offline tests: section routing and passage ranking. Run: python -m unittest discover -s tests"""
+import unittest
+
+from secfeed_crewai import core
+
+
+class Routing(unittest.TestCase):
+    def test_sections(self):
+        self.assertEqual(core._section_for("What are the biggest risks?"), "risk")
+        self.assertEqual(core._section_for("Who are its main competitors?"), "business")
+        self.assertEqual(core._section_for("How exposed is it to interest rate changes?"), "market_risk")
+        self.assertEqual(core._section_for("How did revenue grow?"), "mdna")
+
+
+class Passages(unittest.TestCase):
+    def test_keeps_matching_paragraphs_in_order(self):
+        filler = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore. " * 3
+        text = "\n\n".join([filler, "Export controls on China reduced our data center revenue in the quarter. " * 2,
+                            filler, "Tariffs and export controls may change again and hurt China sales. " * 2])
+        out = core.best_passages(text, "export controls China", max_chars=400)
+        self.assertIn("reduced our data center", out)
+        self.assertIn("Tariffs", out)
+        self.assertLess(out.index("reduced"), out.index("Tariffs"))
+        self.assertNotIn("Lorem", out)
+
+    def test_money(self):
+        self.assertEqual(core._money("215938000000"), "215.94B")
+        self.assertEqual(core._money(5000), "5.00K")
+
+
+if __name__ == "__main__":
+    unittest.main()