Initial commit for Folio project

.dockerignore

@@ -0,0 +1,50 @@
+# Version control
+.git
+.gitignore
+
+# Python cache files
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtual environment
+venv/
+env/
+ENV/
+
+# IDE files
+.vscode/
+.idea/
+
+# Logs
+logs/
+*.log
+
+# Cache directories
+.cache*/
+.tmp/
+
+# Local data
+data/
+*.csv
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Docker files (not needed in build context)
+Dockerfile.dev
+docker-compose.dev.yml
+
+# Documentation
+# Keep docs/ for Hugging Face deployment
+# docs/
+*.md
+!README.md
+
+# personal notes
+-executive.md

.env.example

@@ -0,0 +1,15 @@
+# Environment variables for the Folio application
+
+# API Keys
+# FMP (FinancialModelingPrep) API - not required when using yfinance:
+FMP_API_KEY=your_fmp_api_key_here
+
+# Used for portfolio analysis premium feature
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Application Settings
+PORT=8050
+DEBUG=false
+
+# Data Source Configuration
+DATA_SOURCE=yfinance

.gitattributes

@@ -0,0 +1 @@
+*.pkl filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,84 @@
+# Python virtual environments
+venv/
+env/
+ENV/
+.env
+
+# Cache directories
+.cache*/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS specific files
+.DS_Store
+Thumbs.db
+
+# Log files
+*.log
+logs/**
+mlruns/**
+
+# Local configuration
+.env*
+!.env.example
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Model files (optional, uncomment if you want to ignore model files)
+# models/*.pkl
+
+# Data files (optional, uncomment if you want to ignore data files)
+# data/
+
+# Test coverage
+.coverage
+htmlcov/
+coverage.xml
+.coverage.*
+
+# this is where we store the models
+models/
+.archive/
+
+# Temporary files
+.tmp/
+*.tmp
+*~
+*.bak
+
+# Lab private files
+src/lab/portfolio.csv
+**/portfolio.csv  # Ignore any portfolio.csv files in any directory
+
+# augment specific
+.augment/
+
+# latest AI generated commit message here
+.commit-msg.md
+
+# Personal notes file
+.executive.md
+private-data/*
+
+# Documentation folder (temporary exclusion)
+docs/

.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.4
+    hooks:
+      - id: ruff
+        args: [--fix, --unsafe-fixes]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-toml
+      - id: check-json
+      - id: debug-statements
+      - id: check-merge-conflict
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.28.0
+    hooks:
+      - id: check-github-workflows
+        args: ["--verbose"]
+
+  - repo: https://github.com/python-poetry/poetry
+    rev: 1.8.2
+    hooks:
+      - id: poetry-check
+        stages: [commit]
+        files: ^pyproject.toml$

BEST-PRACTICES.md

@@ -0,0 +1,249 @@
+# Best Practices for Folio Project
+
+This document is the single source of truth for the Folio project's best practices. Keep it updated as new best practices emerge.
+
+---
+
+# 📋 CORE TENETS
+0. NO FAKE DATA + FAIL FAST: if we hide errors by giving default or fake data, it could mislead hedge fund clients and cost tons of $$$. Stop using default values and fake data when handling errors. FAIL FAST and transparently when the app fails.
+1. **SIMPLICITY** - Prefer simple, focused solutions over complex ones. Question every bit of added complexity.
+2. **PRECISION** - Make the smallest necessary changes. Don't modify unrelated code or remove what you don't understand.
+3. **RELIABILITY** - Debug thoroughly and test rigorously. AVOID SWALLOW EXCEPTIONS or hiding errors
+4. **USABILITY** - Prioritize user experience. Design for clarity and ease of use, not technical elegance alone.
+5. **SAFETY** - Never modify Git history or hide Git commands in scripts. All version control operations must be explicit, visible, and performed manually by the user.
+
+---
+
+## Key Principles
+*When in doubt, follow the CORE TENETS above.*
+This section adds specific guidelines for various aspects of the project.
+
+### � Development Workflow
+*Supports PRECISION and SIMPLICITY*
+Follow consistent development practices to maintain code quality and developer productivity.
+
+- **Code Changes**:
+  - **Incremental Changes**: Make small, focused changes rather than large rewrites
+  - **Performance**: Optimize only after identifying actual bottlenecks
+
+- **File Management**:
+  - **Version Control**: Update .gitignore for new temporary files or directories
+  - **Temporary Files**: Store temporary files in the `.tmp` directory
+  - **Cache Files**: Use hidden directories (`.cache_*`) for cache files
+
+- **Version Control**:
+  - **Never Commit Directly**: Let the user handle all git operations
+  - **⚠️ NEVER USE GIT IN SCRIPTS**: Do not write scripts that use git commands - this can lead to catastrophic data loss and irreversible history modification
+  - **Manual Git Operations**: All git operations must be performed manually by the user, never automated
+  - **NEVER CREATE PRs WITHOUT BEING ASKED**: Do not create pull requests unless explicitly requested by the user
+  - **Preserve Git History**: Never modify Git history without explicit user consent and understanding of the consequences
+  - **Transparent Operations**: All version control suggestions must be explicit, visible, and explained clearly
+  - **Preferred Diff Tool**: Use `git aidiff` for code reviews with AI agents - this outputs complete diffs without requiring scrolling
+    - If not available, set up with: `git config --global alias.aidiff "!git --no-pager diff --unified=3 --color=never"`
+    - This produces AI-friendly output that shows the entire diff at once
+
+- **Commit Messages**:
+  - **Delivery Format**: When asked to write a commit message, provide it directly as a markdown code block (```...```) in the chat, not as a separate file
+  - **Conventional Format**: Follow the conventional commits format with a type prefix
+  - **Message Structure**: Use a concise title (50 chars max) followed by a blank line and then a detailed body
+  - **Title Format**: `<type>: <concise description in imperative mood>`
+    - **Types in Priority Order**: Always use the highest impact prefix when multiple types apply
+      1. `feat`: New features or significant enhancements (highest priority)
+      2. `fix`: Bug fixes or correcting errors
+      3. `security`: Security-related changes
+      4. `perf`: Performance improvements
+      5. `refactor`: Code restructuring without changing functionality
+      6. `test`: Adding or modifying tests
+      7. `docs`: Documentation updates only
+      8. `style`: Formatting, white-space, etc. (no code change)
+      9. `build`: Build system or external dependency changes
+      10. `ci`: CI configuration changes
+      11. `chore`: Maintenance tasks, no production code change (lowest priority)
+    - **Examples**:
+      - `feat: add user authentication system`
+      - `fix: resolve database connection timeout issue`
+      - `docs: update deployment instructions`
+  - **Title Guidelines**:
+    - Use imperative mood ("Add feature" not "Added feature")
+    - Capitalize the first word after the type prefix
+    - Don't end with a period
+    - Keep under 50 characters
+    - Be specific about what changed
+  - **Body Guidelines**:
+    - Explain the "what" and "why" of the change, not the "how"
+    - Wrap text at 72 characters
+    - Use bullet points for multiple points
+    - Reference issues or tickets where applicable
+    - Don't use phrases like "This commit..."
+
+### �💻 Implementation
+*Supports SIMPLICITY and RELIABILITY*
+Write code that is clear, maintainable, and robust against edge cases.
+
+- **Code Style**:
+  - **Imports at Top**: ALWAYS place all imports at the top of the file, never in the middle or at the bottom
+  - **Avoid Hardcoding**: Use pattern-based detection instead of hardcoding specific values
+  - **Generic Solutions**: Prefer solutions that work for all cases over special-case handling
+  - **Readability**: Prioritize readable code over clever optimizations
+  - **Code Quality**: Run `make lint` regularly to identify and fix code quality issues
+  - **Unused Code**: Avoid unused imports, functions, and variables; prefix intentionally unused variables with underscore
+  - **Clean Code**: Remove commented-out code and fix exception handling issues
+
+- **Configuration**:
+  - **External Config**: Use configuration files for values that might change
+  - **Sensible Defaults**: Provide reasonable defaults for all configurable options
+  - **Validate Inputs**: Check and validate all external inputs and configuration
+
+- **Framework-Specific Patterns**:
+  - **Dash Callback Registration**: Always register callbacks in a centralized location in the app creation process
+  - **Explicit Registration**: Never rely on side effects of imports for critical functionality like callback registration
+  - **Avoid Duplicate Registration**: Be careful about registering callbacks multiple times, which can cause conflicts
+  - **Component Documentation**: Document the relationship between components and their callbacks
+
+- **Dependency Management**:
+  - **Update Requirements**: ALWAYS update `requirements.txt` when adding new imports or dependencies
+  - **Deployment Verification**: Test deployments after adding new dependencies to ensure they work in all environments
+  - **Minimal Dependencies**: Only add dependencies that are absolutely necessary
+  - **Version Pinning**: Pin versions for stability (`==`) or use minimum version constraints (`>=`) as appropriate
+  - **Document Dependencies**: Add comments explaining what each dependency is used for
+  - **Check Imports**: Regularly audit imports to ensure all are properly listed in requirements
+
+### 🛡️ Error Handling and Logging
+*Supports RELIABILITY and PRECISION*
+Handle errors gracefully and log information that helps diagnose issues quickly.
+
+- **Exception Handling**:
+  - **Use Custom Exceptions**: Use application-specific exceptions from `src/folio/exceptions.py`
+  - **Don't Swallow Exceptions**: Never catch exceptions without proper handling or re-raising
+  - **Fail Fast**: Fail early and visibly for critical errors rather than continuing with incorrect behavior
+  - **Only Handle Errors You Can Handle**: Only catch exceptions that you can meaningfully handle; let others propagate
+  - **Specific Exception Types**: Catch specific exception types rather than using broad `except Exception`
+  - **Distinguish Error Types**: Treat programming errors (ImportError, NameError, AttributeError, TypeError, SyntaxError) differently from data/operational errors (ValueError, KeyError)
+  - **No Default Values for Critical Errors**: Don't use default values (like beta=1.0) for critical calculation errors; fail instead
+  - **Context in Exceptions**: Use `raise ... from e` to preserve exception context and chain
+  - **User-Friendly Messages**: Provide clear, actionable error messages to users while logging technical details
+  - **Use Error Utilities**: Leverage decorators and utilities in `src/folio/error_utils.py`
+
+- **Logging Best Practices**:
+  - **Structured Messages**: Include context (e.g., "Failed to process AAPL: missing price data")
+  - **Include Stack Traces**: For unexpected errors, use `exc_info=True`
+  - **Distinguish States vs. Errors**: Log normal states as DEBUG/INFO, not as errors
+  - **Verification Logs**: Add logs that verify critical operations like callback registration by checking the app's callback_map
+
+- **Log Levels**:
+  - **DEBUG**: Detailed flow information ("Processing portfolio entry 5 of 20")
+  - **INFO**: Normal application events ("Portfolio loaded successfully")
+  - **WARNING**: Potential issues requiring attention ("Using cached data: API unavailable")
+  - **ERROR**: Actual errors affecting functionality ("Failed to calculate beta for AAPL")
+  - **CRITICAL**: Severe errors preventing operation ("Database connection failed")
+
+- **Log Monitoring**:
+  - **Check Latest Logs**: Always check the latest logs in the `logs/` directory after running tests or the application
+  - **Application Logs**: Review `logs/folio_latest.log` after running the application to identify errors
+  - **Test Logs**: Check `logs/test_latest.log` after running tests to catch test failures and errors
+  - **Error Investigation**: When errors occur, examine the logs first for detailed error messages and stack traces
+
+- **Regression Analysis**:
+  - **Root Cause Investigation**: Always use `git blame` to understand what caused a regression
+  - **Document Findings**: Record regression analysis in devlogs to prevent repeating mistakes
+  - **Follow Process**: See [regression-analysis.md](docs/regression-analysis.md) for the complete process
+
+### 🚨 Testing
+*Supports RELIABILITY and PRECISION*
+Thorough testing prevents bugs and ensures code behaves as expected in all scenarios.
+
+- **Testing Workflow**:
+  - **Run Linter Frequently**: Run `make lint` very frequently - it's cheap, fast, and effective at catching issues early
+  - **Always Test Before Completion**: Run `make test` before considering any work complete - this is essential
+  - **Check Test Logs**: Always review `logs/test_latest.log` after running tests to identify failures
+  - **Fix Linting Issues**: Address linting errors before committing code to maintain code quality
+  - **Automated vs. Manual Testing**:
+    - For AI assistants: Only run `make test` and `make lint` to verify changes
+    - NEVER launch the application with `make folio` or `make portfolio` - leave UI testing to human users
+    - Instead, provide detailed instructions on what UI changes to test and how to verify them
+    - Add unit tests for new functionality instead of manual testing when possible
+  - **Testing Instructions**:
+    - Provide clear, step-by-step instructions for the user to test changes
+    - Include specific UI elements to check and expected behavior
+    - Describe what success looks like and potential issues to watch for
+    - Format as a checklist that the user can follow easily
+  - **Review App Logs**: Check `logs/test_latest.log` after running tests to catch errors
+  - **Test Real Data**: Use `src/lab/portfolio.csv` for testing with real portfolio data
+
+- **Test Organization**:
+  - **1:1 Test File Mapping**: Tests should be 1:1 with the code file they are testing
+    - For each source file (e.g., `util.py`), create a corresponding test file (e.g., `test_util.py`)
+    - Maintain the same directory structure in tests as in the source code
+    - This makes it easy to find tests for specific functionality
+  - **New Functionality, New Tests**: Always write tests for new functionality added to the codebase
+    - Tests should be written alongside the implementation, not as an afterthought
+    - No new feature is complete without corresponding tests
+
+- **Testing Strategy**:
+  - **Test Behavior**: Focus on functionality, not implementation details
+  - **Edge Cases**: Test boundary conditions (empty inputs, maximum values, etc.)
+  - **Regression Tests**: Add tests for bugs to prevent recurrence
+  - **Test Coverage**: Aim for high coverage of critical paths and business logic
+  - **Test New Functionality**: Always write tests for new features and components
+  - **Test Naming**: Name tests specifically to the method/module being tested
+  - **Test Public API**: Test only public functions to avoid coupling tests to implementation details
+  - **Test Independence**: Each test should be independent and not rely on other tests
+  - **Fail-First Testing**: Write tests that fail first to confirm they're testing the right thing
+  - **Test Callback Registration**: For Dash apps, always include tests that verify callbacks are properly registered
+
+- **Writing Tests**:
+  - **Test Structure**: Follow the Arrange-Act-Assert pattern
+  - **Mock External Dependencies**: Use mocks for external services, APIs, and databases
+  - **Test Edge Cases**: Include tests for error conditions and boundary cases
+  - **Parameterized Tests**: Use pytest's parameterize for testing multiple inputs
+  - **Fixtures**: Create fixtures for common test setup
+  - **Test Isolation**: Reset state between tests to prevent test interdependence
+  - **Never Change Test Logic**: Fix implementation to make tests pass, not the other way around
+  - **Simple Tests**: Keep tests simple and focused on specific behaviors
+  - **Avoid Implementation Details**: Don't test implementation details like DOM structure that might change
+
+### 🤖 Agent Interactions
+*Supports PRECISION and USABILITY*
+Effective communication with AI agents ensures efficient development and accurate implementation.
+
+- **Question Handling**:
+  - **Direct Answers**: When asked a question, answer directly and honestly without writing code
+  - **Critical Thinking**: Be critical of assumptions or leading questions in the prompt
+  - **Concise Responses**: Provide straightforward responses without unnecessary elaboration
+  - **No Automatic Implementation**: Don't jump into implementation unless specifically requested
+  - **Clarify Ambiguity**: Ask for clarification when the question is unclear rather than making assumptions
+  - **Honest Assessment**: Provide honest feedback about technical feasibility and potential issues
+
+- **Implementation Requests**:
+  - **Confirm Understanding**: Verify understanding of the request before implementing
+  - **Plan First**: Create a detailed plan before making changes
+  - **Focused Changes**: Make only the changes requested, not additional "improvements"
+  - **Test Verification**: Always suggest testing after implementation
+
+### 📝 Documentation
+*Supports USABILITY and RELIABILITY*
+Clear, accurate documentation helps onboard new developers and maintain institutional knowledge.
+
+- **Documentation Standards**:
+  - **Date Accuracy**: Always use the `date` command for current dates in documents
+  - **Consistent Format**: Follow existing formats and naming conventions
+  - **Single Source of Truth**: Maintain one authoritative source for each type of documentation
+
+- **Documentation Maintenance**:
+  - **Keep Updated**: Update documentation when code changes
+  - **Code Comments**: Document complex logic and "why" decisions, not obvious code
+  - **README Files**: Ensure each major component has a clear, concise README
+  - **Component Documentation**: Document component relationships and callback dependencies
+
+- **Development Planning**:
+  - **Create Devplans**: Document detailed plans in `docs/devplan/` for significant features, design changes, or deployments
+  - **Plan Structure**: Include overview, implementation steps, timeline, and considerations
+  - **Phased Approach**: Break complex changes into manageable phases with testing checkpoints
+  - **Deployment Plans**: For deployment-related changes, include hosting options, infrastructure requirements, and security considerations
+
+- **Development Logging**:
+  - **Update Devlogs**: Document completed changes in `docs/devlog/` after implementing major features or changes
+  - **Devlog Format**: Include date, summary, implementation details, and lessons learned
+  - **Technical Details**: Document key technical decisions, challenges overcome, and solutions implemented
+  - **Future Considerations**: Note any follow-up tasks or potential improvements identified during implementation
+  - **Retrospectives**: Create retrospectives in `docs/retrospective/` for significant issues or challenges to document lessons learned

DOCKER.md

@@ -0,0 +1,128 @@
+# Docker Setup for Folio
+
+This document provides instructions for running the Folio application using Docker.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) installed on your system
+- [Docker Compose](https://docs.docker.com/compose/install/) (usually included with Docker Desktop)
+
+## Quick Start
+
+1. **Create a .env file** (optional)
+
+   Copy the example environment file if you want to customize settings:
+
+   ```bash
+   cp .env.example .env
+   # Edit .env to customize settings if needed
+   ```
+
+   Note: Since we're using yfinance as the default data source, no API keys are required.
+
+2. **Build and run with Docker Compose**
+
+   ```bash
+   # Build and start the container in detached mode
+   make docker-up
+   ```
+
+   After successful startup, you'll see a message with the URL where you can access the application.
+
+3. **Access the application**
+
+   Open your browser and navigate to:
+
+   ```
+   http://localhost:8050
+   ```
+
+4. **View logs**
+
+   To monitor the application logs in real-time:
+
+   ```bash
+   make docker-logs
+   ```
+
+   Press Ctrl+C to stop viewing logs.
+
+5. **Stop the application**
+
+   ```bash
+   make docker-down
+   ```
+
+## Docker Commands Reference
+
+The following Make commands are available for working with Docker:
+
+| Command | Description |
+|---------|-------------|
+| `make docker-build` | Build the Docker image |
+| `make docker-run` | Run the Docker container |
+| `make docker-up` | Start the application with docker-compose |
+| `make docker-down` | Stop the docker-compose services |
+| `make docker-logs` | Tail the Docker logs |
+| `make docker-test` | Run tests in a Docker container |
+
+### Manual Docker Commands
+
+If you prefer to use Docker directly without Make:
+
+1. **Build the Docker image**
+
+   ```bash
+   docker build -t folio:latest .
+   ```
+
+2. **Run the Docker container**
+
+   ```bash
+   docker run -p 8050:8050 --env-file .env folio:latest
+   ```
+
+3. **Use Docker Compose directly**
+
+   ```bash
+   # Start services
+   docker-compose up -d
+
+   # View logs
+   docker-compose logs -f
+
+   # Stop services
+   docker-compose down
+   ```
+
+## Troubleshooting
+
+- **Port conflicts**: If port 8050 is already in use, modify the `PORT` environment variable in your `.env` file and update the port mapping in `docker-compose.yml`.
+
+- **Data source issues**: By default, the application uses yfinance as the data source. If you want to use FMP instead, you'll need to set the FMP_API_KEY in your `.env` file and change DATA_SOURCE to 'fmp'.
+
+- **Volume mounting**: If you're making changes to the code and want to see them reflected immediately, ensure the volumes in `docker-compose.yml` are correctly mapping your local directories.
+
+- **Dependencies**: The Docker image uses `requirements.txt` for its dependencies. If you need to add or update dependencies, modify this file instead of editing the Dockerfile directly.
+
+- **Development dependencies**: For development and testing, the Docker image can also install dependencies from `requirements-dev.txt`. These are installed automatically when running `make docker-test`.
+
+- **API Keys**: Sensitive data like API keys should be passed at runtime using environment variables or the `.env` file, not hardcoded in the Dockerfile.
+
+## Testing in Docker
+
+To run tests in a Docker container:
+
+```bash
+make docker-test
+```
+
+This will build a Docker image with development dependencies and run the test suite inside the container.
+
+## Next Steps
+
+After successfully running the application locally with Docker, you can consider:
+
+1. Setting up CI/CD with GitHub Actions
+2. Deploying to a hosting platform like Hugging Face Spaces
+3. Implementing additional Docker configurations for production environments

Dockerfile

@@ -0,0 +1,43 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Set environment variables
+ENV PYTHONPATH=/app
+# Use PORT 7860 for Hugging Face Spaces, 8050 for local development
+# The application will check for HF_SPACE environment variable to determine the environment
+ENV PORT=8050
+ENV HF_SPACE=1
+# No need to set LOG_LEVEL as it will be determined from folio.yaml based on environment
+# Note: Sensitive environment variables like GEMINI_API_KEY should be passed at runtime
+# rather than build time for security reasons
+
+# Flag to install development dependencies
+ARG INSTALL_DEV=false
+
+# Install only the necessary system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends gcc && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy requirements files
+COPY requirements.txt .
+COPY requirements-dev.txt .
+
+# Install required packages
+RUN pip install --no-cache-dir -r requirements.txt && \
+    if [ "$INSTALL_DEV" = "true" ]; then \
+    echo "Installing development dependencies..." && \
+    pip install --no-cache-dir -r requirements-dev.txt; \
+    fi
+
+# Copy all necessary application code
+COPY src ./src
+COPY config ./config
+
+# Expose both ports (7860 for Hugging Face, 8050 for local)
+EXPOSE 7860 8050
+
+# Run the application with Gunicorn for production deployment
+# The command will determine the correct port based on environment
+CMD ["sh", "-c", "if [ -n \"$HF_SPACE\" ]; then PORT=7860; fi && gunicorn --bind 0.0.0.0:$PORT --workers 2 --timeout 60 src.folio.app:server"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 omninmo Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

Makefile

@@ -0,0 +1,296 @@
+# Makefile for folio project
+
+# Variables
+SHELL := /bin/bash
+PYTHON := python3
+VENV_DIR := venv
+SCRIPTS_DIR := scripts
+LOGS_DIR := logs
+SRC_DIR := src.v2
+TIMESTAMP := $(shell date +%Y%m%d_%H%M%S)
+PORT := 5000
+
+# Default target
+.PHONY: help
+help:
+	@echo "Available targets:"
+	@echo "  help        - Show this help message"
+	@echo "  env         - Set up and activate a virtual environment"
+	@echo "  install     - Install dependencies and set script permissions"
+	@echo "  train       - Train the model (use --sample for training with sample data)"
+	@echo "  predict     - Run predictions using console app (usage: make predict [NVDA])"
+	@echo "  mlflow      - Start the MLflow UI to view training results (optional: make mlflow PORT=5001)"
+	@echo "  folio       - Start the portfolio dashboard with debug mode enabled"
+	@echo "               Options: portfolio=path/to/file.csv (use custom portfolio file)"
+	@echo "                        log=LEVEL (set logging level: DEBUG, INFO, WARNING, ERROR)"
+	@echo "  portfolio   - Start the portfolio dashboard with sample portfolio and debug mode"
+	@echo "               Options: log=LEVEL (set logging level: DEBUG, INFO, WARNING, ERROR)"
+	@echo "  simulator   - Run the SPY simulator to analyze portfolio behavior under different market conditions"
+	@echo "               Options: range=VALUE (SPY change range, default: 20.0)"
+	@echo "                        steps=VALUE (number of steps, default: 41)"
+	@echo "                        focus=TICKER (focus on specific ticker(s), comma-separated)"
+	@echo "                        detailed=1 (show detailed analysis for all positions)"
+	@echo "  clean       - Clean up generated files and caches"
+	@echo "               Options: --cache (also clear data cache)"
+	@echo "  lint        - Run type checker and linter"
+	@echo "               Options: --fix (auto-fix linting issues)"
+	@echo "  test        - Run all unit tests in the tests directory"
+	@echo "  test-e2e    - Run end-to-end tests against real portfolio data"
+	@echo "  docker-build - Build the Docker image"
+	@echo "  docker-run   - Run the Docker container"
+	@echo "  docker-up    - Start the application with docker-compose"
+	@echo "  docker-down  - Stop the docker-compose services"
+	@echo "  docker-logs  - Tail the Docker logs"
+	@echo "  docker-test  - Run tests in a Docker container"
+
+# Set up virtual environment
+.PHONY: env
+env:
+	@echo "Setting up virtual environment..."
+	@bash $(SCRIPTS_DIR)/setup-venv.sh
+	@echo "Activating virtual environment..."
+	@echo "NOTE: To use the virtual environment in your current shell, run: source activate-venv.sh"
+	@echo "The virtual environment will be automatically activated for all make commands."
+
+# Install dependencies
+.PHONY: install
+install:
+	@echo "Installing dependencies..."
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo "Virtual environment not found. Please run 'make env' first."; \
+		exit 1; \
+	fi
+	@mkdir -p $(LOGS_DIR)
+	@(echo "=== Installation Log $(TIMESTAMP) ===" && \
+	echo "Starting installation at: $$(date)" && \
+	(source $(VENV_DIR)/bin/activate && \
+	$(PYTHON) -m pip install --upgrade pip && \
+	bash $(SCRIPTS_DIR)/install-reqs.sh) 2>&1 && \
+	echo "Setting script permissions..." && \
+	chmod +x $(SCRIPTS_DIR)/*.sh && \
+	chmod +x $(SCRIPTS_DIR)/*.py && \
+	echo "Installation complete at: $$(date)") | tee $(LOGS_DIR)/install_$(TIMESTAMP).log
+	@echo "Installation log saved to: $(LOGS_DIR)/install_$(TIMESTAMP).log"
+
+# Train the model
+.PHONY: train
+train:
+	@echo "Training the model..."
+	@source $(VENV_DIR)/bin/activate && \
+	PYTHONPATH=. $(PYTHON) -m $(SRC_DIR).train $(if $(findstring --sample,$(MAKECMDGOALS)),--force-sample,)
+
+# Run predictions
+.PHONY: predict
+predict:
+	@echo "Running predictions..."
+	@source $(VENV_DIR)/bin/activate && \
+	if [ -n "$(filter-out $@,$(MAKECMDGOALS))" ]; then \
+		TICKERS=$$(echo "$(filter-out $@,$(MAKECMDGOALS))" | tr ',' ' '); \
+		echo "Predicting for: $$TICKERS"; \
+		PYTHONPATH=. $(PYTHON) -m $(SRC_DIR).console_app --tickers $$TICKERS; \
+	else \
+		echo "Running predictions on watchlist..."; \
+		PYTHONPATH=. $(PYTHON) -m $(SRC_DIR).console_app; \
+	fi
+
+# Start the MLflow UI
+.PHONY: mlflow
+mlflow:
+	@echo "Starting MLflow UI on http://127.0.0.1:$(PORT)..."
+	@echo "Press Ctrl+C to stop the server."
+	@source $(VENV_DIR)/bin/activate && \
+	$(PYTHON) $(SCRIPTS_DIR)/run_mlflow.py $(if $(PORT),--port $(PORT),)
+
+# Clean up generated files
+.PHONY: clean
+clean:
+	@echo "Cleaning up generated files..."
+	@bash $(SCRIPTS_DIR)/clean.sh
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".mypy_cache" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".ruff_cache" -exec rm -rf {} + 2>/dev/null || true
+	@if [ "$(findstring --cache,$(MAKECMDGOALS))" != "" ]; then \
+		echo "Clearing data cache..."; \
+		rm -rf cache/*; \
+		mkdir -p cache; \
+		echo "Cache cleared."; \
+	fi
+
+# Lint Python code
+.PHONY: lint
+lint:
+	@echo "Running linter (ruff)..."
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo "Virtual environment not found. Please run 'make env' first."; \
+		exit 1; \
+	fi
+	@mkdir -p $(LOGS_DIR)
+	@(echo "=== Code Check Log $(TIMESTAMP) ===" && \
+	echo "Starting checks at: $$(date)" && \
+	(source $(VENV_DIR)/bin/activate && \
+	echo "Running linter (ruff)..." && \
+	ruff check --fix --unsafe-fixes .) \
+	2>&1) | tee $(LOGS_DIR)/code_check_latest.log
+	@echo "Check log saved to: $(LOGS_DIR)/code_check_latest.log"
+
+# Allow --fix as target without actions
+.PHONY: --fix
+--fix:
+
+# Lab Projects
+.PHONY: portfolio folio stop-folio port simulator
+
+# Docker targets
+.PHONY: docker-build docker-run docker-up docker-down docker-logs docker-compose-up docker-compose-down docker-test deploy-hf
+
+portfolio:
+	@echo "Starting portfolio dashboard with sample portfolio.csv and debug mode..."
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo "Virtual environment not found. Please run 'make env' first."; \
+		exit 1; \
+	fi
+	@source $(VENV_DIR)/bin/activate && \
+	LOG_LEVEL=$(if $(log),$(log),INFO) \
+	PYTHONPATH=. python3 -m src.folio.app --port 8051 --debug --portfolio src/folio/assets/sample-portfolio.csv
+
+port:
+	@echo "Running portfolio analysis..."
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo "Virtual environment not found. Please run 'make env' first."; \
+		exit 1; \
+	fi
+	@source $(VENV_DIR)/bin/activate && \
+	PYTHONPATH=. python3 src/lab/portfolio.py "$(if $(csv),$(csv),src/folio/assets/sample-portfolio.csv)"
+
+folio:
+	@echo "Starting portfolio dashboard with debug mode..."
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo "Virtual environment not found. Please run 'make env' first."; \
+		exit 1; \
+	fi
+	@source $(VENV_DIR)/bin/activate && \
+	LOG_LEVEL=$(if $(log),$(log),INFO) \
+	PYTHONPATH=. python3 -m src.folio.app --port 8051 --debug $(if $(portfolio),--portfolio $(portfolio),)
+
+stop-folio:
+	@echo "Stopping portfolio dashboard..."
+	@PIDS=$$(ps aux | grep "[p]ython.*folio" | awk '{print $$2}'); \
+	if [ -n "$$PIDS" ]; then \
+		echo "Found folio processes with PIDs: $$PIDS"; \
+		for PID in $$PIDS; do \
+			echo "Killing process $$PID..."; \
+			kill -9 $$PID 2>/dev/null || echo "Failed to kill process $$PID (might require sudo)"; \
+		done; \
+		echo "All folio processes have been terminated."; \
+	else \
+		echo "No running folio processes found."; \
+	fi
+
+simulator:
+	@echo "Running SPY simulator..."
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo "Virtual environment not found. Please run 'make env' first."; \
+		exit 1; \
+	fi
+	@source $(VENV_DIR)/bin/activate && \
+	PYTHONPATH=. ./scripts/folio-simulator.py $(if $(range),--range $(range),) $(if $(steps),--steps $(steps),) $(if $(focus),--focus $(focus),) $(if $(detailed),--detailed,)
+
+# Test targets
+.PHONY: test test-e2e
+test:
+	@echo "Running unit tests..."
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo "Virtual environment not found. Please run 'make env' first."; \
+		exit 1; \
+	fi
+	@mkdir -p $(LOGS_DIR)
+	@(echo "=== Test Run Log $(TIMESTAMP) ===" && \
+	echo "Starting tests at: $$(date)" && \
+	(source $(VENV_DIR)/bin/activate && \
+	PYTHONPATH=. pytest tests/ -v) 2>&1) | tee $(LOGS_DIR)/test_latest.log
+	@echo "Test log saved to: $(LOGS_DIR)/test_latest.log"
+
+test-e2e:
+	@echo "Running end-to-end tests..."
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		echo "Virtual environment not found. Please run 'make env' first."; \
+		exit 1; \
+	fi
+	@if [ ! -f "private-data/test/test-portfolio.csv" ]; then \
+		echo "Warning: Test portfolio file not found at private-data/test/test-portfolio.csv"; \
+		echo "E2E tests will try to use sample-data/sample-portfolio.csv instead."; \
+	fi
+	@mkdir -p $(LOGS_DIR)
+	@(echo "=== E2E Test Run Log $(TIMESTAMP) ===" && \
+	echo "Starting E2E tests at: $$(date)" && \
+	(source $(VENV_DIR)/bin/activate && \
+	PYTHONPATH=. pytest tests/e2e/ -v) 2>&1) | tee $(LOGS_DIR)/test_e2e_latest.log
+	@echo "E2E test log saved to: $(LOGS_DIR)/test_e2e_latest.log"
+
+# Docker commands
+docker-build:
+	@echo "Building Docker image..."
+	docker build --debug -t folio:latest .
+
+# Run the Docker container
+docker-run:
+	@echo "Running Docker container..."
+	docker run -p 8050:8050 --env-file .env folio:latest
+
+# Start with docker-compose
+docker-up:
+	@echo "Starting with docker-compose..."
+	docker-compose up -d
+	@echo "Folio app launched successfully!"
+	@echo "Access the app at: http://localhost:8050"
+
+# Stop docker-compose services
+docker-down:
+	@echo "Stopping docker-compose services..."
+	docker-compose down
+
+# Alias for backward compatibility
+docker-compose-up: docker-up
+docker-compose-down: docker-down
+
+# Tail Docker logs
+docker-logs:
+	@echo "Tailing Docker logs..."
+	docker-compose logs -f
+
+# Run tests in Docker container
+docker-test:
+	@echo "Running tests in Docker container..."
+	@if [ -z "$$GEMINI_API_KEY" ]; then \
+		echo "Warning: GEMINI_API_KEY environment variable not set. Some tests may fail."; \
+	fi
+	@docker-compose -f docker-compose.test.yml build --build-arg INSTALL_DEV=true
+	@docker-compose -f docker-compose.test.yml run --rm folio
+
+# Deploy to Hugging Face Spaces
+deploy-hf:
+	@echo "Deploying to Hugging Face Spaces..."
+	@echo "Checking for Git LFS..."
+	@if ! command -v git-lfs &> /dev/null; then \
+		echo "Error: Git LFS is not installed. Please install it first."; \
+		echo "  macOS: brew install git-lfs"; \
+		echo "  Linux: apt-get install git-lfs"; \
+		exit 1; \
+	fi
+	@echo "Checking if Hugging Face Space remote exists..."
+	@if ! git remote | grep -q "space"; then \
+		echo "Adding Hugging Face Space remote..."; \
+		git remote add space git@huggingface.co:mingdom/folio; \
+	fi
+	@echo "Ensuring Git LFS is tracking .pkl files..."
+	@grep -q "*.pkl filter=lfs diff=lfs merge=lfs -text" .gitattributes || \
+		echo "*.pkl filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
+	@echo "Initializing Git LFS..."
+	@git lfs install
+	@echo "Pushing to Hugging Face Space..."
+	@git push space main:main
+	@echo "\n✅ Deployment to Hugging Face Space completed!"
+	@echo "Your application is now available at: https://huggingface.co/spaces/mingdom/folio"
+
+%:
+	@:

README.md

@@ -0,0 +1,122 @@
+---
+title: Folio - Financial Portfolio Dashboard
+emoji: 📊
+colorFrom: indigo
+colorTo: purple
+sdk: docker
+sdk_version: "latest"
+app_file: app.py
+pinned: false
+---
+
+# Folio - Financial Portfolio Dashboard
+
+Folio is a powerful web-based dashboard for analyzing and optimizing your investment portfolio. Get professional-grade insights into your stocks, options, and other financial instruments with an intuitive, user-friendly interface.
+
+## Why Folio?
+
+- **Complete Portfolio Visibility**: See your entire financial picture in one place
+- **Smart Risk Assessment**: Understand your portfolio's risk profile with beta analysis
+- **AI-Powered Insights**: Get personalized investment advice from our AI portfolio advisor
+- **Cash & Equivalents Detection**: Automatically identifies money market and cash-like positions
+- **Option Analytics**: Detailed metrics for options including implied volatility and Greeks
+- **Zero Cost**: Free to use, with no hidden fees or subscriptions
+
+## Key Features
+
+- **Portfolio Summary**: View total exposure, beta, and allocation breakdown
+- **Position Details**: Analyze individual positions with detailed metrics
+- **AI Portfolio Advisor**: Get personalized investment advice powered by Google's Gemini AI
+- **Filtering & Sorting**: Filter by position type and sort by various metrics
+- **Real-time Data**: Uses Yahoo Finance API for up-to-date market data
+- **Responsive Design**: Works seamlessly on desktop and mobile devices
+- **Dark Mode**: Easy on the eyes for late-night financial analysis
+
+## Getting Started
+
+### Try It Online
+
+The easiest way to try Folio is through our Hugging Face Spaces deployment:
+[https://huggingface.co/spaces/mingdom/folio](https://huggingface.co/spaces/mingdom/folio)
+
+### Local Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/mingdom/folio.git
+   cd folio
+   ```
+
+2. Set up the environment and install dependencies:
+   ```bash
+   make env
+   make install
+   ```
+
+3. Run with sample portfolio:
+   ```bash
+   make portfolio
+   ```
+
+4. Or start with a blank slate:
+   ```bash
+   make folio
+   ```
+
+### Development Setup
+
+1. Install development dependencies:
+   ```bash
+   pip install -r requirements-dev.txt
+   ```
+
+2. Set up pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+
+3. Run linting and tests:
+   ```bash
+   make lint
+   make test
+   ```
+
+### Docker Deployment
+
+1. Start the application with Docker:
+   ```bash
+   make docker-up
+   ```
+
+2. Access the dashboard at http://localhost:8050
+
+3. View logs (if needed):
+   ```bash
+   make docker-logs
+   ```
+
+For more Docker commands and options, see [DOCKER.md](DOCKER.md).
+
+For information about logging configuration, see [docs/logging.md](docs/logging.md).
+
+## Using Folio
+
+1. **Upload Your Portfolio**: Use the upload button to import a CSV file with your holdings
+2. **Explore Your Data**: View summary metrics and detailed breakdowns of your investments
+3. **Filter and Sort**: Focus on specific asset types or metrics that matter to you
+4. **Get AI Insights**: Click the "Robot Advisor" button to get personalized advice about your portfolio
+5. **Export or Share**: Save your analysis or share insights with your financial advisor
+
+## Sample Portfolio
+
+Not ready to upload your own data? Click the "Load Sample Portfolio" button to explore Folio with our demo data.
+
+## Privacy & Security
+
+- **Your Data Stays Private**: All analysis happens in your browser or local environment
+- **No Account Required**: Use Folio without creating an account or sharing personal information
+- **Open Source**: All code is transparent and available for review
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

activate-venv.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Script to activate the virtual environment
+source "/Users/dongming/projects/omninmo/venv/bin/activate"
+echo "Virtual environment activated. Run 'deactivate' to exit."

docker-compose.test.yml

@@ -0,0 +1,20 @@
+version: '3.8'
+
+services:
+  folio:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        - INSTALL_DEV=true
+    environment:
+      - PYTHONPATH=/app
+      - DATA_SOURCE=yfinance
+      - LOG_LEVEL=DEBUG
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+    volumes:
+      - ./src:/app/src
+      - ./tests:/app/tests
+      - ./config:/app/config
+      - ./.env:/app/.env
+    command: pytest tests/ -v

docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  folio:
+    image: folio:latest
+    ports:
+      - "8050:8050"
+    environment:
+      - PORT=8050
+      - HF_SPACE=
+      - PYTHONPATH=/app
+      - DATA_SOURCE=yfinance
+      - LOG_LEVEL=INFO
+      - GEMINI_API_KEY=${GEMINI_API_KEY}
+    volumes:
+      - ./config:/app/config
+      - ./data:/app/data
+      - ./.env:/app/.env
+    restart: unless-stopped

pyproject.toml

@@ -0,0 +1,94 @@
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_optional = true
+plugins = ["numpy.typing.mypy_plugin"]
+
+[[tool.mypy.overrides]]
+module = "dash.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "pandas.*"
+ignore_missing_imports = true
+
+[tool.ruff]
+# Line length and target version are top-level
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+# Enable recommended rules + specific ones useful for data science projects
+select = [
+    "E",        # pycodestyle errors
+    "F",        # pyflakes
+    "I",        # isort
+    "N",        # pep8-naming
+    "UP",       # pyupgrade
+    "PL",       # pylint
+    "RUF",      # ruff-specific rules
+    "W",        # pycodestyle warnings
+    "F401",     # Module imported but unused
+    "F841",     # Local variable is assigned to but never used
+    "F821",     # Undefined name
+    "F811",     # Redefined name
+    "F822",     # Undefined name in __all__
+    "PLC0414",  # Useless import alias
+    "PLE0101",  # Function defined outside __init__
+    "PLE0604",  # Invalid object in __all__, or invalid __all__ format
+    "PLE0605",  # Invalid format for __all__
+    "A",        # Unused functions... etc.
+    "ARG001",   # Unused function argument
+    "ARG002",   # Unused function argument
+    "B",        # flake8-bugbear rules (includes B007 for unused loop variables)
+    "ERA",      # eradicate (commented out code)
+    "F",        # pyflakes (includes F401 for unused imports, F841 for unused variables)
+    "T201",     # print statements
+]
+
+# Ignore specific rules
+ignore = [
+    "E501",  # line too long - let's handle line length more flexibly for data science code
+    "N803",  # argument name should be lowercase - common in ML to use X, y
+    "N806",  # variable name should be lowercase - common in ML to use X_train, y_test
+    "PLR0913",  # too many arguments - common in ML functions with many parameters
+    "PLR0912",  # too many branches - common in ML data processing and training loops
+    "PLR0915",  # too many statements - common in ML training and evaluation functions
+    "PLR2004",  # magic value used in comparison - common in data processing code
+]
+
+# Allow autofix for all enabled rules (when `--fix`) is provided
+fixable = ["ALL"]
+
+# Exclude a variety of commonly ignored directories
+exclude = [
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "mlruns",
+    ".pytest_cache",
+    ".archive",
+]
+
+# Allow unused variables when underscore-prefixed
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.lint.per-file-ignores]
+# DO NOT IGNORE UNLESS IT'S A REALLY GOOD REASON!
+"__init__.py" = ["F401"]  # Re-exports are common in __init__.py files
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]

requirements-dev.txt

@@ -0,0 +1,30 @@
+## Development Dependencies
+# * Always use latest version
+
+# Code Quality Tools
+# -----------------
+
+# ruff - Fast Python linter and formatter written in Rust
+# Used for code quality checks, style enforcement, and automatic formatting
+# Version 0.5.3+ required for native LSP server support in editors
+# Used in: make lint, CI/CD pipeline, editor integrations
+# Configuration: pyproject.toml [tool.ruff] section
+ruff
+
+# Testing Tools
+# ------------
+
+# pytest - Testing framework for writing and running unit and integration tests
+# Used for automated testing of application functionality
+# Used in: make test, CI/CD pipeline
+# Configuration: pytest.ini (implicit)
+pytest
+
+# Terminal UI Tools
+# ----------------
+
+# rich - Library for rich text and beautiful formatting in the terminal
+# Used for creating beautiful, interactive terminal output in scripts
+# Used in: scripts/folio-simulator.py
+# Configuration: None (used directly in code)
+rich>=13.9.0

requirements.txt

@@ -0,0 +1,25 @@
+# Core dependencies - only what's needed for the Folio app
+# Note: Developer Dependencies in requirements-dev.txt
+pandas==2.2.1
+numpy==1.26.4
+# scipy removed - no longer needed after migrating to QuantLib
+QuantLib>=1.30  # For option calculations
+
+# Utilities
+requests>=2.32.0
+PyYAML==6.0.1
+
+# Data source
+yfinance>=0.2.37  # For portfolio beta calculation
+
+# Web application - using latest versions for security updates
+dash>=2.14.2
+dash-bootstrap-components>=1.5.0
+dash-bootstrap-templates>=1.1.1  # For Plotly figure templates
+
+# WSGI server for production - always use latest for security
+gunicorn>=21.2.0
+
+# AI/ML dependencies
+google-generativeai>=0.3.0  # For Gemini AI integration
+

scripts/README.md

@@ -0,0 +1,77 @@
+# Diagnostic Scripts
+
+This directory contains diagnostic scripts used to troubleshoot issues with the Folio application, particularly when running in a Docker container.
+
+## Available Scripts
+
+### `run_diagnostics.sh`
+
+A shell script that runs all diagnostic scripts on a running Docker container.
+
+**Usage:**
+```bash
+./run_diagnostics.sh [container_name]
+```
+
+If `container_name` is not provided, it defaults to "omninmo-folio-1".
+
+### `check_modules.py`
+
+Checks for the availability and versions of Python modules required by the Folio application.
+
+**Usage:**
+```bash
+python check_modules.py
+```
+
+**In Docker:**
+```bash
+docker exec omninmo-folio-1 python /app/scripts/check_modules.py
+```
+
+### `check_network.py`
+
+Tests network connectivity from inside a Docker container, including binding to different interfaces and testing external connectivity.
+
+**Usage:**
+```bash
+python check_network.py [--bind-test] [--external-test]
+```
+
+**In Docker:**
+```bash
+docker exec omninmo-folio-1 python /app/scripts/check_network.py
+```
+
+### `test_imports.py`
+
+Tests importing various modules used by the Folio application to diagnose import-related issues.
+
+**Usage:**
+```bash
+python test_imports.py
+```
+
+**In Docker:**
+```bash
+docker exec omninmo-folio-1 python /app/scripts/test_imports.py
+```
+
+## Common Issues
+
+These scripts were created to diagnose the following common issues:
+
+1. **Module Import Errors**: Problems with Python module imports, particularly with the project structure in a Docker container.
+
+2. **Network Binding Issues**: Issues with the application binding to the correct network interface inside the container.
+
+3. **Dependency Problems**: Missing or incompatible dependencies.
+
+## Adding New Scripts
+
+When adding new diagnostic scripts, please follow these guidelines:
+
+1. Include a detailed docstring explaining the purpose of the script
+2. Add usage examples, both for local execution and in Docker
+3. Make the script executable (`chmod +x script_name.py`)
+4. Update this README with information about the new script

scripts/check_beta.py

@@ -0,0 +1,175 @@
+"""
+Beta Calculation Validation Script
+
+This script fetches historical data and calculates beta values for a predefined list of symbols
+to validate how the beta calculation works in practice. It uses raw beta calculation without
+any of the special case handling found in the portfolio processing code.
+
+Beta measures the volatility of a security in relation to the market (using SPY as proxy).
+- Beta > 1: More volatile than the market
+- Beta = 1: Same volatility as the market
+- Beta < 1: Less volatile than the market
+- Beta < 0: Moves in the opposite direction as the market
+
+Latest Beta Values (as of 2025-04-01):
+   SPAXX**: Not available (money market fund, no market data)
+     FMPXX: Not available (money market fund, no market data)
+     FFRHX: 0.0553 (money market fund)
+       TLT: -0.0145 (long-term treasury ETF, negative correlation)
+       SHY: 0.0107 (short-term treasury ETF)
+       BIL: 0.0005 (1-3 month T-bill ETF, extremely low beta)
+      MCHI: 0.7130 (China ETF, significant market exposure)
+      IEFA: 0.7862 (International ETF, significant market exposure)
+       SPY: 1.0000 (S&P 500 ETF, market benchmark)
+      AAPL: 1.2029 (Tech stock, higher volatility than market)
+     GOOGL: 1.2695 (Tech stock, higher volatility than market)
+   INVALID: Not available (invalid symbol for testing error handling)
+
+Usage:
+    python scripts/check_beta.py
+
+Note: This script calculates raw beta values without the additional logic that might be
+applied in the main application, such as fallbacks for cash-like positions or special
+handling of missing data.
+"""
+
+import os
+import sys
+
+import pandas as pd
+
+# Adjust path to import from src
+if __name__ == "__main__":
+    script_dir = os.path.dirname(__file__)
+    project_root = os.path.abspath(os.path.join(script_dir, ".."))
+    sys.path.insert(0, project_root)
+
+from src.fmp import DataFetcher
+from src.folio.logger import logger  # Use the same logger if desired
+from src.folio.utils import is_cash_or_short_term
+
+
+def calculate_raw_beta(
+    ticker: str, fetcher: DataFetcher, market_data: pd.DataFrame | None
+) -> float | str:
+    """Fetches data and calculates raw beta without special handling."""
+    # Early validation
+    if market_data is None:
+        return "Error: Market data not available"
+
+    try:
+        # Fetch and validate stock data
+        logger.info(f"Fetching data for {ticker}...")
+        stock_data = fetcher.fetch_data(ticker)
+
+        # Data validation checks
+        error_msg = _validate_data(ticker, stock_data)
+        if error_msg:
+            return error_msg
+
+        # Calculate returns
+        logger.info(f"Calculating returns for {ticker}...")
+        stock_returns = stock_data["Close"].pct_change().dropna()
+        market_returns = market_data["Close"].pct_change().dropna()
+
+        # Align data by index
+        aligned_stock, aligned_market = stock_returns.align(
+            market_returns, join="inner"
+        )
+
+        # Validate aligned data
+        if aligned_stock.empty or len(aligned_stock) < 2:
+            return f"Error: Not enough overlapping data points after alignment for {ticker} (need >= 2)"
+
+        # Calculate beta
+        logger.info(f"Calculating variance/covariance for {ticker}...")
+        market_variance = aligned_market.var()
+        covariance = aligned_stock.cov(aligned_market)
+
+        # Validate variance and covariance
+        error_msg = _validate_variance_covariance(market_variance, covariance)
+        if error_msg:
+            return error_msg
+
+        # Calculate and return beta
+        beta = covariance / market_variance
+        return beta
+
+    except Exception as e:
+        return f"Error calculating beta for {ticker}: {e}"
+
+
+def _validate_data(ticker: str, stock_data: pd.DataFrame | None) -> str | None:
+    """Validates stock data and returns error message if invalid."""
+    if stock_data is None or stock_data.empty:
+        return f"Error: No data fetched for {ticker}"
+    if len(stock_data) < 2:
+        return f"Error: Not enough data points for {ticker} (need >= 2)"
+    return None
+
+
+def _validate_variance_covariance(
+    market_variance: float, covariance: float
+) -> str | None:
+    """Validates variance and covariance calculations and returns error message if invalid."""
+    if pd.isna(market_variance) or abs(market_variance) < 1e-12:
+        return f"Error: Market variance is zero or near-zero ({market_variance})"
+    if pd.isna(covariance):
+        return "Error: Covariance calculation resulted in NaN"
+    return None
+
+
+if __name__ == "__main__":
+    symbols_to_check = [
+        "SPAXX**",
+        "FMPXX",
+        "FFRHX",
+        "TLT",  # 20+ Year Treasury Bond ETF
+        "SHY",  # 1-3 Year Treasury Bond ETF
+        "BIL",  # 1-3 Month T-Bill ETF
+        "MCHI",  # iShares MSCI China ETF
+        "IEFA",  # iShares Core MSCI EAFE ETF
+        "SPY",  # S&P 500 ETF
+        "AAPL",  # Apple Stock
+        "GOOGL",  # Google Stock
+        "INVALID",  # Test an invalid ticker
+    ]
+
+    try:
+        fetcher = DataFetcher()
+        if fetcher is None:
+            raise RuntimeError("Fetcher initialization failed")
+        # Fetch market data once
+        market_data = (
+            fetcher.fetch_market_data()
+        )  # Assumes this fetches S&P500 or similar
+        if market_data is None or market_data.empty:
+            sys.exit(1)
+
+    except Exception:
+        sys.exit(1)
+
+    # Calculate beta for each symbol and store results
+    results = {}
+    for symbol in symbols_to_check:
+        beta_result = calculate_raw_beta(symbol, fetcher, market_data)
+        results[symbol] = beta_result
+
+    # Display results in a formatted table
+
+    for symbol, result in results.items():
+        if isinstance(result, float):
+            is_cash = is_cash_or_short_term(symbol, beta=result)
+            classification = "CASH-LIKE" if is_cash else "MARKET-CORRELATED"
+        else:
+            # Error case
+            logger.error(f"Error for {symbol}: {result}")
+
+    # Summary statistics
+    success_count = sum(1 for r in results.values() if isinstance(r, float))
+    error_count = len(results) - success_count
+    cash_like_count = sum(
+        1
+        for s, r in results.items()
+        if isinstance(r, float) and is_cash_or_short_term(s, beta=r)
+    )

scripts/clean.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Script to clean up generated files
+
+echo "Cleaning up generated files..."
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+# Get the project root directory
+PROJECT_ROOT="$( cd "$SCRIPT_DIR/.." &> /dev/null && pwd )"
+
+# Remove Python cache files
+echo "Removing Python cache files..."
+find "$PROJECT_ROOT" -type d -name "__pycache__" -exec rm -rf {} +
+find "$PROJECT_ROOT" -type f -name "*.pyc" -delete
+find "$PROJECT_ROOT" -type f -name "*.pyo" -delete
+find "$PROJECT_ROOT" -type f -name "*.pyd" -delete
+
+# Remove model files
+echo "Removing model files..."
+rm -rf "$PROJECT_ROOT/models"/*.pkl
+
+# Remove cache files
+echo "Removing cache files..."
+rm -rf "$PROJECT_ROOT/cache"/*
+
+echo "Cleanup complete!" 

scripts/compare_exposures_ui.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""
+Script to compare summary card exposures with position details exposures,
+using the same methods as the UI components.
+
+This script loads portfolio data from a CSV file, calculates the summary card values,
+and compares them with the sum of exposures from the position details as they would
+appear in the UI.
+"""
+
+import os
+import sys
+
+import pandas as pd
+
+# Add the src directory to the Python path
+sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
+
+from src.folio.components.summary_cards import format_summary_card_values
+from src.folio.portfolio import process_portfolio_data
+
+
+def load_portfolio_data(csv_path):
+    """Load portfolio data from a CSV file."""
+    try:
+        df = pd.read_csv(csv_path)
+        return df
+    except Exception:
+        return None
+
+
+def compare_exposures():
+    """Compare summary card exposures with position details exposures."""
+    # Try to load the private portfolio data first
+    private_csv_path = "private-data/portfolio-private.csv"
+    sample_csv_path = "sample-data/sample-portfolio.csv"
+
+    if os.path.exists(private_csv_path):
+        df = load_portfolio_data(private_csv_path)
+    elif os.path.exists(sample_csv_path):
+        df = load_portfolio_data(sample_csv_path)
+    else:
+        return
+
+    if df is None:
+        return
+
+    # Process the portfolio data
+    result = process_portfolio_data(df)
+
+    # Check the structure of the result
+    if isinstance(result, tuple):
+        if len(result) == 3:
+            # Newer version: (groups, summary, cash_like_positions)
+            groups, summary, cash_like_positions = result
+        elif len(result) == 2:
+            # Possible alternative: (groups, cash_like_positions)
+            groups, cash_like_positions = result
+            from src.folio.portfolio import calculate_portfolio_summary
+
+            summary = calculate_portfolio_summary(groups, cash_like_positions, 0.0)
+    else:
+        # If result is not a tuple, it's likely just the groups
+        groups = result
+        from src.folio.portfolio import calculate_portfolio_summary
+
+        summary = calculate_portfolio_summary(groups, [], 0.0)
+
+    # Ensure we have a valid summary object
+    if not hasattr(summary, "to_dict"):
+        # Create a minimal summary for testing
+        from src.folio.data_model import ExposureBreakdown, PortfolioSummary
+
+        empty_exposure = ExposureBreakdown()
+        summary = PortfolioSummary(
+            net_market_exposure=0.0,
+            portfolio_beta=0.0,
+            long_exposure=empty_exposure,
+            short_exposure=empty_exposure,
+            options_exposure=empty_exposure,
+        )
+
+    # Get the summary card values
+    summary_dict = summary.to_dict()
+    formatted_values = format_summary_card_values(summary_dict)
+
+    # Extract the values from the formatted values
+    formatted_values[0]
+    net_exposure = formatted_values[1]
+    formatted_values[3]
+    beta_adjusted_net_exposure = formatted_values[4]
+    long_exposure = formatted_values[5]
+    short_exposure = formatted_values[7]
+    options_exposure = formatted_values[9]
+    formatted_values[11]
+
+    # Calculate the sum of exposures from the position details as they would appear in the UI
+
+    # Initialize counters for UI exposures
+    total_ui_market_value = 0.0
+    total_ui_beta_adjusted_exposure = 0.0
+    total_ui_delta_exposure = 0.0
+
+    # Process each group as it would be displayed in the UI
+
+    for group in groups:
+        # Get values as they would be displayed in the UI
+        market_value = (
+            group.net_exposure
+        )  # This is what's shown as "Total Value" in the UI
+        beta_adjusted = (
+            group.beta_adjusted_exposure
+        )  # This is what's shown as "Beta-Adjusted Exposure" in the UI
+        delta_exposure = (
+            group.total_delta_exposure
+        )  # This is what's shown as "Total Delta Exposure" in the UI
+
+        # Print the values for this group
+
+        # Add to totals
+        total_ui_market_value += market_value
+        total_ui_beta_adjusted_exposure += beta_adjusted
+        total_ui_delta_exposure += delta_exposure
+
+    # Extract numeric values from formatted strings
+    def extract_numeric(value):
+        return float(value.replace("$", "").replace(",", ""))
+
+    summary_net_exposure = extract_numeric(net_exposure)
+    summary_beta_adjusted_net_exposure = extract_numeric(beta_adjusted_net_exposure)
+    extract_numeric(long_exposure)
+    extract_numeric(short_exposure)
+    summary_options_exposure = extract_numeric(options_exposure)
+
+    # Compare with summary card values
+
+    # Calculate long and short exposures from UI values
+    ui_long_exposure = 0.0
+    ui_short_exposure = 0.0
+
+    for group in groups:
+        if group.stock_position:
+            stock = group.stock_position
+            if stock.quantity >= 0:  # Long position
+                ui_long_exposure += stock.market_value
+            else:  # Short position
+                ui_short_exposure += stock.market_value  # Already negative
+
+        # Process option positions
+        for opt in group.option_positions:
+            if opt.delta_exposure >= 0:  # Long position
+                ui_long_exposure += opt.delta_exposure
+            else:  # Short position
+                ui_short_exposure += opt.delta_exposure  # Already negative
+
+    # Determine if the summary card values match the UI values
+    if abs(summary_net_exposure - total_ui_market_value) < 0.01:
+        pass
+    else:
+        pass
+
+    if abs(summary_beta_adjusted_net_exposure - total_ui_beta_adjusted_exposure) < 0.01:
+        pass
+    else:
+        pass
+
+    if abs(summary_options_exposure - total_ui_delta_exposure) < 0.01:
+        pass
+    else:
+        pass
+
+
+if __name__ == "__main__":
+    compare_exposures()

scripts/debug_portfolio.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Portfolio Exposure Debugging Script
+
+This script loads a portfolio CSV file and prints out detailed exposure calculations.
+It can be used to debug exposure calculations for any portfolio.
+
+Usage:
+    python debug_portfolio.py [path_to_portfolio.csv]
+
+If no path is provided, it will use the default sample portfolio.
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+# Add the src directory to the Python path
+script_dir = Path(__file__).resolve().parent
+src_dir = script_dir.parent
+sys.path.append(str(src_dir))
+
+# Import after adding to path
+from src.folio.portfolio import process_portfolio_data  # noqa: E402
+
+
+def print_section_header(_title):
+    """Print a section header with formatting."""
+
+
+def print_exposure_breakdown(_name, breakdown):
+    """Print details of an exposure breakdown."""
+
+    # Calculate percentages
+    if breakdown.total_exposure > 0:
+        (breakdown.stock_exposure / breakdown.total_exposure) * 100
+        (breakdown.option_delta_exposure / breakdown.total_exposure) * 100
+
+    # Print components if available
+    if hasattr(breakdown, "components") and breakdown.components:
+        for _key, _value in breakdown.components.items():
+            pass
+
+
+def print_portfolio_summary(summary):
+    """Print a detailed portfolio summary."""
+    print_section_header("PORTFOLIO SUMMARY")
+
+    # Calculate options metrics
+    long_options = summary.long_exposure.option_delta_exposure
+    short_options = summary.short_exposure.option_delta_exposure
+    long_options - short_options
+
+    # Calculate stock metrics
+    long_stocks = summary.long_exposure.stock_exposure
+    short_stocks = summary.short_exposure.stock_exposure
+
+    # Calculate percentages
+    total_exposure = (
+        summary.long_exposure.total_exposure + summary.short_exposure.total_exposure
+    )
+    if total_exposure > 0:
+        options_exposure = long_options + short_options
+        (options_exposure / total_exposure) * 100
+        ((long_stocks + short_stocks) / total_exposure) * 100
+
+    # Calculate options exposure (absolute sum of long and short)
+    options_exposure = long_options + short_options
+
+    # Print exposure breakdowns
+    print_exposure_breakdown("LONG EXPOSURE", summary.long_exposure)
+    print_exposure_breakdown("SHORT EXPOSURE", summary.short_exposure)
+    print_exposure_breakdown("OPTIONS EXPOSURE", summary.options_exposure)
+
+
+def print_portfolio_groups(groups):
+    """Print details of portfolio groups."""
+    print_section_header("PORTFOLIO GROUPS")
+
+    for _i, group in enumerate(groups):
+        # Print stock position if available
+        if group.stock_position:
+            pass
+
+        # Print option positions if available
+        if group.option_positions:
+            for _j, _option in enumerate(group.option_positions):
+                pass
+
+
+def print_cash_like_positions(positions):
+    """Print details of cash-like positions."""
+    print_section_header("CASH-LIKE POSITIONS")
+
+    if not positions:
+        return
+
+    for _i, _pos in enumerate(positions):
+        pass
+
+
+def main():
+    """Main function to load portfolio and print exposure calculations."""
+    parser = argparse.ArgumentParser(
+        description="Debug portfolio exposure calculations"
+    )
+    parser.add_argument(
+        "portfolio_path",
+        nargs="?",
+        default=os.path.join(src_dir, "src", "folio", "assets", "sample-portfolio.csv"),
+        help="Path to portfolio CSV file",
+    )
+    args = parser.parse_args()
+
+    # Check if file exists
+    if not os.path.exists(args.portfolio_path):
+        sys.exit(1)
+
+    try:
+        # Load portfolio data
+        df = pd.read_csv(args.portfolio_path)
+
+        # Process portfolio data
+        groups, summary, _ = process_portfolio_data(df)
+
+        # Print portfolio groups
+        print_portfolio_groups(groups)
+
+        # Print cash-like positions
+        print_cash_like_positions(summary.cash_like_positions)
+
+        # Print portfolio summary (at the end for easy reference)
+        print_portfolio_summary(summary)
+
+    except Exception:
+        import traceback
+
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/folio-simulator.py

@@ -0,0 +1,903 @@
+#!/usr/bin/env python3
+# pylint: disable=print-statement,print-used
+# ruff: noqa: E402, F401
+"""
+Portfolio SPY Simulator
+
+This script simulates how a portfolio would respond to changes in SPY (S&P 500 ETF).
+It provides detailed analysis of the portfolio's behavior under different SPY price
+scenarios, helping investors understand their market exposure and risk profile.
+
+The script uses the Rich library to create beautiful, interactive terminal output
+with colorful tables and charts for better data visualization.
+
+Configuration:
+    The default parameters can be adjusted by modifying the constants at the top of this file.
+    - DEFAULT_SPY_RANGE: The default range of SPY changes to simulate (e.g., 20.0 for ±20%)
+    - DEFAULT_STEPS: The default number of steps in the simulation
+    - CHART_WIDTH: Width of the chart visualization
+    - CHART_HEIGHT: Height of the chart visualization
+    - PORTFOLIO_PATH: Path to the portfolio CSV file
+
+Usage:
+    # Recommended: Use the make target (activates virtual environment automatically)
+    make simulator [range=5] [steps=11] [focus=SPY,QQQ] [detailed=1]
+
+    # Alternative: Activate virtual environment first, then run the script
+    source venv/bin/activate
+    python scripts/folio-simulator.py [options]
+
+    # Show help
+    python scripts/folio-simulator.py --help
+
+Options:
+    --focus TICKERS    Comma-separated list of tickers to focus on (e.g., "SPY,QQQ,AAPL")
+    --range PERCENT    SPY change range in percent (default: 20.0)
+    --steps N          Number of steps in the simulation (default: 13)
+    --detailed         Show detailed analysis for all positions
+
+Examples:
+    # Run with default settings (±20% SPY range with 13 steps)
+    make simulator
+
+    # Run with a narrower range of ±5% SPY with 11 steps (1% increments)
+    make simulator range=5 steps=11
+
+    # Focus on a specific ticker with default range
+    make simulator focus=SPY
+
+    # Focus on multiple tickers with a custom range
+    make simulator focus=SPY,QQQ,AAPL range=15 steps=31
+
+    # Show detailed analysis for all positions
+    make simulator detailed=1
+
+Output:
+    The script provides several sections of output:
+
+    1. Portfolio Summary - A table showing current, minimum, and maximum portfolio values.
+
+    2. Portfolio Values Table - A detailed table showing portfolio values,
+       absolute changes, and percentage changes at each SPY change point.
+
+    3. Portfolio Value Chart - A visual chart showing how the
+       portfolio value changes across the SPY range.
+
+    4. Portfolio Value Summary - Key metrics including worst and best case scenarios.
+
+    5. Correlation Analysis - Tables showing positions with negative correlation to SPY
+       (lose value when SPY goes up) and inverse correlation (gain value when SPY goes down).
+
+    6. Portfolio Beta Analysis - The portfolio's beta for up and down moves, average
+       beta, and a note about non-linear behavior if applicable.
+
+Notes:
+    - The script requires a portfolio CSV file at 'private-data/portfolio-private.csv'.
+    - The script updates prices for all positions before running the simulation.
+    - When focusing on specific tickers, only those positions are included in the simulation.
+    - The script calculates implied beta based on the portfolio's response to SPY changes.
+"""
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+
+# Check if running in the correct environment
+# pylint: disable=import-outside-toplevel,unused-import
+def check_environment():
+    """Check if the script is running in the correct environment with all dependencies."""
+    try:
+        # Try to import pandas to check if dependencies are installed
+        import pandas
+
+        return True
+    except ImportError:
+        # If pandas is not found, provide helpful error message
+        # pylint: disable=multiple-statements
+        return False
+
+
+# Exit if not in the correct environment
+if not check_environment():
+    sys.exit(1)
+
+# Add the src directory to the Python path
+sys.path.append(str(Path(__file__).parent.parent))
+
+# pylint: disable=wrong-import-position
+import pandas as pd
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from src.folio.formatting import format_currency
+from src.folio.portfolio import process_portfolio_data
+from src.folio.simulator import simulate_portfolio_with_spy_changes
+
+console = Console()
+
+# Configurable constants
+DEFAULT_SPY_RANGE = 20.0  # Default range of SPY changes to simulate (±20%)
+DEFAULT_STEPS = 13  # Default number of steps (gives 1% increments for default range)
+CHART_WIDTH = 50  # Width of the ASCII chart visualization
+CHART_HEIGHT = 10  # Height of the ASCII chart visualization
+PORTFOLIO_PATH = "private-data/portfolio-private.csv"  # Path to the portfolio CSV file
+
+# Configure logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[
+        logging.FileHandler("spy_simulator_debug.log", mode="w"),
+        logging.StreamHandler(),
+    ],
+)
+# Set specific loggers to INFO to reduce noise
+logging.getLogger("matplotlib").setLevel(logging.INFO)
+logging.getLogger("PIL").setLevel(logging.INFO)
+
+
+def debug_simulate_portfolio(
+    portfolio_groups,
+    cash_like_positions=None,
+    pending_activity_value=0.0,
+    spy_range=10.0,
+    steps=21,
+):
+    """Run the portfolio simulator with detailed logging for debugging.
+
+    Args:
+        portfolio_groups: Dictionary of portfolio position groups
+        cash_like_positions: List of cash-like positions
+        pending_activity_value: Value of pending activity
+        spy_range: Range of SPY changes to simulate (e.g., 10.0 for ±10%)
+        steps: Number of steps in the simulation (default: 21)
+    """
+    logger = logging.getLogger("debug_simulator")
+    logger.info("Starting detailed portfolio simulation")
+    logger.info(f"Using SPY range of ±{spy_range}% with {steps} steps")
+
+    # Calculate the step size
+    step_size = (2 * spy_range) / (steps - 1) if steps > 1 else 0
+
+    # Generate the SPY changes
+    spy_changes = [-spy_range + i * step_size for i in range(steps)]
+
+    # Ensure we have a zero point
+    if 0.0 not in spy_changes and steps > 2:
+        # Find the closest point to zero and replace it with zero
+        closest_to_zero = min(spy_changes, key=lambda x: abs(x))
+        zero_index = spy_changes.index(closest_to_zero)
+        spy_changes[zero_index] = 0.0
+
+    # Convert to percentages
+    spy_changes = [change / 100.0 for change in spy_changes]
+
+    logger.info(f"SPY changes: {[f'{change:.1%}' for change in spy_changes]}")
+
+    # Get the original results from the simulator
+    results = simulate_portfolio_with_spy_changes(
+        portfolio_groups=portfolio_groups,
+        spy_changes=spy_changes,
+        cash_like_positions=cash_like_positions,
+        pending_activity_value=pending_activity_value,
+    )
+
+    # Add position-by-position analysis
+    logger.info("Analyzing position-by-position behavior")
+
+    # Track original values for each position
+    original_values = {}
+    zero_index = spy_changes.index(0.0)
+
+    # For each position, track how it changes with SPY
+    for group in portfolio_groups:
+        ticker = group.ticker
+        logger.info(f"Analyzing position: {ticker}")
+
+        # Calculate total market value
+        stock_value = group.stock_position.market_value if group.stock_position else 0
+        option_value = (
+            sum(op.market_value for op in group.option_positions)
+            if group.option_positions
+            else 0
+        )
+        total_market_value = stock_value + option_value
+
+        # Skip positions with no market value
+        if total_market_value == 0:
+            logger.info(f"  Skipping {ticker} - zero market value")
+            continue
+
+        # Log position details
+        logger.info(f"  Beta: {group.beta:.2f}")
+        logger.info(f"  Market Value: {format_currency(total_market_value)}")
+
+        if group.stock_position:
+            logger.info(
+                f"  Stock: {group.stock_position.quantity} shares @ {group.stock_position.price:.2f}"
+            )
+            logger.info(
+                f"    Stock Value: {format_currency(group.stock_position.market_value)}"
+            )
+
+        if group.option_positions:
+            logger.info(f"  Options: {len(group.option_positions)}")
+            for i, option in enumerate(group.option_positions):
+                logger.info(
+                    f"    Option {i + 1}: {option.quantity} {option.option_type} @ {option.strike:.2f}, expires {option.expiry}"
+                )
+                logger.info(
+                    f"      Price: {option.price:.4f}, Delta: {option.delta:.4f}"
+                )
+                logger.info(f"      Value: {format_currency(option.market_value)}")
+
+        # Calculate total market value
+        stock_value = group.stock_position.market_value if group.stock_position else 0
+        option_value = (
+            sum(op.market_value for op in group.option_positions)
+            if group.option_positions
+            else 0
+        )
+        total_market_value = stock_value + option_value
+
+        # Calculate expected behavior based on beta
+        expected_change_at_10pct = group.beta * 0.1 * total_market_value
+        logger.info(
+            f"  Expected change at +10% SPY: {format_currency(expected_change_at_10pct)}"
+        )
+
+        # Store original value
+        original_values[ticker] = total_market_value
+
+    # Analyze the results
+    logger.info("\nAnalyzing simulation results")
+
+    # Find positions with unexpected behavior
+
+    # Find the indices for min, max, and zero values
+    zero_index = next(
+        (i for i, change in enumerate(spy_changes) if abs(change) < 0.001), 0
+    )
+    min_index = 0  # First element (most negative)
+    max_index = len(spy_changes) - 1  # Last element (most positive)
+
+    # Calculate the total portfolio change
+    total_min = results["portfolio_values"][min_index]
+    total_zero = results["portfolio_values"][zero_index]
+    total_max = results["portfolio_values"][max_index]
+
+    min_change = spy_changes[min_index]
+    max_change = spy_changes[max_index]
+
+    logger.info(
+        f"Portfolio value at {min_change:.1%} SPY: {format_currency(total_min)}"
+    )
+    logger.info(f"Portfolio value at 0% SPY: {format_currency(total_zero)}")
+    logger.info(
+        f"Portfolio value at {max_change:.1%} SPY: {format_currency(total_max)}"
+    )
+
+    down_change = total_min - total_zero
+    up_change = total_max - total_zero
+
+    logger.info(
+        f"Change on {min_change:.1%} SPY: {format_currency(down_change)} ({down_change / total_zero * 100:.2f}%)"
+    )
+    logger.info(
+        f"Change on {max_change:.1%} SPY: {format_currency(up_change)} ({up_change / total_zero * 100:.2f}%)"
+    )
+
+    # Calculate implied beta
+    down_beta = -down_change / (total_zero * 0.1)
+    up_beta = up_change / (total_zero * 0.1)
+
+    logger.info(f"Implied beta on down moves: {down_beta:.2f}")
+    logger.info(f"Implied beta on up moves: {up_beta:.2f}")
+
+    # Add position-level analysis
+    if "position_values" in results:
+        logger.info("\nAnalyzing position-level contributions:")
+
+        # Calculate position-level changes
+        position_changes = {}
+        for ticker, values in results["position_values"].items():
+            if len(values) > zero_index:
+                base_value = values[zero_index]
+                if base_value == 0:
+                    continue
+
+                # Calculate changes at min and max SPY values
+                min_spy_value = values[min_index] if min_index < len(values) else 0
+                max_spy_value = values[max_index] if max_index < len(values) else 0
+
+                down_change = min_spy_value - base_value
+                up_change = max_spy_value - base_value
+
+                # Calculate percentage changes
+                down_pct = (down_change / base_value) * 100 if base_value != 0 else 0
+                up_pct = (up_change / base_value) * 100 if base_value != 0 else 0
+
+                # Store the changes
+                position_changes[ticker] = {
+                    "base_value": base_value,
+                    "min_spy_value": min_spy_value,
+                    "max_spy_value": max_spy_value,
+                    "down_change": down_change,
+                    "up_change": up_change,
+                    "down_pct": down_pct,
+                    "up_pct": up_pct,
+                }
+
+                logger.info(f"  {ticker}:")
+                logger.info(f"    Base Value: {format_currency(base_value)}")
+                logger.info(
+                    f"    Change at -10% SPY: {format_currency(down_change)} ({down_pct:.2f}%)"
+                )
+                logger.info(
+                    f"    Change at +10% SPY: {format_currency(up_change)} ({up_pct:.2f}%)"
+                )
+
+        # Find positions with largest contributions
+        sorted_down = sorted(
+            position_changes.items(), key=lambda x: x[1]["down_change"]
+        )
+        sorted_up = sorted(
+            position_changes.items(), key=lambda x: x[1]["up_change"], reverse=True
+        )
+
+        logger.info("\nLargest contributors to downside moves:")
+        for ticker, data in sorted_down[:5]:
+            logger.info(
+                f"  {ticker}: {format_currency(data['down_change'])} ({data['down_pct']:.2f}%)"
+            )
+
+        logger.info("\nLargest contributors to upside moves:")
+        for ticker, data in sorted_up[:5]:
+            logger.info(
+                f"  {ticker}: {format_currency(data['up_change'])} ({data['up_pct']:.2f}%)"
+            )
+
+    # Add the analysis to the results
+    results["analysis"] = {
+        "down_beta": down_beta,
+        "up_beta": up_beta,
+        "original_values": original_values,
+        "position_changes": position_changes if "position_values" in results else {},
+    }
+
+    # Add the portfolio groups to the results for position type identification
+    results["portfolio_groups"] = portfolio_groups
+
+    return results
+
+
+def main():
+    # Parse command line arguments
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Portfolio SPY Simulator - Analyze portfolio behavior under different SPY price scenarios",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Run with default settings (±20% SPY range with 13 steps)
+  python scripts/folio-simulator.py
+
+  # Run with a narrower range of ±5% SPY with 11 steps (1% increments)
+  python scripts/folio-simulator.py --range 5 --steps 11
+
+  # Focus on a specific ticker with default range
+  python scripts/folio-simulator.py --focus SPY
+
+  # Focus on multiple tickers with a custom range
+  python scripts/folio-simulator.py --focus SPY,QQQ,AAPL --range 15 --steps 31
+
+  # Show detailed analysis for all positions
+  python scripts/folio-simulator.py --detailed
+        """,
+    )
+
+    # Add a group for simulation parameters
+    sim_group = parser.add_argument_group("Simulation Parameters")
+    sim_group.add_argument(
+        "--range",
+        type=float,
+        default=DEFAULT_SPY_RANGE,
+        help=f"SPY change range in percent (default: ±{DEFAULT_SPY_RANGE}%%)",
+        metavar="PERCENT",
+    )
+    sim_group.add_argument(
+        "--steps",
+        type=int,
+        default=DEFAULT_STEPS,
+        help=f"Number of steps in the simulation (default: {DEFAULT_STEPS}, which gives {DEFAULT_SPY_RANGE / (DEFAULT_STEPS - 1) * 2:.1f}%% increments for default range)",
+        metavar="N",
+    )
+
+    # Add a group for filtering and display options
+    filter_group = parser.add_argument_group("Filtering and Display Options")
+    filter_group.add_argument(
+        "--focus",
+        type=str,
+        help="Comma-separated list of tickers to focus on (e.g., 'SPY,QQQ,AAPL')",
+        metavar="TICKERS",
+    )
+    filter_group.add_argument(
+        "--detailed",
+        action="store_true",
+        help="Show detailed analysis for all positions",
+    )
+
+    args = parser.parse_args()
+
+    # Path to the portfolio CSV file
+    csv_path = Path(os.getcwd()) / PORTFOLIO_PATH
+
+    if not csv_path.exists():
+        sys.exit(1)
+
+    try:
+        # Read the CSV file
+        df = pd.read_csv(csv_path)
+
+        # Process the portfolio data with price updates
+        groups, summary, _ = process_portfolio_data(df, update_prices=True)
+
+        # Filter portfolio if focus is specified
+        focus_tickers = []
+        if args.focus:
+            focus_tickers = [ticker.strip().upper() for ticker in args.focus.split(",")]
+
+            # Create a filtered portfolio with only the specified positions
+            filtered_groups = {}
+
+            # Convert list to dictionary if needed
+            if isinstance(groups, list):
+                groups_dict = {group.ticker: group for group in groups}
+            else:
+                groups_dict = groups
+
+            for ticker, group in groups_dict.items():
+                if ticker in focus_tickers:
+                    filtered_groups[ticker] = group
+
+            if not filtered_groups:
+                pass
+            # Use the filtered groups
+            elif isinstance(groups, list):
+                groups = list(filtered_groups.values())
+            else:
+                groups = filtered_groups
+
+        # Run the simulation with detailed debugging
+        results = debug_simulate_portfolio(
+            portfolio_groups=groups,
+            cash_like_positions=summary.cash_like_positions,
+            pending_activity_value=getattr(summary, "pending_activity_value", 0.0),
+            spy_range=args.range,
+            steps=args.steps,
+        )
+
+        # Print the results
+        # Get the current value (at 0% SPY change)
+        current_value = results["current_value"]
+
+        # Get min and max values
+        min_value = min(results["portfolio_values"])
+        max_value = max(results["portfolio_values"])
+        min_index = results["portfolio_values"].index(min_value)
+        max_index = results["portfolio_values"].index(max_value)
+        min_spy_change = (
+            results["spy_changes"][min_index] * 100
+        )  # Convert to percentage
+        max_spy_change = (
+            results["spy_changes"][max_index] * 100
+        )  # Convert to percentage
+
+        # Create a table of all SPY changes and portfolio values
+        if True:
+            console.print("\n[bold cyan]Portfolio Simulation Results[/bold cyan]")
+
+            # Create a summary table
+            summary_table = Table(title="Portfolio Summary", box=box.ROUNDED)
+            summary_table.add_column("Metric", style="cyan")
+            summary_table.add_column("Value", style="green")
+            summary_table.add_column("SPY Change", style="yellow")
+
+            summary_table.add_row("Current Value", f"${current_value:,.2f}", "0.0%")
+            summary_table.add_row(
+                "Minimum Value", f"${min_value:,.2f}", f"{min_spy_change:.1f}%"
+            )
+            summary_table.add_row(
+                "Maximum Value", f"${max_value:,.2f}", f"{max_spy_change:.1f}%"
+            )
+
+            console.print(summary_table)
+
+            # Create a detailed table with all values
+            value_table = Table(
+                title="Portfolio Values at Different SPY Changes", box=box.ROUNDED
+            )
+            value_table.add_column("SPY Change", style="yellow")
+            value_table.add_column("Portfolio Value", style="green")
+            value_table.add_column("Change", style="cyan")
+            value_table.add_column("% Change", style="magenta")
+
+            for i, spy_change in enumerate(results["spy_changes"]):
+                portfolio_value = results["portfolio_values"][i]
+                value_change = portfolio_value - current_value
+                pct_change = (
+                    (value_change / current_value) * 100 if current_value != 0 else 0
+                )
+
+                # Format the change with color based on positive/negative
+                change_str = f"${value_change:+,.2f}"
+                pct_change_str = f"{pct_change:+.2f}%"
+
+                value_table.add_row(
+                    f"{spy_change * 100:.1f}%",
+                    f"${portfolio_value:,.2f}",
+                    change_str,
+                    pct_change_str,
+                )
+
+            console.print(value_table)
+
+        # Create a visualization of the portfolio value curve
+
+        # Find min and max values for scaling
+        min_value = min(results["portfolio_values"])
+        max_value = max(results["portfolio_values"])
+        value_range = max_value - min_value
+
+        if True:
+            # Create a panel for the chart
+            chart_title = f"Portfolio Value vs SPY Change (Min: ${min_value:,.2f}, Max: ${max_value:,.2f})"
+
+            # Create the visualization using Unicode block characters for a smoother chart
+            chart = [" " * CHART_WIDTH for _ in range(CHART_HEIGHT)]
+
+            # Map SPY changes to x positions
+            x_positions = []
+            for spy_change in results["spy_changes"]:
+                # Map from min to max SPY change to 0 to CHART_WIDTH-1
+                min_spy = results["spy_changes"][0]
+                max_spy = results["spy_changes"][-1]
+                spy_range = max_spy - min_spy
+                x_pos = int((spy_change - min_spy) / spy_range * (CHART_WIDTH - 1))
+                x_positions.append(max(0, min(CHART_WIDTH - 1, x_pos)))
+
+            # Map portfolio values to y positions
+            y_positions = []
+            for value in results["portfolio_values"]:
+                if value_range > 0:
+                    # Map from min_value to max_value to 0 to CHART_HEIGHT-1
+                    y_pos = int((value - min_value) / value_range * (CHART_HEIGHT - 1))
+                    y_positions.append(max(0, min(CHART_HEIGHT - 1, y_pos)))
+                else:
+                    y_positions.append(CHART_HEIGHT // 2)
+
+            # Plot the points with different characters based on position
+            for x, y in zip(x_positions, y_positions, strict=False):
+                row = chart[y]
+                # Use different characters for different parts of the curve
+                if y == 0:  # Top of chart
+                    char = "▲"
+                elif y == CHART_HEIGHT - 1:  # Bottom of chart
+                    char = "▼"
+                else:
+                    char = "●"
+                chart[y] = row[:x] + char + row[x + 1 :]
+
+            # Create the chart string
+            chart_str = "\n".join(
+                ["|" + row + "|" for row in chart[::-1]]
+            )  # Reverse to show bottom to top
+
+            # Add a border
+            border = "+" + "-" * CHART_WIDTH + "+"
+            chart_str = border + "\n" + chart_str + "\n" + border
+
+            # Add axis labels
+            min_spy_label = f"{results['spy_changes'][0] * 100:.1f}%"
+            max_spy_label = f"{results['spy_changes'][-1] * 100:.1f}%"
+            zero_spy_index = next(
+                (
+                    i
+                    for i, change in enumerate(results["spy_changes"])
+                    if abs(change) < 0.001
+                ),
+                None,
+            )
+            zero_spy_label = "0.0%" if zero_spy_index is not None else ""
+
+            axis_labels = f"{min_spy_label}{' ' * (CHART_WIDTH - len(min_spy_label) - len(max_spy_label))}{max_spy_label}"
+            if zero_spy_index is not None:
+                zero_pos = int(
+                    zero_spy_index / (len(results["spy_changes"]) - 1) * CHART_WIDTH
+                )
+                axis_labels = (
+                    axis_labels[:zero_pos]
+                    + zero_spy_label
+                    + axis_labels[zero_pos + len(zero_spy_label) :]
+                )
+
+            chart_str += "\n" + axis_labels
+
+            # Create a panel with the chart
+            chart_panel = Panel(chart_str, title=chart_title, border_style="cyan")
+            console.print(chart_panel)
+
+        # Add value scale
+        value_range / 4 if value_range > 0 else 0
+
+        # Print summary analysis
+        min_value = min(results["portfolio_values"])
+        max_value = max(results["portfolio_values"])
+        min_change = min_value - current_value
+        max_change = max_value - current_value
+        min_pct_change = (min_change / current_value) * 100 if current_value != 0 else 0
+        max_pct_change = (max_change / current_value) * 100 if current_value != 0 else 0
+
+        min_index = results["portfolio_values"].index(min_value)
+        max_index = results["portfolio_values"].index(max_value)
+        min_spy_change = (
+            results["spy_changes"][min_index] * 100
+        )  # Convert to percentage
+        max_spy_change = (
+            results["spy_changes"][max_index] * 100
+        )  # Convert to percentage
+
+        # Print summary analysis
+        if True:
+            summary_table = Table(title="Portfolio Value Summary", box=box.ROUNDED)
+            summary_table.add_column("Scenario", style="cyan")
+            summary_table.add_column("Value", style="green")
+            summary_table.add_column("Change", style="magenta")
+            summary_table.add_column("SPY Change", style="yellow")
+
+            summary_table.add_row(
+                "Worst Case",
+                f"${min_value:,.2f}",
+                f"{min_pct_change:+.2f}%",
+                f"{min_spy_change:.1f}%",
+            )
+            summary_table.add_row(
+                "Best Case",
+                f"${max_value:,.2f}",
+                f"{max_pct_change:+.2f}%",
+                f"{max_spy_change:.1f}%",
+            )
+
+            console.print(summary_table)
+
+        # Print position-level analysis
+        if "position_values" in results:
+            # Find the indices for min, max, and zero values
+            try:
+                zero_index = next(
+                    (
+                        i
+                        for i, change in enumerate(results["spy_changes"])
+                        if abs(change) < 0.001
+                    ),
+                    0,
+                )
+                min_index = 0  # First element (most negative)
+                max_index = (
+                    len(results["spy_changes"]) - 1
+                )  # Last element (most positive)
+
+                # Calculate position-level changes
+                position_changes = {}
+                for ticker, values in results["position_values"].items():
+                    if len(values) > zero_index:
+                        base_value = values[zero_index]
+                        if base_value == 0:
+                            continue
+
+                        # Calculate changes at min and max SPY values
+                        min_spy_value = (
+                            values[min_index] if min_index < len(values) else 0
+                        )
+                        max_spy_value = (
+                            values[max_index] if max_index < len(values) else 0
+                        )
+
+                        down_change = min_spy_value - base_value
+                        up_change = max_spy_value - base_value
+
+                        # Calculate percentage changes
+                        down_pct = (
+                            (down_change / base_value) * 100 if base_value != 0 else 0
+                        )
+                        up_pct = (
+                            (up_change / base_value) * 100 if base_value != 0 else 0
+                        )
+
+                        # Store the changes
+                        position_changes[ticker] = {
+                            "base_value": base_value,
+                            "min_spy_value": min_spy_value,
+                            "max_spy_value": max_spy_value,
+                            "down_change": down_change,
+                            "up_change": up_change,
+                            "down_pct": down_pct,
+                            "up_pct": up_pct,
+                        }
+
+                # Get position details for comparison
+                position_details = results.get("position_details", {})
+
+                # Find positions with largest contributions
+                sorted_down = sorted(
+                    position_changes.items(), key=lambda x: x[1]["down_change"]
+                )
+                sorted_up = sorted(
+                    position_changes.items(),
+                    key=lambda x: x[1]["up_change"],
+                    reverse=True,
+                )
+
+                # Print positions with largest downside contributions
+                for ticker, data in sorted_down[:5]:
+                    # Calculate expected change based on beta
+                    beta = position_details.get(ticker, {}).get("beta", 0)
+                    base_value = data["base_value"]
+                    expected_change = (
+                        beta * min_spy_change * base_value
+                    )  # Expected change at min SPY
+                    actual_change = data["down_change"]
+                    difference = actual_change - expected_change
+                    (
+                        (difference / abs(expected_change)) * 100
+                        if expected_change != 0
+                        else 0
+                    )
+
+                # Print positions with largest upside contributions
+                for ticker, data in sorted_up[:5]:
+                    # Calculate expected change based on beta
+                    beta = position_details.get(ticker, {}).get("beta", 0)
+                    base_value = data["base_value"]
+                    expected_change = (
+                        beta * max_spy_change * base_value
+                    )  # Expected change at max SPY
+                    actual_change = data["up_change"]
+                    difference = actual_change - expected_change
+                    (
+                        (difference / abs(expected_change)) * 100
+                        if expected_change != 0
+                        else 0
+                    )
+
+                # Find positions that lose value when SPY goes up (negative correlation)
+                negative_correlation = []
+                for ticker, data in position_changes.items():
+                    # If position value decreases when SPY increases
+                    if data["up_change"] < 0:
+                        # For any ticker, provide detailed position analysis when requested
+                        if args.detailed:
+                            pass
+                        negative_correlation.append((ticker, data))
+
+                if negative_correlation:
+                    # Sort by the magnitude of negative impact
+                    negative_correlation.sort(key=lambda x: x[1]["up_change"])
+
+                    if True:
+                        # Create a table for positions that lose value when SPY goes up
+                        neg_corr_table = Table(
+                            title="Positions that LOSE value when SPY goes UP (negative correlation)",
+                            box=box.ROUNDED,
+                        )
+                        neg_corr_table.add_column("Ticker", style="cyan")
+                        neg_corr_table.add_column("Change", style="red")
+                        neg_corr_table.add_column("% Change", style="red")
+                        neg_corr_table.add_column("Beta", style="yellow")
+
+                        for ticker, data in negative_correlation:
+                            beta = position_details.get(ticker, {}).get("beta", 0)
+                            neg_corr_table.add_row(
+                                ticker,
+                                f"${data['up_change']:+,.2f}",
+                                f"{data['up_pct']:+.2f}%",
+                                f"{beta:+.2f}",
+                            )
+
+                        console.print(neg_corr_table)
+
+                # Find positions that gain value when SPY goes down (inverse correlation)
+                inverse_correlation = []
+                for ticker, data in position_changes.items():
+                    # If position value increases when SPY decreases
+                    if data["down_change"] > 0:
+                        inverse_correlation.append((ticker, data))
+
+                if inverse_correlation:
+                    # Sort by the magnitude of positive impact
+                    inverse_correlation.sort(
+                        key=lambda x: x[1]["down_change"], reverse=True
+                    )
+
+                    if True:
+                        # Create a table for positions that gain value when SPY goes down
+                        inv_corr_table = Table(
+                            title="Positions that GAIN value when SPY goes DOWN (inverse correlation)",
+                            box=box.ROUNDED,
+                        )
+                        inv_corr_table.add_column("Ticker", style="cyan")
+                        inv_corr_table.add_column("Change", style="green")
+                        inv_corr_table.add_column("% Change", style="green")
+                        inv_corr_table.add_column("Beta", style="yellow")
+
+                        for ticker, data in inverse_correlation:
+                            beta = position_details.get(ticker, {}).get("beta", 0)
+                            inv_corr_table.add_row(
+                                ticker,
+                                f"${data['down_change']:+,.2f}",
+                                f"{data['down_pct']:+.2f}%",
+                                f"{beta:+.2f}",
+                            )
+
+                        console.print(inv_corr_table)
+
+            except (StopIteration, IndexError):
+                pass
+
+        # Calculate the portfolio's beta based on the simulation results
+        try:
+            # Get the min and max values
+            min_index = 0  # First element (most negative)
+            max_index = len(results["spy_changes"]) - 1  # Last element (most positive)
+
+            min_value = results["portfolio_values"][min_index]
+            max_value = results["portfolio_values"][max_index]
+
+            min_spy_change = results["spy_changes"][min_index]
+            max_spy_change = results["spy_changes"][max_index]
+
+            min_pct_change = (min_value / current_value - 1) * 100
+            max_pct_change = (max_value / current_value - 1) * 100
+
+            # Calculate beta for up and down moves
+            beta_up = max_pct_change / (
+                max_spy_change * 100
+            )  # How much portfolio changes per 1% SPY up move
+            beta_down = min_pct_change / (
+                min_spy_change * 100
+            )  # How much portfolio changes per 1% SPY down move
+            (beta_up + beta_down) / 2
+
+            # Print beta analysis
+            if True:
+                beta_table = Table(title="Portfolio Beta Analysis", box=box.ROUNDED)
+                beta_table.add_column("Direction", style="cyan")
+                beta_table.add_column("Beta", style="yellow")
+
+                beta_table.add_row("Up Moves", f"{beta_up:.2f}")
+                beta_table.add_row("Down Moves", f"{beta_down:.2f}")
+                beta_table.add_row("Average", f"{(beta_up + beta_down) / 2:.2f}")
+
+                console.print(beta_table)
+
+                if abs(beta_up - beta_down) > 0.5:
+                    console.print(
+                        f"[bold yellow]Note:[/bold yellow] Beta difference of {abs(beta_up - beta_down):.2f} indicates non-linear behavior"
+                    )
+        except (StopIteration, IndexError):
+            pass
+
+    except Exception:
+        import traceback
+
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/install-reqs.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# Script to install all required dependencies for the omninmo project
+
+echo "Installing dependencies for omninmo..."
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+# Get the project root directory
+PROJECT_ROOT="$( cd "$SCRIPT_DIR/.." &> /dev/null && pwd )"
+
+# Check if we're in a virtual environment
+if [ -z "$VIRTUAL_ENV" ]; then
+    echo "Error: Not in a virtual environment. Please activate the virtual environment first."
+    exit 1
+fi
+
+# Function to check if a package is installed
+is_package_installed() {
+    python3 -m pip show "$1" &> /dev/null
+}
+
+# Install packages with proper flags to avoid system conflicts
+install_package() {
+    echo "Installing $1..."
+    python3 -m pip install --no-cache-dir "$1" --no-warn-script-location
+}
+
+# Install matplotlib separately first with specific flags
+echo "Installing matplotlib..."
+if ! is_package_installed "matplotlib"; then
+    CFLAGS="-I/opt/homebrew/include -I/opt/homebrew/include/freetype2" \
+    LDFLAGS="-L/opt/homebrew/lib" \
+    python3 -m pip install --no-cache-dir matplotlib --no-warn-script-location
+fi
+
+# Install Folio app dependencies from requirements.txt
+echo "Installing Folio app dependencies from requirements.txt..."
+while IFS= read -r package || [ -n "$package" ]; do
+    # Skip empty lines and comments
+    if [[ -z "$package" || "$package" =~ ^# ]]; then
+        continue
+    fi
+    install_package "$package"
+done < "$PROJECT_ROOT/requirements.txt"
+
+# Install additional development dependencies from requirements.txt
+echo "Installing additional development dependencies from requirements.txt..."
+while IFS= read -r package || [ -n "$package" ]; do
+    # Skip empty lines and comments
+    if [[ -z "$package" || "$package" =~ ^# ]]; then
+        continue
+    fi
+    # Skip matplotlib as we've already installed it
+    if [[ "$package" != matplotlib* ]]; then
+        install_package "$package"
+    fi
+done < "$PROJECT_ROOT/requirements.txt"
+
+# Install development tools from requirements-dev.txt
+echo "Installing development tools from requirements-dev.txt..."
+while IFS= read -r package || [ -n "$package" ]; do
+    # Skip empty lines and comments
+    if [[ -z "$package" || "$package" =~ ^# ]]; then
+        continue
+    fi
+    install_package "$package"
+done < "$PROJECT_ROOT/requirements-dev.txt"
+
+# Make all Python scripts executable
+echo "Making Python scripts executable..."
+chmod +x "$SCRIPT_DIR"/*.py
+
+echo "Installation complete!"

scripts/run_mlflow.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""
+Script to start the MLflow UI for viewing model training results.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+
+
+def main():
+    """Start the MLflow UI server"""
+    parser = argparse.ArgumentParser(description='Start the MLflow UI server')
+    parser.add_argument('--port', type=int, default=5000, help='Port to run the server on (default: 5000)')
+    parser.add_argument('--host', type=str, default='127.0.0.1', help='Host to run the server on (default: 127.0.0.1)')
+    args = parser.parse_args()
+
+    # Get the project root directory
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(script_dir)
+
+    # Set the MLflow tracking URI
+    mlruns_dir = os.path.join(project_root, 'mlruns')
+    tracking_uri = f"file:{mlruns_dir}"
+
+
+    # Start the MLflow UI
+    cmd = [
+        "mlflow", "ui",
+        "--backend-store-uri", tracking_uri,
+        "--host", args.host,
+        "--port", str(args.port)
+    ]
+
+    try:
+        subprocess.run(cmd, check=False)
+    except KeyboardInterrupt:
+        pass
+    except Exception:
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

scripts/setup-venv.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Script to set up and use a virtual environment for the omninmo project
+
+echo "Setting up virtual environment for omninmo..."
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+
+# Get the project root directory
+PROJECT_ROOT="$( cd "$SCRIPT_DIR/.." &> /dev/null && pwd )"
+
+# Define the virtual environment directory
+VENV_DIR="$PROJECT_ROOT/venv"
+
+# Check if python3 is installed
+if ! command -v python3 &> /dev/null; then
+    echo "Error: python3 is not installed. Please install python3 first."
+    exit 1
+fi
+
+# Check if venv module is available
+if ! python3 -m venv --help &> /dev/null; then
+    echo "Error: python3-venv is not installed. Please install it first."
+    echo "On Ubuntu/Debian: sudo apt-get install python3-venv"
+    echo "On Fedora: sudo dnf install python3-venv"
+    echo "On macOS: python3 -m pip install --user virtualenv"
+    exit 1
+fi
+
+# Create virtual environment if it doesn't exist
+if [ ! -d "$VENV_DIR" ]; then
+    echo "Creating virtual environment in $VENV_DIR..."
+    python3 -m venv "$VENV_DIR"
+    if [ $? -ne 0 ]; then
+        echo "Error: Failed to create virtual environment."
+        exit 1
+    fi
+    echo "Virtual environment created successfully."
+else
+    echo "Virtual environment already exists at $VENV_DIR."
+fi
+
+# Activate the virtual environment
+echo "Activating virtual environment..."
+source "$VENV_DIR/bin/activate"
+
+# Upgrade pip
+echo "Upgrading pip..."
+pip3 install --upgrade pip
+
+# Create a script to activate the virtual environment
+ACTIVATE_SCRIPT="$PROJECT_ROOT/activate-venv.sh"
+echo "Creating activation script at $ACTIVATE_SCRIPT..."
+cat > "$ACTIVATE_SCRIPT" << EOF
+#!/bin/bash
+# Script to activate the virtual environment
+source "$VENV_DIR/bin/activate"
+echo "Virtual environment activated. Run 'deactivate' to exit."
+EOF
+
+chmod +x "$ACTIVATE_SCRIPT"
+
+echo "Virtual environment setup complete!"
+echo "To activate the virtual environment, run: source $ACTIVATE_SCRIPT"
+echo "To install dependencies in the virtual environment, run: make install" 

scripts/validate_pnl.py

@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+"""
+Validation script for P&L calculations using real portfolio data.
+
+This script loads portfolio data from private-data/, processes the options,
+and validates P&L calculations for a position group (e.g., SPY options).
+"""
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+# Add the project root to the Python path
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.folio.pnl import (
+    calculate_strategy_pnl,
+    determine_price_range,
+    summarize_strategy_pnl,
+)
+from src.folio.portfolio import process_portfolio_data
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+def print_position_details(positions):
+    """
+    Print details of positions for debugging.
+
+    Args:
+        positions: List of positions
+    """
+
+    for _i, pos in enumerate(positions):
+        position_type = getattr(pos, "position_type", "unknown")
+        if position_type == "stock":
+            pass
+        elif position_type == "option":
+            pass
+        else:
+            pass
+
+
+def validate_pnl_for_group(group):
+    """
+    Validate P&L calculations for a position group.
+
+    Args:
+        group: Position group
+
+    Returns:
+        P&L data
+    """
+    # Collect all positions in the group
+    all_positions = []
+    if group.stock_position:
+        all_positions.append(group.stock_position)
+
+    all_positions.extend(group.option_positions)
+
+    if not all_positions:
+        logger.warning(f"No positions found in group {group.ticker}")
+        return None
+
+    # Print position details for debugging
+    print_position_details(all_positions)
+
+    # Get current price from stock position or first option position
+    current_price = None
+    if group.stock_position:
+        current_price = group.stock_position.price
+    elif group.option_positions:
+        # Try to estimate underlying price from notional value and quantity
+        first_option = group.option_positions[0]
+        if hasattr(first_option, "notional_value") and hasattr(
+            first_option, "quantity"
+        ):
+            # Notional value is 100 * underlying price * abs(quantity)
+            abs_quantity = abs(first_option.quantity)
+            if abs_quantity > 0:
+                current_price = first_option.notional_value / (100 * abs_quantity)
+
+    if current_price is None:
+        # Fallback to a default value
+        current_price = 100.0
+        logger.warning(
+            f"Could not determine current price for {group.ticker}, using default: ${current_price:.2f}"
+        )
+    else:
+        logger.info(f"Using current price for {group.ticker}: ${current_price:.2f}")
+
+    # Calculate price range
+    price_range = determine_price_range(all_positions, current_price)
+    logger.info(f"Price range: ${price_range[0]:.2f} to ${price_range[1]:.2f}")
+
+    # Calculate P&L using current price as entry price (default mode)
+    pnl_data_default = calculate_strategy_pnl(
+        all_positions, price_range=price_range, num_points=100, use_cost_basis=False
+    )
+
+    # Generate summary for default mode
+    summary_default = summarize_strategy_pnl(pnl_data_default, current_price)
+
+    # Calculate P&L using cost basis as entry price
+    pnl_data_cost_basis = calculate_strategy_pnl(
+        all_positions, price_range=price_range, num_points=100, use_cost_basis=True
+    )
+
+    # Generate summary for cost basis mode
+    summary_cost_basis = summarize_strategy_pnl(pnl_data_cost_basis, current_price)
+
+    # Return both sets of data
+    return {
+        "default": (pnl_data_default, summary_default),
+        "cost_basis": (pnl_data_cost_basis, summary_cost_basis),
+    }, current_price
+
+
+def plot_pnl(
+    pnl_data, summary, current_price, ticker, mode="default", output_dir=".tmp"
+):
+    """
+    Plot P&L data and save to file.
+
+    Args:
+        pnl_data: P&L data from calculate_strategy_pnl
+        summary: Summary data from summarize_strategy_pnl
+        current_price: Current price of the underlying
+        ticker: Ticker symbol
+        mode: Mode used for P&L calculation ("default" or "cost_basis")
+        output_dir: Directory to save plot
+    """
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Create figure
+    plt.figure(figsize=(12, 8))
+
+    # Plot combined P&L
+    plt.plot(
+        pnl_data["price_points"],
+        pnl_data["pnl_values"],
+        "b-",
+        linewidth=2,
+        label=f"{ticker} Strategy P&L",
+    )
+
+    # Plot individual position P&Ls
+    if "individual_pnls" in pnl_data:
+        for i, pos_pnl in enumerate(pnl_data["individual_pnls"]):
+            pos_desc = pos_pnl.get("position", {}).get("ticker", f"Position {i + 1}")
+            plt.plot(
+                pos_pnl["price_points"],
+                pos_pnl["pnl_values"],
+                "--",
+                linewidth=1,
+                alpha=0.5,
+                label=pos_desc,
+            )
+
+    # Add reference lines
+    plt.axhline(y=0, color="r", linestyle="-", alpha=0.3)
+    plt.axvline(
+        x=current_price,
+        color="g",
+        linestyle="--",
+        alpha=0.5,
+        label=f"Current Price: ${current_price:.2f}",
+    )
+
+    # Add breakeven points
+    for bp in summary["breakeven_points"]:
+        plt.axvline(x=bp, color="orange", linestyle=":", alpha=0.5)
+        plt.text(bp, 0, f"BE: ${bp:.2f}", rotation=90, verticalalignment="center")
+
+    # Add max profit/loss points
+    max_profit_price = summary["max_profit_price"]
+    max_profit = summary["max_profit"]
+    plt.plot(max_profit_price, max_profit, "go", markersize=8)
+    plt.text(
+        max_profit_price,
+        max_profit,
+        f"Max Profit: ${max_profit:.2f}",
+        verticalalignment="bottom",
+        horizontalalignment="center",
+    )
+
+    max_loss_price = summary["max_loss_price"]
+    max_loss = summary["max_loss"]
+    plt.plot(max_loss_price, max_loss, "ro", markersize=8)
+    plt.text(
+        max_loss_price,
+        max_loss,
+        f"Max Loss: ${max_loss:.2f}",
+        verticalalignment="top",
+        horizontalalignment="center",
+    )
+
+    # Add current P&L
+    current_pnl = summary["current_pnl"]
+    plt.plot(current_price, current_pnl, "yo", markersize=8)
+    plt.text(
+        current_price,
+        current_pnl,
+        f"Current P&L: ${current_pnl:.2f}",
+        verticalalignment="bottom",
+        horizontalalignment="right",
+    )
+
+    # Set labels and title
+    mode_label = "Using Cost Basis" if mode == "cost_basis" else "Using Current Price"
+    plt.title(f"P&L Analysis for {ticker} Position Group ({mode_label})")
+    plt.xlabel(f"{ticker} Price")
+    plt.ylabel("P&L ($)")
+    plt.grid(True, alpha=0.3)
+    plt.legend(loc="best")
+
+    # Save the plot
+    output_file = os.path.join(
+        output_dir, f"{ticker.lower()}_pnl_validation_{mode}.png"
+    )
+    plt.savefig(output_file)
+    logger.info(f"P&L plot saved to {output_file}")
+
+    # Close the figure to free memory
+    plt.close()
+
+
+def main():
+    """
+    Load portfolio data, process options, and validate P&L calculations.
+    """
+    # Find the most recent portfolio file in private-data/
+    private_data_dir = Path("private-data")
+    if not private_data_dir.exists():
+        logger.error(f"Private data directory not found: {private_data_dir}")
+        return
+
+    portfolio_files = list(private_data_dir.glob("pf-*.csv"))
+    if not portfolio_files:
+        logger.error(f"No portfolio files found in {private_data_dir}")
+        return
+
+    # Sort by filename (assuming format pf-YYYYMMDD.csv)
+    portfolio_files.sort(reverse=True)
+    portfolio_file = portfolio_files[0]
+    logger.info(f"Using portfolio file: {portfolio_file}")
+
+    # Load portfolio data
+    df = pd.read_csv(portfolio_file)
+    logger.info(f"Loaded portfolio data with {len(df)} positions")
+
+    # Process portfolio data
+    try:
+        # process_portfolio_data returns (groups, summary, cash_positions)
+        result = process_portfolio_data(df)
+        if isinstance(result, tuple) and len(result) >= 2:
+            groups, summary = result[0], result[1]
+            logger.info(
+                f"Portfolio data processed successfully with {len(groups)} groups"
+            )
+        else:
+            logger.error("Unexpected result format from process_portfolio_data")
+            return
+    except Exception as e:
+        logger.error(f"Error processing portfolio data: {e}")
+        return
+
+    # Find position groups to analyze
+    tickers_to_analyze = ["META", "AMZN", "GOOGL", "NVDA", "QQQ", "SPY"]
+
+    found_group = False
+    for ticker in tickers_to_analyze:
+        # Find the group with matching ticker
+        matching_groups = [g for g in groups if g.ticker == ticker]
+
+        if not matching_groups:
+            logger.warning(f"No {ticker} position group found in portfolio")
+            continue
+
+        group = matching_groups[0]
+        found_group = True
+
+        logger.info(f"Found {ticker} position group")
+        if group.option_positions:
+            logger.info(f"  Option positions: {len(group.option_positions)}")
+        if group.stock_position:
+            logger.info(f"  Stock position: {group.stock_position.quantity} shares")
+
+        # Validate P&L calculations
+        try:
+            pnl_results, current_price = validate_pnl_for_group(group)
+            if pnl_results:
+                # Process default mode
+                pnl_data, summary = pnl_results["default"]
+
+                # Print P&L data structure validation
+
+                # Check if pnl_data has the expected structure
+                for key in pnl_data.keys():
+                    if key == "individual_pnls":
+                        for _i, _pos_pnl in enumerate(pnl_data[key]):
+                            pass
+
+                # Print individual position contributions at max profit price
+                max_profit_price = summary["max_profit_price"]
+                max_profit_idx = 0
+                for i, price in enumerate(pnl_data["price_points"]):
+                    if abs(price - max_profit_price) < 0.01:  # Find closest price point
+                        max_profit_idx = i
+                        break
+
+                total_pnl = 0
+                for i, pos_pnl in enumerate(pnl_data["individual_pnls"]):
+                    pos_desc = pos_pnl.get("position", {}).get(
+                        "ticker", f"Position {i + 1}"
+                    )
+                    pos_type = pos_pnl.get("position", {}).get(
+                        "position_type", "unknown"
+                    )
+                    pos_pnl.get("position", {}).get("quantity", 0)
+
+                    if pos_type == "option":
+                        option_type = pos_pnl.get("position", {}).get("option_type", "")
+                        strike = pos_pnl.get("position", {}).get("strike", 0)
+                        pos_desc = f"{pos_desc} {option_type} {strike}"
+
+                    pnl_at_max = pos_pnl["pnl_values"][max_profit_idx]
+                    total_pnl += pnl_at_max
+
+                # Also check at current price
+                # Find the closest price point to current price
+                price_points = np.array(pnl_data["price_points"])
+                current_idx = np.abs(price_points - current_price).argmin()
+
+                total_current_pnl = 0
+                for i, pos_pnl in enumerate(pnl_data["individual_pnls"]):
+                    pos_desc = pos_pnl.get("position", {}).get(
+                        "ticker", f"Position {i + 1}"
+                    )
+                    pos_type = pos_pnl.get("position", {}).get(
+                        "position_type", "unknown"
+                    )
+                    pos_pnl.get("position", {}).get("quantity", 0)
+
+                    if pos_type == "option":
+                        option_type = pos_pnl.get("position", {}).get("option_type", "")
+                        strike = pos_pnl.get("position", {}).get("strike", 0)
+                        pos_desc = f"{pos_desc} {option_type} {strike}"
+
+                    pnl_at_current = pos_pnl["pnl_values"][current_idx]
+                    total_current_pnl += pnl_at_current
+
+                # Debug the current P&L calculation
+
+                # Get the cost basis summary
+                pnl_data_cost_basis, summary_cost_basis = pnl_results["cost_basis"]
+
+                # Print individual position P&Ls at current price
+                for i, pos_pnl in enumerate(pnl_data["individual_pnls"]):
+                    pos_desc = pos_pnl.get("position", {}).get(
+                        "ticker", f"Position {i + 1}"
+                    )
+                    pos_type = pos_pnl.get("position", {}).get(
+                        "position_type", "unknown"
+                    )
+
+                    if pos_type == "option":
+                        option_type = pos_pnl.get("position", {}).get("option_type", "")
+                        strike = pos_pnl.get("position", {}).get("strike", 0)
+                        pos_desc = f"{pos_desc} {option_type} {strike}"
+
+                    pnl_at_current = pos_pnl["pnl_values"][current_idx]
+
+                # Print summary
+
+                # Plot P&L for default mode
+                plot_pnl(pnl_data, summary, current_price, ticker, mode="default")
+
+                # We already got the cost basis data above
+
+                # Plot P&L for cost basis mode
+                plot_pnl(
+                    pnl_data_cost_basis,
+                    summary_cost_basis,
+                    current_price,
+                    ticker,
+                    mode="cost_basis",
+                )
+
+                logger.info(f"P&L validation completed for {ticker} in both modes")
+                break  # Process only the first valid group
+            else:
+                logger.warning(f"No P&L data generated for {ticker}")
+        except Exception as e:
+            logger.error(f"Error validating P&L for {ticker}: {e}", exc_info=True)
+
+    if not found_group:
+        logger.error(
+            "No valid position groups found for analysis. Please check the portfolio data."
+        )
+
+
+if __name__ == "__main__":
+    main()

src/__init__.py

@@ -0,0 +1,8 @@
+# src package initialization
+"""
+omninmo source package.
+"""
+
+"""
+Package initialization for src.
+"""

src/fmp.py

@@ -0,0 +1,243 @@
+"""
+Data fetcher for stock data using Financial Modeling Prep API
+"""
+
+import logging
+import os
+from datetime import datetime, timedelta
+
+import pandas as pd
+import requests
+
+from src.stockdata import DataFetcherInterface
+
+# Setup logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Constants
+HTTP_SUCCESS = 200
+
+
+class DataFetcher(DataFetcherInterface):
+    """Class to fetch stock data from Financial Modeling Prep API"""
+
+    # Default period for beta calculations
+    beta_period = "3m"
+
+    def __init__(self, cache_dir=".cache_fmp"):
+        """Initialize with cache directory"""
+        self.cache_dir = cache_dir
+        self.api_key = os.environ.get("FMP_API_KEY")
+
+        # If not in environment, try to get from config
+        if not self.api_key:
+            try:
+                from src.v2.config import config
+
+                self.api_key = config.get("data.fmp.api_key")
+            except ImportError:
+                logger.warning(
+                    "Could not import config from src.v2.config, will rely on environment variable"
+                )
+
+        self.cache_ttl = 86400  # Default to 1 day
+
+        # Try to get cache TTL from config if available
+        try:
+            from src.v2.config import config
+
+            self.cache_ttl = config.get("app.cache.ttl", 86400)
+        except ImportError:
+            logger.warning(
+                "Could not import config from src.v2.config, using default cache TTL"
+            )
+
+        # Create cache directory if it doesn't exist
+        os.makedirs(cache_dir, exist_ok=True)
+
+        # Check for API key
+        if not self.api_key:
+            raise ValueError(
+                "No API key found. Please set the FMP_API_KEY environment variable or "
+                "configure it in the config file."
+            )
+
+    def fetch_data(self, ticker, period="3m", interval="1d"):
+        """
+        Fetch stock data for a ticker
+
+        Args:
+            ticker (str): Stock ticker symbol
+            period (str): Time period ('3m', '6m', '1y', etc.)
+            interval (str): Data interval ('1d', '1wk', etc.)
+
+        Returns:
+            pandas.DataFrame: DataFrame with stock data
+
+        Raises:
+            ValueError: If no data is returned from API
+        """
+        # Check cache first
+        cache_file = os.path.join(self.cache_dir, f"{ticker}_{period}_{interval}.csv")
+
+        # Use the centralized cache validation logic
+        from src.stockdata import should_use_cache
+
+        should_use, reason = should_use_cache(cache_file, self.cache_ttl)
+
+        if should_use:
+            logger.debug(f"Loading cached data for {ticker}: {reason}")
+            return pd.read_csv(cache_file, index_col=0, parse_dates=True)
+        else:
+            logger.debug(f"Cache for {ticker} is not valid: {reason}")
+
+        # Try to fetch from API
+        try:
+            logger.info(f"Fetching data for {ticker} from API")
+            df = self._fetch_from_api(ticker, period)
+
+            if df is not None and not df.empty:
+                # Save to cache
+                df.to_csv(cache_file)
+                return df
+            else:
+                # This is a valid case - API returned no data for a valid ticker
+                logger.warning(f"No data returned from API for {ticker}")
+                # Raise a specific error instead of returning an empty DataFrame
+                raise ValueError(f"No historical data found for {ticker}")
+        except (ValueError, requests.exceptions.RequestException) as e:
+            # These are expected errors that can happen with valid inputs
+            # For example, a valid ticker that has no data available or network issues
+            logger.warning(f"Data fetch error for {ticker}: {e}")
+
+            # Only use expired cache for expected data errors, not for programming errors
+            if os.path.exists(cache_file):
+                logger.warning(f"Using expired cache for {ticker} as fallback")
+                try:
+                    return pd.read_csv(cache_file, index_col=0, parse_dates=True)
+                except (pd.errors.ParserError, pd.errors.EmptyDataError) as cache_e:
+                    logger.error(f"Error reading cache for {ticker}: {cache_e}")
+                    # If we can't read the cache, re-raise the original error
+                    raise e from cache_e
+
+            # If this is a "No historical data" error and we have no cache,
+            # it's reasonable to return an empty DataFrame with the expected structure
+            if "No historical data found" in str(e):
+                logger.warning(
+                    f"No historical data found for {ticker} and no cache available"
+                )
+                return pd.DataFrame(columns=["Open", "High", "Low", "Close", "Volume"])
+
+            # For other data errors with no cache, re-raise
+            raise
+        except (ImportError, NameError, AttributeError, TypeError, SyntaxError) as e:
+            # These are programming errors that should never be caught silently
+            logger.critical(f"Critical error in data fetcher: {e}", exc_info=True)
+            raise
+        except Exception as e:
+            # For other unexpected errors, log and re-raise
+            logger.error(
+                f"Unexpected error fetching data for {ticker}: {e}", exc_info=True
+            )
+            raise
+
+    def fetch_market_data(self, market_index="SPY", period=None, interval="1d"):
+        """
+        Fetch market index data for beta calculations.
+
+        Args:
+            market_index (str): Market index ticker symbol (default: 'SPY' for S&P 500 ETF)
+            period (str, optional): Time period. If None, uses beta_period.
+            interval (str): Data interval ('1d', '1wk', etc.)
+
+        Returns:
+            pandas.DataFrame: DataFrame with market index data
+        """
+        # Use the class beta_period if period is None
+        if period is None:
+            period = self.beta_period
+            logger.info(f"Using default beta period: {period}")
+
+        logger.debug(f"Fetching market data for {market_index}")
+        return self.fetch_data(market_index, period, interval)
+
+    def _fetch_from_api(self, ticker, period="5y"):
+        """Fetch data from Financial Modeling Prep API"""
+        # Determine date range based on period
+        end_date = datetime.now()
+
+        if period.endswith("y"):
+            years = int(period[:-1])
+            start_date = end_date - timedelta(days=365 * years)
+        elif period.endswith("m"):
+            months = int(period[:-1])
+            start_date = end_date - timedelta(days=30 * months)
+        else:
+            # Default to 1 year
+            start_date = end_date - timedelta(days=365)
+
+        # Format dates for API
+        start_str = start_date.strftime("%Y-%m-%d")
+        end_str = end_date.strftime("%Y-%m-%d")
+
+        # Construct API URL
+        base_url = "https://financialmodelingprep.com/api/v3/historical-price-full"
+        url = f"{base_url}/{ticker}?from={start_str}&to={end_str}&apikey={self.api_key}"
+
+        # Make request
+        response = requests.get(url)
+
+        if response.status_code != HTTP_SUCCESS:
+            raise ValueError(
+                f"API request failed with status code {response.status_code}: {response.text}"
+            )
+
+        # Parse response
+        data = response.json()
+
+        if "historical" not in data:
+            # This is not a critical error - just log a warning and return empty DataFrame
+            logger.warning(f"No historical data found for {ticker}")
+            return pd.DataFrame(columns=["Open", "High", "Low", "Close", "Volume"])
+
+        # Convert to DataFrame
+        df = pd.DataFrame(data["historical"])
+
+        # Convert date to datetime and set as index
+        df["date"] = pd.to_datetime(df["date"])
+        df = df.set_index("date")
+
+        # Sort by date (ascending)
+        df = df.sort_index()
+
+        # Rename columns to match expected format
+        df = df.rename(
+            columns={
+                "open": "Open",
+                "high": "High",
+                "low": "Low",
+                "close": "Close",
+                "volume": "Volume",
+            }
+        )
+
+        return df
+
+    def _fetch_data(self, url, params=None):
+        try:
+            response = requests.get(url, params=params)
+            if response.status_code == HTTP_SUCCESS:
+                return response.json()
+            else:
+                logger.error(f"Failed to fetch data: {response.status_code}")
+                return None
+        except Exception as e:
+            logger.error(f"Error fetching data: {e}")
+            return None
+
+
+if __name__ == "__main__":
+    # Simple test
+    fetcher = DataFetcher()
+    data = fetcher.fetch_data("AAPL", period="1y")

src/folio/README.md

@@ -0,0 +1,119 @@
+# Folio - Portfolio Dashboard
+
+## Overview
+
+Folio is a web-based dashboard for analyzing and visualizing investment portfolios. It provides a comprehensive view of your portfolio's composition, risk metrics, and exposure analysis with a focus on stocks and options.
+
+## Features
+
+- **Portfolio Analysis**: View your entire portfolio with key metrics like value, beta, and exposure
+- **Position Grouping**: Automatically groups stocks with their related options
+- **Risk Metrics**: Calculates beta and beta-adjusted exposure for all positions
+- **Options Analysis**: Provides delta exposure and other option-specific metrics
+- **Interactive UI**: Filter, sort, and search your portfolio with real-time updates
+- **Position Details**: Drill down into specific positions for detailed analysis
+- **CSV Import**: Upload portfolio data from CSV exports (compatible with Fidelity exports)
+- **Auto-Refresh**: Periodically refreshes data to keep metrics current
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.9+
+- Required packages (see `requirements.txt` in the project root)
+
+### Running the Dashboard
+
+```bash
+# From the project root directory:
+
+# Start with default settings (will prompt for file upload)
+make folio
+
+# Start with a specific portfolio file
+make folio portfolio=path/to/portfolio.csv
+
+# Or run directly with Python
+python -m src.folio --portfolio path/to/portfolio.csv --port 8051
+```
+
+The dashboard will be available at http://127.0.0.1:8051/ (or your specified port).
+
+## Project Structure
+
+```
+src/folio/
+├── __init__.py         # Package initialization
+├── __main__.py         # Entry point for running as a module
+├── app.py              # Main Dash application setup and callbacks
+├── components/         # UI components
+│   ├── __init__.py
+│   ├── portfolio_table.py  # Portfolio table component
+│   └── position_details.py # Position details modal
+├── data_model.py       # Data models and type definitions
+├── logger.py           # Logging configuration
+└── utils.py            # Utility functions for data processing
+```
+
+## Data Model
+
+The application uses the following key data structures:
+
+- **Position**: Base class for all positions (stocks and options)
+- **StockPosition**: Represents a stock position
+- **OptionPosition**: Represents an option position with strike, expiry, etc.
+- **PortfolioGroup**: Groups a stock with its related options
+- **PortfolioSummary**: Contains aggregated metrics for the entire portfolio
+- **ExposureBreakdown**: Detailed breakdown of exposure metrics
+
+## Development Guide
+
+### Adding New Features
+
+1. **UI Components**: Add new components in the `components/` directory
+2. **Data Processing**: Extend the data model in `data_model.py` and processing logic in `utils.py`
+3. **Callbacks**: Add new callbacks in `app.py` to handle user interactions
+
+### Coding Standards
+
+- Use type hints for all functions and methods
+- Document functions with docstrings (Google style)
+- Log important operations and errors using the logger
+- Handle exceptions gracefully with appropriate error messages
+- Follow the existing pattern for callback registration
+
+### Testing
+
+While there's no formal test suite yet, you can test your changes by:
+
+1. Running the application with a sample portfolio
+2. Verifying that all UI components render correctly
+3. Checking that calculations produce expected results
+4. Testing edge cases (empty portfolio, invalid data, etc.)
+
+## Troubleshooting
+
+### Common Issues
+
+- **Missing Data**: Ensure your CSV has all required columns (Symbol, Description, Quantity, etc.)
+- **Port Conflicts**: If the default port is in use, specify a different port with `--port`
+- **Data Fetching Errors**: Check network connectivity for beta data retrieval
+
+### Logging
+
+Logs are stored in the `logs/` directory with timestamps. Check these logs for detailed error information.
+
+## Future Improvements
+
+- Add unit tests for core functionality
+- Implement additional portfolio metrics (Sharpe ratio, VaR, etc.)
+- Add visualization components (charts, graphs)
+- Support for additional data sources beyond CSV
+- Enhanced options analytics with Greeks (gamma, theta, vega)
+
+## Contributing
+
+1. Follow the existing code style and patterns
+2. Document your changes thoroughly
+3. Test your changes with various portfolio data
+4. Submit a pull request with a clear description of your changes

src/folio/__init__.py

@@ -0,0 +1,3 @@
+"""Folio - Portfolio Dashboard"""
+
+__version__ = "0.1.0"

src/folio/__main__.py

@@ -0,0 +1,4 @@
+from .app import main
+
+if __name__ == "__main__":
+    main()

src/folio/ai_utils.py

@@ -0,0 +1,111 @@
+"""Utility functions for AI portfolio analysis."""
+
+import logging
+from typing import Any
+
+from .data_model import PortfolioGroup, PortfolioSummary
+from .portfolio import calculate_position_weight
+from .portfolio_value import (
+    calculate_component_percentages,
+    get_portfolio_component_values,
+)
+
+logger = logging.getLogger(__name__)
+
+# System prompt for the AI portfolio advisor
+PORTFOLIO_ADVISOR_SYSTEM_PROMPT = """
+You are a professional financial advisor specializing in portfolio analysis. Your role is strictly limited to:
+
+1. Analyzing the client's investment portfolio
+2. Providing insights on portfolio composition, risk, diversification, and performance
+3. Offering investment advice related to the client's holdings
+4. Answering questions about financial markets, investment strategies, and specific securities
+
+Important guidelines:
+- ONLY respond to questions related to investing, finance, and the client's portfolio
+- REFUSE to answer any questions unrelated to finance or investments
+- If asked about non-financial topics, politely redirect the conversation back to the portfolio
+- Maintain a professional, knowledgeable tone
+- Base your analysis on the portfolio data provided
+- Be transparent about limitations in your analysis
+- When discussing portfolio allocation, refer to the detailed breakdown provided in the context
+- When discussing exposure, consider both the raw exposure values and beta-adjusted values
+- Pay attention to the percentage of portfolio for each metric to provide context
+
+Your goal is to help clients understand their investments and make informed decisions about their portfolio.
+"""
+
+
+def prepare_portfolio_data_for_analysis(
+    groups: list[PortfolioGroup], summary: PortfolioSummary
+) -> dict[str, Any]:
+    """
+    Prepare portfolio data for AI analysis.
+
+    Args:
+        groups: List of portfolio groups
+        summary: Portfolio summary object
+
+    Returns:
+        Dictionary with formatted portfolio data
+    """
+    positions = []
+
+    # Process each portfolio group
+    for group in groups:
+        # Add stock position if present
+        if group.stock_position:
+            stock = group.stock_position
+            positions.append(
+                {
+                    "ticker": stock.ticker,
+                    "position_type": "stock",
+                    "market_value": stock.market_exposure,
+                    "beta": stock.beta,
+                    "weight": calculate_position_weight(
+                        stock.market_exposure, summary.net_market_exposure
+                    ),
+                    "quantity": stock.quantity,
+                }
+            )
+
+        # Add option positions if present
+        for option in group.option_positions:
+            positions.append(
+                {
+                    "ticker": option.ticker,
+                    "position_type": "option",
+                    "market_value": option.market_exposure,
+                    "beta": option.beta,
+                    "weight": calculate_position_weight(
+                        option.market_exposure, summary.net_market_exposure
+                    ),
+                    "option_type": option.option_type,
+                    "strike": option.strike,
+                    "expiry": option.expiry,
+                    "delta": option.delta,
+                }
+            )
+
+    # Enhanced summary data with portfolio value
+    summary_data = {
+        "portfolio_value": summary.portfolio_estimate_value,
+        "net_market_exposure": summary.net_market_exposure,
+        "long_exposure": summary.long_exposure.to_dict(),
+        "short_exposure": summary.short_exposure.to_dict(),
+        "options_exposure": summary.options_exposure.to_dict(),
+        "cash_like_value": summary.cash_like_value,
+    }
+
+    # Get allocation data from existing portfolio_value functions
+    values = get_portfolio_component_values(summary)
+    percentages = calculate_component_percentages(values)
+
+    # Create allocation data structure
+    allocation_data = {"values": values, "percentages": percentages}
+
+    return {
+        "positions": positions,
+        "summary": summary_data,
+        "allocations": allocation_data,
+    }

src/folio/app.py

@@ -0,0 +1,1073 @@
+"""
+Main application module for the Folio app.
+
+This module contains the main application logic for the Folio app.
+"""
+
+import argparse
+import base64
+import io
+import json
+import os
+import sys
+from pathlib import Path
+
+import dash
+import dash_bootstrap_components as dbc
+import pandas as pd
+from dash import ALL, Input, Output, State, dcc, html
+from dash_bootstrap_templates import load_figure_template
+
+from . import portfolio
+from .components import create_premium_chat_component, register_premium_chat_callbacks
+from .components.charts import create_dashboard_section
+from .components.charts import register_callbacks as register_chart_callbacks
+from .components.pnl_chart import create_pnl_modal
+from .components.pnl_chart import register_callbacks as register_pnl_callbacks
+from .components.portfolio_table import create_portfolio_table
+from .components.summary_cards import create_summary_cards
+from .data_model import OptionPosition, PortfolioGroup, StockPosition
+from .error_utils import handle_callback_error
+from .logger import logger
+from .security import sanitize_dataframe, validate_csv_upload
+
+# Load the Bootstrap template for Plotly figures
+load_figure_template("bootstrap")
+
+
+def create_header() -> dbc.Card:
+    """Create the header section with summary cards"""
+    # Use the create_summary_cards function from summary_cards.py
+    return create_summary_cards()
+
+
+def create_empty_state() -> html.Div:
+    """Create the empty state with instructions"""
+    # Check if private portfolio exists
+    private_path = Path(os.getcwd()) / "private-data" / "portfolio-private.csv"
+    button_label = (
+        "Load Private Portfolio" if private_path.exists() else "Load Sample Portfolio"
+    )
+
+    return html.Div(
+        [
+            html.H4("Welcome to Folio", className="text-center mb-3"),
+            html.P(
+                "Upload your portfolio CSV file to get started", className="text-center"
+            ),
+            html.Div(
+                [
+                    html.I(className="fas fa-upload fa-3x"),
+                ],
+                className="text-center my-4",
+            ),
+            html.P(
+                "Or try a sample portfolio to explore the features",
+                className="text-center mt-3",
+            ),
+            dbc.Button(
+                button_label,
+                id="load-sample",
+                color="primary",
+                className="mx-auto d-block",
+            ),
+            # Keyboard shortcut hint removed
+        ],
+        className="empty-state py-5",
+    )
+
+
+def create_upload_section() -> dbc.Card:
+    """Create the file upload section with collapsible functionality"""
+    return dbc.Card(
+        [
+            dbc.CardHeader(
+                dbc.Button(
+                    [
+                        html.I(className="fas fa-upload me-2"),
+                        html.Span("Upload Portfolio"),
+                        html.I(
+                            className="fas fa-chevron-down ms-2", id="collapse-icon"
+                        ),
+                    ],
+                    id="upload-collapse-button",
+                    color="link",
+                    className="text-decoration-none text-dark p-0 d-flex align-items-center",
+                ),
+                className="d-flex justify-content-between align-items-center",
+            ),
+            dbc.Collapse(
+                dbc.CardBody(
+                    [
+                        dcc.Upload(
+                            id="upload-portfolio",
+                            children=html.Div(
+                                [
+                                    html.I(className="fas fa-file-upload me-2"),
+                                    "Drag and Drop or ",
+                                    html.A(
+                                        "Select a CSV File", className="text-primary"
+                                    ),
+                                ]
+                            ),
+                            style={
+                                "width": "100%",
+                                "height": "60px",
+                                "lineHeight": "60px",
+                                "textAlign": "center",
+                                "margin": "10px 0",
+                            },
+                            # Filter for CSV files
+                            accept=".csv",
+                            multiple=False,
+                        ),
+                        dcc.Loading(
+                            id="upload-loading",
+                            type="circle",
+                            children=[html.Div(id="upload-status")],
+                        ),
+                    ]
+                ),
+                id="upload-collapse",
+                is_open=True,  # Initially open
+            ),
+        ],
+        className="mb-3",
+    )
+
+
+def create_filters() -> dbc.InputGroup:
+    """Create the search and filter controls"""
+    return dbc.InputGroup(
+        [
+            dbc.Input(
+                id="search-input",
+                type="text",
+                placeholder="Search positions...",
+                className="border-end-0",
+            ),
+            dbc.InputGroupText(
+                html.I(className="fas fa-search"),
+                className="bg-transparent border-start-0",
+            ),
+            dbc.Button(
+                "All",
+                id="filter-all",
+                color="primary",
+                outline=True,
+                className="ms-2",
+            ),
+            dbc.Button(
+                "Stocks",
+                id="filter-stocks",
+                color="primary",
+                outline=True,
+                className="ms-2",
+            ),
+            dbc.Button(
+                "Options",
+                id="filter-options",
+                color="primary",
+                outline=True,
+                className="ms-2",
+            ),
+            dbc.Button(
+                "Cash",
+                id="filter-cash",
+                color="primary",
+                outline=True,
+                className="ms-2",
+            ),
+        ],
+        className="mb-3",
+    )
+
+
+def create_main_table() -> html.Div:
+    """Create the main portfolio table"""
+    return html.Div(
+        [
+            html.Div(
+                id="portfolio-table",
+                className="portfolio-table-container",
+            ),
+            # Add a Store to track sort state
+            dcc.Store(id="sort-state", data={"column": "value", "direction": "desc"}),
+        ]
+    )
+
+
+def create_position_modal() -> dbc.Modal:
+    """Create the position details modal"""
+    return dbc.Modal(
+        [
+            dbc.ModalHeader(
+                dbc.ModalTitle("Position Details"),
+                close_button=True,
+            ),
+            dbc.ModalBody(id="position-modal-body"),
+        ],
+        id="position-modal",
+        size="lg",
+    )
+
+
+def create_app(portfolio_file: str | None = None, _debug: bool = False) -> dash.Dash:
+    """Create and configure the Dash application"""
+    logger.debug("Initializing Dash application")
+
+    # Create Dash app
+    app = dash.Dash(
+        __name__,
+        external_stylesheets=[
+            dbc.themes.BOOTSTRAP,
+            "https://use.fontawesome.com/releases/v5.15.4/css/all.css",
+        ],
+        title="Folio",
+        # Enable async callbacks
+        use_pages=False,
+        suppress_callback_exceptions=True,
+    )
+
+    # CSS files are automatically loaded from the assets folder
+    # main.css imports all other CSS files and applies the theme
+
+    # Use a simpler index_string without inline styles
+    app.index_string = """
+    <!DOCTYPE html>
+    <html>
+        <head>
+            {%metas%}
+            <title>{%title%}</title>
+            {%favicon%}
+            {%css%}
+        </head>
+        <body>
+            {%app_entry%}
+            <footer>
+                {%config%}
+                {%scripts%}
+                {%renderer%}
+            </footer>
+        </body>
+    </html>
+    """
+
+    # Store portfolio file path
+    app.portfolio_file = portfolio_file
+    logger.debug(f"Portfolio file path set to: {portfolio_file}")
+
+    # Define layout
+    app.layout = dbc.Container(
+        [
+            dcc.Location(id="url", refresh=False),  # Add URL component
+            html.Div(html.H2("Folio"), className="app-header my-3"),
+            create_upload_section(),  # Always show upload section
+            # Wrap the main content in a loading component with gradient border
+            html.Div(
+                dcc.Loading(
+                    id="main-loading",
+                    type="circle",
+                    children=[
+                        html.Div(
+                            [
+                                # Add visualization dashboard section near the top
+                                create_dashboard_section(),
+                                # Add filters below visualizations
+                                create_filters(),
+                                # Move table to the end
+                                dbc.Card(
+                                    [
+                                        dbc.CardHeader(
+                                            dbc.Button(
+                                                [
+                                                    html.I(
+                                                        className="fas fa-table me-2"
+                                                    ),
+                                                    html.Span("Portfolio Positions"),
+                                                    html.I(
+                                                        className="fas fa-chevron-down ms-2",
+                                                        id="positions-collapse-icon",
+                                                    ),
+                                                ],
+                                                id="positions-collapse-button",
+                                                color="link",
+                                                className="text-decoration-none text-dark p-0 d-flex align-items-center w-100 justify-content-between",
+                                            ),
+                                        ),
+                                        dbc.Collapse(
+                                            dbc.CardBody(
+                                                create_main_table(),
+                                            ),
+                                            id="positions-collapse",
+                                            is_open=True,  # Initially open
+                                        ),
+                                    ],
+                                    className="mb-3",
+                                ),
+                            ],
+                            id="main-content",
+                        )
+                    ],
+                ),
+                className="gradient-border",
+            ),
+            create_pnl_modal(),
+            # Empty state container (shown when no data is loaded)
+            html.Div(id="empty-state-container"),
+            # Add keyboard shortcut listener
+            html.Div(id="keyboard-shortcut-listener"),
+            # Premium AI Chat Interface
+            create_premium_chat_component(),
+            # AI Modal
+            dbc.Modal(
+                [
+                    dbc.ModalHeader("AI Portfolio Advisor"),
+                    dbc.ModalBody(
+                        [
+                            html.P("What would you like to know about your portfolio?"),
+                            dbc.Textarea(
+                                id="ai-query-input",
+                                placeholder="Ask about your portfolio...",
+                                rows=3,
+                                className="mb-3",
+                            ),
+                            dbc.Button(
+                                "Analyze",
+                                id="analyze-portfolio-button",
+                                color="primary",
+                                className="mb-3",
+                            ),
+                            html.Div(id="ai-analysis-result"),
+                        ]
+                    ),
+                    dbc.ModalFooter(
+                        dbc.Button(
+                            "Close",
+                            id="close-ai-modal",
+                            className="ms-auto",
+                            n_clicks=0,
+                        )
+                    ),
+                ],
+                id="ai-modal",
+                size="lg",
+                is_open=False,
+            ),
+            # Stores
+            dcc.Store(id="portfolio-data"),
+            dcc.Store(id="portfolio-summary"),  # Add portfolio summary store
+            dcc.Store(id="portfolio-groups"),  # Add portfolio groups store
+            dcc.Store(id="selected-position"),
+            dcc.Store(id="loading-output"),  # Add loading output store
+            dcc.Store(id="theme-store", storage_type="local"),  # Theme preference store
+            dcc.Store(id="ai-analysis-data"),  # Store for AI analysis results
+            dcc.Store(
+                id="portfolio-table-active-cell"
+            ),  # Store for tracking active cell in portfolio table
+            # Add initial trigger
+            dcc.Store(id="initial-trigger", data=True),
+        ],
+        fluid=True,
+        className="px-4",
+    )
+
+    # Add clientside callback to ensure initial trigger fires
+    app.clientside_callback(
+        """
+        function(pathname) {
+            return true;
+        }
+        """,
+        Output("initial-trigger", "data"),
+        Input("url", "pathname"),
+    )
+
+    # Add clientside callback to log portfolio summary data
+    app.clientside_callback(
+        """
+        function(data) {
+            console.log("Portfolio Summary Data:", data);
+            return window.dash_clientside.no_update;
+        }
+        """,
+        Output("portfolio-summary", "data", allow_duplicate=True),
+        Input("portfolio-summary", "data"),
+        prevent_initial_call=True,
+    )
+
+    # Keyboard shortcut functionality removed as it was causing issues
+
+    # Toggle upload section collapse
+    @app.callback(
+        [
+            Output("upload-collapse", "is_open", allow_duplicate=True),
+            Output("collapse-icon", "className"),
+        ],
+        [Input("upload-collapse-button", "n_clicks")],
+        [State("upload-collapse", "is_open")],
+        prevent_initial_call=True,
+    )
+    def toggle_upload_collapse(n_clicks, is_open):
+        """Toggle the upload section collapse state"""
+        if n_clicks:
+            # Toggle the collapse state
+            new_state = not is_open
+            # Update the icon based on the new state
+            icon_class = (
+                "fas fa-chevron-up ms-2" if new_state else "fas fa-chevron-down ms-2"
+            )
+            return new_state, icon_class
+        return is_open, "fas fa-chevron-down ms-2"
+
+    # Show/hide empty state based on portfolio data
+    @app.callback(
+        [
+            Output("empty-state-container", "children"),
+            Output("main-content", "style"),
+            # Also collapse the upload section when data is loaded
+            Output("upload-collapse", "is_open"),
+        ],
+        [Input("portfolio-groups", "data")],
+    )
+    def toggle_empty_state(groups_data):
+        """Show empty state when no data is loaded and collapse upload section when data is loaded"""
+        logger.debug(f"TOGGLE_EMPTY_STATE called with groups_data: {bool(groups_data)}")
+
+        if not groups_data:
+            # No data, show empty state, hide main content, keep upload open
+            logger.debug(
+                "TOGGLE_EMPTY_STATE: No data, showing empty state, hiding main content"
+            )
+            return create_empty_state(), {"display": "none"}, True
+        else:
+            # Data loaded, hide empty state, show main content, collapse upload
+            logger.debug(
+                "TOGGLE_EMPTY_STATE: Data loaded, hiding empty state, showing main content"
+            )
+            return None, {"display": "block"}, False
+
+    # Handle sample portfolio loading
+    @app.callback(
+        [
+            Output("upload-portfolio", "contents"),
+            Output("upload-portfolio", "filename"),
+        ],
+        Input("load-sample", "n_clicks"),
+        prevent_initial_call=True,
+    )
+    def load_sample_portfolio(n_clicks):
+        """Load a sample portfolio when the button is clicked"""
+        logger.debug(f"LOAD_SAMPLE_PORTFOLIO: Button clicked: {n_clicks}")
+        if n_clicks:
+            logger.debug("LOAD_SAMPLE_PORTFOLIO: Processing sample portfolio")
+            try:
+                # First check if private portfolio exists for local debugging
+                private_path = (
+                    Path(os.getcwd()) / "private-data" / "portfolio-private.csv"
+                )
+                sample_path = Path(__file__).parent / "assets" / "sample-portfolio.csv"
+
+                # Determine which file to use
+                if private_path.exists():
+                    logger.debug(f"Found private portfolio at: {private_path}")
+                    portfolio_path = private_path
+                    filename = "portfolio-private.csv"
+                elif sample_path.exists():
+                    logger.debug(f"Using sample portfolio at: {sample_path}")
+                    portfolio_path = sample_path
+                    filename = "sample-portfolio.csv"
+                else:
+                    logger.warning("Neither private nor sample portfolio found")
+                    return None, None
+
+                logger.debug(f"Loading portfolio from: {portfolio_path}")
+
+                # Debug the file content
+                with open(portfolio_path) as f:
+                    content = f.read()
+                    logger.debug(
+                        f"Portfolio content (first 100 chars): {content[:100]}"
+                    )
+
+                # Read the portfolio file
+                with open(portfolio_path, "rb") as f:
+                    file_content = f.read()
+                    logger.debug(f"Read {len(file_content)} bytes from portfolio file")
+
+                # Validate the file content
+                # We'll sanitize it during the normal processing flow
+                df = pd.read_csv(portfolio_path)
+
+                # Check for any potentially dangerous content
+                df = sanitize_dataframe(df)
+
+                # Re-encode the sanitized dataframe
+                csv_buffer = io.StringIO()
+                df.to_csv(csv_buffer, index=False)
+                csv_str = csv_buffer.getvalue()
+
+                # Encode the content as base64 for the upload component
+                content_type = "text/csv"
+                content_string = base64.b64encode(csv_str.encode("utf-8")).decode(
+                    "utf-8"
+                )
+
+                # Return both the contents and the filename
+                return (
+                    f"data:{content_type};base64,{content_string}",
+                    filename,
+                )
+            except Exception as e:
+                logger.error(f"Error loading sample portfolio: {e}", exc_info=True)
+                return None, None
+        return None, None
+
+    @app.callback(
+        [
+            Output("portfolio-data", "data"),
+            Output("portfolio-summary", "data"),
+            Output("portfolio-groups", "data"),
+            Output("loading-output", "data"),  # Changed from "children" to "data"
+            Output("upload-status", "children"),
+            Output(
+                "portfolio-table-active-cell", "data"
+            ),  # Changed from portfolio-table.active_cell
+        ],
+        [
+            Input("initial-trigger", "data"),
+            Input("url", "pathname"),
+            Input("upload-portfolio", "contents"),
+        ],
+        [
+            State("upload-portfolio", "filename"),
+        ],
+    )
+    def update_portfolio_data(_initial_trigger, _pathname, contents, filename):
+        """Update portfolio data when triggered"""
+        try:
+            logger.debug("Loading portfolio data...")
+            ctx = dash.callback_context
+            trigger_id = ctx.triggered[0]["prop_id"] if ctx.triggered else ""
+            logger.debug(f"Trigger: {trigger_id}")
+
+            # Handle file upload if provided
+            if contents and "upload-portfolio.contents" in trigger_id:
+                try:
+                    logger.debug(f"Processing uploaded file: {filename}")
+                    # Validate and sanitize the CSV file
+                    df, error = validate_csv_upload(contents, filename)
+                    if error:
+                        raise ValueError(error)
+
+                    logger.debug(
+                        f"Successfully read and validated {len(df)} rows from uploaded file {filename}"
+                    )
+                    status = html.Div(
+                        f"Successfully loaded {filename}", className="text-success"
+                    )
+                except ValueError as e:
+                    logger.error(f"CSV validation error: {e}")
+                    error_msg = f"Error loading file: {e!s}"
+                    error_div = html.Div(error_msg, className="text-danger")
+                    return [], {}, [], error_msg, error_div, None
+            elif app.portfolio_file:
+                # Use default portfolio file
+                try:
+                    # Try to read the CSV file with standard settings
+                    df = pd.read_csv(app.portfolio_file)
+                except pd.errors.ParserError as e:
+                    logger.warning(f"Parser error with standard settings: {e}")
+                    # Try again with more flexible quoting to handle commas in option symbols
+                    df = pd.read_csv(app.portfolio_file, quoting=3)  # QUOTE_NONE
+                logger.debug(f"Successfully read {len(df)} rows from portfolio file")
+                status = html.Div(
+                    "Using default portfolio file", className="text-muted"
+                )
+            else:
+                # No data available
+                return (
+                    [],
+                    {},
+                    [],
+                    "",
+                    html.Div("Please upload a portfolio file", className="text-muted"),
+                    None,
+                )
+
+            # Process portfolio data with automatic price updates
+            groups, summary, cash_like_positions = portfolio.process_portfolio_data(
+                df, update_prices=True
+            )
+            logger.debug(
+                f"Successfully processed {len(groups)} portfolio groups and {len(cash_like_positions)} cash-like positions"
+            )
+            # Continue with the original summary if price update fails
+
+            # Convert to Dash-compatible format
+            groups_data = [g.to_dict() for g in groups]
+            summary_data = summary.to_dict()
+            logger.debug(f"Summary data keys: {list(summary_data.keys())}")
+            logger.debug(
+                f"Portfolio estimate value: {summary_data.get('portfolio_estimate_value', 'NOT FOUND')}"
+            )
+            portfolio_data = df.to_dict("records")
+
+            return portfolio_data, summary_data, groups_data, "", status, None
+
+        except (ValueError, pd.errors.ParserError, pd.errors.EmptyDataError) as e:
+            # Handle expected data errors with user-friendly messages
+            logger.error(f"Data error loading portfolio: {e}", exc_info=True)
+            error_msg = f"Error loading portfolio: {e!s}"
+            error_div = html.Div(error_msg, className="text-danger")
+            return [], {}, [], error_msg, error_div, None
+        except (ImportError, NameError, AttributeError, TypeError) as e:
+            # These are programming errors that should be fixed, not handled
+            logger.critical(f"Critical programming error: {e}", exc_info=True)
+            error_msg = f"A critical error occurred. Please report this issue: {e!s}"
+            error_div = html.Div(error_msg, className="text-danger")
+            # Re-raise for development environments to see the full traceback
+            if app.debug:
+                raise
+            return [], {}, [], error_msg, error_div, None
+        except Exception as e:
+            # Unexpected errors should be logged and reported
+            logger.critical(
+                f"Unexpected error updating portfolio data: {e}", exc_info=True
+            )
+            error_msg = f"An unexpected error occurred: {e!s}"
+            error_div = html.Div(error_msg, className="text-danger")
+            # Re-raise for development environments to see the full traceback
+            if app.debug:
+                raise
+            return [], {}, [], error_msg, error_div, None
+
+    # Register summary cards callbacks
+    from .components.summary_cards import register_callbacks
+
+    register_callbacks(app)
+
+    # Register P&L chart callbacks
+    register_pnl_callbacks(app)
+
+    @app.callback(
+        Output("portfolio-table", "children"),
+        [
+            Input("portfolio-groups", "data"),
+            Input("search-input", "value"),
+            Input("filter-all", "n_clicks"),
+            Input("filter-stocks", "n_clicks"),
+            Input("filter-options", "n_clicks"),
+            Input("filter-cash", "n_clicks"),
+            Input("sort-state", "data"),  # Add sort state input
+        ],
+        [State("portfolio-summary", "data")],  # Add portfolio summary as state
+    )
+    def update_portfolio_table(
+        groups_data,
+        search,
+        _all_clicks,
+        _stocks_clicks,
+        _options_clicks,
+        _cash_clicks,
+        sort_state,
+        summary_data,
+    ):
+        """Update portfolio table based on filters and sorting"""
+        logger.debug("Updating portfolio table")
+        try:
+            if not groups_data:
+                return html.Tr(
+                    html.Td(
+                        "No portfolio data available",
+                        colSpan=6,
+                        className="text-center",
+                    )
+                )
+
+            # Convert data back to PortfolioGroup objects
+            groups = []
+            for g in groups_data:
+                # Filter out attributes that don't exist in Position class
+                stock_position = None
+                if g["stock_position"]:
+                    stock_position_data = g["stock_position"].copy()
+                    # Remove attributes that don't exist in StockPosition class
+                    if "sector" in stock_position_data:
+                        stock_position_data.pop("sector")
+                    if "is_cash_like" in stock_position_data:
+                        stock_position_data.pop("is_cash_like")
+                    if "position_type" in stock_position_data:
+                        stock_position_data.pop("position_type")
+                    stock_position = StockPosition(**stock_position_data)
+                option_positions = [
+                    OptionPosition(**opt) for opt in g["option_positions"]
+                ]
+                group = PortfolioGroup(
+                    ticker=g["ticker"],
+                    stock_position=stock_position,
+                    option_positions=option_positions,
+                    net_exposure=g["net_exposure"],
+                    beta=g["beta"],
+                    beta_adjusted_exposure=g["beta_adjusted_exposure"],
+                    total_delta_exposure=g["total_delta_exposure"],
+                    options_delta_exposure=g["options_delta_exposure"],
+                )
+                groups.append(group)
+
+            # Determine which filter button was clicked
+            ctx = dash.callback_context
+            if ctx.triggered:
+                button_id = ctx.triggered[0]["prop_id"].split(".")[0]
+                logger.debug(f"Filter button clicked: {button_id}")
+            else:
+                button_id = "filter-all"  # Default to showing all
+
+            # Get cash-like positions from summary data
+            cash_like_positions = []
+            if summary_data and "cash_like_positions" in summary_data:
+                # Convert cash-like positions to PortfolioGroup objects
+                for pos in summary_data["cash_like_positions"]:
+                    # Create a StockPosition
+                    stock_pos = StockPosition(
+                        ticker=pos["ticker"],
+                        quantity=pos["quantity"],
+                        beta=pos["beta"],
+                        market_exposure=pos.get(
+                            "market_exposure", pos.get("market_value", 0.0)
+                        ),  # Use market_exposure or fall back to market_value
+                        beta_adjusted_exposure=pos["beta_adjusted_exposure"],
+                    )
+
+                    # Create a PortfolioGroup with just this stock position
+                    cash_group = PortfolioGroup(
+                        ticker=pos["ticker"],
+                        stock_position=stock_pos,
+                        option_positions=[],
+                        net_exposure=pos.get(
+                            "market_exposure", pos.get("market_value", 0.0)
+                        ),
+                        beta=pos["beta"],
+                        beta_adjusted_exposure=pos["beta_adjusted_exposure"],
+                        total_delta_exposure=0.0,
+                        options_delta_exposure=0.0,
+                    )
+                    cash_like_positions.append(cash_group)
+
+            # Apply filters based on button clicked
+            filtered_groups = []
+            if button_id == "filter-all":
+                # Include all positions (including cash-like)
+                filtered_groups = groups + cash_like_positions
+            elif button_id == "filter-stocks":
+                # Only include groups with stock positions (excluding cash-like)
+                filtered_groups = [g for g in groups if g.stock_position]
+            elif button_id == "filter-options":
+                # Only include groups with option positions
+                filtered_groups = [g for g in groups if g.option_positions]
+            elif button_id == "filter-cash":
+                # Only include cash-like positions
+                filtered_groups = cash_like_positions
+            else:
+                # Default to all positions
+                filtered_groups = groups + cash_like_positions
+
+            # Apply search filter if provided
+            if search:
+                search = search.lower()
+                filtered_groups = [
+                    g
+                    for g in filtered_groups
+                    if (
+                        (g.stock_position and search in g.stock_position.ticker.lower())
+                        or any(
+                            search in opt.ticker.lower() for opt in g.option_positions
+                        )
+                    )
+                ]
+
+            # Get sort information
+            sort_column = sort_state.get("column", "value")
+            sort_direction = sort_state.get("direction", "desc")
+            sort_by = f"{sort_column}-{sort_direction}"
+
+            # Create table with sorting applied
+            return create_portfolio_table(filtered_groups, search, sort_by)
+
+        except (ValueError, KeyError) as e:
+            # Handle expected data errors
+            logger.error(f"Data error updating portfolio table: {e}", exc_info=True)
+            return html.Tr(
+                html.Td(
+                    f"Error loading portfolio data: {e!s}",
+                    colSpan=6,
+                    className="text-center text-danger",
+                )
+            )
+        except (ImportError, NameError, AttributeError, TypeError) as e:
+            # These are programming errors that should be fixed, not handled
+            logger.critical(
+                f"Critical programming error in table update: {e}", exc_info=True
+            )
+            # Re-raise for development environments to see the full traceback
+            if app.debug:
+                raise
+            return html.Tr(
+                html.Td(
+                    f"A critical error occurred. Please report this issue: {e!s}",
+                    colSpan=6,
+                    className="text-center text-danger",
+                )
+            )
+        except Exception as e:
+            # Unexpected errors should be logged and reported
+            logger.critical(
+                f"Unexpected error updating portfolio table: {e}", exc_info=True
+            )
+            # Re-raise for development environments to see the full traceback
+            if app.debug:
+                raise
+            return html.Tr(
+                html.Td(
+                    f"An unexpected error occurred: {e!s}",
+                    colSpan=6,
+                    className="text-center text-danger",
+                )
+            )
+
+    # Position details modal callbacks removed - functionality integrated into P&L modal
+
+    def _create_portfolio_group_from_data(position_data):
+        """Helper function to create a PortfolioGroup from position data"""
+        stock_position = None
+        if position_data["stock_position"]:
+            stock_position_data = position_data["stock_position"].copy()
+            # Remove attributes that don't exist in Position class
+            if "sector" in stock_position_data:
+                stock_position_data.pop("sector")
+            if "is_cash_like" in stock_position_data:
+                stock_position_data.pop("is_cash_like")
+            stock_position = StockPosition(**stock_position_data)
+
+        option_positions = [
+            OptionPosition(**opt) for opt in position_data["option_positions"]
+        ]
+
+        return PortfolioGroup(
+            ticker=position_data["ticker"],
+            stock_position=stock_position,
+            option_positions=option_positions,
+            net_exposure=position_data["net_exposure"],
+            beta=position_data["beta"],
+            beta_adjusted_exposure=position_data["beta_adjusted_exposure"],
+            total_delta_exposure=position_data["total_delta_exposure"],
+            options_delta_exposure=position_data["options_delta_exposure"],
+        )
+
+    # Old chat panel toggle callback removed - using premium chat component instead
+
+    # Old dash-chat callback removed - using premium chat component instead
+
+    # Add callback to handle column sorting
+    @app.callback(
+        Output("sort-state", "data"),
+        [Input({"type": "sort-header", "column": ALL}, "n_clicks")],
+        [State("sort-state", "data")],
+    )
+    @handle_callback_error(
+        default_return=None, error_message="Error updating sort state"
+    )
+    def update_sort_state(_header_clicks, current_sort_state):
+        """Update sort state when a column header is clicked"""
+        ctx = dash.callback_context
+
+        if not ctx.triggered:
+            return current_sort_state
+
+        trigger_id = ctx.triggered[0]["prop_id"]
+        if not trigger_id or "sort-header" not in trigger_id:
+            return current_sort_state
+
+        # Extract column name from trigger ID (in format {"type":"sort-header","column":"value"}.n_clicks)
+
+        column_data = json.loads(trigger_id.split(".")[0])
+        clicked_column = column_data.get("column")
+
+        if not clicked_column:
+            logger.debug(f"No column found in trigger data: {column_data}")
+            return current_sort_state
+
+        # Update sort direction if same column clicked, otherwise reset to descending
+        if clicked_column == current_sort_state.get("column"):
+            new_direction = (
+                "asc" if current_sort_state.get("direction") == "desc" else "desc"
+            )
+        else:
+            new_direction = "desc"
+
+        logger.debug(f"Sorting by {clicked_column} in {new_direction} order")
+        return {"column": clicked_column, "direction": new_direction}
+
+    # Add callbacks for collapsible chart sections
+    @app.callback(
+        [
+            Output("dashboard-collapse", "is_open"),
+            Output("dashboard-collapse-icon", "className"),
+        ],
+        [Input("dashboard-collapse-button", "n_clicks")],
+        [State("dashboard-collapse", "is_open")],
+        prevent_initial_call=True,
+    )
+    def toggle_dashboard_collapse(n_clicks, is_open):
+        """Toggle the dashboard section collapse state"""
+        if n_clicks:
+            # Toggle the collapse state
+            new_state = not is_open
+            # Update the icon based on the new state
+            icon_class = (
+                "fas fa-chevron-up ms-2" if new_state else "fas fa-chevron-down ms-2"
+            )
+            return new_state, icon_class
+        return is_open, "fas fa-chevron-down ms-2"
+
+    # Add callbacks for main section collapses
+    for section in ["summary", "charts"]:
+
+        @app.callback(
+            [
+                Output(f"{section}-collapse", "is_open"),
+                Output(f"{section}-collapse-icon", "className"),
+            ],
+            [Input(f"{section}-collapse-button", "n_clicks")],
+            [State(f"{section}-collapse", "is_open")],
+            prevent_initial_call=True,
+        )
+        def toggle_chart_collapse(n_clicks, is_open, _section=section):
+            """Toggle the chart section collapse state"""
+            if n_clicks:
+                # Toggle the collapse state
+                new_state = not is_open
+                # Update the icon based on the new state
+                icon_class = (
+                    "fas fa-chevron-up ms-2"
+                    if new_state
+                    else "fas fa-chevron-down ms-2"
+                )
+                return new_state, icon_class
+            return is_open, "fas fa-chevron-down ms-2"
+
+    # Add callback for positions collapse
+    @app.callback(
+        [
+            Output("positions-collapse", "is_open"),
+            Output("positions-collapse-icon", "className"),
+        ],
+        [Input("positions-collapse-button", "n_clicks")],
+        [State("positions-collapse", "is_open")],
+        prevent_initial_call=True,
+    )
+    def toggle_positions_collapse(n_clicks, is_open):
+        """Toggle the positions section collapse state"""
+        if n_clicks:
+            # Toggle the collapse state
+            new_state = not is_open
+            # Update the icon based on the new state
+            icon_class = (
+                "fas fa-chevron-up ms-2" if new_state else "fas fa-chevron-down ms-2"
+            )
+            return new_state, icon_class
+        return is_open, "fas fa-chevron-down ms-2"
+
+    # Register chart callbacks
+    register_chart_callbacks(app)
+
+    # Register premium chat callbacks
+    register_premium_chat_callbacks(app)  # This is now an alias for register_callbacks
+
+    return app
+
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(description="Folio - Portfolio Dashboard")
+    parser.add_argument(
+        "--portfolio",
+        type=str,
+        help="Path to portfolio CSV file",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug mode",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8050,
+        help="Port to run the server on",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host to run the server on",
+    )
+    args = parser.parse_args()
+
+    # Validate portfolio file if provided
+    portfolio_file = None
+    if args.portfolio:
+        portfolio_file = Path(args.portfolio)
+        if not portfolio_file.exists():
+            logger.error(f"Portfolio file not found: {portfolio_file}")
+            return 1
+        portfolio_file = str(portfolio_file)
+
+    # Initialize and run app
+    app = AppHolder.init_app(portfolio_file, args.debug)
+
+    # Display a helpful message about where to access the app
+    is_docker = os.path.exists("/.dockerenv")
+    is_huggingface = (
+        os.environ.get("HF_SPACE") == "1" or os.environ.get("SPACE_ID") is not None
+    )
+
+    if is_huggingface:
+        logger.info("\n\n🚀 Folio is running on Hugging Face Spaces!")
+        logger.info("📊 Access the dashboard at the URL provided by Hugging Face\n")
+    elif is_docker and args.host == "0.0.0.0":
+        logger.info("\n\n🚀 Folio is running inside a Docker container!")
+        logger.info(f"📊 Access the dashboard at: http://localhost:{args.port}")
+        logger.info(
+            f"💻 (The app is bound to {args.host}:{args.port} inside the container)\n"
+        )
+    else:
+        logger.info("\n\n🚀 Folio is running!")
+        logger.info(f"📊 Access the dashboard at: http://localhost:{args.port}\n")
+
+    app.run_server(debug=args.debug, port=args.port, host=args.host)
+    return 0
+
+
+# Create a class to hold the app instance
+class AppHolder:
+    """Class to hold the app instance"""
+
+    app = None
+    server = None
+
+    @classmethod
+    def init_app(cls, portfolio_file: str | None = None, debug: bool = False):
+        """Initialize the app for WSGI servers"""
+        if cls.app is None:
+            cls.app = create_app(portfolio_file, debug)
+            cls.server = cls.app.server
+        return cls.app
+
+
+# Create the app instance for Uvicorn to use
+app = AppHolder.init_app()
+server = AppHolder.server
+
+if __name__ == "__main__":
+    sys.exit(main())

src/folio/assets/components/ai.css

@@ -0,0 +1,659 @@
+/*
+ * AI Component Styles
+ * This file defines styles for all AI-related components
+ */
+
+/* AI Analysis Section */
+.analysis-section {
+  margin-bottom: var(--spacing-md);
+  padding: var(--spacing-sm);
+  background-color: rgba(0, 0, 0, 0.03);
+  border-radius: var(--border-radius-sm);
+  line-height: var(--line-height-base);
+}
+
+.ai-loading {
+  position: relative;
+}
+
+.ai-loading::after {
+  content: "Analyzing...";
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: rgba(255, 255, 255, 0.8);
+  font-weight: var(--font-weight-bold);
+  z-index: 10;
+}
+
+/* AI Analysis Collapse Section */
+#ai-analysis-collapse .card {
+  border: none;
+  box-shadow: var(--shadow-md);
+  transition: all var(--transition-fast);
+}
+
+#ai-analysis-collapse .card-header {
+  background: var(--gradient-light);
+  border-bottom: 1px solid var(--light-gray);
+  font-weight: var(--font-weight-bold);
+}
+
+#ai-analysis-collapse h5 {
+  color: var(--primary-color);
+  margin-top: var(--spacing-xs);
+  margin-bottom: var(--spacing-xs);
+  font-weight: var(--font-weight-bold);
+}
+
+#ai-analysis-collapse.collapsing {
+  transition: height 0.35s ease;
+}
+
+/* Analyze Button */
+#analyze-portfolio-button {
+  background: var(--gradient-primary);
+  border: none;
+  box-shadow: 0 4px 10px rgba(42, 0, 75, 0.4);
+  transition: all var(--transition-fast);
+  font-size: var(--font-size-lg);
+  font-weight: var(--font-weight-bold);
+  padding: var(--spacing-md) var(--spacing-lg);
+  margin-top: var(--spacing-md);
+  margin-bottom: var(--spacing-md);
+  border-radius: var(--border-radius-md);
+  position: relative;
+  overflow: hidden;
+}
+
+#analyze-portfolio-button:hover {
+  box-shadow: 0 6px 15px rgba(42, 0, 75, 0.5);
+  transform: translateY(-1px);
+}
+
+#analyze-portfolio-button:active {
+  transform: translateY(1px);
+  box-shadow: 0 2px 5px rgba(42, 0, 75, 0.4);
+}
+
+/* Pulsing Animation */
+@keyframes pulse {
+  0% {
+    box-shadow: 0 0 0 0 rgba(75, 0, 130, 0.7);
+  }
+
+  70% {
+    box-shadow: 0 0 0 10px rgba(75, 0, 130, 0);
+  }
+
+  100% {
+    box-shadow: 0 0 0 0 rgba(75, 0, 130, 0);
+  }
+}
+
+.ai-analyze-button {
+  animation: pulse 2s infinite;
+}
+
+/* AI Analysis Container */
+.ai-analysis-container {
+  background: linear-gradient(to right, rgba(255, 255, 255, 0.9), rgba(240, 249, 255, 0.9));
+  border: 1px solid rgba(75, 0, 130, 0.3) !important;
+  border-radius: var(--border-radius-md) !important;
+  box-shadow: var(--shadow-md);
+}
+
+/* AI Chat Panel */
+
+/* Chat container positioning */
+.ai-chat-container {
+  position: fixed;
+  bottom: var(--spacing-lg);
+  right: var(--spacing-lg);
+  z-index: 1000;
+}
+
+/* Toggle button */
+.ai-toggle-button {
+  background: var(--gradient-primary);
+  border: none;
+  box-shadow: 0 4px 10px rgba(42, 0, 75, 0.4);
+  transition: all var(--transition-fast);
+  border-radius: var(--border-radius-lg);
+  padding: var(--spacing-sm) var(--spacing-md);
+}
+
+.ai-toggle-button:hover {
+  box-shadow: 0 6px 15px rgba(42, 0, 75, 0.5);
+  transform: translateY(-2px);
+}
+
+.ai-toggle-button:active {
+  transform: translateY(1px);
+  box-shadow: 0 2px 5px rgba(42, 0, 75, 0.4);
+}
+
+.ai-toggle-container {
+  animation: pulse 2s infinite;
+}
+
+/* Chat panel */
+.ai-chat-panel {
+  width: 350px;
+  height: 500px;
+  background-color: var(--white);
+  border-radius: var(--border-radius-md);
+  box-shadow: var(--shadow-lg);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+/* Chat container */
+.chat-container {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  overflow: hidden;
+}
+
+/* Chat messages area */
+.chat-messages {
+  flex: 1;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-md);
+}
+
+/* Message bubbles */
+.ai-message,
+.user-message {
+  display: flex;
+  align-items: flex-start;
+  margin-bottom: var(--spacing-sm);
+  max-width: 100%;
+}
+
+.user-message {
+  flex-direction: row-reverse;
+}
+
+.ai-message-bubble,
+.user-message-bubble {
+  padding: var(--spacing-sm) var(--spacing-md);
+  border-radius: var(--border-radius-lg);
+  max-width: 80%;
+  word-wrap: break-word;
+}
+
+.ai-message-bubble {
+  background-color: #f0f7ff;
+  border: 1px solid #e0eeff;
+  border-top-left-radius: 4px;
+  margin-left: var(--spacing-xs);
+}
+
+.user-message-bubble {
+  background-color: #e9f9ff;
+  border: 1px solid #d0f0ff;
+  border-top-right-radius: 4px;
+  margin-right: var(--spacing-xs);
+}
+
+/* Avatar icons */
+.ai-avatar,
+.user-avatar {
+  width: 30px;
+  height: 30px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.ai-avatar {
+  background-color: var(--primary-color);
+  color: var(--white);
+  font-size: var(--font-size-sm);
+}
+
+.user-avatar {
+  background-color: var(--primary-light);
+  color: var(--white);
+  font-size: var(--font-size-sm);
+}
+
+/* Input area */
+.chat-input {
+  border-radius: var(--border-radius-lg);
+  padding: var(--spacing-sm) var(--spacing-md);
+  border: 1px solid var(--light-gray);
+  flex: 1;
+}
+
+.chat-input:focus {
+  outline: none;
+  border-color: var(--primary-color);
+  box-shadow: 0 0 0 2px rgba(75, 0, 130, 0.2);
+}
+
+.send-button {
+  border-radius: 50%;
+  width: 38px;
+  height: 38px;
+  padding: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--gradient-primary);
+  border: none;
+}
+
+/* Loading indicator */
+.chat-loading {
+  display: flex;
+  justify-content: center;
+}
+
+/* Markdown styling */
+.ai-message-content p,
+.user-message-content p {
+  margin-bottom: var(--spacing-xs);
+}
+
+.ai-message-content p:last-child,
+.user-message-content p:last-child {
+  margin-bottom: 0;
+}
+
+.ai-message-content ul,
+.user-message-content ul {
+  padding-left: var(--spacing-lg);
+  margin-bottom: var(--spacing-xs);
+}
+
+.ai-message-content h2,
+.user-message-content h2 {
+  font-size: var(--font-size-lg);
+  font-weight: var(--font-weight-bold);
+  margin-top: var(--spacing-sm);
+  margin-bottom: var(--spacing-xs);
+  color: var(--primary-color);
+}
+
+.ai-message-content code,
+.user-message-content code {
+  background-color: rgba(0, 0, 0, 0.05);
+  padding: 2px 4px;
+  border-radius: var(--border-radius-sm);
+  font-family: monospace;
+}
+
+/* Animation for new messages */
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.ai-message,
+.user-message {
+  animation: fadeIn 0.3s ease-out forwards;
+}
+
+/* Premium Chat Styles */
+
+/* Chat toggle button */
+.premium-chat-toggle {
+  position: fixed;
+  bottom: var(--spacing-lg);
+  right: var(--spacing-lg);
+  z-index: 1000;
+  border-radius: 50%;
+  width: 60px;
+  height: 60px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--gradient-primary);
+  border: none;
+  box-shadow: 0 4px 15px rgba(42, 0, 75, 0.4);
+  transition: all var(--transition-medium);
+  font-size: 24px;
+  color: var(--white);
+}
+
+.premium-chat-toggle:hover {
+  transform: scale(1.05);
+  box-shadow: 0 6px 20px rgba(42, 0, 75, 0.5);
+}
+
+/* Pulsing animation for the toggle button */
+@keyframes premium-pulse {
+  0% {
+    box-shadow: 0 0 0 0 rgba(75, 0, 130, 0.7);
+  }
+
+  70% {
+    box-shadow: 0 0 0 10px rgba(75, 0, 130, 0);
+  }
+
+  100% {
+    box-shadow: 0 0 0 0 rgba(75, 0, 130, 0);
+  }
+}
+
+.premium-pulse {
+  animation: premium-pulse 2s infinite;
+}
+
+/* Main chat panel */
+.premium-chat-panel {
+  position: fixed;
+  top: 0;
+  right: 0;
+  width: 0;
+  height: 100vh;
+  background-color: var(--white);
+  box-shadow: -5px 0 25px rgba(0, 0, 0, 0.1);
+  z-index: 999;
+  transition: width var(--transition-medium);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.premium-chat-panel.open {
+  width: 50%;
+}
+
+/* Main content shifting styles moved to layout.css */
+
+/* Chat header */
+.premium-chat-header {
+  background: var(--gradient-primary);
+  color: var(--white) !important;
+  /* Ensure text is white */
+  padding: var(--spacing-lg);
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  box-shadow: var(--shadow-md);
+  position: relative;
+  z-index: 10;
+}
+
+.premium-chat-title {
+  font-size: var(--font-size-xl);
+  font-weight: var(--font-weight-bold);
+  margin: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-sm);
+}
+
+.premium-chat-close {
+  background: none;
+  border: none;
+  color: var(--white);
+  font-size: var(--font-size-xl);
+  cursor: pointer;
+  transition: transform var(--transition-fast);
+}
+
+.premium-chat-close:hover {
+  transform: scale(1.1);
+}
+
+/* Chat messages container */
+.premium-chat-messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: var(--spacing-lg);
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-lg);
+  background-color: var(--off-white);
+  background-image: linear-gradient(rgba(255, 255, 255, 0.7) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.7) 1px, transparent 1px);
+  background-size: 20px 20px;
+  background-position: -1px -1px;
+}
+
+/* Message bubbles */
+.premium-ai-message,
+.premium-user-message {
+  display: flex;
+  gap: var(--spacing-sm);
+  max-width: 85%;
+}
+
+.premium-ai-message {
+  align-self: flex-start;
+}
+
+.premium-user-message {
+  align-self: flex-end;
+  flex-direction: row-reverse;
+}
+
+.premium-avatar {
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.premium-ai-avatar {
+  background: var(--gradient-primary);
+  color: var(--white);
+}
+
+.premium-user-avatar {
+  background: linear-gradient(135deg, var(--primary-light), var(--primary-color));
+  color: var(--white);
+}
+
+.premium-message-bubble {
+  padding: var(--spacing-md);
+  border-radius: var(--border-radius-lg);
+  box-shadow: var(--shadow-sm);
+  transition: all var(--transition-fast);
+}
+
+.premium-message-bubble:hover {
+  box-shadow: var(--shadow-md);
+  transform: translateY(-2px);
+}
+
+.premium-ai-bubble {
+  background-color: var(--white);
+  border-top-left-radius: 4px;
+}
+
+.premium-user-bubble {
+  background: var(--gradient-primary);
+  color: var(--white);
+  border-top-right-radius: 4px;
+}
+
+.premium-message-content {
+  margin: 0;
+  line-height: var(--line-height-base);
+}
+
+.premium-message-content p {
+  margin-bottom: var(--spacing-sm);
+}
+
+.premium-message-content p:last-child {
+  margin-bottom: 0;
+}
+
+/* Code blocks in messages */
+.premium-message-content pre {
+  background-color: var(--light-gray);
+  padding: var(--spacing-sm);
+  border-radius: var(--border-radius-sm);
+  overflow-x: auto;
+  margin: var(--spacing-sm) 0;
+}
+
+.premium-user-bubble .premium-message-content pre {
+  background-color: rgba(255, 255, 255, 0.1);
+}
+
+/* Chat input area */
+.premium-chat-input-container {
+  padding: var(--spacing-lg);
+  background-color: var(--white);
+  border-top: 1px solid var(--light-gray);
+  box-shadow: 0 -4px 10px rgba(0, 0, 0, 0.05);
+  position: relative;
+  z-index: 5;
+}
+
+.premium-chat-input-group {
+  display: flex;
+  gap: var(--spacing-sm);
+}
+
+.premium-chat-input {
+  flex: 1;
+  border: 1px solid var(--light-gray);
+  border-radius: 24px;
+  padding: var(--spacing-sm) var(--spacing-lg);
+  font-size: var(--font-size-base);
+  transition: all var(--transition-medium);
+  background-color: var(--off-white);
+}
+
+.premium-chat-input:focus {
+  outline: none;
+  border-color: var(--primary-color);
+  box-shadow: 0 0 0 3px rgba(75, 0, 130, 0.2);
+  background-color: var(--white);
+  transform: translateY(-2px);
+}
+
+.premium-chat-send {
+  background: var(--gradient-primary);
+  color: var(--white);
+  border: none;
+  border-radius: 50%;
+  width: 48px;
+  height: 48px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: all var(--transition-medium);
+  box-shadow: 0 4px 8px rgba(42, 0, 75, 0.3);
+}
+
+.premium-chat-send:hover {
+  transform: scale(1.1) rotate(15deg);
+  box-shadow: 0 6px 12px rgba(42, 0, 75, 0.4);
+}
+
+.premium-chat-send:active {
+  transform: scale(0.95);
+  box-shadow: 0 2px 4px rgba(42, 0, 75, 0.3);
+}
+
+/* Loading indicator */
+.premium-chat-loading {
+  align-self: center;
+  margin: var(--spacing-lg) 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--spacing-sm) var(--spacing-lg);
+  background-color: rgba(75, 0, 130, 0.1);
+  border-radius: var(--border-radius-lg);
+  box-shadow: var(--shadow-sm);
+  animation: pulse-loading 1.5s infinite ease-in-out;
+}
+
+/* Loading animation */
+@keyframes pulse-loading {
+  0% {
+    opacity: 0.6;
+    transform: scale(0.95);
+  }
+
+  50% {
+    opacity: 1;
+    transform: scale(1.05);
+  }
+
+  100% {
+    opacity: 0.6;
+    transform: scale(0.95);
+  }
+}
+
+/* Hide loading indicator when not needed */
+.premium-chat-loading.d-none {
+  display: none;
+}
+
+/* Responsive adjustments */
+@media (max-width: 992px) {
+  .premium-chat-panel.open {
+    width: 70%;
+  }
+}
+
+@media (max-width: 768px) {
+  .premium-chat-panel.open {
+    width: 90%;
+  }
+}
+
+@media (max-width: 576px) {
+  .premium-chat-panel.open {
+    width: 100%;
+  }
+}
+
+/* AI Advisor Header */
+.ai-advisor-panel h4,
+.premium-chat-title {
+  color: var(--white);
+}
+
+/* AI Advisor Content */
+.ai-advisor-content {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  background-color: var(--white);
+  overflow-y: auto;
+}
+
+/* Add a header style for the AI advisor panel */
+.ai-advisor-panel .mb-3 {
+  background: var(--gradient-primary);
+  color: var(--white);
+  padding: var(--spacing-md);
+  margin-top: 0 !important;
+  margin-bottom: 0 !important;
+  border-radius: 0;
+}

