fmp-ai-tools 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FMP Node Wrapper
+
+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.

package/README.md

@@ -0,0 +1,217 @@
+# FMP Tools
+
+AI tools for Financial Modeling Prep (FMP) Node API - compatible with Vercel AI SDK, Langchain, OpenAI, and more.
+
+This package provides pre-built AI tools that can be used with various AI frameworks. For direct API access, use the `fmp-node-api` package.
+
+## Installation
+
+```bash
+npm install fmp-tools
+# or
+pnpm add fmp-tools
+# or
+yarn add fmp-tools
+```
+
+## Quick Start
+
+### Vercel AI SDK (Recommended)
+
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { streamText, convertToModelMessages, stepCountIs } from 'ai';
+import { fmpTools } from 'fmp-tools/vercel-ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai('gpt-4o-mini'),
+    messages: convertToModelMessages(messages),
+    tools: fmpTools,
+    stopWhen: stepCountIs(5),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Configuration
+
+**Important**: You must set your FMP API key as an environment variable for the tools to work:
+
+```bash
+FMP_API_KEY=your_api_key_here
+```
+
+The tools internally use the `fmp-node-api` library, which reads this environment variable to authenticate with the Financial Modeling Prep API.
+
+## Available Tools
+
+### Quote Tools
+
+- `getStockQuote` - Get real-time stock quote for a company
+
+### Company Tools
+
+- `getCompanyProfile` - Get comprehensive company profile and information
+
+### Financial Tools
+
+- `getBalanceSheet` - Get balance sheet statements (annual/quarterly)
+- `getIncomeStatement` - Get income statements (annual/quarterly)
+- `getCashFlowStatement` - Get cash flow statements (annual/quarterly)
+- `getFinancialRatios` - Get financial ratios and metrics (annual/quarterly)
+
+### Stock Tools
+
+- `getMarketCap` - Get market capitalization for a company
+- `getStockSplits` - Get historical stock splits for a company
+- `getDividendHistory` - Get dividend history and payments for a company
+
+### Market Tools
+
+- `getMarketPerformance` - Get overall market performance data
+- `getSectorPerformance` - Get sector performance data
+- `getGainers` - Get top gaining stocks
+- `getLosers` - Get top losing stocks
+- `getMostActive` - Get most actively traded stocks
+
+### Economic Tools
+
+- `getTreasuryRates` - Get treasury rates and yields
+- `getEconomicIndicators` - Get economic indicators (GDP, CPI, unemployment, etc.)
+
+### ETF Tools
+
+- `getETFHoldings` - Get holdings for a specific ETF
+- `getETFProfile` - Get ETF profile and information
+
+### Calendar Tools
+
+- `getEarningsCalendar` - Get upcoming earnings calendar
+- `getEconomicCalendar` - Get economic calendar events
+
+### Senate & House Trading Tools
+
+- `getSenateTrading` - Get recent Senate trading activity
+- `getHouseTrading` - Get recent House trading activity
+- `getSenateTradingByName` - Get Senate trading by politician name
+- `getHouseTradingByName` - Get House trading by politician name
+- `getSenateTradingRSSFeed` - Get Senate trading RSS feed
+- `getHouseTradingRSSFeed` - Get House trading RSS feed
+
+### Institutional Tools
+
+- `getInstitutionalHolders` - Get institutional holders for a company
+
+### Insider Trading Tools
+
+- `getInsiderTrading` - Get insider trading data for a company
+
+## Using Individual Tools
+
+You can import and use specific tool categories or individual tools:
+
+### Import Specific Categories
+
+```typescript
+import { quoteTools, financialTools, marketTools } from 'fmp-tools/vercel-ai';
+
+// Use only quote and financial tools
+const selectedTools = {
+  ...quoteTools,
+  ...financialTools,
+};
+
+// Use with Vercel AI SDK
+const result = streamText({
+  model: openai('gpt-4o-mini'),
+  messages: convertToModelMessages(messages),
+  tools: selectedTools,
+});
+```
+
+### Example Tool Usage
+
+Here are some example prompts you can use with the tools:
+
+**Stock Analysis:**
+
+```
+"Get the current stock quote for Apple (AAPL) and show me their latest balance sheet"
+```
+
+**Market Research:**
+
+```
+"What are the top gaining stocks today and show me the overall market performance?"
+```
+
+**Economic Analysis:**
+
+```
+"Get the current treasury rates and show me the latest GDP data"
+```
+
+**ETF Research:**
+
+```
+"Show me the holdings of SPY ETF and get its profile information"
+```
+
+**Financial Analysis:**
+
+```
+"Get Apple's income statement, cash flow statement, and financial ratios for the last year"
+```
+
+## Tool Parameters
+
+Each tool accepts specific parameters. Here are some common ones:
+
+- `symbol` - Stock/ETF symbol (e.g., "AAPL", "SPY")
+- `period` - For financial statements: "annual" or "quarter"
+- `from` - Start date in YYYY-MM-DD format
+- `to` - End date in YYYY-MM-DD format
+- `name` - For economic indicators: specific indicator name
+
+## Error Handling
+
+The tools handle API errors gracefully and will return informative error messages if:
+
+- The API key is invalid or missing
+- The requested data is not available
+- Rate limits are exceeded
+- Invalid parameters are provided
+
+## Testing Tools
+
+Test individual tools:
+
+```bash
+# Test specific tools
+pnpm test:tool getStockQuote
+pnpm test:tool getCompanyProfile
+pnpm test:tool getBalanceSheet
+pnpm test:tool getMarketPerformance
+```
+
+## For Direct API Access
+
+If you need direct access to the FMP API without AI tools, use the `fmp-node-api` package:
+
+```typescript
+import { FMP } from 'fmp-node-api';
+
+const fmp = new FMP({ apiKey: 'your_api_key_here' });
+
+// Direct API calls
+const quote = await fmp.quote.getQuote('AAPL');
+const profile = await fmp.company.getCompanyProfile('AAPL');
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Tool interface that matches the ai library's expected format
+ * This is what the ai library produces when using their tool() function
+ */
+interface Tool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, any>;
+            required: string[];
+        };
+    };
+    execute: (args: any) => Promise<string>;
+}
+
+export type { Tool };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tool interface that matches the ai library's expected format
+ * This is what the ai library produces when using their tool() function
+ */
+interface Tool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, any>;
+            required: string[];
+        };
+    };
+    execute: (args: any) => Promise<string>;
+}
+
+export type { Tool };

package/dist/index.js

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/index.mjs

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/providers/vercel-ai/index.d.mts

@@ -0,0 +1,96 @@
+import * as ai from 'ai';
+export { ToolSet } from 'ai';
+
+declare const quoteTools: {
+    getStockQuote: ai.Tool<unknown, unknown>;
+};
+
+declare const companyTools: {
+    getCompanyProfile: ai.Tool<unknown, unknown>;
+};
+
+declare const financialTools: {
+    getBalanceSheet: ai.Tool<unknown, unknown>;
+    getIncomeStatement: ai.Tool<unknown, unknown>;
+    getCashFlowStatement: ai.Tool<unknown, unknown>;
+    getFinancialRatios: ai.Tool<unknown, unknown>;
+};
+
+declare const calendarTools: {
+    getEarningsCalendar: ai.Tool<unknown, unknown>;
+    getEconomicCalendar: ai.Tool<unknown, unknown>;
+};
+
+declare const economicTools: {
+    getTreasuryRates: ai.Tool<unknown, unknown>;
+    getEconomicIndicators: ai.Tool<unknown, unknown>;
+};
+
+declare const etfTools: {
+    getETFHoldings: ai.Tool<unknown, unknown>;
+    getETFProfile: ai.Tool<unknown, unknown>;
+};
+
+declare const insiderTools: {
+    getInsiderTrading: ai.Tool<unknown, unknown>;
+};
+
+declare const institutionalTools: {
+    getInstitutionalHolders: ai.Tool<unknown, unknown>;
+};
+
+declare const marketTools: {
+    getMarketPerformance: ai.Tool<unknown, unknown>;
+    getSectorPerformance: ai.Tool<unknown, unknown>;
+    getGainers: ai.Tool<unknown, unknown>;
+    getLosers: ai.Tool<unknown, unknown>;
+    getMostActive: ai.Tool<unknown, unknown>;
+};
+
+declare const senateHouseTools: {
+    getSenateTrading: ai.Tool<unknown, unknown>;
+    getHouseTrading: ai.Tool<unknown, unknown>;
+    getSenateTradingByName: ai.Tool<unknown, unknown>;
+    getHouseTradingByName: ai.Tool<unknown, unknown>;
+    getSenateTradingRSSFeed: ai.Tool<unknown, unknown>;
+    getHouseTradingRSSFeed: ai.Tool<unknown, unknown>;
+};
+
+declare const stockTools: {
+    getMarketCap: ai.Tool<unknown, unknown>;
+    getStockSplits: ai.Tool<unknown, unknown>;
+    getDividendHistory: ai.Tool<unknown, unknown>;
+};
+
+declare const fmpTools: {
+    readonly getMarketCap: ai.Tool<unknown, unknown>;
+    readonly getStockSplits: ai.Tool<unknown, unknown>;
+    readonly getDividendHistory: ai.Tool<unknown, unknown>;
+    readonly getSenateTrading: ai.Tool<unknown, unknown>;
+    readonly getHouseTrading: ai.Tool<unknown, unknown>;
+    readonly getSenateTradingByName: ai.Tool<unknown, unknown>;
+    readonly getHouseTradingByName: ai.Tool<unknown, unknown>;
+    readonly getSenateTradingRSSFeed: ai.Tool<unknown, unknown>;
+    readonly getHouseTradingRSSFeed: ai.Tool<unknown, unknown>;
+    readonly getMarketPerformance: ai.Tool<unknown, unknown>;
+    readonly getSectorPerformance: ai.Tool<unknown, unknown>;
+    readonly getGainers: ai.Tool<unknown, unknown>;
+    readonly getLosers: ai.Tool<unknown, unknown>;
+    readonly getMostActive: ai.Tool<unknown, unknown>;
+    readonly getInstitutionalHolders: ai.Tool<unknown, unknown>;
+    readonly getInsiderTrading: ai.Tool<unknown, unknown>;
+    readonly getETFHoldings: ai.Tool<unknown, unknown>;
+    readonly getETFProfile: ai.Tool<unknown, unknown>;
+    readonly getTreasuryRates: ai.Tool<unknown, unknown>;
+    readonly getEconomicIndicators: ai.Tool<unknown, unknown>;
+    readonly getEarningsCalendar: ai.Tool<unknown, unknown>;
+    readonly getEconomicCalendar: ai.Tool<unknown, unknown>;
+    readonly getBalanceSheet: ai.Tool<unknown, unknown>;
+    readonly getIncomeStatement: ai.Tool<unknown, unknown>;
+    readonly getCashFlowStatement: ai.Tool<unknown, unknown>;
+    readonly getFinancialRatios: ai.Tool<unknown, unknown>;
+    readonly getCompanyProfile: ai.Tool<unknown, unknown>;
+    readonly getStockQuote: ai.Tool<unknown, unknown>;
+};
+
+export { calendarTools, companyTools, economicTools, etfTools, financialTools, fmpTools, insiderTools, institutionalTools, marketTools, quoteTools, senateHouseTools, stockTools };

package/dist/providers/vercel-ai/index.d.ts

@@ -0,0 +1,96 @@
+import * as ai from 'ai';
+export { ToolSet } from 'ai';
+
+declare const quoteTools: {
+    getStockQuote: ai.Tool<unknown, unknown>;
+};
+
+declare const companyTools: {
+    getCompanyProfile: ai.Tool<unknown, unknown>;
+};
+
+declare const financialTools: {
+    getBalanceSheet: ai.Tool<unknown, unknown>;
+    getIncomeStatement: ai.Tool<unknown, unknown>;
+    getCashFlowStatement: ai.Tool<unknown, unknown>;
+    getFinancialRatios: ai.Tool<unknown, unknown>;
+};
+
+declare const calendarTools: {
+    getEarningsCalendar: ai.Tool<unknown, unknown>;
+    getEconomicCalendar: ai.Tool<unknown, unknown>;
+};
+
+declare const economicTools: {
+    getTreasuryRates: ai.Tool<unknown, unknown>;
+    getEconomicIndicators: ai.Tool<unknown, unknown>;
+};
+
+declare const etfTools: {
+    getETFHoldings: ai.Tool<unknown, unknown>;
+    getETFProfile: ai.Tool<unknown, unknown>;
+};
+
+declare const insiderTools: {
+    getInsiderTrading: ai.Tool<unknown, unknown>;
+};
+
+declare const institutionalTools: {
+    getInstitutionalHolders: ai.Tool<unknown, unknown>;
+};
+
+declare const marketTools: {
+    getMarketPerformance: ai.Tool<unknown, unknown>;
+    getSectorPerformance: ai.Tool<unknown, unknown>;
+    getGainers: ai.Tool<unknown, unknown>;
+    getLosers: ai.Tool<unknown, unknown>;
+    getMostActive: ai.Tool<unknown, unknown>;
+};
+
+declare const senateHouseTools: {
+    getSenateTrading: ai.Tool<unknown, unknown>;
+    getHouseTrading: ai.Tool<unknown, unknown>;
+    getSenateTradingByName: ai.Tool<unknown, unknown>;
+    getHouseTradingByName: ai.Tool<unknown, unknown>;
+    getSenateTradingRSSFeed: ai.Tool<unknown, unknown>;
+    getHouseTradingRSSFeed: ai.Tool<unknown, unknown>;
+};
+
+declare const stockTools: {
+    getMarketCap: ai.Tool<unknown, unknown>;
+    getStockSplits: ai.Tool<unknown, unknown>;
+    getDividendHistory: ai.Tool<unknown, unknown>;
+};
+
+declare const fmpTools: {
+    readonly getMarketCap: ai.Tool<unknown, unknown>;
+    readonly getStockSplits: ai.Tool<unknown, unknown>;
+    readonly getDividendHistory: ai.Tool<unknown, unknown>;
+    readonly getSenateTrading: ai.Tool<unknown, unknown>;
+    readonly getHouseTrading: ai.Tool<unknown, unknown>;
+    readonly getSenateTradingByName: ai.Tool<unknown, unknown>;
+    readonly getHouseTradingByName: ai.Tool<unknown, unknown>;
+    readonly getSenateTradingRSSFeed: ai.Tool<unknown, unknown>;
+    readonly getHouseTradingRSSFeed: ai.Tool<unknown, unknown>;
+    readonly getMarketPerformance: ai.Tool<unknown, unknown>;
+    readonly getSectorPerformance: ai.Tool<unknown, unknown>;
+    readonly getGainers: ai.Tool<unknown, unknown>;
+    readonly getLosers: ai.Tool<unknown, unknown>;
+    readonly getMostActive: ai.Tool<unknown, unknown>;
+    readonly getInstitutionalHolders: ai.Tool<unknown, unknown>;
+    readonly getInsiderTrading: ai.Tool<unknown, unknown>;
+    readonly getETFHoldings: ai.Tool<unknown, unknown>;
+    readonly getETFProfile: ai.Tool<unknown, unknown>;
+    readonly getTreasuryRates: ai.Tool<unknown, unknown>;
+    readonly getEconomicIndicators: ai.Tool<unknown, unknown>;
+    readonly getEarningsCalendar: ai.Tool<unknown, unknown>;
+    readonly getEconomicCalendar: ai.Tool<unknown, unknown>;
+    readonly getBalanceSheet: ai.Tool<unknown, unknown>;
+    readonly getIncomeStatement: ai.Tool<unknown, unknown>;
+    readonly getCashFlowStatement: ai.Tool<unknown, unknown>;
+    readonly getFinancialRatios: ai.Tool<unknown, unknown>;
+    readonly getCompanyProfile: ai.Tool<unknown, unknown>;
+    readonly getStockQuote: ai.Tool<unknown, unknown>;
+};
+
+export { calendarTools, companyTools, economicTools, etfTools, financialTools, fmpTools, insiderTools, institutionalTools, marketTools, quoteTools, senateHouseTools, stockTools };