clawdfolio 2.2.0__tar.gz

clawdfolio-2.2.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

clawdfolio-2.2.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Type check with mypy
+        run: mypy src/clawdfolio --ignore-missing-imports
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=src/clawdfolio --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v5
+        with:
+          file: ./coverage.xml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*

clawdfolio-2.2.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Only run if PYPI_API_TOKEN is configured
+    if: ${{ vars.ENABLE_PYPI_PUBLISH == 'true' }}
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install twine
+        run: pip install twine
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

clawdfolio-2.2.0/.gitignore

@@ -0,0 +1,70 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# Secrets - NEVER commit these
+config.yaml
+config.json
+*.env
+.env.*
+secrets.yaml
+credentials.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Local data
+data/
+*.db
+*.sqlite
+
+# Keep bundled legacy finance libs for v2 migration
+!src/clawdfolio/legacy_finance/scripts/lib/
+!src/clawdfolio/legacy_finance/scripts/lib/**

clawdfolio-2.2.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

clawdfolio-2.2.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.2.0] - 2025-02-14
+
+### Added
+
+- `py.typed` marker file for PEP 561 compliance, enabling downstream type-checking support.
+- `clawdfolio.utils.suppress` shared module with `suppress_stdio` context manager (DRY refactor from `brokers/futu.py` and `brokers/longport.py`).
+- `CHANGELOG.md` to track version history.
+- Structured `logging` across core modules (`market/data.py`, `brokers/futu.py`, `brokers/longport.py`, `cli/main.py`).
+- `_yf_symbol()` centralised ticker normalisation helper in `market/data.py`.
+
+### Changed
+
+- **Version bumped to 2.2.0.**
+- CLI `--version` flag now reads dynamically from `clawdfolio.__version__` instead of a hardcoded string.
+- `get_quotes_yfinance()` rewritten to use `yf.download` for batch retrieval with per-ticker fallback, significantly reducing API calls.
+- Market data cache (`_cache`) is now protected by `threading.Lock` for thread-safe concurrent access.
+- NaN check in `_safe_float()` replaced from `num == num` idiom to explicit `math.isnan(num)`.
+- Config search now prefers `CLAWDFOLIO_CONFIG` env var and `~/.config/clawdfolio/` paths, with backward-compatible fallback to `PORTFOLIO_MONITOR_CONFIG` and `~/.config/portfolio-monitor/`.
+- Module docstring in `core/config.py` and `core/exceptions.py` updated from "Portfolio Monitor" to "Clawdfolio".
+
+### Fixed
+
+- All repository URLs in `pyproject.toml`, `README.md`, and `README_CN.md` corrected from `2165187809-AXE/clawdfolio` to `YichengYang-Ethan/clawdfolio`.
+- Removed unused `import io` side-effect in `brokers/longport.py` (kept only where actually needed).
+
+## [2.1.0] - 2025-01-28
+
+### Added
+
+- Dedicated options strategy playbook (`docs/OPTIONS_STRATEGY_PLAYBOOK_v2.1.md`).
+- Research-to-execution alignment for CC and Sell Put lifecycle management.
+- Explicit gamma-risk, margin, leverage, roll, assignment, and pause-condition decision rules.
+- Feature mapping connecting strategy decisions to `clawdfolio options` and `clawdfolio finance` workflows.
+
+## [2.0.0] - 2025-01-15
+
+### Added
+
+- Full finance migration from `~/clawd/scripts` (20 production workflows).
+- `clawdfolio finance` command group (list, init, run).
+- Categorized workflow catalog and bundled `legacy_finance` package.
+- Mutable workspace bootstrap (`~/.clawdfolio/finance`).
+- Wilder RSI smoothing, Longport symbol fix, yfinance hardening.
+- Options quote/chain/buyback monitor.

clawdfolio-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 YICHENG YANG
+
+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.

clawdfolio-2.2.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: clawdfolio
+Version: 2.2.0
+Summary: Production-grade quantitative portfolio toolkit — multi-broker aggregation, institutional risk analytics, options lifecycle management, and 20+ automated finance workflows
+Project-URL: Homepage, https://github.com/YichengYang-Ethan/clawdfolio
+Project-URL: Documentation, https://github.com/YichengYang-Ethan/clawdfolio#readme
+Project-URL: Repository, https://github.com/YichengYang-Ethan/clawdfolio.git
+Project-URL: Issues, https://github.com/YichengYang-Ethan/clawdfolio/issues
+Author: YICHENG YANG
+License-Expression: MIT
+License-File: LICENSE
+Keywords: broker,claude-code-compatible,clawdbot,finance,futu,investment,longport,moomoo,options-greeks,options-trading,portfolio,portfolio-analytics,quantitative-finance,risk-management,sharpe-ratio,trading,var
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: yfinance>=0.2.30
+Provides-Extra: all
+Requires-Dist: futu-api>=7.0.0; extra == 'all'
+Requires-Dist: longport>=1.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Provides-Extra: futu
+Requires-Dist: futu-api>=7.0.0; extra == 'futu'
+Provides-Extra: longport
+Requires-Dist: longport>=1.0.0; extra == 'longport'
+Description-Content-Type: text/markdown
+
+# Clawdfolio 🦙📊
+
+[![CI](https://github.com/YichengYang-Ethan/clawdfolio/actions/workflows/ci.yml/badge.svg)](https://github.com/YichengYang-Ethan/clawdfolio/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/clawdfolio.svg)](https://pypi.org/project/clawdfolio/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-blueviolet)](https://github.com/anthropics/claude-code)
+
+English | [中文](README_CN.md)
+
+> **Production-grade quantitative portfolio toolkit** — multi-broker aggregation, institutional risk analytics, options lifecycle management, and 20+ automated finance workflows.
+>
+> *Also available as a native [Claude Code](https://github.com/anthropics/claude-code) / Clawdbot skill.*
+
+---
+
+## Why Clawdfolio?
+
+| Traditional Tools | Clawdfolio |
+|-------------------|------------|
+| Manual data entry | Auto-sync from Longport, Moomoo/Futu |
+| Basic P&L tracking | VaR, Sharpe, Beta, Max Drawdown, HHI |
+| Single broker view | Multi-broker aggregation |
+| Spreadsheet alerts | Smart RSI / price / P&L alerts |
+| No extensibility | Python API + CLI + Claude Code skill |
+
+---
+
+## Features
+
+- **Multi-Broker Support** — Longport (Longbridge), Moomoo/Futu, or demo mode
+- **Risk Analytics** — Volatility, Beta, Sharpe Ratio, Value at Risk, Max Drawdown
+- **Technical Analysis** — RSI, SMA, EMA, Bollinger Bands
+- **Concentration Analysis** — HHI index, sector exposure, correlation warnings
+- **Smart Alerts** — Price movements, RSI extremes, P&L thresholds
+- **Earnings Calendar** — Track upcoming earnings for holdings
+- **DCA Analysis** — Dollar-cost averaging signals
+- **Options Toolkit** — Option quote/Greeks, option chain snapshot, buyback trigger monitor
+- **Options Strategy Playbook (v2.1)** — Covered Call and Sell Put lifecycle management with delta/gamma/margin guardrails
+- **Finance Workflow Suite** — 20 production workflows for reports, alerts, market intel, and broker snapshots
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install clawdfolio                  # Core
+pip install clawdfolio[longport]        # + Longport broker
+pip install clawdfolio[futu]            # + Moomoo/Futu broker
+pip install clawdfolio[all]             # All brokers
+```
+
+### CLI Usage
+
+```bash
+clawdfolio summary                     # Portfolio overview
+clawdfolio risk                        # Risk metrics (VaR, Sharpe, Beta, etc.)
+clawdfolio quotes AAPL TSLA NVDA       # Real-time quotes
+clawdfolio alerts                      # Check alerts
+clawdfolio earnings                    # Upcoming earnings calendar
+clawdfolio dca AAPL                    # DCA analysis
+```
+
+### Options Commands
+
+```bash
+clawdfolio options expiries TQQQ
+clawdfolio options quote TQQQ --expiry 2026-06-18 --strike 60 --type C
+clawdfolio options chain TQQQ --expiry 2026-06-18 --side both --limit 10
+clawdfolio options buyback             # Trigger check from config
+```
+
+### Python API
+
+```python
+from clawdfolio.brokers import get_broker
+from clawdfolio.analysis import analyze_risk
+
+broker = get_broker("demo")  # or "longport", "futu"
+broker.connect()
+
+portfolio = broker.get_portfolio()
+metrics = analyze_risk(portfolio)
+
+print(f"Net Assets: ${portfolio.net_assets:,.2f}")
+print(f"Sharpe Ratio: {metrics.sharpe_ratio:.2f}")
+print(f"VaR 95%: ${metrics.var_95:,.2f}")
+```
+
+---
+
+## Risk Metrics
+
+| Metric | Description |
+|--------|-------------|
+| **Volatility** | 20-day and 60-day annualized |
+| **Beta** | Correlation with SPY/QQQ |
+| **Sharpe Ratio** | Risk-adjusted returns |
+| **VaR** | Value at Risk (95%/99%) |
+| **Max Drawdown** | Largest peak-to-trough decline |
+| **HHI** | Portfolio concentration index |
+
+---
+
+## Options Toolkit
+
+The built-in options module provides real-time Greeks inspection, chain analysis, and stateful buyback monitoring:
+
+| Command | Description |
+|---------|-------------|
+| `options expiries` | List available expiry dates for a symbol |
+| `options quote` | Single option quote with Greeks (delta, gamma, theta, vega, IV) |
+| `options chain` | Full option chain snapshot with filtering |
+| `options buyback` | Stateful trigger monitor for short option buyback |
+
+Strategy methodology is documented in the [Options Strategy Playbook](docs/OPTIONS_STRATEGY_PLAYBOOK_v2.1.md) — covering Covered Call and Sell Put lifecycle management with delta-based strike selection, roll/assignment rules, and margin guardrails.
+
+---
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Longport
+export LONGPORT_APP_KEY=your_app_key
+export LONGPORT_APP_SECRET=your_app_secret
+export LONGPORT_ACCESS_TOKEN=your_access_token
+
+# Moomoo: Run OpenD locally on port 11111
+```
+
+### Config File (optional)
+
+Create `config.yaml`:
+
+```yaml
+brokers:
+  longport:
+    enabled: true
+  futu:
+    enabled: true
+    extra:
+      host: "127.0.0.1"
+      port: 11111
+
+alerts:
+  pnl_trigger: 500.0
+  rsi_high: 80
+  rsi_low: 20
+
+option_buyback:
+  enabled: true
+  symbol: "TQQQ"
+  targets:
+    - name: "cc-june"
+      strike: 60
+      expiry: "2026-06-18"
+      type: "C"
+      trigger_price: 1.60
+      qty: 2
+      reset_pct: 0.20
+```
+
+### Supported Brokers
+
+| Broker | Region | Status |
+|--------|--------|--------|
+| Demo | Global | Built-in |
+| Longport | US/HK/SG | Optional |
+| Moomoo/Futu | US/HK/SG | Optional |
+
+---
+
+## Claude Code & Clawdbot Integration
+
+Clawdfolio works as a native skill in [Claude Code](https://github.com/anthropics/claude-code) and Clawdbot environments:
+
+```
+/clawdfolio summary
+/clawdfolio risk
+/clawdfolio quotes AAPL MSFT NVDA
+/clawdfolio alerts
+/clawdfolio options chain TQQQ --expiry 2026-06-18
+```
+
+The skill is registered via [`SKILL.md`](SKILL.md) and supports all CLI commands through natural language interaction.
+
+---
+
+## Finance Workflows
+
+20 production workflows migrated from live trading infrastructure, organized by category:
+
+| Category | Examples |
+|----------|---------|
+| **Portfolio Reports** | Account report, portfolio analysis, risk breakdown |
+| **Briefing Cards** | Daily brief (console + Telegram), multi-format |
+| **Alerts & Monitors** | Price/RSI alerts, option buyback trigger |
+| **Market Intelligence** | Real-time quotes, earnings calendar, market news |
+| **Broker Snapshots** | Longport / Moomoo asset summaries |
+| **Strategy** | DCA proposals |
+
+```bash
+clawdfolio finance list                # Browse all workflows by category
+clawdfolio finance init                # Bootstrap ~/.clawdfolio/finance workspace
+clawdfolio finance run <workflow_id>   # Execute a workflow
+```
+
+---
+
+## Ecosystem
+
+Clawdfolio is the data hub of a quantitative finance toolkit. Other projects consume its output or share its analytical methodology.
+
+```
+         ┌──────────────────────────┐
+         │   ML Research Layer      │
+         │  crypto-prediction       │
+         │  ESG-prediction          │
+         └────────────┬─────────────┘
+                      │ research informs alert thresholds
+         ┌────────────▼─────────────┐
+         │  clawdfolio (this repo)  │
+         │  brokers · risk · alerts │
+         │  clawdfolio summary -o json
+         └────────────┬─────────────┘
+                      │ JSON data feed
+         ┌────────────▼─────────────┐
+         │   Visualization Layer    │
+         │  investment-dashboard    │
+         │  QQQ-200D-Dashboard     │
+         └──────────────────────────┘
+```
+
+| Project | Layer | Relationship |
+|---------|-------|-------------|
+| **clawdfolio** (this repo) | Core Engine | Risk analytics, broker integration, signal generation, options strategy |
+| [investment-dashboard](https://github.com/YichengYang-Ethan/investment-dashboard) | Visualization | Web frontend — consumes `clawdfolio summary -o json` for portfolio data |
+| [QQQ-200D-Deviation-Dashboard](https://github.com/YichengYang-Ethan/QQQ-200D-Deviation-Dashboard) | Visualization | Implements clawdfolio's SMA deviation methodology as a standalone React dashboard |
+| [crypto-return-prediction](https://github.com/YichengYang-Ethan/crypto-return-prediction-kaggle) | ML Research | Short-term momentum prediction — shares RSI/Bollinger feature engineering |
+| [ESG-Driven-Stock-Value-Prediction](https://github.com/YichengYang-Ethan/ESG-Driven-Stock-Value-Prediction) | ML Research | Long-term value factor research — ESG signals complementing technical indicators |
+
+---
+
+<details>
+<summary><strong>Changelog</strong></summary>
+
+### v2.2.0 (2025-02-14)
+
+- Thread-safe market data caching (`threading.Lock`)
+- Batch quote fetching via `yf.download` with per-ticker fallback
+- Shared `suppress_stdio` utility (DRY refactor)
+- Dynamic CLI version from `__version__`
+- PEP 561 compliance (`py.typed` marker)
+- Structured logging across core modules
+- Centralized ticker normalization (`_yf_symbol()`)
+- Config path migration to `clawdfolio` namespace (backward-compatible)
+
+### v2.1.0 (2025-01-28)
+
+- Options Strategy Playbook v2.1 (`docs/OPTIONS_STRATEGY_PLAYBOOK_v2.1.md`)
+- Research-to-execution framework for CC and Sell Put lifecycle
+- Explicit gamma-risk, margin, leverage, and assignment decision rules
+
+### v2.0.0 (2025-01-15)
+
+- Full finance migration: 20 production workflows from live trading infrastructure
+- `clawdfolio finance` command group (list, init, run)
+- Mutable workspace bootstrap (`~/.clawdfolio/finance`)
+- Options quote/chain/buyback monitor
+- Wilder RSI smoothing, Longport symbol fix, yfinance hardening
+
+See [CHANGELOG.md](CHANGELOG.md) for full details.
+
+</details>
+
+---
+
+## Contributing
+
+Contributions welcome! Please submit a Pull Request.
+
+## License
+
+MIT License — see [LICENSE](LICENSE)
+
+## Links
+
+- [GitHub Repository](https://github.com/YichengYang-Ethan/clawdfolio)
+- [Report Issues](https://github.com/YichengYang-Ethan/clawdfolio/issues)
+- [Options Strategy Playbook](docs/OPTIONS_STRATEGY_PLAYBOOK_v2.1.md)
+- [Claude Code](https://github.com/anthropics/claude-code)