src/folio/assets/components/buttons.css

@@ -0,0 +1,126 @@
+/*
+ * Button Styles
+ * This file defines styles for all button components
+ */
+
+/* Base button styles */
+.btn {
+  border-radius: var(--border-radius-md);
+  transition: all var(--transition-fast);
+  font-weight: var(--font-weight-normal);
+  padding: var(--spacing-sm) var(--spacing-md);
+}
+
+/* Primary buttons */
+.btn-primary {
+  background: var(--gradient-primary);
+  border-color: var(--primary-color);
+  color: var(--white);
+  box-shadow: 0 4px 10px rgba(42, 0, 75, 0.4);
+}
+
+.btn-primary:hover {
+  background: linear-gradient(135deg, var(--primary-light) 0%, var(--primary-dark) 100%);
+  border-color: var(--primary-light);
+  box-shadow: 0 6px 15px rgba(42, 0, 75, 0.5);
+  transform: translateY(-1px);
+}
+
+.btn-primary:active,
+.btn-primary:focus {
+  background: linear-gradient(135deg, var(--primary-dark) 0%, var(--black) 100%);
+  border-color: var(--primary-dark);
+  box-shadow: 0 2px 5px rgba(42, 0, 75, 0.4);
+}
+
+/* Outline buttons */
+.btn-outline-primary {
+  color: var(--primary-color);
+  border-color: var(--primary-color);
+  background-color: transparent;
+}
+
+.btn-outline-primary:hover {
+  background-color: var(--primary-color);
+  border-color: var(--primary-color);
+  color: var(--white);
+}
+
+/* Link buttons */
+.btn-link {
+  color: var(--primary-color);
+  text-decoration: none;
+  padding: var(--spacing-xs) var(--spacing-sm);
+}
+
+.btn-link:hover {
+  color: var(--primary-light);
+  text-decoration: underline;
+}
+
+/* Button sizes */
+.btn-sm {
+  padding: var(--spacing-xs) var(--spacing-sm);
+  font-size: var(--font-size-sm);
+}
+
+.btn-lg {
+  padding: var(--spacing-md) var(--spacing-lg);
+  font-size: var(--font-size-lg);
+}
+
+/* Button positioning */
+.btn.mx-auto.d-block {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+/* Special buttons */
+.load-sample-button {
+  /* Specific styling for the load sample button */
+  font-weight: var(--font-weight-bold);
+}
+
+/* Icon buttons */
+.btn-icon {
+  width: 2.2rem;
+  height: 2.2rem;
+  padding: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+}
+
+.btn-icon.btn-sm {
+  width: 1.8rem;
+  height: 1.8rem;
+  font-size: 0.8rem;
+}
+
+.btn-icon i {
+  line-height: 1;
+}
+
+/* Button groups */
+.btn-group .btn {
+  border-radius: 0;
+}
+
+/* Chart toggle buttons */
+.chart-toggle-buttons {
+  box-shadow: var(--shadow-sm);
+  border-radius: var(--border-radius-sm);
+  overflow: hidden;
+}
+
+.btn-group .btn:first-child {
+  border-top-left-radius: var(--border-radius-md);
+  border-bottom-left-radius: var(--border-radius-md);
+}
+
+.btn-group .btn:last-child {
+  border-top-right-radius: var(--border-radius-md);
+  border-bottom-right-radius: var(--border-radius-md);
+}

src/folio/assets/components/cards.css

@@ -0,0 +1,158 @@
+/*
+ * Card Styles
+ * This file defines styles for all card components
+ */
+
+/* Base card styles */
+.card {
+  border: none;
+  border-radius: var(--border-radius-md);
+  box-shadow: var(--shadow-md);
+  background-color: var(--white);
+  transition: transform var(--transition-fast), box-shadow var(--transition-fast);
+  margin-bottom: var(--spacing-md);
+}
+
+.card:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--shadow-lg);
+}
+
+/* Card header */
+.card-header {
+  background: var(--gradient-light);
+  border-bottom: 1px solid var(--light-gray);
+  border-radius: var(--border-radius-md) var(--border-radius-md) 0 0 !important;
+  padding: var(--spacing-md);
+}
+
+/* Collapsible section headers - automatically applied to all collapsible sections */
+.card .card-header button span {
+  font-size: 1.5rem;
+  font-weight: 500;
+  margin-bottom: 0;
+  line-height: 1.2;
+}
+
+/* Card body */
+.card-body {
+  padding: var(--spacing-md);
+}
+
+/* Center the Portfolio Summary header */
+#summary-card .card-body>h4 {
+  text-align: center;
+}
+
+/* Card footer */
+.card-footer {
+  background-color: var(--off-white);
+  border-top: 1px solid var(--light-gray);
+  border-radius: 0 0 var(--border-radius-md) var(--border-radius-md);
+  padding: var(--spacing-md);
+}
+
+/* Card title and subtitle */
+.card-title {
+  font-weight: var(--font-weight-bold);
+  margin-bottom: var(--spacing-xs);
+  color: var(--black);
+}
+
+.card-subtitle {
+  color: var(--dark-gray);
+  font-size: var(--font-size-sm);
+  margin-bottom: var(--spacing-sm);
+}
+
+/* Card text */
+.card-text {
+  color: var(--black);
+  margin-bottom: var(--spacing-md);
+}
+
+.card-text:last-child {
+  margin-bottom: 0;
+}
+
+/* Card with gradient border */
+.gradient-border {
+  position: relative;
+  border-radius: var(--border-radius-md);
+  padding: var(--spacing-lg);
+  margin-bottom: var(--spacing-lg);
+  background: var(--white);
+  box-shadow: var(--shadow-md);
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+
+.gradient-border::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: -1;
+  margin: -2px;
+  border-radius: inherit;
+  background: var(--gradient-primary);
+  pointer-events: none;
+}
+
+/* Metric cards */
+.metric-card {
+  background-color: var(--white);
+  border-radius: var(--border-radius-md);
+  padding: var(--spacing-md);
+  box-shadow: var(--shadow-sm);
+  text-align: center;
+  height: 100%;
+  transition: transform var(--transition-fast), box-shadow var(--transition-fast);
+}
+
+.metric-card:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--shadow-md);
+}
+
+.metric-title {
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-bold);
+  color: var(--dark-gray);
+  margin-bottom: var(--spacing-xs);
+}
+
+.metric-value {
+  font-size: var(--font-size-xl);
+  font-weight: var(--font-weight-bold);
+  margin-bottom: var(--spacing-xs);
+}
+
+/* Chart cards */
+.chart-card {
+  border: none;
+  border-radius: var(--border-radius-md);
+  box-shadow: var(--shadow-md);
+  transition: all var(--transition-medium);
+  overflow: hidden;
+  background-color: var(--white);
+}
+
+.chart-card:hover {
+  box-shadow: var(--shadow-lg);
+  transform: translateY(-2px);
+}
+
+.chart-card .card-header {
+  background: var(--gradient-light);
+  border-bottom: 1px solid var(--light-gray);
+  padding: var(--spacing-md);
+  border-radius: var(--border-radius-md) var(--border-radius-md) 0 0 !important;
+}
+
+.chart-card .card-body {
+  padding: var(--spacing-md);
+  overflow: hidden;
+}

