Jasper Finance

The terminal-native autonomous financial research agent.
Deterministic planning. Tool-grounded data. Reflection-driven recovery. Human-trustworthy answers.

🎯 Why Jasper?

Financial AI is often unreliable. Most tools produce confident-sounding answers that are frequently backed by hallucinations or missing data. Jasper takes a different approach: it treats every question as a mission.

Instead of just "chatting," Jasper follows a rigorous 5-stage pipeline:

Plan → Decomposes your question into structured research tasks with intent classification.
Execute → Fetches real-time data from authoritative APIs (Alpha Vantage, yfinance).
Reflect → Retries transient failures, degrades gracefully on permanent ones.
Validate → Analyzes data completeness and financial logic with partial-success support.
Synthesize → Generates a report with a confidence score and full audit trail.

Partial data? Jasper continues with caveats and a penalised confidence score — no silent hallucinations.

📝 What's New in v1.1.6

🔄 Hybrid Tier 1/Tier 2 Terminal Streaming Architecture

Tier 1 (Advanced Terminals): Windows Terminal, ConEmu, macOS, Linux continue using Rich Live widget with real-time streaming preview and persistent board updates.
Tier 2 (Basic Terminals): Plain PowerShell.exe now gets line-by-line event output without Live rendering artifacts, showing phases (PLANNING, EXECUTING, SYNTHESIS) with progress indicators.
Unified UX: All terminal types now provide real-time feedback with zero artifacts. Users get appropriate visual feedback for their environment.
Legacy Windows Mode: Console now uses Rich's legacy_windows parameter for plain PowerShell.exe, which handles ANSI codes differently to prevent rendering glitches.
Environment-Specific Rendering: Intelligently detects WT_SESSION (Windows Terminal), ConEmuPID (ConEmu), and TERM_PROGRAM (VS Code) to choose optimal rendering strategy.

📝 What's New in v1.1.4

🎨 Terminal Output Improvements

Fixed ANSI Escape Codes in VS Code Terminal: Rich's Live context manager was emitting ANSI escape codes that rendered as visible green lines in VS Code's integrated PowerShell terminal. Now intelligently detects TTY environments and disables Live rendering in non-TTY contexts (e.g., VS Code, IDEs) while preserving full UI in real terminals.
Proper Terminal Detection: Added sys.stdout.isatty() checks to determine if running in a real terminal. Fallback to plain output when not detected.
Null-Safe Live Updates: All Live.update() calls now safely check for None to prevent errors in non-Live modes.

📝 What's New in v1.1.3

🐛 Bug Fixes & Stability

Exception Hierarchy: Introduced a cohesive exception model with JasperError base class for all custom exceptions (EntityExtractionError, PlannerError, DataFetchError, ValidationError, ConfigurationError, SynthesisError). Enables precise error handling and recovery strategies.
Logger Output Control: Fixed logger to never print to stdout. All session events are now captured cleanly without terminal pollution. RichLogger correctly updates the Live panel instead.
Version Command: Now uses importlib.metadata instead of parsing pyproject.toml directly. Guarantees version consistency across all deployment methods (pip, Docker, executables).

✨ New Features & Enhancements

Balance Sheet Data: New balance_sheet tool now dispatched by executor. Fetch total assets, liabilities, equity, debt ratios alongside income statements for complete financial picture.
Cash Flow Statements: New cash_flow tool provides operating, investing, and financing cash flows. Critical for understanding liquidity and capital allocation.
Real-time Quotes: New realtime_quote tool fetches live price, market cap, P/E ratio, 52-week range, and trading volume. Always bypasses cache for latest data.
Async Provider Execution: Both YFinanceClient and AlphaVantageClient now properly use asyncio.run_in_executor() to prevent blocking the event loop. Non-blocking concurrent data fetches.
Smart Fallback Routing: FinancialDataRouter tries Alpha Vantage first, then seamlessly falls back to yfinance. Automatic .NS suffix retry for Indian stocks (e.g., plain RELIANCE → RELIANCE.NS).
In-Memory Response Caching: API responses cached in-memory with TTL (default 15 minutes, configurable via JASPER_CACHE_TTL_SECS). Saves quota on repeated queries. Real-time quotes always bypass cache.

