Pipeline Components

This document provides detailed information about each component of the Pure Python Pipeline.

Portfolio Deep Analyzer

Overview

The Portfolio Deep Analyzer (portfolio_deep_analyzer.py) replaces AI-based DeepAnalysisCrew with fast, deterministic Python calculations.

Key Features

• Pure Python Scoring: Uses DeepAnalysisScorer for deterministic calculations
• Real Market Data: Fetches actual data via QuantitativeAnalysisTool
• JSON Export Generation: Creates standardized exports for downstream systems
• HTML Report Generation: Uses Jinja2 templates for individual holding reports
• Score Uniqueness Validation: Prevents hardcoded defaults

Performance Characteristics

• Execution Time: < 1 second per holding
• LLM Calls: 0
• Cost: $0.00
• Memory Usage: < 50 MB for typical portfolios

Usage Example

Python

from finwiz.scoring.portfolio_deep_analyzer import analyze_portfolio_with_python

results = analyze_portfolio_with_python(
    holdings=portfolio_holdings,
    session_id="analysis_session_123"
)

# Access results
print(f"Successful: {results['successful_analyses']}")
print(f"Failed: {results['failed_analyses']}")
print(f"Time: {results['performance_metrics']['total_execution_time_seconds']:.2f}s")

Output Structure

The analyzer generates:

1. Individual JSON exports: output/{asset_class}/{ticker}_{session_id}.json
2. Individual HTML reports: output/{asset_class}/{ticker}_{session_id}.html
3. Consolidated export: output/deep_analysis_consolidated_{session_id}.json

View JSON export structure →

A+ Discovery Integrator

Overview

The A+ Discovery Integrator (aplus_discovery_integrator.py) identifies A+ opportunities from deep analysis results by reading JSON exports.

Key Features

• Directory Scanning: Scans output/stock/, output/etf/, output/crypto/
• Grade Filtering: Identifies A+ and A grade holdings
• Cross-Asset Consolidation: Consolidates opportunities across asset classes
• Duplicate Removal: Ensures unique ticker list

Data Flow

Text Only

output/stock/*.json  ─┐
output/etf/*.json    ─┼─> A+ Discovery Integration ─> Opportunities List
output/crypto/*.json ─┘

Usage Example

Python

from finwiz.integration.aplus_discovery_integrator import integrate_aplus_discovery_with_deep_analysis

discovery_results = integrate_aplus_discovery_with_deep_analysis(
    session_id="analysis_session_123"
)

if discovery_results["has_a_plus_analysis"]:
    print(f"Found {discovery_results['total_opportunities_found']} opportunities")
    for holding in discovery_results["aplus_holdings"]:
        print(f"  {holding['ticker']}: Grade {holding['grade']}")

Output Structure

Generates output/aplus_discovery_{session_id}.json containing:

• has_a_plus_analysis: Boolean indicating if opportunities exist
• total_opportunities_found: Count of A+ opportunities
• aplus_holdings: List of opportunity details
• total_analyzed: Total holdings analyzed
• integration_timestamp: ISO timestamp

View discovery results structure →

Backtesting Pipeline Connector

Overview

The Backtesting Pipeline Connector (backtesting_pipeline_connector.py) automatically executes backtesting when A+ candidates are available.

Key Features

• Automatic Candidate Detection: Reads A+ candidates from discovery results
• Backtesting Execution: Executes strategy for each candidate
• Performance Metrics: Calculates comprehensive metrics
• JSON Export: Saves results for report integration

Performance Metrics

The connector calculates:

• Annual Return: Annualized return percentage
• Sharpe Ratio: Risk-adjusted return metric
• Maximum Drawdown: Peak-to-trough decline
• Win Rate: Percentage of winning trades
• Backtest Period: Time period tested

Usage Example

Python

from finwiz.integration.backtesting_pipeline_connector import connect_backtesting_to_discovery_results

backtesting_results = connect_backtesting_to_discovery_results(
    session_id="analysis_session_123"
)

if backtesting_results["backtesting_executed"]:
    print(f"Backtested {backtesting_results['candidates_count']} candidates")
    for result in backtesting_results["results"]:
        print(f"  {result['ticker']}: {result['annual_return']:.1%} return")

Output Structure

Generates output/backtesting_results_{session_id}.json containing:

• backtesting_executed: Boolean indicating execution status
• candidates_count: Number of candidates tested
• candidates: List of candidate details
• results: List of backtesting results with metrics
• execution_time_seconds: Total execution time

View backtesting results structure →

Python Report Generator

Overview

The Python Report Generator (python_report_generator.py) generates comprehensive HTML reports using Jinja2 templates without any AI calls.

Key Features

• Template-Based Generation: Uses Jinja2 for consistent formatting
• Portfolio Statistics: Calculates comprehensive statistics
• Holdings Analysis: Detailed analysis with grades and scores
• Deep Analysis Integration: Incorporates deep analysis results
• Performance Metrics: Displays execution metrics
• Responsive Design: Light/dark mode CSS styling

Report Sections

1. Executive Summary
2. Portfolio grade and score
3. Total holdings and opportunities

4. Key statistics

5. Portfolio Overview

6. Asset class distribution
7. Grade distribution

8. Recommendation breakdown

9. Holdings Analysis

10. Detailed holding information
11. Grades and scores

12. Recommendations and rationale

13. Strategic Recommendations

14. Priority actions
15. Optimization suggestions

16. Python pipeline benefits

17. Deep Analysis Results

18. Analysis success metrics
19. Detailed scores

20. Component breakdowns

21. Performance Metrics

22. Execution time
23. Cost savings
24. Efficiency metrics

Usage Example

Python

from finwiz.reporting.python_report_generator import generate_python_report

report_path = generate_python_report(
    portfolio_review=portfolio_review,
    deep_analysis_results=analysis_results,
    session_id="analysis_session_123"
)

print(f"Report generated: {report_path}")

Output

Generates output/finwiz_family_financial_plan.html with:

• Professional HTML structure
• Responsive CSS styling
• Complete portfolio analysis
• Deep analysis integration
• Performance metrics

Component Integration

Sequential Execution

Components execute in sequence:

Text Only

1. Portfolio Deep Analyzer
   ↓ (generates JSON exports)
2. A+ Discovery Integrator
   ↓ (identifies opportunities)
3. Backtesting Pipeline Connector
   ↓ (validates candidates)
4. Python Report Generator
   ↓ (consolidates results)
Final HTML Report

Data Dependencies

• A+ Discovery depends on Deep Analysis JSON exports
• Backtesting depends on A+ Discovery results
• Report Generator depends on all previous components

Error Handling

Each component implements graceful error handling:

• Deep Analyzer: Continues with remaining holdings if one fails
• A+ Discovery: Returns empty results if no exports found
• Backtesting: Skips execution if no candidates available
• Report Generator: Generates report even with partial data

Performance Optimization

Parallel Processing

• Deep Analyzer processes holdings sequentially (data fetching is I/O bound)
• JSON exports are written asynchronously
• HTML generation uses template caching

Memory Management

• Streaming JSON parsing for large files
• Incremental report generation
• Automatic cleanup of temporary data

Caching Strategy

• Market data cached per session
• Template compilation cached
• Analysis results cached in JSON

Related Documentation

• Data Flow - Complete data flow architecture
• JSON Exports - Export structure specifications
• API Reference - Complete API documentation
• How-to Guide - Usage instructions