Add Hermes control plane automation foundation

.env.example

@@ -7,3 +7,50 @@ DEEPSEEK_API_KEY=
 DASHSCOPE_API_KEY=
 ZHIPU_API_KEY=
 OPENROUTER_API_KEY=
+
+# Hermes / automation-friendly routing
+# Recommended modes: manual, cost_optimized
+MODEL_ROUTING_MODE=cost_optimized
+
+# Primary provider for automated runs. Use ollama for home-PC local models,
+# openrouter for free/cheap cloud models, or openai/google/anthropic for premium.
+LLM_PROVIDER=ollama
+
+# OpenAI-compatible endpoint. For a home PC on Tailscale, use:
+# LLM_BACKEND_URL=http://home-pc-tailnet-name:11434/v1
+LLM_BACKEND_URL=http://127.0.0.1:11434/v1
+OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
+OLLAMA_API_KEY=ollama
+
+# Default models for non-interactive Hermes runs
+QUICK_THINK_LLM=qwen3:latest
+DEEP_THINK_LLM=qwen3:latest
+LOCAL_QUICK_MODEL=qwen3:latest
+LOCAL_DEEP_MODEL=qwen3:latest
+
+# Optional OpenRouter free/cheap fallback model IDs
+OPENROUTER_FREE_QUICK_MODEL=
+OPENROUTER_FREE_DEEP_MODEL=
+OPENROUTER_CHEAP_QUICK_MODEL=
+OPENROUTER_CHEAP_DEEP_MODEL=
+
+# Optional premium fallback defaults
+PAID_LLM_PROVIDER=openai
+PAID_QUICK_MODEL=gpt-5.4-mini
+PAID_DEEP_MODEL=gpt-5.4
+
+# TradingAgents runtime paths and behavior
+TRADINGAGENTS_RESULTS_DIR=
+TRADINGAGENTS_CACHE_DIR=
+TRADINGAGENTS_MEMORY_LOG_PATH=
+TRADINGAGENTS_CHECKPOINT=false
+TRADINGAGENTS_OUTPUT_LANGUAGE=English
+TRADINGAGENTS_MAX_DEBATE_ROUNDS=1
+TRADINGAGENTS_MAX_RISK_DISCUSS_ROUNDS=1
+
+# Data vendors: yfinance or alpha_vantage
+ALPHA_VANTAGE_API_KEY=
+TRADINGAGENTS_CORE_STOCK_VENDOR=yfinance
+TRADINGAGENTS_TECHNICAL_VENDOR=yfinance
+TRADINGAGENTS_FUNDAMENTAL_VENDOR=yfinance
+TRADINGAGENTS_NEWS_VENDOR=yfinance

.gitignore

@@ -27,8 +27,6 @@ share/python-wheels/
 MANIFEST
 
 # PyInstaller
-#   Usually these files are written by a python script from a template
-#   before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
 *.spec
 
@@ -55,8 +53,14 @@ cover/
 *.mo
 *.pot
 
