Portfolio risk monitor
Standalone Execution Contract
Treat this skill folder as self-contained. When the skill is installed or copied alone, run commands from this directory and use scripts/run.mjs for dry-run, fixture, and live execution.
Do not hand-write QVeris curl or ad hoc API calls for normal operation. Manual QVeris calls are allowed only for debugging provider behavior, must be labelled manual_debug, and must not be reported as a successful skill E2E run. The skill E2E path is successful only when scripts/run.mjs produces the Markdown report, structured JSON, and trace artifact.
scripts/lib/qveris-runtime.mjs is bundled runtime plumbing for this skill package. No repository-level shared directory is required when using the skill as an installed package.
Natural-Language Invocation Contract
When this skill is triggered by a user request, treat the skill as responsible for the final artifacts. The user should not need to know or request a command. Produce these canonical outputs whenever the user asks for analysis, a report, or a reusable result:
- Markdown report
- Schema-valid business JSON
- QVeris trace JSON with tool IDs, providers, parameters, execution IDs, costs, skipped calls, and missing-data notes
Use scripts/run.mjs internally to produce the canonical outputs. Always pass a business JSON output path when producing artifacts. In the final response, link the report, business JSON, and trace, and summarize paid calls, credits, execution status, and missing-data limits.
Do not create alternate runners, alternate schemas, or one-off JSON shapes for normal use. If the canonical runner lacks a metric, state the gap in missing_data and improve this skill later; do not silently replace the skill with ad hoc code. Manual QVeris calls, web search, or provider-specific debugging may supplement the analysis only when labelled manual_debug; they cannot replace the canonical runner output or be reported as successful skill E2E.
If the user has not authorized paid QVeris calls, stop after dry-run/preflight or ask for approval. If the user authorizes QVeris spend, run live and stay within the stated budget.
Internal Deterministic Runner
Use the local runner internally before composing a free-form answer:
node scripts/run.mjs --dry-run --holdings AAPL:25,NVDA:25,MSFT:20,TSLA:15,CASH:15 --benchmark SPY --window-days 30
node scripts/run.mjs --live --holdings AAPL:25,NVDA:25,MSFT:20,TSLA:15,CASH:15 --benchmark SPY --window-days 30 --max-paid-calls 25 --max-credits 520 --output artifacts/live-smoke.md --json-output artifacts/live-smoke.json --trace artifacts/live-smoke-trace.json
The runner performs QVeris Discover / Inspect preflight, enforces paid-call and credit budgets, writes a Markdown report, writes schema-valid business JSON, and writes a JSON trace.
Workflow
- Clarify ticker, market, time window, user objective, and maximum paid QVeris Call budget.
- Use QVeris Discover (POST /search) to find the needed finance, market, filing, news, transcript, or social capabilities.
- Use QVeris Inspect (POST /tools/by-ids) before paid execution. Show coverage, parameters, latency, success signal, and billing_rule when available.
- Ask for explicit user approval before paid Call execution.
- Use QVeris Call (POST /tools/execute) only for the bounded sources needed for the task.
- Return the requested finance output with evidence strength, missing data, QVeris capabilities used, paid Call count, estimated credits, and a not-investment-advice disclaimer.
Output Contract
Return these sections unless the user asks for a narrower format:
- Objective and scope
- Data sources discovered and inspected
- Evidence table with source type, recency, and confidence
- Analysis or ranking
- Risks, dissenting evidence, and missing proof
- QVeris calls used and estimated credits
- Not investment advice
The JSON artifact must include concentration HHI, top holding exposure, role-level missing_data, measurable_risks, and risk_metrics when historical prices are available. risk_metrics covers observation count, latest close, daily and annualized volatility, max drawdown, 95% historical VaR, and benchmark correlation when both top-holding and benchmark histories return usable records.
Cost Guardrails
- Discover and Inspect are treated as free preflight actions.
- Paid actions are QVeris Call executions.
- Provider fallback attempts are also paid actions and must remain inside
--max-paid-calls and --max-credits; fallback attempts are recorded in the trace.
- If estimated credits exceed the user's budget, reduce tickers, shorten windows, or ask for approval before continuing.
Methodology Reference
Read references/methodology.md when the user asks where the workflow comes from or how to adapt it. Read references/source-review.md for GitHub research and references/qveris-tool-map.md before changing QVeris data routing.
Source Inspiration
This skill is QVeris-native and does not copy source project text, prompts, code, or branding. It adapts public workflow patterns from permissively licensed finance AI projects:
- virattt/ai-hedge-fund (MIT): Multi-lens investment agents, valuation, sentiment, fundamentals, technicals, risk manager, and portfolio manager patterns.
- AI4Finance-Foundation/FinRL (MIT): Train-test-trade workflow, market environment, risk controls, and strategy evaluation patterns.
- microsoft/qlib (MIT): Quant research pipeline, alpha seeking, factor modeling, backtesting, risk modeling, and portfolio optimization patterns.
1---
2name: qveris-portfolio-risk-monitor
3description: Monitor a portfolio for concentration, drawdown, volatility, catalyst, news, and liquidity risks with auditable QVeris calls. Use when an agent needs QVeris-powered finance research, live market data, filings/news evidence, cost-aware tool calls, or source-backed investment analysis for this workflow.
4metadata:
5 source: https://skillmd.com/skills/qverisai/qveris-portfolio-risk-monitor
6---
7
8# Portfolio risk monitor
9
10## Standalone Execution Contract
11
12Treat this skill folder as self-contained. When the skill is installed or copied alone, run commands from this directory and use `scripts/run.mjs` for dry-run, fixture, and live execution.
13
14Do not hand-write QVeris `curl` or ad hoc API calls for normal operation. Manual QVeris calls are allowed only for debugging provider behavior, must be labelled `manual_debug`, and must not be reported as a successful skill E2E run. The skill E2E path is successful only when `scripts/run.mjs` produces the Markdown report, structured JSON, and trace artifact.
15
16`scripts/lib/qveris-runtime.mjs` is bundled runtime plumbing for this skill package. No repository-level shared directory is required when using the skill as an installed package.
17
18## Natural-Language Invocation Contract
19
20When this skill is triggered by a user request, treat the skill as responsible for the final artifacts. The user should not need to know or request a command. Produce these canonical outputs whenever the user asks for analysis, a report, or a reusable result:
21
22- Markdown report
23- Schema-valid business JSON
24- QVeris trace JSON with tool IDs, providers, parameters, execution IDs, costs, skipped calls, and missing-data notes
25
26Use `scripts/run.mjs` internally to produce the canonical outputs. Always pass a business JSON output path when producing artifacts. In the final response, link the report, business JSON, and trace, and summarize paid calls, credits, execution status, and missing-data limits.
27
28Do not create alternate runners, alternate schemas, or one-off JSON shapes for normal use. If the canonical runner lacks a metric, state the gap in `missing_data` and improve this skill later; do not silently replace the skill with ad hoc code. Manual QVeris calls, web search, or provider-specific debugging may supplement the analysis only when labelled `manual_debug`; they cannot replace the canonical runner output or be reported as successful skill E2E.
29
30If the user has not authorized paid QVeris calls, stop after dry-run/preflight or ask for approval. If the user authorizes QVeris spend, run live and stay within the stated budget.
31
32## Internal Deterministic Runner
33
34Use the local runner internally before composing a free-form answer:
35
36```bash
37node scripts/run.mjs --dry-run --holdings AAPL:25,NVDA:25,MSFT:20,TSLA:15,CASH:15 --benchmark SPY --window-days 30
38node scripts/run.mjs --live --holdings AAPL:25,NVDA:25,MSFT:20,TSLA:15,CASH:15 --benchmark SPY --window-days 30 --max-paid-calls 25 --max-credits 520 --output artifacts/live-smoke.md --json-output artifacts/live-smoke.json --trace artifacts/live-smoke-trace.json
39```
40
41The runner performs QVeris Discover / Inspect preflight, enforces paid-call and credit budgets, writes a Markdown report, writes schema-valid business JSON, and writes a JSON trace.
42
43## Workflow
44
451. Clarify ticker, market, time window, user objective, and maximum paid QVeris Call budget.
462. Use QVeris Discover (POST /search) to find the needed finance, market, filing, news, transcript, or social capabilities.
473. Use QVeris Inspect (POST /tools/by-ids) before paid execution. Show coverage, parameters, latency, success signal, and billing_rule when available.
484. Ask for explicit user approval before paid Call execution.
495. Use QVeris Call (POST /tools/execute) only for the bounded sources needed for the task.
506. Return the requested finance output with evidence strength, missing data, QVeris capabilities used, paid Call count, estimated credits, and a not-investment-advice disclaimer.
51
52## Output Contract
53
54Return these sections unless the user asks for a narrower format:
55
56- Objective and scope
57- Data sources discovered and inspected
58- Evidence table with source type, recency, and confidence
59- Analysis or ranking
60- Risks, dissenting evidence, and missing proof
61- QVeris calls used and estimated credits
62- Not investment advice
63
64The JSON artifact must include concentration HHI, top holding exposure, role-level `missing_data`, `measurable_risks`, and `risk_metrics` when historical prices are available. `risk_metrics` covers observation count, latest close, daily and annualized volatility, max drawdown, 95% historical VaR, and benchmark correlation when both top-holding and benchmark histories return usable records.
65
66## Cost Guardrails
67
68- Discover and Inspect are treated as free preflight actions.
69- Paid actions are QVeris Call executions.
70- Provider fallback attempts are also paid actions and must remain inside `--max-paid-calls` and `--max-credits`; fallback attempts are recorded in the trace.
71- If estimated credits exceed the user's budget, reduce tickers, shorten windows, or ask for approval before continuing.
72
73## Methodology Reference
74
75Read `references/methodology.md` when the user asks where the workflow comes from or how to adapt it. Read `references/source-review.md` for GitHub research and `references/qveris-tool-map.md` before changing QVeris data routing.
76
77## Source Inspiration
78
79This skill is QVeris-native and does not copy source project text, prompts, code, or branding. It adapts public workflow patterns from permissively licensed finance AI projects:
80
81- virattt/ai-hedge-fund (MIT): Multi-lens investment agents, valuation, sentiment, fundamentals, technicals, risk manager, and portfolio manager patterns.
82- AI4Finance-Foundation/FinRL (MIT): Train-test-trade workflow, market environment, risk controls, and strategy evaluation patterns.
83- microsoft/qlib (MIT): Quant research pipeline, alpha seeking, factor modeling, backtesting, risk modeling, and portfolio optimization patterns.