🎯 Reliability & Recovery

Reflector Retry Loop: Post-execution reflector now intelligently retries transient failures (timeouts, rate limits, service unavailable) up to configurable max_retries times per task before gracefully skipping.
Partial-Success Validation: Validation gate now explicitly accepts ≥50% task completion rate. Synthesis proceeds with a confidence penalty and visible data-gap caveats. No more hard failures on partial data.
Validator Confidence Breakdown: Calculates transparency score as: data_coverage × data_quality × inference_strength. Penalises missing data automatically.
Task Error Tracking: All task failures now logged with detailed error messages. Audit trail clearly shows which data sources succeeded/failed.

🎨 UI & Export Improvements

Conditional PDF Status Badges: PDF report now uses Jinja2 conditionals to dynamically render status badges based on actual data retrieval results. No more hardcoded "SUCCESS" labels when data is missing.
PDF Context Truncation: Long synthesis contexts (>10K chars) automatically truncated with a truncation note appended. Prevents LLM context overflow and keeps reports concise.
Cross-Process Report Persistence: Research reports now automatically persisted to disk as JSON cache. _load_report_from_disk() enables session continuity and easy re-export.
Live Streaming Synthesis: Real-time Rich Live panel updates during synthesis. No blank screens while LLM generates responses.

🐍 Developer Experience

Public Python API: New run_research() async function and FinalReport Pydantic model exported from jasper package. Use Jasper programmatically in notebooks, FastAPI routes, or CI pipelines.
Detailed Docstrings: All agent classes (Planner, Executor, Reflector, Synthesizer, Validator) now have comprehensive docstrings explaining intent, parameters, and return values.
Demo Mode Warning: When using demo Alpha Vantage key, explicit warning message mentions "IBM" to alert users that demo responses are dummy data, not real market information.

🔧 Internal Improvements

Entity Extractor: Improved ticker/company name extraction from complex queries. Better handling of multi-company comparisons.
Context Window Management: Synthesizer now actively manages context window size to avoid exceeding LLM limits. Graceful truncation with notes.
Executor Task Dispatching: Unified task dispatch logic. Supports income_statement, balance_sheet, cash_flow, realtime_quote, financial_statement (alias), and key_metrics tools.

📊 Data Provider Enhancements

Alpha Vantage: Now properly parses and surfaces both annual and quarterly reports. Better error messages for rate-limited responses and missing data.
yfinance: Eliminated use of deprecated quarterly_financials attribute. Uses modern quarterly_income_stmt API exclusively.
Provider Abstraction: Providers without requested method (e.g., missing balance_sheet) silently skipped instead of erroring out.

🧪 Testing

16 new comprehensive test suites covering all critical fixes.
Full round-trip testing for report save/load persistence.
Async provider mocking with proper executor simulation.
Conditional template rendering validation via CSS class detection.

✨ Key Features

🧠 Autonomous Planning: Automatically breaks down complex questions into executable sub-tasks with query-intent classification (quantitative / qualitative / mixed).
⚙️ Tool-Grounded Data: Income statements, balance sheets, cash flow, and real-time quotes via Alpha Vantage and yfinance. Supports US and Indian (NSE .NS) stocks.
🔄 Reflector Agent: Post-execution recovery loop that retries transient network/rate-limit failures up to max_retries times per task before gracefully skipping.
✅ Partial-Success Validation: If ≥ 50 % of tasks complete, synthesis proceeds with a confidence penalty and a visible data-gap caveat instead of hard-failing.
📊 Confidence Breakdown: Transparent data_coverage × data_quality × inference_strength scoring per report.
⚡ LLM Streaming: Synthesis tokens stream to the terminal in real-time via a Rich Live panel — no more blank screens.
💬 Session Memory: Interactive mode carries the last 3 Q&A pairs as context so follow-up questions work naturally.
🌐 Qualitative Queries: Questions without a ticker (e.g. "Explain yield curve inversion") are answered directly from LLM domain knowledge.
🗄️ TTL Response Cache: API responses are cached in-memory for 15 minutes (configurable via JASPER_CACHE_TTL_SECS) to save Alpha Vantage quota. Real-time quotes always bypass the cache.
🐍 Public Python API: Use Jasper programmatically in notebooks, web APIs, or CI pipelines via from jasper import run_research.
📄 PDF & HTML Export: Professional research reports with timestamped unique filenames and persistent JSON cache across sessions.
🎨 Rich Terminal UI: Live progress boards, tree views, and structured reports.

