How oskarajaspinall-cell/paper-portfolio works
Paper Portfolio is a paper-trading stock research and portfolio system: it screens a global universe, researches candidates with Claude, applies deterministic portfolio rules, and tracks results against the S&P 500. Its weekly workflow is complemented by daily price, corporate-action, entry-watch, dip-radar, and funding-queue routines, plus dashboard and performance reporting. The README documents the product flow; sampled excerpts and the SOURCE INDEX support selected implementation links. Unsampled subsystem details are represented only where documented, so some edges are omitted.
Main entry points: weekly_run.py Weekly workflow · portfolio.py Portfolio engine · screen.py Weekly screen · fact_sheet.py Fact sheets
Components 24
Research and screening
- Stock universe
scripts/universe.py - Weekly screen
scripts/screen.py - Fact sheets
scripts/fact_sheet.py - Fair valuation
scripts/valuation.py
Review and decisions
- Claude agents
.claude/agents - Weekly workflow
scripts/weekly_run.py - Holding review
scripts/weekly_scan.py - Entry research
scripts/entry_research.py
Portfolio operations
- Portfolio engine
scripts/portfolio.py - Position sizing
scripts/risk.py - Macro regime
scripts/regime.py - Funding queue
scripts/funding_queue.py - Corporate actions
scripts/corporate_actions.py
Monitoring and reporting
- Entry watch
scripts/entry_watch.py - Dip radar
scripts/dip_radar.py - Decision log
scripts/decision_log.py - Decision scorecard
scripts/scorecard.py - Live dashboard
scripts/dashboard.py - Return attribution
scripts/attribution.py
Market data
- Fundamental data
scripts/fetch_data.py - Portfolio prices
scripts/prices.py - Market data services
Other components
- Portfolio owner
- S&P 500 benchmark
Connections 29
- Portfolio owner → Weekly workflow: runs review
README.md - Weekly workflow → Portfolio engine: fills orders
README.md - Weekly workflow → Holding review: checks holdings
README.md - Weekly workflow → Weekly screen: runs screen
README.md - Weekly screen → Stock universe: ranks universe
scripts/screen.py - Weekly screen → Fundamental data: reads fundamentals
scripts/screen.py - Weekly screen → Fact sheets: deep dives
scripts/screen.py - Fact sheets → Fundamental data: reads company data
scripts/fact_sheet.py - Fact sheets → Fair valuation: requests fair value
scripts/fact_sheet.py - Weekly workflow → Claude agents: starts agent sessions
scripts/weekly_run.py - Claude agents → Entry research: researches candidates
README.md - Weekly workflow → Decision log: records decisions
README.md - Weekly workflow → Portfolio engine: submits orders
README.md - Portfolio engine → Position sizing: sizes positions
scripts/portfolio.py - Portfolio engine → Portfolio prices: gets quotes
scripts/portfolio.py - Portfolio engine → Macro regime: uses cash reserve
scripts/portfolio.py - Portfolio engine → Funding queue: queues blocked buys
scripts/funding_queue.py - Portfolio engine → Corporate actions: applies adjustments
scripts/corporate_actions.py - Macro regime → Market data services: reads macro indicators
scripts/regime.py - Portfolio prices → Market data services: fetches price history
scripts/prices.py - Weekly workflow → Entry watch: checks entry hits
README.md - Weekly workflow → Dip radar: runs dip radar
README.md - Entry watch → Entry research: flags hit stocks
README.md - Dip radar → Entry research: flags dip signals
README.md - Weekly workflow → Decision scorecard: checks evaluations
scripts/weekly_run.py - Weekly workflow → Live dashboard: refreshes dashboard
README.md - Weekly workflow → Return attribution: reports returns
README.md - Decision log → S&P 500 benchmark: scores against
scripts/decision_log.py - Portfolio owner → Live dashboard: views portfolio
README.md