src/folio/assets/components/charts.css

@@ -0,0 +1,91 @@
+/*
+ * Chart Styles
+ * This file defines styles for all chart components
+ */
+
+/* Chart container */
+/* Note: Main dash-chart styles moved to components/dash.css */
+
+/* Chart controls */
+.chart-controls {
+  margin-top: var(--spacing-md);
+  display: flex;
+  justify-content: center;
+}
+
+/* Chart toggle buttons moved to buttons.css */
+
+/* Chart tooltips */
+.plotly-tooltip {
+  background-color: rgba(255, 255, 255, 0.95) !important;
+  border: 1px solid rgba(0, 0, 0, 0.1) !important;
+  border-radius: var(--border-radius-sm) !important;
+  box-shadow: var(--shadow-md) !important;
+  padding: var(--spacing-sm) var(--spacing-md) !important;
+  font-family: var(--font-family) !important;
+  font-size: var(--font-size-sm) !important;
+}
+
+/* Chart legends */
+.legend {
+  font-family: var(--font-family) !important;
+  font-size: var(--font-size-sm) !important;
+}
+
+/* Chart axes */
+.xtick text,
+.ytick text {
+  font-family: var(--font-family) !important;
+  font-size: var(--font-size-sm) !important;
+  color: var(--dark-gray) !important;
+}
+
+.xgrid,
+.ygrid {
+  stroke: var(--light-gray) !important;
+  stroke-width: 1 !important;
+}
+
+/* Chart title */
+.gtitle {
+  font-family: var(--font-family) !important;
+  font-weight: var(--font-weight-bold) !important;
+  font-size: var(--font-size-lg) !important;
+  color: var(--black) !important;
+}
+
+/* Chart modebar */
+.modebar {
+  opacity: 0.3 !important;
+  transition: opacity var(--transition-fast) !important;
+}
+
+.modebar:hover {
+  opacity: 1 !important;
+}
+
+.modebar-btn {
+  color: var(--primary-color) !important;
+}
+
+/* Chart loading */
+.js-plotly-plot .plot-container .plotly .loader {
+  border-color: var(--primary-color) !important;
+}
+
+/* Responsive charts */
+@media (max-width: 768px) {
+  .dash-chart {
+    min-height: 250px;
+    max-height: 300px;
+  }
+
+  /* Ensure charts don't overflow on mobile */
+  .js-plotly-plot,
+  .plotly,
+  .plot-container {
+    width: 100% !important;
+    max-width: 100% !important;
+    overflow: hidden !important;
+  }
+}

