US Stock Analyzer

Three-factor stock analysis combining DCF valuation, Livermore trend trading rules, and VIX market sentiment to generate high-confidence buy signals for US e...

Security Scan

The skill appears to implement the advertised three‑factor stock analysis and mostly requests only the API key it needs, but there are metadata/instruction inconsistencies (and a small install metadata oddity) that could cause accidental credential exposure or confusion — review before installing.

Purpose & Capability

Name/description, code, and SKILL.md all align: the package fetches price, financials, VIX, computes DCF, trend and sentiment scores, and produces buy signals. Required binaries (python3, pip3) and listed Python dependencies are appropriate for this purpose. However, the registry metadata marks FMP_API_KEY as a required/primary credential while SKILL.md and the code treat it as optional (used only to enhance financials). Also the install entries repeatedly claim they 'create' a python3 binary which is incorrect and inconsistent with typical Python package installs.

Instruction Scope

SKILL.md instructs the agent to run the included Python scripts and to set the FMP_API_KEY optionally. The runtime instructions and code only reference repo-local config.yaml, environment variable FMP_API_KEY, and external data providers (Yahoo via yfinance and FinancialModelingPrep via requests). There are no instructions to read unrelated system files, other environment secrets, or to exfiltrate data to unexpected endpoints.

Install Mechanism

Dependencies are standard PyPI packages (yfinance, pandas, numpy, matplotlib, pyyaml, requests) and requirements.txt matches. This is a low-to-moderate risk install pattern. The oddity: the manifest/install metadata lists each 'uv' package as 'creates binaries: python3' which is incorrect (pip packages should not be claiming to create the python3 binary) — likely a metadata mistake rather than malicious behavior.

Credentials

Only one credential (FMP_API_KEY) is requested, which is proportionate for optional FinancialModelingPrep access. But the registry metadata declares FMP_API_KEY as required and the primary credential while SKILL.md and the code treat it as optional (it falls back to free Yahoo data). This mismatch could lead users to supply an API key unnecessarily or to assume the skill will function only with the key. Confirm whether the key is mandatory before providing it; also check whether logs or outputs include the key (the code uses it only in API requests).

Persistence & Privilege

The skill does not request always:true, does not modify other skills, and does not claim persistent system-wide privileges. It runs on-demand and only reads its own config.yaml and environment variables. Autonomous invocation is allowed (platform default) but there are no additional privilege escalations requested.

What to consider before installing

What to check before installing: - Clarify the FMP_API_KEY requirement: registry metadata marks it required but SKILL.md and code treat it as optional. If you don't need enhanced FMP financials, you can run with only Yahoo data. Avoid setting a sensitive API key globally until you confirm it's necessary. - Inspect config.yaml and the scripts (already present) to confirm no hidden endpoints; this package uses Yahoo (yfinance) and FinancialModelingPrep (requests to their API). Those are expected for this tool. - The install metadata incorrectly lists that the packages create a 'python3' binary — treat that as a metadata bug, not evidence of hidden installers. Still, install packages from PyPI only and prefer creating an isolated virtualenv before pip installing. - Network behavior: the skill makes outbound HTTP requests to public financial APIs (yfinance and FMP). If you must keep data local or avoid network calls, do not run it or run in an isolated environment. - If you will provide an FMP API key, consider using a scoped API key, storing it in a restricted environment (not a shared machine env), and verifying the code does not log or persist the key anywhere unintended. - If the metadata inconsistencies worry you, ask the publisher to: (1) mark FMP_API_KEY as optional or required consistently, (2) fix the install 'bins' metadata, and (3) document exactly what data is sent to external APIs. If those are corrected, the package looks coherent for its stated purpose. Confidence notes: assessment is “suspicious” (medium confidence) because the functional code matches the description but metadata/instruction mismatches could lead to accidental credential exposure or user confusion; no evidence of malicious intent was found in the code itself.

📈 US Stock Analyzer - Three-Factor Buy Signal System

A comprehensive stock analysis system that combines Value Investing (DCF), Trend Trading (Livermore Rules), and Market Sentiment (VIX) to generate buy signals only when all three factors align.

Quick Start

# Install dependencies
pip3 install yfinance pandas numpy matplotlib pyyaml requests

# Set API key (optional, for enhanced financial data)
export FMP_API_KEY="your_key_here"

# Run analysis
python3 scripts/decision_engine.py AAPL

Three-Factor Framework

1️⃣ Value Factor (DCF) - 40% Weight

• Buy Condition: Price < Intrinsic Value × (1 - Margin of Safety)
• Key Metrics: Free Cash Flow, WACC, growth rates, ROE, debt levels
• Output: Value score 0-100, fair value estimate

2️⃣ Trend Factor (Livermore) - 35% Weight

• Buy Conditions:
  • Break above resistance with volume confirmation (1.5x avg)
  • Sector alignment (ETF in uptrend)
  • Price > MA20 > MA60
• Output: Trend score 0-100, key support/resistance levels

3️⃣ Sentiment Factor (VIX) - 25% Weight

• Buy Conditions:
  • VIX < 25 (non-panic)
  • VIX percentile < 70% (not expensive)
  • Market breadth positive (SPY uptrend)
• Output: Sentiment score 0-100, market regime

Final Buy Signal

BUY = Value ≥ 60 AND Trend ≥ 60 AND Sentiment ≥ 60 AND Composite ≥ 70

Usage

Basic Analysis

from scripts.decision_engine import StockAnalyzer

analyzer = StockAnalyzer(config_path="config.yaml")
result = analyzer.analyze("TSLA")
print(result['report'])

With Chart Output

analyzer.plot_analysis(result['result'], save_path="tsla_analysis.png")

Data Sources

Data	Source	Required
Price/Volume	Yahoo Finance (yfinance)	Free
Financials	FMP API	Optional (free tier)
VIX	CBOE via Yahoo	Free
Sector ETFs	Yahoo Finance	Free

Configuration

Edit config.yaml to customize:

• DCF discount rate (default: 10%)
• Margin of safety threshold (default: 20%)
• VIX panic threshold (default: 30)
• Factor weights
• Position sizing rules

Output

The system generates a formatted report including:

• Executive summary with composite score
• Individual factor scores with visual bars
• Buy/hold signal with confidence level
• Position sizing recommendation
• Target price and stop loss levels
• Risk assessment

File Structure

us-stock-analyzer/
├── SKILL.md                 # This file
├── config.yaml             # Configuration
├── requirements.txt        # Python dependencies
├── scripts/
│   ├── data_fetcher.py    # Data retrieval
│   ├── dcf_analyzer.py    # DCF valuation
│   ├── trend_analyzer.py  # Livermore trend analysis
│   ├── sentiment_analyzer.py # VIX sentiment
│   └── decision_engine.py # Three-factor engine
├── references/
│   └── methodology.md     # Detailed methodology
└── examples/
    └── sample_report.md   # Example output

Methodology

See references/methodology.md for:

• Detailed DCF calculation methodology
• Livermore trading rules implementation
• VIX sentiment scoring algorithm
• Position sizing formulas

Disclaimer

This tool is for informational purposes only and does not constitute investment advice. Always conduct your own research and consider consulting a financial advisor before making investment decisions.

License

MIT-0 (Public Domain)