farcasclaudiu/xtb-investment-tools
1
0
Fork 0
mirror of https://github.com/farcasclaudiu/xtb-investment-tools.git synced 2026-06-22 05:01:57 +03:00
Code Issues Packages Projects Releases Wiki Activity

Enhance portfolio review skill to conditionally generate CSV exports and update documentation for clarity

Browse Source
This commit is contained in:
Claudiu Farcas
2026-06-21 13:55:30 +03:00
parent 7298a992f4
commit cb7260c01d
5 changed files with 116 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
INSTALL_FOR_AGENTS.md
+3
View File
@@ -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
README.md
+70
View File
@@ -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/<stem>_review.html` for the portfolio review and
`results/<stem>_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
skills/xtb-portfolio-review/SKILL.md
+4 -3
View File
@@ -16,7 +16,8 @@ Use this skill to run and assess XTB portfolio reviews from a copied skill folde
`<skill-folder>/scripts/validate-review.sh`
4. Generate the review from the directory where outputs should be written:
`<skill-folder>/scripts/run-review.sh <report.xlsx>`
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/<stem>_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.
skills/xtb-portfolio-review/scripts/run-review.sh
+1 -1
View File
@@ -10,4 +10,4 @@ else
PYTHON_BIN="python3"
fi
exec "$PYTHON_BIN" "$SCRIPT_DIR/main.py" "$@" --csv
exec "$PYTHON_BIN" "$SCRIPT_DIR/main.py" "$@"
test_portfolio.py
+38
View File
@@ -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
# ---------------------------------------------------------------------------