src/folio/assets/components/dash.css

@@ -0,0 +1,75 @@
+/*
+ * Dash-specific Styles
+ * This file defines styles for Dash-specific components
+ */
+
+/* Loading spinner */
+._dash-loading {
+  background-color: rgba(255, 255, 255, 0.8) !important;
+}
+
+._dash-loading-callback {
+  border-color: var(--primary-color) !important;
+}
+
+/* Dash charts */
+.dash-chart {
+  width: 100% !important;
+  max-width: 100% !important;
+  height: auto !important;
+  min-height: 350px;
+  max-height: 450px;
+  overflow: visible !important;
+  /* Changed from hidden to visible */
+  border-radius: 0 0 var(--border-radius-md) var(--border-radius-md);
+  padding: var(--spacing-sm);
+  position: relative;
+  /* Ensure proper positioning */
+  display: block;
+  /* Force block display */
+}
+
+/* Ensure charts don't overflow but can still render properly */
+.js-plotly-plot,
+.plotly,
+.plot-container {
+  width: 100% !important;
+  max-width: 100% !important;
+  overflow: visible !important;
+  /* Changed from hidden to visible */
+  position: relative;
+  /* Ensure proper positioning */
+  display: block;
+  /* Force block display */
+}
+
+/* Force chart visibility */
+.dash-chart>div {
+  visibility: visible !important;
+  opacity: 1 !important;
+}
+
+/* Prevent charts from capturing scroll events */
+.dash-chart .plotly,
+.dash-chart .js-plotly-plot,
+.dash-chart .plot-container {
+  pointer-events: auto !important;
+  /* Allow clicks but not scroll */
+}
+
+/* Only allow pointer events on specific interactive elements */
+.dash-chart .drag,
+.dash-chart .zoom,
+.dash-chart .pan,
+.dash-chart .select,
+.dash-chart .lasso {
+  pointer-events: auto !important;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+  .dash-chart {
+    min-height: 250px;
+    max-height: 300px;
+  }
+}

