Source code for system.agents.finance_agent.market_data_tools
import requests
import re
import json
from datetime import date, timedelta
from typing import Optional, Any, Sequence
from .tools_config.ticker_tools import (
fetch_company_data,
extract_financial_metrics,
score_news_sentiment,
decide_action)
from .tools_config.local_ticker_tools import (
_validate_symbol,
_validate_date,
_request_json,
_build_tool_result,
_error,
DEFAULT_HISTORY_DAYS,
FinancialDataset,
_validate_country_code,
_validate_year,
)
from ...utility.utils import get_env
# foreign ticker tool
[docs]
def analyse_ticker(symbol: str) -> str:
"""Execute a comprehensive financial analysis pipeline for a given stock ticker.
This is a high-level wrapper function that orchestrates a complete research and
analysis workflow for a stock. It fetches current company data, extracts financial
metrics, analyzes news sentiment, and produces a
buy/sell/hold verdict.
The analysis steps are executed in sequence:
1. Fetch company data and financials from yfinance
2. Extract key financial metrics (P/E ratios, revenue, debt, etc.)
3. Retrieve and analyze recent news headlines for sentiment
4. Apply decision rules to produce a buy/sell/hold recommendation
Args:
symbol (str): The stock ticker symbol to analyze (e.g., "AAPL", "MSFT", "GOOGL").
Will be converted to uppercase. Must be a valid ticker symbol
recognized by yfinance.
Returns:
Dict[str, Any]: A comprehensive analysis result containing:
- symbol (str): The stock ticker symbol in uppercase
- company (str): The company name or long name
- metrics (Dict): Financial metrics including:
* current_price (float): Current stock price
* trailing_pe (float): Trailing price-to-earnings ratio
* forward_pe (float): Forward P/E ratio
* market_cap (float): Market capitalization
* revenue (float): Annual revenue
* net_income (float): Annual net income
* revenue_growth_pct (float): Year-over-year revenue growth percentage
* total_debt (float): Total company debt
* total_equity (float): Total stockholder equity
* debt_to_equity (float): Debt-to-equity ratio
- headlines (List[str]): Recent news headlines for the company
- sentiment_score (float): Aggregate sentiment score (-1.0 to 1.0)
where positive indicates bullish sentiment
- verdict (str): Investment decision: "BUY", "SELL", or "HOLD"
- verdict_details (Dict): Detailed reasoning for the decision including:
* score (int): Net score from decision rules
* reasons (List[str]): List of factors that influenced the decision
* recommendation (str): Full recommendation text
Raises:
Exception: May raise various exceptions if yfinance fails to fetch data,
if the ticker symbol is invalid, or if network issues occur.
These are logged but may propagate up.
Example:
result = analyse_ticker("AAPL")
print(f"Verdict for {result['symbol']}: {result['verdict']}")
print(f"Current Price: ${result['metrics']['current_price']}")
print(f"Sentiment: {result['sentiment_score']}")
"""
try:
data = fetch_company_data(symbol)
except Exception as exc:
return json.dumps({
"symbol": symbol.upper(),
"error": f"Fetch failed: {exc}"
})
metrics = extract_financial_metrics(data)
headlines = []
for item in data.get("news", []):
if isinstance(item, dict):
headlines.append(item.get("title", ""))
elif isinstance(item, str):
headlines.append(item)
else:
headlines.append(str(item))
sentiment = score_news_sentiment(headlines)
decision = decide_action(metrics, sentiment)
result = json.dumps({
"symbol": symbol.upper(),
"company": data.get("company"),
"metrics": metrics,
"headlines": headlines,
"sentiment_score": sentiment,
"verdict": decision["verdict"],
"verdict_details": decision,
})
return result
# local ticker tools
# Financial data tool
[docs]
def financial_data_tool(
symbol: str,
include: Sequence[FinancialDataset] = (
"historical",
"fundamentals",
),
start_date: Optional[str] = None,
end_date: Optional[str] = None,
fundamentals_filter: Optional[str] = None,
news_limit: int = 5,
) -> dict[str, Any]:
"""
Retrieve issuer-specific financial data for a market instrument from
EOD Historical Data (EODHD).
PURPOSE
Use this tool when the agent needs information directly related to
a company/security rather than country-level macroeconomic context.
SUPPORTED DATASETS
historical:
Daily end-of-day OHLCV observations. When dates are omitted, the
tool intentionally limits the request to approximately the most
recent 365 calendar days to avoid returning an unnecessarily large
dataset.
fundamentals:
Company profile, valuation, technical metrics, earnings,
dividends/splits, ownership, and/or financial statements,
depending on EODHD coverage and the `fundamentals_filter`.
EODHD may return missing fields for securities whose underlying
issuer does not report them.
news:
Recent financial-news articles associated with the requested
ticker. Each article may contain title, publication date, link,
mentioned symbols, tags, and sentiment fields.
sentiment:
EODHD daily aggregated sentiment observations for the requested
ticker over the requested date range.
SYMBOL FORMAT
Pass EODHD's exchange-qualified symbol, not merely the local ticker.
Example for AIICO on the Nigerian Exchange:
"AIICO.XNSA"
DATE SEMANTICS
Dates must use YYYY-MM-DD.
`start_date` and `end_date` apply to historical, news, and sentiment
requests.
If historical data is requested and no dates are supplied, the tool
uses the previous 365 calendar days.
If only `start_date` is supplied, `end_date` defaults to today.
If only `end_date` is supplied, `start_date` is one year before it.
FUNDAMENTALS FILTER
`fundamentals_filter` is passed directly to EODHD's `filter`
parameter. Omit it to request EODHD's complete fundamentals object.
Use filters to reduce response size, for example:
"General"
"Highlights,Valuation,Technicals"
"Financials::Income_Statement::yearly"
"Financials::Balance_Sheet::yearly"
"General,Highlights,Valuation,Earnings"
ERROR SEMANTICS
This function NEVER raises an HTTP/API error to the agent.
Instead, it returns an `errors` array containing:
code
message
source
endpoint
retryable
http_status (when available)
details (when available)
`status` is:
"success" -> every requested dataset succeeded.
"partial" -> at least one dataset succeeded and at least one
dataset failed.
"error" -> all requested datasets failed.
When `status` is "partial", the agent must use only the successfully
returned datasets and must not infer missing information.
RETURNS
A JSON-serializable dictionary with:
tool
status
ok
request
data
errors
"""
try:
normalized_symbol = _validate_symbol(symbol)
allowed_datasets = {
"historical",
"fundamentals",
"news",
"sentiment",
}
requested_datasets = list(dict.fromkeys(include))
invalid = set(requested_datasets) - allowed_datasets
if invalid:
raise ValueError(
f"Unsupported financial dataset(s): "
f"{sorted(invalid)}. "
f"Allowed values: {sorted(allowed_datasets)}."
)
if not requested_datasets:
raise ValueError(
"`include` must contain at least one dataset."
)
if not 1 <= news_limit <= 100:
raise ValueError("news_limit must be between 1 and 100.")
normalized_start = _validate_date(start_date, "start_date")
normalized_end = _validate_date(end_date, "end_date")
# Determine the bounded historical/news/sentiment window.
today = date.today()
if "historical" in requested_datasets:
if normalized_start is None and normalized_end is None:
historical_start = (
today - timedelta(days=DEFAULT_HISTORY_DAYS)
).isoformat()
historical_end = today.isoformat()
elif normalized_start is None:
historical_end_date = date.fromisoformat(normalized_end) # type: ignore[arg-type]
historical_start = (
historical_end_date - timedelta(days=DEFAULT_HISTORY_DAYS)
).isoformat()
historical_end = normalized_end
elif normalized_end is None:
historical_start = normalized_start
historical_end = today.isoformat()
else:
historical_start = normalized_start
historical_end = normalized_end
if historical_start > historical_end: # type: ignore[operator]
raise ValueError(
"start_date cannot be later than end_date."
)
else:
historical_start = normalized_start
historical_end = normalized_end
api_key = get_env("EODHD_API_KEY")
if not api_key:
return _build_tool_result(
tool_name="financial_data_tool",
request={
"symbol": normalized_symbol,
"include": requested_datasets,
},
data={},
errors=[
_error(
code="CONFIGURATION_ERROR",
message=(
"EODHD_API_KEY is not configured. "
"Set it as an environment variable before "
"calling financial_data_tool."
),
source="EODHD",
endpoint=get_env('EODHD_BASE_URL'),
retryable=False,
)
],
)
session = requests.Session()
data: dict[str, Any] = {}
errors: list[dict[str, Any]] = []
# Historical prices
if "historical" in requested_datasets:
endpoint = f"/eod/{normalized_symbol}"
payload, error = _request_json(
session=session,
source="EODHD",
endpoint=endpoint,
url=f"{get_env('EODHD_BASE_URL')}{endpoint}",
params={
"api_token": api_key,
"fmt": "json",
"from": historical_start,
"to": historical_end,
},
)
if error:
errors.append(error)
else:
data["historical"] = {
"symbol": normalized_symbol,
"from": historical_start,
"to": historical_end,
"records": payload,
"record_count": (
len(payload)
if isinstance(payload, list)
else None
),
}
# Fundamentals
if "fundamentals" in requested_datasets:
endpoint = f"/v1.1/fundamentals/{normalized_symbol}"
params: dict[str, Any] = {
"api_token": api_key,
"fmt": "json",
}
if fundamentals_filter:
params["filter"] = fundamentals_filter
payload, error = _request_json(
session=session,
source="EODHD",
endpoint=endpoint,
url=f"{get_env('EODHD_BASE_URL')}{endpoint}",
params=params,
)
if error:
errors.append(error)
else:
data["fundamentals"] = {
"symbol": normalized_symbol,
"filter": fundamentals_filter,
"records": payload,
}
# News
if "news" in requested_datasets:
endpoint = "/news"
params = {
"api_token": api_key,
"fmt": "json",
"s": normalized_symbol,
"limit": news_limit,
"offset": 0,
}
if normalized_start:
params["from"] = normalized_start
if normalized_end:
params["to"] = normalized_end
payload, error = _request_json(
session=session,
source="EODHD",
endpoint=endpoint,
url=f"{get_env('EODHD_BASE_URL')}{endpoint}",
params=params,
)
if error:
errors.append(error)
else:
data["news"] = {
"symbol": normalized_symbol,
"records": payload,
"record_count": (
len(payload)
if isinstance(payload, list)
else None
),
}
# Sentiment
if "sentiment" in requested_datasets:
endpoint = "/sentiments"
params = {
"api_token": api_key,
"fmt": "json",
"s": normalized_symbol,
}
if normalized_start:
params["from"] = normalized_start
if normalized_end:
params["to"] = normalized_end
payload, error = _request_json(
session=session,
source="EODHD",
endpoint=endpoint,
url=f"{get_env('EODHD_BASE_URL')}{endpoint}",
params=params,
)
if error:
errors.append(error)
else:
data["sentiment"] = {
"symbol": normalized_symbol,
"from": normalized_start,
"to": normalized_end,
"records": payload,
}
return _build_tool_result(
tool_name="financial_data_tool",
request={
"symbol": normalized_symbol,
"include": requested_datasets,
"start_date": normalized_start,
"end_date": normalized_end,
"historical_effective_start": historical_start,
"historical_effective_end": historical_end,
"fundamentals_filter": fundamentals_filter,
"news_limit": news_limit,
},
data=data,
errors=errors,
)
except ValueError as exc:
return _build_tool_result(
tool_name="financial_data_tool",
request={
"symbol": symbol,
"include": list(include),
},
data={},
errors=[
_error(
code="INVALID_ARGUMENT",
message=str(exc),
source="financial_data_tool",
endpoint="local_validation",
retryable=False,
)
],
)
# Macro context tool
[docs]
def macro_context_tool(
country_code: str = "ng",
*,
include_signals: bool = True,
include_fx: bool = True,
include_indicators: bool = False,
include_trade: bool = False,
base_currency: str = "USD",
quote_currencies: Sequence[str] = ("NGN",),
metric_keys: Optional[Sequence[str]] = None,
indicator_category: Optional[str] = None,
start_year: Optional[int] = None,
end_year: Optional[int] = None,
latest: bool = True,
trade_top_limit: int = 5,
) -> dict[str, Any]:
"""
Retrieve country-level macroeconomic and market-context data from
Africa API.
PURPOSE
Use this tool when the agent needs contextual information about the
economic environment surrounding a company or market. This tool does
not provide issuer-specific financial statements; those belong in
`financial_data_tool`.
COUNTRY
`country_code` is a two-letter country code.
The default "ng" means Nigeria.
SIGNALS
`include_signals=True` requests:
GET /v1/countries/{country_code}/signals
Country signals can contain current/selected observations such as
policy rates, inflation, official exchange rates, FX observations,
market snapshots, commodity benchmarks, trade summaries, and other
country-linked records depending on the country's available coverage.
The returned records can have different frequencies and reporting
periods. The agent must inspect their dates/freshness rather than
assuming every value represents today's condition.
FX
`include_fx=True` requests the latest FX rates through:
GET /v1/markets/fx-rates
`base_currency` defaults to USD.
`quote_currencies` defaults to ("NGN",).
INDICATORS
`include_indicators=True` queries:
GET /v1/data
Use `metric_keys` when the agent needs specific metrics, for example:
"gdp_current_usd"
"trade_balance_usd"
"exports_goods_services_usd"
"imports_goods_services_usd"
"policy_rate_pct"
`indicator_category` may be used to request a category such as
"economy" when specific metric keys are not supplied.
`latest=True` means "latest stored observation available from the
provider"; it does NOT mean "measured today."
TRADE
`include_trade=True` requests:
GET /v1/trade/overview/{country_code}
This can return aggregate trade series, latest snapshots, leading
export/import partners, and leading product categories where coverage
exists.
ERROR SEMANTICS
This function NEVER raises an API/HTTP error to the agent.
It returns structured errors with:
code
message
source
endpoint
retryable
http_status (when available)
details (when available)
`status` is:
"success" -> all requested datasets succeeded.
"partial" -> some datasets succeeded and some failed.
"error" -> all requested datasets failed.
If an optional dataset fails, the agent must not fabricate or infer
its missing values from another dataset.
IMPORTANT DATA-PROVENANCE RULE
Africa API aggregates observations from external sources. Every
returned indicator should be interpreted using its source, reporting
year/period, frequency, and freshness when those fields are present.
RETURNS
A JSON-serializable dictionary with:
tool
status
ok
request
data
errors
"""
try:
normalized_country = _validate_country_code(country_code)
normalized_base_currency = base_currency.strip().upper()
if not re.fullmatch(r"[A-Z]{3}", normalized_base_currency):
raise ValueError(
"base_currency must be a three-letter currency code, "
f"received {base_currency!r}."
)
normalized_quotes = tuple(
currency.strip().upper()
for currency in quote_currencies
)
if not normalized_quotes:
raise ValueError(
"quote_currencies must contain at least one currency."
)
for currency in normalized_quotes:
if not re.fullmatch(r"[A-Z]{3}", currency):
raise ValueError(
f"Invalid quote currency {currency!r}. "
"Expected a three-letter currency code."
)
if not (
include_signals
or include_fx
or include_indicators
or include_trade
):
raise ValueError(
"At least one macro dataset must be enabled."
)
normalized_start_year = _validate_year(
start_year,
"start_year",
)
normalized_end_year = _validate_year(
end_year,
"end_year",
)
if (
normalized_start_year is not None
and normalized_end_year is not None
and normalized_start_year > normalized_end_year
):
raise ValueError(
"start_year cannot be later than end_year."
)
if include_indicators and not metric_keys and not indicator_category:
raise ValueError(
"When include_indicators=True, provide either "
"metric_keys or indicator_category. "
"This prevents an accidental broad indicator download."
)
if not 1 <= trade_top_limit <= 50:
raise ValueError(
"trade_top_limit must be between 1 and 50."
)
api_key = get_env("AFRICA_API_KEY")
if not api_key:
return _build_tool_result(
tool_name="macro_context_tool",
request={
"country_code": normalized_country,
},
data={},
errors=[
_error(
code="CONFIGURATION_ERROR",
message=(
"AFRICA_API_KEY is not configured. "
"Set it as an environment variable before "
"calling macro_context_tool."
),
source="Africa API",
endpoint=get_env('AFRICA_API_BASE_URL'),
retryable=False,
)
],
)
headers = {
"Authorization": f"Bearer {api_key}",
"Accept": "application/json",
}
session = requests.Session()
data: dict[str, Any] = {}
errors: list[dict[str, Any]] = []
# Country signals
if include_signals:
endpoint = (
f"/countries/{normalized_country}/signals"
)
payload, error = _request_json(
session=session,
source="Africa API",
endpoint=endpoint,
url=f"{get_env('AFRICA_API_BASE_URL')}{endpoint}",
headers=headers,
)
if error:
errors.append(error)
else:
data["signals"] = {
"country_code": normalized_country,
"records": payload,
}
# FX
if include_fx:
endpoint = "/markets/fx-rates"
params = {
"base_currency": normalized_base_currency,
"quote_currencies": ",".join(normalized_quotes),
"country_code": normalized_country,
"limit": min(len(normalized_quotes) * 5, 500),
}
payload, error = _request_json(
session=session,
source="Africa API",
endpoint=endpoint,
url=f"{get_env('AFRICA_API_BASE_URL')}{endpoint}",
headers=headers,
params=params,
)
if error:
errors.append(error)
else:
data["fx"] = {
"base_currency": normalized_base_currency,
"quote_currencies": normalized_quotes,
"records": payload,
}
# Indicators
if include_indicators:
endpoint = "/data"
params: dict[str, Any] = {
"country_code": normalized_country,
"limit": 1000,
}
if metric_keys:
params["metric_keys"] = ",".join(
key.strip()
for key in metric_keys
if key.strip()
)
if indicator_category:
params["category"] = indicator_category.strip()
if normalized_start_year is not None:
params["start_year"] = normalized_start_year
if normalized_end_year is not None:
params["end_year"] = normalized_end_year
if latest:
params["latest"] = "true"
payload, error = _request_json(
session=session,
source="Africa API",
endpoint=endpoint,
url=f"{get_env('AFRICA_API_BASE_URL')}{endpoint}",
headers=headers,
params=params,
)
if error:
errors.append(error)
else:
data["indicators"] = {
"country_code": normalized_country,
"metric_keys": list(metric_keys)
if metric_keys
else None,
"category": indicator_category,
"latest": latest,
"records": payload,
}
# Trade
if include_trade:
endpoint = (
f"/trade/overview/{normalized_country}"
)
params = {
"top_limit": trade_top_limit,
}
if normalized_start_year is not None:
params["start_year"] = normalized_start_year
if normalized_end_year is not None:
params["end_year"] = normalized_end_year
payload, error = _request_json(
session=session,
source="Africa API",
endpoint=endpoint,
url=f"{get_env('AFRICA_API_BASE_URL')}{endpoint}",
headers=headers,
params=params,
)
if error:
errors.append(error)
else:
data["trade"] = {
"country_code": normalized_country,
"records": payload,
}
return _build_tool_result(
tool_name="macro_context_tool",
request={
"country_code": normalized_country,
"include_signals": include_signals,
"include_fx": include_fx,
"include_indicators": include_indicators,
"include_trade": include_trade,
"base_currency": normalized_base_currency,
"quote_currencies": normalized_quotes,
"metric_keys": (
list(metric_keys) if metric_keys else None
),
"indicator_category": indicator_category,
"start_year": normalized_start_year,
"end_year": normalized_end_year,
"latest": latest,
"trade_top_limit": trade_top_limit,
},
data=data,
errors=errors,
)
except ValueError as exc:
return _build_tool_result(
tool_name="macro_context_tool",
request={
"country_code": country_code,
},
data={},
errors=[
_error(
code="INVALID_ARGUMENT",
message=str(exc),
source="macro_context_tool",
endpoint="local_validation",
retryable=False,
)
],
)