🚀 Installation

Option 1: Python pip (All Platforms)

pip install jasper-finance
jasper interactive

Option 2: Pre-Built Executable

No Python needed. Everything bundled including PDF renderer.

Windows:

git clone https://github.com/ApexYash11/jasper.git
cd jasper
.\scripts\build.ps1
.\dist\jasper\jasper.exe interactive

Linux/macOS:

git clone https://github.com/ApexYash11/jasper.git
cd jasper
chmod +x scripts/build.sh && ./scripts/build.sh
./dist/jasper/jasper interactive

Option 3: Docker (Production)

docker build -t jasper-finance:1.1.6 .
docker run -it jasper-finance:1.1.6 interactive

🖥️ Platform-Specific Setup with Conda

Using Conda ensures isolated environments and avoids dependency conflicts.

macOS

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install system dependencies
brew install miniforge pkg-config cairo

# Initialize Conda
conda init zsh
source ~/.zshrc

# Create and activate environment
conda create -n jasper python=3.11 -y
conda activate jasper

# Install Jasper
pip install jasper-finance

Linux (Ubuntu/Debian)

# Install system dependencies
sudo apt update
sudo apt install -y pkg-config libcairo2-dev

# Install Miniforge
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh -b
~/miniforge3/bin/conda init bash
source ~/.bashrc

# Create and activate environment
conda create -n jasper python=3.11 -y
conda activate jasper

# Install Jasper
pip install jasper-finance

Windows

# Install Miniforge from: https://github.com/conda-forge/miniforge/releases
# Run the installer, then open Miniforge Prompt

# Create and activate environment
conda create -n jasper python=3.11 -y
conda activate jasper

# Install Jasper
pip install jasper-finance

Daily Usage (All Platforms)

# Activate environment
conda activate jasper

# Run Jasper
jasper interactive

# Deactivate when done
conda deactivate

🛠️ Setup (2 Minutes)

Step 1: Get API Keys

You need two free API keys:

API	Purpose	Get Key
OpenRouter	LLM synthesis & planning	openrouter.ai/keys
Alpha Vantage	Financial data (statements)	alphavantage.co/support (free)

Step 2: Configure Environment

macOS/Linux:

export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxx"
export ALPHA_VANTAGE_API_KEY="your-alpha-vantage-key"

To make permanent, add to ~/.zshrc (macOS) or ~/.bashrc (Linux).

Windows PowerShell:

$env:OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxx"
$env:ALPHA_VANTAGE_API_KEY="your-key"

Or use a .env file in your working directory:

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxx
ALPHA_VANTAGE_API_KEY=your-alpha-vantage-key

Step 3: (Optional) Choose a Model

Jasper defaults to stepfun/step-3.5-flash:free via OpenRouter. Override with:

export OPENROUTER_MODEL="openai/gpt-4o-mini"   # recommended for production
export OPENROUTER_MODEL="anthropic/claude-haiku-20240307"

Step 4: Verify Setup

jasper doctor

Expected output:

✅ OPENROUTER_API_KEY is set
✅ ALPHA_VANTAGE_API_KEY is set
✅ Python 3.9+ installed
✅ All dependencies available

📖 Quick Start

Single Query (One-off Research)