src/folio/assets/components/forms.css

@@ -0,0 +1,110 @@
+/* 
+ * Form Styles
+ * This file defines styles for all form components
+ */
+
+/* Form controls */
+.form-control {
+  border-radius: var(--border-radius-sm);
+  border: var(--border-width) solid var(--medium-gray);
+  padding: var(--spacing-sm);
+  font-size: var(--font-size-base);
+  line-height: var(--line-height-base);
+  color: var(--black);
+  background-color: var(--white);
+  transition: border-color var(--transition-fast), box-shadow var(--transition-fast);
+}
+
+.form-control:focus {
+  box-shadow: 0 0 0 3px rgba(75, 0, 130, 0.2);
+  border-color: var(--primary-color);
+  outline: 0;
+}
+
+/* Form labels */
+.form-label {
+  font-weight: var(--font-weight-bold);
+  margin-bottom: var(--spacing-xs);
+  color: var(--black);
+}
+
+/* Form groups */
+.form-group {
+  margin-bottom: var(--spacing-md);
+}
+
+/* Input groups */
+.input-group {
+  display: flex;
+  position: relative;
+}
+
+.input-group .form-control {
+  position: relative;
+  flex: 1 1 auto;
+  width: 1%;
+  min-width: 0;
+}
+
+.input-group-text {
+  display: flex;
+  align-items: center;
+  padding: var(--spacing-sm);
+  font-size: var(--font-size-base);
+  font-weight: var(--font-weight-normal);
+  line-height: var(--line-height-base);
+  color: var(--dark-gray);
+  text-align: center;
+  white-space: nowrap;
+  background-color: var(--off-white);
+  border: var(--border-width) solid var(--medium-gray);
+  border-radius: var(--border-radius-sm);
+}
+
+/* Upload area */
+#upload-portfolio {
+  border: 2px dashed var(--primary-color);
+  background-color: rgba(75, 0, 130, 0.03);
+  border-radius: var(--border-radius-md);
+  padding: var(--spacing-lg);
+  text-align: center;
+  transition: all var(--transition-fast);
+  cursor: pointer;
+}
+
+#upload-portfolio:hover {
+  border-color: var(--primary-light);
+  background-color: rgba(75, 0, 130, 0.05);
+}
+
+/* Checkboxes and radios */
+.form-check {
+  display: block;
+  min-height: 1.5rem;
+  padding-left: 1.5rem;
+  margin-bottom: var(--spacing-sm);
+}
+
+.form-check-input {
+  width: 1rem;
+  height: 1rem;
+  margin-top: 0.25rem;
+  margin-left: -1.5rem;
+  background-color: var(--white);
+  border: var(--border-width) solid var(--medium-gray);
+}
+
+.form-check-input:checked {
+  background-color: var(--primary-color);
+  border-color: var(--primary-color);
+}
+
+.form-check-label {
+  margin-bottom: 0;
+}
+
+/* Textarea */
+textarea.form-control {
+  min-height: 100px;
+  resize: vertical;
+}

