From cb7260c01d595eb9b7d0b30b9b40336c869d485a Mon Sep 17 00:00:00 2001 From: Claudiu Farcas Date: Sun, 21 Jun 2026 13:55:30 +0300 Subject: [PATCH] Enhance portfolio review skill to conditionally generate CSV exports and update documentation for clarity --- INSTALL_FOR_AGENTS.md | 3 + README.md | 70 +++++++++++++++++++ skills/xtb-portfolio-review/SKILL.md | 7 +- .../scripts/run-review.sh | 2 +- test_portfolio.py | 38 ++++++++++ 5 files changed, 116 insertions(+), 4 deletions(-) diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md index 700a673..ffb6db8 100644 --- a/INSTALL_FOR_AGENTS.md +++ b/INSTALL_FOR_AGENTS.md @@ -54,6 +54,9 @@ For portfolio review: /path/to/xtb-portfolio-review/scripts/run-review.sh /path/to/report.xlsx ``` +Append `--csv` to `run-review.sh` only when the user explicitly asks for the +per-section CSV exports. + For Wealthfolio export: ```bash diff --git a/README.md b/README.md index 6ce80e9..46740cd 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,76 @@ The parser is generic for XTB exports in this format. Tests generate a small synthetic workbook at runtime, while personal brokerage exports should stay local and untracked. +## Quick Start + +### Use the skills in your own agent + +This is the recommended path if you want an LLM or coding agent to run the XTB +workflows for you. Give your agent access to this repository and ask it to +follow [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md). That file tells the +agent how to install or use the portable skill folders, validate them, and run +the right workflow for your XTB workbook. + +Install prompt: + +```text +Read https://github.com/farcasclaudiu/xtb-investment-tools/blob/main/INSTALL_FOR_AGENTS.md and install the XTB skills for your agent harness. +``` + +Portfolio review prompt examples: + +```text +Use the XTB portfolio review skill to generate and verify a report for my XTB +workbook. +``` + +```text +Use the XTB portfolio review skill to generate the HTML report, export the CSV +tables, and summarize the reconciliation status and data-quality caveats. +``` + +```text +Use the XTB portfolio review skill with EUR_demo_report.xlsx as the input file. +Generate the review, run validation, and report the generated output paths. +``` + +Wealthfolio export prompt examples: + +```text +Use the XTB Wealthfolio export skill to create and validate a Wealthfolio CSV +from my XTB workbook. +``` + +```text +Use the XTB Wealthfolio export skill to inspect the generated CSV rows and tell +me whether they are ready to import into Wealthfolio. +``` + +```text +Use the XTB Wealthfolio export skill with EUR_demo_report.xlsx as the input file +and write the Wealthfolio CSV to results/EUR_demo_report_wealthfolio.csv. +``` + +### Run the tools directly + +From the repository root: + +```bash +python3 -m venv .venv +.venv/bin/python -m pip install --upgrade pip +.venv/bin/python -m pip install -r requirements.txt + +.venv/bin/python main.py path/to/xtb-report.xlsx +.venv/bin/python exporter.py path/to/xtb-report.xlsx +``` + +Outputs are written to `results/`, including +`results/_review.html` for the portfolio review and +`results/_wealthfolio.csv` for the Wealthfolio import file. If there is +exactly one `.xlsx` file in the current folder, both tools can auto-detect it +when the path is omitted. Add `--csv` to the portfolio review command only when +you want the extra per-section CSV exports. + --- ## Background: the XTB export format diff --git a/skills/xtb-portfolio-review/SKILL.md b/skills/xtb-portfolio-review/SKILL.md index a424885..0993218 100644 --- a/skills/xtb-portfolio-review/SKILL.md +++ b/skills/xtb-portfolio-review/SKILL.md @@ -16,7 +16,8 @@ Use this skill to run and assess XTB portfolio reviews from a copied skill folde `/scripts/validate-review.sh` 4. Generate the review from the directory where outputs should be written: `/scripts/run-review.sh ` -5. Inspect `results/` outputs named from the workbook stem, especially `_review.html`, `_holdings.csv`, `_cash_flows.csv`, `_performance.csv`, `_income.csv`, and `_evolution.csv`. + Add `--csv` only when the user explicitly asks for CSV exports. +5. Inspect the `results/_review.html` output. If CSV export was requested, also inspect outputs named from the workbook stem, especially `_holdings.csv`, `_cash_flows.csv`, `_performance.csv`, `_income.csv`, and `_evolution.csv`. 6. Check whether computed ending cash reconciles to the broker `Total` row within EUR/USD/etc. `0.01`. 7. Report findings with caveats: cost-priced tickers, missing live prices, cash mismatch, XIRR availability, concentration, income tax drag, and any generated file paths. @@ -25,7 +26,7 @@ Use this skill to run and assess XTB portfolio reviews from a copied skill folde - `scripts/main.py`: standalone XTB portfolio review generator. - `scripts/html_charts.py`: offline Chart.js report rendering helper. - `scripts/assets/chartjs.umd.min.js`: vendored Chart.js bundle for self-contained HTML. -- `scripts/run-review.sh`: shell wrapper that runs the bundled review tool with `--csv`. +- `scripts/run-review.sh`: shell wrapper that runs the bundled review tool. It writes only the HTML report by default; pass `--csv` to also write CSV outputs. - `scripts/validate-review.sh`: dependency and asset smoke check. - `scripts/setup-env.sh`: creates `.venv` in the current working directory and installs dependencies. - `scripts/requirements.txt`: Python dependencies. @@ -38,5 +39,5 @@ Use this skill to run and assess XTB portfolio reviews from a copied skill folde ## Guardrails - Do not treat the generated report as investment advice; describe what the tool computed and the data-quality limits. -- Prefer the bundled validation script and generated CSVs over eyeballing the HTML alone. +- Prefer the bundled validation script and generated outputs over eyeballing the HTML alone. - Preserve offline/self-contained HTML behavior; do not introduce CDN dependencies when modifying the report. diff --git a/skills/xtb-portfolio-review/scripts/run-review.sh b/skills/xtb-portfolio-review/scripts/run-review.sh index cc0f647..48795a6 100755 --- a/skills/xtb-portfolio-review/scripts/run-review.sh +++ b/skills/xtb-portfolio-review/scripts/run-review.sh @@ -10,4 +10,4 @@ else PYTHON_BIN="python3" fi -exec "$PYTHON_BIN" "$SCRIPT_DIR/main.py" "$@" --csv +exec "$PYTHON_BIN" "$SCRIPT_DIR/main.py" "$@" diff --git a/test_portfolio.py b/test_portfolio.py index e92b7b2..da4d373 100644 --- a/test_portfolio.py +++ b/test_portfolio.py @@ -1,3 +1,5 @@ +import os +import subprocess import warnings import pandas as pd @@ -827,6 +829,42 @@ class TestSyntheticReport: assert holdings["allocation_pct"].sum() == pytest.approx(100.0, abs=0.05) +# --------------------------------------------------------------------------- +# Bundled script wrappers +# --------------------------------------------------------------------------- +class TestPortfolioReviewWrapper: + def test_run_review_does_not_generate_csv_unless_requested(self, tmp_path): + calls_file = tmp_path / "python-args.txt" + fake_python = tmp_path / "fake-python.sh" + fake_python.write_text( + "#!/usr/bin/env bash\n" + "printf '%s\\n' \"$@\" > \"$CALLS_FILE\"\n", + encoding="utf-8", + ) + fake_python.chmod(0o755) + + env = os.environ | {"PYTHON": str(fake_python), "CALLS_FILE": str(calls_file)} + subprocess.run( + ["skills/xtb-portfolio-review/scripts/run-review.sh", "EUR_demo_report.xlsx"], + check=True, + env=env, + ) + default_args = calls_file.read_text(encoding="utf-8").splitlines() + assert "--csv" not in default_args + + subprocess.run( + [ + "skills/xtb-portfolio-review/scripts/run-review.sh", + "EUR_demo_report.xlsx", + "--csv", + ], + check=True, + env=env, + ) + explicit_args = calls_file.read_text(encoding="utf-8").splitlines() + assert "--csv" in explicit_args + + # --------------------------------------------------------------------------- # HTML report # ---------------------------------------------------------------------------