jasper ask "What is Nvidia's revenue trend over the last 3 years?"

Interactive Mode (Multiple Queries with Session Memory)

jasper interactive

Session memory is automatic — follow-up questions like "and what about their cash flow?" retain context from the previous 3 exchanges.

Qualitative / Macro Queries (No Ticker Required)

jasper ask "Explain yield curve inversion and its impact on equities"
jasper ask "What is quantitative tightening?"

Indian & International Stocks

jasper ask "What is Reliance Industries revenue trend?"   # auto-resolves RELIANCE.NS
jasper ask "Analyze Infosys operating margins"            # INFY.NS
jasper ask "Compare HDFC Bank and ICICI Bank"             # HDFCBANK.NS, ICICIBANK.NS

Export to PDF

jasper export "Analyze Tesla's operating margins"
# Saves as: exports/jasper_report_20260222_143012.pdf  (unique per run)

🐍 Python API

Use Jasper programmatically in notebooks, FastAPI routes, or CI pipelines:

import asyncio
from jasper import run_research, FinalReport

report: FinalReport | None = asyncio.run(
    run_research("What is Apple's revenue trend over the last 3 years?")
)

if report:
    print(report.synthesis_text)
    print(f"Confidence: {report.confidence_score:.0%}")
    print(f"Tickers analysed: {report.tickers}")
    print(f"Data sources: {report.data_sources}")

run_research() returns a fully populated FinalReport Pydantic model or None if the pipeline failed.

🏗️ How It Works (Architecture)

┌─────────────────────────────────────────────────────────┐
│                    YOUR QUESTION                         │
│          "What is Apple's revenue trend?"                │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
        ┌────────────────────────┐
        │   1️⃣ PLANNER AGENT     │
        │ Intent classification   │
        │ (quant / qual / mixed)  │
        │ Task decomposition      │
        └────────────┬────────────┘
                     │
                     ▼
        ┌────────────────────────┐
        │ 2️⃣ EXECUTION ENGINE    │
        │  Income statement       │
        │  Balance sheet          │
        │  Cash flow              │
        │  Real-time quote        │
        │  (Alpha Vantage + yf)   │
        └────────────┬────────────┘
                     │
                     ▼
        ┌────────────────────────┐
        │   3️⃣ REFLECTOR         │
        │ Retry transient errors  │
        │ Degrade on permanent    │
        │  ones gracefully        │
        └────────────┬────────────┘
                     │
                     ▼
        ┌────────────────────────┐
        │ 4️⃣ VALIDATION GATE     │
        │ ≥50% tasks → partial ✅ │
        │ <50% tasks → fail ❌    │
        │ Confidence breakdown    │
        └────┬───────────┬────────┘
             │           │
          ✅ PASS    ❌ FAIL
             │           │
             ▼           ▼
      ┌─────────────┐  Research Failed
      │ 5️⃣ SYNTHESIZE│  (partial data
      │  (streaming) │   reported)
      └──────┬──────┘
             │
             ▼
    ┌─────────────────────┐
    │   FINAL REPORT      │
    │  + Confidence Score │
    │  + Audit Trail      │
    └─────────────────────┘

🔧 All Commands

Command	What It Does
`jasper ask "question"`	Execute a single research mission
`jasper interactive`	Enter multi-query mode with session memory
`jasper export <query>`	Generate research and export as PDF report
`jasper doctor`	Verify API keys and setup
`jasper version`	Show installed version
`jasper --help`	View all commands

📊 Available Data Tools

Tool	Description	Providers
`income_statement`	Annual + quarterly P&L (revenue, EBIT, net income)	Alpha Vantage, yfinance
`balance_sheet`	Assets, liabilities, equity, debt ratios	Alpha Vantage, yfinance
`cash_flow`	Operating / investing / financing cash flows	Alpha Vantage, yfinance
`realtime_quote`	Live price, market cap, P/E, 52-week range, volume	yfinance (always fresh)
`key_metrics`	EV/EBITDA, ROE, ROA, margins, growth rates	yfinance