src/folio/assets/components/modals.css

@@ -0,0 +1,109 @@
+/* 
+ * Modal Styles
+ * This file defines styles for all modal components
+ */
+
+/* Modal container */
+.modal-content {
+  border: none;
+  border-radius: var(--border-radius-lg);
+  box-shadow: var(--shadow-lg);
+  background-color: var(--white);
+  overflow: hidden;
+}
+
+/* Modal header */
+.modal-header {
+  border-bottom: 1px solid var(--light-gray);
+  background: var(--gradient-light);
+  padding: var(--spacing-md) var(--spacing-lg);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.modal-title {
+  margin: 0;
+  font-weight: var(--font-weight-bold);
+  color: var(--black);
+}
+
+.modal-header .close {
+  padding: var(--spacing-sm);
+  margin: calc(-1 * var(--spacing-sm)) calc(-1 * var(--spacing-sm)) calc(-1 * var(--spacing-sm)) auto;
+  background-color: transparent;
+  border: 0;
+  font-size: 1.5rem;
+  color: var(--dark-gray);
+  opacity: 0.5;
+  transition: opacity var(--transition-fast);
+}
+
+.modal-header .close:hover {
+  opacity: 1;
+}
+
+/* Modal body */
+.modal-body {
+  padding: var(--spacing-lg);
+}
+
+/* Modal footer */
+.modal-footer {
+  border-top: 1px solid var(--light-gray);
+  padding: var(--spacing-md) var(--spacing-lg);
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+}
+
+.modal-footer > * {
+  margin: 0 var(--spacing-xs);
+}
+
+/* Modal sizes */
+.modal-sm {
+  max-width: 300px;
+}
+
+.modal-lg {
+  max-width: 800px;
+}
+
+.modal-xl {
+  max-width: 1140px;
+}
+
+/* Position details modal */
+#position-modal .modal-body {
+  padding: var(--spacing-md);
+}
+
+#position-modal .table {
+  margin-bottom: 0;
+}
+
+/* P&L modal */
+#pnl-modal .modal-body {
+  padding: var(--spacing-md);
+}
+
+/* AI modal */
+#ai-modal .modal-body {
+  padding: var(--spacing-lg);
+}
+
+/* Modal backdrop */
+.modal-backdrop {
+  background-color: rgba(0, 0, 0, 0.5);
+}
+
+/* Modal animations */
+.modal.fade .modal-dialog {
+  transition: transform var(--transition-medium);
+  transform: translate(0, -50px);
+}
+
+.modal.show .modal-dialog {
+  transform: none;
+}

