Why it is worth attention

It combines a conversational interface with deterministic risk checks and transparent accounting, all without requiring any third-party Python packages.

Who it is for

Individual investors wanting simulated trading practice
Hermes platform users seeking portfolio automation
Developers learning portfolio management systems
Educators teaching market mechanics and risk management

Use cases

Backtesting investment strategies with evidence-based decisions
Managing a virtual portfolio with automated research and risk controls
Learning market dynamics without risking real capital
Running paper trading competitions or educational simulations

Strengths

Zero third-party Python dependencies (standard-library only)
Auditable SQLite ledger with full transaction history
Rigorous safety model: no leverage, shorts, or real-money execution
Evidence-based decisions requiring at least two sources per thesis

Considerations

Requires Hermes Agent with configured Web Search & Extract for full research
No broker integration or real-world order execution
Limited to long-only positions; no shorts, derivatives, or margin
Optional Convex dashboard needs separate deployment and is not bundled

README quick start

Virtual Investor — Harper

Harper is a long-only virtual portfolio engine and conversational investing skill for Hermes. It combines sourced market research with deterministic risk checks, virtual execution, marked-to-market accounting, forecast calibration, and an auditable SQLite ledger.

Harper can research and simulate intraday or longer-held positions across markets through versioned market adapters. It never places real orders, connects to a broker, uses leverage, or opens short positions.

Highlights

Evidence-backed BUY, SELL, and NO_TRADE decisions
Long-only risk controls enforced by the portfolio engine
Intraday and position-style theses with explicit invalidation rules
Sourced quotes, market sessions, catalysts, and corporate actions
Candidate screening, research memory, and forecast scoring
Market adapters with transparent fallbacks for newly configured markets
Optional Convex dashboard sync and timezone-aware Hermes automation with a user-selected configured messaging destination or local-only reports
Python standard-library runtime with local SQLite storage

Requirements

Python 3
Hermes Agent with Web Search & Extract configured for full research use
pytest only for running the development test suite

The runtime does not require third-party Python packages. Portfolio data, credentials, Hermes configuration, schedules, and virtual environments are not included in this repository.

Install

Install Harper directly from GitHub with Hermes:

hermes skills install balsimpson/virtual-investor/skills/harper

Start a new Hermes conversation, or run /reset in the current conversation, then invoke /harper. Harper will ask for one onboarding detail at a time, including the virtual starting cash after the reporting currency is known. It offers a sensible currency-aware default that the user can confirm or replace, verifies live research access, and initializes the local ledger idempotently.

Verify or update the installation with:

hermes skills list
hermes skills check
hermes skills update harper

For local development, copy the skill directory instead:

mkdir -p ~/.hermes/skills/finance/harper
rsync -a skills/harper/ ~/.hermes/skills/finance/harper/

To configure research access, run:

hermes tools

Choose Web Search & Extract and configure working provid

Related repositories

Similar projects matched by category, topics, and programming language.

lopopolo

Featured

harness-engineering

Harness Engineering is a methodology for improving coding agent outputs by carefully crafting the environment around them—providing curated context, tools, and executable constraints that encode an organization’s nonfunctional requirements and cumulative lessons.

AI & Machine LearningAI Agents

2,390

slvDev

Featured

esp32-ai

A 28.9 million parameter language model runs on an $8 ESP32-S3 microcontroller entirely on-device, generating simple stories at about 9.5 tokens per second.

AI & Machine LearningLarge Language Models

1,960

littledivy

Featured

mimic

mimic captures traffic from any iOS or web app and automatically generates a Python client library that lets you call the app's API like a regular library.

AI & Machine Learning

1,482