-# Django stuff:
+# Framework/runtime state
+reports/
+memory/*.jsonl
+memory/*.tmp
+logs/
 *.log
+
+# Django stuff:
 local_settings.py
 db.sqlite3
 db.sqlite3-journal
@@ -83,48 +87,29 @@ profile_default/
 ipython_config.py
 
 # pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
 # .python-version
 
 # pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
 # Pipfile.lock
 
 # UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
 # uv.lock
 
 # poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
 # poetry.lock
 # poetry.toml
 
 # pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
-#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
 # pdm.lock
 # pdm.toml
 .pdm-python
 .pdm-build/
 
 # pixi
-#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
 # pixi.lock
-#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
-#   in the .venv directory. It is recommended not to include this directory in version control.
 .pixi
 
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+# PEP 582
 __pypackages__/
 
 # Celery stuff
@@ -182,23 +167,12 @@ dmypy.json
 cython_debug/
 
 # PyCharm
-#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#   and can be added to the global gitignore or merged into this file.  For a more nuclear
-#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
 # .idea/
 
 # Abstra
-#   Abstra is an AI-powered process automation framework.
-#   Ignore directories containing user credentials, local state, and settings.
-#   Learn more at https://abstra.io/docs
 .abstra/
 
 # Visual Studio Code
-#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
-#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
-#   you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 
 # Ruff stuff:

AGENTS.md

@@ -0,0 +1,41 @@
+# Agent Operating Rules
+
+This repository is an AI-assisted trading research framework. Agents may help write code, run research jobs, summarize results, and maintain documentation.
+
+## Hard boundaries
+
+- Do not add live broker execution in this repo without an explicit issue and review plan.
+- Do not commit API keys, broker secrets, `.env`, generated reports, or memory logs.
+- Do not remove paper-trading defaults or safety warnings.
+- Do not make generated LLM text directly executable as broker orders.
+- Do not push directly to `main`; use branches and pull requests.
+- Do not weaken risk controls, audit logging, or kill-switch behavior.
+
+## Preferred workflow
+
+1. Inspect before editing.
+2. Make small, reviewable changes.
+3. Prefer deterministic code over LLM judgment where possible.
+4. Use JSON schemas for machine-consumed outputs.
+5. Save research outputs under `reports/` and lessons under `memory/`; these are ignored by git.
+6. Keep Hermes scripts stable and explicit so the home-PC agent runs known commands instead of improvising.
+
+## Architecture rule
+
+```text
+AI researches.
+TradingOrg produces signals.
+A separate app validates strategy and risk.
+Broker execution is deterministic and gated.
+```
+
+## Model routing rule
+
+Use the cheapest reliable model tier first:
+
+1. deterministic code
+2. local Ollama/home-PC model
+3. free or cheap cloud model through OpenRouter or similar
+4. premium cloud model only when quality or consequence justifies it
+
+Log provider/model details for any machine-consumed signal.

docker-compose.yml

@@ -3,8 +3,19 @@ services:
     build: .
     env_file:
       - .env
+    environment:
+      - LLM_PROVIDER=${LLM_PROVIDER:-ollama}
+      - LLM_BACKEND_URL=${LLM_BACKEND_URL:-http://host.docker.internal:11434/v1}
+      - OLLAMA_BASE_URL=${OLLAMA_BASE_URL:-http://host.docker.internal:11434/v1}
+      - QUICK_THINK_LLM=${QUICK_THINK_LLM:-qwen3:latest}
+      - DEEP_THINK_LLM=${DEEP_THINK_LLM:-qwen3:latest}
+      - MODEL_ROUTING_MODE=${MODEL_ROUTING_MODE:-cost_optimized}
     volumes:
       - tradingagents_data:/home/appuser/.tradingagents
+      - ./reports:/home/appuser/app/reports
+      - ./memory:/home/appuser/app/memory
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     tty: true
     stdin_open: true
 
@@ -21,8 +32,15 @@ services:
       - .env
     environment:
       - LLM_PROVIDER=ollama
+      - LLM_BACKEND_URL=${LLM_BACKEND_URL:-http://ollama:11434/v1}
+      - OLLAMA_BASE_URL=${OLLAMA_BASE_URL:-http://ollama:11434/v1}
+      - QUICK_THINK_LLM=${QUICK_THINK_LLM:-qwen3:latest}
+      - DEEP_THINK_LLM=${DEEP_THINK_LLM:-qwen3:latest}
+      - MODEL_ROUTING_MODE=${MODEL_ROUTING_MODE:-cost_optimized}
     volumes:
       - tradingagents_data:/home/appuser/.tradingagents
+      - ./reports:/home/appuser/app/reports
+      - ./memory:/home/appuser/app/memory
     depends_on:
       - ollama
     tty: true

docs/HERMES_CONTROL_PLANE.md

@@ -0,0 +1,126 @@
+# Hermes Control Plane for TradingOrg
+
+This repository can be run as a Hermes-controlled research and post-game review engine.
+
+## Design
+
+Hermes is the home-PC operator. TradingOrg is the research engine. The trading app or broker executor must remain a separate deterministic, risk-gated system.
+
+```text
+Hermes workspace / Hermes WebUI
+  -> runs TradingOrg commands and scripts
+  -> chooses local/free-cloud/premium model route
+  -> saves signal JSON and markdown reports
+  -> runs post-game review
+  -> appends lessons to memory/lessons.jsonl
+
+TradingOrg
+  -> produces research and signal JSON only
+  -> never places broker orders
+
+Trading app
+  -> consumes signals
+  -> applies strategy and risk controls
+  -> paper trades first
+  -> broker execution later, gated
+```
+
+## Non-negotiable safety rules
+
+- TradingOrg output is research only.
+- Generated signals must default to `paper_only: true`.
+- Broker keys do not belong in this repo.
+- Hermes may run scripts, but must not directly place broker orders.
+- No agent should push directly to `main`.
+- Live trading requires a separate deterministic risk engine, kill switch, audit log, and manual approval path.
+
+## Local model over Tailscale
+
+On the home PC, run Ollama and expose it only on your private Tailscale network.
+
+```bash
+ollama serve
+ollama pull qwen3:latest
+```
+
+On the laptop or inside the container, test:
+
+```bash
+curl http://home-pc-tailnet-name:11434/api/tags
+curl http://home-pc-tailnet-name:11434/v1/models
+```
+
+`.env` example:
+
+```env
+LLM_PROVIDER=ollama
+LLM_BACKEND_URL=http://home-pc-tailnet-name:11434/v1
+OLLAMA_BASE_URL=http://home-pc-tailnet-name:11434/v1
+QUICK_THINK_LLM=qwen3:latest
+DEEP_THINK_LLM=qwen3:latest
+MODEL_ROUTING_MODE=cost_optimized
+```
+
+## Free/cheap cloud fallback
+
+OpenRouter can be used as a fallback when the local model is unavailable, slow, or too weak.
+
+```env
+LLM_PROVIDER=openrouter
+OPENROUTER_API_KEY=...
+QUICK_THINK_LLM=your/free-or-cheap-model
+DEEP_THINK_LLM=your/free-or-cheap-model
+```
+
+## Run one ticker
+
+Installed console script:
+
+```bash
+tradingagents-analyze-run \
+  --ticker NVDA \
+  --date 2026-05-19 \
+  --provider ollama \
+  --backend-url http://home-pc-tailnet-name:11434/v1 \
+  --quick-model qwen3:latest \
+  --deep-model qwen3:latest \
+  --analysts market,news,fundamentals \
+  --depth 1 \
+  --checkpoint \
+  --output-json reports/signals/NVDA/2026-05-19/signal.json
+```
+
+Hermes-safe wrapper:
+
+```bash
+scripts/hermes/run_single_ticker.sh NVDA 2026-05-19
+```
+
+## Run a daily watchlist
+
+```bash
+WATCHLIST="SPY,NVDA,AAPL,MSFT" scripts/hermes/run_daily_watchlist.sh
+```
+
+## Run post-game review
+
+```bash
+scripts/hermes/run_postgame_review.sh NVDA 2026-05-19
+```
+
+This creates:
+
+```text
+reports/postgame/NVDA/2026-05-19/review.json
+memory/lessons.jsonl
+```
+
+## Learning loop
+
+The intended loop is:
+
+```text
+analyze -> signal -> observe result -> post-game review -> lesson -> next-run context
+```
+
+This is not model fine-tuning. It is reflection and memory injection. That is safer, cheaper, and easier to audit.

pyproject.toml

@@ -34,6 +34,9 @@ dependencies = [
 
 [project.scripts]
 tradingagents = "cli.main:app"
+tradingagents-analyze-run = "tradingagents.automation.analyze_run:main"
+tradingagents-postgame = "tradingagents.automation.postgame:main"
+tradingagents-update-lessons = "tradingagents.automation.update_lessons:main"
 
 [tool.setuptools.packages.find]
 include = ["tradingagents*", "cli*"]

scripts/hermes/run_daily_watchlist.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+WATCHLIST="${WATCHLIST:-SPY,NVDA,AAPL,MSFT}"
+ANALYSIS_DATE="${ANALYSIS_DATE:-$(date +%F)}"
+
+IFS=',' read -ra SYMBOLS <<< "${WATCHLIST}"
+for symbol in "${SYMBOLS[@]}"; do
+  symbol="$(echo "${symbol}" | xargs)"
+  if [[ -z "${symbol}" ]]; then
+    continue
+  fi
+  echo "=== Running TradingOrg analysis for ${symbol} on ${ANALYSIS_DATE} ==="
+  "$(dirname "$0")/run_single_ticker.sh" "${symbol}" "${ANALYSIS_DATE}"
+done
+
+echo "Daily watchlist complete for ${ANALYSIS_DATE}"