src/folio/assets/components/tables.css

@@ -0,0 +1,152 @@
+/*
+ * Table Styles
+ * This file defines styles for all table components
+ */
+
+/* Base table styles */
+.table {
+  width: 100% !important;
+  background-color: var(--white);
+  border-radius: var(--border-radius-md);
+  overflow: hidden;
+  border-collapse: separate;
+  border-spacing: 0;
+  margin-bottom: var(--spacing-lg);
+  table-layout: fixed !important;
+  /* Use fixed table layout for more predictable column widths */
+  box-sizing: border-box !important;
+}
+
+/* Table header */
+.table thead th {
+  background: var(--gradient-light);
+  border-bottom: 1px solid var(--light-gray);
+  font-weight: var(--font-weight-bold);
+  color: var(--black);
+  padding: var(--spacing-md);
+  text-align: left;
+  white-space: nowrap;
+  /* Prevent wrapping in headers */
+}
+
+/* Table body */
+.table tbody {
+  /* No border needed */
+}
+
+.table tbody tr {
+  transition: background-color var(--transition-fast);
+  width: 100% !important;
+  margin: 0 !important;
+  display: table-row !important;
+}
+
+.table tbody tr:hover {
+  background-color: rgba(75, 0, 130, 0.05);
+}
+
+.table tbody td {
+  padding: var(--spacing-md);
+  border-bottom: 1px solid var(--light-gray);
+  vertical-align: middle;
+  word-wrap: break-word;
+  /* Allow long text to wrap */
+  overflow-wrap: break-word;
+  white-space: normal;
+  /* Allow text to wrap */
+  box-sizing: border-box !important;
+}
+
+/* Sortable headers */
+.sort-header {
+  cursor: pointer;
+  transition: background-color var(--transition-fast);
+  padding: var(--spacing-xs) var(--spacing-sm);
+  border-radius: var(--border-radius-sm);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.sort-header:hover {
+  background-color: rgba(0, 0, 0, 0.05);
+}
+
+.sort-header i {
+  margin-left: var(--spacing-xs);
+  opacity: 0.5;
+}
+
+/* Portfolio table specific */
+.portfolio-table {
+  box-shadow: var(--shadow-md);
+  width: 100% !important;
+  border: 1px solid var(--light-gray);
+  border-radius: var(--border-radius-md);
+  overflow: hidden;
+  box-sizing: border-box !important;
+  table-layout: fixed !important;
+}
+
+.portfolio-table-container {
+  margin-bottom: var(--spacing-lg);
+  overflow-x: auto;
+  /* Add horizontal scrolling if needed */
+  padding: 0 var(--spacing-md);
+
+  width: 100% !important;
+  box-sizing: border-box !important;
+}
+
+.position-row {
+  transition: background-color var(--transition-fast);
+  cursor: pointer;
+
+  width: 100% !important;
+  margin: 0 !important;
+}
+
+.position-row:hover {
+  background-color: rgba(75, 0, 130, 0.08) !important;
+}
+
+/* Ensure columns in portfolio table have proper spacing */
+.position-row>[class*="col-"],
+.g-0>[class*="col-"] {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.header-row {
+
+  width: 100% !important;
+  margin: 0 !important;
+}
+
+/* Responsive tables */
+@media (max-width: 768px) {
+  .table {
+    font-size: var(--font-size-sm);
+  }
+
+  .table thead th,
+  .table tbody td {
+    padding: var(--spacing-sm);
+  }
+}
+
+/* Tooltip behavior for portfolio table */
+.tooltip {
+  opacity: 0;
+  transition: opacity var(--transition-fast);
+  z-index: var(--z-index-tooltip);
+}
+
+.tooltip.show {
+  opacity: 1;
+}
+
+/* Ensure only one tooltip is visible at a time */
+.position-row:not(:hover) .tooltip {
+  display: none !important;
+}

src/folio/assets/js/prevent_chart_scroll.js

@@ -0,0 +1,44 @@
+/**
+ * Prevent chart scroll interference with page scrolling
+ * 
+ * This script prevents the charts from capturing wheel events when users
+ * are trying to scroll through the page. It adds event listeners to all
+ * chart elements to stop wheel events from propagating.
+ */
+
+// Wait for the document to be fully loaded
+document.addEventListener('DOMContentLoaded', function() {
+    // Function to prevent wheel events on charts
+    function preventChartScroll() {
+        // Find all chart containers
+        const chartElements = document.querySelectorAll('.dash-chart');
+        
+        // Add event listeners to each chart
+        chartElements.forEach(function(chart) {
+            chart.addEventListener('wheel', function(e) {
+                // Prevent the wheel event from being captured by the chart
+                e.stopPropagation();
+            }, true);
+        });
+        
+        console.log('Chart scroll prevention initialized');
+    }
+    
+    // Initialize on page load
+    preventChartScroll();
+    
+    // Also run when the page content changes (for dynamically loaded charts)
+    const observer = new MutationObserver(function(mutations) {
+        mutations.forEach(function(mutation) {
+            if (mutation.addedNodes.length > 0) {
+                preventChartScroll();
+            }
+        });
+    });
+    
+    // Observe the entire document for changes
+    observer.observe(document.body, { 
+        childList: true,
+        subtree: true
+    });
+});

src/folio/assets/layout.css

@@ -0,0 +1,369 @@
+/*
+ * Layout Styles
+ * This file defines layout-specific styles
+ */
+
+/* Container */
+.container-fluid {
+  padding: var(--spacing-md);
+  width: 100%;
+  margin-right: auto;
+  margin-left: auto;
+}
+
+/* Spacing utilities */
+.my-1 {
+  margin-top: var(--spacing-xs);
+  margin-bottom: var(--spacing-xs);
+}
+
+.my-2 {
+  margin-top: var(--spacing-sm);
+  margin-bottom: var(--spacing-sm);
+}
+
+.my-3 {
+  margin-top: var(--spacing-md);
+  margin-bottom: var(--spacing-md);
+}
+
+.my-4 {
+  margin-top: var(--spacing-lg);
+  margin-bottom: var(--spacing-lg);
+}
+
+.my-5 {
+  margin-top: var(--spacing-xl);
+  margin-bottom: var(--spacing-xl);
+}
+
+.mx-1 {
+  margin-left: var(--spacing-xs);
+  margin-right: var(--spacing-xs);
+}
+
+.mx-2 {
+  margin-left: var(--spacing-sm);
+  margin-right: var(--spacing-sm);
+}
+
+.mx-3 {
+  margin-left: var(--spacing-md);
+  margin-right: var(--spacing-md);
+}
+
+.mx-4 {
+  margin-left: var(--spacing-lg);
+  margin-right: var(--spacing-lg);
+}
+
+.mx-5 {
+  margin-left: var(--spacing-xl);
+  margin-right: var(--spacing-xl);
+}
+
+.py-1 {
+  padding-top: var(--spacing-xs);
+  padding-bottom: var(--spacing-xs);
+}
+
+.py-2 {
+  padding-top: var(--spacing-sm);
+  padding-bottom: var(--spacing-sm);
+}
+
+.py-3 {
+  padding-top: var(--spacing-md);
+  padding-bottom: var(--spacing-md);
+}
+
+.py-4 {
+  padding-top: var(--spacing-lg);
+  padding-bottom: var(--spacing-lg);
+}
+
+.py-5 {
+  padding-top: var(--spacing-xl);
+  padding-bottom: var(--spacing-xl);
+}
+
+.px-1 {
+  padding-left: var(--spacing-xs);
+  padding-right: var(--spacing-xs);
+}
+
+.px-2 {
+  padding-left: var(--spacing-sm);
+  padding-right: var(--spacing-sm);
+}
+
+.px-3 {
+  padding-left: var(--spacing-md);
+  padding-right: var(--spacing-md);
+}
+
+.px-4 {
+  padding-left: var(--spacing-lg);
+  padding-right: var(--spacing-lg);
+}
+
+.px-5 {
+  padding-left: var(--spacing-xl);
+  padding-right: var(--spacing-xl);
+}
+
+/* Grid system enhancements */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  margin-left: calc(-1 * var(--spacing-md));
+  margin-right: calc(-1 * var(--spacing-md));
+}
+
+.col,
+.col-1,
+.col-2,
+.col-3,
+.col-4,
+.col-5,
+.col-6,
+.col-7,
+.col-8,
+.col-9,
+.col-10,
+.col-11,
+.col-12,
+.col-sm,
+.col-md,
+.col-lg,
+.col-xl {
+  padding-left: var(--spacing-md);
+  padding-right: var(--spacing-md);
+}
+
+/* App header */
+.app-header {
+  margin-bottom: var(--spacing-lg);
+  padding-bottom: var(--spacing-sm);
+  border-bottom: 1px solid var(--light-gray);
+}
+
+.app-header h2 {
+  background: var(--gradient-primary);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+  /* Standard approach */
+  -webkit-text-fill-color: transparent;
+  /* For older webkit browsers */
+  font-weight: var(--font-weight-bold);
+  margin: 0;
+}
+
+/* Empty state */
+.empty-state {
+  background: linear-gradient(135deg, var(--off-white) 0%, var(--white) 100%);
+  border-radius: var(--border-radius-lg);
+  padding: var(--spacing-xl);
+  box-shadow: var(--shadow-md);
+  text-align: center;
+  margin-top: var(--spacing-lg);
+}
+
+.empty-state i {
+  background: var(--gradient-primary);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+  /* Standard approach */
+  -webkit-text-fill-color: transparent;
+  /* For older webkit browsers */
+  font-size: 3rem;
+  margin-bottom: var(--spacing-lg);
+}
+
+/* Flexbox utilities */
+.d-flex {
+  display: flex;
+}
+
+.flex-row {
+  flex-direction: row;
+}
+
+.flex-column {
+  flex-direction: column;
+}
+
+.justify-content-start {
+  justify-content: flex-start;
+}
+
+.justify-content-end {
+  justify-content: flex-end;
+}
+
+.justify-content-center {
+  justify-content: center;
+}
+
+.justify-content-between {
+  justify-content: space-between;
+}
+
+.justify-content-around {
+  justify-content: space-around;
+}
+
+.align-items-start {
+  align-items: flex-start;
+}
+
+.align-items-end {
+  align-items: flex-end;
+}
+
+.align-items-center {
+  align-items: center;
+}
+
+.align-items-baseline {
+  align-items: baseline;
+}
+
+.align-items-stretch {
+  align-items: stretch;
+}
+
+/* Text utilities */
+.text-center {
+  text-align: center;
+}
+
+.text-left {
+  text-align: left;
+}
+
+.text-right {
+  text-align: right;
+}
+
+.text-justify {
+  text-align: justify;
+}
+
+.text-primary {
+  color: var(--primary-color) !important;
+}
+
+.text-success {
+  color: var(--success-color) !important;
+}
+
+.text-danger {
+  color: var(--danger-color) !important;
+}
+
+.text-warning {
+  color: var(--warning-color) !important;
+}
+
+.text-info {
+  color: var(--info-color) !important;
+}
+
+.text-muted {
+  color: var(--dark-gray) !important;
+}
+
+/* Display utilities */
+.d-none {
+  display: none;
+}
+
+.d-block {
+  display: block;
+}
+
+.d-inline {
+  display: inline;
+}
+
+.d-inline-block {
+  display: inline-block;
+}
+
+/* Loading spinner styles moved to components/dash.css */
+
+/* Content shifting for chat panels */
+.main-content-shifted {
+  transition: width var(--transition-medium), margin-right var(--transition-medium);
+  width: 100%;
+  margin-right: 0;
+}
+
+.main-content-shifted.chat-open {
+  width: 50%;
+  margin-right: 50%;
+}
+
+/* Responsive adjustments */
+@media (max-width: 992px) {
+  .main-content-shifted.chat-open {
+    width: 70%;
+    margin-right: 30%;
+  }
+}
+
+@media (max-width: 768px) {
+  .container-fluid {
+    padding: var(--spacing-sm);
+  }
+
+  .app-header {
+    margin-bottom: var(--spacing-md);
+  }
+
+  .empty-state {
+    padding: var(--spacing-lg);
+  }
+
+  .main-content-shifted.chat-open {
+    width: 90%;
+    margin-right: 10%;
+  }
+}
+
+@media (max-width: 576px) {
+  .main-content-shifted.chat-open {
+    width: 100%;
+    margin-right: 0;
+    overflow: hidden;
+  }
+}
+
+.row {
+  margin-left: calc(-1 * var(--spacing-sm));
+  margin-right: calc(-1 * var(--spacing-sm));
+}
+
+.col,
+.col-1,
+.col-2,
+.col-3,
+.col-4,
+.col-5,
+.col-6,
+.col-7,
+.col-8,
+.col-9,
+.col-10,
+.col-11,
+.col-12,
+.col-sm,
+.col-md,
+.col-lg,
+.col-xl {
+  padding-left: var(--spacing-sm);
+  padding-right: var(--spacing-sm);
+}

src/folio/assets/main.css

@@ -0,0 +1,163 @@
+/*
+ * Main CSS File
+ * This file imports all other CSS files and defines global styles
+ */
+
+/* Import theme variables */
+@import 'theme.css';
+
+/* Import layout styles */
+@import 'layout.css';
+
+/* Import component styles */
+@import 'components/buttons.css';
+@import 'components/cards.css';
+@import 'components/tables.css';
+@import 'components/forms.css';
+@import 'components/modals.css';
+@import 'components/charts.css';
+@import 'components/dash.css';
+@import 'components/ai.css';
+
+/* Base styles */
+body {
+  font-family: var(--font-family);
+  font-size: var(--font-size-base);
+  line-height: var(--line-height-base);
+  color: var(--black);
+  background-color: var(--off-white);
+  margin: 0;
+  padding: 0;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-weight: var(--font-weight-bold);
+  line-height: 1.2;
+  margin-top: 0;
+  margin-bottom: var(--spacing-md);
+  color: var(--black);
+}
+
+h1 {
+  font-size: 2.5rem;
+}
+
+h2 {
+  font-size: 2rem;
+}
+
+h3 {
+  font-size: 1.75rem;
+}
+
+h4 {
+  font-size: 1.5rem;
+}
+
+h5 {
+  font-size: 1.25rem;
+}
+
+h6 {
+  font-size: 1rem;
+}
+
+p {
+  margin-top: 0;
+  margin-bottom: var(--spacing-md);
+}
+
+a {
+  color: var(--primary-color);
+  text-decoration: none;
+  transition: color var(--transition-fast);
+}
+
+a:hover {
+  color: var(--primary-light);
+  text-decoration: underline;
+}
+
+/* Code and keyboard shortcuts */
+code,
+kbd,
+pre,
+samp {
+  font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  font-size: 0.875em;
+}
+
+kbd {
+  display: inline-block;
+  padding: 0.2em 0.4em;
+  font-size: 0.85em;
+  font-weight: var(--font-weight-bold);
+  line-height: 1;
+  color: var(--white);
+  background-color: var(--black);
+  border-radius: var(--border-radius-sm);
+  box-shadow: 0 2px 0 rgba(0, 0, 0, 0.2);
+}
+
+/* Lists */
+ul,
+ol {
+  margin-top: 0;
+  margin-bottom: var(--spacing-md);
+  padding-left: var(--spacing-lg);
+}
+
+/* Images */
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+/* Horizontal rule */
+hr {
+  margin: var(--spacing-md) 0;
+  border: 0;
+  border-top: 1px solid var(--light-gray);
+}
+
+/* Focus outline */
+:focus {
+  outline: 0;
+  box-shadow: 0 0 0 3px rgba(75, 0, 130, 0.25);
+}
+
+/* Selection */
+::selection {
+  background-color: var(--primary-color);
+  color: var(--white);
+}
+
+/* Scrollbar - Standard approach for Firefox */
+* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--medium-gray) var(--off-white);
+}
+
+/* Scrollbar - For webkit browsers */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--off-white);
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--medium-gray);
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--dark-gray);
+}

src/folio/assets/sample-portfolio.csv

