Workflows

Copinance OS supports multiple types of workflows for stock research.

Static Workflows

Static workflows follow a predefined analysis pipeline with consistent steps.

What It Does

Fetches stock information
Gets current market quote
Retrieves historical price data (timeframe-dependent)
Gets fundamental data
Calculates key metrics and trends
Generates analysis summary

When to Use

✅ Consistent, repeatable analysis
✅ No API key required
✅ Fast execution
✅ Comprehensive coverage

Example

copinance analyze stock AAPL --timeframe mid_term

Agentic Workflows

Agentic workflows use AI to dynamically analyze stocks based on your questions.

What It Does

Understands your question
Selects appropriate tools (data providers)
Gathers relevant data
Analyzes and synthesizes information
Provides tailored answer adapted to your financial literacy level

When to Use

✅ Custom questions and analysis
✅ Adaptive to specific needs
✅ Natural language interaction
✅ Personalized responses based on financial literacy level
⚠️ Requires Gemini API key

Example

copinance ask "What are the key financial risks?" --symbol AAPL

Setup Required

See Configuration for setting up Gemini API key.

Timeframes

Both workflow types adapt to the timeframe:

Short-term

Focus: Recent price movements, technical indicators
Data: Last 30 days, daily intervals
Use case: Trading decisions

Mid-term

Focus: Quarterly fundamentals, price trends
Data: Last 6 months, daily intervals
Use case: Swing trading

Long-term

Focus: Annual fundamentals, long-term trends
Data: Last 2 years, weekly intervals
Use case: Investment decisions

Fundamentals Workflows

Fundamentals workflows focus specifically on fundamental analysis and financial metrics.

What It Does

Retrieves comprehensive fundamental data
Analyzes financial statements
Calculates key financial ratios
Provides fundamental metrics and trends

When to Use

✅ Deep fundamental analysis
✅ Financial statement review
✅ Ratio analysis
✅ No API key required

Example

copinance analyze stock AAPL --timeframe long_term

Choosing a Workflow

Use Static if:

You want consistent, comprehensive analysis
You don’t have an API key
You need fast results

Use Agentic if:

You have specific questions
You want adaptive analysis
You have an API key configured

Use Fundamentals if:

You need detailed financial analysis
You want to focus on financial statements and ratios
You don’t need AI-powered insights

One-off Execution

All workflow runs are one-off: copinance analyze and copinance ask run workflows without persisting jobs. Each run saves results to .copinance/results/ as JSON. Profiles and cached tool data also live under .copinance. Use copinance cache clear to clear cached tool data.

Example Workflows

# Stock analysis (one-off)
copinance analyze stock AAPL --timeframe mid_term
 
# Macro regime (one-off)
copinance analyze macro --market-index SPY
 
# Agentic Q&A (one-off)
copinance ask "What are the key risks?" --symbol AAPL

Macro Regime Workflow

The macro regime workflow combines market regime indicators with macroeconomic data to provide a comprehensive view of market conditions. Use the dedicated CLI command for easy access.

Quick Start

# Full analysis with defaults
copinance analyze macro

Customization

Market Index: Choose which market index to analyze:

copinance analyze macro --market-index SPY    # S&P 500 (default)
copinance analyze macro --market-index QQQ    # Nasdaq 100
copinance analyze macro --market-index DIA    # Dow Jones
copinance analyze macro --market-index IWM    # Russell 2000

Lookback Period: Adjust the analysis window:

copinance analyze macro --lookback-days 90    # 3 months
copinance analyze macro --lookback-days 252   # 1 year (default)
copinance analyze macro --lookback-days 504   # 2 years

Indicator Selection: All indicator groups are on by default. Use --no-include-<name> to exclude any category. Available: vix, market-breadth, sector-rotation, rates, credit, commodities, labor, housing, manufacturing, consumer, global, advanced.

# Macro-only: exclude market/volatility/sector to focus on economic indicators
copinance analyze macro \
  --no-include-vix \
  --no-include-market-breadth \
  --no-include-sector-rotation
 
# Only market regime indicators (exclude macro categories)
copinance analyze macro \
  --no-include-rates \
  --no-include-credit \
  --no-include-commodities

What It Analyzes

Market Regime Indicators:

VIX: Volatility index measuring market fear
Market Breadth: Advancing vs declining stocks
Sector Rotation: Which sectors are leading/lagging

Macro Indicators:

Rates: 10Y Treasury yields, yield curve analysis
Credit: Credit spreads (HYG, LQD)
Commodities: Energy prices (oil, natural gas)
Labor, Housing, Manufacturing, Consumer, Global: Employment, housing, PMI, consumer sentiment, and global indicators (when enabled)
Advanced: Leading Economic Index (LEI), Federal Reserve balance sheet, and CDS proxies (HYG, LQD) for credit risk—uses FRED when available, else yfinance

Data Sources:

Macro indicators prefer FRED API (if COPINANCEOS_FRED_API_KEY configured) for true yields/spreads
Falls back to yfinance proxies if FRED unavailable
Market regime indicators use yfinance

Use Cases

Market Regime Detection: Identify bull/bear markets, volatility regimes
Macro Environment: Understand interest rate environment, credit conditions
Sector Analysis: See which sectors are rotating in/out of favor
Risk Assessment: Combine volatility (VIX) with credit spreads for risk-on/risk-off signals

Examples

# Quick market check
copinance analyze macro --lookback-days 90
 
# Deep dive on Nasdaq
copinance analyze macro --market-index QQQ --lookback-days 504
 
# Focus on macro conditions
copinance analyze macro \
  --no-include-vix \
  --no-include-market-breadth \
  --no-include-sector-rotation

Next Steps

CLI Reference - Command details
Configuration - Setting up API keys

CLI Reference Configuration