Analysis modes

Copinance OS runs deterministic pipelines (fixed steps, structured JSON results) and question-driven flows (LLM selects tools that call providers and regime/macro tools). Modes are combined with timeframes and profiles (literacy) without mixing computation into the LLM layer—see Architecture.

Deterministic Instrument Analysis

Deterministic analysis follows a predefined pipeline with consistent steps.

Equity Analysis

What it does:

Fetches instrument information
Gets the current quote
Retrieves historical price data
Gets equity fundamentals
Calculates key metrics and trends
Generates a summary

Example:

# Run deterministic equity analysis (quote, history, fundamentals, summary)
copinance analyze equity AAPL --timeframe mid_term

Options Analysis

What it does:

Fetches the current underlying quote
Loads the option chain(s) for the selected expiration(s)—one chain per requested expiry, or the provider default when you omit expiries
Summarizes open interest, volume, and implied volatility (per expiry when multiple)
Highlights the at-the-money contract (per expiry when multiple)

Example:

# Run deterministic options analysis for a given expiration
copinance analyze options AAPL --expiration 2026-06-19
 
# Multiple expirations in one run
copinance analyze options AAPL -e 2026-06-19 -e 2026-09-18

Question-Driven Analysis

Question-driven analysis uses AI to dynamically analyze market instruments or the market based on your question. The model can call tools for quotes, historical data, options chains, fundamentals, SEC public filing data (when configured), regime signals, and macro indicators—outputs stay grounded in tool results.

The executor uses generate_with_tools (multi-turn tool loops inside one analysis). With --stream on copinance analyze … or copinance --stream "…", tokens are printed during each LLM turn; if a turn contains tool calls, a short notice is printed on stderr and the next round continues. For custom handlers, use LLMProvider.generate_text_stream or pass stream / on_llm_stream in job context—see Library — LLM text streaming.

Multi-turn user conversations (a follow-up question that should see prior Q&A) are supported only through the library: pass conversation_history on AnalyzeInstrumentRequest or AnalyzeMarketRequest, and use question for the new user message. After a successful run, results["conversation_turns"] lists the full transcript for chaining. The copinance CLI does not expose conversation state—neither analyze nor root copinance "…"—each invocation is one user question. Details: Library — Multi-turn question-driven analysis.

For example prompts (filings, comparisons, insiders, institutions), see CLI — Question-driven examples.

Equity:

# Question-driven equity analysis; AI uses tools to answer the question
copinance analyze equity AAPL --question "What are the key financial risks?"

Options: Ask about specific stock options data; use analyze options and optionally --expiration / -e (repeat per date for multiple expiries) and --side so the AI gets options context and can fetch the options chain.

# Question-driven options analysis (positioning, open interest, active calls)
copinance analyze options AAPL --question "How is the options chain positioned?"
copinance analyze options AAPL --question "What's the put/call open interest for AAPL?" --expiration 2026-06-19
copinance analyze options AAPL --question "What are the most active calls?" --side call

Market-wide:

# Question-driven macro analysis; AI uses macro and market tools
copinance analyze macro --question "What is the current market sentiment?" --market-index SPY

Root natural-language (no analyze subcommand): copinance "Your question" runs question-driven analysis with default macro-style market context and the full tool suite—see CLI — Natural language at the root.

See CLI Reference - Analyze for all options. Use --include-prompt to include the rendered prompts in saved results for question-driven runs.

Structured reports: When you use the library or orchestrator, RunJobResult.report is populated with an AnalysisReport (summary, key metrics, methodology, assumptions, limitations) for deterministic instrument/market runs and for question-driven runs, so outputs follow the same envelope across modes. For question-driven success paths, key_metrics may include iteration counts, LLM provider/model, tool-call counts, numeric-grounding policy, and partial-synthesis flags when the executor provides them. Use --json on the analyze group to print the full RunJobResult as JSON from the CLI (CLI — machine-readable output).

Timeframes

Both deterministic and question-driven analysis adapt to the timeframe:

Short-term

Focus: Recent price movements, short-dated options context, technical indicators
Data: Last 30 days

Mid-term

Focus: Quarterly fundamentals, price trends
Data: Last 6 months

Long-term

Focus: Annual fundamentals, long-term trends
Data: Last 2 years

One-off Execution

All analysis runs are one-off: copinance analyze runs analysis without persisting jobs. Each run saves results to .copinance/results/v2/ as versioned JSON envelopes. Profiles and cached tool data also live under versioned subdirectories in .copinance.

For all commands and options, see CLI Reference — Analyze.

Macro Regime Analysis

The macro regime analysis combines market regime indicators with macroeconomic data to provide a comprehensive view of market conditions.

Quick Start

# Run full macro/market regime analysis with defaults (SPY, 252-day lookback)
copinance analyze macro

Customization

# Custom index and lookback; exclude specific indicator groups
copinance analyze macro --market-index QQQ --lookback-days 90
copinance analyze macro --no-include-vix --no-include-market-breadth --no-include-sector-rotation

Data Sources

Macro indicators prefer FRED API when configured; fallback proxies use yfinance where needed.
Market regime indicators use yfinance. What gets fetched:
- Reference index (--market-index, e.g. SPY, QQQ, DIA): used for trend/volatility detection and as the “market” benchmark in sector comparison. Only this symbol changes when you change --market-index.
- VIX (^VIX) and the 11 S&P sector ETFs (XLK, XLE, XLI, XLV, XLF, XLP, XLY, XLU, XLB, XLC, XLRE): always fetched when VIX, market breadth, or sector rotation are enabled. They are the same for any --market-index.

Example: copinance analyze macro --market-index QQQ fetches QQQ (reference), all 11 sector ETFs, and VIX. See CLI Reference — Macro + Market Regime for more examples.

Next Steps

CLI Reference - Command details
Configuration — Setting up API keys

CLI Reference Overview