@@ -0,0 +1,31 @@
+Symbol,Description,Quantity,Last Price,Last Price Change,Current Value,Today's Gain/Loss Dollar,Today's Gain/Loss Percent,Total Gain/Loss Dollar,Total Gain/Loss Percent,Percent Of Account,Cost Basis Total,Average Cost Basis,Type
+SPAXX**,"HELD IN MONEY MARKET",,,,"$12,345,670.00",,,,,5.00%,,,Cash
+AAPL,"APPLE INC",1500,$225.50 ,($2.10),"$33,825.00 ",($315.00),-0.92%,"$6,150.00 ",22.15%,1.25%,"$27,675.00 ",$184.50 ,Margin
+ -AAPL250417C220,"AAPL APR 17 2025 $220 CALL",-15,$5.50 ,($1.50),($1100.00),$300.00 ,21.43%,($200.00),-15.38%,-0.04%,"$1,300.00 ",$6.50 ,Margin
+AMZN,"AMAZON.COM INC",15000,$195.00 ,($3.50),"$292,500.00 ","($5,250.00)",-1.77%,"$60,500.00 ",26.09%,10.05%,"$232,000.00 ",$154.67 ,Margin
+ -AMZN250417C200,"AMZN APR 17 2025 $200 CALL",-100,$3.00 ,($2.00),($3000.00),"$2,000.00 ",40.00%,$500.00 ,20.00%,-0.10%,"$3,500.00 ",$3.50 ,Margin
+ -AMZN250516P200,"AMZN MAY 16 2025 $200 PUT",-50,$14.00 ,$2.00 ,($7000.00),($1000.00),-16.67%,($4000.00),-133.33%,-0.24%,"$3,000.00 ",$6.00 ,Margin
+BKNG,"BOOKING HOLDINGS INC COM",200,"$4,600.00 ",($100.00),"$92,000.00 ","($2,000.00)",-2.13%,"$21,000.00 ",29.58%,3.16%,"$71,000.00 ","$3,550.00 ",Margin
+ -CRM250620C350,"CRM JUN 20 2025 $350 CALL",-20,$1.20 ,($0.40),($240.00),$80.00 ,25.00%,$1040.00 ,80.62%,-0.01%,"$1,280.00 ",$6.40 ,Margin
+ -CRM250620P290,"CRM JUN 20 2025 $290 PUT",-20,$30.00 ,$5.00 ,($6000.00),($1000.00),-20.00%,($1800.00),-42.86%,-0.21%,"$4,200.00 ",$21.00 ,Margin
+ -CRM260618C240,"CRM JUN 18 2026 $240 CALL",20,$65.00 ,($6.00),"$13,000.00 ",($1200.00),-8.45%,($4500.00),-25.71%,0.45%,"$17,500.00 ",$87.50 ,Margin
+FFRHX,"FIDELITY FLOATING RATE HIGH INCOME",200000,$9.20 ,($0.01),"$184,000.00 ",($200.00),-0.11%,($2000.00),-1.08%,6.32%,"$186,000.00 ",$9.30 ,Cash
+GOOGL,"ALPHABET INC CAP STK CL A",20000,$155.00 ,($5.00),"$310,000.00 ","($10,000.00)",-3.13%,"$90,000.00 ",40.91%,10.65%,"$220,000.00 ",$110.00 ,Margin
+ -GOOGL250516C170,"GOOGL MAY 16 2025 $170 CALL",-100,$3.00 ,($2.00),($3000.00),"$2,000.00 ",40.00%,$500.00 ,14.29%,-0.10%,"$3,500.00 ",$3.50 ,Margin
+ -GOOGL250516P150,"GOOGL MAY 16 2025 $150 PUT",-50,$6.00 ,$2.50 ,($3000.00),($1250.00),-71.43%,($500.00),-20.00%,-0.10%,"$2,500.00 ",$5.00 ,Margin
+META,"META PLATFORMS INC CLASS A COMMON STOCK",4000,$575.00 ,($25.00),"$230,000.00 ","($10,000.00)",-4.17%,"$50,000.00 ",27.78%,7.90%,"$180,000.00 ",$450.00 ,Margin
+ -META250417C650,"META APR 17 2025 $650 CALL",-30,$1.50 ,($2.50),($450.00),$750.00 ,62.50%,"$4,500.00 ",90.91%,-0.02%,"$4,950.00 ",$16.50 ,Margin
+ -META270115P630,"META JAN 15 2027 $630 PUT",-30,$125.00 ,$15.00 ,($100000.00),($12000.00),-13.64%,($15000.00),-17.65%,-3.44%,"$85,000.00 ",$106.25 ,Margin
+MSFT,"MICROSOFT CORP",400,$380.00 ,($10.00),"$15,200.00 ",($400.00),-2.56%,($300.00),-1.94%,0.52%,"$15,500.00 ",$387.50 ,Margin
+NVDA,"NVIDIA CORPORATION COM",15000,$110.00 ,($2.00),"$165,000.00 ","($3,000.00)",-1.79%,"$57,000.00 ",52.78%,5.67%,"$108,000.00 ",$72.00 ,Margin
+ -NVDA250417C120,"NVDA APR 17 2025 $120 CALL",-50,$1.30 ,($0.40),($650.00),$200.00 ,23.53%,"$1,350.00 ",67.50%,-0.02%,"$2,000.00 ",$4.00 ,Margin
+ -NVDA250417P110,"NVDA APR 17 2025 $110 PUT",-20,$5.00 ,$0.75 ,($1000.00),($150.00),-17.65%,($300.00),-42.86%,-0.03%,$700.00 ,$3.50 ,Margin
+SMH,"VANECK ETF TRUST SEMICONDUCTR ETF",-13000,$210.00 ,($5.00),($273000.00),"$6,500.00 ",2.33%,"$12,000.00 ",4.21%,-9.38%,"$285,000.00 ",$219.23 ,Short
+-SPY250620C580,SPY JUN 20 2025 $580 CALL,-30,$5.37,+$3.23,-$16110.00,+$669.15,+3.98%,+$669.15,+3.98%,-0.60%,$16779.15,$5.59,Margin
+-SPY250620P470,SPY JUN 20 2025 $470 PUT,-30,$7.29,-$12.75,-$21870.00,-$680.97,-3.22%,-$680.97,-3.22%,-0.81%,$21189.03,$7.06,Margin
+-SPY250620P525,SPY JUN 20 2025 $525 PUT,30,$17.76,-$24.36,$53280.00,+$49.63,+0.09%,+$49.63,+0.09%,1.98%,$53230.37,$17.74,Margin
+TCEHY,"TENCENT HOLDINGS LIMITED UNSPON ADR",8000,$65.00 ,$0.00 ,"$52,000.00 ",$0.00 ,0.00%,"$7,000.00 ",15.56%,1.79%,"$45,000.00 ",$56.25 ,Margin
+TLT,"ISHARES TR 20 YR TR BD ETF",10800,$90.00 ,$1.25 ,"$162,000.00 ",$2250.00 ,1.41%,--,--,5.57%,--,--,Cash
+UBER,"UBER TECHNOLOGIES INC COM",20000,$72.50 ,($2.00),"$145,000.00 ","($4,000.00)",-2.68%,"$11,000.00 ",8.21%,4.98%,"$134,000.00 ",$67.00 ,Margin
+ -UBER260116C50,"UBER JAN 16 2026 $50 CALL",100,$26.50 ,($2.00),"$26,500.00 ",($2000.00),-7.02%,"$5,000.00 ",23.26%,0.91%,"$21,500.00 ",$21.50 ,Margin
+UPRO,"PROSHARES ULTRAPRO S&P500",-20000,$72.50 ,($4.50),($145000.00),"$9,000.00 ",5.84%,"$16,500.00 ",10.22%,-4.98%,"$161,500.00 ",$80.75 ,Short

src/folio/assets/theme.css

@@ -0,0 +1,72 @@
+/*
+ * Folio Theme Variables
+ * This file defines all the CSS variables used throughout the application
+ */
+
+:root {
+  /* Primary colors */
+  --primary-color: #6936d0cc;
+  /* Darker Royal Purple */
+  --primary-light: #6936d0;
+  --primary-dark: #6936d049;
+
+  /* Neutral colors */
+  --white: #FFFFFF;
+  --off-white: #F8F9FA;
+  --light-gray: #E9ECEF;
+  --medium-gray: #CED4DA;
+  --dark-gray: #6C757D;
+  --black: #212529;
+
+  /* Semantic colors */
+  --success-color: #28A745;
+  --danger-color: #DC3545;
+  --info-color: #17A2B8;
+  --warning-color: #FFC107;
+
+  /* Typography */
+  --font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --font-size-base: 1rem;
+  --font-size-sm: 0.875rem;
+  --font-size-lg: 1.25rem;
+  --font-size-xl: 1.5rem;
+  --font-weight-normal: 400;
+  --font-weight-bold: 700;
+  --line-height-base: 1.5;
+
+  /* Spacing */
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 1.5rem;
+  --spacing-xl: 2rem;
+
+  /* Borders */
+  --border-radius-sm: 4px;
+  --border-radius-md: 8px;
+  --border-radius-lg: 12px;
+  --border-width: 1px;
+
+  /* Shadows */
+  --shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.05);
+  --shadow-lg: 0 8px 16px rgba(0, 0, 0, 0.1);
+
+  /* Transitions */
+  --transition-fast: 0.2s;
+  --transition-medium: 0.3s;
+  --transition-slow: 0.5s;
+
+  /* Z-index layers */
+  --z-index-dropdown: 1000;
+  --z-index-sticky: 1020;
+  --z-index-fixed: 1030;
+  --z-index-modal-backdrop: 1040;
+  --z-index-modal: 1050;
+  --z-index-popover: 1060;
+  --z-index-tooltip: 1070;
+
+  /* Gradients */
+  --gradient-primary: linear-gradient(135deg, var(--primary-color) 0%, var(--black) 100%);
+  --gradient-light: linear-gradient(to right, var(--off-white), var(--white));
+}

src/folio/callbacks/__init__.py

@@ -0,0 +1,4 @@
+"""Callback modules for the Folio application."""
+
+# Import callback registration functions
+from ..components.charts import register_callbacks as register_chart_callbacks

src/folio/cash_detection.py

@@ -0,0 +1,117 @@
+import re
+
+"""Cash detection functionality for portfolio analysis.
+
+This module provides functions for identifying cash-like positions in a portfolio.
+"""
+
+
+def _is_likely_money_market(
+    ticker: str | float | None, description: str | float | None = ""
+) -> bool:
+    """Determine if a position is likely a money market fund based on patterns and keywords.
+
+    This function uses pattern matching on the ticker symbol and description to identify
+    common money market funds and cash-like instruments.
+
+    Args:
+        ticker: The ticker symbol to check
+        description: The description of the security
+
+    Returns:
+        True if the position is likely a money market fund, False otherwise
+    """
+    # Handle None or non-string inputs
+    if ticker is None or not isinstance(ticker, str):
+        return False
+    if description is None or not isinstance(description, str):
+        description = ""
+
+    # Convert to uppercase for case-insensitive matching
+    ticker = ticker.upper()
+    description = description.upper()
+
+    # Pattern 1: Common money market fund symbol patterns (ending with XX)
+    if re.search(r"[A-Z]{2,4}XX$", ticker):
+        return True
+
+    # Pattern 2: Description contains money market related terms
+    money_market_terms = [
+        "MONEY MARKET",
+        "CASH RESERVES",
+        "TREASURY ONLY",
+        "GOVERNMENT LIQUIDITY",
+        "CASH MANAGEMENT",
+        "LIQUID ASSETS",
+        "CASH EQUIVALENT",
+        "TREASURY FUND",
+        "LIQUIDITY FUND",
+        "CASH FUND",
+        "RESERVE FUND",
+    ]
+
+    for term in money_market_terms:
+        if term in description:
+            return True
+
+    # Pattern 3: Common prefixes for money market funds
+    money_market_prefixes = ["SPAXX", "FMPXX", "VMFXX", "SWVXX"]
+    for prefix in money_market_prefixes:
+        if ticker.startswith(prefix):
+            return True
+
+    # Pattern 4: Common short-term treasury ETFs
+    short_term_treasury_etfs = ["BIL", "SHY", "SGOV", "GBIL"]
+    if ticker in short_term_treasury_etfs:
+        return True
+
+    return False
+
+
+def is_cash_or_short_term(
+    ticker: str | float | None,
+    beta: float | None = None,
+    description: str | float | None = "",
+) -> bool:
+    """Determine if a position should be considered cash or cash-like.
+
+    This function checks if a position is likely cash or a cash-like instrument
+    based on its ticker, beta, and description. Cash-like instruments include
+    money market funds, short-term bond funds, and other low-volatility assets.
+
+    Args:
+        ticker: The ticker symbol to check
+        beta: The calculated beta value for the position
+        description: The description of the security
+
+    Returns:
+        True if the position is likely cash or cash-like, False otherwise
+    """
+    # Handle None or non-string inputs for ticker and description
+    if ticker is None or not isinstance(ticker, str):
+        return False
+    if description is None or not isinstance(description, str):
+        description = ""
+
+    # Convert to uppercase for case-insensitive matching
+    ticker = ticker.upper()
+    description = description.upper()
+
+    # Initialize result
+    is_cash_like = False
+
+    # Check various conditions that would make this a cash-like position
+
+    # 1. Check if it's a cash symbol
+    if ticker in ["CASH", "USD"]:
+        is_cash_like = True
+
+    # 2. Check if it's a money market fund
+    elif _is_likely_money_market(ticker, description):
+        is_cash_like = True
+
+    # 3. Check for very low beta (near zero)
+    elif beta is not None and abs(beta) < 0.1:
+        is_cash_like = True
+
+    return is_cash_like

src/folio/chart_data.py

@@ -0,0 +1,564 @@
+"""Chart data transformation utilities.
+
+This module provides functions to transform portfolio data into formats
+suitable for visualization with Plotly charts.
+"""
+
+from typing import Any
+
+from .data_model import PortfolioGroup, PortfolioSummary
+from .formatting import format_compact_currency, format_currency
+from .logger import logger
+from .portfolio import calculate_beta_adjusted_net_exposure
+from .portfolio_value import (
+    calculate_component_percentages,
+    get_portfolio_component_values,
+)
+
+
+class ChartColors:
+    """Chart color constants for consistent visualization.
+
+    This class defines the color palette used across all charts in the application.
+    Use these constants instead of hardcoded hex values to ensure consistency.
+
+    IMPORTANT: These colors are used across all charts and should be kept consistent.
+    When adding a new chart, always use these constants instead of defining new colors.
+    """
+
+    # Core color palette - used across all charts
+    LONG = "#1E8449"  # Green for long positions
+    SHORT = "#2F3136"  # Dark gray/black for short positions
+    OPTIONS = "#8E44AD"  # Purple for options
+    NET = "#2980B9"  # Blue for net values
+    CASH = "#8E44AD"  # Same purple as OPTIONS
+    PENDING = "#2980B9"  # Same blue as NET
+
+
+# transform_for_asset_allocation function has been removed in favor of the more accurate Exposure Chart
+
+
+def transform_for_exposure_chart(
+    portfolio_summary: PortfolioSummary, use_beta_adjusted: bool = False
+) -> dict[str, Any]:
+    """Transform portfolio summary data for the exposure chart.
+
+    Args:
+        portfolio_summary: Portfolio summary data from the data model
+        use_beta_adjusted: Whether to use beta-adjusted values
+
+    Returns:
+        Dict containing data and layout for the bar chart
+    """
+    logger.debug("Transforming data for exposure chart")
+
+    # Log portfolio summary fields for debugging
+    logger.debug(
+        f"Portfolio summary net_market_exposure: {portfolio_summary.net_market_exposure}"
+    )
+    logger.debug(f"Portfolio summary long_exposure: {portfolio_summary.long_exposure}")
+    logger.debug(
+        f"Portfolio summary short_exposure: {portfolio_summary.short_exposure}"
+    )
+    logger.debug(
+        f"Portfolio summary options_exposure: {portfolio_summary.options_exposure}"
+    )
+
+    # Extract values based on whether we want beta-adjusted or not
+    if use_beta_adjusted:
+        logger.debug("Using beta-adjusted values for exposure chart")
+        long_value = portfolio_summary.long_exposure.total_beta_adjusted
+        # Show short exposure as negative
+        short_value = portfolio_summary.short_exposure.total_beta_adjusted
+        options_value = portfolio_summary.options_exposure.total_beta_adjusted
+        # Use the utility function for beta-adjusted net exposure
+        net_value = calculate_beta_adjusted_net_exposure(
+            portfolio_summary.long_exposure.total_beta_adjusted,
+            portfolio_summary.short_exposure.total_beta_adjusted,
+        )
+        logger.debug(
+            f"Beta-adjusted values - Long: {long_value}, Short: {short_value}, Options: {options_value}, Net: {net_value}"
+        )
+    else:
+        logger.debug("Using net exposure values for exposure chart")
+        long_value = portfolio_summary.long_exposure.total_exposure
+        # Show short exposure as negative
+        short_value = portfolio_summary.short_exposure.total_exposure
+        options_value = portfolio_summary.options_exposure.total_exposure
+        # Use the pre-calculated net market exposure
+        net_value = portfolio_summary.net_market_exposure
+        logger.debug(
+            f"Net exposure values - Long: {long_value}, Short: {short_value}, Options: {options_value}, Net: {net_value}"
+        )
+
+    # Categories and values for the chart
+    categories = ["Long", "Short", "Options", "Net"]
+    values = [long_value, short_value, options_value, net_value]
+
+    # Format values for display
+    text_values = [format_currency(value) for value in values]
+
+    # Colors for the bars - using ChartColors constants
+    colors = [
+        ChartColors.LONG,
+        ChartColors.SHORT,
+        ChartColors.OPTIONS,
+        ChartColors.NET,
+    ]
+
+    # Create the chart data
+    chart_data = {
+        "data": [
+            {
+                "type": "bar",
+                "x": categories,
+                "y": values,
+                "text": text_values,
+                "textposition": "auto",
+                "hoverinfo": "text",
+                "hovertemplate": "<b>%{x}</b><br>%{text}<extra></extra>",
+                "marker": {"color": colors, "line": {"width": 0}, "opacity": 0.9},
+            }
+        ],
+        "layout": {
+            "title": {
+                "text": "Market Exposure"
+                + (" (Beta-Adjusted)" if use_beta_adjusted else ""),
+                "font": {"size": 16, "color": "#2C3E50"},
+                "x": 0.5,  # Center the title
+                "xanchor": "center",
+            },
+            "xaxis": {
+                "title": "Exposure Type",
+                "titlefont": {"size": 12, "color": "#7F8C8D"},
+                "tickfont": {"size": 11},
+            },
+            "yaxis": {
+                "title": "Exposure ($)",
+                "titlefont": {"size": 12, "color": "#7F8C8D"},
+                "tickfont": {"size": 11},
+                "gridcolor": "#ECF0F1",
+                "zerolinecolor": "#BDC3C7",
+            },
+            "margin": {"l": 50, "r": 20, "t": 50, "b": 50, "pad": 4},
+            "autosize": True,  # Allow the chart to resize with its container
+            "plot_bgcolor": "white",
+            "paper_bgcolor": "white",
+            "font": {
+                "family": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif"
+            },
+        },
+    }
+
+    return chart_data
+
+
+def transform_for_treemap(
+    portfolio_groups: list[PortfolioGroup], _group_by: str = "ticker"
+) -> dict[str, Any]:
+    """Transform portfolio groups data for the treemap chart.
+
+    Args:
+        portfolio_groups: List of portfolio groups from the data model
+        _group_by: Unused parameter (kept for backward compatibility)
+
+    Returns:
+        Dict containing data and layout for the treemap chart
+    """
+    logger.debug("Transforming data for treemap chart (grouped by ticker)")
+    logger.debug(f"Number of portfolio groups: {len(portfolio_groups)}")
+
+    # Log some details about the first few groups for debugging
+    for i, group in enumerate(portfolio_groups[:3]):
+        logger.debug(f"Group {i} ticker: {group.ticker}")
+        logger.debug(f"Group {i} net_exposure: {group.net_exposure}")
+        if group.stock_position:
+            logger.debug(
+                f"Group {i} stock position market_exposure: {group.stock_position.market_exposure}"
+            )
+        logger.debug(f"Group {i} has {len(group.option_positions)} option positions")
+
+    # Initialize lists for treemap data
+    labels = []
+    parents = []
+    values = []
+    texts = []
+    colors = []
+
+    # Add root node
+    labels.append("Portfolio")
+    parents.append("")
+    values.append(0)  # Will be sum of children
+    texts.append("Portfolio")
+    colors.append("#FFFFFF")  # White for root
+
+    # Group by ticker
+    # First, collect all unique tickers and calculate their total exposure
+    ticker_exposures = {}
+    for group in portfolio_groups:
+        ticker = group.ticker
+        exposure = 0
+
+        # Add stock position exposure
+        stock_exposure = 0
+        if group.stock_position:
+            # Use market exposure for stocks
+            stock_exposure = group.stock_position.market_exposure
+            logger.debug(f"Ticker {ticker} stock exposure: {stock_exposure}")
+            exposure += stock_exposure
+
+        # Add option positions exposure (delta exposure)
+        option_exposure = 0
+        for option in group.option_positions:
+            logger.debug(
+                f"Ticker {ticker} option {option.option_type} delta_exposure: {option.delta_exposure}"
+            )
+            option_exposure += option.delta_exposure
+
+        exposure += option_exposure
+        logger.debug(
+            f"Ticker {ticker} total exposure: {exposure} (stock: {stock_exposure}, options: {option_exposure})"
+        )
+
+        # Store the net exposure value for sizing (not absolute)
+        ticker_exposures[ticker] = exposure
+
+    # Sort tickers by absolute exposure (largest first)
+    sorted_tickers = sorted(
+        ticker_exposures.keys(), key=lambda t: abs(ticker_exposures[t]), reverse=True
+    )
+
+    # Add ticker nodes
+    for ticker in sorted_tickers:
+        # Skip tickers with zero exposure
+        if ticker_exposures[ticker] == 0:
+            continue
+
+        exposure = ticker_exposures[ticker]
+        labels.append(ticker)
+        parents.append("Portfolio")
+        # Note: We still use abs() here for sizing because treemap requires positive values
+        # But we maintain the sign information in the text and color
+        values.append(abs(exposure))
+        texts.append(f"{ticker}: {format_currency(exposure)}")
+
+        # Color based on long/short - using ChartColors constants
+        color = ChartColors.LONG if exposure > 0 else ChartColors.SHORT
+        colors.append(color)
+
+    # We don't need to add individual positions anymore - just show the ticker level
+
+    # Create the chart data
+    chart_data = {
+        "data": [
+            {
+                "type": "treemap",
+                "labels": labels,
+                "parents": parents,
+                "values": values,
+                "text": texts,
+                "hoverinfo": "text",
+                "marker": {
+                    "colors": colors,
+                    "line": {"width": 1, "color": "#FFFFFF"},
+                    "pad": 3,
+                },
+                "textfont": {
+                    "family": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
+                    "size": 12,
+                    "color": "#FFFFFF",
+                },
+                "hovertemplate": "%{text}<extra></extra>",
+            }
+        ],
+        "layout": {
+            "title": {
+                "text": "Position Size by Exposure",
+                "font": {"size": 16, "color": "#2C3E50"},
+                "x": 0.5,  # Center the title
+                "xanchor": "center",
+            },
+            "margin": {"l": 0, "r": 0, "t": 50, "b": 0, "pad": 4},
+            "autosize": True,  # Allow the chart to resize with its container
+            "paper_bgcolor": "white",
+            "font": {
+                "family": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif"
+            },
+        },
+    }
+
+    return chart_data
+
+
+# Sector allocation chart has been removed as it's not currently supported
+
+
+def transform_for_allocations_chart(
+    portfolio_summary: PortfolioSummary,
+) -> dict[str, Any]:
+    """Transform portfolio summary data for the allocations chart.
+
+    This function takes a portfolio summary and transforms it into a format
+    suitable for a bar chart showing portfolio allocations. The chart
+    has four main categories:
+    - Long: Total long exposure (stocks + options combined)
+    - Short: Total short exposure (stocks + options combined)
+    - Cash: Cash-like positions
+    - Pending: Pending activity
+
+    IMPORTANT: Short values are stored as negative numbers in the portfolio summary.
+    We maintain these negative values in the chart to show short positions below
+    the x-axis, providing a more intuitive visualization of long vs short positions.
+
+    Args:
+        portfolio_summary: The portfolio summary to transform
+
+    Returns:
+        A dictionary with 'data' and 'layout' keys suitable for a Plotly chart
+    """
+    logger.debug("Transforming data for allocations chart")
+
+    # Skip empty portfolios
+    if portfolio_summary.portfolio_estimate_value == 0:
+        logger.warning("Empty portfolio - no data for allocations chart")
+        return {
+            "data": [],
+            "layout": {
+                "height": 400,
+                "annotations": [
+                    {
+                        "text": "No portfolio data available",
+                        "showarrow": False,
+                        "font": {"color": "#7F8C8D"},
+                    }
+                ],
+            },
+        }
+
+    # Get component values (short values are negative)
+    values = get_portfolio_component_values(portfolio_summary)
+
+    # Calculate percentages
+    percentages = calculate_component_percentages(values)
+
+    # Calculate combined values
+    long_total = values["long_stock"] + values["long_option"]
+    short_total = values["short_stock"] + values["short_option"]
+
+    # Format detailed breakdown for hover text
+    long_text = (
+        f"Long Total: {format_currency(long_total)} ({percentages['long_total']:.1f}%)<br>"
+        f"• Stocks: {format_currency(values['long_stock'])} ({percentages['long_stock']:.1f}%)<br>"
+        f"• Options: {format_currency(values['long_option'])} ({percentages['long_option']:.1f}%)"
+    )
+
+    short_text = (
+        f"Short Total: {format_currency(short_total)} ({percentages['short_total']:.1f}%)<br>"
+        f"• Stocks: {format_currency(values['short_stock'])} ({percentages['short_stock']:.1f}%)<br>"
+        f"• Options: {format_currency(values['short_option'])} ({percentages['short_option']:.1f}%)"
+    )
+
+    cash_text = f"Cash: {format_currency(values['cash'])} ({percentages['cash']:.1f}%)"
+    pending_text = (
+        f"Pending: {format_currency(values['pending'])} ({percentages['pending']:.1f}%)"
+    )
+
+    # Create compact text labels for display on bars
+    long_display_text = format_compact_currency(long_total)
+    short_display_text = format_compact_currency(short_total)
+    cash_display_text = format_compact_currency(values["cash"])
+    pending_display_text = format_compact_currency(values["pending"])
+
+    # Create the bar chart data with a single bar for each category
+    chart_data = {
+        "data": [
+            # Long position (single bar with combined value)
+            {
+                "name": "Long",
+                "x": ["Long"],
+                "y": [long_total],
+                "type": "bar",
+                "marker": {"color": ChartColors.LONG},
+                "text": [long_display_text],  # Compact text for display
+                "textposition": "inside",  # Show text inside bars
+                "insidetextanchor": "middle",  # Center text
+                "hoverinfo": "text",
+                "hovertemplate": "%{text}<br>" + long_text + "<extra></extra>",
+                "textfont": {"color": "white", "size": 12},  # Ensure text is visible
+            },
+            # Short position (single bar with combined value)
+            {
+                "name": "Short",
+                "x": ["Short"],
+                "y": [short_total],  # Already negative
+                "type": "bar",
+                "marker": {"color": ChartColors.SHORT},
+                "text": [short_display_text],  # Compact text for display
+                "textposition": "inside",  # Show text inside bars
+                "insidetextanchor": "middle",  # Center text
+                "hoverinfo": "text",
+                "hovertemplate": "%{text}<br>" + short_text + "<extra></extra>",
+                "textfont": {"color": "white", "size": 12},  # Ensure text is visible
+            },
+            # Cash (single bar)
+            {
+                "name": "Cash",
+                "x": ["Cash"],
+                "y": [values["cash"]],
+                "type": "bar",
+                "marker": {"color": ChartColors.CASH},
+                "text": [cash_display_text],  # Compact text for display
+                "textposition": "inside",  # Show text inside bars
+                "insidetextanchor": "middle",  # Center text
+                "hoverinfo": "text",
+                "hovertemplate": "%{text}<br>" + cash_text + "<extra></extra>",
+                "textfont": {"color": "white", "size": 12},  # Ensure text is visible
+            },
+            # Pending (single bar)
+            {
+                "name": "Pending",
+                "x": ["Pending"],
+                "y": [values["pending"]],
+                "type": "bar",
+                "marker": {"color": ChartColors.PENDING},
+                "text": [pending_display_text],  # Compact text for display
+                "textposition": "inside",  # Show text inside bars
+                "insidetextanchor": "middle",  # Center text
+                "hoverinfo": "text",
+                "hovertemplate": "%{text}<br>" + pending_text + "<extra></extra>",
+                "textfont": {"color": "white", "size": 12},  # Ensure text is visible
+            },
+        ],
+        "layout": {
+            "title": {
+                "text": "Portfolio Allocation",
+                "font": {"size": 16, "color": "#2C3E50"},
+                "x": 0.5,  # Center the title
+                "xanchor": "center",
+            },
+            "barmode": "relative",  # Use relative mode instead of stack
+            "margin": {"l": 60, "r": 60, "t": 50, "b": 40, "pad": 4},
+            "autosize": True,  # Allow the chart to resize with its container
+            "paper_bgcolor": "white",
+            "plot_bgcolor": "white",
+            "font": {
+                "family": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif"
+            },
+            "showlegend": False,  # Hide legend since bar labels are clear
+            "yaxis": {
+                "title": "Value ($)",
+                "type": "linear",
+                "tickformat": "$,.1s",  # Use compact format (K, M, B)
+                "gridcolor": "#E5E5E5",
+                "exponentformat": "none",  # Hide exponent notation
+                "showticklabels": True,
+                "nticks": 10,  # More tick marks for better readability
+                "showgrid": True,
+                "zeroline": True,
+                "zerolinecolor": "#000000",
+                "zerolinewidth": 2,
+                "automargin": True,  # Ensure labels don't get cut off
+                "ticklen": 5,  # Longer tick marks
+                "tickwidth": 1,  # Slightly thicker ticks
+                "tickcolor": "#777777",  # Darker tick color
+            },
+            "height": 400,  # Increased height for better visualization
+        },
+    }
+
+    # Calculate the maximum and minimum y-values for setting the y-axis range
+    max_value = max(
+        long_total,
+        values["cash"],
+        values["pending"],
+        1,  # Ensure we have a non-zero range
+    )
+
+    min_value = min(
+        short_total,
+        0,  # Ensure we include zero in the range
+    )
+
+    # Add padding for better visualization
+    top_padding = 0.1  # 10% padding on top
+    bottom_padding = 0.2  # 20% padding on bottom (more space for negative values)
+
+    # Determine the appropriate y-axis range based on the data
+    if abs(min_value) < 0.001:
+        # No significant short positions, focus on positive values only
+        chart_data["layout"]["yaxis"]["range"] = [
+            -max_value * 0.05,  # Small negative space for zero line visibility
+            max_value * (1 + top_padding),
+        ]
+    elif abs(min_value) < max_value * 0.1:
+        # Short positions are small (less than 10% of long)
+        # Use asymmetric scale with just enough room for short positions
+        chart_data["layout"]["yaxis"]["range"] = [
+            min_value * (1 + bottom_padding),
+            max_value * (1 + top_padding),
+        ]
+    elif abs(min_value) < max_value * 0.3:
+        # Short positions are moderate (10-30% of long)
+        # Use moderately asymmetric scale
+        chart_data["layout"]["yaxis"]["range"] = [
+            min_value * (1 + bottom_padding),
+            max_value * (1 + top_padding),
+        ]
+    else:
+        # Short positions are significant (>30% of long)
+        # Use a more balanced scale, but still optimized for the actual data
+        max_abs = max(abs(max_value), abs(min_value))
+        chart_data["layout"]["yaxis"]["range"] = [
+            -max_abs * (1 + bottom_padding) if min_value < 0 else -max_value * 0.05,
+            max_abs * (1 + top_padding),
+        ]
+
+    # Add more tick marks for better readability
+    chart_data["layout"]["yaxis"]["nticks"] = 12
+
+    return chart_data
+
+
+def create_dashboard_metrics(
+    portfolio_summary: PortfolioSummary,
+) -> list[dict[str, str]]:
+    """Create a list of key metrics for the dashboard.
+
+    Args:
+        portfolio_summary: Portfolio summary data from the data model
+
+    Returns:
+        List of dictionaries with title, value, and help_text for each metric
+    """
+    logger.debug("Creating dashboard metrics")
+
+    # Define the metrics to display
+    metrics = [
+        {
+            "title": "Total Value",
+            "value": format_currency(portfolio_summary.total_value_net),
+            "help_text": portfolio_summary.help_text.get("total_value_net", ""),
+        },
+        {
+            "title": "Portfolio Beta",
+            "value": f"{portfolio_summary.portfolio_beta:.2f}",
+            "help_text": portfolio_summary.help_text.get("portfolio_beta", ""),
+        },
+        {
+            "title": "Long Exposure",
+            "value": format_currency(portfolio_summary.long_exposure.total_value),
+            "help_text": portfolio_summary.help_text.get("long_exposure", ""),
+        },
+        {
+            "title": "Short Exposure",
+            "value": format_currency(portfolio_summary.short_exposure.total_value),
+            "help_text": portfolio_summary.help_text.get("short_exposure", ""),
+        },
+        {
+            "title": "Options Exposure",
+            "value": format_currency(portfolio_summary.options_exposure.total_value),
+            "help_text": portfolio_summary.help_text.get("options_exposure", ""),
+        },
+    ]
+
+    return metrics