Alpha Vantage is tried first; yfinance is the automatic fallback. Both providers support US and Indian NSE stocks (.NS suffix).

⚙️ Environment Variables

Variable	Default	Description
`OPENROUTER_API_KEY`	(required)	Your OpenRouter API key
`ALPHA_VANTAGE_API_KEY`	`demo`	Alpha Vantage key (demo = IBM only)
`OPENROUTER_MODEL`	`google/gemini-2.0-flash-exp:free`	LLM model override
`JASPER_CACHE_TTL_SECS`	`900`	API response cache TTL in seconds

❓ Troubleshooting

Problem	Solution
`Research Failed`	By design. Check validation issues. Usually incomplete data or invalid ticker.
`Partial data — confidence penalised`	Normal for rate-limited sessions. Report still generated with caveats.
`API Rate Limit Hit`	Free Alpha Vantage: ~25 calls/day. Jasper's TTL cache reduces redundant calls.
`API KEY not set`	Run `jasper doctor` and export missing keys.
`Ticker not found`	Use symbol (AAPL), not name (Apple). Indian: add `.NS` suffix (RELIANCE.NS).
`pycairo build fails`	Install Cairo: `brew install cairo` (macOS) or `sudo apt install libcairo2-dev` (Linux).
`nan in report output`	Fixed in v1.0.9 — upgrade with `pip install --upgrade jasper-finance`.

⚖️ License

Jasper Finance is released under the MIT License (2026, ApexYash).

✅ Commercial Use
✅ Modification
✅ Distribution
✅ Private Use
⚠️ No Warranty

See LICENSE for full legal text.

🔗 Links

Resource	Link
📦 PyPI Package	pypi.org/project/jasper-finance/
💻 GitHub Source	github.com/ApexYash11/jasper
🐛 Report Issues	github.com/ApexYash11/jasper/issues
📊 Data: Alpha Vantage	alphavantage.co
📈 Data: yfinance	github.com/ranaroussi/yfinance
🤖 LLM: OpenRouter	openrouter.ai

Built by analysts, for analysts. Stop guessing. Start researching. Jasper Finance v1.1.6

Name		Name	Last commit message	Last commit date
Latest commit History 80 Commits
.github/workflows		.github/workflows
assests		assests
config		config
dist		dist
docs		docs
jasper		jasper
jasper_finance.egg-info		jasper_finance.egg-info
scripts		scripts
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
TEST_PLAN_v1.1.5.md		TEST_PLAN_v1.1.5.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini

Folders and files

Latest commit

History

Repository files navigation

Jasper Finance

🎯 Why Jasper?

📝 What's New in v1.1.6

🔄 Hybrid Tier 1/Tier 2 Terminal Streaming Architecture

📝 What's New in v1.1.4

🎨 Terminal Output Improvements

📝 What's New in v1.1.3

🐛 Bug Fixes & Stability

✨ New Features & Enhancements

🎯 Reliability & Recovery

🎨 UI & Export Improvements

🐍 Developer Experience

🔧 Internal Improvements

📊 Data Provider Enhancements

🧪 Testing

✨ Key Features

🚀 Installation

Option 1: Python pip (All Platforms)

Option 2: Pre-Built Executable

Option 3: Docker (Production)

🖥️ Platform-Specific Setup with Conda

macOS

Linux (Ubuntu/Debian)

Windows

Daily Usage (All Platforms)

🛠️ Setup (2 Minutes)

Step 1: Get API Keys

Step 2: Configure Environment

Step 3: (Optional) Choose a Model

Step 4: Verify Setup

📖 Quick Start

Single Query (One-off Research)

Interactive Mode (Multiple Queries with Session Memory)

Qualitative / Macro Queries (No Ticker Required)

Indian & International Stocks

Export to PDF

🐍 Python API

🏗️ How It Works (Architecture)

🔧 All Commands

📊 Available Data Tools

⚙️ Environment Variables

❓ Troubleshooting

⚖️ License

🔗 Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages